@synnaxlabs/client 0.37.0 → 0.38.0

package/examples/node/package.json

@@ -11,6 +11,6 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@synnaxlabs/client": "^0.31.0"
+    "@synnaxlabs/client": "^0.38.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/client",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "The Synnax Client Library",
   "keywords": [
     "synnax",
@@ -25,21 +25,20 @@
   },
   "dependencies": {
     "async-mutex": "^0.5.0",
-    "uuid": "^11.0.3",
+    "uuid": "^11.0.5",
     "zod": "^3.24.1",
-    "@synnaxlabs/x": "0.37.0",
-    "@synnaxlabs/freighter": "0.37.0"
+    "@synnaxlabs/freighter": "0.38.0",
+    "@synnaxlabs/x": "0.38.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.2",
+    "@types/node": "^22.10.6",
     "@types/uuid": "^10.0.0",
-    "@vitest/coverage-v8": "^2.1.8",
-    "eslint": "^9.17.0",
-    "typescript": "^5.7.2",
-    "vite": "^6.0.3",
+    "eslint": "^9.18.0",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.7",
     "vitest": "^2.1.8",
-    "@synnaxlabs/tsconfig": "0.0.2",
     "@synnaxlabs/vite-plugin": "0.0.1",
+    "@synnaxlabs/tsconfig": "0.0.2",
     "eslint-config-synnaxlabs": "0.0.1"
   },
   "type": "module",
@@ -49,10 +48,7 @@
     "build": "tsc --noEmit && vite build",
     "watch": "tsc --noEmit && vite build --watch",
     "test": "vitest",
-    "cov": "vitest --coverage",
     "lint": "eslint --cache",
-    "fix": "eslint --cache --fix",
-    "genApi": "tsc --noEmit && vite build && npx api-extractor run --local",
-    "checkApi": "tsc --noEmit && vite build && npx api-extractor run"
+    "fix": "eslint --cache --fix"
   }
 }

package/src/access/policy/policy.spec.ts

@@ -298,10 +298,7 @@ describe("privilege", async () => {
       password: "pwd1",
     });
     await expect(
-      client2.user.create({
-        username: id.id(),
-        password: id.id(),
-      }),
+      client2.user.create({ username: id.id(), password: id.id() }),
     ).rejects.toThrow(AuthError);
 
     const policy = await client.access.policy.create({

package/src/channel/batchRetriever.spec.ts

@@ -56,6 +56,8 @@ describe("channelRetriever", () => {
         leaseholder: 1,
         index: 0,
         virtual: false,
+        expression: "",
+        requires: [],
       }));
     });
     const retriever = new DebouncedBatchRetriever(base, 10);
@@ -83,6 +85,8 @@ describe("channelRetriever", () => {
         leaseholder: 1,
         index: 0,
         virtual: false,
+        expression: "",
+        requires: [],
       }));
     });
     const retriever = new DebouncedBatchRetriever(base, 10);

package/src/channel/channel.spec.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { DataType, Rate, TimeStamp } from "@synnaxlabs/x/telem";
-import { describe, expect, it, test } from "vitest";
+import { beforeAll, describe, expect, it, test } from "vitest";
 
 import { Channel } from "@/channel/client";
 import { NotFoundError, QueryError } from "@/errors";
@@ -31,6 +31,27 @@ describe("Channel", () => {
       expect(channel.dataType).toEqual(DataType.FLOAT32);
     });
 
+    test("create calculated", async () => {
+      let chOne = new Channel({
+        name: "test",
+        isIndex: true,
+        dataType: DataType.TIMESTAMP,
+      });
+      chOne = await client.channels.create(chOne);
+      let calculatedCH = new Channel({
+        name: "test2",
+        virtual: true,
+        dataType: DataType.FLOAT32,
+        expression: "test * 2",
+        requires: [chOne.key],
+      });
+      calculatedCH = await client.channels.create(calculatedCH);
+      expect(calculatedCH.key).not.toEqual(0);
+      expect(calculatedCH.virtual).toEqual(true);
+      expect(calculatedCH.expression).toEqual("test * 2");
+      expect(calculatedCH.requires).toEqual([chOne.key]);
+    });
+
     test("create index and indexed pair", async () => {
       const one = await client.channels.create({
         name: "Time",
@@ -48,18 +69,8 @@ describe("Channel", () => {
 
     test("create many", async () => {
       const channels = await client.channels.create([
-        {
-          name: "test1",
-          leaseholder: 1,
-          rate: Rate.hz(1),
-          dataType: DataType.FLOAT32,
-        },
-        {
-          name: "test2",
-          leaseholder: 1,
-          rate: Rate.hz(1),
-          dataType: DataType.FLOAT32,
-        },
+        { name: "test1", leaseholder: 1, rate: Rate.hz(1), dataType: DataType.FLOAT32 },
+        { name: "test2", leaseholder: 1, rate: Rate.hz(1), dataType: DataType.FLOAT32 },
       ]);
       expect(channels.length).toEqual(2);
       expect(channels[0].name).toEqual("test1");
@@ -116,12 +127,7 @@ describe("Channel", () => {
           dataType: DataType.FLOAT32,
         });
         const channelTwo = await client.channels.create(
-          {
-            name,
-            leaseholder: 1,
-            rate: Rate.hz(1),
-            dataType: DataType.FLOAT32,
-          },
+          { name, leaseholder: 1, rate: Rate.hz(1), dataType: DataType.FLOAT32 },
           { retrieveIfNameExists: true },
         );
         expect(channelTwo.key).toEqual(channel.key);
@@ -155,12 +161,7 @@ describe("Channel", () => {
         });
         const channelTwo = await client.channels.create(
           [
-            {
-              name,
-              leaseholder: 1,
-              rate: Rate.hz(1),
-              dataType: DataType.FLOAT32,
-            },
+            { name, leaseholder: 1, rate: Rate.hz(1), dataType: DataType.FLOAT32 },
             {
               name: `${name}-2`,
               leaseholder: 1,
@@ -253,18 +254,8 @@ describe("Channel", () => {
     });
     test("multiple rename", async () => {
       const channels = await client.channels.create([
-        {
-          name: "test1",
-          leaseholder: 1,
-          rate: Rate.hz(1),
-          dataType: DataType.FLOAT32,
-        },
-        {
-          name: "test2",
-          leaseholder: 1,
-          rate: Rate.hz(1),
-          dataType: DataType.FLOAT32,
-        },
+        { name: "test1", leaseholder: 1, rate: Rate.hz(1), dataType: DataType.FLOAT32 },
+        { name: "test2", leaseholder: 1, rate: Rate.hz(1), dataType: DataType.FLOAT32 },
       ]);
       // Retrieve channels here to ensure we check for cache invalidation
       const initial = await client.channels.retrieve(channels.map((c) => c.key));
@@ -279,4 +270,84 @@ describe("Channel", () => {
       expect(renamed[1].name).toEqual("test4");
     });
   });
+
+  describe("update", () => {
+    let idxCH: Channel;
+    beforeAll(async () => {
+      idxCH = await client.channels.create({
+        name: "idx",
+        dataType: DataType.TIMESTAMP,
+        isIndex: true,
+      });
+    });
+    test("update virtual channel expression", async () => {
+      const channel = await client.channels.create({
+        name: "virtual-calc",
+        dataType: DataType.FLOAT32,
+        virtual: true,
+        expression: "return 1",
+        requires: [idxCH.key],
+      });
+
+      const updated = await client.channels.create({
+        key: channel.key,
+        name: channel.name,
+        dataType: channel.dataType,
+        virtual: true,
+        expression: "return 2",
+        requires: [idxCH.key],
+      });
+
+      const channelsWithName = await client.channels.retrieve(["virtual-calc"]);
+      expect(channelsWithName.length).toEqual(1);
+
+      expect(updated.expression).toEqual("return 2");
+
+      const retrieved = await client.channels.retrieve(channel.key);
+      expect(retrieved.expression).toEqual("return 2");
+    });
+
+    test("update calculated channel name", async () => {
+      const channel = await client.channels.create({
+        name: "virtual-calc",
+        dataType: DataType.FLOAT32,
+        virtual: true,
+        expression: "return 1",
+        requires: [idxCH.key],
+      });
+
+      const updated = await client.channels.create({
+        key: channel.key,
+        name: "new-name",
+        dataType: channel.dataType,
+        virtual: true,
+        expression: channel.expression,
+        requires: [idxCH.key],
+      });
+      expect(updated.name).toEqual("new-name");
+
+      const retrieved = await client.channels.retrieve(channel.key);
+      expect(retrieved.name).toEqual("new-name");
+    });
+
+    test("should not allow updates to non-virtual channels", async () => {
+      const channel = await client.channels.create({
+        name: "regular-channel",
+        leaseholder: 1,
+        rate: Rate.hz(1),
+        dataType: DataType.FLOAT32,
+      });
+
+      const _updated = await client.channels.create({
+        key: channel.key,
+        name: "new-name",
+        leaseholder: channel.leaseholder,
+        rate: channel.rate,
+        dataType: channel.dataType,
+      });
+
+      const retrieved = await client.channels.retrieve(channel.key);
+      expect(retrieved.name).toEqual("regular-channel");
+    });
+  });
 });

package/src/channel/client.ts

@@ -25,6 +25,7 @@ import {
   type Key,
   type KeyOrName,
   type NewPayload,
+  ontologyID as payloadOntologyID,
   type Params,
   type Payload,
   payload,
@@ -40,7 +41,7 @@ import {
 import { type Writer } from "@/channel/writer";
 import { ValidationError } from "@/errors";
 import { type framer } from "@/framer";
-import { ontology } from "@/ontology";
+import { type ontology } from "@/ontology";
 import { group } from "@/ontology/group";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
@@ -107,6 +108,15 @@ export class Channel {
    * database, but can still be used for streaming purposes.
    */
   readonly virtual: boolean;
+  /**
+   * Only used for calculated channels. Specifies the python expression to evaluate
+   * the calculated value
+   */
+  readonly expression: string;
+  /**
+   * Only used for calculated channels. Specifies the channels required for calculation
+   */
+  readonly requires: Key[];
 
   constructor({
     dataType,
@@ -120,6 +130,8 @@ export class Channel {
     virtual = false,
     frameClient,
     alias,
+    expression = "",
+    requires = [],
   }: NewPayload & {
     frameClient?: framer.Client;
     density?: CrudeDensity;
@@ -134,6 +146,8 @@ export class Channel {
     this.internal = internal;
     this.alias = alias;
     this.virtual = virtual;
+    this.expression = expression;
+    this.requires = requires ?? [];
     this._frameClient = frameClient ?? null;
   }
 
@@ -158,14 +172,21 @@ export class Channel {
       index: this.index,
       isIndex: this.isIndex,
       internal: this.internal,
+      virtual: this.virtual,
+      expression: this.expression,
+      requires: this.requires,
     });
   }
 
+  get isCalculated(): boolean {
+    return isCalculated(this.payload);
+  }
+
   /***
    * @returns the ontology ID of the channel
    */
   get ontologyID(): ontology.ID {
-    return new ontology.ID({ type: "channel", key: this.key.toString() });
+    return payloadOntologyID(this.key);
   }
 
   /**
@@ -421,3 +442,25 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
     return new group.Group(res.group.name, res.group.key);
   }
 }
+
+export const isCalculated = ({ virtual, expression }: Payload): boolean =>
+  virtual && expression !== "";
+
+export const resolveCalculatedIndex = async (
+  retrieve: (key: Key) => Promise<Payload>,
+  channel: Payload,
+): Promise<Key | null> => {
+  if (!isCalculated(channel)) return channel.index;
+  for (const required of channel.requires) {
+    const requiredChannel = await retrieve(required);
+    if (!requiredChannel.virtual) return requiredChannel.index;
+  }
+  for (const required of channel.requires) {
+    const requiredChannel = await retrieve(required);
+    if (isCalculated(requiredChannel)) {
+      const index = await resolveCalculatedIndex(retrieve, requiredChannel);
+      if (index != null) return index;
+    }
+  }
+  return null;
+};

package/src/channel/payload.ts

@@ -11,6 +11,7 @@ import { DataType, Rate } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
+import { nullableArrayZ } from "@/util/zod";
 
 export const keyZ = z.number();
 export type Key = number;
@@ -32,6 +33,8 @@ export const payload = z.object({
   internal: z.boolean(),
   virtual: z.boolean(),
   alias: z.string().optional(),
+  expression: z.string().default(""),
+  requires: nullableArrayZ(keyZ),
 });
 
 export type Payload = z.infer<typeof payload>;
@@ -44,6 +47,8 @@ export const newPayload = payload.extend({
   isIndex: z.boolean().optional(),
   internal: z.boolean().optional().default(false),
   virtual: z.boolean().optional().default(false),
+  expression: z.string().optional().default(""),
+  requires: nullableArrayZ(keyZ).optional().default([]),
 });
 
 export type NewPayload = z.input<typeof newPayload>;

package/src/framer/frame.ts

@@ -7,6 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+import { toArray, unique } from "@synnaxlabs/x";
 import {
   MultiSeries,
   Series,
@@ -17,8 +18,6 @@ import {
   TimeRange,
   TimeStamp,
 } from "@synnaxlabs/x/telem";
-import { toArray } from "@synnaxlabs/x/toArray";
-import { unique } from "@synnaxlabs/x/unique";
 import { z } from "zod";
 
 import {
@@ -177,7 +176,7 @@ export class Frame {
    * error otherwise.
    */
   get uniqueKeys(): Keys {
-    return unique(this.keys);
+    return unique.unique(this.keys);
   }
 
   /**
@@ -194,7 +193,7 @@ export class Frame {
    * otherwise.
    */
   get uniqueNames(): Names {
-    return unique(this.names);
+    return unique.unique(this.names);
   }
 
   /**

package/src/framer/streamer.spec.ts

@@ -108,3 +108,181 @@ describe("Streamer", () => {
     expect(Array.from(d.get(ch.key))).toEqual([1]);
   });
 });
+
+describe("Streamer - Calculated Channels", () => {
+  test("basic calculated channel streaming", async () => {
+    // Create a timestamp index channel
+    const timeChannel = await client.channels.create({
+      name: "calc_test_time",
+      isIndex: true,
+      dataType: DataType.TIMESTAMP,
+    });
+
+    // Create source channels with the timestamp index
+    const [channelA, channelB] = await client.channels.create([
+      {
+        name: "test_a",
+        dataType: DataType.FLOAT64,
+        index: timeChannel.key,
+      },
+      {
+        name: "test_b",
+        dataType: DataType.FLOAT64,
+        index: timeChannel.key,
+      },
+    ]);
+
+    // Create calculated channel that adds the two source channels
+    const calcChannel = await client.channels.create({
+      name: "test_calc",
+      dataType: DataType.FLOAT64,
+      index: timeChannel.key,
+      virtual: true,
+      expression: "return test_a + test_b",
+      requires: [channelA.key, channelB.key],
+    });
+
+    // Set up streamer to listen for calculated results
+    const streamer = await client.openStreamer(calcChannel.key);
+
+    // Give streamer time to initialize
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Write test data
+    const startTime = TimeStamp.now();
+    const writer = await client.openWriter({
+      start: startTime,
+      channels: [timeChannel.key, channelA.key, channelB.key],
+    });
+
+    try {
+      // Write test values - each source gets 2.5 so sum should be 5.0
+      await writer.write({
+        [timeChannel.key]: [startTime],
+        [channelA.key]: new Float64Array([2.5]),
+        [channelB.key]: new Float64Array([2.5]),
+      });
+
+      // Read from streamer
+      const frame = await streamer.read();
+
+      // Verify calculated results
+      const calcData = Array.from(frame.get(calcChannel.key));
+      expect(calcData).toEqual([5.0]);
+    } finally {
+      await writer.close();
+      streamer.close();
+    }
+  });
+  test("calculated channel with constant", async () => {
+    // Create an index channel for timestamps
+    const timeChannel = await client.channels.create({
+      name: "calc_const_time",
+      isIndex: true,
+      dataType: DataType.TIMESTAMP,
+    });
+
+    // Create base channel with index
+    const baseChannel = await client.channels.create({
+      name: "base_channel",
+      dataType: DataType.FLOAT64,
+      index: timeChannel.key,
+    });
+
+    // Create calculated channel that adds 5
+    const calcChannel = await client.channels.create({
+      name: "calc_const_channel",
+      dataType: DataType.FLOAT64,
+      index: timeChannel.key,
+      virtual: true,
+      expression: `return ${baseChannel.name} + 5`,
+      requires: [baseChannel.key],
+    });
+
+    const streamer = await client.openStreamer(calcChannel.key);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const startTime = TimeStamp.now();
+    const writer = await client.openWriter({
+      start: startTime,
+      channels: [timeChannel.key, baseChannel.key],
+    });
+
+    try {
+      const timestamps = [
+        startTime,
+        new TimeStamp(startTime.valueOf() + BigInt(1000000000)),
+        new TimeStamp(startTime.valueOf() + BigInt(2000000000)),
+      ];
+
+      await writer.write({
+        [timeChannel.key]: timestamps,
+        [baseChannel.key]: new Float64Array([1, 2, 3]),
+      });
+
+      const frame = await streamer.read();
+      const calcData = Array.from(frame.get(calcChannel.key));
+      expect(calcData).toEqual([6, 7, 8]); // Original values + 5
+    } finally {
+      await writer.close();
+      streamer.close();
+    }
+  });
+
+  test("calculated channel with multiple operations", async () => {
+    // Create timestamp channel
+    const timeChannel = await client.channels.create({
+      name: "calc_multi_time",
+      isIndex: true,
+      dataType: DataType.TIMESTAMP,
+    });
+
+    // Create source channels
+    const [channelA, channelB] = await client.channels.create([
+      {
+        name: "multi_test_a",
+        dataType: DataType.FLOAT64,
+        index: timeChannel.key,
+      },
+      {
+        name: "multi_test_b",
+        dataType: DataType.FLOAT64,
+        index: timeChannel.key,
+      },
+    ]);
+
+    // Create calculated channel with multiple operations
+    const calcChannel = await client.channels.create({
+      name: "multi_calc",
+      dataType: DataType.FLOAT64,
+      index: timeChannel.key,
+      virtual: true,
+      expression: "return (multi_test_a * 2) + (multi_test_b / 2)",
+      requires: [channelA.key, channelB.key],
+    });
+
+    const streamer = await client.openStreamer(calcChannel.key);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const startTime = TimeStamp.now();
+    const writer = await client.openWriter({
+      start: startTime,
+      channels: [timeChannel.key, channelA.key, channelB.key],
+    });
+
+    try {
+      await writer.write({
+        [timeChannel.key]: [startTime],
+        [channelA.key]: new Float64Array([2.0]), // Will be multiplied by 2 = 4.0
+        [channelB.key]: new Float64Array([4.0]), // Will be divided by 2 = 2.0
+      });
+
+      const frame = await streamer.read();
+      const calcData = Array.from(frame.get(calcChannel.key));
+      expect(calcData).toEqual([6.0]); // (2.0 * 2) + (4.0 / 2) = 4.0 + 2.0 = 6.0
+    } finally {
+      await writer.close();
+      streamer.close();
+    }
+  });
+});

package/src/hardware/task/client.ts

@@ -24,6 +24,7 @@ import {
   commandZ,
   type NewTask,
   newTaskZ,
+  ontologyID as payloadOntologyID,
   type Payload,
   type State,
   type StateObservable,
@@ -32,7 +33,7 @@ import {
   taskKeyZ,
   taskZ,
 } from "@/hardware/task/payload";
-import { ontology } from "@/ontology";
+import { type ontology } from "@/ontology";
 import { type ranger } from "@/ranger";
 import { signals } from "@/signals";
 import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
@@ -95,7 +96,7 @@ export class Task<
   }
 
   get ontologyID(): ontology.ID {
-    return new ontology.ID({ type: "task", key: this.key });
+    return payloadOntologyID(this.key);
   }
 
   async executeCommand(type: string, args?: UnknownRecord): Promise<string> {

package/src/index.ts

@@ -10,7 +10,7 @@
 export { access } from "@/access";
 export { policy } from "@/access/policy";
 export { channel } from "@/channel";
-export { Channel } from "@/channel/client";
+export { Channel, isCalculated } from "@/channel/client";
 export { default as Synnax, type SynnaxProps, synnaxPropsZ } from "@/client";
 export * from "@/connection";
 export { control } from "@/control";

package/src/label/client.ts

@@ -12,7 +12,7 @@ import { observe } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 
 import { type framer } from "@/framer";
-import { type Key, type Label, labelZ } from "@/label/payload";
+import { type Key, type Label, labelZ, ontologyID } from "@/label/payload";
 import { Retriever } from "@/label/retriever";
 import { type NewLabelPayload, type SetOptions, Writer } from "@/label/writer";
 import { ontology } from "@/ontology";
@@ -105,7 +105,7 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
   ): Promise<observe.ObservableAsyncCloseable<Label[]>> {
     const wrapper = new observe.Observer<Label[]>();
     const initial = (await this.retrieveFor(id)).map((l) => ({
-      id: new ontology.ID({ key: l.key, type: "label" }),
+      id: ontologyID(l.key),
       key: l.key,
       name: l.name,
       data: l,