@ng-org/orm 0.1.2-alpha.4 → 0.1.2-alpha.6

package/README.md

@@ -239,7 +239,7 @@ dogs.add({
 
 > **Note**: For nested sub-objects, `@graph` is optional — the parent's graph IRI is used.
 >
-> **Note**: If you want to use the ORM signal object in a non-component context, you can use `createSignalObjectForShape` function as well.
+> **Note**: If you want to use the ORM signal object in a non-component context, you can create an ORM connection manually using `OrmConnection.getOrCreate()`.
 
 ### Modifying Objects
 

package/dist/connector/applyPatches.d.ts

@@ -3,7 +3,7 @@ export type Patch = {
     path: string;
     valType?: string & {};
     value?: unknown;
-} & (SetAddPatch | SetRemovePatch | ObjectAddPatch | RemovePatch | LiteralAddPatch);
+} & (SetAddPatch | SetRemovePatch | RemovePatch | LiteralAddPatch);
 export interface SetAddPatch {
     /** Mutation kind applied at the resolved `path`. */
     op: "add";
@@ -24,12 +24,7 @@ export interface SetRemovePatch {
      *  - A single primitive
      *  - An array of primitives
      */
-    value: number | string | boolean | (number | string | boolean)[];
-}
-export interface ObjectAddPatch {
-    /** Mutation kind applied at the resolved `path`. */
-    op: "add";
-    valType: "object";
+    value: number | string | boolean | object | (number | string | boolean | object)[];
 }
 export interface RemovePatch {
     /** Mutation kind applied at the resolved `path`. */
@@ -39,7 +34,7 @@ export interface LiteralAddPatch {
     /** Mutation kind applied at the resolved `path`. */
     op: "add";
     /** The literal value to be added at the resolved `path` */
-    value: string | number | boolean;
+    value: string | number | boolean | object;
 }
 /**
  * Apply a diff to an object.
@@ -98,9 +93,9 @@ export interface LiteralAddPatch {
  *       from being triggered before these identity fields are set, which would cause it to generate
  *       random IDs unnecessarily.
  */
-export declare function applyPatches(currentState: Record<string, any>, patches: Patch[], ensurePathExists?: boolean): void;
+export declare function applyPatches(currentState: Record<string, any>, patches: Patch[], ormType: "set" | "discrete", ensurePathExists?: boolean): void;
 /**
- * See documentation for applyDiff
+ * See documentation for applyPatches
  */
-export declare function applyPatchesToDeepSignal(currentState: object, patch: Patch[]): void;
+export declare function applyPatchesToDeepSignal(currentState: object, patch: Patch[], ormType: "set" | "discrete"): void;
 //# sourceMappingURL=applyPatches.d.ts.map

package/dist/connector/applyPatches.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"applyPatches.d.ts","sourceRoot":"","sources":["../../src/connector/applyPatches.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,KAAK,GAAG;IAChB,iHAAiH;IACjH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,CACE,WAAW,GACX,cAAc,GACd,cAAc,GACd,WAAW,GACX,eAAe,CACpB,CAAC;AAEF,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CACpE;AAED,MAAM,WAAW,cAAc;IAC3B,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CACpE;AAED,MAAM,WAAW,cAAc;IAC3B,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC5B,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACpC;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,YAAY,CACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,EAAE,KAAK,EAAE,EAChB,gBAAgB,GAAE,OAAe,QAgOpC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAI5E"}
+{"version":3,"file":"applyPatches.d.ts","sourceRoot":"","sources":["../../src/connector/applyPatches.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,KAAK,GAAG;IAChB,iHAAiH;IACjH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,CAAC,WAAW,GAAG,cAAc,GAAG,WAAW,GAAG,eAAe,CAAC,CAAC;AAEnE,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CACpE;AAED,MAAM,WAAW,cAAc;IAC3B,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EACC,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC5B,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAC7C;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,YAAY,CACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,EAAE,KAAK,EAAE,EAChB,OAAO,EAAE,KAAK,GAAG,UAAU,EAC3B,gBAAgB,GAAE,OAAe,QA6PpC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACpC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,KAAK,EAAE,EACd,OAAO,EAAE,KAAK,GAAG,UAAU,QAU9B"}

package/dist/connector/applyPatches.js

@@ -101,7 +101,7 @@ function findInSetBySegment(set, seg) {
  *       from being triggered before these identity fields are set, which would cause it to generate
  *       random IDs unnecessarily.
  */
-export function applyPatches(currentState, patches, ensurePathExists = false) {
+export function applyPatches(currentState, patches, ormType, ensurePathExists = false) {
     for (let patchIndex = 0; patchIndex < patches.length; patchIndex++) {
         const patch = patches[patchIndex];
         if (!patch.path.startsWith("/"))
@@ -112,7 +112,8 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
             .filter(Boolean)
             .map(decodePathSegment);
         if (pathParts.length === 0) {
-            console.warn("[applyDiff] No path specified for patch", patch);
+            // Actually, this should mean replace..
+            console.warn("[applyPatches] No path specified for patch", patch);
             continue;
         }
         const lastKey = pathParts[pathParts.length - 1];
@@ -149,7 +150,7 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
             if (ensurePathExists) {
                 if (parentVal != null && typeof parentVal === "object") {
                     // Check if we need to create an object or a set:
-                    if (pathParts[i + 1]?.includes("|")) {
+                    if (pathParts[i + 1]?.includes("|") && ormType === "set") {
                         // The next path segment is an IRI, that means the new element must be a set of objects. Create a set.
                         parentVal[seg] = new Set();
                     }
@@ -170,13 +171,12 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
             }
         }
         if (parentMissing) {
-            console.warn(`[applyDiff] Skipping patch due to missing parent path segment(s): ${patch.path}`);
+            console.warn(`[applyPatches] Skipping patch due to missing parent path segment(s): ${patch.path}`);
             continue;
         }
-        // parentVal now should be an object or Set into which we apply lastKey
-        if (parentVal == null ||
-            (typeof parentVal !== "object" && !(parentVal instanceof Set))) {
-            console.warn(`[applyDiff] Skipping patch because parent is not an object or Set: ${patch.path}`);
+        // parentVal now should be an object, array, or set into which we apply lastKey
+        if (parentVal == null || typeof parentVal !== "object") {
+            console.warn(`[applyPatches] Skipping patch because parent is not an object or Set: ${patch.path}`);
             continue;
         }
         const key = lastKey;
@@ -185,7 +185,9 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
             // The key represents the identifier of an object within the Set
             const targetObj = findInSetBySegment(parentVal, key);
             // Handle object creation in a Set
-            if (patch.op === "add" && patch.valType === "object") {
+            if (patch.op === "add" &&
+                typeof patch.value === "object" &&
+                patch.value !== null) {
                 if (!targetObj) {
                     // Determine if this will be a single object or nested Set
                     const hasId = patches[patchIndex + 2]?.path.endsWith("@id");
@@ -203,6 +205,8 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
                         }
                     }
                     parentVal.add(newLeaf);
+                    // Skip the next two add (@id + @graph) patches.
+                    patchIndex += 2;
                 }
                 continue;
             }
@@ -215,14 +219,13 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
             }
             // All other operations require the target object to exist
             if (!targetObj) {
-                console.warn(`[applyDiff] Target object with @id=${key} not found in Set for path: ${patch.path}`);
+                console.warn(`[applyPatches] Target object with @id=${key} not found in Set for path: ${patch.path}`);
                 continue;
             }
             // This shouldn't happen - we handle all intermediate segments in the traversal loop
-            console.warn(`[applyDiff] Unexpected: reached end of path with Set as parent: ${patch.path}`);
+            console.warn(`[applyPatches] Unexpected: reached end of path with Set as parent: ${patch.path}`);
             continue;
         }
-        // Regular object handling (parentVal is a plain object, not a Set)
         // Handle primitive set additions
         if (patch.op === "add" && patch.valType === "set") {
             const existing = parentVal[key];
@@ -267,7 +270,11 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
         // Distinguish between single objects and multi-object containers:
         // - If an @id patch follows for this path, it's a single object -> create {}
         // - If no @id patch follows, it's a container for multi-valued objects -> create set.
-        if (patch.op === "add" && patch.valType === "object") {
+        if (patch.op === "add" &&
+            typeof patch.value === "object" &&
+            patch.value !== null &&
+            ormType === "set" // TODO: The backend should preferably add valType: "set" here (we don't need ormType then).
+        ) {
             const leafVal = parentVal[key];
             const hasId = patches.at(patchIndex + 2)?.path.endsWith("@id");
             // If the leafVal does not exist and it should be a set, create.
@@ -286,12 +293,34 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
                     newLeaf["@id"] = idPatch.value;
                 }
                 parentVal[key] = newLeaf;
+                // Skip the next two add (@id + @graph) patches.
+                patchIndex += 2;
             }
             continue;
         }
-        // Literal add
-        if (patch.op === "add" &&
-            !(patch.path.endsWith("@id") || patch.path.endsWith("@graph"))) {
+        if (Array.isArray(parentVal)) {
+            if (key === "-") {
+                if (patch.op == "add") {
+                    parentVal.push(patch.value);
+                }
+                else {
+                    parentVal.pop();
+                }
+            }
+            else if (patch.op == "add") {
+                let keyNum = Number(key);
+                parentVal.splice(keyNum, 0, patch.value);
+            }
+            else {
+                // patch.op == remove
+                let keyNum = Number(key);
+                // Remove element at position from array in-place (will resize).
+                parentVal.splice(keyNum, 1);
+            }
+            continue;
+        }
+        // Basic add
+        if (patch.op === "add") {
             parentVal[key] = patch.value;
             continue;
         }
@@ -305,11 +334,11 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
     }
 }
 /**
- * See documentation for applyDiff
+ * See documentation for applyPatches
  */
-export function applyPatchesToDeepSignal(currentState, patch) {
+export function applyPatchesToDeepSignal(currentState, patch, ormType) {
     batch(() => {
-        applyPatches(currentState, patch, true);
+        applyPatches(currentState, patch, ormType, false);
     });
 }
 function decodePathSegment(segment) {

package/dist/connector/discrete/discreteOrmConnectionHandler.d.ts

@@ -0,0 +1,45 @@
+import { DiscreteArray, DiscreteObject } from "../../types.ts";
+import { Patch } from "../applyPatches.ts";
+import type { DeepPatch, DeepSignal } from "@ng-org/alien-deepsignals";
+import type { BaseType } from "@ng-org/shex-orm";
+export declare class DiscreteOrmConnection {
+    private static idToEntry;
+    readonly documentId: string;
+    private _signalObject;
+    private stopSignalListening;
+    private subscriptionId;
+    private refCount;
+    suspendDeepWatcher: boolean;
+    inTransaction: boolean;
+    /** Aggregation of patches to be sent when in transaction. */
+    pendingPatches: Patch[] | undefined;
+    /** Resolves once the data arrives */
+    readyPromise: Promise<void>;
+    private closeOrmConnection;
+    /** Called to resolve the readyPromise. */
+    private resolveReady;
+    private constructor();
+    get signalObject(): DeepSignal<DiscreteArray | DiscreteObject> | undefined;
+    /**
+     * Get or create a connection which contains the ORM and lifecycle methods.
+     * @param shapeType
+     * @param scope
+     * @param ng
+     * @returns
+     */
+    static getOrCreate: <T extends BaseType>(documentId: string) => DiscreteOrmConnection;
+    close: () => void;
+    private onSignalObjectUpdate;
+    private onBackendMessage;
+    private handleInitialResponse;
+    private onBackendUpdate;
+    beginTransaction: () => void;
+    commitTransaction: () => Promise<void>;
+}
+/**
+ * Converts DeepSignal patches to ORM Wasm-compatible patches
+ * @param patches DeepSignal patches
+ * @returns Patches with stringified path
+ */
+export declare function deepPatchesToWasm(patches: DeepPatch[]): Patch[];
+//# sourceMappingURL=discreteOrmConnectionHandler.d.ts.map

package/dist/connector/discrete/discreteOrmConnectionHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discreteOrmConnectionHandler.d.ts","sourceRoot":"","sources":["../../../src/connector/discrete/discreteOrmConnectionHandler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAA4B,KAAK,EAAE,MAAM,oBAAoB,CAAC;AASrE,OAAO,KAAK,EACR,SAAS,EACT,UAAU,EAGb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AASjD,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4C;IAEpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,aAAa,CAEL;IAChB,OAAO,CAAC,mBAAmB,CAA2B;IACtD,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAS;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAS;IAC/B,6DAA6D;IAC7D,cAAc,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IACpC,qCAAqC;IACrC,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,kBAAkB,CAAa;IACvC,0CAA0C;IAC1C,OAAO,CAAC,YAAY,CAAc;IAElC,OAAO;IA+BP,IAAW,YAAY,2DAEtB;IAED;;;;;;OAMG;IACH,OAAc,WAAW,GAAI,CAAC,SAAS,QAAQ,EAC3C,YAAY,MAAM,KACnB,qBAAqB,CActB;IAEK,KAAK,aASV;IAEF,OAAO,CAAC,oBAAoB,CAsB1B;IAEF,OAAO,CAAC,gBAAgB,CAStB;IAEF,OAAO,CAAC,qBAAqB,CAiB3B;IAEF,OAAO,CAAC,eAAe,CAUrB;IAEK,gBAAgB,aAerB;IAEK,iBAAiB,sBAiCtB;CACL;AAED;;;;GAIG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,CAO/D"}

package/dist/connector/discrete/discreteOrmConnectionHandler.js

@@ -0,0 +1,186 @@
+// Copyright (c) 2025 Laurin Weger, Par le Peuple, NextGraph.org developers
+// All rights reserved.
+// Licensed under the Apache License, Version 2.0
+// <LICENSE-APACHE2 or http://www.apache.org/licenses/LICENSE-2.0>
+// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>,
+// at your option. All files in the project carrying such
+// notice may not be copied, modified, or distributed except
+// according to those terms.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+import { applyPatchesToDeepSignal } from "../applyPatches.js";
+import { ngSession } from "../initNg.js";
+import { deepSignal, watch as watchDeepSignal, } from "@ng-org/alien-deepsignals";
+/**
+ * Delay in ms to wait before closing connection.\
+ * Useful when a hook unsubscribes and resubscribes in a short time interval
+ * so that no new connections need to be set up.
+ */
+const WAIT_BEFORE_CLOSE = 500;
+export class DiscreteOrmConnection {
+    static idToEntry = new Map();
+    documentId;
+    _signalObject;
+    stopSignalListening;
+    subscriptionId;
+    refCount;
+    suspendDeepWatcher;
+    inTransaction = false;
+    /** Aggregation of patches to be sent when in transaction. */
+    pendingPatches;
+    /** Resolves once the data arrives */
+    readyPromise;
+    closeOrmConnection;
+    /** Called to resolve the readyPromise. */
+    resolveReady;
+    constructor(documentId) {
+        // @ts-expect-error
+        window.ormDiscreteSignalConnections = DiscreteOrmConnection.idToEntry;
+        // @ts-expect-error
+        window.OrmDiscreteConnection = DiscreteOrmConnection;
+        // @ts-expect-error
+        window.OrmDiscreteIncomingPatches = [];
+        this.documentId = documentId;
+        this.refCount = 1;
+        this.closeOrmConnection = () => { };
+        this.suspendDeepWatcher = false;
+        // Initialize per-entry readiness promise that resolves in setUpConnection
+        this.readyPromise = new Promise((resolve) => {
+            this.resolveReady = resolve;
+        });
+        ngSession.then(async ({ ng, session }) => {
+            try {
+                this.closeOrmConnection = await ng.orm_start_discrete(documentId, session.session_id, this.onBackendMessage);
+            }
+            catch (e) {
+                console.error(e);
+            }
+        });
+    }
+    get signalObject() {
+        return this._signalObject;
+    }
+    /**
+     * Get or create a connection which contains the ORM and lifecycle methods.
+     * @param shapeType
+     * @param scope
+     * @param ng
+     * @returns
+     */
+    static getOrCreate = (documentId) => {
+        // If we already have a connection open,
+        // return that signal object it and just increase the reference count.
+        // Otherwise, open a new one.
+        const existingConnection = DiscreteOrmConnection.idToEntry.get(documentId);
+        if (existingConnection) {
+            existingConnection.refCount += 1;
+            return existingConnection;
+        }
+        else {
+            const newConnection = new DiscreteOrmConnection(documentId);
+            DiscreteOrmConnection.idToEntry.set(documentId, newConnection);
+            return newConnection;
+        }
+    };
+    close = () => {
+        setTimeout(() => {
+            if (this.refCount > 0)
+                this.refCount--;
+            if (this.refCount === 0) {
+                DiscreteOrmConnection.idToEntry.delete(this.documentId);
+                this.closeOrmConnection();
+            }
+        }, WAIT_BEFORE_CLOSE);
+    };
+    onSignalObjectUpdate = async ({ patches, }) => {
+        if (this.suspendDeepWatcher || !patches.length)
+            return;
+        const ormPatches = deepPatchesToWasm(patches);
+        // If in transaction, collect patches immediately (no await before).
+        if (this.inTransaction) {
+            this.pendingPatches?.push(...ormPatches);
+            return;
+        }
+        // Wait for session and subscription to be initialized.
+        const { ng, session } = await ngSession;
+        await this.readyPromise;
+        ng.discrete_orm_update(this.subscriptionId, ormPatches, session.session_id);
+    };
+    onBackendMessage = (message) => {
+        const data = message?.V0;
+        if (data?.DiscreteOrmInitial) {
+            this.handleInitialResponse(data.DiscreteOrmInitial);
+        }
+        else if (data?.DiscreteOrmUpdate) {
+            this.onBackendUpdate(data.DiscreteOrmUpdate);
+        }
+        else {
+            console.warn("Received unknown ORM message from backend", message);
+        }
+    };
+    handleInitialResponse = ([initialData, subscriptionId]) => {
+        this.subscriptionId = subscriptionId;
+        const signalObject = deepSignal(initialData, {
+            syntheticIdPropertyName: undefined,
+        });
+        this._signalObject = signalObject;
+        const { stopListening } = watchDeepSignal(this._signalObject, this.onSignalObjectUpdate);
+        this.stopSignalListening = stopListening;
+        // Resolve readiness after initial data is committed and watcher armed.
+        this.resolveReady();
+    };
+    onBackendUpdate = (patches) => {
+        // @ts-expect-error
+        window.OrmDiscreteIncomingPatches.push(patches);
+        this.suspendDeepWatcher = true;
+        applyPatchesToDeepSignal(this._signalObject, patches, "discrete");
+        // Use queueMicrotask to ensure watcher is re-enabled _after_ batch completes
+        queueMicrotask(() => {
+            this.suspendDeepWatcher = false;
+        });
+    };
+    beginTransaction = () => {
+        this.inTransaction = true;
+        this.pendingPatches = [];
+        this.readyPromise.then(() => {
+            // Use a listener that immediately triggers on object modifications.
+            // We don't need the deep-signal's batching (through microtasks) here.
+            this.stopSignalListening?.();
+            const { stopListening } = watchDeepSignal(this.signalObject, this.onSignalObjectUpdate, { triggerInstantly: true });
+            this.stopSignalListening = stopListening;
+        });
+    };
+    commitTransaction = async () => {
+        if (!this.inTransaction) {
+            throw new Error("No transaction is open. Call `beginTransaction` first.");
+        }
+        const { ng, session } = await ngSession;
+        await this.readyPromise;
+        this.inTransaction = false;
+        if (this.pendingPatches?.length == 0) {
+            // Nothing to send to the backend.
+        }
+        else {
+            ng.discrete_orm_update(this.subscriptionId, this.pendingPatches, session.session_id);
+        }
+        this.pendingPatches = undefined;
+        // Go back to the regular object modification listening where we want batching
+        // scheduled in a microtask only triggered after the main task.
+        // This way we prevent excessive calls to the backend.
+        this.stopSignalListening();
+        const { stopListening } = watchDeepSignal(this.signalObject, this.onSignalObjectUpdate);
+        this.stopSignalListening = stopListening;
+    };
+}
+/**
+ * Converts DeepSignal patches to ORM Wasm-compatible patches
+ * @param patches DeepSignal patches
+ * @returns Patches with stringified path
+ */
+export function deepPatchesToWasm(patches) {
+    return patches.flatMap((patch) => {
+        if (patch.op === "add" && patch.type === "set" && !patch.value?.length)
+            return [];
+        const path = "/" + patch.path.join("/");
+        return { ...patch, path };
+    });
+}

package/dist/connector/getObjects.d.ts

@@ -0,0 +1,10 @@
+import { BaseType, ShapeType } from "@ng-org/shex-orm";
+import { Scope } from "../types.ts";
+/**
+ * Utility for retrieving objects once without establishing a two-way subscription.
+ * @param shapeType The shape type of the objects to be retrieved.
+ * @param scope The scope of the objects to be retrieved.
+ * @returns A set of all objects matching the shape and scope
+ */
+export declare function getObjects<T extends BaseType>(shapeType: ShapeType<T>, scope?: Scope): Promise<import("@ng-org/alien-deepsignals").DeepSignalSet<T>>;
+//# sourceMappingURL=getObjects.d.ts.map

package/dist/connector/getObjects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getObjects.d.ts","sourceRoot":"","sources":["../../src/connector/getObjects.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,QAAQ,EAC/C,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,KAAK,GAAE,KAAU,iEAUpB"}

package/dist/connector/getObjects.js

@@ -0,0 +1,25 @@
+// Copyright (c) 2025 Laurin Weger, Par le Peuple, NextGraph.org developers
+// All rights reserved.
+// Licensed under the Apache License, Version 2.0
+// <LICENSE-APACHE2 or http://www.apache.org/licenses/LICENSE-2.0>
+// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>,
+// at your option. All files in the project carrying such
+// notice may not be copied, modified, or distributed except
+// according to those terms.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+import { OrmConnection } from "./ormConnectionHandler.js";
+import { deepClone } from "./utils.js";
+/**
+ * Utility for retrieving objects once without establishing a two-way subscription.
+ * @param shapeType The shape type of the objects to be retrieved.
+ * @param scope The scope of the objects to be retrieved.
+ * @returns A set of all objects matching the shape and scope
+ */
+export async function getObjects(shapeType, scope = {}) {
+    const connection = OrmConnection.getOrCreate(shapeType, scope);
+    await connection.readyPromise;
+    setTimeout(() => {
+        connection.close();
+    }, 1_000);
+    return deepClone(connection.signalObject);
+}

package/dist/connector/insertObject.d.ts

@@ -0,0 +1,8 @@
+import { BaseType, ShapeType } from "@ng-org/shex-orm";
+/**
+ * Utility for adding ORM-typed objects to the database without the need for subscribing to documents.
+ * @param shapeType The shape type of the objects to be inserted.
+ * @param object The object to be inserted.
+ */
+export declare function insertObject<T extends BaseType>(shapeType: ShapeType<T>, object: T): Promise<void>;
+//# sourceMappingURL=insertObject.d.ts.map

package/dist/connector/insertObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insertObject.d.ts","sourceRoot":"","sources":["../../src/connector/insertObject.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,QAAQ,EACjD,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,CAAC,iBASZ"}

package/dist/connector/{createSignalObjectForShape.js → insertObject.js}

@@ -9,16 +9,15 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 import { OrmConnection } from "./ormConnectionHandler.js";
 /**
- *
- * @param shapeType
- * @param scope
- * @returns
+ * Utility for adding ORM-typed objects to the database without the need for subscribing to documents.
+ * @param shapeType The shape type of the objects to be inserted.
+ * @param object The object to be inserted.
  */
-export function createSignalObjectForShape(shapeType, scope) {
-    const connection = OrmConnection.getConnection(shapeType, scope || "");
-    return {
-        signalObject: connection.signalObject,
-        stop: connection.release,
-        readyPromise: connection.readyPromise,
-    };
+export async function insertObject(shapeType, object) {
+    const connection = OrmConnection.getOrCreate(shapeType, {
+        graphs: [], // Subscribe to no documents
+    });
+    await connection.readyPromise;
+    connection.signalObject.add(object);
+    connection.close();
 }

package/dist/connector/ormConnectionHandler.d.ts

@@ -1,5 +1,6 @@
-import type { Diff as Patches, Scope } from "../types.ts";
-import type { DeepPatch, DeepSignalSet } from "@ng-org/alien-deepsignals";
+import type { Scope } from "../types.ts";
+import { Patch } from "./applyPatches.ts";
+import type { DeepSignalSet } from "@ng-org/alien-deepsignals";
 import type { ShapeType, BaseType } from "@ng-org/shex-orm";
 export declare class OrmConnection<T extends BaseType> {
     private static idToEntry;
@@ -8,40 +9,40 @@ export declare class OrmConnection<T extends BaseType> {
      * Useful when a hook unsubscribes and resubscribes in a short time interval
      * so that no new connections need to be set up.
      */
-    private WAIT_BEFORE_RELEASE;
     readonly shapeType: ShapeType<T>;
     readonly scope: Scope;
     readonly signalObject: DeepSignalSet<T>;
+    private stopSignalListening;
+    private subscriptionId;
     private refCount;
     /** Identifier as a combination of shape type and scope. Prevents duplications. */
     private identifier;
     suspendDeepWatcher: boolean;
+    inTransaction: boolean;
+    /** Aggregation of patches to be sent when in transaction. */
+    pendingPatches: Patch[] | undefined;
     readyPromise: Promise<void>;
-    cancel: () => void;
+    private closeOrmConnection;
     /** Promise that resolves once initial data has been applied. */
     resolveReady: () => void;
     private static cleanupSignalRegistry;
     private constructor();
     /**
-     * Get a connection which contains the ORM and lifecycle methods.
+     * Get or create a connection which contains the ORM and lifecycle methods.
      * @param shapeType
      * @param scope
      * @param ng
      * @returns
      */
-    static getConnection: <T_1 extends BaseType>(shapeType: ShapeType<T_1>, scope: Scope) => OrmConnection<T_1>;
-    release: () => void;
+    static getOrCreate: <T_1 extends BaseType>(shapeType: ShapeType<T_1>, scope: Scope) => OrmConnection<T_1>;
+    close: () => void;
     private onSignalObjectUpdate;
     private onBackendMessage;
     private handleInitialResponse;
     private onBackendUpdate;
     /** Function to create random subject IRIs for newly created nested objects. */
     private signalObjectPropGenerator;
+    beginTransaction: () => void;
+    commitTransaction: () => Promise<void>;
 }
-/**
- * Converts DeepSignal patches to ORM Wasm-compatible patches
- * @param patches DeepSignal patches
- * @returns Patches with stringified path
- */
-export declare function deepPatchesToWasm(patches: DeepPatch[]): Patches;
 //# sourceMappingURL=ormConnectionHandler.d.ts.map

package/dist/connector/ormConnectionHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ormConnectionHandler.d.ts","sourceRoot":"","sources":["../../src/connector/ormConnectionHandler.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAU1D,OAAO,KAAK,EACR,SAAS,EAET,aAAa,EAEhB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5D,qBAAa,aAAa,CAAC,CAAC,SAAS,QAAQ;IACzC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAyC;IACjE;;;;OAIG;IACH,OAAO,CAAC,mBAAmB,CAAO;IAElC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,QAAQ,CAAS;IACzB,kFAAkF;IAClF,OAAO,CAAC,UAAU,CAAS;IAC3B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,gEAAgE;IAChE,YAAY,EAAG,MAAM,IAAI,CAAC;IAG1B,OAAO,CAAC,MAAM,CAAC,qBAAqB,CASrB;IAEf,OAAO;IAgDP;;;;;;OAMG;IACH,OAAc,aAAa,GAAI,GAAC,SAAS,QAAQ,EAC7C,WAAW,SAAS,CAAC,GAAC,CAAC,EACvB,OAAO,KAAK,KACb,aAAa,CAAC,GAAC,CAAC,CAkBjB;IAEK,OAAO,aAYZ;IAEF,OAAO,CAAC,oBAAoB,CAe1B;IAEF,OAAO,CAAC,gBAAgB,CAStB;IAEF,OAAO,CAAC,qBAAqB,CAmB3B;IACF,OAAO,CAAC,eAAe,CAOrB;IAEF,+EAA+E;IAC/E,OAAO,CAAC,yBAAyB,CAgD/B;CACL;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAO/D"}
+{"version":3,"file":"ormConnectionHandler.d.ts","sourceRoot":"","sources":["../../src/connector/ormConnectionHandler.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAA4B,KAAK,EAAE,MAAM,mBAAmB,CAAC;AASpE,OAAO,KAAK,EAER,aAAa,EAEhB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAK5D,qBAAa,aAAa,CAAC,CAAC,SAAS,QAAQ;IACzC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAyC;IACjE;;;;OAIG;IAEH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAS;IACzB,kFAAkF;IAClF,OAAO,CAAC,UAAU,CAAS;IAC3B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAS;IAC/B,6DAA6D;IAC7D,cAAc,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IACpC,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,kBAAkB,CAAa;IACvC,gEAAgE;IAChE,YAAY,EAAG,MAAM,IAAI,CAAC;IAG1B,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAUrB;IAEf,OAAO;IAoDP;;;;;;OAMG;IACH,OAAc,WAAW,GAAI,GAAC,SAAS,QAAQ,EAC3C,WAAW,SAAS,CAAC,GAAC,CAAC,EACvB,OAAO,KAAK,KACb,aAAa,CAAC,GAAC,CAAC,CAkBjB;IAEK,KAAK,aAYV;IAEF,OAAO,CAAC,oBAAoB,CAoB1B;IAEF,OAAO,CAAC,gBAAgB,CAStB;IAEF,OAAO,CAAC,qBAAqB,CAuB3B;IACF,OAAO,CAAC,eAAe,CAOrB;IAEF,+EAA+E;IAC/E,OAAO,CAAC,yBAAyB,CAgD/B;IAEK,gBAAgB,aAarB;IAEK,iBAAiB,sBAkCtB;CACL"}