@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/serve/worker/client/rtdb-listeners.ts

@@ -0,0 +1,337 @@
+/** RTDB value/child listeners and Firebase-compatible `off` registration identity. */
+import type { InboundMessage } from '../protocol.js';
+import { queryIdentifier } from 'pyric/database/internal';
+import { sameRtdbValue } from '../rtdb-value-equality.js';
+import {
+  _defaultLens,
+  closeSubscription,
+  nextSubId,
+  openSnapshotSubscription,
+  stampIssuer,
+} from './core.js';
+import type { ClientPort, RtdbDataSnapshot, Unsubscribe } from './handles.js';
+import {
+  isRtdbQuery,
+  rtdbChild,
+  targetParts,
+  type RtdbTarget,
+} from './rtdb-references.js';
+import {
+  hydrateRtdbSnapshot,
+  makeRtdbSnapshot,
+  valueAt,
+  type RtdbWireEntry,
+} from './rtdb-snapshots.js';
+
+export type RtdbEventType =
+  | 'value'
+  | 'child_added'
+  | 'child_changed'
+  | 'child_removed'
+  | 'child_moved';
+
+interface ListenerRegistration {
+  readonly port: ClientPort;
+  readonly path: string;
+  readonly scope?: string;
+  readonly eventType: RtdbEventType;
+  readonly callback: object;
+  close(): void;
+}
+
+const registrations: ListenerRegistration[] = [];
+
+/** Drop client-side registration identity when the owning app port closes. */
+export function dropRtdbListenersForPort(port: ClientPort): void {
+  for (const registration of [...registrations]) {
+    if (registration.port === port) registration.close();
+  }
+}
+
+function targetScope(target: RtdbTarget): string {
+  if (!isRtdbQuery(target)) return 'default';
+  return queryIdentifier(target._spec);
+}
+
+function removeRegistration(registration: ListenerRegistration): void {
+  const index = registrations.indexOf(registration);
+  if (index >= 0) registrations.splice(index, 1);
+}
+
+function openValueSubscription(
+  target: RtdbTarget,
+  next: (snap: RtdbDataSnapshot) => void,
+  cancelCallbackOrOptions?: ((err: unknown) => void) | { readonly onlyOnce?: boolean },
+  options?: { readonly onlyOnce?: boolean },
+): Unsubscribe {
+  const { ref, query } = targetParts(target);
+  const error = typeof cancelCallbackOrOptions === 'function' ? cancelCallbackOrOptions : undefined;
+  const listenOptions = typeof cancelCallbackOrOptions === 'function'
+    ? options
+    : cancelCallbackOrOptions;
+  const subId = nextSubId();
+  const msg: InboundMessage = _defaultLens
+    ? { t: 'sub', subId, target: { service: 'rtdb', path: ref.path, ...(query ? { query } : {}) }, actAs: _defaultLens }
+    : { t: 'sub', subId, target: { service: 'rtdb', path: ref.path, ...(query ? { query } : {}) } };
+  let fired = false;
+  const opened = openSnapshotSubscription(ref.port, subId, {
+    port: ref.port,
+    next: (wire) => {
+      if (listenOptions?.onlyOnce && fired) return;
+      fired = true;
+      if (listenOptions?.onlyOnce) closeSubscription(ref.port, subId);
+      next(hydrateRtdbSnapshot(ref, wire));
+    },
+    error,
+  }, stampIssuer(msg));
+  if (!opened && error) {
+    queueMicrotask(() => error(new Error('FIREBASE FATAL ERROR: Database has been deleted.')));
+  }
+  return () => closeSubscription(ref.port, subId);
+}
+
+function registerListener(
+  target: RtdbTarget,
+  eventType: RtdbEventType,
+  callback: object,
+  unsubscribe: Unsubscribe,
+): Unsubscribe {
+  const { ref } = targetParts(target);
+  let closed = false;
+  const registration: ListenerRegistration = {
+    port: ref.port,
+    path: ref.path,
+    scope: targetScope(target),
+    eventType,
+    callback,
+    close() {
+      if (closed) return;
+      closed = true;
+      removeRegistration(registration);
+      unsubscribe();
+    },
+  };
+  registrations.push(registration);
+  return registration.close;
+}
+
+export function rtdbOnValue(
+  target: RtdbTarget,
+  next: (snap: RtdbDataSnapshot) => void,
+  cancelCallbackOrOptions?: ((err: unknown) => void) | { readonly onlyOnce?: boolean },
+  options?: { readonly onlyOnce?: boolean },
+  registryCallback: object = next,
+): Unsubscribe {
+  const listenOptions = typeof cancelCallbackOrOptions === 'function'
+    ? options
+    : cancelCallbackOrOptions;
+  let unsubscribe: Unsubscribe = () => {};
+  const rawUnsubscribe = openValueSubscription(target, (snapshot) => {
+    try {
+      next(snapshot);
+    } catch {
+      // Firebase isolates listener exceptions from sibling deliveries.
+    } finally {
+      if (listenOptions?.onlyOnce) queueMicrotask(() => unsubscribe());
+    }
+  }, cancelCallbackOrOptions, options);
+  unsubscribe = registerListener(
+    target,
+    'value',
+    registryCallback,
+    rawUnsubscribe,
+  );
+  return unsubscribe;
+}
+
+type ChildEventKind = 'added' | 'changed' | 'removed' | 'moved';
+
+function directChildren(value: unknown): Record<string, unknown> {
+  if (Array.isArray(value)) {
+    return Object.fromEntries(
+      value.flatMap((child, index) => child == null ? [] : [[String(index), child]]),
+    );
+  }
+  if (value === null || typeof value !== 'object') return {};
+  return value as Record<string, unknown>;
+}
+
+function rtdbKeyCompare(left: string, right: string): number {
+  const integerKey = (key: string): number | null => {
+    if (!/^(0|[1-9]\d*)$/.test(key)) return null;
+    const value = Number(key);
+    return Number.isSafeInteger(value) && value <= 2_147_483_647 ? value : null;
+  };
+  const leftInteger = integerKey(left);
+  const rightInteger = integerKey(right);
+  if (leftInteger !== null && rightInteger !== null) return leftInteger - rightInteger;
+  if (leftInteger !== null) return -1;
+  if (rightInteger !== null) return 1;
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function onChildEvent(
+  target: RtdbTarget,
+  kind: ChildEventKind,
+  next: (snap: RtdbDataSnapshot, previousChildName: string | null) => void,
+  error?: (err: unknown) => void,
+  reverseInitial = false,
+): Unsubscribe {
+  const { ref, query } = targetParts(target);
+  let initialized = false;
+  let previous: RtdbWireEntry[] = [];
+  return openValueSubscription(target, (parent) => {
+    const current: RtdbWireEntry[] = [];
+    parent.forEach((childSnap) => {
+      if (childSnap.key !== null) {
+        current.push({
+          key: childSnap.key,
+          value: childSnap.val(),
+          priority: childSnap.priority,
+          exportValue: childSnap.exportVal(),
+        });
+      }
+    });
+    if (current.length === 0) {
+      for (const key of Object.keys(directChildren(parent.val())).sort(rtdbKeyCompare)) {
+        current.push({ key, value: directChildren(parent.val())[key] });
+      }
+    }
+    const emit = (entry: RtdbWireEntry, previousChildName: string | null): void => {
+      try {
+        next(makeRtdbSnapshot(
+          rtdbChild(ref, entry.key),
+          entry.value,
+          undefined,
+          entry.priority ?? null,
+          undefined,
+          entry.exportValue ?? entry.value,
+        ), previousChildName);
+      } catch {
+        // Firebase isolates listener exceptions from sibling deliveries.
+      }
+    };
+    if (!initialized) {
+      initialized = true;
+      if (kind === 'added') {
+        const indexes = current.map((_, index) => index);
+        if (reverseInitial) indexes.reverse();
+        for (const index of indexes) {
+          emit(current[index]!, current[index - 1]?.key ?? null);
+        }
+      }
+      previous = current;
+      return;
+    }
+    const previousByKey = new Map(previous.map((entry, index) => [entry.key, { entry, index }]));
+    const currentByKey = new Map(current.map((entry, index) => [entry.key, { entry, index }]));
+    if (kind === 'removed') {
+      for (const prior of previous) {
+        if (!currentByKey.has(prior.key)) {
+          emit(prior, null);
+        }
+      }
+    } else {
+      for (let index = 0; index < current.length; index++) {
+        const entry = current[index]!;
+        const prior = previousByKey.get(entry.key);
+        const previousChildName = current[index - 1]?.key ?? null;
+        if (kind === 'added' && !prior) emit(entry, previousChildName);
+        if (kind === 'changed' && prior && !sameRtdbValue(prior.entry.value, entry.value)) {
+          emit(entry, previousChildName);
+        }
+        if (kind === 'moved' && prior) {
+          const orderBy = query?.orderBy ?? { kind: 'priority' as const };
+          const indexed = (candidate: RtdbWireEntry): unknown => {
+            if (orderBy.kind === 'key') return candidate.key;
+            if (orderBy.kind === 'priority') return candidate.priority ?? null;
+            if (orderBy.kind === 'value') return candidate.value;
+            return valueAt(candidate.value, orderBy.path);
+          };
+          if (!sameRtdbValue(indexed(prior.entry), indexed(entry))) {
+            emit(entry, previousChildName);
+          }
+        }
+      }
+    }
+    previous = current;
+  }, error);
+}
+
+function subscribeChild(
+  target: RtdbTarget,
+  kind: ChildEventKind,
+  next: (snap: RtdbDataSnapshot, previousChildName: string | null) => void,
+  cancelCallbackOrOptions?: ((err: unknown) => void) | { readonly onlyOnce?: boolean },
+  options?: { readonly onlyOnce?: boolean },
+  registryCallback: object = next,
+): Unsubscribe {
+  const error = typeof cancelCallbackOrOptions === 'function' ? cancelCallbackOrOptions : undefined;
+  const listenOptions = typeof cancelCallbackOrOptions === 'function'
+    ? options
+    : cancelCallbackOrOptions;
+  const eventType = `child_${kind}` as RtdbEventType;
+  if (!listenOptions?.onlyOnce) {
+    return registerListener(target, eventType, registryCallback, onChildEvent(target, kind, next, error));
+  }
+  let stopped = false;
+  let stopScheduled = false;
+  let unsubscribe: Unsubscribe = () => {};
+  const rawUnsubscribe = onChildEvent(target, kind, (snapshot, previousChildName) => {
+    if (stopped) return;
+    try {
+      next(snapshot, kind === 'removed' ? null : previousChildName);
+    } finally {
+      if (kind === 'added') {
+        if (!stopScheduled) {
+          stopScheduled = true;
+          queueMicrotask(() => { stopped = true; unsubscribe(); });
+        }
+      } else {
+        stopped = true;
+        unsubscribe();
+      }
+    }
+  }, error, kind === 'added');
+  unsubscribe = registerListener(target, eventType, registryCallback, rawUnsubscribe);
+  return unsubscribe;
+}
+
+type ChildCallback = (snap: RtdbDataSnapshot, previousChildName: string | null) => void;
+type CancelOrOptions = ((err: unknown) => void) | { readonly onlyOnce?: boolean };
+type ListenOptions = { readonly onlyOnce?: boolean };
+
+export function rtdbOnChildAdded(target: RtdbTarget, next: ChildCallback, cancel?: CancelOrOptions, options?: ListenOptions, identity: object = next): Unsubscribe {
+  return subscribeChild(target, 'added', next, cancel, options, identity);
+}
+
+export function rtdbOnChildChanged(target: RtdbTarget, next: ChildCallback, cancel?: CancelOrOptions, options?: ListenOptions, identity: object = next): Unsubscribe {
+  return subscribeChild(target, 'changed', next, cancel, options, identity);
+}
+
+export function rtdbOnChildRemoved(target: RtdbTarget, next: ChildCallback, cancel?: CancelOrOptions, options?: ListenOptions, identity: object = next): Unsubscribe {
+  return subscribeChild(target, 'removed', next, cancel, options, identity);
+}
+
+export function rtdbOnChildMoved(target: RtdbTarget, next: ChildCallback, cancel?: CancelOrOptions, options?: ListenOptions, identity: object = next): Unsubscribe {
+  return subscribeChild(target, 'moved', next, cancel, options, identity);
+}
+
+export function rtdbOff(target: RtdbTarget, eventType?: RtdbEventType, callback?: object): void {
+  const { ref } = targetParts(target);
+  const scope = targetScope(target);
+  const allViews = !isRtdbQuery(target);
+  const matches = (registration: ListenerRegistration): boolean =>
+    registration.port === ref.port
+      && registration.path === ref.path
+      && (allViews || registration.scope === scope)
+      && (eventType === undefined || registration.eventType === eventType)
+      && (callback === undefined || registration.callback === callback);
+  if (callback !== undefined && eventType !== undefined) {
+    registrations.find(matches)?.close();
+    return;
+  }
+  for (const registration of [...registrations]) {
+    if (matches(registration)) registration.close();
+  }
+}

package/src/serve/worker/client/rtdb-reads.ts

@@ -0,0 +1,12 @@
+/** RTDB reads over the worker port. */
+import { dataRpc, nextId } from './core.js';
+import type { RtdbDataSnapshot } from './handles.js';
+import { targetParts, type RtdbTarget } from './rtdb-references.js';
+import { hydrateRtdbSnapshot } from './rtdb-snapshots.js';
+
+export async function rtdbGet(target: RtdbTarget): Promise<RtdbDataSnapshot> {
+  const { ref, query } = targetParts(target);
+  return hydrateRtdbSnapshot(ref, await dataRpc(ref.port, {
+    t: 'op', id: nextId(), method: 'rtdb.get', path: ref.path, ...(query ? { query } : {}),
+  }));
+}

package/src/serve/worker/client/rtdb-references.ts

@@ -0,0 +1,85 @@
+/** RTDB database handles, references, path validation, and query target routing. */
+import type { RtdbQuerySpec } from '../protocol.js';
+import { isDisconnectedPort } from './core.js';
+import { getFirestore } from './connection.js';
+import type { ClientDb, ClientPort, ClientRtdb, RtdbRefHandle } from './handles.js';
+
+export type RtdbQueryLike = {
+  readonly ref: RtdbRefHandle;
+  readonly _spec: RtdbQuerySpec;
+};
+
+export type RtdbTarget = RtdbRefHandle | RtdbQueryLike;
+
+export function rtdbGetDatabase(source?: ClientDb | string | URL, name?: string): ClientRtdb {
+  if (source && typeof source === 'object' && 'port' in source) {
+    return { __kind: 'client-rtdb', port: (source as ClientDb).port };
+  }
+  const firestore = getFirestore(source ?? '/__pyric/sdk/worker.js', name);
+  return { __kind: 'client-rtdb', port: firestore.port };
+}
+
+export function normalizeRtdbPath(path?: string): string {
+  const joined = (path ?? '/').split('/').filter(Boolean).join('/');
+  return joined ? `/${joined}` : '/';
+}
+
+function rtdbKey(path: string): string | null {
+  return path.split('/').filter(Boolean).at(-1) ?? null;
+}
+
+export function makeRtdbRef(port: ClientPort, path: string): RtdbRefHandle {
+  const normalized = normalizeRtdbPath(path);
+  const parts = normalized.split('/').filter(Boolean);
+  const parentPath = parts.length > 0 ? `/${parts.slice(0, -1).join('/')}` : '/';
+  const self: RtdbRefHandle = {
+    __kind: 'rtdb-ref',
+    port,
+    path: normalized,
+    _path: normalized,
+    key: rtdbKey(normalized),
+    get parent() { return normalized === '/' ? null : makeRtdbRef(port, parentPath); },
+    get root() { return makeRtdbRef(port, '/'); },
+    isEqual(other) {
+      return other !== null && other.__kind === 'rtdb-ref'
+        && other.port === port && other.path === normalized;
+    },
+    toJSON() { return `worker://rtdb${normalized}`; },
+    toString() { return `worker://rtdb${normalized}`; },
+  };
+  return self;
+}
+
+function validateRtdbPath(path: string, allowEmpty: boolean): void {
+  if ((!allowEmpty && path.length === 0) || /[.#$[\]]/.test(path)) {
+    throw new Error(
+      `child failed: path argument was an invalid path = "${path}". Paths must be non-empty strings and can't contain ".", "#", "$", "[", or "]"`,
+    );
+  }
+}
+
+export function rtdbRef(db: ClientRtdb, path?: string): RtdbRefHandle {
+  if (isDisconnectedPort(db.port)) {
+    throw new Error('FIREBASE FATAL ERROR: Cannot call ref on a deleted database. ');
+  }
+  if (path !== undefined) validateRtdbPath(path, true);
+  return makeRtdbRef(db.port, path ?? '/');
+}
+
+export function rtdbChild(parent: RtdbRefHandle, path: string): RtdbRefHandle {
+  validateRtdbPath(path, false);
+  return makeRtdbRef(parent.port, `${parent.path}/${path}`);
+}
+
+export function isRtdbQuery(target: RtdbTarget): target is RtdbQueryLike {
+  return 'ref' in target && '_spec' in target;
+}
+
+export function targetParts(target: RtdbTarget): {
+  ref: RtdbRefHandle;
+  query?: RtdbQuerySpec;
+} {
+  return isRtdbQuery(target)
+    ? { ref: target.ref, query: target._spec }
+    : { ref: target };
+}

package/src/serve/worker/client/rtdb-snapshots.ts

@@ -0,0 +1,118 @@
+/** RTDB snapshot wire shape and Firebase-compatible client hydration. */
+import type { RtdbDataSnapshot, RtdbRefHandle } from './handles.js';
+import { rtdbChild } from './rtdb-references.js';
+
+export interface RtdbWireEntry {
+  key: string;
+  value: unknown;
+  priority?: string | number | null;
+  exportValue?: unknown;
+}
+
+export interface RtdbWireSnapshot {
+  value?: unknown;
+  exists?: boolean;
+  key?: string | null;
+  priority?: string | number | null;
+  exportValue?: unknown;
+  entries?: RtdbWireEntry[];
+}
+
+export function valueAt(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of path.split('/').filter(Boolean)) {
+    if (current === null || typeof current !== 'object') return null;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current === undefined ? null : current;
+}
+
+function exportValueAt(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of path.split('/').filter(Boolean)) {
+    if (current === null || typeof current !== 'object') return null;
+    const record = current as Record<string, unknown>;
+    const container = '.value' in record && Object.keys(record).every(
+      (key) => key === '.value' || key === '.priority',
+    ) ? record['.value'] : current;
+    if (container === null || typeof container !== 'object') return null;
+    current = (container as Record<string, unknown>)[segment];
+  }
+  return current === undefined ? null : current;
+}
+
+export function makeRtdbSnapshot(
+  refHandle: RtdbRefHandle,
+  value: unknown,
+  exists?: boolean,
+  priority: string | number | null = null,
+  entries?: RtdbWireEntry[],
+  exportValue: unknown = value,
+): RtdbDataSnapshot {
+  const childValue = (path: string) => valueAt(value, path);
+  const size = entries?.length ?? (
+    value && typeof value === 'object'
+      ? Object.keys(value as Record<string, unknown>).filter((key) => valueAt(value, key) !== null).length
+      : 0
+  );
+  return {
+    key: refHandle.key,
+    size,
+    priority,
+    exists: () => exists ?? (value !== null && value !== undefined),
+    val: () => value ?? null,
+    child: (path) => {
+      const direct = path.split('/').filter(Boolean);
+      const entry = direct.length === 1
+        ? entries?.find((candidate) => candidate.key === direct[0])
+        : undefined;
+      return makeRtdbSnapshot(
+        rtdbChild(refHandle, path),
+        childValue(path),
+        undefined,
+        entry?.priority ?? null,
+        undefined,
+        entry?.exportValue ?? exportValueAt(exportValue, path),
+      );
+    },
+    hasChild: (path) => childValue(path) !== null && childValue(path) !== undefined,
+    hasChildren: () => size > 0,
+    exportVal: () => exportValue ?? null,
+    toJSON: () => exportValue ?? null,
+    forEach: (callback) => {
+      const orderedEntries: RtdbWireEntry[] = entries ?? (
+        !value || typeof value !== 'object' || Array.isArray(value)
+          ? []
+          : Object.entries(value as Record<string, unknown>)
+              .map(([key, child]) => ({ key, value: child }))
+      );
+      for (const entry of orderedEntries) {
+        if (callback(makeRtdbSnapshot(
+          rtdbChild(refHandle, entry.key),
+          entry.value,
+          undefined,
+          entry.priority ?? null,
+          undefined,
+          entry.exportValue ?? entry.value,
+        )) === true) return true;
+      }
+      return false;
+    },
+    ref: refHandle,
+  };
+}
+
+export function hydrateRtdbSnapshot(
+  refHandle: RtdbRefHandle,
+  wire: unknown,
+): RtdbDataSnapshot {
+  const payload = wire as RtdbWireSnapshot;
+  return makeRtdbSnapshot(
+    refHandle,
+    payload.value ?? null,
+    payload.exists,
+    payload.priority ?? null,
+    payload.entries,
+    payload.exportValue ?? payload.value ?? null,
+  );
+}

package/src/serve/worker/client/rtdb-transactions.ts

@@ -0,0 +1,51 @@
+/** Optimistic RTDB transaction loop over the worker RPC boundary. */
+import { dataRpc, nextId } from './core.js';
+import type { RtdbDataSnapshot, RtdbRefHandle } from './handles.js';
+import { rtdbGet } from './rtdb-reads.js';
+import { hydrateRtdbSnapshot, type RtdbWireSnapshot } from './rtdb-snapshots.js';
+
+export interface RtdbTransactionOptions {
+  readonly applyLocally?: boolean;
+}
+
+export interface RtdbTransactionResult {
+  readonly committed: boolean;
+  readonly snapshot: RtdbDataSnapshot;
+  toJSON(): { committed: boolean; snapshot: unknown };
+}
+
+function transactionResult(
+  committed: boolean,
+  snapshot: RtdbDataSnapshot,
+): RtdbTransactionResult {
+  return {
+    committed,
+    snapshot,
+    toJSON: () => ({ committed, snapshot: snapshot.toJSON() }),
+  };
+}
+
+export async function rtdbRunTransaction<T>(
+  ref: RtdbRefHandle,
+  transactionUpdate: (current: T | null) => T | undefined,
+  options?: RtdbTransactionOptions,
+): Promise<RtdbTransactionResult> {
+  for (let attempt = 0; attempt < 25; attempt++) {
+    const before = await rtdbGet(ref);
+    const expected = before.val() as T | null;
+    const value = transactionUpdate(expected);
+    if (value === undefined) return transactionResult(false, before);
+    const wire = await dataRpc(ref.port, {
+      t: 'op',
+      id: nextId(),
+      method: 'rtdb.transactionCommit',
+      path: ref.path,
+      expected,
+      value,
+      applyLocally: options?.applyLocally,
+    }) as { retry?: boolean; committed: boolean; snapshot: RtdbWireSnapshot };
+    const snapshot = hydrateRtdbSnapshot(ref, wire.snapshot);
+    if (!wire.retry) return transactionResult(wire.committed, snapshot);
+  }
+  throw new Error('maxretry');
+}

package/src/serve/worker/client/rtdb-writes.ts

@@ -0,0 +1,74 @@
+/** RTDB writes, priorities, and push-ID generation over the worker port. */
+import { dataRpc, nextId } from './core.js';
+import type { RtdbRefHandle } from './handles.js';
+import { makeRtdbRef } from './rtdb-references.js';
+
+const RTDB_PUSH_CHARS = '-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz';
+let lastRtdbPushTime = 0;
+const lastRtdbRandChars: number[] = new Array(12).fill(0);
+
+function generateRtdbPushId(now: number = Date.now()): string {
+  const duplicateTime = now === lastRtdbPushTime;
+  lastRtdbPushTime = now;
+  const timestampChars: string[] = new Array(8);
+  let timestamp = now;
+  for (let i = 7; i >= 0; i--) {
+    timestampChars[i] = RTDB_PUSH_CHARS.charAt(timestamp % 64);
+    timestamp = Math.floor(timestamp / 64);
+  }
+  if (timestamp !== 0) throw new Error('RTDB push-id: timestamp overflow.');
+  if (!duplicateTime) {
+    for (let i = 0; i < 12; i++) lastRtdbRandChars[i] = Math.floor(Math.random() * 64);
+  } else {
+    let i: number;
+    for (i = 11; i >= 0 && lastRtdbRandChars[i] === 63; i--) lastRtdbRandChars[i] = 0;
+    if (i < 0) {
+      for (let j = 0; j < 12; j++) lastRtdbRandChars[j] = Math.floor(Math.random() * 64);
+    } else {
+      lastRtdbRandChars[i] = (lastRtdbRandChars[i] ?? 0) + 1;
+    }
+  }
+  return timestampChars.join('') + lastRtdbRandChars.map((n) => RTDB_PUSH_CHARS.charAt(n)).join('');
+}
+
+export async function rtdbSet(ref: RtdbRefHandle, value: unknown): Promise<void> {
+  await dataRpc(ref.port, { t: 'op', id: nextId(), method: 'rtdb.set', path: ref.path, value });
+}
+
+export async function rtdbSetPriority(ref: RtdbRefHandle, priority: string | number | null): Promise<void> {
+  await dataRpc(ref.port, { t: 'op', id: nextId(), method: 'rtdb.setPriority', path: ref.path, priority });
+}
+
+export async function rtdbSetWithPriority(
+  ref: RtdbRefHandle,
+  value: unknown,
+  priority: string | number | null,
+): Promise<void> {
+  await dataRpc(ref.port, {
+    t: 'op', id: nextId(), method: 'rtdb.setWithPriority', path: ref.path, value, priority,
+  });
+}
+
+export async function rtdbUpdate(ref: RtdbRefHandle, values: Record<string, unknown>): Promise<void> {
+  await dataRpc(ref.port, { t: 'op', id: nextId(), method: 'rtdb.update', path: ref.path, values });
+}
+
+export async function rtdbRemove(ref: RtdbRefHandle): Promise<void> {
+  await dataRpc(ref.port, { t: 'op', id: nextId(), method: 'rtdb.remove', path: ref.path });
+}
+
+export function rtdbPush(
+  ref: RtdbRefHandle,
+  value?: unknown,
+): RtdbRefHandle & PromiseLike<RtdbRefHandle> {
+  const key = generateRtdbPushId();
+  const pushed = makeRtdbRef(ref.port, `${ref.path}/${key}`);
+  const settledRef = makeRtdbRef(ref.port, pushed.path);
+  const promise = dataRpc(ref.port, {
+    t: 'op', id: nextId(), method: 'rtdb.push', path: ref.path, key, value,
+  }).then(() => settledRef);
+  return Object.assign(pushed, {
+    then: promise.then.bind(promise),
+    catch: promise.catch.bind(promise),
+  });
+}

package/src/serve/worker/client.ts

@@ -16,7 +16,6 @@
  *   - `firestore-writes` writes + `writeBatch` + `runTransaction`
  *   - `rules`           Firestore/RTDB rules deploy + status
  *   - `admin-firestore` admin-lens document ops
- *   - `rtdb`            RTDB modular subset
  *   - `studio`          event stream, confirm-policy, sandbox snapshot
  *   - `auth`            per-port auth surface
  *   - `storage`         worker-backed storage mirror
@@ -49,7 +48,6 @@ export * from './client/firestore-reads.js';
 export * from './client/firestore-writes.js';
 export * from './client/rules.js';
 export * from './client/admin-firestore.js';
-export * from './client/rtdb.js';
 export * from './client/studio.js';
 export * from './client/presence.js';
 export * from './client/auth.js';