@audiotool/nexus 0.0.10 → 0.0.11

package/dist/audiotool-client.d.ts

@@ -29,22 +29,10 @@ export type AudiotoolClient = {
      * @returns Promise resolving to a SyncedDocument instance
      */
     createSyncedDocument: (opts: {
-        /** Run in online mode, which means the document state is synced in real time. */
-        mode: "online";
         /** The project to sync to; this can be anything containing a project's UUID, e.g. the URL of the studio
          * when the project is open in the browser.
          */
         project: string;
-    } | {
-        /** Run in offline mode, i.e. not synced to any particular project.
-         *
-         * All changes are discarded on reload.
-         */
-        mode: "offline";
-        /** Whether transaction validation is on. If off, fewer transaction errors will occur,
-         * but the document might not get accepted by the backend if connecting to a project.
-         */
-        validated: boolean;
     }) => Promise<SyncedDocument>;
     /**
      * Collection of Audiotool API service clients.

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

@@ -41,8 +41,12 @@ export interface NexusGateway {
      * This function must indicate that the current document state was loaded by returning at least
      * 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.
+     *
+     * After the first transaction, the gateway can return "done" to indicate that no further transactions
+     * will be returned, which the caller can use as a signal to stop polling. This is useful in situations
+     * where it's known that no synchronization transactions will ever be returned, such as when running in offline mode.
      */
-    synchronize(): ReadonlyTransaction[];
+    synchronize(): ReadonlyTransaction[] | "done";
     /** 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/exports/index.d.ts

@@ -29,3 +29,5 @@
 export { createAudiotoolClient, type AudiotoolClient, } from '../audiotool-client';
 export type { SyncedDocument } from '../synced-document';
 export { getLoginStatus, type LoginStatus } from '../login-status';
+export { createOfflineDocument } from '../synced-document';
+export type { OfflineDocument } from '../synced-document';

package/dist/index.js

@@ -2297,7 +2297,7 @@ let NexusEventManager = bt;
 const sizeOf = (i) => i.values().reduce((e, t) => e + t.size, 0), getOrDefault = (i, e) => i.get(e) ?? i.set(e, /* @__PURE__ */ new Set()).get(e) ?? throw_(), mockNexusGateway = () => {
   let i = !1, e = !1;
   return {
-    synchronize: () => e ? [] : (e = !0, [new Transaction()]),
+    synchronize: () => e ? "done" : (e = !0, [new Transaction()]),
     send: () => {
       if (i)
         throw new Error("Gateway terminated");
@@ -3306,6 +3306,10 @@ class NexusDocument {
       resolve: r
     } = Promise.withResolvers(), c = asyncInterval(async () => {
       const u = (s(this, M) ?? throw_()).synchronize();
+      if (u === "done")
+        throw new Error(
+          "Gateway returned 'done' before returning the initial transaction."
+        );
       if (u.length === 0)
         return;
       const f = u.flatMap((m) => m.modifications).length;
@@ -3327,6 +3331,10 @@ class NexusDocument {
       if (u.aborted)
         return;
       const f = await s(this, S).acquire(), m = (s(this, M) ?? throw_()).synchronize();
+      if (m === "done") {
+        d.terminate(), f.release();
+        return;
+      }
       await this._applyIncomingTransactions(m, { _takeTransactionLock: !1 }), f.release();
     }, s(this, Nt));
     g(this, Bt, () => d.terminate());
@@ -3558,8 +3566,19 @@ const DocumentService = {
       kind: MethodKind.Unary
     }
   }
+}, createSyncedDocument = (i, e, t, n) => ({
+  connected: e,
+  createTransaction: () => i.createTransaction(),
+  modify: (o) => i.modify(o),
+  queryEntities: i.queryEntitiesWithoutLock,
+  events: i.events,
+  start: async () => i.takeTransactions({ validator: t, gateway: n }),
+  stop: async () => i.terminate()
+}), createOfflineDocument = async (i) => {
+  const e = (i == null ? void 0 : i.validated) ?? !0 ? await createWasmNexusValidator() : mockNexusValidator(), t = mockNexusGateway(), n = new NexusDocument(), o = new ValueNotifier(!0), r = createSyncedDocument(n, o, e, t);
+  return await r.start(), r;
 }, createOnlineDocument = async (i, e, t) => {
-  var u;
+  var f;
   let n = createWasmNexusValidator();
   const o = await i.projectService.openSession({
     projectName: e
@@ -3569,30 +3588,17 @@ const DocumentService = {
   const r = createRetryingPromiseClient(
     DocumentService,
     createAuthorizedKeepaliveTransport({
-      baseUrl: ((u = o.session) == null ? void 0 : u.documentServiceUrl) ?? throw_("backend returned no document service url"),
+      baseUrl: ((f = o.session) == null ? void 0 : f.documentServiceUrl) ?? throw_("backend returned no document service url"),
       useBinaryFormat: !0,
       getToken: t
     })
-  );
-  await n;
-  const c = createCollabGateway(
+  ), c = await n, l = createCollabGateway(
     r,
     await getWasmDocumentState(),
     e
-  ), l = new NexusDocument(), d = new ValueNotifier(!1);
-  return c.blocked.subscribe((f) => d.setValue(!f)), createSyncedDocument(l, d, await n, c);
-}, createOfflineDocument = async (i) => {
-  const e = i ? await createWasmNexusValidator() : mockNexusValidator(), t = mockNexusGateway(), n = new NexusDocument(), o = new ValueNotifier(!0);
-  return createSyncedDocument(n, o, e, t);
-}, createSyncedDocument = (i, e, t, n) => ({
-  connected: e,
-  createTransaction: () => i.createTransaction(),
-  modify: (o) => i.modify(o),
-  queryEntities: i.queryEntitiesWithoutLock,
-  events: i.events,
-  start: async () => i.takeTransactions({ validator: t, gateway: n }),
-  stop: async () => i.terminate()
-}), createAudiotoolClient = async ({
+  ), d = new NexusDocument(), u = new ValueNotifier(!1);
+  return l.blocked.subscribe((m) => u.setValue(!m)), createSyncedDocument(d, u, c, l);
+}, createAudiotoolClient = async ({
   authorization: i
 }) => {
   const e = async () => {
@@ -3607,12 +3613,9 @@ const DocumentService = {
   }, t = await createAudiotoolAPI(e);
   return {
     api: t,
-    createSyncedDocument: async (n) => {
-      if (n.mode === "online") {
-        const o = extractProjectName(n.project);
-        return await createOnlineDocument(t, o, e);
-      } else
-        return await createOfflineDocument(n.validated);
+    createSyncedDocument: async ({ project: n }) => {
+      const o = extractProjectName(n);
+      return await createOnlineDocument(t, o, e);
     }
   };
 }, extractProjectName = (i) => {
@@ -3815,5 +3818,6 @@ const DocumentService = {
 };
 export {
   createAudiotoolClient,
+  createOfflineDocument,
   getLoginStatus
 };

package/dist/synced-document.d.ts

@@ -1,8 +1,11 @@
+import { AudiotoolAPI } from './api/audiotool-api';
+import { NexusGateway } from './document/backend/gateway';
+import { NexusValidator } from './document/backend/validator';
+import { NexusDocument } from './document/document';
 import { NexusEventManager } from './document/event-manager';
 import { EntityQuery } from './document/query/entity';
 import { SafeTransactionBuilder, TransactionBuilder } from './document/transaction-builder';
 import { ValueNotifier } from './utils/observable-notifier-value';
-import { AudiotoolAPI } from './api/audiotool-api';
 
 /**
  * An Audiotool project document that synchronizes in real-time with the backend.
@@ -150,6 +153,26 @@ export type SyncedDocument = {
      **/
     stop: () => Promise<void>;
 };
-/** Create an online document. */
+/** Create a SyncedDocument wrapper from a NexusDocument. */
+export declare const createSyncedDocument: (document: NexusDocument, connected: ValueNotifier<boolean>, validator: NexusValidator, gateway: NexusGateway) => SyncedDocument;
+/** An offline version of a {@link SyncedDocument} - starts out completely empty,
+ * and all changes are discarded on reload/shutdown.
+ *
+ * Doesn't have start/stop methods since no syncing is happening.
+ *
+ * Can be safely thrown away after usage.
+ */
+export type OfflineDocument = Omit<SyncedDocument, "start" | "stop">;
+/**
+ * Create a nexus document that is not synced to the backend; all changes are discarded on reload/shutdown.
+ *
+ * The returned document is ready to be modified immediately and can be thrown away without calling start/stop.
+ *
+ * To create a document that is synced with a state from the backend/DAW, use {@link AudiotoolClient.createSyncedDocument}.
+ * */
+export declare const createOfflineDocument: (opts?: {
+    /** Whether validation is enabled. Turning that off results in fewer transaction errors, but can lead to invalid states. */
+    validated?: boolean;
+}) => Promise<OfflineDocument>;
+/** Create a SyncedDocument wrapper that's connected to the backend. */
 export declare const createOnlineDocument: (api: AudiotoolAPI, projectName: string, getToken: () => Promise<string>) => Promise<SyncedDocument>;
-export declare const createOfflineDocument: (validated: boolean) => Promise<SyncedDocument>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audiotool/nexus",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "type": "module",
   "license": "MIT",
   "description": "Audiotool Nexus SDK",