@velajs/cloudflare 1.10.1 → 2.0.0

package/dist/nonce.durable-object-Df3_42Sy.d.ts

@@ -0,0 +1,141 @@
+import { Type } from "@velajs/vela";
+import { DurableObject } from "cloudflare:workers";
+//#region src/root-module.d.ts
+/** A static module, or a module graph built from this Worker's native environment. */
+type CloudflareRoot<T extends object> = Type | {
+  create(env: T): Type;
+};
+//#endregion
+//#region src/websocket/do-pitr.d.ts
+/**
+ * Durable Object point-in-time recovery (PITR) — thin, testable wrappers over a
+ * SQLite-backed DO's native bookmark API. A SQLite Durable Object exposes three
+ * storage methods (last-30-days PITR):
+ *
+ *   - `getCurrentBookmark()` — an opaque bookmark for the storage's current state.
+ *   - `getBookmarkForTime(t)` — the bookmark closest to a wall-clock instant.
+ *   - `onNextSessionRestoreBookmark(b)` — arm a restore to bookmark `b`; the DO
+ *     restores to it the next time it starts a session, and the call RETURNS a
+ *     bookmark for the state JUST BEFORE the restore (the undo handle).
+ *
+ * These methods are ABSENT on a non-SQLite DO (key-value storage) and in some
+ * local-dev runtimes, so this module models storage structurally with all three
+ * methods OPTIONAL and degrades to a typed {@link DoPitrUnavailableError} (a
+ * `code: 'PITR_UNAVAILABLE'`, HTTP 409 error) rather than an
+ * `undefined is not a function` TypeError when a needed method is missing.
+ *
+ * Neither wrapper aborts the DO — `armDoPitr` only ARMS the restore and returns
+ * the undo bookmark; the caller (the WS-DO RPC method) decides whether to
+ * `ctx.abort()` to apply it immediately vs. on the next natural restart.
+ *
+ * This file is `cloudflare:workers`-free and pulls in NOTHING from `@velajs/vela`
+ * or `@velajs/studio` — it is the raw capability the studio `TimeTravelPort`
+ * wraps. Dependency direction is one-way: studio → cloudflare, never the reverse.
+ */
+/**
+ * The subset of `DurableObjectStorage` this module touches, with every method
+ * OPTIONAL so it structurally models a non-SQLite DO whose storage has none of
+ * them. A real `DurableObjectStorage` (whose methods are required) is assignable
+ * to this shape.
+ */
+interface DoPitrStorage {
+  getCurrentBookmark?(): Promise<string>;
+  getBookmarkForTime?(timestamp: number | Date): Promise<string>;
+  onNextSessionRestoreBookmark?(bookmark: string): Promise<string>;
+}
+/** A read of a DO's current bookmark (+ the by-time bookmark when a time is given). */
+interface DoPitrBookmarkRead {
+  /** The bookmark for the DO storage's current state. */
+  current: string;
+  /** The bookmark closest to the requested time (only when `time` was passed). */
+  forTime?: string;
+}
+/** Arming input for {@link armDoPitr}: a target (bookmark WINS over time) + restart intent. */
+interface DoPitrArmOptions {
+  /** An explicit target bookmark. Takes precedence over `time`. */
+  bookmark?: string;
+  /** A wall-clock target (epoch ms, ISO string, or Date), resolved to a bookmark. */
+  time?: number | string | Date;
+  /** Caller intent to restart-now; recorded on the result. `armDoPitr` never aborts. */
+  restart?: boolean;
+}
+/** The result of arming a PITR restore (before any restart is applied). */
+interface DoPitrArmResult {
+  /** The bookmark the restore is armed to. */
+  restoredTo: string;
+  /** The bookmark for the pre-restore state — restore to this to undo. */
+  undoBookmark: string;
+  /** Whether a restart-now was requested (the RPC layer performs the actual abort). */
+  restarted: boolean;
+}
+/** The RPC surface a PITR-capable Vela WebSocket DO stub exposes to a Worker. */
+interface VelaDoPitrRpc {
+  pitrCurrentBookmark(): Promise<DoPitrBookmarkRead>;
+  pitrBookmarkForTime(time: number | string): Promise<DoPitrBookmarkRead>;
+  pitrArmRestore(opts: DoPitrArmOptions): Promise<DoPitrArmResult>;
+}
+/** Structural view of a DO id (avoids depending on `@cloudflare/workers-types` downstream). */
+interface DoPitrId {
+  toString(): string;
+  readonly name?: string | null;
+}
+/**
+ * Structural view of a DO namespace binding whose stubs speak the PITR RPC. A
+ * downstream (the studio `@velajs/studio/cloudflare` port) types the app's
+ * namespace binding as this shape to reach the PITR methods without importing
+ * `@cloudflare/workers-types`.
+ */
+interface DoPitrNamespace {
+  idFromName(name: string): DoPitrId;
+  get(id: DoPitrId): VelaDoPitrRpc;
+}
+/**
+ * Thrown when a DO's storage lacks the SQLite bookmark API (non-SQLite DO, or a
+ * local runtime without PITR). Carries a stable `code` + HTTP 409 `status`, and
+ * a recognizable `name`/message so the studio port can map it to
+ * `TIMETRAVEL_UNAVAILABLE` even after the error crosses the Worker→DO RPC hop
+ * (which preserves `name` + `message`, not arbitrary own-properties).
+ */
+declare class DoPitrUnavailableError extends Error {
+  readonly code = "PITR_UNAVAILABLE";
+  readonly status = 409;
+  constructor(message?: string);
+}
+/**
+ * True when `error` signals DO PITR unavailability. Robust across the Worker→DO
+ * RPC hop: checks the `code` own-property (same process) AND the `name` / message
+ * sentinel (survive RPC serialization) so a downstream can classify it either way.
+ */
+declare function isDoPitrUnavailable(error: unknown): boolean;
+/**
+ * Read a DO's current bookmark, and — when `time` is given — the bookmark closest
+ * to that instant. Throws {@link DoPitrUnavailableError} when a needed method is
+ * absent, never `undefined is not a function`.
+ */
+declare function readDoPitrBookmark(storage: DoPitrStorage, time?: number | string | Date): Promise<DoPitrBookmarkRead>;
+/**
+ * Arm a PITR restore. Resolves the target (an explicit `bookmark` WINS over
+ * `time`), arms it via `onNextSessionRestoreBookmark`, and returns the undo
+ * bookmark the DO reports for the pre-restore state. Does NOT abort — the caller
+ * decides whether to restart now. Throws {@link DoPitrUnavailableError} when the
+ * arming API (or the by-time resolver a `time` target needs) is absent.
+ */
+declare function armDoPitr(storage: DoPitrStorage, opts: DoPitrArmOptions): Promise<DoPitrArmResult>;
+//#endregion
+//#region src/nonce/nonce.durable-object.d.ts
+/**
+ * SQLite Durable Object that atomically consumes nonces.
+ *
+ * Export this class from the Worker entry and register it through a Wrangler
+ * `new_sqlite_classes` migration. `INSERT ... ON CONFLICT DO NOTHING RETURNING`
+ * is the single-use decision; all SQL runs synchronously before the RPC method
+ * yields, and the nonce primary key is the final concurrency boundary.
+ */
+declare class VelaNonceDurableObject extends DurableObject<Record<string, unknown>> {
+  private sql?;
+  constructor(ctx: DurableObjectState, env: Record<string, unknown>);
+  claim(nonce: string, expEpochSeconds: number): Promise<boolean>;
+}
+//#endregion
+export { DoPitrId as a, DoPitrUnavailableError as c, isDoPitrUnavailable as d, readDoPitrBookmark as f, DoPitrBookmarkRead as i, VelaDoPitrRpc as l, DoPitrArmOptions as n, DoPitrNamespace as o, CloudflareRoot as p, DoPitrArmResult as r, DoPitrStorage as s, VelaNonceDurableObject as t, armDoPitr as u };
+//# sourceMappingURL=nonce.durable-object-Df3_42Sy.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.10.1",
+  "version": "2.0.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "keywords": [
     "cloudflare",
@@ -14,15 +14,16 @@
     "r2",
     "vela"
   ],
-  "homepage": "https://github.com/velajs/cloudflare#readme",
+  "homepage": "https://github.com/velajs/vela/tree/main/cloudflare#readme",
   "bugs": {
-    "url": "https://github.com/velajs/cloudflare/issues"
+    "url": "https://github.com/velajs/vela/issues"
   },
   "license": "MIT",
   "author": "ksh",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/velajs/cloudflare.git"
+    "url": "git+https://github.com/velajs/vela.git",
+    "directory": "cloudflare"
   },
   "files": [
     "dist",
@@ -38,29 +39,35 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./durable-objects": {
+      "types": "./dist/durable-objects.d.ts",
+      "import": "./dist/durable-objects.js"
     }
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.5",
-    "@changesets/cli": "^2.31.0",
-    "@cloudflare/workers-types": "^4.20260624.1",
-    "@swc/core": "^1.15.43",
-    "@velajs/feature-flags": "^0.1.0",
-    "@velajs/vela": "^1.17.0",
-    "hono": "^4.12.27",
-    "oxfmt": "^0.58.0",
-    "oxlint": "^1.73.0",
-    "publint": "^0.3.21",
-    "tsdown": "^0.22.4",
-    "typescript": "^7.0.2",
-    "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.10"
+    "@arethetypeswrong/cli": "0.18.5",
+    "@changesets/cli": "2.31.0",
+    "@cloudflare/vitest-plugin": "1.1.13",
+    "@cloudflare/workers-types": "5.20260920.1",
+    "@swc/core": "1.15.43",
+    "hono": "4.13.8",
+    "oxfmt": "0.58.0",
+    "oxlint": "1.73.0",
+    "publint": "0.3.21",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "unplugin-swc": "1.5.9",
+    "vitest": "4.1.10",
+    "zod": "^3.25.76",
+    "@velajs/feature-flags": "2.0.0",
+    "@velajs/vela": "2.0.0"
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/feature-flags": "^0.1.0",
-    "@velajs/vela": ">=1.17.0",
-    "hono": ">=4"
+    "hono": ">=4",
+    "@velajs/feature-flags": "^2.0.0",
+    "@velajs/vela": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@velajs/feature-flags": {
@@ -70,18 +77,19 @@
   "engines": {
     "node": ">=24"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "test:workers": "vitest run --config vitest.config.workers.ts",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "lint": "oxlint .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "publint": "publint",
     "attw": "attw --pack . --profile esm-only",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm build && changeset publish",
-    "verify": "pnpm lint && pnpm format:check && pnpm build && pnpm typecheck && pnpm test && pnpm publint && pnpm attw"
+    "verify": "pnpm lint && pnpm format:check && pnpm build && pnpm typecheck && pnpm test && pnpm test:workers && pnpm publint && pnpm attw"
   }
 }