@synnaxlabs/client 0.56.1 → 0.57.0

package/src/ethercat/types.gen.ts

@@ -0,0 +1,151 @@
+// 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { id, zod } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { channel } from "@/channel";
+import { device } from "@/device";
+import { task } from "@/task";
+
+/** PDOAddress addresses a PDO entry explicitly in the CoE object dictionary. */
+export const pdoAddressZ = z.object({
+  /** index is the CoE object dictionary index of the PDO entry. */
+  index: zod.uint16.default(0),
+  /** subIndex is the CoE object dictionary sub-index of the PDO entry. */
+  subIndex: zod.uint8.default(0),
+  /** bitLength is the size of the PDO entry, in bits. */
+  bitLength: zod.uint8.default(16),
+  /** dataType is the data type of the PDO entry. */
+  dataType: z.string().default("uint16"),
+});
+export interface PDOAddress extends z.infer<typeof pdoAddressZ> {}
+
+/** BaseReadChannel carries the fields every EtherCAT read channel shares. */
+export const baseReadChannelZ = z.object({
+  /** key uniquely identifies the channel within the task. */
+  key: z.string().default(id.create),
+  /** name is the human-readable channel name. */
+  name: z.string().default(""),
+  /** disabled is true when the channel is excluded from acquisition. */
+  disabled: z.boolean().default(false),
+  /** channel is the Synnax channel that raw samples are written to. */
+  channel: channel.keyZ.default(0),
+  /** device is the key of the slave device the channel reads from. */
+  device: device.keyZ.default(""),
+});
+export interface BaseReadChannel extends z.infer<typeof baseReadChannelZ> {}
+
+/** BaseWriteChannel carries the fields every EtherCAT write channel shares. */
+export const baseWriteChannelZ = z.object({
+  /** key uniquely identifies the channel within the task. */
+  key: z.string().default(id.create),
+  /** name is the human-readable channel name. */
+  name: z.string().default(""),
+  /** disabled is true when the channel is excluded from the task. */
+  disabled: z.boolean().default(false),
+  /** cmdChannel is the Synnax channel commands are read from. */
+  cmdChannel: channel.keyZ.default(0),
+  /** stateChannel is the Synnax channel the output state is written to. */
+  stateChannel: channel.keyZ.default(0),
+  /** cmdChannelName is the human-readable name of the command channel. */
+  cmdChannelName: z.string().default(""),
+  /** stateChannelName is the human-readable name of the state channel. */
+  stateChannelName: z.string().default(""),
+  /** device is the key of the slave device the channel writes to. */
+  device: device.keyZ.default(""),
+});
+export interface BaseWriteChannel extends z.infer<typeof baseWriteChannelZ> {}
+
+export const scanConfigZ = task.scanConfigZ;
+export interface ScanConfig extends z.infer<typeof scanConfigZ> {}
+
+/** AutomaticReadChannel resolves its PDO address from the slave's discovered PDOs. */
+export const automaticReadChannelZ = baseReadChannelZ.extend({
+  type: z.literal("automatic"),
+  /** pdo is the name of the PDO entry to resolve on the slave. */
+  pdo: z.string().default(""),
+});
+export interface AutomaticReadChannel extends z.infer<typeof automaticReadChannelZ> {}
+
+/** ManualReadChannel specifies its PDO address inline. */
+export const manualReadChannelZ = baseReadChannelZ.extend(pdoAddressZ.shape).extend({
+  type: z.literal("manual"),
+});
+export interface ManualReadChannel extends z.infer<typeof manualReadChannelZ> {}
+
+export const READ_CHANNEL_TYPES = ["automatic", "manual"] as const;
+export const readChannelTypeZ = z.enum(READ_CHANNEL_TYPES);
+export type ReadChannelType = z.infer<typeof readChannelTypeZ>;
+
+/**
+ * ReadChannel is a single EtherCAT read channel (TxPDO, slave to master). The type
+ * field selects how the PDO entry is addressed.
+ */
+export const readChannelZ = z.discriminatedUnion("type", [
+  automaticReadChannelZ,
+  manualReadChannelZ,
+]);
+export type ReadChannel = AutomaticReadChannel | ManualReadChannel;
+
+export const READ_CHANNEL_SCHEMAS: {
+  [K in ReadChannelType]: z.ZodType<Extract<ReadChannel, { type: K }>>;
+} = {
+  automatic: automaticReadChannelZ,
+  manual: manualReadChannelZ,
+};
+
+/** AutomaticWriteChannel resolves its PDO address from the slave's discovered PDOs. */
+export const automaticWriteChannelZ = baseWriteChannelZ.extend({
+  type: z.literal("automatic"),
+  /** pdo is the name of the PDO entry to resolve on the slave. */
+  pdo: z.string().default(""),
+});
+export interface AutomaticWriteChannel extends z.infer<typeof automaticWriteChannelZ> {}
+
+/** ManualWriteChannel specifies its PDO address inline. */
+export const manualWriteChannelZ = baseWriteChannelZ.extend(pdoAddressZ.shape).extend({
+  type: z.literal("manual"),
+});
+export interface ManualWriteChannel extends z.infer<typeof manualWriteChannelZ> {}
+
+export const WRITE_CHANNEL_TYPES = ["automatic", "manual"] as const;
+export const writeChannelTypeZ = z.enum(WRITE_CHANNEL_TYPES);
+export type WriteChannelType = z.infer<typeof writeChannelTypeZ>;
+
+/**
+ * WriteChannel is a single EtherCAT write channel (RxPDO, master to slave). The type
+ * field selects how the PDO entry is addressed.
+ */
+export const writeChannelZ = z.discriminatedUnion("type", [
+  automaticWriteChannelZ,
+  manualWriteChannelZ,
+]);
+export type WriteChannel = AutomaticWriteChannel | ManualWriteChannel;
+
+export const WRITE_CHANNEL_SCHEMAS: {
+  [K in WriteChannelType]: z.ZodType<Extract<WriteChannel, { type: K }>>;
+} = {
+  automatic: automaticWriteChannelZ,
+  manual: manualWriteChannelZ,
+};
+
+export const readConfigZ = task.readConfigZ.extend({
+  channels: readChannelZ.array().default(() => []),
+});
+export interface ReadConfig extends z.infer<typeof readConfigZ> {}
+
+export const writeConfigZ = task.persistConfigZ.extend({
+  stateRate: z.number().default(25),
+  executionRate: z.number().default(1000),
+  channels: writeChannelZ.array().default(() => []),
+});
+export interface WriteConfig extends z.infer<typeof writeConfigZ> {}

package/src/framer/adapter.ts

@@ -7,43 +7,61 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { compare, type CrudeSeries, Series } from "@synnaxlabs/x";
+import { type CrudeSeries, Series } from "@synnaxlabs/x";
 
-import { channel } from "@/channel";
-import { ValidationError } from "@/errors";
+import { type channel } from "@/channel";
+import { analyzeParams, paramsZ } from "@/channel/payload";
+import { QueryError, ValidationError } from "@/errors";
 import { Codec } from "@/framer/codec";
 import { type CrudeFrame, Frame } from "@/framer/frame";
 
+/** Fetches channel payloads. Missing channels are omitted, not thrown. */
+export type ChannelRetriever = (channels: channel.Params) => Promise<channel.Payload[]>;
+
+/** Fetches channel payloads, throwing a {@link QueryError} when any is missing. */
+const retrieveRequired = async (
+  retrieve: ChannelRetriever,
+  channels: channel.Params,
+): Promise<channel.Payload[]> => {
+  const { normalized } = analyzeParams(channels);
+  const results = await retrieve(normalized);
+  const notFound: (channel.Key | channel.Name)[] = [];
+  normalized.forEach((v) => {
+    if (results.find((c) => c.name === v || c.key === v) == null) notFound.push(v);
+  });
+  if (notFound.length > 0)
+    throw new QueryError(`Could not find channels: ${JSON.stringify(notFound)}`);
+  return results;
+};
+
 export class ReadAdapter {
   private adapter: Map<channel.Key, string> | null;
-  retriever: channel.Retriever;
+  private readonly retrieveChannels: ChannelRetriever;
   keys: Set<channel.Key>;
   codec: Codec;
 
-  private constructor(retriever: channel.Retriever) {
-    this.retriever = retriever;
+  private constructor(retrieveChannels: ChannelRetriever) {
+    this.retrieveChannels = retrieveChannels;
     this.adapter = null;
     this.keys = new Set();
     this.codec = new Codec();
   }
 
   static async open(
-    retriever: channel.Retriever,
+    retrieveChannels: ChannelRetriever,
     channels: channel.Params,
   ): Promise<ReadAdapter> {
-    const adapter = new ReadAdapter(retriever);
+    const adapter = new ReadAdapter(retrieveChannels);
     await adapter.update(channels);
     return adapter;
   }
 
   async update(channels: channel.Params): Promise<boolean> {
-    const { variant, normalized } = channel.analyzeParams(channels);
-    const fetched = await this.retriever.retrieve(normalized);
+    const { variant, normalized } = analyzeParams(channels);
+    const fetched = await this.retrieveChannels(normalized);
     const newKeys = fetched.map((c) => c.key);
-    if (
-      compare.uniqueUnorderedPrimitiveArrays(Array.from(this.keys), newKeys) ===
-      compare.EQUAL
-    )
+    const newKeySet = new Set(newKeys);
+    if (newKeySet.size === this.keys.size && newKeySet.isSubsetOf(this.keys))
       return false;
     this.codec.update(
       newKeys,
@@ -51,7 +69,7 @@ export class ReadAdapter {
     );
     if (variant === "keys") {
       this.adapter = null;
-      this.keys = new Set(normalized as channel.Key[]);
+      this.keys = new Set(normalized);
       return true;
     }
     const a = new Map<channel.Key, string>();
@@ -74,10 +92,10 @@ export class ReadAdapter {
       if (shouldFilter) return frm.filter((k) => this.keys.has(k as channel.Key));
       return frm;
     }
-    const a = this.adapter;
+    const { adapter } = this;
     return frm.mapFilter((col, arr) => {
       if (typeof col === "number") {
-        const name = a.get(col);
+        const name = adapter.get(col);
         if (name == null) return [col, arr, false];
         return [name, arr, true];
       }
@@ -87,29 +105,31 @@ export class ReadAdapter {
 }
 
 export class WriteAdapter {
-  private adapter: Map<string, channel.Key> | null;
-  retriever: channel.Retriever;
+  private byName: Map<channel.Name, channel.Payload> | null;
+  private byKey: Map<channel.Key, channel.Payload>;
+  private readonly retrieveChannels: ChannelRetriever;
   keys: channel.Key[];
   codec: Codec;
 
-  private constructor(retriever: channel.Retriever) {
-    this.retriever = retriever;
-    this.adapter = null;
+  private constructor(retrieveChannels: ChannelRetriever) {
+    this.retrieveChannels = retrieveChannels;
+    this.byName = null;
+    this.byKey = new Map();
     this.keys = [];
     this.codec = new Codec();
   }
 
   static async open(
-    retriever: channel.Retriever,
+    retrieveChannels: ChannelRetriever,
     channels: channel.Params,
   ): Promise<WriteAdapter> {
-    const adapter = new WriteAdapter(retriever);
+    const adapter = new WriteAdapter(retrieveChannels);
     await adapter.update(channels);
     return adapter;
   }
 
   async adaptParams(data: channel.Params): Promise<channel.Key[]> {
-    const arrParams = channel.paramsZ.parse(data);
+    const arrParams = paramsZ.parse(data);
     const keys = await Promise.all(
       arrParams.map(async (p) => await this.adaptToKey(p)),
     );
@@ -117,15 +137,14 @@ export class WriteAdapter {
   }
 
   async update(channels: channel.Params): Promise<boolean> {
-    const results = await channel.retrieveRequired(this.retriever, channels);
+    const results = await retrieveRequired(this.retrieveChannels, channels);
     const newKeys = results.map((c) => c.key);
     const previousKeySet = new Set(this.keys);
     const newKeySet = new Set(newKeys);
-    const hasAddedKeys = !newKeySet.isSubsetOf(previousKeySet);
-    const hasRemovedKeys = !previousKeySet.isSubsetOf(newKeySet);
-    const hasChanged = hasAddedKeys || hasRemovedKeys;
-    if (!hasChanged) return false;
-    this.adapter = new Map<string, channel.Key>(results.map((c) => [c.name, c.key]));
+    if (newKeySet.size === previousKeySet.size && newKeySet.isSubsetOf(previousKeySet))
+      return false;
+    this.byName = new Map(results.map((c) => [c.name, c]));
+    this.byKey = new Map(results.map((c) => [c.key, c]));
     this.keys = newKeys;
     this.codec.update(
       this.keys,
@@ -137,7 +156,13 @@ export class WriteAdapter {
   private async fetchChannel(
     ch: channel.Key | channel.Name | channel.Payload,
   ): Promise<channel.Payload> {
-    const res = await this.retriever.retrieve(ch);
+    // The channel set is fixed between updates, so cached payloads cannot go stale.
+    let cached: channel.Payload | undefined;
+    if (typeof ch === "number") cached = this.byKey.get(ch);
+    else if (typeof ch === "string") cached = this.byName?.get(ch);
+    else cached = this.byKey.get(ch.key);
+    if (cached != null) return cached;
+    const res = await this.retrieveChannels(ch);
     if (res.length === 0) throw new Error(`Channel ${JSON.stringify(ch)} not found`);
     return res[0];
   }
@@ -154,9 +179,7 @@ export class WriteAdapter {
 
   async adapt(
     columnsOrData:
-      | channel.Params
-      | Record<channel.Key | channel.Name, CrudeSeries>
-      | CrudeFrame,
+      channel.Params | Record<channel.Key | channel.Name, CrudeSeries> | CrudeFrame,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<Frame> {
     if (typeof columnsOrData === "string" || typeof columnsOrData === "number") {
@@ -205,9 +228,9 @@ export class WriteAdapter {
 
     if (columnsOrData instanceof Frame || columnsOrData instanceof Map) {
       const fr = new Frame(columnsOrData);
-      if (this.adapter == null) return fr;
+      if (this.byName == null) return fr;
       const cols = fr.columns.map((col_) => {
-        const col = typeof col_ === "string" ? this.adapter?.get(col_) : col_;
+        const col = typeof col_ === "string" ? this.byName?.get(col_)?.key : col_;
         if (col == null)
           throw new ValidationError(`
           Channel ${col_} was not provided in the list of channels when opening the writer

package/src/framer/benchutil.ts

@@ -0,0 +1,67 @@
+// 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 { DataType, TimeRange } from "@synnaxlabs/x";
+
+import { type channel } from "@/channel";
+import { Codec } from "@/framer/codec";
+import { Frame, type Payload } from "@/framer/frame";
+
+export const createKeys = (n: number): channel.Key[] =>
+  Array.from({ length: n }, (_, i) => i + 1);
+
+interface PayloadOptions {
+  /** Base alignment for every series in the frame. */
+  alignment?: bigint;
+  /** Give every series a distinct time range and alignment, defeating the codec's
+   * equal-props fast paths. */
+  varied?: boolean;
+}
+
+/** Builds a frame payload with one float32 series per key. */
+export const createPayload = (
+  keys: channel.Key[],
+  samplesPerChannel: number,
+  { alignment = 0n, varied = false }: PayloadOptions = {},
+): Payload => {
+  const data = new Float32Array(samplesPerChannel);
+  for (let i = 0; i < data.length; i++) data[i] = i;
+  return {
+    keys: [...keys],
+    series: keys.map((_, i) => ({
+      dataType: DataType.FLOAT32,
+      data: data.buffer.slice(0),
+      alignment: varied ? alignment + BigInt(i) : alignment,
+      timeRange: varied ? new TimeRange(i * 1000, (i + 1) * 1000) : TimeRange.ZERO,
+    })),
+  };
+};
+
+/** Builds a sequence of frames with monotonically increasing alignments, the shape
+ * the streaming run loop ingests in steady state. */
+export const createSequence = (
+  keys: channel.Key[],
+  samplesPerChannel: number,
+  count: number,
+): Frame[] =>
+  Array.from(
+    { length: count },
+    (_, i) =>
+      new Frame(
+        createPayload(keys, samplesPerChannel, {
+          alignment: BigInt(i * samplesPerChannel),
+        }),
+      ),
+  );
+
+export const createCodec = (keys: channel.Key[]): Codec =>
+  new Codec(
+    keys,
+    keys.map(() => DataType.FLOAT32),
+  );

package/src/framer/cache/cache.ts

@@ -0,0 +1,115 @@
+// 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 { TimeSpan } from "@synnaxlabs/x";
+
+import { type channel } from "@/channel";
+import { UnexpectedError } from "@/errors";
+import { type DynamicProps } from "@/framer/cache/dynamic";
+import {
+  DEFAULT_STATIC_PROPS,
+  type StaticProps,
+  zeroGCMetrics,
+} from "@/framer/cache/static";
+import { Unary } from "@/framer/cache/unary";
+
+const DEFAULT_DYNAMIC_BUFFER_SIZE: TimeSpan = TimeSpan.seconds(60);
+
+/** Props for instantiating a {@link Cache} */
+export interface CacheProps
+  extends StaticProps, Partial<Pick<DynamicProps, "dynamicBufferSize">> {
+  /**
+   * Sets the interval at which the cache will garbage collect, removing stale data
+   * that is not in use by the rest of the program.
+   * @default TimeSpan.seconds(30)
+   */
+  gcInterval?: TimeSpan;
+}
+
+/**
+ * Maintains an in-memory cache of channel data. Entries are created on demand and
+ * carry no channel metadata; buffer types derive from the data written to them.
+ */
+export class Cache {
+  private readonly props: Required<CacheProps>;
+  private readonly cache = new Map<channel.Key, Unary>();
+  private readonly gcInterval: ReturnType<typeof setInterval>;
+  private closed = false;
+
+  constructor(props: CacheProps = {}) {
+    const {
+      dynamicBufferSize = DEFAULT_DYNAMIC_BUFFER_SIZE,
+      gcInterval = TimeSpan.seconds(30),
+      instrumentation = DEFAULT_STATIC_PROPS.instrumentation,
+      transform = DEFAULT_STATIC_PROPS.transform,
+      staleEntryThreshold = DEFAULT_STATIC_PROPS.staleEntryThreshold,
+    } = props;
+    this.props = {
+      dynamicBufferSize,
+      gcInterval,
+      instrumentation,
+      transform,
+      staleEntryThreshold,
+    };
+    this.gcInterval = setInterval(() => this.gc(), gcInterval.milliseconds);
+  }
+
+  /**
+   * Returns the cache entry for the given channel, creating an empty one if it does
+   * not exist.
+   * @throws {UnexpectedError} if the cache has been closed.
+   */
+  get(key: channel.Key): Unary {
+    if (this.closed)
+      throw new UnexpectedError(`get(${key}) called on a closed telemetry cache`);
+    const existing = this.cache.get(key);
+    if (existing != null) return existing;
+    const { dynamicBufferSize, transform, staleEntryThreshold } = this.props;
+    const unary = new Unary({
+      dynamicBufferSize,
+      transform,
+      staleEntryThreshold,
+      instrumentation: this.props.instrumentation.child(`cache-${key}`),
+    });
+    this.cache.set(key, unary);
+    return unary;
+  }
+
+  private gc(): void {
+    const {
+      instrumentation: { L },
+    } = this.props;
+    L.info("starting garbage collection");
+    const total = zeroGCMetrics();
+    this.cache.forEach((c) => {
+      const res = c.gc();
+      total.purgedSeries += res.purgedSeries;
+      total.purgedBytes = total.purgedBytes.add(res.purgedBytes);
+    });
+    L.info(
+      "garbage collection complete",
+      {
+        purgedSeries: total.purgedSeries,
+        purgedBytes: total.purgedBytes.toString(),
+      },
+      true,
+    );
+  }
+
+  /**
+   * Closes the cache, clearing all entries and stopping garbage collection. All
+   * methods throw after close.
+   */
+  close(): void {
+    this.closed = true;
+    clearInterval(this.gcInterval);
+    this.cache.forEach((c) => c.close());
+    this.cache.clear();
+  }
+}