@audiotool/nexus 0.0.8 → 0.0.10

package/dist/document/backend/create-wasm-document-state.d.ts

@@ -12,6 +12,8 @@ export type WasmDocumentState = {
      * * an error string if the transaction is invalid
      */
     applyTransaction: (transaction: Transaction) => Transaction | string;
+    /** Causes {@link applyTransaction} to throw. Used to clean up memory in the wasm. */
+    terminate(): void;
 };
 /** Type of object returned by the wasm module if an error happens. */
 type WasmError = {
@@ -42,4 +44,13 @@ declare global {
     } | undefined;
     var createDocumentState: (() => WasmState) | undefined;
 }
+/**
+ * @internal
+ *
+ * For debugging - tracks how many documents are currently open in wasm but not yet closed.
+ *
+ * This can be used to assert that all documents have been terminated when a nexus document is terminated.
+ * This is important because the wasm memory won't be freed on its own if it's not referenced.
+ */
+export declare let DEBUG_totalOpenWasmDocuments: number;
 export {};

package/dist/document/backend/document-service/connection/index.d.ts

@@ -0,0 +1,37 @@
+import { DocumentService } from '../../../../gen/audiotool/document/v1/document_service_connect';
+import { Transaction } from '../../../../gen/audiotool/document/v1/document_service_pb';
+import { RetryingClient } from '../../../../utils/grpc/retrying-client';
+import { ObservableValue } from '../../../../utils/observable-notifier-value';
+
+/** This object represents a connection to the document service. It's built from a document service client.
+ *
+ * While it isn't terminated, it will continuously ping the backend to check if the connection is still alive,
+ * and update the ping value.
+ *
+ * The parameter {@link connectionOk} turns to false if something goes wrong in a recoverable way.
+ * If something goes wrong in an unrecoverable way, the service connection will throw an error in a detached promise.
+ *
+ */
+export type DocumentServiceConnection = {
+    /** The stream of incoming transactions. The document is "loaded" when the first transaction is received.*/
+    receiveNextTransaction: AsyncIterable<Transaction, void, void>;
+    /** Send the next transaction to the backend, returns a string if the backend rejects it. */
+    sendNextTransaction: (t: Transaction) => Promise<string | undefined>;
+    /** The current ping to the backend. */
+    pingMs: ObservableValue<number>;
+    /**
+     * Turns to false if any of the three calls (send, receive, ping) fail in a recoverable way.
+     */
+    connectionOk: ObservableValue<boolean>;
+    /** Terminate the connection. Has the following effect:
+     * * `receiveNextTransaction` is terminated
+     * * `sendNextTransaction` will throw an error
+     *
+     * Resolves once the last transaction has been sent.
+     */
+    terminate: () => Promise<void>;
+};
+export declare const createDocumentServiceConnection: (documentService: RetryingClient<typeof DocumentService>, projectName: string, opts?: {
+    backoffMs?: number;
+    pingIntervalMs?: number;
+}) => DocumentServiceConnection;

package/dist/document/backend/document-service/connection/ping-notifier.d.ts

@@ -0,0 +1,20 @@
+import { DocumentService } from '../../../../gen/audiotool/document/v1/document_service_connect';
+import { RetryingClient } from '../../../../utils/grpc/retrying-client';
+import { Observable } from '../../../../utils/observable-notifier';
+import { ObservableValue } from '../../../../utils/observable-notifier-value';
+
+/** A ping notifier continuously pings the backend to check if the connection is still alive. */
+export type PingNotifier = {
+    /** emits a true/false value every time a successful/failed ping is received. */
+    pingCallResults: Observable<boolean>;
+    /** true while ping call is not retrying */
+    connectionOk: ObservableValue<boolean>;
+    /** current ping to server, in milliseconds. Currently doesn't update if no ping response is received */
+    pingMs: ObservableValue<number>;
+    /** Immediately terminates the ping loop. */
+    terminate: () => void;
+};
+export declare const createPingNotifier: (documentService: Pick<RetryingClient<typeof DocumentService>, "ping">, projectName: string, opts?: {
+    pingIntervalMs?: number;
+    clientId?: string;
+}) => PingNotifier;

package/dist/document/backend/document-service/connection/transaction-receiver.d.ts

@@ -0,0 +1,26 @@
+import { DocumentService } from '../../../../gen/audiotool/document/v1/document_service_connect';
+import { Transaction } from '../../../../gen/audiotool/document/v1/document_service_pb';
+import { RetryingClient } from '../../../../utils/grpc/retrying-client';
+import { ObservableValue } from '../../../../utils/observable-notifier-value';
+
+export type TransactionReceiver = {
+    /** Get the next transaction sent from the backend. On disconnect, just blocks until
+     * reconnection. Throws only if unrecoverable. The very first transaction will "load" the current document
+     * state, which might be empty if the document is new.
+     */
+    nextTransactionIterator: AsyncIterable<Transaction, void, void>;
+    /**
+     * Stops internal logic, terminates the iterator. No effect on connectionOk.
+     */
+    terminate(): void;
+    /** Trigger a recovery of the connection. This should be called if an issue is detected in the logic
+     * outside of the iterator (e.g. if the ping call fails), because the connection used internally
+     * in this object cannot reliably detect disconnects.
+     */
+    reconnect(): void;
+    /** Turns to false while we're trying to reconnect. */
+    connectionOk: ObservableValue<boolean>;
+};
+export declare const createTransactionReceiver: (documentService: Pick<RetryingClient<typeof DocumentService>, "attach">, projectName: string, opts?: {
+    backoffMs?: number;
+}) => TransactionReceiver;

package/dist/document/backend/document-service/connection/transaction-receiver.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/document/backend/document-service/connection/transaction-sender.d.ts

@@ -0,0 +1,17 @@
+import { DocumentService } from '../../../../gen/audiotool/document/v1/document_service_connect';
+import { Transaction } from '../../../../gen/audiotool/document/v1/document_service_pb';
+import { RetryingClient } from '../../../../utils/grpc/retrying-client';
+import { ObservableValue } from '../../../../utils/observable-notifier-value';
+
+export type TransactionSender = {
+    sendNextTransaction: (t: Transaction) => Promise<string | undefined>;
+    /** Turns to false if sending is temporarily interrupted. */
+    connectionOk: ObservableValue<boolean>;
+    /** Terminate this sender. This will cause all sendNextTransaction calls
+     * to throw. The promise will resolve once the last transaction has been
+     * confirmed as received by the backend, and the sendNextTransaction
+     * methods of all pending transactions have been resolved.
+     */
+    terminate: () => Promise<void>;
+};
+export declare const createTransactionSender: (documentService: Pick<RetryingClient<typeof DocumentService>, "applyTransactions">, projectName: string) => TransactionSender;

package/dist/document/backend/document-service/connection/transaction-sender.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/document/backend/document-service/consolidator.d.ts

@@ -1,5 +1,6 @@
 import { Transaction } from '../../../gen/audiotool/document/v1/document_service_pb';
 import { WasmDocumentState } from '../create-wasm-document-state';
+import { ReadonlyTransaction } from '../gateway';
 
 /**
  * This class can be used to "consolidate" two transaction histories in such a way that
@@ -28,5 +29,5 @@ export declare class NexusStateConsolidator {
     /** new rejected transactions received from the document service. Must be a subset of `newOutgoing`. */
     newReceivedRejected: Set<string>, 
     /** new locally created transactions */
-    newCreated: Transaction[]): Transaction[];
+    newCreated: Transaction[]): ReadonlyTransaction[];
 }

package/dist/document/backend/document-service/gateway.d.ts

@@ -1,36 +1,22 @@
-import { Transaction } from '../../../gen/audiotool/document/v1/document_service_pb';
-import { ObservableValue } from '../../../utils/observable-notifier-value';
 import { NexusGateway } from '../gateway';
+import { DocumentService } from '../../../gen/audiotool/document/v1/document_service_connect';
+import { RetryingClient } from '../../../utils/grpc/retrying-client';
 import { WasmDocumentState } from '../create-wasm-document-state';
-import { DocumentServiceWrapper } from './wrapper/wrapper';
 
-/** A gateway that is connected to some collab backend that might:
- * * reject transaction
- * * reorder transactions
- * * interleave transactions with transactions of other clients
+/** Collab gateway returns a gateway that syncs with a document service.
  */
-export declare class CollabGateway implements NexusGateway {
-    #private;
-    /**
-     * Some stats, useful for debugging.
-     */
-    static readonly stats: {
-        numReceivedCtr: number;
-        numConfirmedCtr: number;
-        numQueuedCtr: number;
-        numRejectedCtr: number;
-    };
-    readonly blocked: ObservableValue<boolean>;
-    constructor({ documentService, state, logOutgoingTransactions, logIncomingTransactions, logConsolidatedTransactions, logRejectedTransactions, }: {
-        documentService: DocumentServiceWrapper;
-        state: WasmDocumentState;
-        logOutgoingTransactions?: boolean;
-        logIncomingTransactions?: boolean;
-        logConsolidatedTransactions?: boolean;
-        logRejectedTransactions?: boolean;
-    });
-    /** Send a transaction to the document service. */
-    send(t: Transaction): void;
-    /** Receive new transactions from the backend, already consolidated with the local change history.*/
-    synchronize(): Transaction[];
-}
+export declare const createCollabGateway: (documentService: RetryingClient<typeof DocumentService>, state: WasmDocumentState, projectName: string, opts?: {
+    logOutgoingTransactions?: boolean;
+    logIncomingTransactions?: boolean;
+    logConsolidatedTransactions?: boolean;
+    logRejectedTransactions?: boolean;
+}) => NexusGateway;
+/** Statistics for debugging - global singleton for easy of access.
+ * Won't be correct if multiple gateways are created.
+ */
+export declare const debugStatistics: {
+    numReceivedCtr: number;
+    numConfirmedCtr: number;
+    numQueuedCtr: number;
+    numRejectedCtr: number;
+};

package/dist/document/backend/gateway.d.ts

@@ -1,6 +1,17 @@
-import { Transaction } from '../../gen/audiotool/document/v1/document_service_pb';
+import { Modification, Transaction } from '../../gen/audiotool/document/v1/document_service_pb';
 import { ObservableValue } from '../../utils/observable-notifier-value';
 
+/** A read only variant of a transaction that is returned by {@link NexusGateway.synchronize}.
+ *
+ * It's important that the gateway doesn't have to clone every transaction for performance reasons,
+ * but the returned transactions must also never be modified by the caller. This type
+ * allows us to enforce this.
+ */
+export type ReadonlyTransaction = {
+    readonly id: string;
+    readonly commitIndex: number;
+    readonly modifications: readonly Modification[];
+};
 /**
  * This is the interface the {@link NexusDocument} uses to sync itself with
  * a state from some "backend". This could be a server, local storage,
@@ -15,6 +26,8 @@ export interface NexusGateway {
      */
     send(t: Transaction): void;
     /** Fetch new transactions that should be immediately applied to the document to sync with upstream.
+     *
+     * The returned transactions MUST NOT be modified by the caller.
      *
      * This function must only be called after all local transactions created since the last call
      * to {@link synchronize} have been sent with {@link send}.
@@ -29,9 +42,16 @@ export interface NexusGateway {
      * one transaction. If the document state is empty, that transaction can be empty. The studio
      * will show the loading spinner until the first transaction is received.
      */
-    synchronize(): Transaction[];
+    synchronize(): ReadonlyTransaction[];
     /** This becomes true when the gateway is blocked in some way from syncing with upstream state.
      * The document should be locked in this case to prevent data loss.
      */
     blocked: ObservableValue<boolean>;
+    /** Terminate the gateway. This will have the following effect:
+     * * `send` will throw
+     * * `synchronize` will return an empty array
+     *
+     * The promise will resolve once the last sent transaction has been confirmed as received by the backend.
+     */
+    terminate(): Promise<void>;
 }

package/dist/document/backend/validator.d.ts

@@ -7,4 +7,6 @@ import { Modification } from '../../gen/audiotool/document/v1/document_service_p
  */
 export interface NexusValidator {
     validate(mod: Modification): string | undefined;
+    /** terminate causes {@link validate} to throw. */
+    terminate(): void;
 }

package/dist/document/document.d.ts

@@ -1,8 +1,7 @@
-import { Modification, Transaction } from '../gen/audiotool/document/v1/document_service_pb';
-import { EntityTypes } from '../gen/audiotool/document/v1/utils/types';
 import { Notifier } from '../utils/observable-notifier';
-import { NexusGateway } from './backend/gateway';
+import { NexusGateway, ReadonlyTransaction } from './backend/gateway';
 import { NexusValidator } from './backend/validator';
+import { Modification, Transaction } from '../gen/audiotool/document/v1/document_service_pb';
 import { EntityTypeKey } from './entity-utils';
 import { NexusEventManager } from './event-manager';
 import { EntityQuery } from './query/entity';
@@ -100,16 +99,6 @@ export declare class NexusDocument {
          */
         actionId?: symbol;
     }>;
-    /** Public field to query the entities in the document.
-     *
-     * @deprecated Don't use this field, as it can cause race conditions on the nexus document.
-     *
-     * Instead, use
-     * * for building a transaction: {@link TransactionBuilder.entities}
-     * * for other purposes, being aware of caveats: {@link NexusDocument.queryEntitiesWithoutLock}
-     *
-     */
-    readonly entities: EntityQuery<keyof EntityTypes>;
     /**
      * This flag is set to true if {@link takeTransactions} is called. Before that, no transactions
      * from the backend are processed, and no transactions are allowed to be created from the frontend.
@@ -139,7 +128,9 @@ export declare class NexusDocument {
      * Note that every transaction by default is undoable, unless the flag in {@link TransactionOptions} is set to false.
      * @returns: {@link TransactionBuilder}
      */
-    createTransaction(opts?: TransactionOptions): Promise<TransactionBuilder>;
+    createTransaction(opts?: TransactionOptions, 
+    /** @internal allows skipping of taking the transaction lock */
+    _takeTransactionLock?: boolean): Promise<TransactionBuilder>;
     /**
      * A helper method for small transactions.
      *
@@ -169,15 +160,33 @@ export declare class NexusDocument {
     takeTransactions(props?: {
         validator?: NexusValidator;
         gateway?: NexusGateway;
+        /** if a project template should be loaded on startup, pass a promise that resolves to the transaction */
+        templateTransaction?: Promise<Transaction>;
     }): Promise<void>;
     /** Apply a transaction that doesn't originate from this document. Yields to the browser
      * scheduler every few modifications applied to make sure we don't block the main thread
      * for too long for big transactions. Throws if the transaction lock isn't taken.
+     *
      */
-    applyIncomingTransactions(ts: Transaction[]): Promise<void>;
+    _applyIncomingTransactions(ts: ReadonlyTransaction[], 
+    /** @internal */
+    opts?: {
+        /** This can be false if the transaction lock is already held already when calling from the outside.
+         * The method will throw if takeTransactionLock is false and the lock is not held.
+         */
+        _takeTransactionLock?: boolean;
+    }): Promise<void>;
     /** For debugging purposes */
     getStats(): {
         entities: number;
         references: number;
     };
+    /** Stop the document from syncing. This will have the following effect:
+     * First, all pending `modify` and `createTransaction` calls will finish.
+     * The modifications they create will be synced with the backend, and the document is locked down.
+     *
+     * After this, calling `modify` or `createTransaction` will throw an error. The only property that
+     * can still be accessed is `queryEntities`. The document can be thrown away safely after this.
+     */
+    terminate(): Promise<void>;
 }

package/dist/document/event-manager.d.ts

@@ -175,6 +175,11 @@ export declare class NexusEventManager {
     from: NexusLocation) => void): Terminable;
     /** @internal */
     _dispatchStopPointingTo(to: NexusLocation, from: NexusLocation): void;
+    /**
+     * @internal
+     *
+     * Removes all event listeners.*/
+    _clear(): void;
     /**
      * @internal
      * Some stats for debugging. Static for easy access. This method can get quite slow, 6.5ms measured

package/dist/document/mock/mock-document-state.d.ts

@@ -3,4 +3,5 @@ import { Transaction } from '../../gen/audiotool/document/v1/document_service_pb
 
 export declare class MockNexusDocumentState implements WasmDocumentState {
     applyTransaction(t: Transaction): string | Transaction;
+    terminate(): void;
 }

package/dist/document.js

@@ -1,4 +1,4 @@
-import { g as e, s as t, a as c } from "./get-schema-location-details-BSMUliFD.js";
+import { g as e, s as t, a as c } from "./get-schema-location-details-CI3Fi5PK.js";
 import { T as h } from "./opt_pb-Dp9pF04Q.js";
 export {
   h as TargetType,

package/dist/{get-schema-location-details-BSMUliFD.js → get-schema-location-details-CI3Fi5PK.js}

@@ -1,4 +1,4 @@
-import { t as o, a as d } from "./lang-KJQpoj7q.js";
+import { t as o, a as d } from "./lang-K-8hAzE4.js";
 import { e as f } from "./types-Cztu157p.js";
 import { ScalarType as e } from "@bufbuild/protobuf";
 const g = {

package/dist/{observable-notifier-value-pw47I_2-.js → hash-map-CMrPM1s6.js}

@@ -3,16 +3,86 @@ var v = (i) => {
 };
 var M = (i, e, s) => e.has(i) || v("Cannot " + s);
 var t = (i, e, s) => (M(i, e, "read from private field"), s ? s.call(i) : e.get(i)), h = (i, e, s) => e.has(i) ? v("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(i) : e.set(i, s), o = (i, e, s, r) => (M(i, e, "write to private field"), r ? r.call(i, s) : e.set(i, s), s);
-var l, m, f;
+var l;
+class A {
+  constructor() {
+    h(this, l, /* @__PURE__ */ new Set());
+  }
+  // A set allows us to remove while iterating
+  subscribe(e) {
+    return t(this, l).add(e), { terminate: () => t(this, l).delete(e) };
+  }
+  notify(e) {
+    t(this, l).forEach((s) => s(e));
+  }
+  terminate() {
+    t(this, l).clear();
+  }
+}
+l = new WeakMap();
+var f, c, g;
 class E {
+  constructor(e) {
+    h(this, f, new A());
+    h(this, c);
+    h(this, g, V(t(this, f)));
+    o(this, c, e);
+  }
+  getValue() {
+    return t(this, g).call(this), t(this, c);
+  }
+  setValue(e) {
+    t(this, c) !== e && (o(this, c, e), t(this, f).notify(e));
+  }
+  subscribe(e, s = !1) {
+    return s && e(t(this, c)), t(this, f).subscribe(e);
+  }
+  terminate() {
+    t(this, f).terminate();
+  }
+}
+f = new WeakMap(), c = new WeakMap(), g = new WeakMap();
+var u, y, n;
+class N {
+  constructor(e) {
+    h(this, u, new A());
+    h(this, y, V(t(this, u)));
+    h(this, n);
+    o(this, n, e ?? /* @__PURE__ */ new Map());
+  }
+  /** Subscribe to updates of the set */
+  subscribe(e, s = !1) {
+    return s && e(t(this, n)), t(this, u).subscribe(() => e(t(this, n)));
+  }
+  /** Get the underlying map. Readonly because changing it won't trigger updates. */
+  getValue() {
+    return t(this, y).call(this), t(this, n);
+  }
+  set(e, s) {
+    return t(this, n).set(e, s), t(this, u).notify(), this;
+  }
+  delete(e) {
+    const s = t(this, n).delete(e);
+    return s && t(this, u).notify(), s;
+  }
+  clear() {
+    const e = t(this, n).size > 0;
+    t(this, n).clear(), e && t(this, u).notify();
+  }
+}
+u = new WeakMap(), y = new WeakMap(), n = new WeakMap();
+const V = (i) => () => {
+};
+var d, m, b;
+class T {
   /** if `warnAfterMs` is set, the lock will emit a warning if a call to `lock.acquire()
    * tok more than `warnAfterMs` milliseconds.
    */
   constructor(e) {
-    h(this, l, !1);
+    h(this, d, !1);
     h(this, m, []);
-    h(this, f);
-    o(this, f, (e == null ? void 0 : e.warnAfterMs) ?? void 0);
+    h(this, b);
+    o(this, b, (e == null ? void 0 : e.warnAfterMs) ?? void 0);
   }
   /**
    * Wait until no other async thread holds a lock, then returns a lock.
@@ -36,17 +106,17 @@ class E {
   async acquire() {
     let e = () => {
     };
-    t(this, f) !== void 0 && (e = k(
-      t(this, f),
-      `Waited for lock.acquire() for more than ${t(this, f)} ms, deadlock?`
-    )), t(this, l) && await new Promise((r) => t(this, m).push(r)), e(), o(this, l, !0);
+    t(this, b) !== void 0 && (e = k(
+      t(this, b),
+      `Waited for lock.acquire() for more than ${t(this, b)} ms, deadlock?`
+    )), t(this, d) && await new Promise((r) => t(this, m).push(r)), e(), o(this, d, !0);
     let s = !1;
     return {
       release: () => {
         var r;
         if (s)
           throw new Error("Lock already released");
-        s = !0, t(this, m).length > 0 ? (r = t(this, m).shift()) == null || r() : o(this, l, !1);
+        s = !0, t(this, m).length > 0 ? (r = t(this, m).shift()) == null || r() : o(this, d, !1);
       }
     };
   }
@@ -88,36 +158,18 @@ class E {
    * without `await`ing the `lock.acquire()`.
    */
   get locked() {
-    return t(this, l);
+    return t(this, d);
   }
 }
-l = new WeakMap(), m = new WeakMap(), f = new WeakMap();
+d = new WeakMap(), m = new WeakMap(), b = new WeakMap();
 const k = (i, e) => {
   const s = setTimeout(() => {
     console.warn(e), console.trace("Waited here:");
   }, i);
   return () => clearTimeout(s);
-};
-var d;
-class A {
-  constructor() {
-    h(this, d, /* @__PURE__ */ new Set());
-  }
-  // A set allows us to remove while iterating
-  subscribe(e) {
-    return t(this, d).add(e), { terminate: () => t(this, d).delete(e) };
-  }
-  notify(e) {
-    t(this, d).forEach((s) => s(e));
-  }
-  terminate() {
-    t(this, d).clear();
-  }
-}
-d = new WeakMap();
-const w = Symbol();
+}, w = Symbol();
 var a;
-class N {
+class _ {
   constructor() {
     /** Maps the hash of a key to both key and value */
     h(this, a, /* @__PURE__ */ new Map());
@@ -165,64 +217,11 @@ class N {
   }
 }
 a = new WeakMap();
-var b, c, g;
-class T {
-  constructor(e) {
-    h(this, b, new A());
-    h(this, c);
-    h(this, g, V(t(this, b)));
-    o(this, c, e);
-  }
-  getValue() {
-    return t(this, g).call(this), t(this, c);
-  }
-  setValue(e) {
-    t(this, c) !== e && (o(this, c, e), t(this, b).notify(e));
-  }
-  subscribe(e, s = !1) {
-    return s && e(t(this, c)), t(this, b).subscribe(e);
-  }
-  terminate() {
-    t(this, b).terminate();
-  }
-}
-b = new WeakMap(), c = new WeakMap(), g = new WeakMap();
-var u, y, n;
-class _ {
-  constructor(e) {
-    h(this, u, new A());
-    h(this, y, V(t(this, u)));
-    h(this, n);
-    o(this, n, e ?? /* @__PURE__ */ new Map());
-  }
-  /** Subscribe to updates of the set */
-  subscribe(e, s = !1) {
-    return s && e(t(this, n)), t(this, u).subscribe(() => e(t(this, n)));
-  }
-  /** Get the underlying map. Readonly because changing it won't trigger updates. */
-  getValue() {
-    return t(this, y).call(this), t(this, n);
-  }
-  set(e, s) {
-    return t(this, n).set(e, s), t(this, u).notify(), this;
-  }
-  delete(e) {
-    const s = t(this, n).delete(e);
-    return s && t(this, u).notify(), s;
-  }
-  clear() {
-    const e = t(this, n).size > 0;
-    t(this, n).clear(), e && t(this, u).notify();
-  }
-}
-u = new WeakMap(), y = new WeakMap(), n = new WeakMap();
-const V = (i) => () => {
-};
 export {
-  E as A,
-  N as H,
-  _ as M,
+  T as A,
+  _ as H,
+  N as M,
   A as N,
-  T as V,
+  E as V,
   w as h
 };