@brass-build/client 0.4.1 → 0.5.0

package/src/page-restore.ts

@@ -0,0 +1,38 @@
+// A page the browser restores from its back-forward cache resumes with the
+// state it was frozen in, and nothing it held can be trusted to still be true.
+// Two things go stale with no event to say so: a link this page was a guest
+// on can have been claimed or revoked while it was frozen, and the person can
+// have signed in or out in the page they navigated to. Either way the page
+// shows someone the wrong document under the wrong identity, so it loads
+// again, which asks both questions afresh.
+
+export interface RestoredPageState {
+  /** The link token this page is a guest on, or null. */
+  guestLinkToken: string | null;
+  /** Whether this page resolved a signed-in person. */
+  signedIn: boolean;
+  /** Whether this browser's stored hint says a session exists for the app. */
+  sessionHinted: boolean;
+}
+
+// Whether a guest link still answers. `null` when the question could not be
+// asked (no network), which keeps the page rather than reloading it offline.
+export type LinkStillOpen = (token: string) => Promise<boolean | null>;
+
+export async function restoredPageIsStale(
+  state: RestoredPageState,
+  linkStillOpen: LinkStillOpen,
+): Promise<boolean> {
+  if (state.guestLinkToken !== null) {
+    return (await linkStillOpen(state.guestLinkToken)) === false;
+  }
+  return state.signedIn !== state.sessionHinted;
+}
+
+// Calls `onRestore` for every show that comes out of the back-forward cache.
+export function onPageRestored(onRestore: () => void): void {
+  if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return;
+  window.addEventListener('pageshow', (event) => {
+    if ((event as { persisted?: boolean }).persisted === true) onRestore();
+  });
+}

package/src/placement.ts

@@ -0,0 +1,54 @@
+// The loop that places a document through the hosted surfaces: run an
+// attempt, open the surface each `needs-*` outcome names, and retry with
+// what it returned. Shared by the session's create and the client's claim of
+// a document created without an account, so the two cannot drift on which
+// surface answers which refusal.
+
+import type {
+  AcquireOrganizationResult,
+  CreateDestinationResult,
+} from './hosted-ui.js';
+
+export interface PlacementSurfaces {
+  acquireOrganization(): Promise<AcquireOrganizationResult | null>;
+  selectCreateDestination(options?: {
+    name?: string;
+  }): Promise<CreateDestinationResult | null>;
+}
+
+// Run `attempt` until the server places the document. `needs-organization`
+// opens the acquire surface and retries with `{ organization_id }`;
+// `needs-destination` opens the destination dialog (pre-filled with `name`)
+// and retries with its opaque result, relayed verbatim. Resolves null when
+// the person dismisses a surface. `onDestination` hears the dialog's result,
+// which also carries the name the person settled on.
+export async function placeThroughHostedSurfaces<R extends { kind: string }>(
+  surfaces: PlacementSurfaces,
+  attempt: (destination: unknown) => Promise<R>,
+  name: string | undefined,
+  onDestination?: (chosen: CreateDestinationResult) => void,
+): Promise<Exclude<R, { kind: 'needs-organization' | 'needs-destination' }> | null> {
+  let destination: unknown = undefined;
+  for (;;) {
+    const result = await attempt(destination);
+    if (result.kind === 'needs-organization') {
+      const acquired = await surfaces.acquireOrganization();
+      if (!acquired) return null;
+      destination = { organization_id: acquired.organization_id };
+      continue;
+    }
+    if (result.kind === 'needs-destination') {
+      const chosen = await surfaces.selectCreateDestination(
+        name !== undefined ? { name } : undefined,
+      );
+      if (chosen === null) return null;
+      onDestination?.(chosen);
+      destination = chosen;
+      continue;
+    }
+    return result as Exclude<
+      R,
+      { kind: 'needs-organization' | 'needs-destination' }
+    >;
+  }
+}

package/src/presence.ts

@@ -23,7 +23,7 @@ export const PRESENCE_PUBLISH_INTERVAL_MS = 100;
  */
 export const PRESENCE_LAYER_MAX_BYTES = 2048;
 
-const PRESENCE_TOPIC_PREFIX = 'presence:doc:';
+export const PRESENCE_TOPIC_PREFIX = 'presence:doc:';
 
 const TEXT_ENCODER = new TextEncoder();
 
@@ -107,7 +107,8 @@ export interface PresenceParticipant {
 
 // The partial payload passed to `presence.set(...)`. Either layer may
 // be present; each is shallow-merged into the client's current self
-// payload, so `set({ cursor })` then `set({ camera })` keeps both.
+// payload, so `set({ cursor })` then `set({ camera })` keeps both. A key
+// set to `undefined` is removed from the layer.
 export interface PresenceSetInput {
   state?: Record<string, unknown>;
   ext?: Record<string, unknown>;
@@ -264,6 +265,19 @@ function splitPresencePayload(payload: unknown): {
   };
 }
 
+// Shallow-merge `input` into a layer. A key set to `undefined` is removed, so
+// the payload held here is exactly the one peers are sent.
+function mergeLayer(
+  current: Record<string, unknown>,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...current, ...input };
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined) delete next[key];
+  }
+  return next;
+}
+
 class PresenceController implements PresenceClient {
   private readonly _topic: string;
   private readonly _roster = new Map<string, PresenceParticipant>();
@@ -349,10 +363,10 @@ class PresenceController implements PresenceClient {
   set(input: PresenceSetInput): void {
     if (this._closed) return;
     if (input.state !== undefined) {
-      this._selfState = { ...this._selfState, ...input.state };
+      this._selfState = mergeLayer(this._selfState, input.state);
     }
     if (input.ext !== undefined) {
-      this._selfExt = { ...this._selfExt, ...input.ext };
+      this._selfExt = mergeLayer(this._selfExt, input.ext);
     }
     this._scheduleSend();
   }
@@ -639,7 +653,9 @@ class PresenceController implements PresenceClient {
     lastSent: Record<string, unknown> | null,
     withheld: PresenceLayer[],
   ): Record<string, unknown> | undefined {
-    if (Object.keys(current).length === 0) return undefined;
+    // A layer emptied by removing its keys still has to reach peers, who
+    // otherwise keep the last one this connection published.
+    if (Object.keys(current).length === 0) return lastSent === null ? undefined : current;
     if (presenceLayerBytes(current) <= PRESENCE_LAYER_MAX_BYTES) return current;
     withheld.push(layer);
     return lastSent ?? undefined;

package/src/read-only-document.ts

@@ -0,0 +1,133 @@
+// The document types an open that cannot write returns, so writing through
+// one is a type error rather than a thrown `mutate`.
+
+import type {
+  ListHandle,
+  MapHandle,
+  OrderedMapHandle,
+  TextHandle,
+} from './handle-types.js';
+import type { OpenDocumentByIdOptions, OpenedDocument } from './open-document.js';
+import type { DocumentUnsubscribe } from './documents.js';
+import type { DocumentStream } from './document-streams.js';
+
+/** A map on a `ReadOnlyDocument`: the reads of `MapHandle`, and no writes. */
+export type ReadOnlyMapHandle<T = unknown> = Omit<MapHandle<T>, 'mutate' | 'map' | 'list'> & {
+  map<U = unknown>(entryKey: string): ReadOnlyMapHandle<U>;
+  list<U = unknown>(entryKey: string): ReadOnlyListHandle<U>;
+};
+
+/** A list on a `ReadOnlyDocument`: the reads of `ListHandle`, and no writes. */
+export type ReadOnlyListHandle<T = unknown> = Omit<ListHandle<T>, 'mutate'>;
+
+/** An ordered map on a `ReadOnlyDocument`, with no writes. */
+export type ReadOnlyOrderedMapHandle<T = unknown> = Omit<
+  OrderedMapHandle<T>,
+  'mutate' | 'insert' | 'move' | 'ordered'
+>;
+
+/** A text on a `ReadOnlyDocument`, with no writes. */
+export type ReadOnlyTextHandle = Omit<TextHandle, 'update'>;
+
+/** Members of a document that write to it. */
+type WritingMembers =
+  | 'mutate'
+  | 'undo'
+  | 'redo'
+  | 'createCheckpoint'
+  | 'setAutoCheckpointIntervalMs'
+  | 'getOrCreateStream'
+  | 'stream'
+  | 'useCanvas'
+  | 'map'
+  | 'list'
+  | 'text'
+  | 'orderedMap'
+  | 'dependsOn'
+  | 'markRead';
+
+/** Members that report writing, which a copy that cannot write never does. */
+type WriterStateMembers = 'savingCount' | 'subscribeUndoState';
+
+/** Members of a stream that write to it. */
+type WritingStreamMembers =
+  | 'mutate'
+  | 'undo'
+  | 'redo'
+  | 'sealUndoStep'
+  | 'map'
+  | 'list'
+  | 'text'
+  | 'orderedMap'
+  | 'dependsOn'
+  | 'markRead';
+
+/** Members whose meaning the update mode decides. */
+type UpdateModeMembers = 'changed' | 'onChanged' | 'reload';
+
+/** One stream of a `ReadOnlyDocument`. */
+export type ReadOnlyStream = Omit<
+  DocumentStream,
+  WritingStreamMembers | 'savingCount' | UpdateModeMembers
+> & {
+  /** On a frozen copy, called when this stream moves past what it last
+   *  loaded, at once if it already has. Each stream is its own line, so each
+   *  is watched on its own. */
+  onChanged(cb: () => void): DocumentUnsubscribe;
+  reload(): Promise<void>;
+  map<T = unknown>(key: string): ReadOnlyMapHandle<T>;
+  list<T = unknown>(key: string): ReadOnlyListHandle<T>;
+  text(key: string): ReadOnlyTextHandle;
+  orderedMap<T = unknown>(mapKey: string, orderKey: string): ReadOnlyOrderedMapHandle<T>;
+};
+
+/**
+ * A document opened with `readOnly: true` or `frozen: true`, with nothing on
+ * it that writes. A document the signed-in person may only view opens
+ * read-only whatever was asked, which `doc.readOnly` reports and a refused
+ * `mutate` throws on.
+ *
+ * A live copy follows every change as it is made. A frozen copy keeps what it
+ * loaded: `onChanged` reports the document moving past it, and `reload()`
+ * loads the document as it stands, under the same handles, whose subscribers
+ * are told what changed.
+ */
+export type ReadOnlyDocument = Omit<
+  OpenedDocument,
+  WritingMembers | WriterStateMembers | UpdateModeMembers
+> & {
+  readonly readOnly: true;
+  /** On a frozen copy, called when the document moves past what this copy
+   *  last loaded (a content edit, an import landing or failing, the document
+   *  being deleted), at once if it already has. Called once per load. A live
+   *  copy never calls it. */
+  onChanged(cb: () => void): DocumentUnsubscribe;
+  /** On a frozen copy, loads the document as it stands now. A live copy
+   *  already holds it, so this resolves at once. */
+  reload(): Promise<void>;
+  map<T = unknown>(key: string): ReadOnlyMapHandle<T>;
+  list<T = unknown>(key: string): ReadOnlyListHandle<T>;
+  text(key: string): ReadOnlyTextHandle;
+  orderedMap<T = unknown>(mapKey: string, orderKey: string): ReadOnlyOrderedMapHandle<T>;
+  stream(name: string): Promise<ReadOnlyStream>;
+};
+
+/** The modes an open or a reopen can ask for. A frozen copy is read-only, so
+ *  `frozen: true` takes no `readOnly: false`. */
+export type OpenModeOptions =
+  | { frozen?: false; readOnly?: boolean }
+  | { frozen: boolean; readOnly?: true };
+
+/** `Brass.openDocumentById`, typed by what the open asks for. */
+export interface OpenDocumentById {
+  (
+    docId: string,
+    options: OpenDocumentByIdOptions & { frozen: true; readOnly?: true },
+  ): Promise<ReadOnlyDocument>;
+  (docId: string, options: OpenDocumentByIdOptions & { readOnly: true }): Promise<ReadOnlyDocument>;
+  (docId: string, options?: OpenDocumentByIdOptions & { frozen?: false }): Promise<OpenedDocument>;
+  (
+    docId: string,
+    options: Omit<OpenDocumentByIdOptions, 'frozen' | 'readOnly'> & OpenModeOptions,
+  ): Promise<OpenedDocument | ReadOnlyDocument>;
+}

package/src/record-paging.ts

@@ -79,8 +79,14 @@ function gunzip(bytes: Uint8Array): Uint8Array {
 export const TAG_FIELD = 'type';
 export const BODY_FIELD = 'params';
 
-/** Root container keys the record store occupies on a document. */
+/** Root container keys the record store occupies on a document, and the one
+ *  `meta` entry that is not paging bookkeeping. Fixed names rather than a
+ *  document's configurable `rootKey`: a record store is one shape wherever it
+ *  is written, so the encoding it is written in cannot change where a reader
+ *  looks for it. */
 export const META_KEY = 'meta';
+export const SCHEMA_VERSION_KEY = 'schema_version';
+export const HEADER_KEY = 'header';
 export const RECORDS_KEY = 'instances';
 export const ORDER_KEY = 'instance_order';
 
@@ -172,9 +178,29 @@ export const PAGE_TAG = '__page__';
  *  holds. */
 export const RESERVED_KEY_PREFIX = 'brass:';
 
-/** Whether `key` names one of the store's own entries rather than a record. */
-export function isReservedKey(key: string): boolean {
-  return key.startsWith(RESERVED_KEY_PREFIX);
+/** Whether `key` in the root map `rootKey` is a paged marker
+ *  (`PAGED_ROOT_PREFIX`). `meta` is a root an app reads and writes like any
+ *  other (an import keeps `schema_version` there), so the markers are hidden
+ *  from every read of it and refused on write: an app that copies or clears
+ *  `meta` generically would otherwise delete one, and every reader after that
+ *  takes the unpaged path over a map holding pages, seeing the store's
+ *  `brass:` keys in place of its records. A `paged:` key in any other root is
+ *  an ordinary record key. */
+export function isPagedMarkerEntry(rootKey: string | null, key: string): boolean {
+  return rootCarriesMarkers(rootKey) && key.startsWith(PAGED_ROOT_PREFIX);
+}
+
+/** Whether the root map `rootKey` is the one the paged markers are kept in,
+ *  so a reader can skip the per-key test on every other root. */
+export function rootCarriesMarkers(rootKey: string | null): boolean {
+  return rootKey === META_KEY;
+}
+
+/** Whether `key` names one of the platform's own entries rather than a record:
+ *  the store's bookkeeping under `RESERVED_KEY_PREFIX` in any root, and, when
+ *  the root is named, a paged marker in `meta`. */
+export function isReservedKey(key: string, rootKey: string | null = null): boolean {
+  return key.startsWith(RESERVED_KEY_PREFIX) || isPagedMarkerEntry(rootKey, key);
 }
 
 /** The one key a reader cannot carry as an ordinary object property.
@@ -197,7 +223,10 @@ const UNCARRIABLE_RECORD_KEY = '__proto__';
  *  is from the key alone. The alternative, escaping, would put the escape on
  *  the read of every key of every map, paged or not, and a store that pages
  *  later cannot escape what it already holds. */
-export function assertUsableRecordKey(key: string): void {
+export function assertUsableRecordKey(
+  key: string,
+  rootKey: string | null = null,
+): void {
   if (key === UNCARRIABLE_RECORD_KEY) {
     throw new Error(
       `Key "${key}" is reserved: a record key cannot be ` +
@@ -205,6 +234,12 @@ export function assertUsableRecordKey(key: string): void {
         `rather than one of its entries.`,
     );
   }
+  if (isPagedMarkerEntry(rootKey, key)) {
+    throw new Error(
+      `Key "${key}" is reserved: a key in "${META_KEY}" cannot start with ` +
+        `"${PAGED_ROOT_PREFIX}", which marks how a collection is stored.`,
+    );
+  }
   if (!isReservedKey(key)) return;
   throw new Error(
     `Key "${key}" is reserved: a record key cannot start with ` +
@@ -257,11 +292,25 @@ export function repackRecord(
   ];
 }
 
-/** The stored value a page triple carries: the value itself for a whole-value
- *  record, else the `{ type, params }` pair a typed one was split into. */
+/**
+ * The stored value a tag and a body carry: the body itself when there is no
+ * tag, else the `{ type, params }` pair a typed record was split into.
+ *
+ * A null tag is not an absent field, it is the statement that this record was
+ * never split: a map holds whatever its writer assigned and an app's own value
+ * has no tag to take off it. Every reader that rebuilds a value from the two
+ * comes through here, because a reader that built the pair unconditionally
+ * would hand an app `{ type: null, params: 5 }` where the same record read out
+ * of a CRDT document is `5`, which is the encoding showing through.
+ */
+export function recordValueOf(tag: string | null, body: unknown): unknown {
+  if (tag === null) return body;
+  return { [TAG_FIELD]: tag, [BODY_FIELD]: body };
+}
+
+/** The stored value a page triple carries. See `recordValueOf`. */
 export function unpackRecord(packed: PackedRecord<unknown>): unknown {
-  if (packed[1] === null) return packed[2];
-  return { [TAG_FIELD]: packed[1], [BODY_FIELD]: packed[2] };
+  return recordValueOf(packed[1], packed[2]);
 }
 
 /** The tag + body a page triple names, for a reader that walks the two
@@ -388,40 +437,120 @@ export function encodePageFromEncoded(
   encoded: string[],
   keys: string[],
 ): EncodedPage {
+  const bytes = encodePageBytes(encoded, keys);
+  return {
+    body: strFromU8(bytes.body, true),
+    keys: strFromU8(bytes.keys, true),
+    chars: bytes.chars,
+  };
+}
+
+/** A page's two stored strings as raw bytes, for a store that holds bytes
+ *  rather than the latin1 strings a loro container needs. */
+export interface EncodedPageBytes {
+  body: Uint8Array;
+  keys: Uint8Array;
+  chars: number;
+}
+
+/** Encode a page to the gzip bytes `encodePageFromEncoded` widens into
+ *  strings. Byte-identical either way, so a page written into a container and
+ *  a page written into a byte store hold the same compressed run. */
+export function encodePageBytes(
+  encoded: string[],
+  keys: string[],
+): EncodedPageBytes {
   const body = '[' + encoded.join(',') + ']';
   return {
-    body: gzipJson(body),
-    keys: gzipJson(JSON.stringify(keys)),
+    body: gzipJsonBytes(body),
+    keys: gzipJsonBytes(JSON.stringify(keys)),
     chars: body.length,
   };
 }
 
-function gzipJson(json: string): string {
-  return strFromU8(gzip(strToU8(json)), true);
+/** Gzip a JSON string to raw bytes. The latin1 string a page container stores
+ *  is these bytes widened; a store that holds bytes directly keeps them as
+ *  they are, so one compressor serves both. */
+export function gzipJsonBytes(json: string): Uint8Array {
+  return gzip(strToU8(json));
 }
 
-/** Parse one of a page's stored strings. Returns null for anything that does
+/** Gunzip bytes holding UTF-8 text. */
+export function gunzipText(bytes: Uint8Array): string {
+  return strFromU8(gunzip(bytes));
+}
+
+/** Parse gzipped JSON bytes as an array. Returns null for anything that does
  *  not decompress to a JSON array, so a reader tolerates a corrupt or stray
  *  page rather than throwing. */
-function decodePageField(value: unknown): unknown[] | null {
-  if (typeof value !== 'string') return null;
+export function decodeGzippedJsonArray(bytes: Uint8Array): unknown[] | null {
   try {
-    const parsed = JSON.parse(strFromU8(gunzip(strToU8(value, true))));
+    const parsed: unknown = JSON.parse(strFromU8(gunzip(bytes)));
     return Array.isArray(parsed) ? (parsed as unknown[]) : null;
   } catch {
     return null;
   }
 }
 
+/** Parse one of a page's stored strings. Returns null for anything that does
+ *  not decompress to a JSON array, so a reader tolerates a corrupt or stray
+ *  page rather than throwing. */
+function decodePageField(value: unknown): unknown[] | null {
+  if (typeof value !== 'string') return null;
+  return decodeGzippedJsonArray(strToU8(value, true));
+}
+
 /** The record keys a page holds, from the page's own `keys` string. Reading
  *  this field alone is what makes learning a store's key locations cost the
  *  keys rather than every record body. */
 export function decodePageKeys(keysField: unknown): string[] {
   const parsed = decodePageField(keysField);
   if (parsed === null) return [];
+  return keyStrings(parsed);
+}
+
+/** The record keys a page holds, from the gzipped bytes of its key list. The
+ *  same answer `decodePageKeys` gives for a container-stored page. */
+export function decodePageKeyBytes(keysBytes: Uint8Array): string[] {
+  const parsed = decodeGzippedJsonArray(keysBytes);
+  if (parsed === null) return [];
+  return keyStrings(parsed);
+}
+
+function keyStrings(parsed: unknown[]): string[] {
   return parsed.filter((k): k is string => typeof k === 'string');
 }
 
+/** Zip a page's decoded key list and `[tag, body]` pairs back into triples. A
+ *  key with no pair (or a pair with no key) is dropped: the two arrays are
+ *  written together and index each other, so a length mismatch means a page
+ *  nothing can read as records. */
+function zipPageRecords(
+  keys: readonly string[],
+  pairs: readonly unknown[],
+): PackedRecord<unknown>[] {
+  const out: PackedRecord<unknown>[] = [];
+  for (let i = 0; i < keys.length && i < pairs.length; i += 1) {
+    const pair = pairs[i];
+    if (!Array.isArray(pair)) continue;
+    if (typeof pair[0] !== 'string' && pair[0] !== null) continue;
+    out.push([keys[i]!, pair[0], pair[1]]);
+  }
+  return out;
+}
+
+/** A page's records from the gzipped bytes of its two stored strings. */
+export function decodePageRecordBytes(
+  keysBytes: Uint8Array,
+  bodyBytes: Uint8Array,
+): PackedRecord<unknown>[] {
+  const keys = decodePageKeyBytes(keysBytes);
+  if (keys.length === 0) return [];
+  const pairs = decodeGzippedJsonArray(bodyBytes);
+  if (pairs === null) return [];
+  return zipPageRecords(keys, pairs);
+}
+
 /** A page's records, zipped back into `[key, tag, body]` triples from the two
  *  strings the page stores. A key with no body (or a body with no key) is
  *  dropped: the two arrays are written together and index each other, so a
@@ -433,14 +562,7 @@ export function decodePageRecords(page: unknown): PackedRecord<unknown>[] {
   if (keys.length === 0) return [];
   const pairs = decodePageField(fields[BODY_FIELD]);
   if (pairs === null) return [];
-  const out: PackedRecord<unknown>[] = [];
-  for (let i = 0; i < keys.length && i < pairs.length; i += 1) {
-    const pair = pairs[i];
-    if (!Array.isArray(pair)) continue;
-    if (typeof pair[0] !== 'string' && pair[0] !== null) continue;
-    out.push([keys[i]!, pair[0], pair[1]]);
-  }
-  return out;
+  return zipPageRecords(keys, pairs);
 }
 
 // How many bodies to weigh when estimating a population's record width. A