@ultimat3/realtime 27.6.0 → 27.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "27.6.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.6.0",
-    "@ultimat3/entity": "27.6.0",
-    "@ultimat3/policy": "27.6.0",
-    "@ultimat3/query": "27.6.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/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