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

package/dist/connector/discrete/discreteOrmSubscriptionHandler.js

@@ -0,0 +1,309 @@
+// 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;
+/**
+ * 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 class DiscreteOrmSubscription {
+    /** Global store of all subscriptions. We use that for pooling. */
+    static idToEntry = new Map();
+    /** The document ID (NURI) of the subscribed document. */
+    documentId;
+    _signalObject;
+    stopSignalListening;
+    /** The subscription ID kept as an identifier for communicating with the verifier. */
+    subscriptionId;
+    /** The number of OrmSubscriptions with the same shape and scope (for pooling). */
+    refCount;
+    /** When true, modifications from the signalObject are not processed. */
+    suspendDeepWatcher;
+    /** @readonly True, if a transaction is running. */
+    inTransaction = false;
+    /** Aggregation of patches to be sent when in transaction. */
+    pendingPatches;
+    /** **Await to ensure that the subscription is established and the data arrived.** */
+    readyPromise;
+    closeOrmSubscription;
+    /** Function to call once initial data has been applied. */
+    resolveReady;
+    constructor(documentId) {
+        // @ts-expect-error
+        window.ormDiscreteSignalConnections = DiscreteOrmSubscription.idToEntry;
+        // @ts-expect-error
+        window.OrmDiscreteConnection = DiscreteOrmSubscription;
+        // @ts-expect-error
+        window.OrmDiscreteIncomingPatches = [];
+        this.documentId = documentId;
+        this.refCount = 1;
+        this.closeOrmSubscription = () => { };
+        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.closeOrmSubscription = await ng.orm_start_discrete(documentId, session.session_id, this.onBackendMessage);
+            }
+            catch (e) {
+                console.error(e);
+            }
+        });
+    }
+    /**
+     * 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() {
+        return this._signalObject;
+    }
+    /**
+     * 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 = (documentId) => {
+        // If we already have a connection open,
+        // return that signal object and just increase the reference count.
+        // Otherwise, open a new one.
+        const existingConnection = DiscreteOrmSubscription.idToEntry.get(documentId);
+        if (existingConnection) {
+            existingConnection.refCount += 1;
+            return existingConnection;
+        }
+        else {
+            const newConnection = new DiscreteOrmSubscription(documentId);
+            DiscreteOrmSubscription.idToEntry.set(documentId, newConnection);
+            return newConnection;
+        }
+    };
+    /**
+     * 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 = () => {
+        setTimeout(() => {
+            if (this.refCount > 0)
+                this.refCount--;
+            if (this.refCount === 0) {
+                DiscreteOrmSubscription.idToEntry.delete(this.documentId);
+                this.closeOrmSubscription();
+            }
+        }, WAIT_BEFORE_CLOSE);
+    };
+    /** Handle updates (patches) coming from signal object modifications. */
+    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);
+    };
+    /** Handle messages coming from the engine (initial data or patches). */
+    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();
+    };
+    /** Handle incoming patches from the engine */
+    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;
+        });
+    };
+    /**
+     * 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 = () => {
+        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;
+        });
+    };
+    /**
+     * Commits a transactions sending all modifications made during the transaction
+     * (started with `beginTransaction`) to the database.
+     * @throws if no transaction is open.
+     */
+    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
+ *
+ * @ignore
+ */
+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,11 @@
+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;;;;;;GAMG;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,26 @@
+// 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 { OrmSubscription } from "./ormSubscriptionHandler.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 = OrmSubscription.getOrCreate(shapeType, scope);
+    await connection.readyPromise;
+    setTimeout(() => {
+        connection.close();
+    }, 1_000);
+    return deepClone(connection.signalObject);
+}

package/dist/connector/initNg.d.ts

@@ -1,14 +1,45 @@
 import * as NG from "@ng-org/lib-wasm";
-type Session = {
+export type Session = {
     session_id: string | number;
     protected_store_id: string;
     private_store_id: string;
     public_store_id: string;
+    ng: typeof NG;
+    [key: string]: unknown;
 };
+/** Resolves to the NG session and the ng implementation. */
 export declare const ngSession: Promise<{
     ng: typeof NG;
     session: Session;
 }>;
+/**
+ * Initialize the ORM by passing the ng implementation and session.
+ *
+ * **This is the first thing you need to to before using the ORM.**
+ *
+ * @param ngImpl The NextGraph API, e.g. exported from `@ng-org/web`.
+ * @param session The established NextGraph session.
+ *
+ * @example
+ * ```typescript
+ * import { ng, init } from "@ng-org/web";
+ * import { initNg as initNgSignals, Session } from "@ng-org/orm";
+ * let session: Session;
+ *
+ * // Call as early as possible as it will redirect to the auth page.
+ * await init(
+ *     async (event: any) => {
+ *         session = event.session;
+ *         session!.ng ??= ng;
+ *
+ *         // Call initNgSignals
+ *         initNgSignals(ng, session);
+ *     },
+ *     true,
+ *     []
+ * );
+ * ```
+ *
+ */
 export declare function initNgSignals(ngImpl: typeof NG, session: Session): void;
-export {};
 //# sourceMappingURL=initNg.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"initNg.d.ts","sourceRoot":"","sources":["../../src/connector/initNg.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEvC,KAAK,OAAO,GAAG;IACX,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CAC3B,CAAC;AAIF,eAAO,MAAM,SAAS;QAAqB,OAAO,EAAE;aAAW,OAAO;EAIrE,CAAC;AAEF,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,QAEhE"}
+{"version":3,"file":"initNg.d.ts","sourceRoot":"","sources":["../../src/connector/initNg.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEvC,MAAM,MAAM,OAAO,GAAG;IAClB,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B,CAAC;AAIF,4DAA4D;AAC5D,eAAO,MAAM,SAAS;QAAqB,OAAO,EAAE;aAAW,OAAO;EAIrE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,QAEhE"}

package/dist/connector/initNg.js

@@ -8,9 +8,39 @@
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 let resolveNgSession;
+/** Resolves to the NG session and the ng implementation. */
 export const ngSession = new Promise((resolve) => {
     resolveNgSession = resolve;
 });
+/**
+ * Initialize the ORM by passing the ng implementation and session.
+ *
+ * **This is the first thing you need to to before using the ORM.**
+ *
+ * @param ngImpl The NextGraph API, e.g. exported from `@ng-org/web`.
+ * @param session The established NextGraph session.
+ *
+ * @example
+ * ```typescript
+ * import { ng, init } from "@ng-org/web";
+ * import { initNg as initNgSignals, Session } from "@ng-org/orm";
+ * let session: Session;
+ *
+ * // Call as early as possible as it will redirect to the auth page.
+ * await init(
+ *     async (event: any) => {
+ *         session = event.session;
+ *         session!.ng ??= ng;
+ *
+ *         // Call initNgSignals
+ *         initNgSignals(ng, session);
+ *     },
+ *     true,
+ *     []
+ * );
+ * ```
+ *
+ */
 export function initNgSignals(ngImpl, session) {
     resolveNgSession({ ng: ngImpl, session });
 }

package/dist/connector/insertObject.d.ts

@@ -0,0 +1,9 @@
+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;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,QAAQ,EACjD,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,CAAC,iBASZ"}

package/dist/connector/insertObject.js

@@ -0,0 +1,24 @@
+// 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 { OrmSubscription } from "./ormSubscriptionHandler.js";
+/**
+ * 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 async function insertObject(shapeType, object) {
+    const connection = OrmSubscription.getOrCreate(shapeType, {
+        graphs: [], // Subscribe to no documents
+    });
+    await connection.readyPromise;
+    connection.signalObject.add(object);
+    connection.close();
+}

package/dist/connector/ormSubscriptionHandler.d.ts

@@ -0,0 +1,167 @@
+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";
+/**
+ * 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 and follow the tutorial.
+ */
+export declare class OrmSubscription<T extends BaseType> {
+    /** Global store of all subscriptions. We use that for pooling. */
+    private static idToEntry;
+    /** The shape type that is subscribed to. */
+    readonly shapeType: ShapeType<T>;
+    /** The {@link Scope} of the subscription. */
+    readonly scope: Scope;
+    /**
+     * The signalObject containing all data matching the shape and scope
+     * (once subscription is established).
+     * The object is of type {@link DeepSignalSet} which
+     * to the outside behaves like a regular set but has a couple of
+     * additional features:
+     * - Modifications are immediately propagated back to the database.
+     * - Database changes are immediately reflected in the object.
+     * - `.getBy(graphIri, subjectIri)` utility for quicker access to objects in set.
+     * - `.first()` utility to get the first element added to the set.
+     * - the iterator utilities, e.g. `.map()`, `.filter()`, ...
+     * - Watch for object changes using {@link watchDeepSignal}.
+     */
+    readonly signalObject: DeepSignalSet<T>;
+    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;
+    /** Identifier as a combination of shape type and scope. Prevents duplications. */
+    private identifier;
+    /** When true, modifications from the signalObject are not processed. */
+    suspendDeepWatcher: boolean;
+    /** 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 static cleanupSignalRegistry;
+    private constructor();
+    /**
+     * Returns an OrmSubscription which subscribes to the given
+     * {@link ShapeType} and {@link Scope} in a 2-way binding.
+     *
+     * You **find the data** and objects matching the shape and scope
+     * in the **`signalObject`** once {@link readyPromise} resolves. This is a {@link DeepSignalSet} which
+     * to the outside behaves like a regular set but has a couple of
+     * additional features:
+     * - Modifications are propagated back to the database.
+     *   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.
+     * - Database changes are immediately reflected in the object.
+     * - `.getBy(graphIri, subjectIri)` utility for quicker access to objects in set.
+     * - `.first()` utility to get the first element added to the set.
+     * - the iterator utilities, e.g. `.map()`, `.filter()`, ...
+     * - Watch for object changes using {@link watchDeepSignal}.
+     *
+     * You can use **transactions**, to prevent excessive calls to the database
+     * 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 `close` was not called on it (or only shortly after),
+     * it will return the same OrmSubscription.
+     *
+     * @param shapeType The {@link ShapeType}
+     * @param scope The {@link Scope}. If no scope is given, the whole store is considered.
+     *
+     * @example
+     * ```typescript
+     * // We assume you have created a graph document already, as below.
+     * // const documentId = await ng.doc_create(
+     * //     session_id,
+     * //     "Graph",
+     * //     "data:graph",
+     * //     "store",
+     * //     undefined
+     * // );
+     * const subscription = OrmSubscription.getOrCreate(ExpenseShapeType, {graphs: [graphIri]});
+     * // Wait for data.
+     * await subscription.readyPromise;
+     *
+     * const expense = subscription.signalObject.first()
+     * expense.name = "updated name";
+     * expense.description = "updated description";
+     *
+     * // Await promise to run the below code in a new task.
+     * // That will push the changes to the database.
+     * await Promise.resolve();
+     *
+     * // Here, the expense modifications have been 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 frontend frameworks.
+     * const subscription2 = OrmSubscription.getOrCreate(ExpenseShapeType, {graphs: [graphIri]});
+     *
+     * subscription2.signalObject.add({
+     *    "@graph": graphIri,
+     *    "@id": "", // Leave empty to auto-assign one.
+     *    name": "A new expense",
+     *    description: "A new description"
+     * });
+     *
+     * subscription2.close()
+     * ```
+     */
+    static getOrCreate: <T_1 extends BaseType>(shapeType: ShapeType<T_1>, scope: Scope) => OrmSubscription<T_1>;
+    /**
+     * Stop the subscription.
+     *
+     * **If there is more than one subscription with the same shape type and scope
+     * the orm subscription will persist.**
+     *
+     * 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
+     * shape type and scope,  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;
+    /** Function to create random subject NURIs for newly created nested objects. */
+    private signalObjectPropGenerator;
+    /**
+     * 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.
+     */
+    beginTransaction: () => void;
+    /**
+     * Commits a transactions sending all modifications made during the transaction
+     * (started with `beginTransaction`) to the database.
+     */
+    commitTransaction: () => Promise<void>;
+}
+//# sourceMappingURL=ormSubscriptionHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ormSubscriptionHandler.d.ts","sourceRoot":"","sources":["../../src/connector/ormSubscriptionHandler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAkB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACzD,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;AAU5D;;;;;;;;;GASG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,QAAQ;IAC3C,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,SAAS,CAA2C;IAEnE,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,mBAAmB,CAAa;IACxC,qFAAqF;IACrF,OAAO,CAAC,cAAc,CAAqB;IAC3C,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAS;IACzB,kFAAkF;IAClF,OAAO,CAAC,UAAU,CAAS;IAC3B,wEAAwE;IACxE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,yCAAyC;IACzC,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;IAGlC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAUrB;IAEf,OAAO;IAqDP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2EG;IACH,OAAc,WAAW,GAAI,GAAC,SAAS,QAAQ,EAC3C,WAAW,SAAS,CAAC,GAAC,CAAC,EACvB,OAAO,KAAK,KACb,eAAe,CAAC,GAAC,CAAC,CAkBnB;IAEF;;;;;;;;;OASG;IACI,KAAK,aAYV;IAEF,wEAAwE;IACxE,OAAO,CAAC,oBAAoB,CAoB1B;IAEF,wEAAwE;IACxE,OAAO,CAAC,gBAAgB,CAStB;IAEF,OAAO,CAAC,qBAAqB,CAuB3B;IAEF,8CAA8C;IAC9C,OAAO,CAAC,eAAe,CAOrB;IAEF,gFAAgF;IAChF,OAAO,CAAC,yBAAyB,CAgD/B;IAEF;;;;;;OAMG;IACI,gBAAgB,aAarB;IAEF;;;OAGG;IACI,iBAAiB,sBAkCtB;CACL"}