@typicalday/firegraph 0.11.1 → 0.12.0

package/dist/cloudflare/index.d.cts

@@ -1,5 +1,8 @@
-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 { W as WritableRecord, b as WriteMode, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-Ct-fLlkG.cjs';
+export { d as deleteField } from '../backend-Ct-fLlkG.cjs';
+import { e as GraphRegistry, I as IndexSpec, g 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, l as GraphReader, G as GraphClientOptions, c as DynamicRegistryConfig } from '../types-DxYLy8Ol.cjs';
+import { DurableObject } from 'cloudflare:workers';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, b as createMergedRegistry, d as createRegistry, f as generateId } from '../registry-B1qsVL0E.cjs';
 import '@google-cloud/firestore';
 
 /**
@@ -79,14 +82,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> {
@@ -111,6 +126,7 @@ type BatchOp = {
     kind: 'set';
     docId: string;
     record: WritableRecord;
+    mode: WriteMode;
 } | {
     kind: 'update';
     docId: string;
@@ -146,11 +162,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. */
@@ -160,7 +188,7 @@ declare class FiregraphDO {
     constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     /**
@@ -232,7 +260,7 @@ interface DurableObjectIdLike {
 interface FiregraphStub {
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     _fgBatch(ops: BatchOp[]): Promise<void>;
@@ -295,7 +323,7 @@ declare class DORPCBackend implements StorageBackend {
     private get stub();
     getDoc(docId: string): Promise<StoredGraphRecord | null>;
     query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
-    setDoc(docId: string, record: WritableRecord): Promise<void>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     updateDoc(docId: string, update: UpdatePayload): Promise<void>;
     deleteDoc(docId: string): Promise<void>;
     runTransaction<T>(_fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;

package/dist/cloudflare/index.d.ts

@@ -1,5 +1,8 @@
-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 { W as WritableRecord, b as WriteMode, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-BsR0lnFL.js';
+export { d as deleteField } from '../backend-BsR0lnFL.js';
+import { e as GraphRegistry, I as IndexSpec, g 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, l as GraphReader, G as GraphClientOptions, c as DynamicRegistryConfig } from '../types-DxYLy8Ol.js';
+import { DurableObject } from 'cloudflare:workers';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, b as createMergedRegistry, d as createRegistry, f as generateId } from '../registry-Fi074zVa.js';
 import '@google-cloud/firestore';
 
 /**
@@ -79,14 +82,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> {
@@ -111,6 +126,7 @@ type BatchOp = {
     kind: 'set';
     docId: string;
     record: WritableRecord;
+    mode: WriteMode;
 } | {
     kind: 'update';
     docId: string;
@@ -146,11 +162,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. */
@@ -160,7 +188,7 @@ declare class FiregraphDO {
     constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     /**
@@ -232,7 +260,7 @@ interface DurableObjectIdLike {
 interface FiregraphStub {
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     _fgBatch(ops: BatchOp[]): Promise<void>;
@@ -295,7 +323,7 @@ declare class DORPCBackend implements StorageBackend {
     private get stub();
     getDoc(docId: string): Promise<StoredGraphRecord | null>;
     query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
-    setDoc(docId: string, record: WritableRecord): Promise<void>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     updateDoc(docId: string, update: UpdatePayload): Promise<void>;
     deleteDoc(docId: string): Promise<void>;
     runTransaction<T>(_fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;