@ultimat3/realtime 27.5.0 → 27.6.1

package/README.md

@@ -87,7 +87,7 @@ class — stay on `.`.
 | hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
 | channel records, no replicator | `./server` | `recordPublisher` — an app's committed rows as channel `records`, sequenced per producer ([below](#channel-records-with-no-replicator)) |
 | channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
-| first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`: the boot's restore and the open outbox, capped (#506) |
+| first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`, for an island that reads the store or the outbox: the boot's restore and the open outbox, capped (#506). An island taking only `useChannel` / `usePresence` / `useConnection` never awaits it and is never hidden |
 | offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `memoryLocalStore()` |
 | the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "27.5.0",
+  "version": "27.6.1",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -40,10 +40,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.5.0",
-    "@ultimat3/entity": "27.5.0",
-    "@ultimat3/policy": "27.5.0",
-    "@ultimat3/query": "27.5.0",
+    "@ultimat3/core": "27.6.1",
+    "@ultimat3/entity": "27.6.1",
+    "@ultimat3/policy": "27.6.1",
+    "@ultimat3/query": "27.6.1",
     "nats": "2.29.3"
   }
 }

package/src/error-titles.ts

@@ -5,7 +5,10 @@
 // rebuilds a node's refusal by code in `refusalError`, and `page-errors.ts` constructs codes from
 // here without importing it) and by `errors.ts`, so constructing a server refusal registers too.
 
-import { registerErrorCodes } from '@ultimat3/core';
+// From `/page`, never core's barrel: this module is in every island chunk that reaches realtime,
+// and the barrel's own anchors are core's and schema's titles tables — 4,571 B minified of titles
+// no realtime island reads (`page-errors-bundle.test.ts`). The registry is one module either way.
+import { registerErrorCodes } from '@ultimat3/core/page';
 
 /** Codes this package declares and owns. */
 export const REALTIME_OWNED_ERROR_CODES = [

package/src/first-paint-hold.ts

@@ -1,7 +1,7 @@
-// What a realtime island's bootstrap awaits before its `mount` may run (#506, owner option 3): the
-// page boot's disk restore AND the outbox it opened, so the island's first render already carries
-// the overlays a reload rebuilds from the queue — never the server's stale count. Capped, because
-// an IndexedDB that hangs must cost the hold, never the island.
+// What the bootstrap of a realtime island that READS the store or the outbox awaits before `mount`
+// (#506, owner option 3; one that only follows a channel never imports this): the page boot's disk
+// restore AND the outbox it opened, so the first render already carries the overlays a reload
+// rebuilds from the queue. Capped, because an IndexedDB that hangs must cost the hold, never the island.
 
 import { peekOutbox } from './outbox-slot';
 import { pageRealtime } from './page-store';

package/src/pg-array.ts

@@ -1,10 +1,10 @@
-// The Postgres array TEXT literal — `{a,b}`, `{"a,b",NULL}`, `{{1,2},{3,4}}` — and the element
-// type behind an array oid. Split from `pg-values.ts` so that file stays the oid switch and this
-// one stays the grammar; the element decoder arrives as a parameter, so neither imports the other.
+// The element type behind an array type oid. The WAL names only the ARRAY type and carries the
+// value as its TEXT literal (`{a,b}`), while `@ultimat3/entity`'s repository hands an `arrayOf()`
+// column back as a JS array — and a live row and a repository row have to be the same object.
 //
-// It exists because `@ultimat3/entity`'s repository hands an `arrayOf()` column back as a JS array
-// (the driver parses the literal) while the WAL carries the literal itself. A live row and a
-// repository row have to be the same object, so the literal is parsed here rather than shipped.
+// The GRAMMAR of that literal is `@ultimat3/entity`'s `parsePgArray`: the repository reads the
+// same text when a driver leaves an array unparsed, and one grammar has one reader. This file
+// keeps the half only the WAL needs — which element decoder an oid selects.
 
 /**
  * `text[]` -> `text`. The wire names only the ARRAY type, so the element type behind it is a
@@ -41,101 +41,3 @@ const ELEMENT_OF = Object.freeze<Record<number, number>>({
 export function arrayElementOid(typeOid: number): number | undefined {
   return Object.hasOwn(ELEMENT_OF, typeOid) ? ELEMENT_OF[typeOid] : undefined;
 }
-
-/** Where the scan is, so every branch below advances one cursor rather than slicing the text. */
-interface Scan {
-  readonly text: string;
-  at: number;
-}
-
-/**
- * One array literal -> a nested JS array, or `null` when the text is not one this grammar
- * describes. `null` is not an error: a dimension prefix (`[0:2]={…}`), a `DateStyle` this decoder
- * does not read, or a corrupted literal all mean the same thing to the caller — keep the text it
- * arrived as rather than deliver an array that is missing a member.
- *
- * `decode` is the ELEMENT decoder. It never sees a quoted element's quotes or its backslash
- * escapes: an unquoted `NULL` is the null value and a quoted `"NULL"` is the four-character
- * string, which is the one distinction the quoting exists to carry.
- */
-export function parsePgArray<T>(text: string, decode: (raw: string) => T): PgArray<T> | null {
-  const scan: Scan = { text, at: 0 };
-  const parsed = readArray(scan, decode);
-  // Trailing content means the literal was not what this grammar accepted, whatever it parsed.
-  return parsed === null || scan.at !== text.length ? null : parsed;
-}
-
-/** A member is a decoded value, the null member, or — for a multidimensional array — a row of them. */
-export type PgArray<T> = (T | null | PgArray<T>)[];
-
-function readArray<T>(scan: Scan, decode: (raw: string) => T): PgArray<T> | null {
-  if (scan.text[scan.at] !== '{') return null;
-  scan.at += 1;
-  const out: PgArray<T> = [];
-  if (scan.text[scan.at] === '}') {
-    scan.at += 1;
-    return out;
-  }
-  for (;;) {
-    const member = readMember(scan, decode);
-    if (member === FAILED) return null;
-    out.push(member);
-    const next = scan.text[scan.at];
-    scan.at += 1;
-    if (next === '}') return out;
-    if (next !== ',') return null;
-  }
-}
-
-/** A sentinel, because `null` is a legal member and `undefined` would be a second spelling of it. */
-const FAILED = Symbol('pg-array-failed');
-
-function readMember<T>(
-  scan: Scan,
-  decode: (raw: string) => T,
-): T | null | PgArray<T> | typeof FAILED {
-  const head = scan.text[scan.at];
-  if (head === '{') {
-    const nested = readArray(scan, decode);
-    return nested === null ? FAILED : nested;
-  }
-  if (head === '"') {
-    const quoted = readQuoted(scan);
-    return quoted === null ? FAILED : decode(quoted);
-  }
-  const start = scan.at;
-  while (scan.at < scan.text.length) {
-    const char = scan.text[scan.at];
-    if (char === ',' || char === '}') break;
-    // A brace or a quote inside a bare element is a literal this grammar does not describe.
-    if (char === '{' || char === '"') return FAILED;
-    scan.at += 1;
-  }
-  if (scan.at === scan.text.length) return FAILED;
-  const raw = scan.text.slice(start, scan.at);
-  // Unquoted and case-insensitive is the ONLY spelling of the null member; `"NULL"` is a string.
-  return raw.toUpperCase() === 'NULL' ? null : decode(raw);
-}
-
-/** The text between one pair of quotes, with `\\` and `\"` unescaped. `null` if it never closes. */
-function readQuoted(scan: Scan): string | null {
-  scan.at += 1;
-  let out = '';
-  while (scan.at < scan.text.length) {
-    const char = scan.text[scan.at];
-    if (char === '"') {
-      scan.at += 1;
-      return out;
-    }
-    if (char === '\\') {
-      const escaped = scan.text[scan.at + 1];
-      if (escaped === undefined) return null;
-      out += escaped;
-      scan.at += 2;
-      continue;
-    }
-    out += char ?? '';
-    scan.at += 1;
-  }
-  return null;
-}

package/src/pg-values.ts

@@ -11,9 +11,10 @@
 // in the component the first patch reached.
 
 import { renderThrowable } from '@ultimat3/core';
+import { parsePgArray } from '@ultimat3/entity';
 import { ReplicationProtocolError } from './errors';
 import type { JsonValue } from './json';
-import { arrayElementOid, parsePgArray } from './pg-array';
+import { arrayElementOid } from './pg-array';
 
 /**
  * What a row value can be between the WAL and the wire: JSON, plus the two JS shapes a repository