@synnaxlabs/client 0.56.1 → 0.57.0

package/src/framer/client.ts

@@ -17,8 +17,11 @@ import {
   TimeSpan,
 } from "@synnaxlabs/x";
 
-import { channel } from "@/channel";
+import { type channel } from "@/channel";
+import { analyzeParams } from "@/channel/payload";
+import { type ChannelRetriever } from "@/framer/adapter";
 import { Deleter } from "@/framer/deleter";
+import { Feed, type FeedOptions } from "@/framer/feed";
 import { Frame } from "@/framer/frame";
 import { AUTO_SPAN, Iterator, type IteratorConfig } from "@/framer/iterator";
 import { Reader, type ReadRequest } from "@/framer/reader";
@@ -29,27 +32,32 @@ import { ontology } from "@/ontology";
 export const ontologyID = ontology.createIDFactory<string>("framer");
 export const TYPE_ONTOLOGY_ID = ontologyID("");
 
+/** Config for {@link Client}. */
+export interface ClientConfig {
+  stream: WebSocketClient;
+  unary: UnaryClient;
+  retrieveChannels: ChannelRetriever;
+}
+
+/**
+ * Reads and writes telemetry on a Core. Reach it through `client.telem` rather than
+ * building one: `read` and `write` cover one-shot access, and the `open*` methods hand
+ * back a long-lived stream the caller must close.
+ */
 export class Client {
-  private readonly streamClient: WebSocketClient;
-  private readonly retriever: channel.Retriever;
+  private readonly cfg: ClientConfig;
   private readonly deleter: Deleter;
   private readonly reader: Reader;
 
-  constructor(
-    stream: WebSocketClient,
-    unary: UnaryClient,
-    retriever: channel.Retriever,
-  ) {
-    this.streamClient = stream;
-    this.retriever = retriever;
+  constructor(cfg: ClientConfig) {
+    const { stream, unary, retrieveChannels } = cfg;
+    this.cfg = cfg;
     this.deleter = new Deleter(unary);
-    this.reader = new Reader(retriever, stream);
+    this.reader = new Reader(retrieveChannels, stream);
   }
 
   /**
    * Opens a new iterator over the given channels within the provided time range.
-   *
-   * @param tr - A time range to iterate over.
    * @param channels - A list of channels (by name or key) to iterate over.
    * @param opts - see {@link IteratorConfig}
    * @returns a new {@link Iterator}.
@@ -59,33 +67,47 @@ export class Client {
     channels: channel.Params,
     opts?: IteratorConfig,
   ): Promise<Iterator> {
-    return await Iterator._open(tr, channels, this.retriever, this.streamClient, opts);
+    return await Iterator._open(
+      tr,
+      channels,
+      this.cfg.retrieveChannels,
+      this.cfg.stream,
+      opts,
+    );
   }
 
   /**
    * Opens a new writer on the given channels.
-   *
    * @param config - The configuration for the created writer, see documentation for
    * writerConfig for more detail.
    * @returns a new {@link Writer}.
    */
   async openWriter(config: WriterConfig): Promise<Writer> {
-    return await Writer._open(this.retriever, this.streamClient, config);
+    return await Writer._open(this.cfg.retrieveChannels, this.cfg.stream, config);
   }
 
   /**
    * Opens a new streamer with the provided configuration.
-   *
-   * @param config - Configuration parameters for the streamer.
    * @param config.channels - The channels to stream values from. Can be a key, name,
    * list of keys, or list of names.
-   * @param config.from - If this parameter is set and is before the current time,
-   * the streamer will first read and receive historical data from before this point
-   * and then will start reading new values.
-   *
+   * @param config.from - If this parameter is set and is before the current time, the
+   * streamer will first read and receive historical data from before this point and
+   * then will start reading new values.
    */
   async openStreamer(config: StreamerConfig): Promise<Streamer> {
-    return await openStreamer(this.retriever, this.streamClient, config);
+    return await openStreamer(this.cfg.retrieveChannels, this.cfg.stream, config);
+  }
+
+  /**
+   * Opens a feed over this client. The underlying stream opens on first demand;
+   * the caller must close the feed.
+   */
+  openFeed(options: FeedOptions = {}): Feed {
+    return new Feed({
+      ...options,
+      readRemote: async (tr, keys) => await this.read(tr, keys),
+      openStreamer: async (config) => await this.openStreamer(config),
+    });
   }
 
   async write(
@@ -106,13 +128,13 @@ export class Client {
   ): Promise<void>;
 
   /**
-   * Writes telemetry to the given channel starting at the given timestamp.
+   * Writes telemetry to the given channels, starting at the given timestamp. It commits
+   * and closes before it returns, so the samples land on disk.
    *
-   * @param channels - The key of the channel to write to.
-   * @param start - The starting timestamp of the first sample in data.
-   * @param data  - The telemetry to write. This telemetry must have the same
-   * data type as the channel.
-   * @throws if the channel does not exist.
+   * @param start - The timestamp of the first sample.
+   * @throws {NotFoundError} if a channel does not exist.
+   * @throws {UnauthorizedError} if another writer holds control of a channel.
+   * @throws {ValidationError} if the data type does not match the channel's.
    */
   async write(
     start: CrudeTimeStamp,
@@ -142,6 +164,12 @@ export class Client {
     await w.close();
   }
 
+  /**
+   * Reads every sample in the time range from the given channels.
+   *
+   * @returns a {@link MultiSeries} for one channel, or a {@link Frame} for several.
+   * @throws {NotFoundError} if a channel does not exist.
+   */
   async read(
     tr: CrudeTimeRange,
     channel: channel.Key | channel.Name,
@@ -153,7 +181,7 @@ export class Client {
     channels?: channel.Params,
   ): Promise<MultiSeries | Frame | ReadableStream<Uint8Array>> {
     if (!("start" in tr)) return await this.reader.read(tr);
-    const { single } = channel.analyzeParams(channels!);
+    const { single } = analyzeParams(channels!);
     const fr = await this.readFrame(tr, channels!);
     if (single) return fr.get(channels as channel.Key | channel.Name);
     return fr;
@@ -181,22 +209,18 @@ export class Client {
   async readLatest(channels: channel.Params, n: number): Promise<Frame>;
 
   /**
-   * Reads the latest n samples from the given channel(s).
-   *
-   * If fewer than n samples are available, returns only the samples that
-   * exist.
-   *
-   * @param channels - A single channel key/name or an array of channel
-   * keys/names.
+   * Reads the latest n samples from the given channel(s). If fewer than n samples are
+   * available, returns only the samples that exist.
+   * @param channels - A single channel key/name or an array of channel keys/names.
    * @param n - The maximum number of samples to read. Defaults to 1.
-   * @returns A MultiSeries when a single channel is provided, or a Frame when
-   * multiple channels are provided.
+   * @returns A MultiSeries when a single channel is provided, or a Frame when multiple
+   * channels are provided.
    */
   async readLatest(
     channels: channel.Params,
     n: number = 1,
   ): Promise<MultiSeries | Frame> {
-    const { single } = channel.analyzeParams(channels);
+    const { single } = analyzeParams(channels);
     const fr = await this.readLatestNFrame(channels, n);
     if (single) return fr.get(channels as channel.Key | channel.Name);
     return fr;
@@ -216,11 +240,15 @@ export class Client {
     return frame;
   }
 
+  /**
+   * Deletes every sample in the time range from the given channels. Deletion is
+   * permanent.
+   */
   async delete(channels: channel.Params, timeRange: CrudeTimeRange): Promise<void> {
-    const { normalized, variant } = channel.analyzeParams(channels);
+    const { normalized, variant } = analyzeParams(channels);
     const bounds = new TimeRange(timeRange);
     if (variant === "keys")
-      return await this.deleter.delete({ keys: normalized as channel.Key[], bounds });
-    return await this.deleter.delete({ names: normalized as string[], bounds });
+      return await this.deleter.delete({ keys: normalized, bounds });
+    return await this.deleter.delete({ names: normalized, bounds });
   }
 }

package/src/framer/codec.ts

@@ -24,22 +24,51 @@ import { type StreamerResponse } from "@/framer/streamer";
 import { IteratorResponseVariant, WriterCommand } from "@/framer/types.gen";
 import { type WriteRequest } from "@/framer/writer";
 
+const BITS_PER_BYTE = 8;
+
+const bitPackedByteCount = (nSamples: number): number =>
+  Math.ceil(nSamples / BITS_PER_BYTE);
+
 const seriesPldLength = (series: SeriesPayload): number =>
   series.data.byteLength / series.dataType.density.valueOf();
 
-interface KeyedSeries extends SeriesPayload {
-  key: number;
-}
+const seriesWireByteLength = (series: SeriesPayload): number => {
+  if (series.dataType.equals(DataType.BOOLEAN))
+    return bitPackedByteCount(seriesPldLength(series));
+  return series.data.byteLength;
+};
+
+const packBoolBits = (src: ArrayBuffer | Uint8Array): Uint8Array => {
+  const srcBytes = src instanceof Uint8Array ? src : new Uint8Array(src);
+  const dst = new Uint8Array(bitPackedByteCount(srcBytes.length));
+  for (let i = 0; i < srcBytes.length; i++)
+    if (srcBytes[i] !== 0)
+      dst[Math.floor(i / BITS_PER_BYTE)] |= 1 << (i % BITS_PER_BYTE);
+  return dst;
+};
+
+const unpackBoolBits = (src: Uint8Array, sampleCount: number): ArrayBuffer => {
+  const buf = new ArrayBuffer(sampleCount);
+  const dst = new Uint8Array(buf);
+  for (let i = 0; i < sampleCount; i++)
+    dst[i] = (src[Math.floor(i / BITS_PER_BYTE)] >> (i % BITS_PER_BYTE)) & 1;
+  return buf;
+};
+
+/** Orders channel keys the way the Core does. The default comparator sorts numbers as
+ * strings and diverges as soon as two keys differ in decimal width. */
+const compareKeys = (a: channel.Key, b: channel.Key): number => a - b;
 
 const sortFramePayloadByKey = (framePayload: Payload): void => {
   const { keys, series } = framePayload;
-  keys.forEach((key, index) => {
-    (series[index] as KeyedSeries).key = key;
-  });
-  series.sort((a, b) => (a as KeyedSeries).key - (b as KeyedSeries).key);
-  keys.sort((a, b) => a - b);
-  // @ts-expect-error - deleting static property keys.
-  series.forEach((ser) => delete (ser as KeyedSeries).key);
+  if (keys.every((k, i) => i === 0 || keys[i - 1] <= k)) return;
+  const order = keys.map((_, i) => i).sort((a, b) => compareKeys(keys[a], keys[b]));
+  const orderedKeys = order.map((i) => keys[i]);
+  const orderedSeries = order.map((i) => series[i]);
+  for (let i = 0; i < keys.length; i++) {
+    keys[i] = orderedKeys[i];
+    series[i] = orderedSeries[i];
+  }
 };
 
 const ZERO_ALIGNMENTS_FLAG_POS = 5;
@@ -75,7 +104,7 @@ export class Codec {
   update(keys: channel.Key[], dataTypes: DataType[]): void {
     this.seqNum++;
     const state = {
-      keys,
+      keys: [...keys],
       keyDataTypes: new Map(),
       hasVariableDataTypes: false,
     };
@@ -84,7 +113,9 @@ export class Codec {
       state.keyDataTypes.set(k, dt);
       if (dt.isVariable) state.hasVariableDataTypes = true;
     });
-    state.keys.sort();
+    // Encoder and decoder walk this order positionally when a frame carries every
+    // channel, so it has to match the Core's.
+    state.keys.sort(compareKeys);
     this.states.set(this.seqNum, state);
     this.currState = state;
   }
@@ -133,7 +164,7 @@ export class Codec {
           `Series data type of ${series.dataType.toString()} does not match the data type of ${dt.toString()} for channel ${key}`,
         );
 
-      byteArraySize += series.data.byteLength;
+      byteArraySize += seriesWireByteLength(series);
       if (currDataSize === -1) {
         currDataSize = pldLength;
         startTime = series.timeRange?.start;
@@ -208,8 +239,11 @@ export class Codec {
         view.setUint32(offset, seriesLengthOrSize, true);
         offset += DATA_LENGTH_SIZE;
       }
-      buffer.set(new Uint8Array(series.data), offset);
-      offset += series.data.byteLength;
+      const bytes = series.dataType.equals(DataType.BOOLEAN)
+        ? packBoolBits(series.data)
+        : new Uint8Array(series.data);
+      buffer.set(bytes, offset);
+      offset += bytes.byteLength;
       if (!equalTimeRangesFlag && !timeRangesZeroFlag) {
         view.setBigUint64(offset, series.timeRange?.start.valueOf() ?? 0n, true);
         offset += TIMESTAMP_SIZE;
@@ -281,12 +315,15 @@ export class Codec {
 
       let dataByteLength = currSize;
       if (!dataType.isVariable) dataByteLength *= dataType.density.valueOf();
-      if (index + dataByteLength > view.byteLength) return false;
+      const isBool = dataType.equals(DataType.BOOLEAN);
+      const wireByteLength = isBool ? bitPackedByteCount(currSize) : dataByteLength;
+      if (index + wireByteLength > view.byteLength) return false;
+      const wireBytes = src.slice(index, index + wireByteLength);
       const currSeries: SeriesPayload = {
         dataType,
-        data: src.slice(index, index + dataByteLength).buffer,
+        data: isBool ? unpackBoolBits(wireBytes, currSize) : wireBytes.buffer,
       };
-      index += dataByteLength;
+      index += wireByteLength;
       if (!equalTimeRangesFlag && !timeRangesZeroFlag) {
         if (index + TIMESTAMP_SIZE * 2 > view.byteLength) return false;
         const start = view.getBigUint64(index, true);

package/src/framer/deleter.ts

@@ -11,21 +11,19 @@ import { type UnaryClient } from "@synnaxlabs/freighter";
 import { TimeRange } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { channel } from "@/channel";
+import { keyZ, nameZ } from "@/channel/types.gen";
 
 const reqZ = z.object({
-  keys: channel.keyZ.array().optional(),
+  keys: keyZ.array().optional(),
   bounds: TimeRange.z,
-  names: channel.nameZ.array().optional(),
+  names: nameZ.array().optional(),
 });
 interface Request extends z.infer<typeof reqZ> {}
 
 const resZ = z.object({});
 
+/** Deletes a time range of telemetry from a Core. Reach it through `client.telem`. */
 export class Deleter {
-  /*
-  Deleter is used to delete a time range of telemetry from the data engine.
-   */
   private readonly client: UnaryClient;
 
   constructor(client: UnaryClient) {

package/src/framer/external.ts

@@ -7,8 +7,18 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export { type ChannelRetriever } from "@/framer/adapter";
+export { type RemoteReader } from "@/framer/cache/reader";
+export {
+  type StatusHandler,
+  type StreamHandler,
+  type Subscription,
+} from "@/framer/cache/streamer";
+export { IDENTITY_TRANSFORM, type Transform } from "@/framer/cache/transform";
 export * from "@/framer/client";
+export * from "@/framer/feed";
 export * from "@/framer/frame";
+export * from "@/framer/hardened";
 export * from "@/framer/iterator";
 export * from "@/framer/reader";
 export * from "@/framer/streamer";

package/src/framer/feed.ts

@@ -0,0 +1,108 @@
+// 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 MultiSeries, type TimeRange } from "@synnaxlabs/x";
+
+import { type channel } from "@/channel";
+import { Cache, type CacheProps } from "@/framer/cache/cache";
+import { Reader, type ReaderProps } from "@/framer/cache/reader";
+import {
+  MultiplexedStreamer,
+  type MultiplexedStreamerProps,
+  type StreamHandler,
+  type Subscription,
+} from "@/framer/cache/streamer";
+import { HardenedStreamer } from "@/framer/hardened";
+import { type StreamOpener } from "@/framer/streamer";
+
+/** Props for {@link Feed}, including the transport it reads and streams through. */
+export interface FeedProps
+  extends
+    CacheProps,
+    Omit<ReaderProps, "cache">,
+    Omit<MultiplexedStreamerProps, "cache" | "openStreamer"> {
+  openStreamer: StreamOpener;
+}
+
+/** The part of {@link FeedProps} a caller sets. The client supplies the rest. */
+export interface FeedOptions extends Omit<FeedProps, "readRemote" | "openStreamer"> {}
+
+/**
+ * Cached, demand-managed access to channel telemetry: durable streaming
+ * subscriptions multiplexed onto one frame stream, and batched historical reads
+ * served through per-channel rolling buffers.
+ */
+export class Feed {
+  private readonly cache: Cache;
+  private readonly reader: Reader;
+  private readonly streamer: MultiplexedStreamer;
+
+  constructor(props: FeedProps) {
+    const {
+      readRemote,
+      openStreamer,
+      transform,
+      instrumentation,
+      dynamicBufferSize,
+      gcInterval,
+      staleEntryThreshold,
+      removalDelay,
+      breaker,
+      batchDebounce,
+      overlapThreshold,
+    } = props;
+    this.cache = new Cache({
+      transform,
+      dynamicBufferSize,
+      gcInterval,
+      staleEntryThreshold,
+      instrumentation: instrumentation?.child("cache"),
+    });
+    this.reader = new Reader({
+      readRemote,
+      cache: this.cache,
+      batchDebounce,
+      overlapThreshold,
+    });
+    this.streamer = new MultiplexedStreamer({
+      cache: this.cache,
+      openStreamer: async (config, { onReopen, onDrop }) =>
+        await HardenedStreamer.open(openStreamer, config, breaker, onReopen, onDrop),
+      removalDelay,
+      breaker,
+      instrumentation: instrumentation?.child("streamer"),
+    });
+  }
+
+  /**
+   * Registers durable streaming demand for the given keys. Returns synchronously;
+   * convergence failures surface as per-key statuses, never as rejections. The
+   * handler's first call precedes registration, so a throw from it leaves no
+   * subscription behind.
+   * @throws {UnexpectedError} if the feed has been closed.
+   */
+  stream(handler: StreamHandler, keys: channel.Key[]): Subscription {
+    return this.streamer.stream(handler, keys);
+  }
+
+  /**
+   * Reads the given time range for the given channel, serving from the cache and
+   * gap-filling from the cluster.
+   */
+  async read(tr: TimeRange, key: channel.Key): Promise<MultiSeries> {
+    return await this.reader.read(tr, key);
+  }
+
+  /** Closes the feed, releasing the stream and all cached buffers. */
+  async close(): Promise<void> {
+    await this.streamer.close();
+    await this.reader.close();
+    this.cache.close();
+  }
+}

package/src/framer/frame.ts

@@ -26,6 +26,7 @@ import { UnexpectedError, ValidationError } from "@/errors";
 
 type ColumnType = "key" | "name" | null;
 
+/** A frame's shape without its samples, for logging and debugging. */
 export interface Digest extends Record<channel.Key | channel.Name, SeriesDigest[]> {}
 
 const columnType = (columns: channel.PrimitiveParams): ColumnType => {
@@ -53,6 +54,7 @@ const validateMatchedColsAndSeries = (
   );
 };
 
+/** Anything {@link Frame}'s constructor accepts. */
 export type CrudeFrame =
   | Frame
   | CrudePayload
@@ -108,7 +110,6 @@ export class Frame {
       return;
     }
 
-    // Construction from a map.
     if (columnsOrData instanceof Map) {
       columnsOrData.forEach((v, k) => this.push(k, ...array.toArray(v)));
       return;
@@ -116,7 +117,6 @@ export class Frame {
 
     const isObject = typeof columnsOrData === "object" && !Array.isArray(columnsOrData);
 
-    // Construction from a payload.
     if (isObject) {
       if ("keys" in columnsOrData && "series" in columnsOrData) {
         const data_ = columnsOrData as Payload;
@@ -124,7 +124,8 @@ export class Frame {
         data_.keys ??= [];
         const series = data_.series.map((a) => seriesFromPayload(a));
         validateMatchedColsAndSeries(data_.keys, series);
-        data_.keys.forEach((key, i) => this.push(key, series[i]));
+        this.columns = data_.keys.slice();
+        this.series = series;
       } else
         Object.entries(columnsOrData).forEach(([k, v]) => {
           const key = parseInt(k, 10);
@@ -134,7 +135,6 @@ export class Frame {
       return;
     }
 
-    // Construction from a set of series and columns.
     if (
       Array.isArray(columnsOrData) ||
       ["string", "number"].includes(typeof columnsOrData)
@@ -197,9 +197,7 @@ export class Frame {
     return unique.unique(this.names);
   }
 
-  /**
-   * @returns the unique columns in the frame.
-   */
+  /** @returns the unique columns in the frame. */
   get uniqueColumns(): channel.Key[] | channel.Name[] {
     return this.colType === "key" ? this.uniqueKeys : this.uniqueNames;
   }
@@ -246,8 +244,8 @@ export class Frame {
    */
   get isWeaklyAligned(): boolean {
     if (this.columns.length <= 1) return true;
-    const ranges = this.timeRanges;
-    return ranges.every((tr) => tr.equals(ranges[0]));
+    const { timeRanges } = this;
+    return timeRanges.every((tr) => tr.equals(timeRanges[0]));
   }
 
   timeRange(col?: channel.Key | channel.Name): TimeRange {
@@ -288,19 +286,10 @@ export class Frame {
     return new MultiSeries(this.series.filter((_, i) => this.columns[i] === key));
   }
 
-  /**
-   * Pushes a set of series for the given channel onto the frame.
-   *
-   * @param key the channel key or name;
-   * @param v the series to push.
-   */
+  /** Pushes a set of series for the given channel onto the frame. */
   push(key: channel.Key | channel.Name, ...v: Series[]): void;
 
-  /**
-   * Pushes the frame onto the current frame.
-   *
-   * @param frame  - the frame to push.
-   */
+  /** Pushes the frame onto the current frame. */
   push(frame: Frame): void;
 
   push(keyOrFrame: channel.Key | channel.Name | Frame, ...v: Series[]): void {
@@ -348,8 +337,7 @@ export class Frame {
 
   /**
    * @returns a new frame containing the mapped output of the provided function.
-   * @param fn a function that takes a channel key and series and returns a
-   * boolean.
+   * @param fn a function that takes a channel key and series and returns a boolean.
    */
   map(
     fn: (
@@ -380,7 +368,6 @@ export class Frame {
 
   /**
    * Iterates over all series in the current frame.
-   *
    * @param fn a function that takes a channel key and series.
    */
   forEach(fn: (k: channel.Key | channel.Name, arr: Series, i: number) => void): void {
@@ -470,6 +457,7 @@ export class Frame {
   }
 }
 
+/** Zod schema for a frame on the wire. */
 export const frameZ = z.object({
   keys: z.union([
     z.null().transform<number[]>(() => []),
@@ -485,11 +473,13 @@ export interface Payload extends z.infer<typeof frameZ> {}
 
 export interface CrudePayload extends z.input<typeof frameZ> {}
 
+/** Rebuilds a {@link Series} from its wire form. */
 export const seriesFromPayload = (series: SeriesPayload): Series => {
   const { dataType, data, timeRange, alignment } = series;
   return new Series({ data, dataType, timeRange, glBufferUsage: "static", alignment });
 };
 
+/** Reduces a {@link Series} to its wire form. */
 export const seriesToPayload = (series: Series): SeriesPayload => ({
   timeRange: series.timeRange,
   dataType: series.dataType,