@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.12

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

@@ -0,0 +1,181 @@
+/**
+ * Firestore read execution — document/collection reads, keyspace enumeration,
+ * count/aggregate reads, and the `onSnapshot` listener. Each RPCs the worker and
+ * rehydrates the reply into the modular SDK's snapshot shapes.
+ */
+
+import type {
+  TargetDescriptor,
+  AggregateFieldDescriptor,
+  AggregateSpecDescriptor,
+  InboundMessage,
+} from '../protocol.js';
+import { closeSubscription, nextId, nextSubId, dataRpc, _defaultLens, openSnapshotSubscription, stampIssuer } from './core.js';
+import type { ClientDb, DocRefHandle, CollRefHandle, QueryHandle, Unsubscribe } from './handles.js';
+import { makeDocSnapshot, makeQuerySnapshot } from './snapshots.js';
+import type { RawDocResult, RawQueryResult, ClientDocSnapshot, ClientQuerySnapshot } from './snapshots.js';
+
+// ─── Execution functions (RPC) ────────────────────────────────────────────
+
+export async function getDoc(ref: DocRefHandle): Promise<ClientDocSnapshot> {
+  const result = await dataRpc(ref.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'getDoc',
+    path: ref.descriptor.path,
+  }) as RawDocResult;
+  return makeDocSnapshot(result, ref.port);
+}
+
+export async function getDocs(
+  source: CollRefHandle | QueryHandle,
+): Promise<ClientQuerySnapshot> {
+  const result = await dataRpc(source.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'getDocs',
+    source: source.__kind === 'coll-ref'
+      ? (source as CollRefHandle).descriptor
+      : (source as QueryHandle).descriptor,
+  }) as RawQueryResult;
+  return makeQuerySnapshot(result, source.port);
+}
+
+/**
+ * Enumerate root collection ids (Pyric Studio data browse). The modular SDK has
+ * no client `listCollections`, so the host scans the sandbox keyspace and
+ * returns the ids. Lens is attached (via dataRpc) but the host enumeration is
+ * lens-independent.
+ */
+export async function listRootCollections(db: ClientDb): Promise<string[]> {
+  const r = (await dataRpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'listRootCollections',
+  })) as { ids: string[] };
+  return r.ids;
+}
+
+/** Enumerate subcollection ids under a document path (Pyric Studio data browse). */
+export async function listSubcollections(db: ClientDb, docPath: string): Promise<string[]> {
+  const r = (await dataRpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'listSubcollections',
+    docPath,
+  })) as { ids: string[] };
+  return r.ids;
+}
+
+export async function getCountFromServer(
+  source: CollRefHandle | QueryHandle,
+): Promise<{ data(): { count: number } }> {
+  const result = await dataRpc(source.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'count',
+    source: source.__kind === 'coll-ref'
+      ? (source as CollRefHandle).descriptor
+      : (source as QueryHandle).descriptor,
+  }) as { count: number };
+  return { data: () => ({ count: result.count }) };
+}
+
+// ─── Multi-field aggregates (count / sum / average) ───────────────────────
+
+/** Factory: count() aggregate field. Mirrors `pyric/firestore`'s `count()`. */
+export function count(): AggregateFieldDescriptor {
+  return { kind: 'count' };
+}
+
+/** Factory: sum-of-`field` aggregate. Mirrors `pyric/firestore`'s `sum()`. */
+export function sum(field: string): AggregateFieldDescriptor {
+  return { kind: 'sum', field };
+}
+
+/** Factory: average-of-`field` aggregate. Empty input yields `null`. */
+export function average(field: string): AggregateFieldDescriptor {
+  return { kind: 'average', field };
+}
+
+/**
+ * Run a multi-field aggregate on the worker. Mirrors `pyric/firestore`'s
+ * `getAggregateFromServer(query, spec)`: spec entries are keyed by
+ * caller-chosen aliases; `.data()` returns the numbers under the same keys
+ * (`average` over no rows is `null`).
+ */
+export async function getAggregateFromServer<S extends AggregateSpecDescriptor>(
+  source: CollRefHandle | QueryHandle,
+  spec: S,
+): Promise<{ data(): { [K in keyof S]: number | null } }> {
+  const result = await dataRpc(source.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'aggregate',
+    source: source.__kind === 'coll-ref'
+      ? (source as CollRefHandle).descriptor
+      : (source as QueryHandle).descriptor,
+    spec,
+  }) as { data: { [K in keyof S]: number | null } };
+  return { data: () => result.data };
+}
+
+// ─── onSnapshot ──────────────────────────────────────────────────────────
+
+/**
+ * Subscribe to a document or query. Mirrors `pyric/firestore`'s `onSnapshot`.
+ *
+ * Returns an `unsub` function. Sends `{ t:'unsub', subId }` to the worker
+ * to deregister the listener on the worker side.
+ */
+export function onSnapshot(
+  target: DocRefHandle | CollRefHandle | QueryHandle,
+  callback: (snap: ClientDocSnapshot | ClientQuerySnapshot) => void,
+  errorCallback?: (err: unknown) => void,
+): Unsubscribe {
+  const subId = nextSubId();
+  const port = target.port;
+
+  const subscription = {
+    port,
+    service: 'firestore' as const,
+    next: (raw: unknown) => {
+      const r = raw as Record<string, unknown>;
+      if ('docs' in r) {
+        callback(makeQuerySnapshot(r as unknown as RawQueryResult, port));
+      } else {
+        callback(makeDocSnapshot(r as unknown as RawDocResult, port));
+      }
+    },
+    error: errorCallback,
+  };
+
+  const descriptor: TargetDescriptor =
+    target.__kind === 'doc-ref'
+      ? (target as DocRefHandle).descriptor
+      : target.__kind === 'coll-ref'
+        ? (target as CollRefHandle).descriptor
+        : (target as QueryHandle).descriptor;
+
+  // Stamp the active default lens onto the sub (Pyric Studio "watch as user")
+  // exactly as `dataRpc` does for ops, so a `setLens({mode:'as',uid})` choice
+  // makes listeners impersonate too. Omitted when no lens is set → byte-identical
+  // wire message, preserving the additive contract. The declared op source
+  // rides along the same way (client-constructed subs only — the relay's
+  // subs post verbatim).
+  const opened = openSnapshotSubscription(
+    port,
+    subId,
+    subscription,
+    stampIssuer(
+      (_defaultLens
+        ? { t: 'sub', subId, target: descriptor, actAs: _defaultLens }
+        : { t: 'sub', subId, target: descriptor }) satisfies InboundMessage,
+    ),
+  );
+  if (!opened && errorCallback) queueMicrotask(() => errorCallback(new Error('Firebase App was deleted')));
+
+  return () => {
+    closeSubscription(port, subId);
+  };
+}

package/src/serve/worker/client/firestore-refs.ts

@@ -0,0 +1,226 @@
+/**
+ * Firestore reference, query, and sentinel factories — the synchronous,
+ * client-side descriptor builders. No RPC fires here: each returns a handle or
+ * marker carrying a serializable descriptor the execution functions send later.
+ */
+
+import type {
+  DocRef,
+  CollRef,
+  GroupRef,
+  QueryDescriptor,
+  QueryConstraintDescriptor,
+  FilterConstraintDescriptor,
+  TargetDescriptor,
+  SentinelMarker,
+} from '../protocol.js';
+import { lastSegment } from './handles.js';
+import type { ClientDb, DocRefHandle, CollRefHandle, QueryHandle } from './handles.js';
+
+// ─── Path factories (client-side only — no RPC) ──────────────────────────
+
+/**
+ * Build a document reference. Mirrors `pyric/firestore`'s `doc(db, path)`.
+ *
+ * WHY CLIENT-SIDE: Firebase's `doc()` is synchronous and path-only — it
+ * needs no data from the sandbox. We build a descriptor object here and
+ * include the port so execution calls can route to the worker.
+ */
+export function doc(
+  parent: ClientDb | CollRefHandle,
+  ...pathSegments: string[]
+): DocRefHandle {
+  const port = 'port' in parent ? parent.port : (parent as ClientDb).port;
+  let path: string;
+
+  if (parent.__kind === 'client-db') {
+    if (pathSegments.length === 0) throw new TypeError('doc(db, path) requires a path segment.');
+    path = pathSegments.join('/');
+  } else {
+    // parent is a CollRefHandle
+    const collPath = (parent as CollRefHandle).descriptor.path;
+    path = pathSegments.length > 0
+      ? `${collPath}/${pathSegments.join('/')}`
+      : collPath; // caller will get auto-id via addDoc; doc() without id is unusual
+  }
+
+  const descriptor: DocRef = { __ref: 'doc', path };
+  return {
+    __kind: 'doc-ref',
+    descriptor,
+    port,
+    id: lastSegment(path),
+    path,
+  };
+}
+
+/**
+ * Build a collection reference. Mirrors `pyric/firestore`'s `collection(db, path)`.
+ */
+export function collection(
+  parent: ClientDb | DocRefHandle,
+  ...pathSegments: string[]
+): CollRefHandle {
+  const port = parent.port;
+  if (pathSegments.length === 0) throw new TypeError('collection() requires a path segment.');
+
+  let path: string;
+  if (parent.__kind === 'client-db') {
+    path = pathSegments.join('/');
+  } else {
+    const docPath = (parent as DocRefHandle).descriptor.path;
+    path = `${docPath}/${pathSegments.join('/')}`;
+  }
+
+  const descriptor: CollRef = { __ref: 'collection', path };
+  return {
+    __kind: 'coll-ref',
+    descriptor,
+    port,
+    id: lastSegment(path),
+    path,
+  };
+}
+
+/**
+ * Build a collection-group query. Mirrors `pyric/firestore`'s `collectionGroup(db, id)`.
+ */
+export function collectionGroup(db: ClientDb, collectionId: string): QueryHandle {
+  const descriptor: QueryDescriptor = {
+    __ref: 'query',
+    source: { __ref: 'group', collectionId },
+    constraints: [],
+  };
+  return { __kind: 'query', descriptor, port: db.port };
+}
+
+// ─── Query constraint factories (client-side) ─────────────────────────────
+
+/** Opaque query constraint — carries its descriptor for embedding in queries. */
+export interface QueryConstraintHandle {
+  readonly _descriptor: QueryConstraintDescriptor;
+}
+
+export function where(field: string, op: string, value: unknown): QueryConstraintHandle {
+  return { _descriptor: { kind: 'where', field, op, value } };
+}
+
+/**
+ * Extract a constraint's FILTER descriptor for composite embedding — throws
+ * the same TypeError `pyric/firestore`'s `and()`/`or()` raise when handed a
+ * non-filter (`orderBy` / `limit` / cursors are not valid inside composites).
+ */
+function toFilterDescriptor(
+  kind: 'and' | 'or',
+  c: QueryConstraintHandle,
+): FilterConstraintDescriptor {
+  const d = c._descriptor;
+  if (d.kind !== 'where' && d.kind !== 'and' && d.kind !== 'or') {
+    throw new TypeError(
+      `pyric worker client: ${kind}() received a non-filter constraint (orderBy / limit are not valid here).`,
+    );
+  }
+  return d;
+}
+
+function composite(kind: 'and' | 'or', filters: QueryConstraintHandle[]): QueryConstraintHandle {
+  if (filters.length === 0) {
+    throw new TypeError(`pyric worker client: ${kind}() requires at least one filter argument.`);
+  }
+  return { _descriptor: { kind, filters: filters.map((f) => toFilterDescriptor(kind, f)) } };
+}
+
+/**
+ * OR composite filter — at least one operand must match. Operands must be
+ * filters (`where()`, or nested `or()`/`and()`). Mirrors `pyric/firestore`'s
+ * `or(...)`; the worker rebuilds it with the real modular factory.
+ */
+export function or(...filters: QueryConstraintHandle[]): QueryConstraintHandle {
+  return composite('or', filters);
+}
+
+/** AND composite filter — every operand must match. See {@link or}. */
+export function and(...filters: QueryConstraintHandle[]): QueryConstraintHandle {
+  return composite('and', filters);
+}
+
+export function orderBy(field: string, direction?: 'asc' | 'desc'): QueryConstraintHandle {
+  return { _descriptor: { kind: 'orderBy', field, direction } };
+}
+
+export function limit(n: number): QueryConstraintHandle {
+  return { _descriptor: { kind: 'limit', n } };
+}
+
+export function limitToLast(n: number): QueryConstraintHandle {
+  return { _descriptor: { kind: 'limitToLast', n } };
+}
+
+export function startAt(...values: unknown[]): QueryConstraintHandle {
+  return { _descriptor: { kind: 'startAt', values } };
+}
+
+export function startAfter(...values: unknown[]): QueryConstraintHandle {
+  return { _descriptor: { kind: 'startAfter', values } };
+}
+
+export function endAt(...values: unknown[]): QueryConstraintHandle {
+  return { _descriptor: { kind: 'endAt', values } };
+}
+
+export function endBefore(...values: unknown[]): QueryConstraintHandle {
+  return { _descriptor: { kind: 'endBefore', values } };
+}
+
+/**
+ * Apply query constraints to a source ref or query.
+ * Mirrors `pyric/firestore`'s `query(source, ...constraints)`.
+ */
+export function query(
+  source: CollRefHandle | QueryHandle,
+  ...constraints: QueryConstraintHandle[]
+): QueryHandle {
+  const sourceDescriptor: TargetDescriptor =
+    source.__kind === 'coll-ref'
+      ? (source as CollRefHandle).descriptor
+      : (source as QueryHandle).descriptor;
+
+  const existingConstraints: readonly QueryConstraintDescriptor[] =
+    source.__kind === 'query'
+      ? (source as QueryHandle).descriptor.constraints
+      : [];
+
+  const descriptor: QueryDescriptor = {
+    __ref: 'query',
+    source: sourceDescriptor.__ref === 'query'
+      ? (sourceDescriptor as QueryDescriptor).source
+      : (sourceDescriptor as DocRef | CollRef | GroupRef),
+    constraints: [
+      ...existingConstraints,
+      ...constraints.map((c) => c._descriptor),
+    ],
+  };
+  return { __kind: 'query', descriptor, port: source.port };
+}
+
+// ─── Sentinel factories (client-side markers) ────────────────────────────
+
+export function serverTimestamp(): SentinelMarker {
+  return { __sentinel: 'serverTimestamp' };
+}
+
+export function increment(n: number): SentinelMarker {
+  return { __sentinel: 'increment', n };
+}
+
+export function arrayUnion(...values: unknown[]): SentinelMarker {
+  return { __sentinel: 'arrayUnion', values };
+}
+
+export function arrayRemove(...values: unknown[]): SentinelMarker {
+  return { __sentinel: 'arrayRemove', values };
+}
+
+export function deleteField(): SentinelMarker {
+  return { __sentinel: 'deleteField' };
+}

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

@@ -0,0 +1,232 @@
+/**
+ * Firestore write execution — single-document writes, `writeBatch`, and
+ * `runTransaction` with read-set validation + retry for multi-tab correctness.
+ */
+
+import type { WriteDescriptor, TxnReadEntry } from '../protocol.js';
+import { nextId, dataRpc } from './core.js';
+import type { ClientDb, DocRefHandle, CollRefHandle } from './handles.js';
+import { makeDocSnapshot } from './snapshots.js';
+import type { RawDocResult, ClientDocSnapshot } from './snapshots.js';
+
+export async function setDoc(
+  ref: DocRefHandle,
+  data: Record<string, unknown>,
+  options?: { merge?: boolean; mergeFields?: string[] },
+): Promise<void> {
+  await dataRpc(ref.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'setDoc',
+    path: ref.descriptor.path,
+    data,
+    options,
+  });
+}
+
+export async function updateDoc(
+  ref: DocRefHandle,
+  data: Record<string, unknown>,
+): Promise<void> {
+  await dataRpc(ref.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'updateDoc',
+    path: ref.descriptor.path,
+    data,
+  });
+}
+
+export async function deleteDoc(ref: DocRefHandle): Promise<void> {
+  await dataRpc(ref.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'deleteDoc',
+    path: ref.descriptor.path,
+  });
+}
+
+export async function addDoc(
+  coll: CollRefHandle,
+  data: Record<string, unknown>,
+): Promise<DocRefHandle> {
+  const result = await dataRpc(coll.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'addDoc',
+    collectionPath: coll.descriptor.path,
+    data,
+  }) as { id: string; path: string };
+
+  return {
+    __kind: 'doc-ref',
+    descriptor: { __ref: 'doc', path: result.path },
+    port: coll.port,
+    id: result.id,
+    path: result.path,
+  };
+}
+
+// ─── writeBatch ──────────────────────────────────────────────────────────
+
+/**
+ * Client-side write batch. Buffers `set`/`update`/`delete` calls and
+ * sends them all to the worker on `.commit()`.
+ *
+ * Mirrors `pyric/firestore`'s `writeBatch(db)` shape:
+ *   const batch = writeBatch(db);
+ *   batch.set(ref, { ... });
+ *   batch.delete(ref2);
+ *   await batch.commit();
+ */
+export interface ClientWriteBatch {
+  set(ref: DocRefHandle, data: Record<string, unknown>, options?: { merge?: boolean; mergeFields?: string[] }): ClientWriteBatch;
+  update(ref: DocRefHandle, data: Record<string, unknown>): ClientWriteBatch;
+  delete(ref: DocRefHandle): ClientWriteBatch;
+  commit(): Promise<void>;
+}
+
+export function writeBatch(db: ClientDb): ClientWriteBatch {
+  const writes: WriteDescriptor[] = [];
+  const port = db.port;
+
+  const batch: ClientWriteBatch = {
+    set(ref, data, options) {
+      writes.push({ method: 'set', path: ref.descriptor.path, data, options });
+      return batch;
+    },
+    update(ref, data) {
+      writes.push({ method: 'update', path: ref.descriptor.path, data });
+      return batch;
+    },
+    delete(ref) {
+      writes.push({ method: 'delete', path: ref.descriptor.path });
+      return batch;
+    },
+    async commit() {
+      await dataRpc(port, {
+        t: 'op',
+        id: nextId(),
+        method: 'batchCommit',
+        writes: [...writes],
+      });
+    },
+  };
+  return batch;
+}
+
+// ─── runTransaction ──────────────────────────────────────────────────────
+
+/** Client-side transaction handle. */
+export interface ClientTransaction {
+  get(ref: DocRefHandle): Promise<ClientDocSnapshot>;
+  set(ref: DocRefHandle, data: Record<string, unknown>, options?: { merge?: boolean; mergeFields?: string[] }): void;
+  update(ref: DocRefHandle, data: Record<string, unknown>): void;
+  delete(ref: DocRefHandle): void;
+}
+
+/**
+ * Maximum number of times the client will retry `updateFn` on a
+ * worker-reported conflict (`aborted`). Matches Firestore SDK default.
+ */
+const TXN_MAX_ATTEMPTS = 5;
+
+/**
+ * Run a transaction. Mirrors `pyric/firestore`'s `runTransaction(db, fn)`.
+ *
+ * MULTI-TAB CORRECTNESS — READ-SET VALIDATION + RETRY
+ * ----------------------------------------------------
+ * A transaction spans two messages: the `txn.get` RPC (read) and the
+ * `txnCommit` RPC (commit). Between those two messages another tab may
+ * write to a doc the current tab read — a silent lost update without
+ * validation. We fix this the standard way:
+ *
+ *   1. Each `txn.get(ref)` records `{ path, data }` in a per-attempt
+ *      read-set (`data` is the raw `SerializedDocData` the worker
+ *      returned, or `null` if the doc was missing).
+ *   2. `txnCommit` carries both `reads` (the read-set) and `writes`.
+ *   3. The worker re-reads each doc inside a sandbox transaction, re-
+ *      serializes it the same way, and compares the JSON strings.
+ *      Any mismatch → `{ ok: false, error: { code: 'aborted' } }`.
+ *   4. On `aborted`, the client discards the result of `updateFn` and
+ *      re-runs it with a fresh transaction object (fresh reads, empty
+ *      write buffer). Up to `TXN_MAX_ATTEMPTS` attempts are made.
+ *   5. After the cap, throws an error with `.code === 'aborted'`.
+ *
+ * This matches real Firestore's behaviour: the SDK retries `updateFn`
+ * on conflict rather than surfacing the error immediately.
+ */
+export async function runTransaction<R>(
+  db: ClientDb,
+  updateFn: (txn: ClientTransaction) => Promise<R> | R,
+): Promise<R> {
+  const port = db.port;
+
+  for (let attempt = 0; attempt < TXN_MAX_ATTEMPTS; attempt++) {
+    // Fresh read-set and write buffer for each attempt.
+    const reads: TxnReadEntry[] = [];
+    const writes: WriteDescriptor[] = [];
+
+    const txn: ClientTransaction = {
+      async get(ref) {
+        // RPC to the worker — capture the raw result before rehydration.
+        const rawResult = await dataRpc(ref.port, {
+          t: 'op',
+          id: nextId(),
+          method: 'getDoc',
+          path: ref.descriptor.path,
+          activity: { groupKind: 'transaction' },
+        }) as RawDocResult;
+
+        // Record the raw serialized data (or null) in the read-set.
+        // We preserve the wire-form SerializedDocData so the worker can
+        // re-serialize the current doc and compare JSON strings.
+        reads.push({
+          path: ref.descriptor.path,
+          data: (rawResult.exists && rawResult.data) ? rawResult.data : null,
+        });
+
+        return makeDocSnapshot(rawResult, ref.port);
+      },
+      set(ref, data, options) {
+        writes.push({ method: 'set', path: ref.descriptor.path, data, options });
+      },
+      update(ref, data) {
+        writes.push({ method: 'update', path: ref.descriptor.path, data });
+      },
+      delete(ref) {
+        writes.push({ method: 'delete', path: ref.descriptor.path });
+      },
+    };
+
+    const result = await updateFn(txn);
+
+    // Send read-set + writes to the worker for validation and commit.
+    try {
+      await dataRpc(port, {
+        t: 'op',
+        id: nextId(),
+        method: 'txnCommit',
+        reads: [...reads],
+        writes: [...writes],
+      });
+      return result;
+    } catch (err) {
+      const e = err as { code?: string };
+      if (e.code === 'aborted') {
+        // Conflict detected — retry updateFn on the next attempt.
+        continue;
+      }
+      // Permission-denied, not-found, etc. — propagate immediately.
+      throw err;
+    }
+  }
+
+  // Exceeded max attempts.
+  const abortErr = new Error(
+    `Transaction failed after ${TXN_MAX_ATTEMPTS} attempts due to repeated conflicts. ` +
+    'Another tab is concurrently writing to the same documents.',
+  ) as Error & { code: string };
+  abortErr.code = 'aborted';
+  throw abortErr;
+}