@synnaxlabs/client 0.26.0 → 0.26.7

package/examples/node/package.json

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

package/examples/node/seriesAndFrames.js

@@ -21,13 +21,13 @@ series = new Series({ data: [1, 2, 3, 4, 5], dataType: "float32" });
 // automatically be of type string.
 series = new Series(["apple", "banana", "cherry"]);
 
-// Construct a series from a Float32Array. This is the most efficient way to
-// construct a series from a large amount of data.
+// Construct a series from a Float32Array. This is the most efficient way to construct a
+// series from a large amount of data.
 series = new Series(new Float32Array([1, 2, 3, 4, 5]));
 
-// Construct a series from a JSON object. This is useful when you have a series
-// that has been serialized to JSON.
-series = new Series([{ red: "cherry" }, { yellow: "banana" }, {orange: "orange" }]);
+// Construct a series from a JSON object. This is useful when you have a series that has
+// been serialized to JSON.
+series = new Series([{ red: "cherry" }, { yellow: "banana" }, { orange: "orange" }]);
 
 series = new Series([1, "a", 3, "b", 5]);
 
@@ -60,16 +60,16 @@ series = new Series([{ red: "cherry", yellow: "banana", orange: "orange" }]);
 jsArray = [...series];
 console.log(jsArray); // [ { red: 'cherry', yellow: 'banana', orange: 'orange' } ]
 
-import { TimeRange, TimeStamp, TimeSpan } from "@synnaxlabs/client";
+import { TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/client";
 
 const start = TimeStamp.now();
 
 const tr = new TimeRange(start, start.add(TimeSpan.seconds(5)));
 
 series = new Series({
-  data: [1, 2, 3, 4, 5],
-  dataType: "float64",
-  timeRange: new TimeRange(start, start.add(TimeSpan.seconds(6)))
+    data: [1, 2, 3, 4, 5],
+    dataType: "float64",
+    timeRange: tr,
 });
 
 series = new Series([1, 2, 3, 4, 5]);
@@ -93,51 +93,52 @@ import { Frame } from "@synnaxlabs/client";
 
 // Construct a frame for the given channel names.
 let frame = new Frame({
-  "channel1": new Series([1, 2, 3, 4, 5]),
-  "channel2": new Series([5, 4, 3, 2, 1]),
-  "channel3": new Series([1, 1, 1, 1, 1]),
+    channel1: new Series([1, 2, 3, 4, 5]),
+    channel2: new Series([5, 4, 3, 2, 1]),
+    channel3: new Series([1, 1, 1, 1, 1]),
 });
 
 // Construct a frame for the given channel keys
 frame = new Frame({
-  1: new Series([1, 2, 3, 4, 5]),
-  2: new Series([5, 4, 3, 2, 1]),
-  // Notice that series do not need to be the same length.
-  3: new Series([1, 1, 1]),
+    1: new Series([1, 2, 3, 4, 5]),
+    2: new Series([5, 4, 3, 2, 1]),
+    // Notice that series do not need to be the same length.
+    3: new Series([1, 1, 1]),
 });
 
 // Construct a frame from a map
-frame = new Frame(new Map([
-  ["channel1", new Series([1, 2, 3, 4, 5])],
-  ["channel2", new Series([5, 4, 3, 2, 1])],
-  ["channel3", new Series([1, 1, 1, 1, 1])],
-]));
+frame = new Frame(
+    new Map([
+        ["channel1", new Series([1, 2, 3, 4, 5])],
+        ["channel2", new Series([5, 4, 3, 2, 1])],
+        ["channel3", new Series([1, 1, 1, 1, 1])],
+    ]),
+);
 
 // Or from an array of keys and series
-frame = new Frame(["channel1", "channel2", "channel3"], [
-  new Series([1, 2, 3, 4, 5]),
-  new Series([5, 4, 3, 2, 1]),
-  new Series([1, 1, 1, 1, 1]),
-]);
+frame = new Frame(
+    ["channel1", "channel2", "channel3"],
+    [
+        new Series([1, 2, 3, 4, 5]),
+        new Series([5, 4, 3, 2, 1]),
+        new Series([1, 1, 1, 1, 1]),
+    ],
+);
 
 // Or construct a frame with multiple series for a single channel
 frame = new Frame({
-  "channel1": [
-    new Series([1, 2, 3, 4, 5]),
-    new Series([5, 4, 3, 2, 1]),
-    new Series([1, 1, 1, 1, 1]),
-  ],
-  "channel2": [
-    new Series([1, 2, 3, 4, 5]),
-  ],
+    channel1: [
+        new Series([1, 2, 3, 4, 5]),
+        new Series([5, 4, 3, 2, 1]),
+        new Series([1, 1, 1, 1, 1]),
+    ],
+    channel2: [new Series([1, 2, 3, 4, 5])],
 });
 
-import { MultiSeries } from "@synnaxlabs/client";
-
 frame = new Frame({
-  "channel1": [new Series([1, 2]), new Series([3, 4, 5])],
-  "channel2": new Series([5, 4, 3, 2, 1]),
-  "channel3": new Series([1, 1, 1, 1, 1]),
+    channel1: [new Series([1, 2]), new Series([3, 4, 5])],
+    channel2: new Series([5, 4, 3, 2, 1]),
+    channel3: new Series([1, 1, 1, 1, 1]),
 });
 
 const multiSeries = frame.get("channel1");
@@ -152,21 +153,21 @@ jsArray = [...multiSeries];
 console.log(jsArray); // [ 1, 2, 3, 4, 5 ]
 
 frame = new Frame({
-  "channel1": new Series([1, 2, 3, 4, 5]),
-  "channel2": new Series([5, 4, 3, 2, 1]),
-  "channel3": new Series([1, 1]),
+    channel1: new Series([1, 2, 3, 4, 5]),
+    channel2: new Series([5, 4, 3, 2, 1]),
+    channel3: new Series([1, 1]),
 });
 
 let obj = frame.at(3);
 console.log(obj); // { channel1: 1, channel2: 5, channel3: undefined }
 
 frame = new Frame({
-  "channel1": new Series([1, 2, 3, 4, 5]),
-  "channel2": new Series([5, 4, 3, 2, 1]),
-  "channel3": new Series([1, 1]),
+    channel1: new Series([1, 2, 3, 4, 5]),
+    channel2: new Series([5, 4, 3, 2, 1]),
+    channel3: new Series([1, 1]),
 });
 try {
-  obj = frame.at(3, true); // Throws an error
+    obj = frame.at(3, true); // Throws an error
 } catch (e) {
-  console.log(e.message); // no value at index
+    console.log(e.message); // no value at index
 }

package/examples/node/streamWrite.js

@@ -12,7 +12,7 @@
 // applications (such as data acquisition from a sensor) or for very large datasets that
 // cannot be written all at once.
 
-import { Rate, Series, Synnax, TimeStamp, framer } from "@synnaxlabs/client";
+import { Rate, Synnax, TimeStamp } from "@synnaxlabs/client";
 
 // Connect to a locally running, insecure Synnax cluster. If your connection parameters
 // are different, enter them here.
@@ -24,51 +24,58 @@ const client = new Synnax({
 });
 
 // Create an index channel that will be used to store our timestamps.
-const timeChannel = await client.channels.create({
-    name: "stream_write_example_time",
-    isIndex: true,
-    dataType: "timestamp"
-}, { retrieveIfNameExists: true });
+const timeChannel = await client.channels.create(
+    {
+        name: "stream_write_example_time",
+        isIndex: true,
+        dataType: "timestamp",
+    },
+    { retrieveIfNameExists: true },
+);
 
 // Create a data channel that will be used to store our fake sensor data.
-const dataChannel1 = await client.channels.create({
-    name: "stream_write_example_data_1",
-    dataType: "float32",
-    index: timeChannel.key,
-}, { retrieveIfNameExists: true });
-
-const dataChannel2 = await client.channels.create({
-    name: "stream_write_example_data_2",
-    dataType: "int32",
-    index: timeChannel.key,
-}, { retrieveIfNameExists: true });
+const dataChannel1 = await client.channels.create(
+    {
+        name: "stream_write_example_data_1",
+        dataType: "float32",
+        index: timeChannel.key,
+    },
+    { retrieveIfNameExists: true },
+);
 
+const dataChannel2 = await client.channels.create(
+    {
+        name: "stream_write_example_data_2",
+        dataType: "int32",
+        index: timeChannel.key,
+    },
+    { retrieveIfNameExists: true },
+);
 
 // We'll start our write at the current time. This timestamps should be the same as or
 // just before the first timestamp we write.
 const start = TimeStamp.now();
 
-// Set a rough rate of 20 Hz. This won't be exact because we're sleeping for a fixed
+// Set a rough rate of 25 Hz. This won't be exact because we're sleeping for a fixed
 // amount of time, but it's close enough for demonstration purposes.
 const roughRate = Rate.hz(25);
 
-// Make the writer commit every 500 samples. This will make the data available for
-// historical reads every 500 samples.
-const commitInterval = 500;
-
 const writer = await client.openWriter({
     start,
     channels: [timeChannel.key, dataChannel1.key, dataChannel2.key],
+    enableAutoCommit: true,
 });
 
 try {
     let i = 0;
     while (true) {
-        await new Promise(resolve => setTimeout(resolve, roughRate.period.milliseconds));
+        await new Promise((resolve) =>
+            setTimeout(resolve, roughRate.period.milliseconds),
+        );
         i++;
         const timestamp = TimeStamp.now();
-        const data2= i % 2;
         const data1 = Math.sin(i / 10);
+        const data2 = i % 2;
         await writer.write({
             [timeChannel.key]: timestamp,
             [dataChannel1.key]: data1,
@@ -76,16 +83,10 @@ try {
         });
 
         if (i % 60 == 0)
-            console.log(`Writing sample ${i} at ${timestamp.toISOString()}`)
-
-        // Commit the writer. This method will return false if the commit fails i.e.
-        // we've mad an invalid write or someone has already written to this region.
-        if (i % commitInterval == 0 && !await writer.commit()) {
-            console.error("Failed to commit data");
-            break;
-        }
+            console.log(`Writing sample ${i} at ${timestamp.toISOString()}`);
     }
 } finally {
+    // Close the writer and the client when you are done
     await writer.close();
+    client.close();
 }
-

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@synnaxlabs/client",
   "private": false,
-  "version": "0.26.0",
+  "version": "0.26.7",
   "type": "module",
   "description": "The Client Library for Synnax",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/client/ts",
@@ -18,8 +18,8 @@
   "dependencies": {
     "async-mutex": "^0.5.0",
     "zod": "3.23.8",
-    "@synnaxlabs/freighter": "0.26.0",
-    "@synnaxlabs/x": "0.26.0"
+    "@synnaxlabs/freighter": "0.26.7",
+    "@synnaxlabs/x": "0.26.7"
   },
   "devDependencies": {
     "@types/node": "^20.14.9",

package/src/framer/adapter.spec.ts

@@ -156,4 +156,13 @@ describe("WriteFrameAdapter", () => {
     expect(res.get(jsonChannel.key)).toHaveLength(1);
     expect(res.get(jsonChannel.key).at(0)).toEqual({ dog: "blue" });
   });
+
+  it("should correctly adapt generic object keys", async () => {
+    const res = await adapter.adaptObjectKeys({
+      [timeCh.name]: 532,
+      [dataCh.name]: 123,
+    });
+    expect(res).toHaveProperty(timeCh.key.toString());
+    expect(res).toHaveProperty(dataCh.key.toString());
+  });
 });

package/src/framer/adapter.ts

@@ -93,6 +93,12 @@ export class WriteFrameAdapter {
     return adapter;
   }
 
+  async adaptObjectKeys<V>(data: Record<KeyOrName, V>): Promise<Record<Key, V>> {
+    const out: Record<Key, V> = {};
+    for (const [k, v] of Object.entries(data)) out[await this.adaptToKey(k)] = v;
+    return out;
+  }
+
   async update(channels: Params): Promise<void> {
     const results = await retrieveRequired(this.retriever, channels);
     this.adapter = new Map<Name, Key>(results.map((c) => [c.name, c.key]));
@@ -105,6 +111,12 @@ export class WriteFrameAdapter {
     return res[0];
   }
 
+  private async adaptToKey(k: KeyOrName): Promise<Key> {
+    if (typeof k === "number") return k;
+    const res = await this.fetchChannel(k);
+    return res.key;
+  }
+
   async adapt(
     columnsOrData: Params | Record<KeyOrName, CrudeSeries> | CrudeFrame,
     series?: CrudeSeries | CrudeSeries[],

package/src/framer/client.ts

@@ -134,7 +134,7 @@ export class Client {
       const w = await this.openWriter({
         start,
         channels: Object.keys(data_),
-        mode: WriterMode.PersistOnly,
+        mode: WriterMode.Persist,
       });
       try {
         await w.write(data_);
@@ -147,7 +147,7 @@ export class Client {
     const w = await this.openWriter({
       start,
       channels: channels as Params,
-      mode: WriterMode.PersistOnly,
+      mode: WriterMode.Persist,
       errOnUnauthorized: true,
       enableAutoCommit: true,
       autoIndexPersistInterval: TimeSpan.MAX,

package/src/framer/writer.spec.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 { id } from "@synnaxlabs/x";
 import { DataType, Rate, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, expect, test } from "vitest";
 
@@ -20,8 +21,8 @@ const client = newClient();
 
 const newChannel = async (): Promise<channel.Channel> =>
   await client.channels.create({
-    name: "test",
     leaseholder: 1,
+    name: `test-${id.id()}`,
     rate: Rate.hz(1),
     dataType: DataType.FLOAT64,
   });
@@ -53,7 +54,7 @@ describe("Writer", () => {
       const writer = await client.openWriter({
         start: 0,
         channels: ch.key,
-        mode: WriterMode.PersistOnly,
+        mode: WriterMode.Persist,
       });
       try {
         await writer.write(ch.key, randomSeries(10, ch.dataType));
@@ -137,27 +138,111 @@ describe("Writer", () => {
         channels: ch.key,
         authorities: 10,
         enableAutoCommit: true,
-      })
+      });
       const w2 = await client.openWriter({
         start: 0,
         channels: ch.key,
         authorities: 20,
         enableAutoCommit: true,
-      })
+      });
 
-      await w1.write(ch.key, randomSeries(10, ch.dataType))
-      let f = await ch.read(TimeRange.MAX)
-      expect(f.length).toEqual(0)
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+      let f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(0);
 
-      await w1.setAuthority({[ch.key]: 100});
-      await w1.write(ch.key, randomSeries(10, ch.dataType))
+      await w1.setAuthority({ [ch.key]: 100 });
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
 
-      f = await ch.read(TimeRange.MAX)
-      expect(f.length).toEqual(10)
+      f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(10);
 
-      await w1.close()
-      await w2.close()
-    })
+      await w1.close();
+      await w2.close();
+    });
+    test("setAuthority with name keys", async () => {
+      const ch = await newChannel();
+      const w1 = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        authorities: 10,
+        enableAutoCommit: true,
+      });
+      const w2 = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        authorities: 20,
+        enableAutoCommit: true,
+      });
+
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+      let f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(0);
+
+      await w1.setAuthority({ [ch.name]: 100 });
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+
+      f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(10);
+
+      await w1.close();
+      await w2.close();
+    });
+    test("setAuthority with name-value pair", async () => {
+      const ch = await newChannel();
+      const w1 = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        authorities: 10,
+        enableAutoCommit: true,
+      });
+      const w2 = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        authorities: 20,
+        enableAutoCommit: true,
+      });
+
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+      let f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(0);
+
+      await w1.setAuthority(ch.name, 100);
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+
+      f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(10);
+
+      await w1.close();
+      await w2.close();
+    });
+    test("setAuthority on all channels", async () => {
+      const ch = await newChannel();
+      const w1 = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        authorities: 10,
+        enableAutoCommit: true,
+      });
+      const w2 = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        authorities: 20,
+        enableAutoCommit: true,
+      });
+
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+      let f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(0);
+
+      await w1.setAuthority(ch.name, 255);
+      await w1.write(ch.key, randomSeries(10, ch.dataType));
+
+      f = await ch.read(TimeRange.MAX);
+      expect(f.length).toEqual(10);
+
+      await w1.close();
+      await w2.close();
+    });
   });
   describe("Client", () => {
     test("Client - basic write", async () => {

package/src/framer/writer.ts

@@ -7,8 +7,12 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import type { Stream, StreamClient } from "@synnaxlabs/freighter";
-import { decodeError, errorZ } from "@synnaxlabs/freighter";
+import {
+  decodeError,
+  errorZ,
+  type Stream,
+  type StreamClient,
+} from "@synnaxlabs/freighter";
 import { control } from "@synnaxlabs/x";
 import {
   type CrudeSeries,
@@ -19,12 +23,7 @@ import {
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
-import {
-  type Key,
-  type KeyOrName,
-  type KeysOrNames,
-  type Params,
-} from "@/channel/payload";
+import { type KeyOrName, type KeysOrNames, type Params } from "@/channel/payload";
 import { type Retriever } from "@/channel/retriever";
 import { WriteFrameAdapter } from "@/framer/adapter";
 import { type CrudeFrame, frameZ } from "@/framer/frame";
@@ -40,10 +39,25 @@ enum Command {
 
 export enum WriterMode {
   PersistStream = 1,
-  PersistOnly = 2,
-  StreamOnly = 3,
+  Persist = 2,
+  Stream = 3,
 }
 
+export type CrudeWriterMode = "persist" | "stream" | "persistStream" | WriterMode;
+
+const constructWriterMode = (mode: CrudeWriterMode): WriterMode => {
+  switch (mode) {
+    case "persist":
+      return WriterMode.Persist;
+    case "stream":
+      return WriterMode.Stream;
+    case "persistStream":
+      return WriterMode.PersistStream;
+    default:
+      return mode;
+  }
+};
+
 export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
 
 const netConfigZ = z.object({
@@ -57,6 +71,8 @@ const netConfigZ = z.object({
   autoIndexPersistInterval: TimeSpan.z.optional(),
 });
 
+type Config = z.infer<typeof netConfigZ>;
+
 const reqZ = z.object({
   command: z.nativeEnum(Command),
   config: netConfigZ.optional(),
@@ -86,10 +102,10 @@ export interface WriterConfig {
   authorities?: control.Authority | control.Authority[];
   // mode sets the persistence and streaming mode of the writer. The default
   // mode is WriterModePersistStream.
-  mode?: WriterMode;
+  mode?: CrudeWriterMode;
   // errOnUnauthorized sets whether the writer raises an error when it attempts to write
   // to a channel without permission.
-  errOnUnauthorized?: boolean,
+  errOnUnauthorized?: boolean;
   //  enableAutoCommit determines whether the writer will automatically commit.
   //  If enableAutoCommit is true, then the writer will commit after each write, and
   //  will flush that commit to index after the specified autoIndexPersistInterval.
@@ -175,7 +191,7 @@ export class Writer {
         keys: adapter.keys,
         controlSubject: subject,
         authorities: toArray(authorities),
-        mode,
+        mode: constructWriterMode(mode),
         errOnUnauthorized,
         enableAutoCommit,
         autoIndexPersistInterval,
@@ -219,20 +235,37 @@ export class Writer {
     return true;
   }
 
-  async setAuthority(value: Record<Key, control.Authority>): Promise<boolean> {
-    const res = await this.execute({
-      command: Command.SetAuthority,
-      config: {
-        keys: Object.keys(value).map((k) => Number(k)),
-        authorities: Object.values(value),
-      },
-    });
-    return res.ack;
+  async setAuthority(value: number): Promise<boolean>;
+
+  async setAuthority(key: KeyOrName, authority: control.Authority): Promise<boolean>;
+
+  async setAuthority(value: Record<KeyOrName, control.Authority>): Promise<boolean>;
+
+  async setAuthority(
+    value: Record<KeyOrName, control.Authority> | KeyOrName | number,
+    authority?: control.Authority,
+  ): Promise<boolean> {
+    let config: Config = { keys: [], authorities: [] };
+    if (typeof value === "number" && authority == null)
+      config = { keys: [], authorities: [value] };
+    else {
+      let oValue: Record<KeyOrName, control.Authority>;
+      if (typeof value === "string" || typeof value === "number")
+        oValue = { [value]: authority } as Record<KeyOrName, control.Authority>;
+      else oValue = value;
+      oValue = await this.adapter.adaptObjectKeys(oValue);
+      config = {
+        keys: Object.keys(oValue).map((k) => Number(k)),
+        authorities: Object.values(oValue),
+      };
+    }
+    const response = await this.execute({ command: Command.SetAuthority, config });
+    return response.ack;
   }
 
   /**
    * Commits the written frames to the database. Commit is synchronous, meaning that it
-   * will not return until all frames have been commited to the database.
+   * will not return until all frames have been committed to the database.
    *
    * @returns false if the commit failed due to an error. In this case, the caller
    * should acknowledge the error by calling the error method or closing the writer.