feat(runner): add resolveAsCell() method to Cell API (#1916)

feat(runner): add `resolveAsCell()` method to Cell API

Adds a new `resolveAsCell()` method that resolves a cell reference to the
actual cell it points to. This is useful when accessing data via .key() and wanting a direct reference to the final underlying document, e.g. to create an id for it.

The method is equivalent to wrapping the current schema in `Cell<>` and
calling `.get()`, providing a more convenient API for this common pattern.

Includes test coverage for resolving nested cell references.

Author: seefeldb

packages/api/index.ts

@@ -26,6 +26,7 @@ export interface Cell<T = any> {
   push(...value: T extends (infer U)[] ? U[] : never): void;
   equals(other: Cell<any>): boolean;
   key<K extends keyof T>(valueKey: K): Cell<T[K]>;
+  resolveAsCell(): Cell<T>;
 }
 
 // Cell type with only public methods

packages/runner/src/cell.ts

@@ -73,8 +73,8 @@ import { ContextualFlowControl } from "./cfc.ts";
  * @returns {void}
  *
  * @method push Adds an item to the end of an array cell.
- * @param {U | Cell<U>} value - The value to add, where U is
- * the array element type.
+ * @param {U | Cell<U>} value - The value to add, where U is the array element
+ * type.
  * @returns {void}
  *
  * @method equals Compares two cells for equality.
@@ -102,6 +102,10 @@ import { ContextualFlowControl } from "./cfc.ts";
  * @method sync Syncs the cell to the storage.
  * @returns {Promise<void>}
  *
+ * @method resolveAsCell Resolves the cell to a new cell with the resolved link.
+ * Equivalent to `cell.getAsSchema(<current schema wrapped in Cell<>).get()`
+ * @returns {Cell<T>}
+ *
  * @method getAsQueryResult Returns a query result for the cell.
  * @param {Path} path - The optional path to follow.
  * @param {ReactivityLog} log - Optional reactivity log.
@@ -197,6 +201,7 @@ declare module "@commontools/api" {
     withTx(tx?: IExtendedStorageTransaction): Cell<T>;
     sink(callback: (value: Readonly<T>) => Cancel | undefined | void): Cancel;
     sync(): Promise<Cell<T>> | Cell<T>;
+    resolveAsCell(): Cell<T>;
     getAsQueryResult<Path extends PropertyKey[]>(
       path?: Readonly<Path>,
       tx?: IExtendedStorageTransaction,
@@ -646,6 +651,11 @@ export class RegularCell<T> implements Cell<T> {
     return this.runtime.storageManager.syncCell<T>(this);
   }
 
+  resolveAsCell(): Cell<T> {
+    const link = resolveLink(this.runtime.readTx(this.tx), this.link);
+    return createCell(this.runtime, link, this.tx, true, this.synced);
+  }
+
   getAsQueryResult<Path extends PropertyKey[]>(
     path?: Readonly<Path>,
     tx?: IExtendedStorageTransaction,

packages/runner/test/cell.test.ts

@@ -3642,4 +3642,33 @@ describe("Cell success callbacks", () => {
       expect(link0.id).not.toBe(link1.id);
     });
   });
+
+  describe("resolveAsCell", () => {
+    it("should resolve a cell reference to the actual cell", () => {
+      const innerCell = runtime.getCell<number>(
+        space,
+        "inner-cell",
+        { type: "number" },
+        tx,
+      );
+      innerCell.set(42);
+
+      const outerCell = runtime.getCell<{ inner: unknown }>(
+        space,
+        "outer-cell",
+        {
+          type: "object",
+          properties: {
+            inner: { type: "number" },
+          },
+        },
+        tx,
+      );
+      outerCell.set({ inner: innerCell });
+
+      const resolvedCell = outerCell.key("inner").resolveAsCell();
+
+      expect(resolvedCell.equals(innerCell)).toBe(true);
+    });
+  });
 });

packages/static/assets/types/commontools.d.ts

@@ -17,6 +17,7 @@ export interface Cell<T = any> {
     push(...value: T extends (infer U)[] ? U[] : never): void;
     equals(other: Cell<any>): boolean;
     key<K extends keyof T>(valueKey: K): Cell<T[K]>;
+    resolveAsCell(): Cell<T>;
 }
 export interface Stream<T> {
     send(event: T): void;