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

package/dist/frontendAdapters/react/useDiscrete.js

@@ -0,0 +1,151 @@
+// Copyright (c) 2026 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 { useEffect, useMemo, useRef } from "react";
+import { DiscreteOrmSubscription } from "../../connector/discrete/discreteOrmSubscriptionHandler.js";
+import { useDeepSignal } from "@ng-org/alien-deepsignals/react";
+const EMPTY_OBJECT = {};
+/**
+ * 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 document.
+ *
+ * Establishes a 2-way binding: Modifications to the object are immediately committed;
+ * changes coming from the engine (or other components) cause an immediate rerender.
+ *
+ * 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 NURI of the CRDT document.
+ * @returns An object that contains as `doc` 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 { doc } = useDiscrete(documentId);
+ *
+ *     // If the CRDT document is still empty, we need to initialize it.
+ *     if (doc && !doc.expenses) {
+ *         doc.expenses = [];
+ *     }
+ *     const expenses = doc?.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 a NURI 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?
+ *     if (!doc) 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.doc}
+ *        </div
+ *    );
+ * }
+ * ```
+ */
+export function useDiscrete(documentId) {
+    const prevDocumentId = useRef(undefined);
+    const prevOrmSubscription = useRef(undefined);
+    const ormConnection = useMemo(() => {
+        // Close previous connection if documentId changed.
+        if (prevOrmSubscription.current &&
+            prevDocumentId.current !== documentId) {
+            prevOrmSubscription.current.close();
+            prevOrmSubscription.current = undefined;
+        }
+        // If no documentId, return undefined.
+        if (!documentId) {
+            prevDocumentId.current = undefined;
+            return undefined;
+        }
+        // Create new connection only if needed.
+        if (!prevOrmSubscription.current ||
+            prevDocumentId.current !== documentId) {
+            prevOrmSubscription.current =
+                DiscreteOrmSubscription.getOrCreate(documentId);
+            prevDocumentId.current = documentId;
+        }
+        return prevOrmSubscription.current;
+    }, [documentId]);
+    useEffect(() => {
+        return () => {
+            prevOrmSubscription.current?.close();
+        };
+    }, []);
+    // useDeepSignal requires an object, so pass empty object when no connection.
+    const signalSource = ormConnection?.signalObject ?? EMPTY_OBJECT;
+    const deepSignalValue = useDeepSignal(signalSource, {
+        replaceProxiesInBranchOnChange: true,
+    });
+    // Only return doc if we have a valid connection with a signal object.
+    const docOrUndefined = ormConnection?.signalObject
+        ? deepSignalValue
+        : undefined;
+    return { doc: docOrUndefined };
+}

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

@@ -1,6 +1,73 @@
 import type { BaseType } from "@ng-org/shex-orm";
 import type { ShapeType } from "@ng-org/shex-orm";
-import type { Scope } from "../../types.ts";
-declare const useShape: <T extends BaseType>(shape: ShapeType<T>, scope?: Scope) => import("@ng-org/alien-deepsignals").DeepSignalSet<T>;
+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 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 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: DeepSignal<Set<Expense>> = useShape(ExpenseShapeType, {graphs: ["<graph NURI>"]});
+ *
+ *     const createExpense = useCallback(
+ *         () => {
+ *             expenses.add({
+ *                 "@graph": `<graph NURI>`,
+ *                 "@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 (i.e. there are two graphs with the same subject), 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) => (
+ *                         // You can modify the expense's properties in the ExpenseCard component
+ *                         // which will instantly trigger a rerender.
+ *                         <ExpenseCard
+ *                             key={expense["@id"]}
+ *                             expense={expense}
+ *                         />
+ *                     ))
+ *                 )}
+ *             </div>
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+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;AAGlD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,QAAA,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAChC,OAAO,SAAS,CAAC,CAAC,CAAC,EACnB,QAAO,KAAU,yDAcpB,CAAC;AAEF,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;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,QAAA,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAChC,OAAO,SAAS,CAAC,CAAC,CAAC,EACnB,OAAO,KAAK,GAAG,MAAM,GAAG,SAAS,KAgCjB,aAAa,CAAC,CAAC,CAClC,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/frontendAdapters/react/useShape.js

@@ -8,17 +8,98 @@
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 import { useDeepSignal } from "@ng-org/alien-deepsignals/react";
-import { useEffect, useRef } from "react";
-import { createSignalObjectForShape } from "../../connector/createSignalObjectForShape.js";
-const useShape = (shape, scope = "") => {
-    const handleRef = useRef(createSignalObjectForShape(shape, scope));
-    const handle = handleRef.current;
-    const state = useDeepSignal(handle.signalObject);
+import { useEffect, useMemo, useRef } from "react";
+import { normalizeScope } from "../../types.js";
+import { OrmSubscription } from "../../connector/ormSubscriptionHandler.js";
+import { readOnlySet } from "../utils.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 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 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: DeepSignal<Set<Expense>> = useShape(ExpenseShapeType, {graphs: ["<graph NURI>"]});
+ *
+ *     const createExpense = useCallback(
+ *         () => {
+ *             expenses.add({
+ *                 "@graph": `<graph NURI>`,
+ *                 "@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 (i.e. there are two graphs with the same subject), 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) => (
+ *                         // You can modify the expense's properties in the ExpenseCard component
+ *                         // which will instantly trigger a rerender.
+ *                         <ExpenseCard
+ *                             key={expense["@id"]}
+ *                             expense={expense}
+ *                         />
+ *                     ))
+ *                 )}
+ *             </div>
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+const useShape = (shape, scope) => {
+    const parsedScope = !scope ? undefined : normalizeScope(scope);
+    const prevOrmSubscription = useRef(undefined);
+    const ormSubscription = useMemo(() => {
+        if (parsedScope === undefined)
+            return undefined;
+        if (prevOrmSubscription.current)
+            prevOrmSubscription.current.close();
+        const newOrmSubscription = OrmSubscription.getOrCreate(shape, parsedScope);
+        prevOrmSubscription.current = newOrmSubscription;
+        return newOrmSubscription;
+    }, [shape, scope, parsedScope?.graphs, parsedScope?.subjects]);
     useEffect(() => {
+        if (!ormSubscription)
+            return;
         return () => {
-            handleRef.current.stop();
+            ormSubscription.close();
         };
-    }, [shape, scope]);
+    }, [ormSubscription]);
+    const state = useDeepSignal(ormSubscription?.signalObject ?? readOnlySet, {
+        replaceProxiesInBranchOnChange: true,
+    });
     return state;
 };
 export default useShape;

package/dist/frontendAdapters/svelte/index.d.ts

@@ -1,3 +1,4 @@
 import useShape from "./useShape.svelte.ts";
-export { useShape };
+import { useDiscrete } from "./useDiscrete.svelte.ts";
+export { useShape, useDiscrete };
 //# sourceMappingURL=index.d.ts.map

package/dist/frontendAdapters/svelte/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/svelte/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/svelte/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC"}

package/dist/frontendAdapters/svelte/index.js

@@ -1,2 +1,3 @@
 import useShape from "./useShape.svelte.js";
-export { useShape };
+import { useDiscrete } from "./useDiscrete.svelte.js";
+export { useShape, useDiscrete };

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

@@ -0,0 +1,94 @@
+import { DiscreteRoot } from "../../types.ts";
+import { DeepSignal } from "@ng-org/alien-deepsignals";
+/**
+ * Svelte 5 hook to subscribe to existing discrete (JSON) CRDT documents.
+ * You can modify the returned object like any other JSON object. Changes are immediately
+ * reflected in the CRDT.
+ *
+ * Establishes a 2-way binding: Modifications to the object are immediately committed,
+ * changes coming from the engine (or other components) cause an immediate rerender.
+ *
+ * In comparison to {@link svelteUseShape}, discrete CRDTs are untyped.
+ * You can put any JSON data inside and need to validate the schema yourself.
+ *
+ * @param documentIdOrPromise The NURI of the CRDT document or a promise to that.
+ * @returns The reactive JSON object of the CRDT document.
+ *
+ *@example
+ * ```svelte
+ * <script lang="ts">
+ *     // We assume you have created a CRDT document already, as below.
+ *     // const documentId = await ng.doc_create(
+ *     //     session_id,
+ *     //     crdt, // "Automerge" | "YMap" | "YArray"
+ *     //     crdt === "Automerge" ? "data:json" : crdt === "YMap ? "data:map" : "data:array",
+ *     //     "store",
+ *     //     undefined,
+ *     // );
+ *
+ *     const { doc } = useDiscrete(documentIdPromise);
+ *
+ *     $effect(() => {
+ *         // If the CRDT document is still empty, we need to initialize it.
+ *         if (doc && !doc.expenses) {
+ *             doc.expenses = [];
+ *         }
+ *     });
+ *
+ *     const createExpense = () => {
+ *         // 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
+ *         // preceding objects are removed or added from the array.
+ *         // The `@id` is an NURI 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(),
+ *         });
+ *      };
+ *
+ *
+ * </script>
+ *
+ * <section>
+ *     <div>
+ *         <button on:click={() => createExpense({})}/>
+ *
+ *         {#if !doc}
+ *             Loading...
+ *         {:else if doc.expenses.length === 0}
+ *             <p>
+ *                 Nothing tracked yet - log your first purchase to kick things off.
+ *             </p>
+ *         {:else}
+ *             {#each doc.expenses as expense, index (expense['@id']) }
+ *                 <ExpenseCard
+ *                     expense={expense}
+ *                 />
+ *             {/each}
+ *         {/if}
+ *     </div>
+ * </section>
+ * ```
+ *
+ * ---
+ * In the ExpenseCard component:
+ * ```svelte
+ *     let {
+ *         expense = $bindable(),
+ *     }: { expense: Expense; } = $props();
+ * </script>
+ *
+ * <div>
+ *     <input
+ *         bind:value={expense.title}
+ *     />
+ * </div>
+ * ```
+ */
+export declare function useDiscrete<T extends DiscreteRoot = DiscreteRoot>(documentIdOrPromise: string | Promise<string> | undefined): {
+    doc: DeepSignal<T | undefined>;
+};
+//# sourceMappingURL=useDiscrete.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDiscrete.svelte.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/svelte/useDiscrete.svelte.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAC7D,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,GAC1D;IACC,GAAG,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CAClC,CAqCA"}

package/dist/frontendAdapters/svelte/useDiscrete.svelte.js

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 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 { onDestroy } from "svelte";
+import { useDeepSignal } from "@ng-org/alien-deepsignals/svelte";
+import { DiscreteOrmSubscription } from "../../connector/discrete/discreteOrmSubscriptionHandler.js";
+/**
+ * Svelte 5 hook to subscribe to existing discrete (JSON) CRDT documents.
+ * You can modify the returned object like any other JSON object. Changes are immediately
+ * reflected in the CRDT.
+ *
+ * Establishes a 2-way binding: Modifications to the object are immediately committed,
+ * changes coming from the engine (or other components) cause an immediate rerender.
+ *
+ * In comparison to {@link svelteUseShape}, discrete CRDTs are untyped.
+ * You can put any JSON data inside and need to validate the schema yourself.
+ *
+ * @param documentIdOrPromise The NURI of the CRDT document or a promise to that.
+ * @returns The reactive JSON object of the CRDT document.
+ *
+ *@example
+ * ```svelte
+ * <script lang="ts">
+ *     // We assume you have created a CRDT document already, as below.
+ *     // const documentId = await ng.doc_create(
+ *     //     session_id,
+ *     //     crdt, // "Automerge" | "YMap" | "YArray"
+ *     //     crdt === "Automerge" ? "data:json" : crdt === "YMap ? "data:map" : "data:array",
+ *     //     "store",
+ *     //     undefined,
+ *     // );
+ *
+ *     const { doc } = useDiscrete(documentIdPromise);
+ *
+ *     $effect(() => {
+ *         // If the CRDT document is still empty, we need to initialize it.
+ *         if (doc && !doc.expenses) {
+ *             doc.expenses = [];
+ *         }
+ *     });
+ *
+ *     const createExpense = () => {
+ *         // 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
+ *         // preceding objects are removed or added from the array.
+ *         // The `@id` is an NURI 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(),
+ *         });
+ *      };
+ *
+ *
+ * </script>
+ *
+ * <section>
+ *     <div>
+ *         <button on:click={() => createExpense({})}/>
+ *
+ *         {#if !doc}
+ *             Loading...
+ *         {:else if doc.expenses.length === 0}
+ *             <p>
+ *                 Nothing tracked yet - log your first purchase to kick things off.
+ *             </p>
+ *         {:else}
+ *             {#each doc.expenses as expense, index (expense['@id']) }
+ *                 <ExpenseCard
+ *                     expense={expense}
+ *                 />
+ *             {/each}
+ *         {/if}
+ *     </div>
+ * </section>
+ * ```
+ *
+ * ---
+ * In the ExpenseCard component:
+ * ```svelte
+ *     let {
+ *         expense = $bindable(),
+ *     }: { expense: Expense; } = $props();
+ * </script>
+ *
+ * <div>
+ *     <input
+ *         bind:value={expense.title}
+ *     />
+ * </div>
+ * ```
+ */
+export function useDiscrete(documentIdOrPromise) {
+    let connection;
+    let isDestroyed = false;
+    let doc = $state.raw(undefined);
+    const init = (docId) => {
+        if (isDestroyed)
+            return;
+        connection = DiscreteOrmSubscription.getOrCreate(docId);
+        connection.readyPromise.then(() => {
+            if (isDestroyed) {
+                connection?.close();
+                return;
+            }
+            doc = useDeepSignal(connection.signalObject);
+        });
+    };
+    if (typeof documentIdOrPromise === "string") {
+        init(documentIdOrPromise);
+    }
+    else if (documentIdOrPromise === undefined) {
+        // There is nothing to initialize.
+    }
+    else {
+        documentIdOrPromise.then(init);
+    }
+    onDestroy(() => {
+        isDestroyed = true;
+        if (connection) {
+            connection.close();
+        }
+    });
+    return {
+        get doc() {
+            return doc;
+        },
+    };
+}