@outfitter/state 0.2.4 → 0.2.5

package/dist/shared/@outfitter/state-3n2wh1yq.js

@@ -0,0 +1,154 @@
+// @bun
+// packages/state/src/internal/cursor.ts
+import { Result, ValidationError } from "@outfitter/contracts";
+function createCursor(options) {
+  if (options.position < 0) {
+    return Result.err(new ValidationError({
+      message: "Position must be non-negative",
+      field: "position"
+    }));
+  }
+  const createdAt = Date.now();
+  const id = options.id ?? crypto.randomUUID();
+  const cursor = Object.freeze({
+    id,
+    position: options.position,
+    createdAt,
+    ...options.metadata !== undefined && { metadata: options.metadata },
+    ...options.ttl !== undefined && { ttl: options.ttl },
+    ...options.ttl !== undefined && { expiresAt: createdAt + options.ttl }
+  });
+  return Result.ok(cursor);
+}
+function advanceCursor(cursor, newPosition) {
+  const newCursor = Object.freeze({
+    id: cursor.id,
+    position: newPosition,
+    createdAt: cursor.createdAt,
+    ...cursor.metadata !== undefined && { metadata: cursor.metadata },
+    ...cursor.ttl !== undefined && { ttl: cursor.ttl },
+    ...cursor.expiresAt !== undefined && { expiresAt: cursor.expiresAt }
+  });
+  return newCursor;
+}
+function isExpired(cursor) {
+  if (cursor.expiresAt === undefined) {
+    return false;
+  }
+  return Date.now() > cursor.expiresAt;
+}
+function toBase64Url(base64) {
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+var base64Encoder = new TextEncoder;
+var base64Decoder = new TextDecoder;
+function toBase64(value) {
+  const bytes = base64Encoder.encode(value);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+function fromBase64(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0;i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return base64Decoder.decode(bytes);
+}
+function fromBase64Url(base64Url) {
+  let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+  const padLength = (4 - base64.length % 4) % 4;
+  base64 += "=".repeat(padLength);
+  return base64;
+}
+function encodeCursor(cursor) {
+  const json = JSON.stringify(cursor);
+  const base64 = toBase64(json);
+  return toBase64Url(base64);
+}
+function decodeCursor(encoded) {
+  let json;
+  try {
+    const base64 = fromBase64Url(encoded);
+    json = fromBase64(base64);
+  } catch {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: failed to decode base64",
+      field: "cursor"
+    }));
+  }
+  let data;
+  try {
+    data = JSON.parse(json);
+  } catch {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: failed to parse JSON",
+      field: "cursor"
+    }));
+  }
+  if (typeof data !== "object" || data === null) {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: expected object",
+      field: "cursor"
+    }));
+  }
+  const obj = data;
+  if (typeof obj.id !== "string") {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: missing or invalid 'id' field",
+      field: "cursor.id"
+    }));
+  }
+  if (typeof obj.position !== "number") {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: missing or invalid 'position' field",
+      field: "cursor.position"
+    }));
+  }
+  if (obj.position < 0) {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: position must be non-negative",
+      field: "cursor.position"
+    }));
+  }
+  if (typeof obj.createdAt !== "number") {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: missing or invalid 'createdAt' field",
+      field: "cursor.createdAt"
+    }));
+  }
+  if (obj.metadata !== undefined && (typeof obj.metadata !== "object" || obj.metadata === null)) {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: 'metadata' must be an object",
+      field: "cursor.metadata"
+    }));
+  }
+  if (obj.ttl !== undefined && typeof obj.ttl !== "number") {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: 'ttl' must be a number",
+      field: "cursor.ttl"
+    }));
+  }
+  if (obj.expiresAt !== undefined && typeof obj.expiresAt !== "number") {
+    return Result.err(new ValidationError({
+      message: "Invalid cursor: 'expiresAt' must be a number",
+      field: "cursor.expiresAt"
+    }));
+  }
+  const cursor = Object.freeze({
+    id: obj.id,
+    position: obj.position,
+    createdAt: obj.createdAt,
+    ...obj.metadata !== undefined && {
+      metadata: obj.metadata
+    },
+    ...obj.ttl !== undefined && { ttl: obj.ttl },
+    ...obj.expiresAt !== undefined && { expiresAt: obj.expiresAt }
+  });
+  return Result.ok(cursor);
+}
+
+export { createCursor, advanceCursor, isExpired, encodeCursor, decodeCursor };

package/dist/shared/@outfitter/state-6h22x3e6.d.ts

@@ -0,0 +1,264 @@
+import { NotFoundError, Result } 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 {
+	/** Unix timestamp (ms) when this cursor was created */
+	readonly createdAt: number;
+	/** Unix timestamp (ms) when this cursor expires (computed from createdAt + ttl) */
+	readonly expiresAt?: number;
+	/** Unique identifier for this cursor (UUID format) */
+	readonly id: string;
+	/** Optional user-defined metadata associated with this cursor */
+	readonly metadata?: Record<string, unknown>;
+	/** Current position/offset in the result set (zero-based) */
+	readonly position: number;
+	/** Time-to-live in milliseconds (optional, omitted if cursor never expires) */
+	readonly ttl?: 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;
+	/** User-defined metadata to associate with the cursor */
+	metadata?: Record<string, unknown>;
+	/** Starting position in the result set (must be non-negative) */
+	position: number;
+	/** 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 {
+	/**
+	* Remove all cursors from the store.
+	*/
+	clear(): void;
+	/**
+	* Delete a cursor by ID.
+	* @param id - The cursor ID to delete (no-op if not found)
+	*/
+	delete(id: string): 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;
+	/**
+	* 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;
+	/**
+	* Save or update a cursor in the store.
+	* @param cursor - The cursor to store (replaces existing if same ID)
+	*/
+	set(cursor: Cursor): void;
+}
+/**
+* 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 {
+	/**
+	* Dispose of the store and cleanup resources.
+	* Call this when the store is no longer needed.
+	*/
+	dispose(): void;
+	/**
+	* 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>;
+}
+/**
+* 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 {
+	/**
+	* Delete a cursor by ID.
+	* @param id - The cursor ID to delete
+	*/
+	delete(id: string): void;
+	/**
+	* 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;
+}
+/**
+* Result of a pagination operation.
+*
+* @typeParam T - The type of items being paginated
+*/
+interface PaginationResult<T> {
+	/** The cursor for the next page, or null if this is the last page */
+	nextCursor: Cursor | null;
+	/** The items in the current page */
+	page: T[];
+}
+export { Cursor, CreateCursorOptions, CursorStore, ScopedStore, PersistentStoreOptions, PersistentStore, PaginationStore, PaginationResult };

package/dist/shared/@outfitter/state-9q2yv8dy.d.ts

@@ -0,0 +1,133 @@
+import { CreateCursorOptions, Cursor } from "./state-6h22x3e6.js";
+import { Result, ValidationError } from "@outfitter/contracts";
+/**
+* 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>>;
+export { createCursor, advanceCursor, isExpired, encodeCursor, decodeCursor };

package/dist/shared/@outfitter/state-cgc92xms.d.ts

@@ -0,0 +1,139 @@
+import { CursorStore, PersistentStore, PersistentStoreOptions, ScopedStore } from "./state-6h22x3e6.js";
+/**
+* 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;
+export { createCursorStore, createPersistentStore, createScopedStore };