@ng-org/orm 0.1.2-alpha.1 → 0.1.2-alpha.10

package/dist/connector/applyPatches.js

@@ -26,7 +26,7 @@ function parseGraphId(input) {
     return { graph, id };
 }
 /**
- * Find an object in a Set by its @id property.
+ * Find an object in a Set by its `@id` property.
  * Returns the object if found, otherwise undefined.
  */
 function findInSetBySegment(set, seg) {
@@ -45,63 +45,31 @@ function findInSetBySegment(set, seg) {
     return undefined;
 }
 /**
+ * @ignore
+ *
  * Apply a diff to an object.
  *
  * The syntax is inspired by RFC 6902 but it is not compatible.
  *
  * It supports Sets for multi-valued properties:
  *   - Primitive values are added as Sets (Set<string | number | boolean>)
- *   - Multi-valued objects are stored in Sets, accessed by their @id property
- *   - Single objects are plain objects with an @id property
+ *   - Multi-valued objects are stored in Sets, accessed by their `@id` property
+ *   - Single objects are plain objects with an `@id` property
  *
  * Path traversal:
- *   - When traversing through a Set, the path segment is treated as an @id to find the object
+ *   - When traversing through a Set, the path segment is treated as an `@id` to find the object
  *   - When traversing through a plain object, the path segment is a property name
  *
- * @example operations
- *   ```jsonc
- *     // === SINGLE OBJECT ===
- *     // Creating a single object (has @id at same level)
- *     { "op": "add", "path": "/urn:example:person1/address", "valType": "object" }
- *     { "op": "add", "path": "/urn:example:person1/address/@id", "value": "urn:test:address1" }
- *     // Adding primitives to single object
- *     { "op": "add", "path": "/urn:example:person1/address/street", "value": "1st street" }
- *     { "op": "add", "path": "/urn:example:person1/address/country", "value": "Greece" }
- *     // Remove a primitive from object
- *     { "op": "remove", "path": "/urn:example:person1/address/street" }
- *     // Remove the entire object
- *     { "op": "remove", "path": "/urn:example:person1/address" }
- *
- *     // === MULTI-VALUED OBJECTS (Set) ===
- *     // Creating a multi-object container (NO @id at this level -> creates Set)
- *     { "op": "add", "path": "/urn:example:person1/children", "valType": "object" }
- *     // Adding an object to the Set (path includes object's @id)
- *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1", "valType": "object" }
- *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1/@id", "value": "urn:example:child1" }
- *     // Adding properties to object in Set
- *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1/name", "value": "Alice" }
- *     // Remove an object from Set
- *     { "op": "remove", "path": "/urn:example:person1/children/urn:example:child1" }
- *     // Remove all objects (the Set itself)
- *     { "op": "remove", "path": "/urn:example:person1/children" }
- *
- *     // === PRIMITIVE SETS ===
- *     // Add primitive types to Sets
- *     { "op": "add", "valType": "set", "path": "/urn:example:person1/tags", "value": [1,2,3] }
- *     // Remove primitive types from a Set
- *     { "op": "remove", "valType": "set", "path": "/urn:example:person1/tags", "value": [1,2] }
- * ```
- *
  * @param currentState The object before the patch
  * @param patches An array of patches to apply to the object.
  * @param ensurePathExists If true, create nested objects along the path if the path does not exist.
  *
- * @note When creating new objects, this function pre-scans upcoming patches to find @id and @graph
+ * Note: When creating new objects, this function pre-scans upcoming patches to find `@id` and `@graph`
  *       values that will be assigned to the object. This prevents the signal library's propGenerator
  *       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 +80,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 +118,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 +139,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 +153,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 +173,8 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
                         }
                     }
                     parentVal.add(newLeaf);
+                    // Skip the next two add (@id + @graph) patches.
+                    patchIndex += 2;
                 }
                 continue;
             }
@@ -215,14 +187,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 +238,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 engine 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 +261,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 +302,13 @@ export function applyPatches(currentState, patches, ensurePathExists = false) {
     }
 }
 /**
- * See documentation for applyDiff
+ * @ignore
+ *
+ * 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/discreteOrmSubscriptionHandler.d.ts

@@ -0,0 +1,168 @@
+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";
+/**
+ * Class for managing RDF-based ORM subscriptions with the engine.
+ *
+ * You have two options on how to interact with the ORM:
+ * - Use a hook for your favorite framework under `@ng-org/orm/react|vue|svelte`
+ * - Call {@link OrmSubscription.getOrCreate} to create a subscription manually
+ *
+ * For more information about RDF-based ORM subscriptions,
+ * see the [README](../../../README.md) and follow the tutorial.
+ */
+export declare class DiscreteOrmSubscription {
+    /** Global store of all subscriptions. We use that for pooling. */
+    private static idToEntry;
+    /** The document ID (NURI) of the subscribed document. */
+    readonly documentId: string;
+    private _signalObject;
+    private stopSignalListening;
+    /** The subscription ID kept as an identifier for communicating with the verifier. */
+    private subscriptionId;
+    /** The number of OrmSubscriptions with the same shape and scope (for pooling). */
+    private refCount;
+    /** When true, modifications from the signalObject are not processed. */
+    private suspendDeepWatcher;
+    /** @readonly True, if a transaction is running. */
+    inTransaction: boolean;
+    /** Aggregation of patches to be sent when in transaction. */
+    pendingPatches: Patch[] | undefined;
+    /** **Await to ensure that the subscription is established and the data arrived.** */
+    readyPromise: Promise<void>;
+    private closeOrmSubscription;
+    /** Function to call once initial data has been applied. */
+    private resolveReady;
+    private constructor();
+    /**
+     * The signalObject containing all data of the document
+     * (once subscription is established).
+     * The object behaves like a regular object or array with a couple of additions:
+     * - Modifications are immediately propagated back to the database.
+     * - Database changes are immediately reflected in the object.
+     * - Watch for object changes using {@link watchDeepSignal}.
+     * - Objects in arrays receive a unique `@id` property.
+     */
+    get signalObject(): DeepSignal<DiscreteArray | DiscreteObject> | undefined;
+    /**
+     * Returns an OrmSubscription which subscribes to the given
+     * document in a 2-way binding.
+     *
+     * You **find the document data** in the **`signalObject`**,
+     * once {@link readyPromise} resolves.
+     * This is a {@link DeepSignal} object or array, depending on
+     * your CRDT document (e.g. YArray vs YMap). The signalObject
+     * behaves like a regular set to the outside but has a couple
+     * of additional features:
+     * - Modifications are propagated back to the document.
+     *   Note that multiple immediate modifications in the same task,
+     *   e.g. `obj[0] = "foo"; obj[1] = "bar"` are batched together
+     *   and sent in a subsequent microtask.
+     * - External document changes are immediately reflected in the object.
+     * - Watch for object changes using {@link watchDeepSignal}.
+     *
+     * You can use **transactions**, to prevent excessive calls to the engine
+     * with {@link beginTransaction} and {@link commitTransaction}.
+     *
+     * In many cases, you are advised to use a hook for your
+     * favorite framework under `@ng-org/orm/react|vue|svelte`
+     * instead of calling `getOrCreate` directly.
+     *
+     * Call `{@link close}, to close the subscription.
+     *
+     * Note: If another call to `getOrCreate` was previously made
+     * and {@link close} was not called on it (or only shortly after),
+     * it will return the same OrmSubscription (pooling).
+     *
+     * @param documentId The document ID (NURI) of the CRDT
+     *
+     * @example
+     * ```typescript
+     * // We assume you have created a CRDT document already, as below.
+     * // const documentId = await ng.doc_create(
+     * //     session_id,
+     * //     crdt, // "Automerge" | "YMap" | "YArray". YArray is for root arrays, the other two have objects at root.
+     * //     crdt === "Automerge" ? "data:json" : crdt === "YMap ? "data:map" : "data:array",
+     * //     "store",
+     * //     undefined
+     * // );
+     * const subscription = DiscreteOrmSubscription.getOrCreate(documentId);
+     * // Wait for data.
+     * await subscription.readyPromise;
+     *
+     * const document = subscription.signalObject;
+     * if (!document.expenses) {
+     *     document.expenses = [];
+     * }
+     * document.expenses.push({
+     *     name: "New Expense name",
+     *     description: "Expense description"
+     * });
+     *
+     * // Await promise to run the below code in a new task.
+     * // That will have push the changes to the database.
+     * await Promise.resolve();
+     *
+     * // Here, the expense modifications have been committed
+     * // (unless you had previously called subscription.beginTransaction()).
+     * // The data is available in subscriptions running on a different device too.
+     *
+     * subscription.close();
+     *
+     * // If you create a new subscription with the same document within a couple of 100ms,
+     * // The subscription hasn't been closed and the old one is returned so that the data
+     * // is available instantly. This is especially useful in the context of unmounting and remounting frontend frameworks.
+     * const subscription2 = DiscreteOrmSubscription.getOrCreate(documentId);
+     *
+     * subscription2.signalObject.expenses.push({
+     *     name: "Second expense",
+     *     description: "Second description"
+     * });
+     *
+     * subscription2.close();
+     * ```
+     */
+    static getOrCreate: <T extends BaseType>(documentId: string) => DiscreteOrmSubscription;
+    /**
+     * Stop the subscription.
+     *
+     * **If there is more than one subscription with the document ID,
+     * the orm subscription won't close yet.**
+     *
+     * Additionally, the closing of the subscription is delayed by a couple hundred milliseconds
+     * so that when frontend frameworks unmount and soon mount a component again with the same
+     * document ID, we reuse the same orm subscription.
+     */
+    close: () => void;
+    /** Handle updates (patches) coming from signal object modifications. */
+    private onSignalObjectUpdate;
+    /** Handle messages coming from the engine (initial data or patches). */
+    private onBackendMessage;
+    private handleInitialResponse;
+    /** Handle incoming patches from the engine */
+    private onBackendUpdate;
+    /**
+     * Begins a transaction that batches changes to be committed to the database.
+     * This is useful for performance reasons.
+     *
+     * Note that this does not disable reactivity of the `signalObject`.
+     * Modifications keep being rendered instantly.
+     */
+    beginTransaction: () => void;
+    /**
+     * Commits a transactions sending all modifications made during the transaction
+     * (started with `beginTransaction`) to the database.
+     * @throws if no transaction is open.
+     */
+    commitTransaction: () => Promise<void>;
+}
+/**
+ * Converts DeepSignal patches to ORM Wasm-compatible patches
+ * @param patches DeepSignal patches
+ * @returns Patches with stringified path
+ *
+ * @ignore
+ */
+export declare function deepPatchesToWasm(patches: DeepPatch[]): Patch[];
+//# sourceMappingURL=discreteOrmSubscriptionHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discreteOrmSubscriptionHandler.d.ts","sourceRoot":"","sources":["../../../src/connector/discrete/discreteOrmSubscriptionHandler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAA4B,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAQrE,OAAO,KAAK,EACR,SAAS,EACT,UAAU,EAEb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AASjD;;;;;;;;;GASG;AACH,qBAAa,uBAAuB;IAChC,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,SAAS,CAA8C;IAEtE,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,aAAa,CAEL;IAChB,OAAO,CAAC,mBAAmB,CAA2B;IACtD,qFAAqF;IACrF,OAAO,CAAC,cAAc,CAAqB;IAC3C,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAS;IACzB,wEAAwE;IACxE,OAAO,CAAC,kBAAkB,CAAU;IACpC,mDAAmD;IACnD,aAAa,EAAE,OAAO,CAAS;IAC/B,6DAA6D;IAC7D,cAAc,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IACpC,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,oBAAoB,CAAa;IACzC,2DAA2D;IAC3D,OAAO,CAAC,YAAY,CAAc;IAElC,OAAO;IA+BP;;;;;;;;OAQG;IACH,IAAW,YAAY,2DAEtB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6EG;IACH,OAAc,WAAW,GAAI,CAAC,SAAS,QAAQ,EAC3C,YAAY,MAAM,KACnB,uBAAuB,CAcxB;IAEF;;;;;;;;;OASG;IACI,KAAK,aASV;IAEF,wEAAwE;IACxE,OAAO,CAAC,oBAAoB,CAsB1B;IAEF,wEAAwE;IACxE,OAAO,CAAC,gBAAgB,CAStB;IAEF,OAAO,CAAC,qBAAqB,CAiB3B;IAEF,8CAA8C;IAC9C,OAAO,CAAC,eAAe,CAUrB;IAEF;;;;;;OAMG;IACI,gBAAgB,aAerB;IAEF;;;;OAIG;IACI,iBAAiB,sBAiCtB;CACL;AAED;;;;;;GAMG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,CAO/D"}