@typicalday/firegraph 0.11.1 → 0.11.2

package/dist/cloudflare/index.d.cts

@@ -1,5 +1,6 @@
 import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-np4gEVhB.cjs';
 import { c as GraphRegistry, I as IndexSpec, i as QueryFilter, z as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-BGWxcpI_.cjs';
+import { DurableObject } from 'cloudflare:workers';
 import '@google-cloud/firestore';
 
 /**
@@ -79,14 +80,26 @@ interface DORecordWire {
  * }
  * ```
  *
- * ## Why a plain class (not `extends DurableObject`)?
+ * ## Why `extends DurableObject`?
  *
- * Cloudflare accepts any class with the `(state, env)` constructor shape as
- * a DO class. Extending `DurableObject` from `cloudflare:workers` would pull
- * a runtime import into this module and prevent it from loading in Node
- * tests. The plain-class form keeps this file runtime-neutral — the only
- * Cloudflare thing we touch is `ctx.storage.sql`, typed via local minimal
- * interfaces.
+ * Cloudflare's modern Durable Objects RPC dispatcher only accepts arbitrary
+ * method invocations on stubs whose backing class extends the special
+ * `DurableObject` base from `cloudflare:workers`. Plain classes with the
+ * `(state, env)` constructor shape still load and serve `fetch()`, but a
+ * stub method call (`stub._fgGetDoc(...)`) on a plain-class DO throws:
+ *
+ *   The receiving Durable Object does not support RPC, because its class
+ *   was not declared with `extends DurableObject`.
+ *
+ * `DORPCBackend` calls every operation as a stub method (see
+ * `src/cloudflare/backend.ts`), so extending `DurableObject` is mandatory
+ * for this library's design to work on production Workers.
+ *
+ * The `cloudflare:workers` import is virtual — only the workerd runtime
+ * resolves it. For Node tests we route the import through a vitest alias
+ * to a tiny stub class (`tests/__shims__/cloudflare-workers.ts`) that just
+ * captures `ctx`/`env`. Tests instantiating `FiregraphDO` directly still
+ * work; they just go through the stub instead of the real base class.
  */
 
 interface DOSqlCursor<T> {
@@ -146,11 +159,23 @@ interface FiregraphDOOptions {
      */
     coreIndexes?: IndexSpec[];
 }
-declare class FiregraphDO {
-    /** @internal — exposed for subclass access, not part of the public RPC. */
-    protected readonly ctx: DurableObjectStateLike;
-    /** @internal — exposed for subclass access; opaque to this class. */
-    protected readonly env: unknown;
+declare class FiregraphDO extends DurableObject<unknown> {
+    /**
+     * @internal — locally-narrowed alias for `this.ctx`, used only by
+     * FiregraphDO's own SQL helpers. Same runtime object as the inherited
+     * `this.ctx`, but typed as `DurableObjectStateLike` (just `storage.sql`
+     * / `transactionSync` / `blockConcurrencyWhile`) so internal calls
+     * don't trip over workers-types' stricter
+     * `SqlStorage.exec<T extends Record<string, SqlStorageValue>>`
+     * constraint vs the `Record<string, unknown>` rows firegraph passes.
+     *
+     * **Subclasses should use `this.ctx`, not `this.state`.** `this.state`
+     * deliberately exposes only the slice FiregraphDO needs internally;
+     * subclasses that want `id`, `acceptWebSocket`, `setAlarm`, `getAlarm`,
+     * `waitUntil`, `props`, etc. must reach for the inherited `this.ctx`
+     * (the full workers-types `DurableObjectState`).
+     */
+    protected readonly state: DurableObjectStateLike;
     /** @internal — table name used by every compiled statement. */
     protected readonly table: string;
     /** @internal — registry consulted by `runSchema` for per-entry indexes. */

package/dist/cloudflare/index.d.ts

@@ -1,5 +1,6 @@
 import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-U-MLShlg.js';
 import { c as GraphRegistry, I as IndexSpec, i as QueryFilter, z as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-BGWxcpI_.js';
+import { DurableObject } from 'cloudflare:workers';
 import '@google-cloud/firestore';
 
 /**
@@ -79,14 +80,26 @@ interface DORecordWire {
  * }
  * ```
  *
- * ## Why a plain class (not `extends DurableObject`)?
+ * ## Why `extends DurableObject`?
  *
- * Cloudflare accepts any class with the `(state, env)` constructor shape as
- * a DO class. Extending `DurableObject` from `cloudflare:workers` would pull
- * a runtime import into this module and prevent it from loading in Node
- * tests. The plain-class form keeps this file runtime-neutral — the only
- * Cloudflare thing we touch is `ctx.storage.sql`, typed via local minimal
- * interfaces.
+ * Cloudflare's modern Durable Objects RPC dispatcher only accepts arbitrary
+ * method invocations on stubs whose backing class extends the special
+ * `DurableObject` base from `cloudflare:workers`. Plain classes with the
+ * `(state, env)` constructor shape still load and serve `fetch()`, but a
+ * stub method call (`stub._fgGetDoc(...)`) on a plain-class DO throws:
+ *
+ *   The receiving Durable Object does not support RPC, because its class
+ *   was not declared with `extends DurableObject`.
+ *
+ * `DORPCBackend` calls every operation as a stub method (see
+ * `src/cloudflare/backend.ts`), so extending `DurableObject` is mandatory
+ * for this library's design to work on production Workers.
+ *
+ * The `cloudflare:workers` import is virtual — only the workerd runtime
+ * resolves it. For Node tests we route the import through a vitest alias
+ * to a tiny stub class (`tests/__shims__/cloudflare-workers.ts`) that just
+ * captures `ctx`/`env`. Tests instantiating `FiregraphDO` directly still
+ * work; they just go through the stub instead of the real base class.
  */
 
 interface DOSqlCursor<T> {
@@ -146,11 +159,23 @@ interface FiregraphDOOptions {
      */
     coreIndexes?: IndexSpec[];
 }
-declare class FiregraphDO {
-    /** @internal — exposed for subclass access, not part of the public RPC. */
-    protected readonly ctx: DurableObjectStateLike;
-    /** @internal — exposed for subclass access; opaque to this class. */
-    protected readonly env: unknown;
+declare class FiregraphDO extends DurableObject<unknown> {
+    /**
+     * @internal — locally-narrowed alias for `this.ctx`, used only by
+     * FiregraphDO's own SQL helpers. Same runtime object as the inherited
+     * `this.ctx`, but typed as `DurableObjectStateLike` (just `storage.sql`
+     * / `transactionSync` / `blockConcurrencyWhile`) so internal calls
+     * don't trip over workers-types' stricter
+     * `SqlStorage.exec<T extends Record<string, SqlStorageValue>>`
+     * constraint vs the `Record<string, unknown>` rows firegraph passes.
+     *
+     * **Subclasses should use `this.ctx`, not `this.state`.** `this.state`
+     * deliberately exposes only the slice FiregraphDO needs internally;
+     * subclasses that want `id`, `acceptWebSocket`, `setAlarm`, `getAlarm`,
+     * `waitUntil`, `props`, etc. must reach for the inherited `this.ctx`
+     * (the full workers-types `DurableObjectState`).
+     */
+    protected readonly state: DurableObjectStateLike;
     /** @internal — table name used by every compiled statement. */
     protected readonly table: string;
     /** @internal — registry consulted by `runSchema` for per-entry indexes. */

package/dist/cloudflare/index.js

@@ -5,7 +5,7 @@ import {
   computeEdgeDocId,
   computeNodeDocId,
   createGraphClientFromBackend
-} from "../chunk-6SB34IPQ.js";
+} from "../chunk-NJSOD64C.js";
 import {
   FiregraphError
 } from "../chunk-R7CRGYY4.js";
@@ -697,15 +697,28 @@ function createSiblingClient(client, siblingRootKey) {
 }
 
 // src/cloudflare/do.ts
+import { DurableObject } from "cloudflare:workers";
 var DEFAULT_OPTIONS = {
   table: "firegraph",
   autoMigrate: true
 };
-var FiregraphDO = class {
-  /** @internal — exposed for subclass access, not part of the public RPC. */
-  ctx;
-  /** @internal — exposed for subclass access; opaque to this class. */
-  env;
+var FiregraphDO = class extends DurableObject {
+  /**
+   * @internal — locally-narrowed alias for `this.ctx`, used only by
+   * FiregraphDO's own SQL helpers. Same runtime object as the inherited
+   * `this.ctx`, but typed as `DurableObjectStateLike` (just `storage.sql`
+   * / `transactionSync` / `blockConcurrencyWhile`) so internal calls
+   * don't trip over workers-types' stricter
+   * `SqlStorage.exec<T extends Record<string, SqlStorageValue>>`
+   * constraint vs the `Record<string, unknown>` rows firegraph passes.
+   *
+   * **Subclasses should use `this.ctx`, not `this.state`.** `this.state`
+   * deliberately exposes only the slice FiregraphDO needs internally;
+   * subclasses that want `id`, `acceptWebSocket`, `setAlarm`, `getAlarm`,
+   * `waitUntil`, `props`, etc. must reach for the inherited `this.ctx`
+   * (the full workers-types `DurableObjectState`).
+   */
+  state;
   /** @internal — table name used by every compiled statement. */
   table;
   /** @internal — registry consulted by `runSchema` for per-entry indexes. */
@@ -713,8 +726,8 @@ var FiregraphDO = class {
   /** @internal — overrides `DEFAULT_CORE_INDEXES` when set. */
   coreIndexes;
   constructor(ctx, env, options = {}) {
-    this.ctx = ctx;
-    this.env = env;
+    super(ctx, env);
+    this.state = ctx;
     const table = options.table ?? DEFAULT_OPTIONS.table;
     validateDOTableName(table);
     this.table = table;
@@ -722,7 +735,7 @@ var FiregraphDO = class {
     this.coreIndexes = options.coreIndexes;
     const autoMigrate = options.autoMigrate ?? DEFAULT_OPTIONS.autoMigrate;
     if (autoMigrate) {
-      void this.ctx.blockConcurrencyWhile(async () => {
+      void this.state.blockConcurrencyWhile(async () => {
         this.runSchema();
       });
     }
@@ -754,7 +767,7 @@ var FiregraphDO = class {
   async _fgUpdateDoc(docId, update) {
     const stmt = compileDOUpdate(this.table, docId, update, Date.now());
     const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
-    const rows = this.ctx.storage.sql.exec(sqlWithReturning, ...stmt.params).toArray();
+    const rows = this.state.storage.sql.exec(sqlWithReturning, ...stmt.params).toArray();
     if (rows.length === 0) {
       throw new FiregraphError(`updateDoc: no document found for doc_id=${docId}`, "NOT_FOUND");
     }
@@ -785,9 +798,9 @@ var FiregraphDO = class {
           return compileDODelete(this.table, op.docId);
       }
     });
-    this.ctx.storage.transactionSync(() => {
+    this.state.storage.transactionSync(() => {
       for (const stmt of statements) {
-        this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+        this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
       }
     });
   }
@@ -836,9 +849,9 @@ var FiregraphDO = class {
       };
     }
     try {
-      this.ctx.storage.transactionSync(() => {
+      this.state.storage.transactionSync(() => {
         for (const stmt of statements) {
-          this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+          this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
         }
       });
       return {
@@ -878,9 +891,9 @@ var FiregraphDO = class {
     }
     const deleteStmts = docIds.map((id) => compileDODelete(this.table, id));
     try {
-      this.ctx.storage.transactionSync(() => {
+      this.state.storage.transactionSync(() => {
         for (const stmt of deleteStmts) {
-          this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+          this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
         }
       });
       return { deleted: deleteStmts.length, batches: 1, errors: [] };
@@ -914,14 +927,14 @@ var FiregraphDO = class {
       registry: this.registry
     });
     for (const sql of statements) {
-      this.ctx.storage.sql.exec(sql).toArray();
+      this.state.storage.sql.exec(sql).toArray();
     }
   }
   execAll(stmt) {
-    return this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+    return this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
   }
   execRun(stmt) {
-    this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+    this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
   }
 };
 export {