List & Pagination Types

Type definitions for pagination and filtering.

ListOptions

Options for listing resources.

interface ListOptions {
  page?: {
    number?: number;
    size?: number;
  };
  cursor?: string;
  limit?: number;
  filter?: Record<string, FilterValue>;
  sort?: string;
  include?: string[];
  fields?: Record<string, string[]>;
}

Parameters

Parameter	Type	Description
page.number	number	Page number (1-indexed)
page.size	number	Items per page
cursor	string	Cursor for cursor-based pagination
limit	number	Maximum items to return
filter	Record<string, FilterValue>	Filter criteria
sort	string	Sort field (prefix with - for descending)
include	string[]	Related resources to include
fields	Record<string, string[]>	Sparse fieldsets

ListResponse

Response structure for list operations.

interface ListResponse<T> {
  data: T[];
  meta: PaginationMeta;
  links: PaginationLinks;
  included?: unknown[];
}

PaginationMeta

Metadata about the current page.

interface PaginationMeta {
  totalCount: number;
  pageCount: number;
  currentPage: number;
  perPage: number;
  hasMore?: boolean;
  nextCursor?: string;
}

PaginationLinks

Links for pagination navigation.

interface PaginationLinks {
  self: string;
  first: string;
  last: string;
  next?: string;
  prev?: string;
}

FilterOperator

Available filter operators.

type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like';

FilterValue

Filter value types.

type FilterValue = 
  | string 
  | number 
  | boolean 
  | Date 
  | string[]
  | { [K in FilterOperator]?: string | number | boolean | Date | string[] };

Usage Examples

Basic Pagination

const response = await client.risks.list({
  page: { number: 1, size: 25 }
});

console.log(`Page ${response.meta.currentPage} of ${response.meta.pageCount}`);
console.log(`Total: ${response.meta.totalCount}`);

Filtering

// Simple filter
const response = await client.risks.list({
  filter: { status: 'active' }
});

// Filter with operator
const response = await client.risks.list({
  filter: { 
    severity: { in: ['high', 'critical'] },
    createdAt: { gte: '2024-01-01' }
  }
});

Sorting

// Ascending
const response = await client.risks.list({
  sort: 'createdAt'
});

// Descending
const response = await client.risks.list({
  sort: '-createdAt'
});

Including Related Resources

const response = await client.risks.list({
  include: ['controls', 'owner']
});