@brass-build/client 0.4.0 → 0.5.0

package/src/document-set-subscription.ts

@@ -0,0 +1,274 @@
+// What lets a listing notice that its set moved (`DocumentList.onChanged`).
+//
+// A feed frame is a trigger and the listing is the truth. The socket feeds
+// that cover a query's references say THAT something in their scope moved;
+// the listing decides what the set is, so folder ancestry, archive members,
+// type matching and the reader's own access are decided in one place, the
+// server's listing, and never re-derived from frames here.
+
+import type {
+  DocumentListing,
+  ListDocumentsQuery,
+} from './documents-namespace.js';
+import type { InputReference } from './hosted-ui.js';
+import type { SubscribeOptions, WsTopicCallback } from './ws-client.js';
+
+/** The slice of the socket client a subscription uses. */
+export interface DocumentSetSocket {
+  subscribe(
+    topic: string,
+    callback: WsTopicCallback,
+    options?: SubscribeOptions,
+  ): () => void;
+}
+
+/**
+ * The feed topic that covers each reference: `organization:<id>`,
+ * `project:<id>`, or `reference:<id>` for a document, which fires when the
+ * document or anything filed under it changes.
+ */
+export function feedTopicsFor(refs: readonly InputReference[]): string[] {
+  const topics = new Set<string>();
+  for (const ref of refs) {
+    if (ref.extent === 'organization') {
+      topics.add(`organization:${ref.organization_id}`);
+    } else if (ref.extent === 'project' && ref.project_id) {
+      topics.add(`project:${ref.project_id}`);
+    } else if (ref.extent === 'document' && ref.doc_id) {
+      topics.add(`reference:${ref.doc_id}`);
+    }
+  }
+  return [...topics];
+}
+
+// Frames the socket client hands a topic's callback that report on the
+// subscription itself rather than on anything in its scope.
+const CONTROL_FRAMES = new Set([
+  'subscribed',
+  'subscribed_ack',
+  'unsubscribed',
+  'not_subscribed',
+  'server_ended',
+  'error',
+  'pong',
+]);
+
+/** Whether a frame on a feed could have moved what a listing answers: any
+ *  data frame does, whatever its type, since the listing decides. */
+export function frameCouldMoveSet(frame: unknown): boolean {
+  if (frame === null || typeof frame !== 'object') return false;
+  const type = (frame as { type?: unknown }).type;
+  return typeof type === 'string' && !CONTROL_FRAMES.has(type);
+}
+
+/** Whether two listings differ, keyed by `doc_id`: a document joined, left,
+ *  or has a different `updated_at` or work `status`. */
+export function listingsDiffer(
+  previous: readonly DocumentListing[],
+  next: readonly DocumentListing[],
+): boolean {
+  if (previous.length !== next.length) return true;
+  const before = new Map(previous.map((d) => [d.doc_id, d]));
+  return next.some((doc) => {
+    const was = before.get(doc.doc_id);
+    return was === undefined || was.updated_at !== doc.updated_at || !sameStatus(was.status, doc.status);
+  });
+}
+
+// An import that fails writes its status without moving the stamp, so the
+// status is compared as well.
+function sameStatus(a: DocumentListing['status'], b: DocumentListing['status']): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.pending === b.pending && a.blocking === b.blocking && a.message === b.message;
+}
+
+/**
+ * How long a trigger waits before listing, so a burst of frames (a move
+ * stamps the document and nudges both containers) is one listing.
+ */
+export const RELIST_COALESCE_MS = 250;
+
+/** The longest the first listing waits for its feeds to be established. */
+export const FEED_WAIT_MS = 3_000;
+
+/**
+ * Watch the set `query` lists and call `listener` whenever a listing differs
+ * from the last one, starting from `initial`. Returns the stop function.
+ */
+export function watchDocumentSet(args: {
+  query: ListDocumentsQuery;
+  list: (query: ListDocumentsQuery) => Promise<DocumentListing[]>;
+  socket: DocumentSetSocket | undefined;
+  listener: () => void;
+  initial: DocumentListing[];
+}): () => void {
+  const { query, list, socket, listener } = args;
+  let stopped = false;
+  let last = args.initial;
+  let inFlight = false;
+  let again = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const relist = async (): Promise<void> => {
+    if (stopped) return;
+    if (inFlight) {
+      // A frame that lands while a listing is out may describe a write that
+      // listing already missed, so one more follows it.
+      again = true;
+      return;
+    }
+    inFlight = true;
+    try {
+      const next = await list(query);
+      if (stopped) return;
+      const moved = listingsDiffer(last, next);
+      last = next;
+      if (moved) listener();
+    } catch (error) {
+      // The watch keeps its last answer and lists again on the next trigger.
+      if (!stopped) console.error('Brass.documents.list:', error);
+    } finally {
+      inFlight = false;
+      if (again && !stopped) {
+        again = false;
+        schedule();
+      }
+    }
+  };
+
+  const schedule = (): void => {
+    // Before the first listing, that listing answers whatever moved.
+    if (stopped || !firstListed || timer !== null) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void relist();
+    }, RELIST_COALESCE_MS);
+  };
+
+  // The first listing waits for the feeds to be established, so a write
+  // landing between that listing and the subscription cannot fall between
+  // them. A feed the socket refuses, or one that never answers, stops being
+  // waited for rather than holding the first answer back.
+  const awaiting = new Set<string>();
+  let firstListed = false;
+  const listFirst = (): void => {
+    if (firstListed) return;
+    firstListed = true;
+    if (firstTimer !== null) clearTimeout(firstTimer);
+    void relist();
+  };
+  const settled = (topic: string): void => {
+    awaiting.delete(topic);
+    if (awaiting.size === 0) listFirst();
+  };
+
+  const unsubscribes: Array<() => void> = [];
+  const topics = socket ? feedTopicsFor(query.from ?? []) : [];
+  for (const topic of topics) awaiting.add(topic);
+  let firstTimer: ReturnType<typeof setTimeout> | null =
+    topics.length > 0 ? setTimeout(listFirst, FEED_WAIT_MS) : null;
+  for (const topic of topics) {
+    unsubscribes.push(
+      socket!.subscribe(
+        topic,
+        (frame) => {
+          if (frameCouldMoveSet(frame)) schedule();
+        },
+        {
+          onSubscribed: ({ resubscribed }) => {
+            // Frames fanned out while the socket was down are gone, so a
+            // re-established feed is answered with a listing.
+            if (resubscribed) schedule();
+            else settled(topic);
+          },
+          onEnded: () => settled(topic),
+        },
+      ),
+    );
+  }
+  if (topics.length === 0) listFirst();
+
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer !== null) clearTimeout(timer);
+    if (firstTimer !== null) clearTimeout(firstTimer);
+    for (const unsubscribe of unsubscribes) unsubscribe();
+  };
+}
+
+/** A listing, as `Brass.documents.list` returns it. */
+export interface DocumentList {
+  /** The set as it stood when it was listed. */
+  readonly documents: DocumentListing[];
+  /** Whether the set has moved since: a document joined it, left it, or
+   *  changed (its `updated_at` or work `status`). List again to see how. */
+  readonly changed: boolean;
+  /** Fires once, when the set moves. The set is watched only while a
+   *  listener is registered and until `close`; throws after `close`. */
+  onChanged(cb: () => void): () => void;
+  close(): void;
+}
+
+export function createDocumentList(args: {
+  documents: DocumentListing[];
+  query: ListDocumentsQuery;
+  list: (query: ListDocumentsQuery) => Promise<DocumentListing[]>;
+  socket: DocumentSetSocket | undefined;
+}): DocumentList {
+  let changed = false;
+  let closed = false;
+  let stopWatching: (() => void) | null = null;
+  const listeners = new Set<() => void>();
+  const stopWatch = (): void => {
+    stopWatching?.();
+    stopWatching = null;
+  };
+  const markChanged = (): void => {
+    if (changed || closed) return;
+    changed = true;
+    stopWatch();
+    const fire = [...listeners];
+    listeners.clear();
+    for (const cb of fire) {
+      try {
+        cb();
+      } catch (err) {
+        console.error('Brass: an onChanged listener threw', err);
+      }
+    }
+  };
+  const set: DocumentList = {
+    documents: args.documents,
+    get changed() {
+      return changed;
+    },
+    onChanged(cb) {
+      if (closed) throw new Error('DocumentList is closed');
+      if (changed) {
+        queueMicrotask(() => {
+          if (!closed) cb();
+        });
+        return () => {};
+      }
+      listeners.add(cb);
+      stopWatching ??= watchDocumentSet({
+        query: args.query,
+        list: args.list,
+        socket: args.socket,
+        initial: args.documents,
+        listener: markChanged,
+      });
+      return () => {
+        listeners.delete(cb);
+        if (listeners.size === 0) stopWatch();
+      };
+    },
+    close() {
+      closed = true;
+      listeners.clear();
+      stopWatch();
+    },
+  };
+  return set;
+}

package/src/document-signals.ts

@@ -67,8 +67,10 @@ export interface DocumentDriveStatus {
   driveName: string;
   // The divergence state. `ahead` / `diverged` mean unpublished local edits.
   state: DocumentDriveTrackingState;
-  // True when publishing would do something (local edits to save back and the
-  // link is not broken): the cue to surface a "Publish" affordance.
+  // True when publishing would do something now, as the server decides it:
+  // edits the drive takes and something here can write, or a rename or move
+  // to carry, on an unbroken link with no publish in flight. The cue to
+  // surface a "Publish" affordance.
   canPush: boolean;
   // Server-authored short pill text (`null` when nothing worth surfacing).
   label: string | null;
@@ -81,9 +83,14 @@ export interface DocumentDriveStatus {
   // (the file-roundtrip path), so an app can warn that the source's newer
   // version will be replaced, not merged.
   pushReplacesRemote: boolean;
+  /** @internal True when the drive keeps every prior version of the item,
+   *  so a version a publish replaces stays in the item's history on the
+   *  drive. The SDK's own drive surface words its publish confirm from it. */
+  keepsPriorVersions: boolean;
   // Whether the link round-trips (`two_way`) or only imports (`import_only`).
-  // On `import_only`, `canPush` is always false; an app surfaces the class so
-  // a one-way import doesn't read as a live two-way mirror.
+  // An `import_only` link publishes no content, so `canPush` is true there
+  // only for a rename or a move; an app surfaces the class so a one-way
+  // import doesn't read as a live two-way mirror.
   mirrorDirection: DriveMirrorDirection;
   // Current external head ref, empty when the adapter could not produce one.
   ref: string;
@@ -135,6 +142,9 @@ export interface DrivePublishTarget {
   // The last publish attempt failed, in which case `detail` carries the
   // server's account of why rather than the resting sentence.
   publishFailed: boolean;
+  // The drive does not take this document's file; `detail` says why, and
+  // there is nothing to publish.
+  unpublishable: boolean;
 }
 
 // Each signal is a `createEmitter` composed with the retain / attach / dedup
@@ -178,9 +188,19 @@ export class GoneSignal {
   }
 }
 
+const NO_WORK_STATUS: DocumentWorkStatus = { message: '', pending: false, blocking: false };
+
 // Latest-retained, re-emit-per-phase signal for `doc_status`. Not one-shot:
 // phases arrive repeatedly until terminal (`pending: false`), and the latest
 // is retained so a late subscriber still sees the final state.
+//
+// A notice is the SDK's own status, raised over the platform's work rather
+// than replacing it: `status` reads the notice while one is up, and `work`
+// keeps answering what the platform reported, which is what every SDK-side
+// decision about pending work reads. A work status arriving under a notice
+// still reaches the listeners (the SDK's own import waiters attach here and
+// wait for a terminal one), and the notice is re-emitted straight after it so
+// the last thing a listener hears matches `status`.
 export class WorkStatusSignal {
   private readonly _emitter = createEmitter<DocumentWorkStatus>({
     fireOnAttach: true,
@@ -189,9 +209,19 @@ export class WorkStatusSignal {
       console.error('[Brass] onStatus listener threw:', err);
     },
   });
+  private _work: DocumentWorkStatus | null = null;
+  private _notice: DocumentWorkStatus | null = null;
 
   get status(): DocumentWorkStatus | null {
-    return this._emitter.retained ?? null;
+    return this._notice ?? this._work;
+  }
+
+  get work(): DocumentWorkStatus | null {
+    return this._work;
+  }
+
+  get notice(): DocumentWorkStatus | null {
+    return this._notice;
   }
 
   on(cb: DocumentStatusListener): DocumentStatusUnsubscribe {
@@ -199,7 +229,18 @@ export class WorkStatusSignal {
   }
 
   emit(status: DocumentWorkStatus): void {
+    this._work = status;
     this._emitter.emit(status);
+    if (this._notice !== null) this._emitter.emit(this._notice);
+  }
+
+  // Raise or clear the notice. Clearing hands listeners the work status it
+  // covered, or a terminal empty one when there is none, since a listener
+  // takes a status rather than `null`.
+  setNotice(notice: DocumentWorkStatus | null): void {
+    if (notice === this._notice) return;
+    this._notice = notice;
+    this._emitter.emit(notice ?? this._work ?? NO_WORK_STATUS);
   }
 
   clearListeners(): void {
@@ -335,6 +376,7 @@ function driveStatusEqual(
     a.detail === b.detail &&
     a.broken === b.broken &&
     a.pushReplacesRemote === b.pushReplacesRemote &&
+    a.keepsPriorVersions === b.keepsPriorVersions &&
     a.mirrorDirection === b.mirrorDirection &&
     a.ref === b.ref &&
     a.refUpdatedAt === b.refUpdatedAt &&

package/src/document-streams.ts

@@ -26,12 +26,17 @@ import type {
   DocumentStatusUnsubscribe,
   DocumentWorkStatus,
 } from './document-signals.js';
+import type { InputStatus } from './inputs-status.js';
+import type { InputDocumentHandlers, InputDocumentOptions } from './input-documents.js';
 import type {
   ListHandle,
   MapHandle,
+  MutateOptions,
   OrderedMapHandle,
   TextHandle,
 } from './handle-types.js';
+import type { InputReference } from './hosted-ui.js';
+import type { MarkReadOptions, MarkReadStatus } from './references.js';
 
 // The wiring `Document.stream()` runs on: list/create manifests over
 // HTTP, and open a stream's line (join + WS subscribe) returning the
@@ -80,8 +85,22 @@ export class DocumentStream {
 
   mutate<E extends object = EntityProxy>(
     fn: (d: DocumentMutator<E>) => void,
+    options?: MutateOptions,
   ): void {
-    this._inner.mutate<E>(fn);
+    this._inner.mutate<E>(fn, options);
+  }
+
+  /** Records the documents `key` depends on for this stream; see
+   *  `Document.dependsOn`. A reference to any stream of this document is
+   *  refused. */
+  dependsOn(key: string, refs: readonly InputReference[] | null): void {
+    this._inner.dependsOn(key, refs);
+  }
+
+  /** @internal Records what this reader read for the key `status` reports
+   *  on this stream; see `Document.markRead`. */
+  markRead(status: MarkReadStatus, options?: MarkReadOptions): void {
+    this._inner.markRead(status, options);
   }
 
   roots(): Record<string, RootKind> {
@@ -111,6 +130,12 @@ export class DocumentStream {
     return this._inner.readOnly;
   }
 
+  /** @internal This stream's line's `updated_at` as it was opened; see
+   *  `Document.updatedAt`. */
+  get updatedAt(): string | null {
+    return this._inner.updatedAt;
+  }
+
   // Locally-issued ops on this stream the server has not acked yet. This
   // stream's own line: `doc.savingCount` is the one that adds the streams up,
   // and the default stream's inner IS the document, so reading that here would
@@ -126,14 +151,18 @@ export class DocumentStream {
     return this._inner.atCapacity;
   }
 
-  // The latest opaque work-status for this stream, or `null` when no slow
-  // server-side work is in flight. Render `message` verbatim.
+  /**
+   * The work in flight on this stream, or `null` when there is none. Render
+   * `message` verbatim.
+   */
   get status(): DocumentWorkStatus | null {
     return this._inner.status;
   }
 
-  // Subscribe to this stream's work-status updates. Fires once on attach when
-  // a status is already known.
+  /**
+   * Calls `cb` with every work-status update for this stream, and once on
+   * attach when a status is already known. Returns an unsubscribe.
+   */
   onStatus(cb: DocumentStatusListener): DocumentStatusUnsubscribe {
     return this._inner.onStatus(cb);
   }
@@ -144,23 +173,63 @@ export class DocumentStream {
     return this._inner.onGone(cb);
   }
 
-  // Per-stream undo/redo: each stream keeps its own local-edit stack
-  // (its edits are its own CRDT commits). The doc-level `doc.undo()`
-  // covers only the default stream.
+  /** @internal On a frozen copy: whether this stream has moved since it was
+   *  read. Each stream is its own line, so each is watched on its own. */
+  get changed(): false {
+    return this._inner.changed;
+  }
+
+  /** @internal */
+  onChanged(cb: () => void): () => void {
+    return this._inner.onChanged(cb);
+  }
+
+  /** @internal Typed on `ReadOnlyStream`: loads this stream as it stands now
+   *  on a frozen copy. */
+  reload(): Promise<void> {
+    return this._inner.reload();
+  }
+
+  /** The input files of a key this stream records references under;
+   *  see `Document.subscribeInputDocuments`. A stream's keys are its own,
+   *  apart from the document's and every other stream's. */
+  subscribeInputDocuments(
+    key: string,
+    handlers: InputDocumentHandlers,
+    options?: InputDocumentOptions,
+  ): () => void {
+    return this._inner.subscribeInputDocuments(key, handlers, options);
+  }
+
+  /** @internal The status of a key this stream records references under. */
+  subscribeInputStatus(key: string, cb: (status: InputStatus) => void): () => void {
+    return this._inner.subscribeInputStatus(key, cb);
+  }
+
+  /**
+   * Reverts this stream's part of the newest undo step that touched it,
+   * leaving the document's other streams as they are.
+   * @deprecated Call `doc.undo()`, which reverts the newest step in every
+   * stream it touched.
+   */
   undo(): boolean {
-    return this._inner.undo();
+    return this._inner._replayOwnUndoStep('undo');
   }
 
+  /**
+   * Re-applies this stream's part of the step it most recently undid.
+   * @deprecated Call `doc.redo()`.
+   */
   redo(): boolean {
-    return this._inner.redo();
+    return this._inner._replayOwnUndoStep('redo');
   }
 
-  // Seal the stream's open undo group, so the next local edit starts a
-  // fresh undo step. Local and synchronous (no server call). Call it
-  // when a user operation completes: commits group into one step until
-  // sealed (the same same-stroke collapsing the doc-level undo has), so
-  // an app that never seals gets one giant step per session. The
-  // cross-stream operation recipe in `docs/streams.md` is built on this.
+  /**
+   * Ends the document's open undo step, so the next local edit in any stream
+   * starts a new one.
+   * @deprecated Call `doc.createCheckpoint()` at the end of each user action,
+   * which also ends the step.
+   */
   sealUndoStep(): void {
     this._inner._sealUndoStep();
   }