@outfitter/state 0.2.3 → 0.2.5

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

@@ -0,0 +1,139 @@
+import { Cursor, PaginationResult, PaginationStore } from "./state-6h22x3e6.js";
+import { Result, StorageError } from "@outfitter/contracts";
+/**
+* Default page size when limit is not specified in cursor metadata.
+*/
+declare const DEFAULT_PAGE_LIMIT = 25;
+/**
+* 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;
+/**
+* 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 { DEFAULT_PAGE_LIMIT, getDefaultPaginationStore, createPaginationStore, paginate, loadCursor, saveCursor };

package/package.json

@@ -1,11 +1,25 @@
 {
   "name": "@outfitter/state",
+  "version": "0.2.5",
   "description": "Pagination cursor persistence and state management for Outfitter",
-  "version": "0.2.3",
-  "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,38 +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 ../.. && bash ./scripts/run-bunup-with-lock.sh bunup --filter @outfitter/state",
+    "lint": "oxlint ./src",
+    "lint:fix": "oxlint --fix ./src",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
   },
   "dependencies": {
-    "@outfitter/contracts": "0.4.1",
-    "@outfitter/types": "0.2.3"
+    "@outfitter/contracts": "0.5.0",
+    "@outfitter/types": "0.2.5"
   },
   "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"
   }
 }