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

package/README.md

@@ -1,34 +1,41 @@
-# @ng-org/orm
+# NextGraph ORM SDK
 
-Reactive ORM library for NextGraph — use typed, reactive objects that automatically sync to NextGraph's encrypted, local-first storage.
+Reactive ORM library for NextGraph: use reactive (typed) objects that automatically sync to NextGraph's encrypted, local-first storage.
 
-For a walk-through, you can see the the [expense-tracker example app](https://git.nextgraph.org/NextGraph/expense-tracker) which shows
-- React, Vue, and Svelte frontends sharing data
-- SHEX schema definitions
-- CRUD operations
-- Cross-framework real-time sync
+For a walk-through you can see the the expense-tracker example apps for [discrete JSON documents](https://git.nextgraph.org/NextGraph/expense-tracker-discrete) or [typed graph documents](https://git.nextgraph.org/NextGraph/expense-tracker-graph).
+
+## Why?
+
+Different CRDTs have different APIs. We want to make it as easy as possible to use them in the same way:\
+**You modify a plain old TypeScript object and that updates the CRDT.**\
+Vice versa, the CRDT is modified and that is reflected in your TS object.\
+We offer this for **React, Vue, and Svelte**.
+
+Note that we support discrete (**JSON**) CRDT and graph (**RDF**) CRDT ORMs.
+
+- For graphs, you specify a schema using a SHEX shape and optionally a scope. This provides you with typing support.
+- For discrete CRDTs, all you need is a document id.
 
 ## Table of Contents
 
-- [@ng-org/orm](#ng-orgorm)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-  - [Defining Schemas](#defining-schemas)
-  - [Framework Usage](#framework-usage)
-    - [React](#react)
-    - [Vue](#vue)
-    - [Svelte](#svelte)
-  - [Working with Data](#working-with-data)
-    - [Adding Objects](#adding-objects)
-    - [Modifying Objects](#modifying-objects)
-    - [Deleting Objects](#deleting-objects)
-    - [Working with Sets](#working-with-sets)
-    - [Relationships](#relationships)
-  - [API Reference](#api-reference)
-    - [`useShape(shapeType)`](#useshapeshapetype)
-    - [Shared State](#shared-state)
-  - [License](#license)
+- [NextGraph ORM SDK](#nextgraph-orm-sdk)
+    - [Why?](#why)
+    - [Table of Contents](#table-of-contents)
+    - [Installation](#installation)
+    - [Start](#start)
+    - [Graph ORM: Defining Schemas](#graph-orm-defining-schemas)
+    - [Framework Usage](#framework-usage)
+        - [React](#react)
+        - [Vue](#vue)
+        - [Svelte](#svelte)
+    - [Working with Data](#working-with-data)
+        - [Adding Objects](#adding-objects)
+        - [Modifying Objects](#modifying-objects)
+        - [Deleting Objects](#deleting-objects)
+        - [Working with Sets](#working-with-sets)
+        - [Relationships](#relationships)
+    - [About NextGraph](#about-nextgraph)
+    - [License](#license)
 
 ---
 
@@ -38,7 +45,7 @@ For a walk-through, you can see the the [expense-tracker example app](https://gi
 pnpm add @ng-org/orm @ng-org/web @ng-org/alien-deepsignals
 ```
 
-For schema code generation, also install:
+For schema generation, also install:
 
 ```bash
 pnpm add -D @ng-org/shex-orm
@@ -46,7 +53,9 @@ pnpm add -D @ng-org/shex-orm
 
 ---
 
-## Quick Start
+## Start
+
+You are strongly advised to look at the example apps for [discrete JSON documents](https://git.nextgraph.org/NextGraph/expense-tracker-discrete) and [typed graph documents](https://git.nextgraph.org/NextGraph/expense-tracker-graph).
 
 Before using the ORM, initialize NextGraph in your app entry point:
 
@@ -56,6 +65,7 @@ import { initNg } from "@ng-org/orm";
 
 await init(
     async (event) => {
+        // The ORM needs to have access to ng, the interface to the engine running in WASM.
         initNg(ng, event.session);
     },
     true,
@@ -63,27 +73,24 @@ await init(
 );
 ```
 
-Then use `useShape()` in your components:
+Then use `useShape()` for graph, or `useDiscrete()` for discrete documents.
 
-```typescript
-import { useShape } from "@ng-org/orm/react";  // or /vue, /svelte
-import { DogShapeType } from "./shapes/orm/dogShape.shapeTypes";
+In some cases, you may want to use advanced features managing subscriptions with the engine.
+For that, you can directly use:
 
-const dogs = useShape(DogShapeType);
+- `OrmSubscription.getOrCreate(ShapeType, scope)` for graphs
+- `DiscreteOrmSubscription.getOrCreate(documentId)` for discrete documents
 
-// Iterate, modify, add — changes auto-sync everywhere
-for (const dog of dogs) {
-    console.log(dog.name);
-}
-```
+Internally, the OrmSubscription keeps a signalObject, a proxied, reactive object. When modifications are made, this makes the frontend components rerender and sends the update to the engine to be persisted.
+In all cases, you have to create a document first with `ng.doc_create()`. For more details, you can consult the example apps and the inline jsdoc documentation.
 
----
-
-## Defining Schemas
+## Graph ORM: Defining Schemas
 
 Define your data model using [SHEX (Shape Expressions)](https://shex.io/):
+See [@ng-org/shex-orm](../shex-orm/README.md) for details.
 
 **`shapes/shex/dogShape.shex`**:
+
 ```shex
 PREFIX ex: <http://example.org/>
 PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
@@ -102,15 +109,6 @@ Generate TypeScript types. Add the following to your `package.json` scripts and
     "build:orm": "rdf-orm build --input ./src/shapes/shex --output ./src/shapes/orm"
 ```
 
-This creates:
-- `dogShape.typings.ts` — TypeScript interfaces
-- `dogShape.shapeTypes.ts` — Shape type objects for `useShape()`
-- `dogShape.schema.ts` — Internal schema metadata
-
-See [@ng-org/shex-orm](../shex-orm/README.md) for full documentation.
-
----
-
 ## Framework Usage
 
 ### React
@@ -121,16 +119,16 @@ import { DogShapeType } from "./shapes/orm/dogShape.shapeTypes";
 import type { Dog } from "./shapes/orm/dogShape.typings";
 
 export function DogList() {
-    const dogs = useShape(DogShapeType);  // DeepSignalSet<Dog>
+    const dogs = useShape(DogShapeType); // DeepSignalSet<Dog>
 
     return (
         <ul>
-            {[...dogs].map(dog => (
+            {[...dogs].map((dog) => (
                 <li key={dog["@id"]}>
                     {/* Direct mutation triggers re-render */}
                     <input
                         value={dog.name}
-                        onChange={e => dog.name = e.target.value}
+                        onChange={(e) => (dog.name = e.target.value)}
                     />
                 </li>
             ))}
@@ -144,25 +142,23 @@ export function DogList() {
 ### Vue
 
 **Parent component** (`DogList.vue`):
+
 ```vue
 <script setup lang="ts">
 import { useShape } from "@ng-org/orm/vue";
 import { DogShapeType } from "./shapes/orm/dogShape.shapeTypes";
 import DogCard from "./DogCard.vue";
 
-const dogs = useShape(DogShapeType);  // DeepSignalSet<Dog>
+const dogs = useShape(DogShapeType); // DeepSignalSet<Dog>
 </script>
 
 <template>
-    <DogCard
-        v-for="dog in dogs"
-        :key="dog['@id']"
-        :dog="dog"
-    />
+    <DogCard v-for="dog in dogs" :key="dog['@id']" :dog="dog" />
 </template>
 ```
 
 **Child component** (`DogCard.vue`):
+
 ```vue
 <script setup lang="ts">
 import { useDeepSignal } from "@ng-org/alien-deepsignals/vue";
@@ -187,14 +183,14 @@ const dog = useDeepSignal(props.dog);
 
 ```svelte
 <script lang="ts">
-import { useShape } from "@ng-org/orm/svelte";
-import { DogShapeType } from "./shapes/orm/dogShape.shapeTypes";
+    import { useShape } from "@ng-org/orm/svelte";
+    import { DogShapeType } from "./shapes/orm/dogShape.shapeTypes";
 
-const dogs = useShape(DogShapeType);  // Reactive store
+    const dogs = useShape(DogShapeType); // Reactive store
 </script>
 
 <ul>
-    {#each [...$dogs] as dog (dog['@id'])}
+    {#each [...$dogs] as dog (dog["@id"])}
         <li>
             <input bind:value={dog.name} />
         </li>
@@ -228,9 +224,9 @@ const docIri = await session.ng.doc_create(
 
 // Add to the reactive set
 dogs.add({
-    "@graph": docIri,                   // Required: document IRI
-    "@type": "http://example.org/Dog",  // Required: RDF type
-    "@id": "",                          // Empty = auto-generate subject IRI
+    "@graph": docIri, // Required: document IRI
+    "@type": "http://example.org/Dog", // Required: RDF type
+    "@id": "", // Empty = auto-generate subject IRI
     name: "Buddy",
     age: 3,
     toys: new Set(["ball", "rope"]),
@@ -239,7 +235,7 @@ dogs.add({
 
 > **Note**: For nested sub-objects, `@graph` is optional — the parent's graph IRI is used.
 >
-> **Note**: If you want to use the ORM signal object in a non-component context, you can create an ORM connection manually using `OrmConnection.getOrCreate()`.
+> **Note**: If you want to use the ORM signal object in a non-component context, you can create an ORM connection manually using `OrmSubscription.getOrCreate()`.
 
 ### Modifying Objects
 
@@ -251,6 +247,7 @@ dog.age = 4;
 ```
 
 Changes are:
+
 - Immediately reflected in all components using the same shape
 - Automatically persisted to NextGraph storage
 - Synced to other devices in real-time
@@ -301,35 +298,20 @@ Link objects by storing the target's `@id` IRI:
 dog.owner = person["@id"];
 
 // Resolve the relationship
-const owner = people.find(p => p["@id"] === dog.owner);
+const owner = people.find((p) => p["@id"] === dog.owner);
 ```
 
 ---
 
-## API Reference
-
-### `useShape(shapeType)`
-
-Returns a `DeepSignalSet<T>` containing all objects of the given shape type.
-
-```typescript
-const dogs = useShape(DogShapeType);
-```
-
-**DeepSignalSet methods:**
-- `add(obj)` — Add a new object
-- `delete(obj)` — Remove an object
-- `has(obj)` — Check if object exists
-- `size` — Number of objects
-- `getBy(graphIri, subjectIri)` — Find object by IRIs
-- `[Symbol.iterator]` — Iterate with `for...of` or spread `[...set]`
-- ... and all symbol iterator helper methods (like `.map`, `.find`, ...), if you are in an ES2025+ environment.
-
-### Shared State
+## About NextGraph
 
-When `useShape()` is called with the same shape type and scope in multiple components, they share the exact same reactive data. Changes in one component instantly appear in all others.
-
----
+> **NextGraph** brings about the convergence of P2P and Semantic Web technologies, towards a decentralized, secure and privacy-preserving cloud, based on CRDTs.
+>
+> This open source ecosystem provides solutions for end-users (a platform) and software developers (a framework), wishing to use or create **decentralized** apps featuring: **live collaboration** on rich-text documents, peer to peer communication with **end-to-end encryption**, offline-first, **local-first**, portable and interoperable data, total ownership of data and software, security and privacy.
+>
+> Centered on repositories containing **semantic data** (RDF), **rich text**, and structured data formats like **JSON**, synced between peers belonging to permissioned groups of users, it offers strong eventual consistency, thanks to the use of **CRDTs**. Documents can be linked together, signed, shared securely, queried using the **SPARQL** language and organized into sites and containers.
+>
+> More info: [https://nextgraph.org](https://nextgraph.org)
 
 ## License
 
@@ -337,7 +319,7 @@ Licensed under either of
 
 - Apache License, Version 2.0 ([LICENSE-APACHE2](LICENSE-APACHE2) or http://www.apache.org/licenses/LICENSE-2.0)
 - MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
-  
+
 at your option.
 
 `SPDX-License-Identifier: Apache-2.0 OR MIT`

package/dist/connector/applyPatches.d.ts

@@ -1,9 +1,11 @@
+/** @internal */
 export type Patch = {
     /** Property path (array indices, object keys, synthetic Set entry ids) from the root to the mutated location. */
     path: string;
     valType?: string & {};
     value?: unknown;
 } & (SetAddPatch | SetRemovePatch | RemovePatch | LiteralAddPatch);
+/** @internal */
 export interface SetAddPatch {
     /** Mutation kind applied at the resolved `path`. */
     op: "add";
@@ -15,6 +17,7 @@ export interface SetAddPatch {
      */
     value: number | string | boolean | (number | string | boolean)[];
 }
+/** @internal */
 export interface SetRemovePatch {
     /** Mutation kind applied at the resolved `path`. */
     op: "remove";
@@ -26,10 +29,12 @@ export interface SetRemovePatch {
      */
     value: number | string | boolean | object | (number | string | boolean | object)[];
 }
+/** @internal */
 export interface RemovePatch {
     /** Mutation kind applied at the resolved `path`. */
     op: "remove";
 }
+/** @internal */
 export interface LiteralAddPatch {
     /** Mutation kind applied at the resolved `path`. */
     op: "add";
@@ -37,17 +42,19 @@ export interface LiteralAddPatch {
     value: string | number | boolean | object;
 }
 /**
+ * @internal
+ *
  * Apply a diff to an object.
  *
  * The syntax is inspired by RFC 6902 but it is not compatible.
  *
  * It supports Sets for multi-valued properties:
  *   - Primitive values are added as Sets (Set<string | number | boolean>)
- *   - Multi-valued objects are stored in Sets, accessed by their @id property
- *   - Single objects are plain objects with an @id property
+ *   - Multi-valued objects are stored in Sets, accessed by their `@id` property
+ *   - Single objects are plain objects with an `@id` property
  *
  * Path traversal:
- *   - When traversing through a Set, the path segment is treated as an @id to find the object
+ *   - When traversing through a Set, the path segment is treated as an `@id` to find the object
  *   - When traversing through a plain object, the path segment is a property name
  *
  * @example operations
@@ -88,13 +95,15 @@ export interface LiteralAddPatch {
  * @param patches An array of patches to apply to the object.
  * @param ensurePathExists If true, create nested objects along the path if the path does not exist.
  *
- * @note When creating new objects, this function pre-scans upcoming patches to find @id and @graph
+ * Note: When creating new objects, this function pre-scans upcoming patches to find `@id` and `@graph`
  *       values that will be assigned to the object. This prevents the signal library's propGenerator
  *       from being triggered before these identity fields are set, which would cause it to generate
  *       random IDs unnecessarily.
  */
 export declare function applyPatches(currentState: Record<string, any>, patches: Patch[], ormType: "set" | "discrete", ensurePathExists?: boolean): void;
 /**
+ * @internal
+ *
  * See documentation for applyPatches
  */
 export declare function applyPatchesToDeepSignal(currentState: object, patch: Patch[], ormType: "set" | "discrete"): void;

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

@@ -1 +1 @@
-{"version":3,"file":"applyPatches.d.ts","sourceRoot":"","sources":["../../src/connector/applyPatches.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,KAAK,GAAG;IAChB,iHAAiH;IACjH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,CAAC,WAAW,GAAG,cAAc,GAAG,WAAW,GAAG,eAAe,CAAC,CAAC;AAEnE,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CACpE;AAED,MAAM,WAAW,cAAc;IAC3B,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EACC,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC5B,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAC7C;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,YAAY,CACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,EAAE,KAAK,EAAE,EAChB,OAAO,EAAE,KAAK,GAAG,UAAU,EAC3B,gBAAgB,GAAE,OAAe,QA6PpC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACpC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,KAAK,EAAE,EACd,OAAO,EAAE,KAAK,GAAG,UAAU,QAU9B"}
+{"version":3,"file":"applyPatches.d.ts","sourceRoot":"","sources":["../../src/connector/applyPatches.ts"],"names":[],"mappings":"AAYA,gBAAgB;AAChB,MAAM,MAAM,KAAK,GAAG;IAChB,iHAAiH;IACjH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,CAAC,WAAW,GAAG,cAAc,GAAG,WAAW,GAAG,eAAe,CAAC,CAAC;AAEnE,gBAAgB;AAChB,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CACpE;AAED,gBAAgB;AAChB,MAAM,WAAW,cAAc;IAC3B,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf;;;;OAIG;IACH,KAAK,EACC,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAChD;AAED,gBAAgB;AAChB,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,EAAE,EAAE,QAAQ,CAAC;CAChB;AAED,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC5B,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAC7C;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,YAAY,CACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,EAAE,KAAK,EAAE,EAChB,OAAO,EAAE,KAAK,GAAG,UAAU,EAC3B,gBAAgB,GAAE,OAAe,QA6PpC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACpC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,KAAK,EAAE,EACd,OAAO,EAAE,KAAK,GAAG,UAAU,QAU9B"}

package/dist/connector/applyPatches.js

@@ -45,17 +45,19 @@ function findInSetBySegment(set, seg) {
     return undefined;
 }
 /**
+ * @internal
+ *
  * Apply a diff to an object.
  *
  * The syntax is inspired by RFC 6902 but it is not compatible.
  *
  * It supports Sets for multi-valued properties:
  *   - Primitive values are added as Sets (Set<string | number | boolean>)
- *   - Multi-valued objects are stored in Sets, accessed by their @id property
- *   - Single objects are plain objects with an @id property
+ *   - Multi-valued objects are stored in Sets, accessed by their `@id` property
+ *   - Single objects are plain objects with an `@id` property
  *
  * Path traversal:
- *   - When traversing through a Set, the path segment is treated as an @id to find the object
+ *   - When traversing through a Set, the path segment is treated as an `@id` to find the object
  *   - When traversing through a plain object, the path segment is a property name
  *
  * @example operations
@@ -96,7 +98,7 @@ function findInSetBySegment(set, seg) {
  * @param patches An array of patches to apply to the object.
  * @param ensurePathExists If true, create nested objects along the path if the path does not exist.
  *
- * @note When creating new objects, this function pre-scans upcoming patches to find @id and @graph
+ * Note: When creating new objects, this function pre-scans upcoming patches to find `@id` and `@graph`
  *       values that will be assigned to the object. This prevents the signal library's propGenerator
  *       from being triggered before these identity fields are set, which would cause it to generate
  *       random IDs unnecessarily.
@@ -273,7 +275,7 @@ export function applyPatches(currentState, patches, ormType, ensurePathExists =
         if (patch.op === "add" &&
             typeof patch.value === "object" &&
             patch.value !== null &&
-            ormType === "set" // TODO: The backend should preferably add valType: "set" here (we don't need ormType then).
+            ormType === "set" // TODO: The engine should preferably add valType: "set" here (we don't need ormType then).
         ) {
             const leafVal = parentVal[key];
             const hasId = patches.at(patchIndex + 2)?.path.endsWith("@id");
@@ -334,6 +336,8 @@ export function applyPatches(currentState, patches, ormType, ensurePathExists =
     }
 }
 /**
+ * @internal
+ *
  * See documentation for applyPatches
  */
 export function applyPatchesToDeepSignal(currentState, patch, ormType) {

package/dist/connector/discrete/discreteOrmSubscriptionHandler.d.ts

@@ -0,0 +1,156 @@
+import { DiscreteArray, DiscreteObject } from "../../types.ts";
+import { Patch } from "../applyPatches.ts";
+import type { DeepPatch, DeepSignal } from "@ng-org/alien-deepsignals";
+import type { 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](../../../README.md) and follow the tutorial.
+ */
+export declare class DiscreteOrmSubscription {
+    /** Global store of all subscriptions. We use that for pooling. */
+    private static idToEntry;
+    /** The document id (IRI) of the subscribed document. */
+    readonly documentId: string;
+    private _signalObject;
+    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;
+    /** 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 constructor();
+    get signalObject(): DeepSignal<DiscreteArray | DiscreteObject> | undefined;
+    /**
+     * 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.
+     *
+     * @param documentId The document ID (IRI) 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 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 = DiscreteOrmSubscription.getOrCreate(documentId);
+     *
+     * subscription2.signalObject.expenses.push({
+     *     name: "Second expense",
+     *     description: "Second description"
+     * });
+     *
+     * subscription2.close();
+     * ```
+     */
+    static getOrCreate: <T extends BaseType>(documentId: string) => DiscreteOrmSubscription;
+    /**
+     * 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: () => 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;
+    /**
+     * 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>;
+}
+/**
+ * Converts DeepSignal patches to ORM Wasm-compatible patches
+ * @param patches DeepSignal patches
+ * @returns Patches with stringified path
+ */
+export declare function deepPatchesToWasm(patches: DeepPatch[]): Patch[];
+//# sourceMappingURL=discreteOrmSubscriptionHandler.d.ts.map

package/dist/connector/discrete/discreteOrmSubscriptionHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discreteOrmSubscriptionHandler.d.ts","sourceRoot":"","sources":["../../../src/connector/discrete/discreteOrmSubscriptionHandler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAA4B,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAQrE,OAAO,KAAK,EACR,SAAS,EACT,UAAU,EAEb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AASjD;;;;;;;;;GASG;AACH,qBAAa,uBAAuB;IAChC,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,SAAS,CAA8C;IAEtE,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,aAAa,CAEL;IAChB,OAAO,CAAC,mBAAmB,CAA2B;IACtD,qFAAqF;IACrF,OAAO,CAAC,cAAc,CAAqB;IAC3C,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAS;IACzB,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;IAElC,OAAO;IA+BP,IAAW,YAAY,2DAEtB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6EG;IACH,OAAc,WAAW,GAAI,CAAC,SAAS,QAAQ,EAC3C,YAAY,MAAM,KACnB,uBAAuB,CAcxB;IAEF;;;;;;;;;OASG;IAEI,KAAK,aASV;IAEF,wEAAwE;IACxE,OAAO,CAAC,oBAAoB,CAsB1B;IAEF,wEAAwE;IACxE,OAAO,CAAC,gBAAgB,CAStB;IAEF,OAAO,CAAC,qBAAqB,CAiB3B;IAEF,8CAA8C;IAC9C,OAAO,CAAC,eAAe,CAUrB;IAEF;;;;;;OAMG;IACI,gBAAgB,aAerB;IAEF;;;OAGG;IACI,iBAAiB,sBAiCtB;CACL;AAED;;;;GAIG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,CAO/D"}