@synnaxlabs/client 0.23.1 → 0.25.0

package/src/framer/client.ts

@@ -7,7 +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 {type StreamClient, UnaryClient } from "@synnaxlabs/freighter";
+import { type StreamClient, UnaryClient } from "@synnaxlabs/freighter";
 import {
   type CrudeSeries,
   type CrudeTimeRange,
@@ -17,13 +17,13 @@ import {
   TimeSpan,
 } from "@synnaxlabs/x";
 
-import { type Key, type KeyOrName, KeysOrNames, type Params} from "@/channel/payload";
-import { analyzeChannelParams,type Retriever } from "@/channel/retriever";
+import { type Key, type KeyOrName, KeysOrNames, type Params } from "@/channel/payload";
+import { analyzeChannelParams, type Retriever } from "@/channel/retriever";
+import { Deleter } from "@/framer/deleter";
 import { Frame } from "@/framer/frame";
-import { Iterator } from "@/framer/iterator";
+import { Iterator, IteratorConfig } from "@/framer/iterator";
 import { Streamer, type StreamerConfig } from "@/framer/streamer";
-import { Writer, type WriterConfig,WriterMode } from "@/framer/writer";
-import { Deleter } from "@/framer/deleter";
+import { Writer, type WriterConfig, WriterMode } from "@/framer/writer";
 
 export class Client {
   private readonly streamClient: StreamClient;
@@ -42,11 +42,16 @@ export class Client {
    * Opens a new iterator over the given channels within the provided time range.
    *
    * @param tr - A time range to iterate over.
-   * @param keys - A list of channel keys to iterate over.
-   * @returns a new {@link TypedIterator}.
+   * @param channels - A list of channels (by name or key) to iterate over.
+   * @param opts - see {@link IteratorConfig}
+   * @returns a new {@link Iterator}.
    */
-  async openIterator(tr: CrudeTimeRange, channels: Params): Promise<Iterator> {
-    return await Iterator._open(tr, channels, this.retriever, this.streamClient);
+  async openIterator(
+    tr: CrudeTimeRange,
+    channels: Params,
+    opts?: IteratorConfig,
+  ): Promise<Iterator> {
+    return await Iterator._open(tr, channels, this.retriever, this.streamClient, opts);
   }
 
   /**
@@ -54,7 +59,7 @@ export class Client {
    *
    * @param config - The configuration for the created writer, see documentation for
    * writerConfig for more detail.
-   * @returns a new {@link RecordWriter}.
+   * @returns a new {@link Writer}.
    */
   async openWriter(config: WriterConfig | Params): Promise<Writer> {
     if (Array.isArray(config) || typeof config !== "object")
@@ -175,14 +180,16 @@ export class Client {
     return frame;
   }
 
-  async delete(
-    channels: Params,
-    timeRange : TimeRange,
-  ): Promise<void> {
-
+  async delete(channels: Params, timeRange: TimeRange): Promise<void> {
     const { normalized, variant } = analyzeChannelParams(channels);
     if (variant === "keys")
-      return await this.deleter.delete({ keys: normalized as Key[], bounds: timeRange });
-    return await this.deleter.delete({ names: normalized as string[], bounds: timeRange });
+      return await this.deleter.delete({
+        keys: normalized as Key[],
+        bounds: timeRange,
+      });
+    return await this.deleter.delete({
+      names: normalized as string[],
+      bounds: timeRange,
+    });
   }
 }

package/src/framer/deleter.spec.ts

@@ -9,9 +9,9 @@
 
 import { DataType, Rate, TimeRange, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, expect, test } from "vitest";
-import { NotFoundError, UnauthorizedError } from "@/errors"
 
 import { type channel } from "@/channel";
+import { NotFoundError, UnauthorizedError } from "@/errors";
 import { newClient } from "@/setupspecs";
 import { randomSeries } from "@/util/telem";
 
@@ -31,16 +31,16 @@ const newIndexDataChannelPair = async (): Promise<channel.Channel[]> => {
     leaseholder: 1,
     isIndex: true,
     dataType: DataType.TIMESTAMP,
-  })
+  });
   const data = await client.channels.create({
     name: "data",
     leaseholder: 1,
     index: ind.key,
     dataType: DataType.INT64,
-  })
+  });
 
-  return [ind, data]
-}
+  return [ind, data];
+};
 
 describe("Deleter", () => {
   test("Client - basic delete", async () => {
@@ -48,49 +48,49 @@ describe("Deleter", () => {
     const data = randomSeries(10, ch.dataType);
     await client.write(TimeStamp.seconds(0), ch.key, data);
 
-    await client.delete(ch.key, TimeStamp.seconds(2).range(TimeStamp.seconds(5)))
+    await client.delete(ch.key, TimeStamp.seconds(2).range(TimeStamp.seconds(5)));
 
     const res = await client.read(TimeRange.MAX, ch.key);
     expect(res.length).toEqual(data.length - 3);
-    expect(res.data.slice(0, 2)).toEqual(data.slice(0, 2))
-    expect(res.data.slice(2)).toEqual(data.slice(5))
+    expect(res.data.slice(0, 2)).toEqual(data.slice(0, 2));
+    expect(res.data.slice(2)).toEqual(data.slice(5));
   });
   test("Client - basic delete by name", async () => {
-    const ch = await newChannel()
+    const ch = await newChannel();
     const data = randomSeries(10, ch.dataType);
     await client.write(TimeStamp.seconds(0), ch.key, data);
 
-    await client.delete(ch.name, TimeStamp.seconds(2).range(TimeStamp.seconds(5)))
+    await client.delete(ch.name, TimeStamp.seconds(2).range(TimeStamp.seconds(5)));
 
     const res = await client.read(TimeRange.MAX, ch.key);
     expect(res.length).toEqual(data.length - 3);
-    expect(res.data.slice(0, 2)).toEqual(data.slice(0, 2))
-    expect(res.data.slice(2)).toEqual(data.slice(5))
-  })
+    expect(res.data.slice(0, 2)).toEqual(data.slice(0, 2));
+    expect(res.data.slice(2)).toEqual(data.slice(5));
+  });
   test("Client - delete name not found", async () => {
     const ch = await newChannel();
     const data = randomSeries(10, ch.dataType);
     await client.write(TimeStamp.seconds(0), ch.key, data);
 
-    await expect(
-      client.delete(["billy bob", ch.name], TimeRange.MAX)
-    ).rejects.toThrow(NotFoundError)
+    await expect(client.delete(["billy bob", ch.name], TimeRange.MAX)).rejects.toThrow(
+      NotFoundError,
+    );
 
     const res = await client.read(TimeRange.MAX, ch.key);
     expect(res.data).toEqual(data);
-  })
+  });
   test("Client - delete key not found", async () => {
     const ch = await newChannel();
     const data = randomSeries(10, ch.dataType);
     await client.write(TimeStamp.seconds(0), ch.key, data);
 
-    await expect(
-      client.delete([ch.key, 1232], TimeRange.MAX)
-    ).rejects.toThrow(NotFoundError)
+    await expect(client.delete([ch.key, 1232], TimeRange.MAX)).rejects.toThrow(
+      NotFoundError,
+    );
 
     const res = await client.read(TimeRange.MAX, ch.key);
     expect(res.data).toEqual(data);
-  })
+  });
 
   test("Client - delete with writer", async () => {
     const ch = await newChannel();
@@ -101,29 +101,30 @@ describe("Deleter", () => {
     });
 
     await expect(
-      client.delete(
-      [ch.key], TimeStamp.seconds(12).range(TimeStamp.seconds(30)))
-    ).rejects.toThrow(UnauthorizedError)
+      client.delete([ch.key], TimeStamp.seconds(12).range(TimeStamp.seconds(30))),
+    ).rejects.toThrow(UnauthorizedError);
 
-    await writer.close()
-  })
+    await writer.close();
+  });
 
   test("Client - delete index channel alone", async () => {
-    const chs = await newIndexDataChannelPair()
-    const index = chs[0]
-    const dat = chs[1]
-    const data = randomSeries(10, dat.dataType)
+    const chs = await newIndexDataChannelPair();
+    const index = chs[0];
+    const dat = chs[1];
+    const data = randomSeries(10, dat.dataType);
 
-    const time = BigInt64Array.from({ length: 10 },
-      (_, i) => (TimeStamp.milliseconds(i)).valueOf());
+    const time = BigInt64Array.from({ length: 10 }, (_, i) =>
+      TimeStamp.milliseconds(i).valueOf(),
+    );
 
-    await index.write(0, time)
-    await dat.write(0, data)
+    await index.write(0, time);
+    await dat.write(0, data);
 
     await expect(
       client.delete(
-        [index.key], TimeStamp.milliseconds(2).range(TimeStamp.milliseconds(5))
-      )
-    ).rejects.toThrow()
-  })
+        [index.key],
+        TimeStamp.milliseconds(2).range(TimeStamp.milliseconds(5)),
+      ),
+    ).rejects.toThrow();
+  });
 });

package/src/framer/iterator.spec.ts

@@ -8,9 +8,10 @@
 // included in the file licenses/APL.txt.
 
 import { DataType, Rate, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
-import { describe, expect,test } from "vitest";
+import { describe, expect, test } from "vitest";
 
 import { type channel } from "@/channel";
+import { AUTO_SPAN } from "@/framer/iterator";
 import { newClient } from "@/setupspecs";
 import { randomSeries } from "@/util/telem";
 
@@ -59,4 +60,28 @@ describe("Iterator", () => {
       await iter.close();
     }
   });
+  test("chunk size", async () => {
+    const ch = await newChannel();
+    const data = Float64Array.of(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
+    await ch.write(0, data);
+
+    const iter = await client.openIterator(TimeRange.MAX, [ch.key], { chunkSize: 4 });
+
+    try {
+      expect(await iter.seekFirst()).toBeTruthy();
+
+      expect(await iter.next(AUTO_SPAN)).toBeTruthy();
+      expect(iter.value.get(ch.key).data).toEqual(Float64Array.of(0, 1, 2, 3));
+
+      expect(await iter.next(AUTO_SPAN)).toBeTruthy();
+      expect(iter.value.get(ch.key).data).toEqual(Float64Array.of(4, 5, 6, 7));
+
+      expect(await iter.next(AUTO_SPAN)).toBeTruthy();
+      expect(iter.value.get(ch.key).data).toEqual(Float64Array.of(8, 9));
+
+      expect(await iter.next(AUTO_SPAN)).toBeFalsy();
+    } finally {
+      await iter.close();
+    }
+  });
 });

package/src/framer/iterator.ts

@@ -50,6 +50,7 @@ const reqZ = z.object({
   bounds: TimeRange.z.optional(),
   stamp: TimeStamp.z.optional(),
   keys: z.number().array().optional(),
+  chunkSize: z.number().optional(),
 });
 
 type Request = z.infer<typeof reqZ>;
@@ -62,6 +63,13 @@ const resZ = z.object({
   frame: frameZ.optional(),
 });
 
+export interface IteratorConfig {
+  /** chunkSize is the maximum number of samples contained per channel in the frame
+  * resulting from a call to next with {@link AUTO_SPAN}.
+  */
+  chunkSize?: number;
+}
+
 /**
  * Used to iterate over a clusters telemetry in time-order. It should not be
  * instantiated directly, and should instead be instantiated via the SegmentClient.
@@ -90,13 +98,18 @@ export class Iterator {
    * channels with the given keys within the provided time range.
    *
    * @param tr - The time range to iterate over.
-   * @param keys - The keys of the channels to iterate over.
+   * @param channels - The channels for the iterator to iterate over (can be provided
+   * in keys or names).
+   * @param retriever - Retriever used to retrieve channel keys from names.
+   * @param client - The stream client allowing streaming of iterated data.
+   * @param opts - See {@link IteratorConfig}.
    */
   static async _open(
     tr: CrudeTimeRange,
     channels: Params,
     retriever: Retriever,
     client: StreamClient,
+    opts: IteratorConfig = {},
   ): Promise<Iterator> {
     const adapter = await ReadFrameAdapter.open(retriever, channels);
     const stream = await client.stream(Iterator.ENDPOINT, reqZ, resZ);
@@ -105,6 +118,7 @@ export class Iterator {
       command: Command.Open,
       keys: adapter.keys,
       bounds: new TimeRange(tr),
+      chunkSize: opts.chunkSize ?? 1e5,
     });
     return iter;
   }

package/src/framer/streamProxy.ts

@@ -39,7 +39,7 @@ export class StreamProxy<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny> {
         Please report this error to the Synnax team. ${JSON.stringify(res)}`,
         );
       if (err != null) {
-        if (err instanceof EOF) return;
+        if (EOF.matches(err)) return;
         throw err;
       }
     }

package/src/framer/streamer.ts

@@ -68,7 +68,7 @@ export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
       const frame = await this.read();
       return { done: false, value: frame };
     } catch (err) {
-      if (err instanceof EOF) return { done: true, value: undefined };
+      if (EOF.matches(err)) return { done: true, value: undefined };
       throw err;
     }
   }

package/src/framer/writer.spec.ts

@@ -117,7 +117,7 @@ describe("Writer", () => {
     test("write with errOnUnauthorized", async () => {
       const ch = await newChannel();
       const w1 = await client.openWriter({
-        start: 0,
+        start: new TimeStamp(TimeSpan.milliseconds(500)),
         channels: ch.key,
       });
 
@@ -130,6 +130,34 @@ describe("Writer", () => {
       ).rejects.toThrow(UnauthorizedError);
       await w1.close();
     });
+    test("setAuthority", 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.key]: 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()
+    })
   });
   describe("Client", () => {
     test("Client - basic write", async () => {

package/src/hardware/device/client.ts

@@ -7,8 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { sendRequired,type UnaryClient } from "@synnaxlabs/freighter";
-import { toArray,type UnknownRecord } from "@synnaxlabs/x";
+import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { toArray, type UnknownRecord } from "@synnaxlabs/x";
 import { binary } from "@synnaxlabs/x/binary";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { z } from "zod";

package/src/hardware/task/client.ts

@@ -9,16 +9,17 @@
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { binary, type observe } from "@synnaxlabs/x";
+import { id } from "@synnaxlabs/x";
 import { type UnknownRecord } from "@synnaxlabs/x/record";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { type CrudeTimeSpan, TimeSpan } from "@synnaxlabs/x/telem";
 import { toArray } from "@synnaxlabs/x/toArray";
-import { nanoid } from "nanoid/non-secure";
 import { z } from "zod";
 
 import { framer } from "@/framer";
 import { type Frame } from "@/framer/frame";
 import { rack } from "@/hardware/rack";
+import { signals } from "@/signals";
 import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
 
@@ -60,6 +61,7 @@ export const taskZ = z.object({
   key: taskKeyZ,
   name: z.string(),
   type: z.string(),
+  internal: z.boolean().optional(),
   config: z.record(z.unknown()).or(
     z.string().transform((c) => {
       if (c === "") return {};
@@ -114,9 +116,10 @@ export class Task<
 > {
   readonly key: TaskKey;
   readonly name: string;
+  readonly internal: boolean;
   readonly type: T;
   readonly config: C;
-  readonly state?: State<D>;
+  state?: State<D>;
   private readonly frameClient: framer.Client;
 
   constructor(
@@ -125,12 +128,14 @@ export class Task<
     type: T,
     config: C,
     frameClient: framer.Client,
+    internal: boolean = false,
     state?: State<D> | null,
   ) {
     this.key = key;
     this.name = name;
     this.type = type;
     this.config = config;
+    this.internal = internal;
     if (state !== null) this.state = state;
     this.frameClient = frameClient;
   }
@@ -142,12 +147,13 @@ export class Task<
       type: this.type,
       config: this.config,
       state: this.state,
+      internal: this.internal,
     };
   }
 
   async executeCommand(type: string, args?: UnknownRecord): Promise<string> {
     const writer = await this.frameClient.openWriter(TASK_CMD_CHANNEL);
-    const key = nanoid();
+    const key = id.id();
     await writer.write(TASK_CMD_CHANNEL, [{ task: this.key, type, key, args }]);
     await writer.close();
     return key;
@@ -282,7 +288,11 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
   }
 
   async page(offset: number, limit: number): Promise<Payload[]> {
-    return this.execRetrieve({ offset, limit });
+    return await this.execRetrieve({ offset, limit });
+  }
+
+  async list(options: RetrieveOptions = {}): Promise<Task[]> {
+    return this.sugar(await this.execRetrieve(options));
   }
 
   async retrieve<
@@ -343,8 +353,37 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
 
   private sugar(payloads: Payload[]): Task[] {
     return payloads.map(
-      ({ key, name, type, config, state }) =>
-        new Task(key, name, type, config, this.frameClient, state),
+      ({ key, name, type, config, state, internal }) =>
+        new Task(key, name, type, config, this.frameClient, internal, state),
+    );
+  }
+
+  async openTracker(): Promise<signals.Observable<string, string>> {
+    return await signals.openObservable<string, string>(
+      this.frameClient,
+      "sy_task_set",
+      "sy_task_delete",
+      (variant, data) =>
+        Array.from(data).map((k) => ({
+          variant,
+          key: k.toString(),
+          value: k.toString(),
+        })),
+    );
+  }
+
+  async openStateObserver<D extends UnknownRecord = UnknownRecord>(): Promise<
+    StateObservable<D>
+  > {
+    return new framer.ObservableStreamer<State<D>>(
+      await this.frameClient.openStreamer(TASK_STATE_CHANNEL),
+      (frame) => {
+        const s = frame.get(TASK_STATE_CHANNEL);
+        if (s.length === 0) return [null, false];
+        const parse = stateZ.safeParse(s.at(-1));
+        if (!parse.success) return [null, false];
+        return [parse.data as State<D>, true];
+      },
     );
   }
 }

package/src/hardware/task/task.spec.ts

@@ -7,7 +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 { nanoid } from "nanoid";
+import { id } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 
 import { task } from "@/hardware/task";
@@ -71,7 +71,7 @@ describe("Hardware", () => {
           dog: string;
         }
         const state: task.State<StateDetails> = {
-          key: nanoid(),
+          key: id.id(),
           task: t.key,
           variant: "success",
         };
@@ -84,5 +84,17 @@ describe("Hardware", () => {
         expect(retrieved.state?.variant).toBe(state.variant);
       });
     });
+    describe("list", () => {
+      it("should list all tasks", async () => {
+        const t = await client.hardware.racks.create({ name: "test" });
+        await t.createTask({
+          name: "test",
+          config: { a: "dog" },
+          type: "ni",
+        });
+        const tasks = await client.hardware.tasks.list();
+        expect(tasks.length).toBeGreaterThan(0);
+      });
+    });
   });
 });

package/src/index.ts

@@ -9,13 +9,14 @@
 
 export * from "@/channel";
 export { Channel } from "@/channel/client";
-export type { SynnaxProps } from "@/client";
-export { default as Synnax, synnaxPropsZ } from "@/client";
+export { default as Synnax, type SynnaxProps, synnaxPropsZ } from "@/client";
 export * from "@/connection";
 export { control } from "@/control";
 export {
   AuthError,
   ContiguityError,
+  MultipleFoundError,
+  NotFoundError,
   QueryError,
   RouteError,
   UnexpectedError,

package/src/ontology/group/external.ts

@@ -9,3 +9,4 @@
 
 export * from "@/ontology/group/client";
 export * from "@/ontology/group/group";
+export * from "@/ontology/group/payload";

package/src/ontology/group/payload.ts

@@ -17,12 +17,12 @@ export type Keys = Key[];
 export type Names = Name[];
 export type Params = Key | Name | Keys | Names;
 
-export const payloadZ = z.object({
+export const groupZ = z.object({
   key: keyZ,
   name: z.string(),
 });
 
-export type Payload = z.infer<typeof payloadZ>;
+export type Payload = z.infer<typeof groupZ>;
 
 export type ParamAnalysisResult =
   | {

package/src/ontology/group/writer.ts

@@ -10,11 +10,11 @@
 import { type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { type Payload, payloadZ } from "@/ontology/group/payload";
+import { groupZ,type Payload } from "@/ontology/group/payload";
 import { type ID, idZ } from "@/ontology/payload";
 
 const resZ = z.object({
-  group: payloadZ,
+  group: groupZ,
 });
 
 const createReqZ = z.object({

package/src/ontology/ontology.spec.ts

@@ -7,7 +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 { describe, expect, it,test } from "vitest";
+import { describe, expect, it, test } from "vitest";
 
 import { ontology } from "@/ontology";
 import { newClient } from "@/setupspecs";

package/src/ranger/active.ts

@@ -11,7 +11,7 @@ import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
 import { QueryError } from "@/errors";
-import { type Key, keyZ,type Payload, payloadZ } from "@/ranger/payload";
+import { type Key, keyZ, type Payload, payloadZ } from "@/ranger/payload";
 
 const setActiveResZ = z.object({});
 
@@ -57,7 +57,7 @@ export class Active {
       z.object({}),
       retrieveActiveResZ,
     );
-    if (err instanceof QueryError) return null;
+    if (QueryError.matches(err)) return null;
     if (err != null) throw err;
     return res.range;
   }