@audiotool/nexus 0.0.7 → 0.0.9

package/README.md

@@ -1,37 +1,7 @@
-# Audiotool SDK
+# Audiotool Nexus SDK
 
-Overview of repo:
+Th official Audiotool Nexus SDK, allowing you to connect to a multiplayer session on https://beta.audiotool.com/ and modify projects in real time.
 
-- `src/` source code
-- `src/exports/*.ts` - the entry points of the package
-- `src/docs/` docs `.md` pages
-- `tests` - tests of the package in various platforms (bun, node, ...)
-- `codegen` - code generators executed when running `npm run codegen`
+See the documentation at https://developer.audiotool.com/js-package-documentation/.
 
-Config files currently contain duplicate infos:
-
-- `tsconfig.ts`: path aliases like `@gen/`, `@utils`
-- `vite.config.ts`: same aliases but used by vite's bundler
-- `package.json`: defines what of the `dist/` dir should be exported by package
-- `typedoc.json`: defines what of the unbundled source code should be considered "entry points" of the package
-
-## Running tests in `tests/`:
-
-Add env var `AT_PAT=<pat>` with PAT found at https://developer.audiotool.com/personal-access-tokens.
-
-## Testing the package
-
-To test what the package does when built, create a new project with npm or bun somewhere. Then:
-
-1. in this directory, call `npm/bun link`
-2. in your new directory, call `npm/bun link @audiotool/nexus --save`
-
-When you call `npm run build` here, the other repository will automatically update (`link` creates a dyn link to this repo).
-
-What's finally uploaded to npm can be seen by calling `npm run pack`, which generates a `.tgz` file in `dist/`; this file can then be installed with:
-
-```
-npm/bun install <file>.tgz
-```
-
-What's installed in `node_modules` is what's part of the final package on npm. This should be what's in `dist/`, including the `README.md` copied from `src/docs/README.md`.
+This package is currently at version 0.0.x. Expect breaking changes between minor versions.

package/dist/api.js

@@ -1,8 +1,8 @@
 var d = Object.defineProperty;
 var U = (e, n, s) => n in e ? d(e, n, { enumerable: !0, configurable: !0, writable: !0, value: s }) : e[n] = s;
 var a = (e, n, s) => U(e, typeof n != "symbol" ? n + "" : n, s);
-import { S as m, P as E } from "./audiotool-api-BeiEe46q.js";
-import { A as P, a as A, C as q, i as O, a9 as c, aa as g, az as j, v as G, w as F, _ as L, $ as v, J as K, K as f, am as H, ao as Y, D as w, j as x, y as B, z as h, a4 as J, a5 as V, M, N as b, av as z, aw as Q, aH as $, aI as k, c as y, b as W, d as X, e as Z, ad as ee, ae as se, f as ae, g as te, t as oe, u as ne, Y as re, Z as ie, ar as Re, as as pe, aL as me, aM as le, aF as ue, aG as Ee, G as Ne, L as Ce, h as de, q as Ue, r as Se, H as Te, I as _e, W as De, X as Ie, ak as Pe, al as Ae, ab as qe, ac as Oe, aD as ce, aE as ge, ax as je, ay as Ge, a7 as Fe, a8 as Le, O as ve, o as Ke, l as fe, p as He, m as Ye, E as we, F as xe, B as Be, V as he, ai as Je, ag as Ve, ah as Me, aj as be, an as ze, af as Qe, aA as $e, k as ke, a6 as ye, T as We, U as Xe, x as Ze, a2 as es, a3 as ss, Q as as, R as ts, at as os, au as ns, aN as rs, aO as is, aJ as Rs, aK as ps, aP as ms, aQ as ls, a0 as us, a1 as Es, ap as Ns, aq as Cs, aB as ds, aC as Us, aR as Ss, n as Ts, s as _s } from "./audiotool-api-BeiEe46q.js";
+import { S as m, P as E } from "./audiotool-api-o8DnCQiu.js";
+import { A as P, a as A, C as q, i as O, a9 as c, aa as g, az as j, v as G, w as F, _ as L, $ as v, J as K, K as f, am as H, ao as Y, D as w, j as x, y as B, z as h, a4 as J, a5 as V, M, N as b, av as z, aw as Q, aH as $, aI as k, c as y, b as W, d as X, e as Z, ad as ee, ae as se, f as ae, g as te, t as oe, u as ne, Y as re, Z as ie, ar as Re, as as pe, aL as me, aM as le, aF as ue, aG as Ee, G as Ne, L as Ce, h as de, q as Ue, r as Se, H as Te, I as _e, W as De, X as Ie, ak as Pe, al as Ae, ab as qe, ac as Oe, aD as ce, aE as ge, ax as je, ay as Ge, a7 as Fe, a8 as Le, O as ve, o as Ke, l as fe, p as He, m as Ye, E as we, F as xe, B as Be, V as he, ai as Je, ag as Ve, ah as Me, aj as be, an as ze, af as Qe, aA as $e, k as ke, a6 as ye, T as We, U as Xe, x as Ze, a2 as es, a3 as ss, Q as as, R as ts, at as os, au as ns, aN as rs, aO as is, aJ as Rs, aK as ps, aP as ms, aQ as ls, a0 as us, a1 as Es, ap as Ns, aq as Cs, aB as ds, aC as Us, aR as Ss, n as Ts, s as _s } from "./audiotool-api-o8DnCQiu.js";
 import { B as Is, f as Ps, E as As, F as qs, d as Os, e as cs, I as gs, b as js, L as Gs, P as Fs, a as Ls, S as vs, T as Ks, U as fs, c as Hs, g as Ys, j as ws, m as xs, k as Bs, h as hs, i as Js, l as Vs, p as Ms, s as bs, u as zs } from "./opt_pb-Dp9pF04Q.js";
 import { Message as N, proto3 as o, Timestamp as C } from "@bufbuild/protobuf";
 var R = /* @__PURE__ */ ((e) => (e[e.UNSPECIFIED = 0] = "UNSPECIFIED", e[e.STARTED = 1] = "STARTED", e[e.AUDIO_RENDERING = 3] = "AUDIO_RENDERING", e[e.AUDIO_RENDERED = 4] = "AUDIO_RENDERED", e[e.AUDIO_CONVERTING = 5] = "AUDIO_CONVERTING", e[e.AUDIO_CONVERTED = 6] = "AUDIO_CONVERTED", e[e.FINISHED = 7] = "FINISHED", e))(R || {});

package/dist/{audiotool-api-BeiEe46q.js → audiotool-api-o8DnCQiu.js}

@@ -4,7 +4,7 @@ var a = (i, s, t) => Tr(i, typeof s != "symbol" ? s + "" : s, t);
 import { Message as e, proto3 as r, MethodKind as o, Any as Zt, Timestamp as d, FieldMask as mn, Duration as ur, createRegistry as lr } from "@bufbuild/protobuf";
 import { createConnectTransport as Sr } from "@connectrpc/connect-web";
 import { createClient as wr, ConnectError as Ir, Code as za } from "@connectrpc/connect";
-import { s as gr, t as cr } from "./lang-KJQpoj7q.js";
+import { s as gr, t as cr } from "./lang-BqPY1uAS.js";
 import { a as Er, e as Jr } from "./types-Cztu157p.js";
 const S = class S extends e {
   constructor(t) {

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,6 +1,6 @@
 import { Transaction } from '../../../gen/audiotool/document/v1/document_service_pb';
 import { ObservableValue } from '../../../utils/observable-notifier-value';
-import { NexusGateway } from '../gateway';
+import { NexusGateway, ReadonlyTransaction } from '../gateway';
 import { WasmDocumentState } from '../create-wasm-document-state';
 import { DocumentServiceWrapper } from './wrapper/wrapper';
 
@@ -32,5 +32,5 @@ export declare class CollabGateway implements NexusGateway {
     /** 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[];
+    synchronize(): ReadonlyTransaction[];
 }

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,7 +42,7 @@ 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.
      */

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,12 +160,22 @@ 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;

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-D2lXBgbu.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-D2lXBgbu.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-BqPY1uAS.js";
 import { e as f } from "./types-Cztu157p.js";
 import { ScalarType as e } from "@bufbuild/protobuf";
 const g = {