@arckit/resultset

Pagination, filtering, and result set utilities with native branded types.

📑 Table of Contents

• 🪧 About
• 📦 Installation
• 🚀 Usage
• 📖 API
• 🤗 Contributing
• 📝 License

Type-safe pagination, filtering, and sorting utilities using native TypeScript branded types for Page and PageSize. Ensures values are always valid positive integers at the type level.

pnpm add @arckit/resultset

Pagination

import { Page, PageSize, paginate } from '@arckit/resultset';

const items = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k'];

const result = paginate(items, { page: Page(2), pageSize: PageSize(5) });
// { items: ['f', 'g', 'h', 'i', 'j'], totalItems: 11, currentPage: 2, pageSize: 5 }

Filtering

import { filtered, Search } from '@arckit/resultset';

const result = filtered(paginatedResult, { search: Search('hello') });
// Adds search metadata to the result

Sorting

import { Sort, sorted } from '@arckit/resultset';

const result = sorted(paginatedResult, { sort: Sort('name', 'desc') });
// Adds sort metadata to the result: { ..., sort: { field: 'name', direction: 'desc' } }

Sort carries the chosen field and direction; the actual ordering stays the caller's responsibility (e.g. the database query). Sort is generic over the field name, so it can be constrained to a known set of sortable columns:

type ClientField = 'name' | 'createdAt';
const sort = Sort<ClientField>('createdAt', 'desc');

Page(value: number) => Page

Branded positive integer. Clamps to 1 minimum, rounds to nearest integer.

PageSize(value: number) => PageSize

Branded positive integer. Clamps to 1 minimum, rounds to nearest integer.

paginate<T>(items: T[], params?) => Paginated<T>

| Parameter | Description | |-------------------|------------------------------| | items | The full array to paginate | | params.page | Page number (default: 1) | | params.pageSize | Items per page (default: 10) |

Search(value: string) => Search

Branded search string. Wraps a raw string into the Search brand for use with filtered.

filtered<T>(result: T, params?) => Filtered<T>

| Parameter | Description | |-----------------|------------------------------------------| | result | The result object to augment | | params.search | Optional Search to attach |

SortDirection(value: string) => SortDirection

Normalizes a raw value to 'asc' | 'desc'. Defaults to 'asc' for anything other than 'desc'.

Sort<Field>(field: Field, direction?: SortDirection) => Sort<Field>

Builds a sort instruction. direction defaults to 'asc'. Generic over the field name to constrain sortable columns.

sorted<T, Field>(result: T, params?) => Sorted<T, Field>

| Parameter | Description | |---------------|------------------------------| | result | The result object to augment | | params.sort | Optional Sort to attach |

See CONTRIBUTING.md for details.

MIT © Marc Gavanier