@outfitter/state 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,667 @@
+import { NotFoundError, Result, StorageError, ValidationError } from "@outfitter/contracts";
+/**
+* A pagination cursor representing a position in a result set.
+*
+* Cursors are immutable (frozen) objects that encapsulate pagination state.
+* They are intentionally opaque to prevent direct manipulation - use
+* {@link advanceCursor} to create a new cursor with an updated position.
+*
+* @example
+* ```typescript
+* const result = createCursor({
+*   position: 0,
+*   metadata: { query: "status:open" },
+*   ttl: 3600000, // 1 hour
+* });
+*
+* if (result.isOk()) {
+*   const cursor = result.value;
+*   console.log(cursor.id);        // UUID
+*   console.log(cursor.position);  // 0
+*   console.log(cursor.expiresAt); // Unix timestamp
+* }
+* ```
+*/
+interface Cursor {
+	/** Unique identifier for this cursor (UUID format) */
+	readonly id: string;
+	/** Current position/offset in the result set (zero-based) */
+	readonly position: number;
+	/** Optional user-defined metadata associated with this cursor */
+	readonly metadata?: Record<string, unknown>;
+	/** Time-to-live in milliseconds (optional, omitted if cursor never expires) */
+	readonly ttl?: number;
+	/** Unix timestamp (ms) when this cursor expires (computed from createdAt + ttl) */
+	readonly expiresAt?: number;
+	/** Unix timestamp (ms) when this cursor was created */
+	readonly createdAt: number;
+}
+/**
+* Options for creating a pagination cursor.
+*
+* @example
+* ```typescript
+* // Minimal options (ID auto-generated, no TTL)
+* const opts1: CreateCursorOptions = { position: 0 };
+*
+* // Full options with custom ID, metadata, and TTL
+* const opts2: CreateCursorOptions = {
+*   id: "my-cursor-id",
+*   position: 50,
+*   metadata: { query: "status:open", pageSize: 25 },
+*   ttl: 30 * 60 * 1000, // 30 minutes
+* };
+* ```
+*/
+interface CreateCursorOptions {
+	/** Custom cursor ID (UUID generated if not provided) */
+	id?: string;
+	/** Starting position in the result set (must be non-negative) */
+	position: number;
+	/** User-defined metadata to associate with the cursor */
+	metadata?: Record<string, unknown>;
+	/** Time-to-live in milliseconds (cursor never expires if omitted) */
+	ttl?: number;
+}
+/**
+* A store for managing pagination cursors.
+*
+* Cursor stores handle storage, retrieval, and expiration of cursors.
+* Expired cursors are automatically excluded from `get()` and `has()` operations.
+*
+* @example
+* ```typescript
+* const store = createCursorStore();
+*
+* // Store a cursor
+* const cursor = createCursor({ position: 0 });
+* if (cursor.isOk()) {
+*   store.set(cursor.value);
+* }
+*
+* // Retrieve by ID
+* const result = store.get("cursor-id");
+* if (result.isOk()) {
+*   console.log(result.value.position);
+* }
+*
+* // Cleanup expired cursors
+* const pruned = store.prune();
+* console.log(`Removed ${pruned} expired cursors`);
+* ```
+*/
+interface CursorStore {
+	/**
+	* Save or update a cursor in the store.
+	* @param cursor - The cursor to store (replaces existing if same ID)
+	*/
+	set(cursor: Cursor): void;
+	/**
+	* Retrieve a cursor by ID.
+	* @param id - The cursor ID to look up
+	* @returns Result with cursor or NotFoundError (also returned for expired cursors)
+	*/
+	get(id: string): Result<Cursor, InstanceType<typeof NotFoundError>>;
+	/**
+	* Check if a cursor exists and is not expired.
+	* @param id - The cursor ID to check
+	* @returns True if cursor exists and is valid, false otherwise
+	*/
+	has(id: string): boolean;
+	/**
+	* Delete a cursor by ID.
+	* @param id - The cursor ID to delete (no-op if not found)
+	*/
+	delete(id: string): void;
+	/**
+	* Remove all cursors from the store.
+	*/
+	clear(): void;
+	/**
+	* List all cursor IDs in the store (including expired).
+	* @returns Array of cursor IDs
+	*/
+	list(): string[];
+	/**
+	* Remove all expired cursors from the store.
+	* @returns Number of cursors that were pruned
+	*/
+	prune(): number;
+}
+/**
+* A cursor store with namespace isolation.
+*
+* Scoped stores prefix all cursor IDs with the scope name, preventing
+* collisions between different contexts (e.g., "issues" vs "pull-requests").
+*
+* Scopes can be nested: creating a scoped store from another scoped store
+* produces IDs like "parent:child:cursor-id".
+*
+* @example
+* ```typescript
+* const store = createCursorStore();
+* const issueStore = createScopedStore(store, "issues");
+* const prStore = createScopedStore(store, "prs");
+*
+* // These don't conflict - different namespaces
+* issueStore.set(cursor1);  // Stored as "issues:abc123"
+* prStore.set(cursor2);     // Stored as "prs:abc123"
+*
+* // Clear only affects the scope
+* issueStore.clear();  // Only clears issue cursors
+* ```
+*/
+interface ScopedStore extends CursorStore {
+	/**
+	* Get the full scope path for this store.
+	* @returns Scope string (e.g., "parent:child" for nested scopes)
+	*/
+	getScope(): string;
+}
+/**
+* Options for creating a persistent cursor store.
+*
+* @example
+* ```typescript
+* const options: PersistentStoreOptions = {
+*   path: "/home/user/.config/myapp/cursors.json",
+* };
+*
+* const store = await createPersistentStore(options);
+* ```
+*/
+interface PersistentStoreOptions {
+	/** Absolute file path for cursor persistence (JSON format) */
+	path: string;
+}
+/**
+* A cursor store that persists to disk and survives process restarts.
+*
+* Persistent stores use atomic writes (temp file + rename) to prevent
+* corruption. They automatically load existing data on initialization
+* and handle corrupted files gracefully by starting empty.
+*
+* @example
+* ```typescript
+* const store = await createPersistentStore({
+*   path: "~/.config/myapp/cursors.json",
+* });
+*
+* // Use like any cursor store
+* store.set(cursor);
+*
+* // Flush to disk before exit
+* await store.flush();
+*
+* // Cleanup resources
+* store.dispose();
+* ```
+*/
+interface PersistentStore extends CursorStore {
+	/**
+	* Flush all in-memory cursors to disk.
+	* Uses atomic write (temp file + rename) to prevent corruption.
+	* @returns Promise that resolves when write is complete
+	*/
+	flush(): Promise<void>;
+	/**
+	* Dispose of the store and cleanup resources.
+	* Call this when the store is no longer needed.
+	*/
+	dispose(): void;
+}
+/**
+* Create a new pagination cursor.
+*
+* Cursors are immutable and frozen. To update position, use {@link advanceCursor}.
+* If no ID is provided, a UUID is generated automatically.
+*
+* @param options - Cursor creation options including position, optional ID, metadata, and TTL
+* @returns Result containing frozen Cursor or ValidationError if position is negative
+*
+* @example
+* ```typescript
+* // Basic cursor at position 0
+* const result = createCursor({ position: 0 });
+*
+* // Cursor with metadata and TTL
+* const result = createCursor({
+*   position: 0,
+*   metadata: { filter: "active" },
+*   ttl: 3600000, // 1 hour
+* });
+*
+* if (result.isOk()) {
+*   store.set(result.value);
+* }
+* ```
+*/
+declare function createCursor(options: CreateCursorOptions): Result<Cursor, InstanceType<typeof ValidationError>>;
+/**
+* Advance a cursor to a new position, returning a new immutable cursor.
+*
+* The original cursor is not modified. All properties (ID, metadata, TTL,
+* expiresAt, createdAt) are preserved in the new cursor.
+*
+* @param cursor - The cursor to advance (not modified)
+* @param newPosition - The new position value (typically cursor.position + pageSize)
+* @returns A new frozen Cursor with the updated position
+*
+* @example
+* ```typescript
+* const cursor = createCursor({ position: 0 });
+* if (cursor.isOk()) {
+*   // Advance by page size of 25
+*   const nextPage = advanceCursor(cursor.value, cursor.value.position + 25);
+*
+*   console.log(cursor.value.position); // 0 (unchanged)
+*   console.log(nextPage.position);     // 25
+*
+*   // Store the advanced cursor
+*   store.set(nextPage);
+* }
+* ```
+*/
+declare function advanceCursor(cursor: Cursor, newPosition: number): Cursor;
+/**
+* Check if a cursor has expired based on its TTL.
+*
+* Cursors without a TTL (no `expiresAt` property) never expire and
+* this function will always return `false` for them.
+*
+* @param cursor - The cursor to check for expiration
+* @returns `true` if cursor has expired, `false` if still valid or has no TTL
+*
+* @example
+* ```typescript
+* const cursor = createCursor({ position: 0, ttl: 1000 }); // 1 second TTL
+*
+* if (cursor.isOk()) {
+*   console.log(isExpired(cursor.value)); // false (just created)
+*
+*   // Wait 2 seconds...
+*   await new Promise(resolve => setTimeout(resolve, 2000));
+*
+*   console.log(isExpired(cursor.value)); // true (expired)
+* }
+*
+* // Cursors without TTL never expire
+* const eternal = createCursor({ position: 0 });
+* if (eternal.isOk()) {
+*   console.log(isExpired(eternal.value)); // always false
+* }
+* ```
+*/
+declare function isExpired(cursor: Cursor): boolean;
+/**
+* Encodes a cursor to an opaque URL-safe string.
+*
+* The internal structure is hidden from consumers. The cursor is serialized
+* to JSON and then encoded using URL-safe base64 (RFC 4648 Section 5).
+*
+* @param cursor - Cursor to encode
+* @returns URL-safe base64 encoded string (no +, /, or = characters)
+*
+* @example
+* ```typescript
+* const cursor = createCursor({ position: 0, metadata: { query: "status:open" } });
+* if (cursor.isOk()) {
+*   const encoded = encodeCursor(cursor.value);
+*   // encoded is a URL-safe string like "eyJpZCI6IjEyMzQ..."
+*
+*   // Can be safely used in URLs, query params, headers
+*   const url = `/api/items?cursor=${encoded}`;
+* }
+* ```
+*/
+declare function encodeCursor(cursor: Cursor): string;
+/**
+* Decodes an opaque cursor string back to a Cursor.
+*
+* Validates the structure after decoding, ensuring all required fields
+* are present and have correct types.
+*
+* @param encoded - URL-safe base64 encoded cursor
+* @returns Result with decoded Cursor or ValidationError if invalid
+*
+* @example
+* ```typescript
+* // Successful decode
+* const result = decodeCursor(encodedString);
+* if (result.isOk()) {
+*   console.log(result.value.position);
+* }
+*
+* // Handle invalid input
+* const invalid = decodeCursor("not-a-valid-cursor");
+* if (invalid.isErr()) {
+*   console.log(invalid.error.message); // "Invalid cursor: ..."
+* }
+* ```
+*/
+declare function decodeCursor(encoded: string): Result<Cursor, InstanceType<typeof ValidationError>>;
+/**
+* Create an in-memory cursor store.
+*
+* The store automatically handles expiration: `get()` and `has()` return
+* not-found/false for expired cursors. Use `prune()` to remove expired
+* cursors from memory.
+*
+* @returns A new cursor store implementing both CursorStore and ScopedStore interfaces
+*
+* @example
+* ```typescript
+* const store = createCursorStore();
+*
+* // Create and store a cursor
+* const cursor = createCursor({
+*   position: 0,
+*   metadata: { query: "status:open" },
+*   ttl: 3600000, // 1 hour
+* });
+*
+* if (cursor.isOk()) {
+*   store.set(cursor.value);
+*
+*   // Retrieve later
+*   const result = store.get(cursor.value.id);
+*   if (result.isOk()) {
+*     console.log(result.value.position);
+*   }
+* }
+*
+* // List all cursors
+* console.log(store.list()); // ["cursor-id", ...]
+*
+* // Cleanup expired
+* const pruned = store.prune();
+* ```
+*/
+declare function createCursorStore(): CursorStore & ScopedStore;
+/**
+* Create a persistent cursor store that saves to disk.
+*
+* The store loads existing cursors from the file on initialization.
+* Changes are kept in memory until `flush()` is called. Uses atomic
+* writes (temp file + rename) to prevent corruption.
+*
+* If the file is corrupted or invalid JSON, the store starts empty
+* rather than throwing an error.
+*
+* @param options - Persistence options including the file path
+* @returns Promise resolving to a PersistentStore
+*
+* @example
+* ```typescript
+* // Create persistent store
+* const store = await createPersistentStore({
+*   path: "/home/user/.config/myapp/cursors.json",
+* });
+*
+* // Use like any cursor store
+* const cursor = createCursor({ position: 0 });
+* if (cursor.isOk()) {
+*   store.set(cursor.value);
+* }
+*
+* // Flush to disk (call before process exit)
+* await store.flush();
+*
+* // Cleanup when done
+* store.dispose();
+* ```
+*
+* @example
+* ```typescript
+* // Combine with scoped stores for organized persistence
+* const persistent = await createPersistentStore({
+*   path: "~/.config/myapp/cursors.json",
+* });
+*
+* const issuesCursors = createScopedStore(persistent, "issues");
+* const prsCursors = createScopedStore(persistent, "prs");
+*
+* // All scopes share the same persistence file
+* await persistent.flush();
+* ```
+*/
+declare function createPersistentStore(options: PersistentStoreOptions): Promise<PersistentStore>;
+/**
+* Create a scoped cursor store with namespace isolation.
+*
+* Scoped stores prefix all cursor IDs with the scope name, preventing
+* collisions between different contexts (e.g., "issues" vs "pull-requests").
+*
+* Scopes can be nested: `createScopedStore(scopedStore, "child")` creates
+* IDs like "parent:child:cursor-id".
+*
+* When retrieving cursors, the scope prefix is automatically stripped,
+* so consumers see clean IDs without the namespace prefix.
+*
+* @param store - Parent store to scope (CursorStore or another ScopedStore for nesting)
+* @param scope - Namespace for this scope (will be prefixed to all cursor IDs)
+* @returns ScopedStore with isolated cursor management
+*
+* @example
+* ```typescript
+* const store = createCursorStore();
+* const issueStore = createScopedStore(store, "issues");
+* const prStore = createScopedStore(store, "prs");
+*
+* // These don't conflict - different namespaces
+* issueStore.set(cursor1);  // Stored as "issues:abc123"
+* prStore.set(cursor2);     // Stored as "prs:abc123"
+*
+* // Retrieved cursors have clean IDs
+* const result = issueStore.get("abc123");
+* if (result.isOk()) {
+*   result.value.id; // "abc123" (not "issues:abc123")
+* }
+*
+* // Clear only affects the scope
+* issueStore.clear();  // Only clears issue cursors
+* prStore.list();      // PR cursors still exist
+* ```
+*
+* @example
+* ```typescript
+* // Nested scopes for hierarchical organization
+* const store = createCursorStore();
+* const githubStore = createScopedStore(store, "github");
+* const issuesStore = createScopedStore(githubStore, "issues");
+*
+* issuesStore.getScope(); // "github:issues"
+*
+* // Cursor stored as "github:issues:cursor-id"
+* issuesStore.set(cursor);
+* ```
+*/
+declare function createScopedStore(store: CursorStore | ScopedStore, scope: string): ScopedStore;
+/**
+* Default page size when limit is not specified in cursor metadata.
+*/
+declare const DEFAULT_PAGE_LIMIT = 25;
+/**
+* A simple cursor store for pagination operations.
+*
+* This is a simplified interface compared to {@link CursorStore}, designed
+* specifically for pagination helpers. It returns `null` instead of errors
+* for missing cursors, making pagination code more straightforward.
+*
+* @example
+* ```typescript
+* const store = createPaginationStore();
+*
+* // Store a cursor
+* store.set("my-cursor", cursor);
+*
+* // Retrieve (returns null if not found)
+* const cursor = store.get("my-cursor");
+* if (cursor) {
+*   console.log(cursor.position);
+* }
+* ```
+*/
+interface PaginationStore {
+	/**
+	* Get a cursor by ID.
+	* @param id - The cursor ID to look up
+	* @returns The cursor if found, null otherwise
+	*/
+	get(id: string): Cursor | null;
+	/**
+	* Store a cursor by ID.
+	* @param id - The ID to store under
+	* @param cursor - The cursor to store
+	*/
+	set(id: string, cursor: Cursor): void;
+	/**
+	* Delete a cursor by ID.
+	* @param id - The cursor ID to delete
+	*/
+	delete(id: string): void;
+}
+/**
+* Get the default pagination store (module-level singleton).
+*
+* The default store is lazily initialized on first access.
+* Use this when you want cursors to persist across multiple
+* load/save calls within the same process.
+*
+* @returns The default pagination store instance
+*
+* @example
+* ```typescript
+* const store = getDefaultPaginationStore();
+* store.set("cursor-1", cursor);
+*
+* // Later, same store is returned
+* const sameStore = getDefaultPaginationStore();
+* sameStore.get("cursor-1"); // Returns the cursor
+* ```
+*/
+declare function getDefaultPaginationStore(): PaginationStore;
+/**
+* Create an in-memory pagination store.
+*
+* This is a simple Map-backed store for cursor persistence.
+* Unlike {@link createCursorStore}, this store does not handle
+* TTL/expiration - it's designed for simple pagination use cases.
+*
+* @returns A new pagination store instance
+*
+* @example
+* ```typescript
+* const store = createPaginationStore();
+*
+* const cursor = createCursor({ position: 0, metadata: { limit: 25 } });
+* if (cursor.isOk()) {
+*   store.set(cursor.value.id, cursor.value);
+*   const retrieved = store.get(cursor.value.id);
+* }
+* ```
+*/
+declare function createPaginationStore(): PaginationStore;
+/**
+* Result of a pagination operation.
+*
+* @typeParam T - The type of items being paginated
+*/
+interface PaginationResult<T> {
+	/** The items in the current page */
+	page: T[];
+	/** The cursor for the next page, or null if this is the last page */
+	nextCursor: Cursor | null;
+}
+/**
+* Extract a page of items based on cursor position.
+*
+* Uses `cursor.position` as the offset and `cursor.metadata.limit` as
+* the page size (defaults to {@link DEFAULT_PAGE_LIMIT} if not specified).
+*
+* Returns a `nextCursor` for fetching the next page, or `null` if there
+* are no more items (i.e., this is the last page).
+*
+* @typeParam T - The type of items being paginated
+* @param items - The full array of items to paginate
+* @param cursor - Cursor containing position (offset) and optionally limit in metadata
+* @returns Object containing the page slice and next cursor (or null)
+*
+* @example
+* ```typescript
+* const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+* const cursor = createCursor({
+*   position: 0,
+*   metadata: { limit: 3 },
+* });
+*
+* if (cursor.isOk()) {
+*   const { page, nextCursor } = paginate(items, cursor.value);
+*   console.log(page); // [1, 2, 3]
+*   console.log(nextCursor?.position); // 3
+*
+*   if (nextCursor) {
+*     const { page: page2 } = paginate(items, nextCursor);
+*     console.log(page2); // [4, 5, 6]
+*   }
+* }
+* ```
+*/
+declare function paginate<T>(items: T[], cursor: Cursor): PaginationResult<T>;
+/**
+* Load a cursor from a pagination store.
+*
+* Returns `Ok(null)` if the cursor is not found (not an error).
+* This differs from {@link CursorStore.get} which returns a `NotFoundError`.
+*
+* @param id - The cursor ID to load
+* @param store - Optional store to load from (defaults to module-level store)
+* @returns Result containing the cursor or null if not found
+*
+* @example
+* ```typescript
+* // Using default store
+* const result = loadCursor("my-cursor");
+* if (result.isOk()) {
+*   if (result.value) {
+*     console.log(`Found cursor at position ${result.value.position}`);
+*   } else {
+*     console.log("Cursor not found, starting fresh");
+*   }
+* }
+*
+* // Using custom store
+* const store = createPaginationStore();
+* const result = loadCursor("my-cursor", store);
+* ```
+*/
+declare function loadCursor(id: string, store?: PaginationStore): Result<Cursor | null, StorageError>;
+/**
+* Save a cursor to a pagination store.
+*
+* The cursor is stored by its `id` property.
+*
+* @param cursor - The cursor to save
+* @param store - Optional store to save to (defaults to module-level store)
+* @returns Result indicating success or storage error
+*
+* @example
+* ```typescript
+* const cursor = createCursor({
+*   id: "search-results",
+*   position: 50,
+*   metadata: { limit: 25, query: "status:open" },
+* });
+*
+* if (cursor.isOk()) {
+*   // Save to default store
+*   saveCursor(cursor.value);
+*
+*   // Or save to custom store
+*   const store = createPaginationStore();
+*   saveCursor(cursor.value, store);
+* }
+* ```
+*/
+declare function saveCursor(cursor: Cursor, store?: PaginationStore): Result<void, StorageError>;
+export { saveCursor, paginate, loadCursor, isExpired, getDefaultPaginationStore, encodeCursor, decodeCursor, createScopedStore, createPersistentStore, createPaginationStore, createCursorStore, createCursor, advanceCursor, ScopedStore, PersistentStoreOptions, PersistentStore, PaginationStore, PaginationResult, DEFAULT_PAGE_LIMIT, CursorStore, Cursor, CreateCursorOptions };