feat: memory transaction

packages/runner/src/builder/types.ts

@@ -84,7 +84,7 @@ declare module "@commontools/api" {
     connect(node: NodeRef): void;
     export(): {
       cell: OpaqueRef<any>;
-      path: PropertyKey[];
+      path: readonly PropertyKey[];
       value?: Opaque<T>;
       defaultValue?: Opaque<T>;
       nodes: Set<NodeRef>;
@@ -96,7 +96,7 @@ declare module "@commontools/api" {
     };
     unsafe_bindToRecipeAndPath(
       recipe: Recipe,
-      path: PropertyKey[],
+      path: readonly PropertyKey[],
     ): void;
     unsafe_getExternal(): OpaqueRef<T>;
     map<S>(
@@ -181,7 +181,9 @@ declare module "@commontools/api" {
     nodes: Node[];
     [unsafe_originalRecipe]?: Recipe;
     [unsafe_parentRecipe]?: Recipe;
-    [unsafe_materializeFactory]?: (log: any) => (path: PropertyKey[]) => any;
+    [unsafe_materializeFactory]?: (
+      log: any,
+    ) => (path: readonly PropertyKey[]) => any;
   }
 }
 
@@ -228,7 +230,7 @@ export function isShadowRef(value: unknown): value is ShadowRef {
 
 export type UnsafeBinding = {
   recipe: Recipe;
-  materialize: (path: PropertyKey[]) => any;
+  materialize: (path: readonly PropertyKey[]) => any;
   parent?: UnsafeBinding;
 };
 

packages/runner/src/cell.ts

@@ -39,7 +39,7 @@ import {
   type NormalizedFullLink,
   parseNormalizedFullLinktoLegacyDocCellLink,
 } from "./link-utils.ts";
-import { type IStorageTransaction } from "./storage/interface.ts";
+import type { IExtendedStorageTransaction as IStorageTransaction } from "./storage/interface.ts";
 
 /**
  * This is the regular Cell interface, generated by DocImpl.asCell().
@@ -174,7 +174,7 @@ declare module "@commontools/api" {
     ): Cell<T>;
     withLog(log: ReactivityLog): Cell<T>;
     sink(callback: (value: T) => Cancel | undefined | void): Cancel;
-    getAsQueryResult<Path extends PropertyKey[]>(
+    getAsQueryResult<Path extends readonly PropertyKey[]>(
       path?: Path,
       log?: ReactivityLog,
     ): QueryResult<DeepKeyLookup<T, Path>>;
@@ -231,7 +231,7 @@ declare module "@commontools/api" {
     space: MemorySpace;
     entityId: EntityId;
     sourceURI: URI;
-    path: PropertyKey[];
+    path: readonly PropertyKey[];
     [isCellMarker]: true;
     copyTrap: boolean;
   }
@@ -520,7 +520,13 @@ function createRegularCell<T>(
     getAsQueryResult: (subPath: PropertyKey[] = [], newLog?: ReactivityLog) =>
       createQueryResultProxy(doc, [...path, ...subPath], newLog ?? log),
     getAsLegacyCellLink: (): LegacyDocCellLink => {
-      return { space: doc.space, cell: doc, path, schema, rootSchema };
+      return {
+        space: doc.space,
+        cell: doc,
+        path: path as string[],
+        schema,
+        rootSchema,
+      };
     },
     getAsNormalizedFullLink: () => link,
     getAsLink: (
@@ -572,7 +578,13 @@ function createRegularCell<T>(
       return self.get();
     },
     get cellLink(): LegacyDocCellLink {
-      return { space: doc.space, cell: doc, path, schema, rootSchema };
+      return {
+        space: doc.space,
+        cell: doc,
+        path: path as string[],
+        schema,
+        rootSchema,
+      };
     },
     get space(): MemorySpace {
       return doc.space;
@@ -583,7 +595,7 @@ function createRegularCell<T>(
     get sourceURI(): URI {
       return toURI(doc.entityId);
     },
-    get path(): PropertyKey[] {
+    get path(): readonly PropertyKey[] {
       return path;
     },
     [isCellMarker]: true,
@@ -664,7 +676,7 @@ function subscribeToReferencedDocs<T>(
  */
 function createSigilLink(
   doc: DocImpl<any>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
   schema?: JSONSchema,
   rootSchema?: JSONSchema,
   options: {

packages/runner/src/data-updating.ts

@@ -24,7 +24,7 @@ import {
 // if there was no change.
 export function setNestedValue<T>(
   doc: DocImpl<T>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
   value: unknown,
   log?: ReactivityLog,
 ): boolean {

packages/runner/src/doc.ts

@@ -45,7 +45,9 @@ export type DocImpl<T> = {
    * @param path - Path to follow.
    * @returns Value.
    */
-  getAtPath<Path extends PropertyKey[]>(path: Path): DeepKeyLookup<T, Path>;
+  getAtPath<Path extends readonly PropertyKey[]>(
+    path: Path,
+  ): DeepKeyLookup<T, Path>;
 
   /**
    * Get as value proxy, following query (i.e. aliases) and cell references.
@@ -75,7 +77,7 @@ export type DocImpl<T> = {
    * @param log - Reactivity log.
    * @returns Simple cell.
    */
-  asCell<Q = T, Path extends PropertyKey[] = []>(
+  asCell<Q = T, Path extends readonly PropertyKey[] = []>(
     path?: Path,
     log?: ReactivityLog,
     schema?: JSONSchema,
@@ -117,7 +119,7 @@ export type DocImpl<T> = {
    * @returns Whether the value changed.
    */
   setAtPath(
-    path: PropertyKey[],
+    path: readonly PropertyKey[],
     newValue: any,
     log?: ReactivityLog,
     schema?: JSONSchema,
@@ -130,7 +132,7 @@ export type DocImpl<T> = {
    * @returns Cancel function.
    */
   updates(
-    callback: (value: T, path: PropertyKey[], labels?: Labels) => void,
+    callback: (value: T, path: readonly PropertyKey[], labels?: Labels) => void,
   ): Cancel;
 
   /**
@@ -233,7 +235,8 @@ export type DocImpl<T> = {
   copyTrap: boolean;
 };
 
-export type DeepKeyLookup<T, Path extends PropertyKey[]> = Path extends [] ? T
+export type DeepKeyLookup<T, Path extends readonly PropertyKey[]> = Path extends
+  [] ? T
   : Path extends [infer First, ...infer Rest]
     ? First extends keyof T
       ? Rest extends PropertyKey[] ? DeepKeyLookup<T[First], Rest>
@@ -293,7 +296,7 @@ export function createDoc<T>(
       callbacks.add(callback);
       return () => callbacks.delete(callback);
     },
-    getAtPath: (path: PropertyKey[]) => getValueAtPath(value, path),
+    getAtPath: (path: readonly PropertyKey[]) => getValueAtPath(value, path),
     setAtPath: (
       path: PropertyKey[],
       newValue: any,
@@ -346,7 +349,9 @@ export function createDoc<T>(
       return value as T;
     },
     get "/"(): string {
-      return typeof entityId.toJSON === "function" ? entityId.toJSON()["/"] : (entityId["/"] as string);
+      return typeof entityId.toJSON === "function"
+        ? entityId.toJSON()["/"]
+        : (entityId["/"] as string);
     },
     get entityId(): EntityId {
       return entityId;
@@ -399,15 +404,18 @@ export function createDoc<T>(
 
 const docLinkToOpaqueRef = new WeakMap<
   Frame,
-  WeakMap<DocImpl<any>, { path: PropertyKey[]; opaqueRef: OpaqueRef<any> }[]>
+  WeakMap<
+    DocImpl<any>,
+    { path: readonly PropertyKey[]; opaqueRef: OpaqueRef<any> }[]
+  >
 >();
 
 // Creates aliases to value, used in recipes to refer to this specific cell. We
 // have to memoize these, as conversion happens at multiple places when
 // creaeting the recipe.
 export function makeOpaqueRef(
   doc: DocImpl<any>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
 ): OpaqueRef<any> {
   const frame = getTopFrame();
   if (!frame) throw new Error("No frame");

packages/runner/src/link-resolution.ts

@@ -45,15 +45,15 @@ export function createVisits(): Visits {
  */
 function createPathCacheKey<T>(
   doc: DocImpl<T>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
   aliases: boolean = false,
 ): string {
   return JSON.stringify([doc.space, doc.toJSON(), path, aliases]);
 }
 
 export function resolveLinkToValue<T>(
   doc: DocImpl<T>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
   log?: ReactivityLog,
   schema?: JSONSchema,
   rootSchema?: JSONSchema,
@@ -65,7 +65,7 @@ export function resolveLinkToValue<T>(
 
 export function resolveLinkToWriteRedirect<T>(
   doc: DocImpl<T>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
   log?: ReactivityLog,
   schema?: JSONSchema,
   rootSchema?: JSONSchema,
@@ -85,7 +85,7 @@ export function resolveLinks(
 
 function resolvePath<T>(
   doc: DocImpl<T>,
-  path: PropertyKey[],
+  path: readonly PropertyKey[],
   log?: ReactivityLog,
   schema?: JSONSchema,
   rootSchema?: JSONSchema,

packages/runner/src/link-utils.ts

@@ -20,14 +20,17 @@ import {
   isQueryResultForDereferencing,
   QueryResultInternals,
 } from "./query-result-proxy.ts";
-import { type IMemoryAddress } from "./storage/interface.ts";
+import type {
+  IMemorySpaceAddress,
+  MemoryAddressPathComponent,
+} from "./storage/interface.ts";
 
 /**
  * Normalized link structure returned by parsers
  */
 export type NormalizedLink = {
   id?: URI; // URI format with "of:" prefix
-  path: string[];
+  path: readonly MemoryAddressPathComponent[];
   space?: MemorySpace;
   type?: string; // Default is "application/json"
   schema?: JSONSchema;
@@ -41,7 +44,7 @@ export type NormalizedLink = {
  *
  * Any such link can be used as a memory address.
  */
-export type NormalizedFullLink = NormalizedLink & IMemoryAddress;
+export type NormalizedFullLink = NormalizedLink & IMemorySpaceAddress;
 
 /**
  * A type reflecting all possible link formats, including cells themselves.
@@ -449,7 +452,7 @@ function parseToLegacyCellLinkWithMaybeACell(
 
   return {
     cell: cellValue,
-    path: link.path ?? [],
+    path: link.path as string[] ?? [],
     space: link.space,
     schema: link.schema,
     rootSchema: link.rootSchema,
@@ -471,7 +474,7 @@ export function parseNormalizedFullLinktoLegacyDocCellLink(
 ): LegacyDocCellLink {
   return {
     cell: runtime.getCellFromLink(link).getDoc(),
-    path: link.path,
+    path: link.path as string[],
   } satisfies LegacyDocCellLink;
 }
 
@@ -519,7 +522,7 @@ export function createSigilLinkFromParsedLink(
   const sigilLink: SigilLink = {
     "/": {
       [LINK_V1_TAG]: {
-        path: link.path,
+        path: link.path as string[],
         schema: link.schema,
         rootSchema: link.rootSchema,
       },

packages/runner/src/path-utils.ts

@@ -29,7 +29,7 @@ export function setValueAtPath(
   return true;
 }
 
-export function getValueAtPath(obj: any, path: PropertyKey[]): any {
+export function getValueAtPath(obj: any, path: readonly PropertyKey[]): any {
   let current = obj;
   for (const key of path) {
     if (current === undefined || current === null) return undefined;
@@ -65,7 +65,10 @@ export const deepEqual = (a: any, b: any): boolean => {
   return a !== a && b !== b; // NaN check
 };
 
-export function arrayEqual(a?: PropertyKey[], b?: PropertyKey[]): boolean {
+export function arrayEqual(
+  a?: readonly PropertyKey[],
+  b?: readonly PropertyKey[],
+): boolean {
   if (!a || !b) return a === b;
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;

packages/runner/src/runner.ts

@@ -249,8 +249,9 @@ export class Runner implements IRunner {
 
     // [unsafe closures:] For recipes from closures, add a materialize factory
     if (recipe[unsafe_originalRecipe]) {
-      recipe[unsafe_materializeFactory] = (log: any) => (path: PropertyKey[]) =>
-        processCell.getAsQueryResult(path, log);
+      recipe[unsafe_materializeFactory] =
+        (log: any) => (path: readonly PropertyKey[]) =>
+          processCell.getAsQueryResult(path, log);
     }
 
     for (const node of recipe.nodes) {
@@ -551,7 +552,7 @@ export class Runner implements IRunner {
 
         const frame = pushFrameFromCause(cause, {
           recipe,
-          materialize: (path: PropertyKey[]) =>
+          materialize: (path: readonly PropertyKey[]) =>
             processCell.getAsQueryResult(path),
         });
 
@@ -618,7 +619,7 @@ export class Runner implements IRunner {
           { inputs, outputs, fn: fn.toString() },
           {
             recipe,
-            materialize: (path: PropertyKey[]) =>
+            materialize: (path: readonly PropertyKey[]) =>
               processCell.getAsQueryResult(path, log),
           } satisfies UnsafeBinding,
         );

packages/runner/src/runtime.ts

@@ -9,9 +9,9 @@ import type { RecipeEnvironment } from "./builder/env.ts";
 import { ContextualFlowControl } from "./cfc.ts";
 import { setRecipeEnvironment } from "./builder/env.ts";
 import type {
+  IExtendedStorageTransaction,
   IStorageManager,
   IStorageProvider,
-  IStorageTransaction,
   MemorySpace,
 } from "./storage/interface.ts";
 import { type Cell } from "./cell.ts";
@@ -36,9 +36,9 @@ import {
 } from "./link-utils.ts";
 
 export type {
+  IExtendedStorageTransaction,
   IStorageManager,
   IStorageProvider,
-  IStorageTransaction,
   MemorySpace,
 };
 
@@ -92,7 +92,7 @@ export interface IRuntime {
   dispose(): Promise<void>;
 
   // Storage transaction method
-  edit(): IStorageTransaction;
+  edit(): IExtendedStorageTransaction;
 
   // Cell factory methods
   getCell<T>(
@@ -416,7 +416,7 @@ export class Runtime implements IRuntime {
    * locally replicated memory spaces. Transaction allows reading from many
    * multiple spaces but writing only to one space.
    */
-  edit(): IStorageTransaction {
+  edit(): IExtendedStorageTransaction {
     return new StorageTransaction(this);
   }