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

package/dist/frontendAdapters/react/useDiscrete.js

@@ -8,96 +8,116 @@
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 import { useEffect, useMemo, useRef } from "react";
-import { DiscreteOrmConnection } from "../../connector/discrete/discreteOrmConnectionHandler.js";
+import { DiscreteOrmSubscription } from "../../connector/discrete/discreteOrmSubscriptionHandler.js";
 import { useDeepSignal } from "@ng-org/alien-deepsignals/react";
 const EMPTY_OBJECT = {};
 /**
- * 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 function useDiscrete(documentId) {
     const prevDocumentId = useRef(undefined);
-    const prevOrmConnection = useRef(undefined);
+    const prevOrmSubscription = useRef(undefined);
     const ormConnection = useMemo(() => {
         // Close previous connection if documentId changed.
-        if (prevOrmConnection.current &&
+        if (prevOrmSubscription.current &&
             prevDocumentId.current !== documentId) {
-            prevOrmConnection.current.close();
-            prevOrmConnection.current = undefined;
+            prevOrmSubscription.current.close();
+            prevOrmSubscription.current = undefined;
         }
         // If no documentId, return undefined.
         if (!documentId) {
@@ -105,23 +125,25 @@ export function useDiscrete(documentId) {
             return undefined;
         }
         // Create new connection only if needed.
-        if (!prevOrmConnection.current ||
+        if (!prevOrmSubscription.current ||
             prevDocumentId.current !== documentId) {
-            prevOrmConnection.current =
-                DiscreteOrmConnection.getOrCreate(documentId);
+            prevOrmSubscription.current =
+                DiscreteOrmSubscription.getOrCreate(documentId);
             prevDocumentId.current = documentId;
         }
-        return prevOrmConnection.current;
+        return prevOrmSubscription.current;
     }, [documentId]);
     useEffect(() => {
         return () => {
-            prevOrmConnection.current?.close();
+            prevOrmSubscription.current?.close();
         };
     }, []);
     // useDeepSignal requires an object, so pass empty object when no connection.
     const signalSource = ormConnection?.signalObject ?? EMPTY_OBJECT;
-    const state = useDeepSignal(signalSource);
+    const deepSignalValue = useDeepSignal(signalSource);
     // Only return data if we have a valid connection with a signal object.
-    const data = ormConnection?.signalObject ? state : undefined;
-    return { data };
+    const dataOrUndefined = ormConnection?.signalObject
+        ? deepSignalValue
+        : undefined;
+    return { doc: dataOrUndefined };
 }

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

@@ -1,72 +1,72 @@
 import type { BaseType } from "@ng-org/shex-orm";
 import type { ShapeType } from "@ng-org/shex-orm";
-import type { Scope } from "../../types.ts";
+import { type Scope } from "../../types.ts";
 import { DeepSignalSet } from "@ng-org/alien-deepsignals";
 /**
  * Hook to subscribe to RDF data in the graph database using a shape, see {@link ShapeType}.
  *
  * Returns a {@link DeepSignalSet} of objects matching the shape and that are within the scope.
  * 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.
  *
  * @param shape The {@link ShapeType} the objects should have (generated by the shex-orm tool).
- * @param scope The {@link Scope} as graph, array of graphs or scope object with graphs and subjects.
- * @returns A deep {@link DeepSignalSet} with the orm objects or an empty set, if still loading.\
+ * @param scope The {@link Scope} as graph string or scope object with graphs and subjects.
+ * @returns A {@link DeepSignalSet} with the orm objects or an empty set, if still loading.\
  *          If the scope is explicitly set to `undefined`, an empty set is returned which errors
  *          if you try to make modifications on it.
  *
  * @example
- ```tsx
-function Expenses() {
-    const expenses = useShape(ExpenseShapeType, {graphs: ["<graph IRI>"]});
-
-    const createExpense = useCallback(
-        () => {
-            expenses.add({
-                "@graph": `<graph IRI>`,
-                "@type": "http://example.org/Expense",
-                "@id": "", // Assigns id automatically, if set to "".
-                title: "New expense",
-                dateOfPurchase: obj.dateOfPurchase ?? new Date().toISOString(),
-            });
-        },
-        [expenses]
-    );
-
-    const expensesSorted = [...expenses].sort((a, b) =>
-        a.dateOfPurchase.localeCompare(b.dateOfPurchase)
-    );
-
-    // Not that if you use `@id` (the subject IRI) as key, you need to ensure that it is unique within your scope.
-    // If it is not, use the combination of `@graph` and `@id`.
-    
-    return (
-        <div>
-            <button
-                onClick={() => createExpense({})}
-            >
-                + Add expense
-            </button>
-            <div>
-                {expensesSorted.length === 0 ? (
-                    <p>
-                        No expenses yet.
-                    </p>
-                ) : (
-                    expensesSorted.map((expense) => (
-                        <ExpenseCard
-                            key={expense["@id"]}
-                            expense={expense}
-                            availableCategories={expenseCategories}
-                        />
-                    ))
-                )}
-            </div>
-        </div>
-    );
-}
-```
+ * ```tsx
+ * function Expenses() {
+ *     const expenses = useShape(ExpenseShapeType, {graphs: ["<graph IRI>"]});
+ *
+ *     const createExpense = useCallback(
+ *         () => {
+ *             expenses.add({
+ *                 "@graph": `<graph IRI>`,
+ *                 "@type": "http://example.org/Expense",
+ *                 "@id": "", // Assigns id automatically, if set to "".
+ *                 title: "New expense",
+ *                 dateOfPurchase: obj.dateOfPurchase ?? new Date().toISOString(),
+ *             });
+ *         },
+ *         [expenses]
+ *     );
+ *
+ *     const expensesSorted = [...expenses].sort((a, b) =>
+ *         a.dateOfPurchase.localeCompare(b.dateOfPurchase)
+ *     );
+ *
+ *     // Note that if you use `@id` (the subject IRI) as key, you need to ensure that it is unique within your scope.
+ *     // If it is not, use the combination of `@graph` and `@id`.
+ *
+ *     return (
+ *         <div>
+ *             <button
+ *                 onClick={() => createExpense({})}
+ *             >
+ *                 + Add expense
+ *             </button>
+ *             <div>
+ *                 {expensesSorted.length === 0 ? (
+ *                     <p>
+ *                         No expenses yet.
+ *                     </p>
+ *                 ) : (
+ *                     expensesSorted.map((expense) => (
+ *                         <ExpenseCard
+ *                             key={expense["@id"]}
+ *                             expense={expense}
+ *                             availableCategories={expenseCategories}
+ *                         />
+ *                     ))
+ *                 )}
+ *             </div>
+ *         </div>
+ *     );
+ * }
+ * ```
  */
-declare const useShape: <T extends BaseType>(shape: ShapeType<T>, scope?: Scope | string[] | string) => DeepSignalSet<T>;
+declare const useShape: <T extends BaseType>(shape: ShapeType<T>, scope: Scope | string | undefined) => DeepSignalSet<T>;
 export default useShape;
 //# sourceMappingURL=useShape.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useShape.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/react/useShape.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,QAAA,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAChC,OAAO,SAAS,CAAC,CAAC,CAAC,EACnB,QAAO,KAAK,GAAG,MAAM,EAAE,GAAG,MAAW,KA6BrB,aAAa,CAAC,CAAC,CAClC,CAAC;AAiBF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"useShape.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/react/useShape.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAkB,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,QAAA,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAChC,OAAO,SAAS,CAAC,CAAC,CAAC,EACnB,OAAO,KAAK,GAAG,MAAM,GAAG,SAAS,KA8BjB,aAAa,CAAC,CAAC,CAClC,CAAC;AAiBF,eAAe,QAAQ,CAAC"}

package/dist/frontendAdapters/react/useShape.js

@@ -9,96 +9,94 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 import { useDeepSignal } from "@ng-org/alien-deepsignals/react";
 import { useEffect, useMemo, useRef } from "react";
-import { OrmConnection } from "../../connector/ormConnectionHandler.js";
+import { normalizeScope } from "../../types.js";
+import { OrmSubscription } from "../../connector/ormSubscriptionHandler.js";
 /**
  * Hook to subscribe to RDF data in the graph database using a shape, see {@link ShapeType}.
  *
  * Returns a {@link DeepSignalSet} of objects matching the shape and that are within the scope.
  * 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.
  *
  * @param shape The {@link ShapeType} the objects should have (generated by the shex-orm tool).
- * @param scope The {@link Scope} as graph, array of graphs or scope object with graphs and subjects.
- * @returns A deep {@link DeepSignalSet} with the orm objects or an empty set, if still loading.\
+ * @param scope The {@link Scope} as graph string or scope object with graphs and subjects.
+ * @returns A {@link DeepSignalSet} with the orm objects or an empty set, if still loading.\
  *          If the scope is explicitly set to `undefined`, an empty set is returned which errors
  *          if you try to make modifications on it.
  *
  * @example
- ```tsx
-function Expenses() {
-    const expenses = useShape(ExpenseShapeType, {graphs: ["<graph IRI>"]});
-
-    const createExpense = useCallback(
-        () => {
-            expenses.add({
-                "@graph": `<graph IRI>`,
-                "@type": "http://example.org/Expense",
-                "@id": "", // Assigns id automatically, if set to "".
-                title: "New expense",
-                dateOfPurchase: obj.dateOfPurchase ?? new Date().toISOString(),
-            });
-        },
-        [expenses]
-    );
-
-    const expensesSorted = [...expenses].sort((a, b) =>
-        a.dateOfPurchase.localeCompare(b.dateOfPurchase)
-    );
-
-    // Not that if you use `@id` (the subject IRI) as key, you need to ensure that it is unique within your scope.
-    // If it is not, use the combination of `@graph` and `@id`.
-    
-    return (
-        <div>
-            <button
-                onClick={() => createExpense({})}
-            >
-                + Add expense
-            </button>
-            <div>
-                {expensesSorted.length === 0 ? (
-                    <p>
-                        No expenses yet.
-                    </p>
-                ) : (
-                    expensesSorted.map((expense) => (
-                        <ExpenseCard
-                            key={expense["@id"]}
-                            expense={expense}
-                            availableCategories={expenseCategories}
-                        />
-                    ))
-                )}
-            </div>
-        </div>
-    );
-}
-```
+ * ```tsx
+ * function Expenses() {
+ *     const expenses = useShape(ExpenseShapeType, {graphs: ["<graph IRI>"]});
+ *
+ *     const createExpense = useCallback(
+ *         () => {
+ *             expenses.add({
+ *                 "@graph": `<graph IRI>`,
+ *                 "@type": "http://example.org/Expense",
+ *                 "@id": "", // Assigns id automatically, if set to "".
+ *                 title: "New expense",
+ *                 dateOfPurchase: obj.dateOfPurchase ?? new Date().toISOString(),
+ *             });
+ *         },
+ *         [expenses]
+ *     );
+ *
+ *     const expensesSorted = [...expenses].sort((a, b) =>
+ *         a.dateOfPurchase.localeCompare(b.dateOfPurchase)
+ *     );
+ *
+ *     // Note that if you use `@id` (the subject IRI) as key, you need to ensure that it is unique within your scope.
+ *     // If it is not, use the combination of `@graph` and `@id`.
+ *
+ *     return (
+ *         <div>
+ *             <button
+ *                 onClick={() => createExpense({})}
+ *             >
+ *                 + Add expense
+ *             </button>
+ *             <div>
+ *                 {expensesSorted.length === 0 ? (
+ *                     <p>
+ *                         No expenses yet.
+ *                     </p>
+ *                 ) : (
+ *                     expensesSorted.map((expense) => (
+ *                         <ExpenseCard
+ *                             key={expense["@id"]}
+ *                             expense={expense}
+ *                             availableCategories={expenseCategories}
+ *                         />
+ *                     ))
+ *                 )}
+ *             </div>
+ *         </div>
+ *     );
+ * }
+ * ```
  */
-const useShape = (shape, scope = {}) => {
-    const parsedScope = typeof scope === "string"
-        ? { graphs: [scope] }
-        : Array.isArray(scope)
-            ? { graphs: scope }
-            : scope;
-    const prevOrmConnection = useRef(undefined);
-    const ormConnection = useMemo(() => {
-        if (scope === undefined)
+const useShape = (shape, scope) => {
+    const parsedScope = !scope ? undefined : normalizeScope(scope);
+    const prevOrmSubscription = useRef(undefined);
+    const ormSubscription = useMemo(() => {
+        if (parsedScope === undefined)
             return undefined;
-        if (prevOrmConnection.current)
-            prevOrmConnection.current.close();
-        const newOrmConnection = OrmConnection.getOrCreate(shape, parsedScope);
-        prevOrmConnection.current = newOrmConnection;
-        return newOrmConnection;
-    }, [shape, scope, parsedScope.graphs, parsedScope.subjects]);
+        if (prevOrmSubscription.current)
+            prevOrmSubscription.current.close();
+        // TODO: Add flag to indicate that we want branch replacement of proxies on nested changes.
+        const newOrmSubscription = OrmSubscription.getOrCreate(shape, parsedScope);
+        prevOrmSubscription.current = newOrmSubscription;
+        return newOrmSubscription;
+    }, [shape, scope, parsedScope?.graphs, parsedScope?.subjects]);
     useEffect(() => {
-        if (!ormConnection)
+        if (!ormSubscription)
             return;
         return () => {
-            ormConnection.close();
+            ormSubscription.close();
         };
-    }, [ormConnection]);
-    const state = useDeepSignal(ormConnection?.signalObject ?? readOnlySet);
+    }, [ormSubscription]);
+    const state = useDeepSignal(ormSubscription?.signalObject ?? readOnlySet);
     return state;
 };
 const readOnlySet = new Proxy(new Set(), {