@synnaxlabs/client 0.56.1 → 0.57.0

package/src/query/retriever.ts

@@ -0,0 +1,308 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type destructor, type record, zod } from "@synnaxlabs/x";
+import z from "zod";
+
+import { NotFoundError, ValidationError } from "@/errors";
+import { type Cache } from "@/query/cache";
+import {
+  type Cached,
+  type ChangeHandler,
+  type Retrieves,
+  type Watch,
+} from "@/query/query";
+import { type Keyed, type Table } from "@/query/table";
+import { type Data, type FetchOptions, type Params } from "@/query/types";
+
+/** Query fields only the server can evaluate, shared by most request shapes. */
+const DEFAULT_SERVER_FIELDS = ["searchTerm", "limit", "offset"] as const;
+
+/**
+ * Returns the keys of a request that addresses keys and nothing else: a
+ * non-empty `keys` field with every other field nullish. Such requests resolve
+ * through the table's fetch primitive instead of the request fetch. Returns
+ * null for any other request.
+ */
+const keysOnly = (query: unknown): unknown[] | null => {
+  if (typeof query !== "object" || query === null || Array.isArray(query)) return null;
+  const { keys } = query as { keys?: unknown };
+  if (!Array.isArray(keys) || keys.length === 0) return null;
+  if (!Object.entries(query).every(([k, v]) => k === "keys" || v == null)) return null;
+  return keys;
+};
+
+/** True for params that are a bare record key rather than a query object. */
+const isBareKey = (params: unknown): params is record.Key =>
+  typeof params === "string" || typeof params === "number";
+
+/**
+ * Request schema arm reading a bare key list as `{ keys }`. Union it onto a
+ * domain's request schema to opt that domain into the shorthand:
+ * `retrieveRequestZ.or(keyListZ(keyZ))`.
+ */
+export const keyListZ = <K extends z.ZodType<record.Key>>(key: K) =>
+  z.array(key).transform((keys) => ({ keys }));
+
+interface ComposeProp<V, D> {
+  /**
+   * Per-record enrichment applied to every answer, receiving the normalized
+   * query the record answers. Defaults to identity.
+   */
+  compose: (record: V, query: Params) => D;
+}
+
+/** Optional only when a record is a valid answer as-is (V assignable to D):
+ *  the identity default is unsound for any narrower D. */
+type ComposeParam<V, D> = [V] extends [D]
+  ? Partial<ComposeProp<V, D>>
+  : ComposeProp<V, D>;
+
+/**
+ * Declaration of a domain client's read surface. The single space is derived
+ * from the table and its fetch: `{ key }` params resolve one record, with
+ * deletion flipping the answer to deleted. Declare `single` only when the
+ * domain's single query is richer than a key.
+ */
+export type RetrieverParams<
+  Z extends z.ZodType<Params>,
+  K extends record.Key,
+  V extends Keyed<K>,
+  D extends Data = V,
+  SingleInput = { key: K },
+  SingleQuery extends Params = K,
+> = ComposeParam<V, D> & {
+  /** Resource name used in error messages, e.g. "range". */
+  name: string;
+  /** The table owning this domain's record content. */
+  table: Table<K, V>;
+  /** The space answering every non-single query shape. */
+  request: {
+    /**
+     * Parses and canonicalizes request params so equivalent queries hash
+     * identically; its output type is the space's query type.
+     */
+    schema: Z;
+    /**
+     * Fetches matching records from the cluster. Keys-only requests never
+     * reach it; they resolve through the table's fetch. Results hydrate the
+     * table under its declared mode.
+     */
+    fetch: (query: z.output<Z>, options?: FetchOptions) => Promise<V[]>;
+    /** Rule 2: whether a record satisfies the query. Pure; no network. */
+    matches?: (record: V, query: z.output<Z>) => boolean;
+    /** Overrides {@link DEFAULT_SERVER_FIELDS} for this request shape. */
+    serverFields?: readonly string[];
+    /** Foreign tables whose events affect this space's answers. */
+    watch?: Array<Watch<z.output<Z>, K>>;
+  };
+  /** Custom single space for domains whose single query is richer than a key. */
+  single?: {
+    /**
+     * Discriminates and canonicalizes single params: parse success routes the
+     * query to the single space, and the output is the space's query. Object
+     * schemas must reject unknown keys so request params fall through. Union
+     * in a bare-key arm to accept `retrieve(key)`.
+     */
+    schema: z.ZodType<SingleQuery, SingleInput | record.Key>;
+    /** The space answering single queries, built via the cache. */
+    space: Retrieves<SingleQuery, D>;
+  };
+};
+
+/**
+ * A domain client's cached read surface, routing each query to the single or
+ * request answer space. The arity of the result follows the query: params
+ * addressing one record yield a record, every other shape yields an array.
+ *
+ * Extend it and call `super(cache, { ... })`:
+ *
+ * ```ts
+ * export class Client extends query.Retriever<typeof requestZ, Key, Label> {
+ *   constructor(client: UnaryClient, cache: query.Cache) {
+ *     const store = cache.createTable({ ... });
+ *     super(cache, { name: "label", table: store, request: { ... } });
+ *   }
+ * }
+ * ```
+ *
+ * Anything evaluated eagerly inside `super` must come from a local, since
+ * `this` is unavailable until it returns. Closures may reference `this`: an
+ * arrow captures it lexically and does not read it until called.
+ *
+ * The read surface is not designed for overriding: a domain with more query
+ * kinds exposes them as named {@link Retrieves} members instead.
+ */
+export abstract class Retriever<
+  Z extends z.ZodType<Params>,
+  K extends record.Key,
+  V extends Keyed<K>,
+  D extends Data = V,
+  SingleInput = { key: K },
+  SingleQuery extends Params = K,
+> {
+  private readonly singleSpace: Retrieves<Params, D | D[]>;
+  private readonly requestSpace: Retrieves<Params, D | D[]>;
+  private readonly trySingle: (params: unknown) => { query: SingleQuery } | null;
+  private readonly normalizeRequest: (params: unknown) => z.output<Z>;
+  private readonly routes = new WeakMap<object, [Retrieves<Params, D | D[]>, Params]>();
+
+  constructor(
+    cache: Cache,
+    params: RetrieverParams<Z, K, V, D, SingleInput, SingleQuery>,
+  ) {
+    const {
+      name,
+      table,
+      request,
+      compose = (record: V) => record as unknown as D,
+      single,
+    } = params;
+    const {
+      schema,
+      fetch,
+      matches,
+      serverFields = DEFAULT_SERVER_FIELDS,
+      watch,
+    } = request;
+    this.requestSpace = cache.queries<z.output<Z>, D[], K, V>({
+      name,
+      table,
+      fetch: async (query, options) => {
+        const keys = keysOnly(query);
+        if (keys != null) return (await table.retrieve(keys as K[])).map((r) => r.key);
+        const records = await fetch(query, options);
+        table.ingest(records);
+        return records.map((r) => r.key);
+      },
+      compose: (records, q) => records.map((r) => compose(r, q)),
+      keysOf: (query) => keysOnly(query) as K[] | null,
+      matches,
+      serverFields,
+      watch,
+    }) as Retrieves<Params, D | D[]>;
+    this.normalizeRequest = (p) => zod.parse(schema, p, { label: `${name} query` });
+    if (single != null) {
+      this.singleSpace = single.space as Retrieves<Params, D | D[]>;
+      const singleSchema = single.schema;
+      // Params carrying `key` that fail the single schema are malformed
+      // single queries; falling through would silently fetch every record.
+      this.trySingle = (p) => {
+        const res = singleSchema.safeParse(p);
+        if (res.success) return { query: res.data };
+        if (isBareKey(p) || (typeof p === "object" && p !== null && "key" in p)) {
+          const cause = new zod.ParseError({
+            issues: res.error.issues,
+            input: p,
+            label: `${name} single query params`,
+            cause: res.error,
+          });
+          throw new ValidationError(
+            `${name} params address a single key but do not match the ` +
+              `single-query schema.\n${cause.message}`,
+            { cause },
+          );
+        }
+        return null;
+      };
+    } else {
+      // The default path binds SingleQuery = K: `{ key }` params resolve through the
+      // table's fetch. The casts are the one seam the defaults can't prove.
+      this.singleSpace = cache.queries<K, D, K, V>({
+        name,
+        table,
+        fetch: async (key) => {
+          const records = await table.retrieve([key]);
+          if (records.length === 0)
+            throw new NotFoundError(`${name} with key ${key} not found`);
+          return [key];
+        },
+        compose: (records, q) => compose(records[0], q),
+        keyOf: (query) => query,
+        single: true,
+      }) as Retrieves<Params, D | D[]>;
+      this.trySingle = (p) => {
+        if (isBareKey(p)) return { query: p as Params as SingleQuery };
+        return typeof p === "object" && p !== null && "key" in p
+          ? { query: (p as { key: K }).key as Params as SingleQuery }
+          : null;
+      };
+    }
+  }
+
+  /**
+   * Routes params to their answer space, memoized per params object identity.
+   * {@link Params} is readonly, so a given object always routes identically;
+   * repeat reads of the same object skip schema validation entirely.
+   */
+  private route(params: unknown): [Retrieves<Params, D | D[]>, Params] {
+    const cacheable = typeof params === "object" && params !== null;
+    if (cacheable) {
+      const held = this.routes.get(params);
+      if (held !== undefined) return held;
+    }
+    const single = this.trySingle(params);
+    const route: [Retrieves<Params, D | D[]>, Params] =
+      single != null
+        ? [this.singleSpace, single.query]
+        : [this.requestSpace, this.normalizeRequest(params)];
+    if (cacheable) this.routes.set(params, route);
+    return route;
+  }
+
+  /**
+   * Reads the record the params address, or every record matching them.
+   * Serves the cache when the answer is fresh, fetching otherwise. A bare key
+   * is shorthand for `{ key }`; a bare key list is accepted by domains whose
+   * request schema unions in {@link keyListZ}.
+   * @throws {NotFoundError} if a single-record query matches nothing or the
+   * record was deleted.
+   * @throws {ValidationError} if params contain `key` (or are a bare key)
+   * but fail the single-query schema.
+   */
+  retrieve(params: K | SingleInput, options?: FetchOptions): Promise<D>;
+  retrieve(params: K[] | z.input<Z>, options?: FetchOptions): Promise<D[]>;
+  async retrieve(
+    params: K | K[] | SingleInput | z.input<Z>,
+    options?: FetchOptions,
+  ): Promise<D | D[]> {
+    const [space, query] = this.route(params);
+    return await space.retrieve(query, options);
+  }
+
+  /**
+   * Subscribes to changes in the cached answer to the given query. The handler
+   * fires on every change or deletion. Returns a destructor that unsubscribes.
+   */
+  onChange(params: K | SingleInput, handler: ChangeHandler<D>): destructor.Destructor;
+  onChange(
+    params: K[] | z.input<Z>,
+    handler: ChangeHandler<D[]>,
+  ): destructor.Destructor;
+  onChange(
+    params: K | K[] | SingleInput | z.input<Z>,
+    handler: ChangeHandler<D> | ChangeHandler<D[]>,
+  ): destructor.Destructor {
+    const [space, query] = this.route(params);
+    return space.onChange(query, handler as ChangeHandler<D | D[]>);
+  }
+
+  /**
+   * Returns the cached answer to the given query without touching the network, or
+   * undefined when nothing is cached. May be stale for unsubscribed queries.
+   */
+  getCached(params: K | SingleInput): Cached<D> | undefined;
+  getCached(params: K[] | z.input<Z>): Cached<D[]> | undefined;
+  getCached(
+    params: K | K[] | SingleInput | z.input<Z>,
+  ): Cached<D> | Cached<D[]> | undefined {
+    const [space, query] = this.route(params);
+    return space.getCached(query) as Cached<D> | Cached<D[]> | undefined;
+  }
+}

package/src/query/streamer.ts

@@ -0,0 +1,207 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { EOF } from "@synnaxlabs/freighter";
+import { type breaker, DataType, errors, zod } from "@synnaxlabs/x";
+import type z from "zod";
+
+import { isConnectionError, NotFoundError } from "@/errors";
+import { type framer } from "@/framer";
+import { HardenedStreamer, ObservableStreamer } from "@/framer/hardened";
+
+/**
+ * A raw channel reaction: parses frames from the channel with the schema and invokes
+ * onChange once per frame with every parsed value, in order. Mirror listeners bind to
+ * this shape internally; domains register reactions via the cache's listen.
+ */
+export interface Listener<Z extends z.ZodType = z.ZodType> {
+  /** The name of the Synnax channel to listen to */
+  channel: string;
+  /** Zod schema for parsing and validating channel data */
+  schema: Z;
+  /** Receives the frame's parsed values for the channel as one batch. */
+  onChange(this: void, changed: z.output<Z>[]): Promise<unknown> | unknown;
+}
+
+/**
+ * Sorts channel names to ensure deletions are processed before other changes. This
+ * ensures that modifications to things like relationships (delete followed by create)
+ * are processed in the correct order.
+ * @returns Sort order (-1, 0, or 1)
+ */
+const channelNameSort = (a: string, b: string) => {
+  const aHasDelete = a.includes("delete");
+  const bHasDelete = b.includes("delete");
+  if (aHasDelete && !bHasDelete) return -1;
+  if (!aHasDelete && bHasDelete) return 1;
+  return 0;
+};
+
+/** Arguments for opening a cache streamer. */
+export interface StreamerParams {
+  /** Receives frame-handling and listener errors. */
+  onError: (error: Error) => void;
+  /** The channel listeners to drive with streamed changes. */
+  listeners: Listener[];
+  /** Opens the raw frame stream; hardening is applied internally. */
+  openStreamer: framer.StreamOpener;
+  /** Retry behavior for stream reconnect attempts. */
+  breaker?: breaker.Config;
+  /** Called once when the stream first opens, before any frame is processed. */
+  onOpen?: () => void;
+  /**
+   * Called after every successful reconnect of the underlying stream (not the
+   * initial open). Changes may have been missed while disconnected.
+   */
+  onReopen?: () => void;
+  /**
+   * Called whenever the stream goes live: after the initial open and before every
+   * onReopen, so reconciliation fetches never race a stale liveness verdict.
+   */
+  onLive?: () => void;
+  /** Called when the underlying stream fails and reconnection begins. */
+  onDrop?: (error: Error) => void;
+  /**
+   * Called when the stream ends on a failure it cannot recover from. The next
+   * demand opens a new stream.
+   */
+  onDead?: (error: Error) => void;
+}
+
+/**
+ * A lazily-opened change stream over the channels named in a table config.
+ * Construction is synchronous and network-free; the underlying stream opens
+ * on the first {@link Streamer.demand} call.
+ */
+export interface Streamer {
+  /**
+   * Ensures the underlying stream is open, opening it on first call. Resolves
+   * once streaming is live. Safe to call concurrently and repeatedly.
+   */
+  demand: () => Promise<void>;
+  /** Closes the stream. A no-op when the stream was never demanded. */
+  close: () => Promise<void>;
+}
+
+/**
+ * Creates a lazy streamer that, once demanded, listens to configured channels and
+ * invokes the appropriate listeners when data changes.
+ * @returns The lazy streamer handle
+ */
+export const createStreamer = ({
+  openStreamer,
+  breaker: breakerConfig,
+  listeners: allListeners,
+  onError,
+  onOpen,
+  onReopen,
+  onLive,
+  onDrop,
+  onDead,
+}: StreamerParams): Streamer => {
+  let opened: Promise<ObservableStreamer> | null = null;
+  let hardened: HardenedStreamer | null = null;
+  let closed = false;
+  const report = (exc: unknown, message: string) => {
+    if (NotFoundError.matches(exc)) return;
+    // A connectivity failure mid-change is repaired by the reconcile that
+    // follows the stream's reopen, so it is churn, not a defect.
+    if (isConnectionError(exc)) return;
+    onError(new Error(message, { cause: exc }));
+  };
+  const open = async (): Promise<ObservableStreamer> => {
+    if (closed) throw new EOF();
+    const listenersForChannels = Map.groupBy(allListeners, ({ channel }) => channel);
+    const channels = Array.from(listenersForChannels.keys());
+    const h = new HardenedStreamer(
+      openStreamer,
+      { channels },
+      breakerConfig,
+      // onLive first: onReopen's reconcile fetches must not hit a stale
+      // liveness short circuit
+      () => {
+        onLive?.();
+        onReopen?.();
+      },
+      onDrop,
+    );
+    // Held outside so close() can interrupt the retry loop while this call
+    // is still waiting on a first successful open.
+    hardened = h;
+    await h.start();
+    // ObservableStreamer construction below starts reads, so onOpen precedes any frame.
+    onOpen?.();
+    onLive?.();
+    const handleChange = (frame: framer.Frame) => {
+      const namesInFrame = frame.uniqueNames.sort(channelNameSort);
+      void (async () => {
+        for (const name of namesInFrame) {
+          const series = frame.get(name);
+          const listeners = listenersForChannels.get(name);
+          if (listeners == null) continue;
+          const parseOpts = { label: `${name} sample` };
+          for (const { onChange, schema } of listeners) {
+            let parsed: z.output<typeof schema>[];
+            try {
+              if (!series.dataType.equals(DataType.JSON))
+                parsed = Array.from(series).map((s) => zod.parse(schema, s, parseOpts));
+              else parsed = series.parseJSON(schema);
+            } catch (exc) {
+              report(exc, `failed to parse streamer change for ${name}`);
+              continue;
+            }
+            if (parsed.length === 0) continue;
+            try {
+              await onChange(parsed);
+            } catch (exc) {
+              report(exc, `failed to handle streamer change for ${name}`);
+            }
+          }
+        }
+      })();
+    };
+    const stream = new ObservableStreamer(h, undefined, (error) => {
+      // drop the memoized stream so the next demand opens a fresh one
+      opened = null;
+      onDead?.(error);
+    });
+    stream.onChange(handleChange);
+    return stream;
+  };
+  return {
+    demand: async () => {
+      if (opened == null) {
+        const { promise, resolve, reject } =
+          Promise.withResolvers<ObservableStreamer>();
+        // Assigned before open runs: opening resolves channels through the cached
+        // read path, which re-enters demand synchronously. An unset memo there
+        // recurses instead of joining. Keep these two statements in this order.
+        opened = promise;
+        open().then(resolve, reject);
+      }
+      try {
+        await opened;
+      } catch (exc) {
+        // clear the memoized failure so a later demand can retry the open
+        opened = null;
+        // a close mid-open retires the stream; the demand did not fail
+        if (closed) return;
+        throw errors.fromUnknown(exc);
+      }
+    },
+    close: async () => {
+      closed = true;
+      // Interrupts an in-flight open's retry loop; opened then settles.
+      hardened?.close();
+      if (opened == null) return;
+      const streamer = await opened.catch(() => null);
+      if (streamer != null) await streamer.close();
+    },
+  };
+};