@beignet/core/dist/pagination/index.d.ts

Core framework primitives for Beignet

/**
 * Sort direction for list queries.
 */
export type SortDirection = "asc" | "desc";
/**
 * Sort option for a whitelisted field.
 */
export type SortOption<Field extends string = string> = {
    /**
     * Field to sort by.
     */
    field: Field;
    /**
     * Sort direction.
     */
    direction: SortDirection;
};
/**
 * Normalized offset pagination request.
 */
export interface OffsetPage {
    /**
     * Pagination mode.
     */
    readonly kind: "offset";
    /**
     * Page size after defaulting and max-limit clamping.
     */
    readonly limit: number;
    /**
     * Zero-based item offset.
     */
    readonly offset: number;
}
/**
 * Normalized cursor pagination request.
 */
export interface CursorPage {
    /**
     * Pagination mode.
     */
    readonly kind: "cursor";
    /**
     * Page size after defaulting and max-limit clamping.
     */
    readonly limit: number;
    /**
     * Cursor for the current page, or null for the first page.
     */
    readonly cursor: string | null;
}
/**
 * Normalized pagination request.
 */
export type Page = OffsetPage | CursorPage;
/**
 * Offset pagination response metadata.
 */
export type OffsetPageInfo = OffsetPage & {
    /**
     * Total item count.
     */
    readonly total: number;
    /**
     * Whether another page exists.
     */
    readonly hasMore: boolean;
};
/**
 * Cursor pagination response metadata.
 */
export type CursorPageInfo = CursorPage & {
    /**
     * Cursor for the next page, or null when there is no next page.
     */
    readonly nextCursor: string | null;
    /**
     * Whether another page exists.
     */
    readonly hasMore: boolean;
};
/**
 * Pagination response metadata.
 */
export type PageInfo = OffsetPageInfo | CursorPageInfo;
/**
 * Paginated list result.
 */
export interface PageResult<TItem, TPage extends PageInfo = PageInfo> {
    /**
     * Page items. Result helpers clone the input array.
     */
    readonly items: TItem[];
    /**
     * Page metadata.
     */
    readonly page: TPage;
}
/**
 * Options for normalizing pagination input.
 */
export interface NormalizePageOptions {
    /**
     * Limit used when the caller does not provide one.
     */
    readonly defaultLimit: number;
    /**
     * Maximum allowed limit. Larger caller values are clamped.
     */
    readonly maxLimit: number;
}
/**
 * Raw offset pagination input.
 */
export interface OffsetPageInput {
    /**
     * Requested page size.
     */
    readonly limit?: number | null;
    /**
     * Requested zero-based offset.
     */
    readonly offset?: number | null;
}
/**
 * Raw cursor pagination input.
 */
export interface CursorPageInput {
    /**
     * Requested page size.
     */
    readonly limit?: number | null;
    /**
     * Requested cursor.
     */
    readonly cursor?: string | null;
}
/**
 * Error thrown when pagination input is invalid.
 */
export declare class PaginationError extends Error {
    constructor(message: string);
}
/**
 * Normalize offset pagination input.
 *
 * The limit is defaulted and clamped to `maxLimit`; offset must be a
 * non-negative integer.
 */
export declare function normalizeOffsetPage(input: OffsetPageInput, options: NormalizePageOptions): OffsetPage;
/**
 * Normalize cursor pagination input.
 *
 * The limit is defaulted and clamped to `maxLimit`; cursor must be a string or
 * null.
 */
export declare function normalizeCursorPage(input: CursorPageInput, options: NormalizePageOptions): CursorPage;
/**
 * Create an offset page result and derive `hasMore`.
 */
export declare function offsetPageResult<TItem>(items: readonly TItem[], page: OffsetPage, total: number): PageResult<TItem, OffsetPageInfo>;
/**
 * Create a cursor page result and derive `hasMore` from `nextCursor`.
 */
export declare function cursorPageResult<TItem>(items: readonly TItem[], page: CursorPage, nextCursor: string | null): PageResult<TItem, CursorPageInfo>;
//# sourceMappingURL=index.d.ts.map