@synnaxlabs/client 0.56.2 → 0.57.1

package/src/framer/cache/unary.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 { MultiSeries, type Series, type TimeRange } from "@synnaxlabs/x";
+
+import { UnexpectedError } from "@/errors";
+import { Dynamic, type DynamicProps } from "@/framer/cache/dynamic";
+import {
+  type DirtyReadResult,
+  type GCMetrics,
+  Static,
+  type StaticProps,
+} from "@/framer/cache/static";
+
+export interface UnaryProps
+  extends StaticProps, Pick<DynamicProps, "dynamicBufferSize"> {}
+
+/**
+ * Caches data for a single channel: a dynamic leading buffer for live writes backed
+ * by a static cache for flushed and historical data.
+ * @throws {UnexpectedError} from every method after close().
+ */
+export class Unary {
+  private closed: boolean = false;
+  private readonly static: Static;
+  private readonly dynamic: Dynamic;
+
+  constructor(props: UnaryProps) {
+    this.static = new Static(props);
+    this.dynamic = new Dynamic({
+      dynamicBufferSize: props.dynamicBufferSize,
+      transform: props.transform,
+      instrumentation: props.instrumentation,
+    });
+  }
+
+  writeDynamic(series: MultiSeries): MultiSeries {
+    this.checkOpen("writeDynamic");
+    const { flushed, allocated } = this.dynamic.write(series);
+    // Flushed buffers stay streamed until a fetch replaces them.
+    if (flushed.length > 0) this.static.write(flushed, true);
+    return allocated;
+  }
+
+  get leadingBuffer(): Series | null {
+    this.checkOpen("leadingBuffer");
+    return this.dynamic.leadingBuffer;
+  }
+
+  /**
+   * Flushes the live leading buffer into the static cache with its real end time,
+   * so reads treat the span after it as a gap to fetch. Call when streaming for
+   * the channel stops.
+   */
+  flushDynamic(): void {
+    this.checkOpen("flushDynamic");
+    const flushed = this.dynamic.flush();
+    if (flushed != null && flushed.length > 0)
+      this.static.write(new MultiSeries([flushed]), true);
+  }
+
+  writeStatic(series: MultiSeries): void {
+    this.checkOpen("writeStatic");
+    this.static.write(series);
+  }
+
+  /**
+   * Reads cached data overlapping the given time range. The result includes the live
+   * leading buffer when the data it actually holds overlaps the range, judged by the
+   * last stamped write rather than the buffer's provisional MAX end, so the buffer
+   * never leaks into reads of spans it has no samples for. It never claims coverage
+   * either: its samples carry provisional leading alignments that cannot pair with
+   * fetched data on another channel, so its span is still reported as a gap to fetch. A
+   * span may therefore return in both its streamed and fetched representation.
+   */
+  read(tr: TimeRange): DirtyReadResult {
+    this.checkOpen("read");
+    const res = this.static.dirtyRead(tr);
+    const buf = this.dynamic.leadingBuffer;
+    const dataTr = this.dynamic.dataTimeRange;
+    if (buf == null || dataTr == null || buf.length === 0 || !dataTr.overlapsWith(tr))
+      return res;
+    res.series.push(buf);
+    return res;
+  }
+
+  gc(): GCMetrics {
+    this.checkOpen("gc");
+    return this.static.gc();
+  }
+
+  close(): void {
+    this.closed = true;
+    this.dynamic.close();
+    this.static.close();
+  }
+
+  private checkOpen(op: string): void {
+    if (this.closed)
+      throw new UnexpectedError(`${op} called on a closed telemetry cache entry`);
+  }
+}

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();
+  }
+}