@outfitter/state 0.2.2 → 0.2.4

package/README.md

@@ -42,14 +42,14 @@ if (cursorResult.isOk()) {
 
 Cursors are intentionally **opaque** to consumers. They are immutable, frozen objects that encapsulate pagination state.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | Unique identifier for storage lookup |
-| `position` | `number` | Current offset in the result set |
-| `metadata` | `Record<string, unknown>` | Optional user-defined context |
-| `ttl` | `number` | Time-to-live in milliseconds (optional) |
-| `expiresAt` | `number` | Computed Unix timestamp for expiry (if TTL set) |
-| `createdAt` | `number` | Unix timestamp when cursor was created |
+| Property    | Type                      | Description                                     |
+| ----------- | ------------------------- | ----------------------------------------------- |
+| `id`        | `string`                  | Unique identifier for storage lookup            |
+| `position`  | `number`                  | Current offset in the result set                |
+| `metadata`  | `Record<string, unknown>` | Optional user-defined context                   |
+| `ttl`       | `number`                  | Time-to-live in milliseconds (optional)         |
+| `expiresAt` | `number`                  | Computed Unix timestamp for expiry (if TTL set) |
+| `createdAt` | `number`                  | Unix timestamp when cursor was created          |
 
 ### Why Opaque?
 
@@ -95,7 +95,11 @@ if (result.isOk()) {
 ### Example: Paginated Handler
 
 ```typescript
-import { createCursor, createCursorStore, advanceCursor } from "@outfitter/state";
+import {
+  createCursor,
+  createCursorStore,
+  advanceCursor,
+} from "@outfitter/state";
 import { Result } from "@outfitter/contracts";
 
 const store = createCursorStore();
@@ -150,11 +154,11 @@ const issuesStore = createScopedStore(store, "linear:issues");
 const prsStore = createScopedStore(store, "github:prs");
 
 // Cursors are isolated - same ID won't conflict
-issuesStore.set(issueCursor);  // Stored as "linear:issues:cursor-id"
-prsStore.set(prCursor);        // Stored as "github:prs:cursor-id"
+issuesStore.set(issueCursor); // Stored as "linear:issues:cursor-id"
+prsStore.set(prCursor); // Stored as "github:prs:cursor-id"
 
 // Each scope manages its own cursors
-issuesStore.clear();  // Only clears issue cursors
+issuesStore.clear(); // Only clears issue cursors
 ```
 
 ### Nested Scopes
@@ -167,8 +171,8 @@ const githubStore = createScopedStore(store, "github");
 const issuesStore = createScopedStore(githubStore, "issues");
 const prsStore = createScopedStore(githubStore, "prs");
 
-issuesStore.getScope();  // "github:issues"
-prsStore.getScope();     // "github:prs"
+issuesStore.getScope(); // "github:issues"
+prsStore.getScope(); // "github:prs"
 ```
 
 ### Scoped Store Behavior
@@ -183,15 +187,15 @@ if (cursor.isOk()) {
   scoped.set(cursor.value);
 
   // Underlying store has prefixed ID
-  store.list();  // ["my-scope:abc123"]
+  store.list(); // ["my-scope:abc123"]
 
   // Scoped store returns clean ID
-  scoped.list();  // ["abc123"]
+  scoped.list(); // ["abc123"]
 
   // Get returns cursor with clean ID
   const result = scoped.get("abc123");
   if (result.isOk()) {
-    result.value.id;  // "abc123" (not "my-scope:abc123")
+    result.value.id; // "abc123" (not "my-scope:abc123")
   }
 }
 ```
@@ -257,7 +261,7 @@ const result = createCursor({
 
 if (result.isOk()) {
   const cursor = result.value;
-  cursor.ttl;       // 3600000
+  cursor.ttl; // 3600000
   cursor.expiresAt; // Unix timestamp (e.g., 1706000000000)
 }
 ```
@@ -289,7 +293,7 @@ Cursors created without a TTL never expire:
 ```typescript
 const result = createCursor({ position: 0 });
 if (result.isOk()) {
-  result.value.ttl;       // undefined
+  result.value.ttl; // undefined
   result.value.expiresAt; // undefined
   isExpired(result.value); // always false
 }
@@ -299,24 +303,24 @@ if (result.isOk()) {
 
 ### Functions
 
-| Function | Description |
-|----------|-------------|
-| `createCursor(options)` | Create a new immutable pagination cursor |
+| Function                          | Description                               |
+| --------------------------------- | ----------------------------------------- |
+| `createCursor(options)`           | Create a new immutable pagination cursor  |
 | `advanceCursor(cursor, position)` | Create a new cursor with updated position |
-| `isExpired(cursor)` | Check if a cursor has expired |
-| `createCursorStore()` | Create an in-memory cursor store |
-| `createPersistentStore(options)` | Create a disk-backed cursor store |
-| `createScopedStore(store, scope)` | Create a namespace-isolated cursor store |
+| `isExpired(cursor)`               | Check if a cursor has expired             |
+| `createCursorStore()`             | Create an in-memory cursor store          |
+| `createPersistentStore(options)`  | Create a disk-backed cursor store         |
+| `createScopedStore(store, scope)` | Create a namespace-isolated cursor store  |
 
 ### Interfaces
 
-| Interface | Description |
-|-----------|-------------|
-| `Cursor` | Immutable pagination cursor |
-| `CreateCursorOptions` | Options for `createCursor()` |
-| `CursorStore` | Base interface for cursor stores |
-| `ScopedStore` | Cursor store with namespace isolation |
-| `PersistentStore` | Cursor store with disk persistence |
+| Interface                | Description                           |
+| ------------------------ | ------------------------------------- |
+| `Cursor`                 | Immutable pagination cursor           |
+| `CreateCursorOptions`    | Options for `createCursor()`          |
+| `CursorStore`            | Base interface for cursor stores      |
+| `ScopedStore`            | Cursor store with namespace isolation |
+| `PersistentStore`        | Cursor store with disk persistence    |
 | `PersistentStoreOptions` | Options for `createPersistentStore()` |
 
 ## Error Handling
@@ -339,7 +343,7 @@ if (getResult.isErr()) {
   // NotFoundError: Cursor not found: nonexistent
   console.error(getResult.error.message);
   console.log(getResult.error.resourceType); // "cursor"
-  console.log(getResult.error.resourceId);   // "nonexistent"
+  console.log(getResult.error.resourceId); // "nonexistent"
 }
 ```
 

package/dist/index.d.ts

@@ -23,18 +23,18 @@ import { NotFoundError, Result, StorageError, ValidationError } from "@outfitter
 * ```
 */
 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;
-	/** 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>;
+	/** 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;
-	/** 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.
@@ -56,10 +56,10 @@ interface Cursor {
 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>;
+	/** Starting position in the result set (must be non-negative) */
+	position: number;
 	/** Time-to-live in milliseconds (cursor never expires if omitted) */
 	ttl?: number;
 }
@@ -92,10 +92,14 @@ interface CreateCursorOptions {
 */
 interface CursorStore {
 	/**
-	* Save or update a cursor in the store.
-	* @param cursor - The cursor to store (replaces existing if same ID)
+	* Remove all cursors from the store.
 	*/
-	set(cursor: Cursor): void;
+	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
@@ -109,15 +113,6 @@ interface CursorStore {
 	*/
 	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
 	*/
@@ -127,6 +122,11 @@ interface CursorStore {
 	* @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.
@@ -198,17 +198,17 @@ interface PersistentStoreOptions {
 * ```
 */
 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>;
-	/**
-	* Dispose of the store and cleanup resources.
-	* Call this when the store is no longer needed.
-	*/
-	dispose(): void;
 }
 /**
 * Create a new pagination cursor.
@@ -378,53 +378,6 @@ declare function decodeCursor(encoded: string): Result<Cursor, InstanceType<type
 * ```
 */
 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.
@@ -503,6 +456,11 @@ declare const DEFAULT_PAGE_LIMIT = 25;
 * ```
 */
 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
@@ -515,11 +473,6 @@ interface PaginationStore {
 	* @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).
@@ -568,10 +521,10 @@ declare function createPaginationStore(): PaginationStore;
 * @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;
+	/** The items in the current page */
+	page: T[];
 }
 /**
 * Extract a page of items based on cursor position.

package/dist/index.js

@@ -1,9 +1,9 @@
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
+// @bun
+var __require = import.meta.require;
 
-// src/index.ts
-import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+// packages/state/src/index.ts
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
+import { dirname } from "path";
 import {
   NotFoundError,
   Result,
@@ -213,6 +213,7 @@ function createCursorStore() {
     }
   };
 }
+var dispose = () => {};
 async function createPersistentStore(options) {
   const { path: storagePath } = options;
   const cursors = new Map;
@@ -242,13 +243,12 @@ async function createPersistentStore(options) {
       renameSync(tempPath, storagePath);
     } catch (error) {
       try {
-        const { unlinkSync } = await import("node:fs");
+        const { unlinkSync } = await import("fs");
         unlinkSync(tempPath);
       } catch {}
       throw error;
     }
   };
-  const dispose = () => {};
   return {
     set(cursor) {
       cursors.set(cursor.id, cursor);

package/package.json

@@ -1,11 +1,25 @@
 {
   "name": "@outfitter/state",
+  "version": "0.2.4",
   "description": "Pagination cursor persistence and state management for Outfitter",
-  "version": "0.2.2",
-  "type": "module",
+  "keywords": [
+    "cursor",
+    "outfitter",
+    "pagination",
+    "state",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/outfitter-dev/outfitter.git",
+    "directory": "packages/state"
+  },
   "files": [
     "dist"
   ],
+  "type": "module",
+  "sideEffects": false,
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -17,37 +31,24 @@
     },
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "bunup --filter @outfitter/state",
-    "lint": "biome lint ./src",
-    "lint:fix": "biome lint --write ./src",
+    "build": "cd ../.. && bunup --filter @outfitter/state",
+    "lint": "oxlint ./src",
+    "lint:fix": "oxlint --fix ./src",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
   },
   "dependencies": {
-    "@outfitter/contracts": "0.4.0",
-    "@outfitter/types": "0.2.2"
+    "@outfitter/contracts": "0.4.2",
+    "@outfitter/types": "0.2.4"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "typescript": "^5.8.0"
-  },
-  "keywords": [
-    "outfitter",
-    "state",
-    "pagination",
-    "cursor",
-    "typescript"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/outfitter-dev/outfitter.git",
-    "directory": "packages/state"
-  },
-  "publishConfig": {
-    "access": "public"
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3"
   }
 }