@ng-org/orm 0.1.2-alpha.7 → 0.1.2-alpha.9

package/dist/connector/{ormConnectionHandler.js → ormSubscriptionHandler.js}

@@ -7,35 +7,67 @@
 // notice may not be copied, modified, or distributed except
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
+import { normalizeScope } from "../types.js";
 import { applyPatchesToDeepSignal } from "./applyPatches.js";
 import { ngSession } from "./initNg.js";
 import { deepSignal, watch as watchDeepSignal, batch, } from "@ng-org/alien-deepsignals";
 import { deepPatchesToWasm } from "./utils.js";
+/**
+ * Delay in ms to wait before closing subscription.\
+ * Useful when a hook unsubscribes and resubscribes in a short time interval
+ * so that no new subscriptions need to be set up.
+ */
 const WAIT_BEFORE_CLOSE = 500;
-export class OrmConnection {
+/**
+ * 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 class OrmSubscription {
+    /** Global store of all subscriptions. We use that for pooling. */
     static idToEntry = new Map();
-    /**
-     * 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.
-     */
+    /** The shape type that is subscribed to. */
     shapeType;
+    /** The {@link Scope} of the subscription. */
     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}.
+     */
     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;
     /** Identifier as a combination of shape type and scope. Prevents duplications. */
     identifier;
+    /** When true, modifications from the signalObject are not processed. */
     suspendDeepWatcher;
+    /** 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;
-    closeOrmConnection;
-    /** Promise that resolves once initial data has been applied. */
+    closeOrmSubscription;
+    /** Function to call once initial data has been applied. */
     resolveReady;
-    // FinalizationRegistry to clean up connections when signal objects are GC'd.
+    // FinalizationRegistry to clean up subscriptions when signal objects are GC'd.
     static cleanupSignalRegistry = typeof FinalizationRegistry === "function"
         ? new FinalizationRegistry((connectionId) => {
             console.log("finalization called for", connectionId);
@@ -49,32 +81,33 @@ export class OrmConnection {
         : null;
     constructor(shapeType, scope) {
         // @ts-expect-error
-        window.ormSignalConnections = OrmConnection.idToEntry;
+        window.ormSignalConnections = OrmSubscription.idToEntry;
         // @ts-expect-error
-        window.OrmConnection = OrmConnection;
+        window.OrmSubscription = OrmSubscription;
         this.shapeType = shapeType;
-        this.scope = scope;
+        const normalizedScope = normalizeScope(scope);
+        this.scope = normalizedScope;
         this.refCount = 1;
-        this.closeOrmConnection = () => { };
+        this.closeOrmSubscription = () => { };
         this.suspendDeepWatcher = false;
-        this.identifier = `${shapeType.shape}|${canonicalScope(scope)}`;
+        this.identifier = `${shapeType.shape}|${canonicalScope(normalizedScope)}`;
         this.signalObject = deepSignal(new Set(), {
             propGenerator: this.signalObjectPropGenerator,
             // Don't set syntheticIdPropertyName - let propGenerator handle all ID logic
             readOnlyProps: ["@id", "@graph"],
         });
         // Schedule cleanup of the connection when the signal object is GC'd.
-        OrmConnection.cleanupSignalRegistry?.register(this.signalObject, this.identifier, this.signalObject);
+        OrmSubscription.cleanupSignalRegistry?.register(this.signalObject, this.identifier, this.signalObject);
         // Add listener to deep signal object to report changes back to wasm land.
         const { stopListening } = watchDeepSignal(this.signalObject, this.onSignalObjectUpdate);
         this.stopSignalListening = stopListening;
-        // Initialize per-entry readiness promise that resolves in setUpConnection
+        // Set promise to be resolved when data arrived from engine.
         this.readyPromise = new Promise((resolve) => {
             this.resolveReady = resolve;
         });
         ngSession.then(async ({ ng, session }) => {
             try {
-                this.closeOrmConnection = await ng.orm_start_graph(scope.graphs ?? ["did:ng:i"], scope.subjects ?? [], shapeType, session.session_id, this.onBackendMessage);
+                this.closeOrmSubscription = await ng.orm_start_graph(normalizedScope.graphs, normalizedScope.subjects, shapeType, session.session_id, this.onBackendMessage);
             }
             catch (e) {
                 console.error(e);
@@ -82,11 +115,79 @@ export class OrmConnection {
         });
     }
     /**
-     * Get or create a connection which contains the ORM and lifecycle methods.
-     * @param shapeType
-     * @param scope
-     * @param ng
-     * @returns
+     * 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 = (shapeType, scope) => {
         const scopeKey = canonicalScope(scope);
@@ -95,28 +196,39 @@ export class OrmConnection {
         // If we already have an object for this shape+scope,
         // return it and just increase the reference count.
         // Otherwise, create new one.
-        const existingConnection = OrmConnection.idToEntry.get(identifier);
+        const existingConnection = OrmSubscription.idToEntry.get(identifier);
         if (existingConnection) {
             existingConnection.refCount += 1;
             return existingConnection;
         }
         else {
-            const newConnection = new OrmConnection(shapeType, scope);
-            OrmConnection.idToEntry.set(identifier, newConnection);
+            const newConnection = new OrmSubscription(shapeType, scope);
+            OrmSubscription.idToEntry.set(identifier, newConnection);
             return newConnection;
         }
     };
+    /**
+     * 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 mound a component again with the same
+     * shape type and scope, no new orm subscription has be set up with the engine.
+     */
     close = () => {
         setTimeout(() => {
             if (this.refCount > 0)
                 this.refCount--;
             if (this.refCount === 0) {
-                OrmConnection.idToEntry.delete(this.identifier);
-                OrmConnection.cleanupSignalRegistry?.unregister(this.signalObject);
-                this.closeOrmConnection();
+                OrmSubscription.idToEntry.delete(this.identifier);
+                OrmSubscription.cleanupSignalRegistry?.unregister(this.signalObject);
+                this.closeOrmSubscription();
             }
         }, WAIT_BEFORE_CLOSE);
     };
+    /** Handle updates (patches) coming from signal object modifications. */
     onSignalObjectUpdate = async ({ patches }) => {
         if (this.suspendDeepWatcher || !patches.length)
             return;
@@ -131,6 +243,7 @@ export class OrmConnection {
         await this.readyPromise;
         ng.graph_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?.GraphOrmInitial) {
@@ -140,7 +253,7 @@ export class OrmConnection {
             this.onBackendUpdate(data.GraphOrmUpdate);
         }
         else {
-            console.warn("Received unknown ORM message from backend", message);
+            console.warn("Received unknown ORM message from engine", message);
         }
     };
     handleInitialResponse = ([initialData, subscriptionId]) => {
@@ -162,6 +275,7 @@ export class OrmConnection {
             this.resolveReady();
         });
     };
+    /** Handle incoming patches from the engine */
     onBackendUpdate = (patches) => {
         this.suspendDeepWatcher = true;
         applyPatchesToDeepSignal(this.signalObject, patches, "set");
@@ -212,6 +326,13 @@ export class OrmConnection {
             syntheticId: graphIri + "|" + subjectIri,
         };
     };
+    /**
+     * 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 = () => {
         this.inTransaction = true;
         this.pendingPatches = [];
@@ -221,6 +342,10 @@ export class OrmConnection {
         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.
+     */
     commitTransaction = async () => {
         if (!this.inTransaction) {
             throw new Error("No transaction is open. Call `beginTransaction` first.");
@@ -229,16 +354,16 @@ export class OrmConnection {
         await this.readyPromise;
         this.inTransaction = false;
         if (this.pendingPatches?.length == 0) {
-            // Nothing to send to the backend.
+            // Nothing to send to the engine.
         }
         else {
-            // Send patches to backend.
+            // Send patches to engine.
             await ng.graph_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 way we prevent excessive calls to the engine.
         this.stopSignalListening();
         const { stopListening } = watchDeepSignal(this.signalObject, this.onSignalObjectUpdate);
         this.stopSignalListening = stopListening;

package/dist/frontendAdapters/react/useDiscrete.d.ts

@@ -1,84 +1,104 @@
 import { DeepSignal } from "@ng-org/alien-deepsignals";
 import { DiscreteArray, DiscreteObject } from "../../types.ts";
 /**
- * Hook to subscribe to discrete (JSON) CRDT documents.
+ * Hook to subscribe to an existing discrete (JSON) CRDT document.
  * You can modify the returned object like any other JSON object. Changes are immediately
- * reflected in the CRDT.
+ * reflected in the CRDT document.
  *
  * Establishes a 2-way binding: Modifications to the object are immediately committed,
- * changes coming from the backend (or other components) cause an immediate rerender.
+ * changes coming from the engine (or other components) cause an immediate rerender.
  *
- * In comparison to {@link useShape}, discrete CRDTs are untyped.
+ * In comparison to {@link reactUseShape}, discrete CRDTs are untyped.
  * You can put any JSON data inside and need to validate the schema yourself.
  *
- * @param documentId The IRI of the crdt document.
+ * @param documentId The IRI of the CRDT document.
  * @returns An object that contains as `data` the reactive DeepSignal object or undefined if `documentId` is undefined.
  *
- *@example
-```tsx
-// 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
-// );
-
-function Expenses({documentId}: {documentId: string}) {
-    const { data } = useDiscrete(documentIdPromise);
-
-    // If the CRDT document is still empty, we need to initialize it.
-    if (data && !data.expenses) {
-        data.expenses = [];
-    }
-    const expenses = data?.expenses;
-
-    const createExpense = useCallback(() => {
-            expenses.add({
-                title: "New expense",
-                dateOfPurchase: obj.dateOfPurchase ?? new Date().toISOString(),
-            });
-        },
-        [expenses]
-    );
-
-    // Loaded already?
-    if (!expenses) return <div>Loading...</div>;
-
-    // Note that we use expense["@id"] as a key in the expense list.
-    // Every object added to a CRDT array gets a stable `@id` property assigned
-    // which you can use for referencing objects in arrays even as
-    // objects are removed from the array. The ID is an IRI with the schema `<documentId>:d:<object-specific id>`.
-    // Since the `@id` is generated in the backend, the object is preliminarily
-    // given a mock id which will be replaced immediately
-
-    return (
-        <div>
-            <button
-                onClick={() => createExpense()}
-            >
-                + Add expense
-            </button>
-            <div>
-                {expenses.length === 0 ? (
-                    <p>
-                        No expenses yet.
-                    </p>
-                ) : (
-                    expenses.map((expense) => (
-                        <ExpenseCard
-                            key={expense["@id"]}
-                            expense={expense}
-                        />
-                    ))
-                )}
-            </div>
-        </div>
-    );
-}
+ * @example
+ * ```tsx
+ * // 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
+ * // );
+ *
+ * function Expenses({documentId}: {documentId: string}) {
+ *     const { data } = useDiscrete(documentId);
+ *
+ *     // If the CRDT document is still empty, we need to initialize it.
+ *     if (data && !data.expenses) {
+ *         data.expenses = [];
+ *     }
+ *     const expenses = data?.expenses;
+ *
+ *     const createExpense = useCallback(() => {
+ *             // Note that we use *expense["@id"]* as a key in the expense list.
+ *             // Every object added to a CRDT array gets a stable `@id` property assigned
+ *             // which you can use for referencing objects in arrays even as
+ *             // objects are removed or added from the array.
+ *             // The `@id` is an IRI with the schema `<documentId>:d:<object-specific id>`.
+ *             // Since the `@id` is generated in the engine, the object is
+ *             // *preliminarily given a mock id* which will be replaced immediately.
+ *             expenses.push({
+ *                 title: "New expense",
+ *                 date: new Date().toISOString(),
+ *             });
+ *         },
+ *         [expenses]
+ *     );
+ *
+ *     // Still loading (data undefined)?
+ *     if (!data) return <div>Loading...</div>;
+ *
+ *     return (
+ *         <div>
+ *             <button
+ *                 onClick={() => createExpense()}
+ *             >
+ *                 + Add expense
+ *             </button>
+ *             <div>
+ *                 {expenses.length === 0 ? (
+ *                     <p>
+ *                         No expenses yet.
+ *                     </p>
+ *                 ) : (
+ *                     expenses.map((expense) => (
+ *                         <ExpenseCard
+ *                             key={expense["@id"]}
+ *                             expense={expense}
+ *                         />
+ *                     ))
+ *                 )}
+ *             </div>
+ *         </div>
+ *     );
+ * }
+ * ```
+ *
+ * ---
+ * In the ExpenseCard component:
+ * ```tsx
+ * function ExpenseCard({expense}: {expense: Expense}) {
+ *    return (
+ *        <input
+ *            value={expense.title}
+ *            onChange={(e) => {
+ *                expense.title = e.target.value; // Changes trigger rerender.
+ *            }}
+ *        />
+ *        <div>
+ *            <p>Date</p>
+ *            <p>{expense.data}
+ *        </div
+ *    );
+ * }
+ * ```
  */
 export declare function useDiscrete(documentId: string | undefined): {
-    data: DeepSignal<DiscreteArray | DiscreteObject> | undefined;
+    doc: DeepSignal<DiscreteArray | DiscreteObject> | undefined;
 };
 //# sourceMappingURL=useDiscrete.d.ts.map

package/dist/frontendAdapters/react/useDiscrete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDiscrete.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/react/useDiscrete.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AAEH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;;EAmDzD"}
+{"version":3,"file":"useDiscrete.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/react/useDiscrete.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;;EAqDzD"}