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

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

@@ -1,92 +1,99 @@
-import { MaybeRefOrGetter } from "vue";
-import { type DeepSignal } from "@ng-org/alien-deepsignals";
-import { DiscreteArray, DiscreteObject } from "../../types.ts";
+import { MaybeRefOrGetter, ToRefs } from "vue";
+import { DiscreteRootObject } 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 `useShape`, 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.
- * @returns An object that contains as `data` the reactive DeepSignal object.
+ * @param documentId The IRI of the CRDT document or `undefined` as MaybeRefOrGetter.
+ * @returns An object that contains as `data` the reactive DeepSignal object or undefined if not loaded yet or `documentId` is undefined.
  *
  *@example
-```html
-<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 { data } = useDiscrete(documentId);
-
-// If document is new, we need to set up the basic structure.
-if (data && !data.expenses) {
-    data.expenses = [];
-}
-
-// 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
-</script>
-
-<template>
-    <div v-if="!data">
-        Loading...
-    </div>
-    <div v-else>
-        <p v-if="expensesSorted.length === 0">
-            No expenses yet.
-        </p>
-        <template v-else>
-            <ExpenseCard
-                v-for="expense in expenses"
-                :key="expense['@id']"
-                :expense="expense"
-            />
-        </template>
-    </div>
-</template>
-```
-
-In the `ExpenseCard` component:
-```html
-<script lang="ts">
-const props = defineProps<{
-    expense: DeepSignal<Expense>;
-}>();
-
-// Important!
-// In vue, you need to wrap children into useDeepSignal hooks,
-// to ensure the component re-renders on changes coming from
-// other components or the backend.
-const expense = useDeepSignal(props.expense);
-
-// If you modify expense in the component,
-// the changes are immediately propagated to the other components
-// And persisted in the database.
-</script>
-
-<template>
-    <input
-        v-model="expense.title"
-        placeholder="Expense title"
-    />
-</template>
-```
+ * ```html
+ * <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(documentId);
+ *
+ * // If document is new, we need to set up the basic structure.
+ * effect(() => {
+ *     if (doc.value && !doc.value.expenses) {
+ *         doc.value.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
+ *     // 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.
+ *     doc.value.expenses.push({
+ *         title: "New expense",
+ *         date: new Date().toISOString(),
+ *     });
+ * };
+ * </script>
+ *
+ * <template>
+ *     <div v-if="!doc">
+ *         Loading...
+ *     </div>
+ *     <div v-else>
+ *         <p v-if="expenses.length === 0">
+ *             No expenses yet.
+ *         </p>
+ *         <template v-else>
+ *             <button
+ *                 @click={() => createExpense()}
+ *             >
+ *                 + Add expense
+ *             </button>
+ *             <ExpenseCard
+ *                 v-for="expense in expenses"
+ *                 :key="expense['@id']"
+ *                 :expense="expense"
+ *             />
+ *         </template>
+ *     </div>
+ * </template>
+ * ```
+ *
+ * In the `ExpenseCard` component:
+ * ```html
+ * <script lang="ts">
+ * const { expense } = defineProps<{
+ *     expense: DeepSignal<Expense>;
+ * }>();
+ *
+ * // If you modify expense in the component,
+ * // the changes are immediately propagated to the other components
+ * // And persisted in the database.
+ * </script>
+ *
+ * <template>
+ *     <input
+ *         v-model="expense.title"
+ *         placeholder="Expense title"
+ *     />
+ * </template>
+ * ```
  */
-export declare function useDiscrete(documentId: MaybeRefOrGetter<string | undefined>): {
-    data: import("vue").ComputedRef<DeepSignal<DiscreteArray | DiscreteObject> | undefined>;
-};
+export declare function useDiscrete(documentId: MaybeRefOrGetter<string | undefined>): ToRefs<{
+    doc: DiscreteRootObject;
+}>;
 //# sourceMappingURL=useDiscrete.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useDiscrete.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/vue/useDiscrete.ts"],"names":[],"mappings":"AAUA,OAAO,EAAY,gBAAgB,EAA4B,MAAM,KAAK,CAAC;AAC3E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC;;EAuB3E"}
+{"version":3,"file":"useDiscrete.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/vue/useDiscrete.ts"],"names":[],"mappings":"AAUA,OAAO,EAEH,gBAAgB,EAGhB,MAAM,EAIT,MAAM,KAAK,CAAC;AAGb,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,GAmBlD,MAAM,CAAC;IAAE,GAAG,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAC5D"}

package/dist/frontendAdapters/vue/useDiscrete.js

@@ -7,105 +7,117 @@
 // notice may not be copied, modified, or distributed except
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
-import { computed, onBeforeUnmount, toValue } from "vue";
+import { computed, onBeforeUnmount, shallowReactive, toRefs, toValue, watchEffect, } from "vue";
 import { useDeepSignal } from "@ng-org/alien-deepsignals/vue";
-import { DiscreteOrmConnection } from "../../connector/discrete/discreteOrmConnectionHandler.js";
-const EMPTY_OBJECT = {};
+import { DiscreteOrmSubscription } from "../../connector/discrete/discreteOrmSubscriptionHandler.js";
 /**
- * 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 `useShape`, 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.
- * @returns An object that contains as `data` the reactive DeepSignal object.
+ * @param documentId The IRI of the CRDT document or `undefined` as MaybeRefOrGetter.
+ * @returns An object that contains as `data` the reactive DeepSignal object or undefined if not loaded yet or `documentId` is undefined.
  *
  *@example
-```html
-<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 { data } = useDiscrete(documentId);
-
-// If document is new, we need to set up the basic structure.
-if (data && !data.expenses) {
-    data.expenses = [];
-}
-
-// 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
-</script>
-
-<template>
-    <div v-if="!data">
-        Loading...
-    </div>
-    <div v-else>
-        <p v-if="expensesSorted.length === 0">
-            No expenses yet.
-        </p>
-        <template v-else>
-            <ExpenseCard
-                v-for="expense in expenses"
-                :key="expense['@id']"
-                :expense="expense"
-            />
-        </template>
-    </div>
-</template>
-```
-
-In the `ExpenseCard` component:
-```html
-<script lang="ts">
-const props = defineProps<{
-    expense: DeepSignal<Expense>;
-}>();
-
-// Important!
-// In vue, you need to wrap children into useDeepSignal hooks,
-// to ensure the component re-renders on changes coming from
-// other components or the backend.
-const expense = useDeepSignal(props.expense);
-
-// If you modify expense in the component,
-// the changes are immediately propagated to the other components
-// And persisted in the database.
-</script>
-
-<template>
-    <input
-        v-model="expense.title"
-        placeholder="Expense title"
-    />
-</template>
-```
+ * ```html
+ * <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(documentId);
+ *
+ * // If document is new, we need to set up the basic structure.
+ * effect(() => {
+ *     if (doc.value && !doc.value.expenses) {
+ *         doc.value.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
+ *     // 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.
+ *     doc.value.expenses.push({
+ *         title: "New expense",
+ *         date: new Date().toISOString(),
+ *     });
+ * };
+ * </script>
+ *
+ * <template>
+ *     <div v-if="!doc">
+ *         Loading...
+ *     </div>
+ *     <div v-else>
+ *         <p v-if="expenses.length === 0">
+ *             No expenses yet.
+ *         </p>
+ *         <template v-else>
+ *             <button
+ *                 @click={() => createExpense()}
+ *             >
+ *                 + Add expense
+ *             </button>
+ *             <ExpenseCard
+ *                 v-for="expense in expenses"
+ *                 :key="expense['@id']"
+ *                 :expense="expense"
+ *             />
+ *         </template>
+ *     </div>
+ * </template>
+ * ```
+ *
+ * In the `ExpenseCard` component:
+ * ```html
+ * <script lang="ts">
+ * const { expense } = defineProps<{
+ *     expense: DeepSignal<Expense>;
+ * }>();
+ *
+ * // If you modify expense in the component,
+ * // the changes are immediately propagated to the other components
+ * // And persisted in the database.
+ * </script>
+ *
+ * <template>
+ *     <input
+ *         v-model="expense.title"
+ *         placeholder="Expense title"
+ *     />
+ * </template>
+ * ```
  */
 export function useDiscrete(documentId) {
-    const ormConnection = computed(() => {
+    const ormSubscription = computed(() => {
         const id = toValue(documentId);
-        return id ? DiscreteOrmConnection.getOrCreate(id) : undefined;
+        return id ? DiscreteOrmSubscription.getOrCreate(id) : undefined;
+    });
+    const ret = shallowReactive({
+        doc: undefined,
+    });
+    watchEffect(() => {
+        ormSubscription.value?.readyPromise.then(() => {
+            ret.doc = useDeepSignal(ormSubscription.value.signalObject);
+        });
     });
     onBeforeUnmount(() => {
-        ormConnection?.value?.close();
+        ormSubscription.value?.close();
     });
-    const signalSource = computed(() => ormConnection.value?.signalObject ?? EMPTY_OBJECT);
-    const state = useDeepSignal(signalSource);
-    const data = computed(() => ormConnection.value?.signalObject ? state : undefined);
-    return { data };
+    return toRefs(ret);
 }

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

@@ -1,4 +1,4 @@
-import type { Scope } from "../../types.ts";
+import { type Scope } from "../../types.ts";
 import type { BaseType, ShapeType } from "@ng-org/shex-orm";
 import { DeepSignalSet } from "@ng-org/alien-deepsignals";
 /**
@@ -10,71 +10,65 @@ import { DeepSignalSet } from "@ng-org/alien-deepsignals";
  * changes coming from the backend (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 scope in which the objects should be.
+ * @param scope The scope in which the objects should be. Leaving it `undefined` makes no subscription.
  * @returns A {@link DeepSignalSet} containing the objects matching the shape type and scope.
  *
  * @example
-```html
-<script lang="ts">
-// Contains all expense objects with `@id` <s1 IRI> or <s2 IRI> and `@graph` <g1 IRI> or <g2 IRI>
-const expenses: DeepSignalSet<Expense> = useShape(ExpenseShape,
-     {graphs: ["<g1 IRI>", "<g2 IRI>"],
-      subjects: ["<s1 IRI>", "<s2 IRI>"]});
-
-
-const expensesSorted = computed(() => [...expenses].sort((a, b) =>
-    a.dateOfPurchase.localeCompare(b.dateOfPurchase)
-));
-
-// Call expenses.add({"@graph": "<g1 or g2 IRI>", "@id": "", title: "Example title"}), to add new elements.
-// Leave `@id` an empty string to auto-generate a subject IRI (adjust your scope accordingly).
-
-// 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`.
-</script>
-
-<template>
-    <div>
-        <p v-if="expensesSorted.length === 0">
-            No expenses yet.
-        </p>
-        <template v-else>
-            <ExpenseCard
-                v-for="expense in expensesSorted"
-                :key="expense['@id'])"
-                :expense="expense"
-            />
-        </template>
-    </div>
-</template>
-```
-
-In the `ExpenseCard` component:
-```html
-<script lang="ts">
-const props = defineProps<{
-    expense: DeepSignal<Expense>;
-}>();
-
-// Important!
-// In vue, you need to wrap children into useDeepSignal hooks,
-// to ensure the component re-renders on changes coming from
-// other components or the backend.
-const expense = useDeepSignal(props.expense);
-
-// If you modify expense in the component,
-// the changes are immediately propagated to the other components
-// And persisted in the database.
-</script>
-
-<template>
-    <input
-        v-model="expense.title"
-        placeholder="Expense title"
-    />
-</template>
-```
+ * ```html
+ * <script lang="ts">
+ * // Contains all expense objects with `@id` <s1 IRI> or <s2 IRI> and `@graph` <g1 IRI> or <g2 IRI>
+ * const expenses: DeepSignalSet<Expense> = useShape(ExpenseShapeType,
+ *      {graphs: ["<g1 IRI>", "<g2 IRI>"],
+ *       subjects: ["<s1 IRI>", "<s2 IRI>"]});
+ *
+ *
+ * const expensesSorted = computed(() => [...expenses].sort((a, b) =>
+ *     a.dateOfPurchase.localeCompare(b.dateOfPurchase)
+ * ));
+ *
+ * // Simply call expenses.add({"@graph": "<g1 or g2 IRI>", "@id": "", title: "Example title"}), to add new elements.
+ * // Leave `@id` an empty string to auto-generate a subject IRI (adjust your scope accordingly).
+ *
+ * // 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`.
+ * </script>
+ *
+ * <template>
+ *     <div>
+ *         <p v-if="expensesSorted.length === 0">
+ *             No expenses yet.
+ *         </p>
+ *         <template v-else>
+ *             <ExpenseCard
+ *                 v-for="expense in expensesSorted"
+ *                 :key="expense['@id'])"
+ *                 :expense="expense"
+ *             />
+ *         </template>
+ *     </div>
+ * </template>
+ * ```
+ *
+ * In the `ExpenseCard` component:
+ * ```html
+ * <script lang="ts">
+ * const { expense } = defineProps<{
+ *     expense: DeepSignal<Expense>;
+ * }>();
+ *
+ * // If you modify expense in the component,
+ * // the changes are immediately propagated to the other components
+ * // And persisted in the database.
+ * </script>
+ *
+ * <template>
+ *     <input
+ *         v-model="expense.title"
+ *         placeholder="Expense title"
+ *     />
+ * </template>
+ * ```
  */
-export declare function useShape<T extends BaseType>(shape: ShapeType<T>, scope?: Scope): DeepSignalSet<T>;
+export declare function useShape<T extends BaseType>(shape: ShapeType<T>, scope: Scope): DeepSignalSet<T>;
 export default useShape;
 //# sourceMappingURL=useShape.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useShape.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/vue/useShape.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EACvC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,KAAK,GAAE,KAAU,oBAYpB;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"useShape.d.ts","sourceRoot":"","sources":["../../../src/frontendAdapters/vue/useShape.ts"],"names":[],"mappings":"AAUA,OAAO,EAAkB,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5D,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EACvC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,KAAK,EAAE,KAAK,oBAef;AAED,eAAe,QAAQ,CAAC"}