@outfitter/state 0.1.0-rc.1

package/dist/index.js

@@ -0,0 +1,425 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/index.ts
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import {
+  NotFoundError,
+  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);
+}
+function createCursorStore() {
+  const cursors = new Map;
+  return {
+    set(cursor) {
+      cursors.set(cursor.id, cursor);
+    },
+    get(id) {
+      const cursor = cursors.get(id);
+      if (cursor === undefined) {
+        return Result.err(new NotFoundError({
+          message: `Cursor not found: ${id}`,
+          resourceType: "cursor",
+          resourceId: id
+        }));
+      }
+      if (isExpired(cursor)) {
+        return Result.err(new NotFoundError({
+          message: `Cursor expired: ${id}`,
+          resourceType: "cursor",
+          resourceId: id
+        }));
+      }
+      return Result.ok(cursor);
+    },
+    has(id) {
+      const cursor = cursors.get(id);
+      if (cursor === undefined) {
+        return false;
+      }
+      return !isExpired(cursor);
+    },
+    delete(id) {
+      cursors.delete(id);
+    },
+    clear() {
+      cursors.clear();
+    },
+    list() {
+      return Array.from(cursors.keys());
+    },
+    prune() {
+      let count = 0;
+      for (const [id, cursor] of cursors) {
+        if (isExpired(cursor)) {
+          cursors.delete(id);
+          count++;
+        }
+      }
+      return count;
+    },
+    getScope() {
+      return "";
+    }
+  };
+}
+async function createPersistentStore(options) {
+  const { path: storagePath } = options;
+  const cursors = new Map;
+  if (existsSync(storagePath)) {
+    try {
+      const content = await Bun.file(storagePath).text();
+      const data = JSON.parse(content);
+      if (data.cursors && typeof data.cursors === "object") {
+        for (const [id, cursor] of Object.entries(data.cursors)) {
+          cursors.set(id, cursor);
+        }
+      }
+    } catch {}
+  }
+  const flush = async () => {
+    const dir = dirname(storagePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const data = {
+      cursors: Object.fromEntries(cursors)
+    };
+    const tempPath = `${storagePath}.tmp.${Date.now()}`;
+    const content = JSON.stringify(data, null, 2);
+    try {
+      writeFileSync(tempPath, content, { encoding: "utf-8" });
+      renameSync(tempPath, storagePath);
+    } catch (error) {
+      try {
+        const { unlinkSync } = await import("node:fs");
+        unlinkSync(tempPath);
+      } catch {}
+      throw error;
+    }
+  };
+  const dispose = () => {};
+  return {
+    set(cursor) {
+      cursors.set(cursor.id, cursor);
+    },
+    get(id) {
+      const cursor = cursors.get(id);
+      if (cursor === undefined) {
+        return Result.err(new NotFoundError({
+          message: `Cursor not found: ${id}`,
+          resourceType: "cursor",
+          resourceId: id
+        }));
+      }
+      if (isExpired(cursor)) {
+        return Result.err(new NotFoundError({
+          message: `Cursor expired: ${id}`,
+          resourceType: "cursor",
+          resourceId: id
+        }));
+      }
+      return Result.ok(cursor);
+    },
+    has(id) {
+      const cursor = cursors.get(id);
+      if (cursor === undefined) {
+        return false;
+      }
+      return !isExpired(cursor);
+    },
+    delete(id) {
+      cursors.delete(id);
+    },
+    clear() {
+      cursors.clear();
+    },
+    list() {
+      return Array.from(cursors.keys());
+    },
+    prune() {
+      let count = 0;
+      for (const [id, cursor] of cursors) {
+        if (isExpired(cursor)) {
+          cursors.delete(id);
+          count++;
+        }
+      }
+      return count;
+    },
+    flush,
+    dispose
+  };
+}
+function createScopedStore(store, scope) {
+  const parentScope = "getScope" in store ? store.getScope() : "";
+  const fullScope = parentScope ? `${parentScope}:${scope}` : scope;
+  const prefix = `${fullScope}:`;
+  return {
+    set(cursor) {
+      const scopedCursor = Object.freeze({
+        ...cursor,
+        id: `${prefix}${cursor.id}`
+      });
+      store.set(scopedCursor);
+    },
+    get(id) {
+      const result = store.get(`${prefix}${id}`);
+      if (result.isErr()) {
+        return result;
+      }
+      const cursor = result.value;
+      return Result.ok(Object.freeze({
+        ...cursor,
+        id: cursor.id.slice(prefix.length)
+      }));
+    },
+    has(id) {
+      return store.has(`${prefix}${id}`);
+    },
+    delete(id) {
+      store.delete(`${prefix}${id}`);
+    },
+    clear() {
+      const ids = store.list().filter((id) => id.startsWith(prefix));
+      for (const id of ids) {
+        store.delete(id);
+      }
+    },
+    list() {
+      return store.list().filter((id) => id.startsWith(prefix)).map((id) => id.slice(prefix.length));
+    },
+    prune() {
+      return store.prune();
+    },
+    getScope() {
+      return fullScope;
+    }
+  };
+}
+var DEFAULT_PAGE_LIMIT = 25;
+var defaultPaginationStore = null;
+function getDefaultPaginationStore() {
+  if (defaultPaginationStore === null) {
+    defaultPaginationStore = createPaginationStore();
+  }
+  return defaultPaginationStore;
+}
+function createPaginationStore() {
+  const cursors = new Map;
+  return {
+    get(id) {
+      return cursors.get(id) ?? null;
+    },
+    set(id, cursor) {
+      cursors.set(id, cursor);
+    },
+    delete(id) {
+      cursors.delete(id);
+    }
+  };
+}
+function paginate(items, cursor) {
+  const offset = cursor.position;
+  const rawLimit = cursor.metadata?.limit;
+  const limit = typeof rawLimit === "number" && Number.isFinite(rawLimit) && rawLimit > 0 ? Math.floor(rawLimit) : DEFAULT_PAGE_LIMIT;
+  const page = items.slice(offset, offset + limit);
+  const nextPosition = offset + page.length;
+  if (nextPosition >= items.length) {
+    return { page, nextCursor: null };
+  }
+  const nextCursor = advanceCursor(cursor, nextPosition);
+  return { page, nextCursor };
+}
+function loadCursor(id, store) {
+  const effectiveStore = store ?? getDefaultPaginationStore();
+  const cursor = effectiveStore.get(id);
+  return Result.ok(cursor);
+}
+function saveCursor(cursor, store) {
+  const effectiveStore = store ?? getDefaultPaginationStore();
+  effectiveStore.set(cursor.id, cursor);
+  return Result.ok(undefined);
+}
+export {
+  saveCursor,
+  paginate,
+  loadCursor,
+  isExpired,
+  getDefaultPaginationStore,
+  encodeCursor,
+  decodeCursor,
+  createScopedStore,
+  createPersistentStore,
+  createPaginationStore,
+  createCursorStore,
+  createCursor,
+  advanceCursor,
+  DEFAULT_PAGE_LIMIT
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@outfitter/state",
+  "description": "Pagination cursor persistence and state management for Outfitter",
+  "version": "0.1.0-rc.1",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "bunup --filter @outfitter/state",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --write ./src",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "workspace:*",
+    "@outfitter/types": "workspace:*"
+  },
+  "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"
+  }
+}