@synnaxlabs/client 0.20.0 → 0.22.0

package/src/hardware/rack/rack.spec.ts

@@ -8,7 +8,9 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it } from "vitest";
+import { ZodError } from "zod";
 
+import { NotFoundError } from "@/errors";
 import { newClient } from "@/setupspecs";
 
 const client = newClient();
@@ -19,6 +21,10 @@ describe("Rack", () => {
       const r = await client.hardware.racks.create({ name: "test" });
       expect(r.key).toBeGreaterThan(0n);
     });
+    it("should return an error if the rack doesn't have a name", async () => {
+      // @ts-expect-error
+      await expect(client.hardware.racks.create({})).rejects.toThrow(ZodError);
+    });
   });
   describe("retrieve", () => {
     it("should retrieve a rack by its key", async () => {
@@ -27,6 +33,13 @@ describe("Rack", () => {
       expect(retrieved.key).toBe(r.key);
       expect(retrieved.name).toBe("test");
     });
+    it("should retrieve a rack by its name", async () => {
+      const name = `TimeStamp.now().toString()}-${Math.random()}`;
+      const r = await client.hardware.racks.create({ name });
+      const retrieved = await client.hardware.racks.retrieve(name);
+      expect(retrieved.key).toBe(r.key);
+      expect(retrieved.name).toEqual(name);
+    });
   });
   describe("tasks", () => {
     it("should list the tasks on a rack", async () => {
@@ -34,5 +47,11 @@ describe("Rack", () => {
       const tasks = await r.listTasks();
       expect(tasks).toHaveLength(0);
     });
-  })
+    it("should throw an error if a task cannot be found by name", async () => {
+      const r = await client.hardware.racks.create({ name: "test" });
+      await expect(
+        async () => await r.retrieveTaskByName("nonexistent"),
+      ).rejects.toThrow(NotFoundError);
+    });
+  });
 });

package/src/hardware/task/client.ts

@@ -7,51 +7,344 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { AsyncTermSearcher, toArray } from "@synnaxlabs/x";
+import { type UnaryClient, sendRequired } from "@synnaxlabs/freighter";
+import { binary, type observe } from "@synnaxlabs/x";
+import { type UnknownRecord } from "@synnaxlabs/x/record";
+import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
+import { TimeSpan, type CrudeTimeSpan } from "@synnaxlabs/x/telem";
+import { toArray } from "@synnaxlabs/x/toArray";
+import { nanoid } from "nanoid";
+import { z } from "zod";
 
-import { TaskKey, type NewTask, type Task } from "@/hardware/task/payload";
-import { type RetrieveRequest, type Retriever } from "@/hardware/task/retriever";
-import { type Writer } from "@/hardware/task/writer";
+import { framer } from "@/framer";
+import { type Frame } from "@/framer/frame";
+import { rack } from "@/hardware/rack";
+import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
+import { nullableArrayZ } from "@/util/zod";
 
-export class Client implements AsyncTermSearcher<string, TaskKey, Task> {
-  private readonly retriever: Retriever;
-  private readonly writer: Writer;
+const TASK_STATE_CHANNEL = "sy_task_state";
+const TASK_CMD_CHANNEL = "sy_task_cmd";
 
-  constructor(retriever: Retriever, writer: Writer) {
-    this.retriever = retriever;
-    this.writer = writer;
+export const taskKeyZ = z.union([
+  z.string(),
+  z.bigint().transform((k) => k.toString()),
+  z.number().transform((k) => k.toString()),
+]);
+
+export type TaskKey = z.infer<typeof taskKeyZ>;
+
+export const stateZ = z.object({
+  task: taskKeyZ,
+  variant: z.string(),
+  key: z.string().optional(),
+  details: z
+    .record(z.unknown())
+    .or(
+      z.string().transform((c) => {
+        if (c === "") return {};
+        return JSON.parse(c);
+      }),
+    )
+    .or(z.array(z.unknown()))
+    .or(z.null()),
+});
+
+export type State<D extends {} = UnknownRecord> = Omit<
+  z.infer<typeof stateZ>,
+  "details"
+> & {
+  details?: D;
+};
+
+export const taskZ = z.object({
+  key: taskKeyZ,
+  name: z.string(),
+  type: z.string(),
+  config: z.record(z.unknown()).or(
+    z.string().transform((c) => {
+      if (c === "") return {};
+      return binary.JSON_ECD.decodeString(c);
+    }),
+  ) as z.ZodType<UnknownRecord>,
+  state: stateZ.optional().nullable(),
+});
+
+export const newTaskZ = taskZ.omit({ key: true }).extend({
+  key: taskKeyZ.transform((k) => k.toString()).optional(),
+  config: z.unknown().transform((c) => binary.JSON_ECD.encodeString(c)),
+});
+
+export type NewTask<
+  C extends UnknownRecord = UnknownRecord,
+  T extends string = string,
+> = Omit<z.input<typeof newTaskZ>, "config" | "state"> & {
+  type: T;
+  config: C;
+};
+
+export type Payload<
+  C extends UnknownRecord = UnknownRecord,
+  D extends {} = UnknownRecord,
+  T extends string = string,
+> = Omit<z.output<typeof taskZ>, "config" | "type" | "state"> & {
+  type: T;
+  config: C;
+  state?: State<D> | null;
+};
+
+export const commandZ = z.object({
+  task: taskKeyZ,
+  type: z.string(),
+  key: z.string(),
+  args: z.record(z.unknown()).or(
+    z.string().transform((c) => {
+      if (c === "") return {};
+      return JSON.parse(c);
+    }),
+  ) as z.ZodType<UnknownRecord>,
+});
+
+export type StateObservable<D extends UnknownRecord = UnknownRecord> =
+  observe.ObservableAsyncCloseable<State<D>>;
+
+export class Task<
+  C extends UnknownRecord = UnknownRecord,
+  D extends {} = UnknownRecord,
+  T extends string = string,
+> {
+  readonly key: TaskKey;
+  readonly name: string;
+  readonly type: T;
+  readonly config: C;
+  readonly state?: State<D>;
+  private readonly frameClient: framer.Client;
+
+  constructor(
+    key: TaskKey,
+    name: string,
+    type: T,
+    config: C,
+    frameClient: framer.Client,
+    state?: State<D> | null,
+  ) {
+    this.key = key;
+    this.name = name;
+    this.type = type;
+    this.config = config;
+    if (state !== null) this.state = state;
+    this.frameClient = frameClient;
   }
 
-  async search(term: string): Promise<Task[]> {
-    const res = await this.retriever.search(term);
-    return res;
+  get payload(): Payload<C, D> {
+    return {
+      key: this.key,
+      name: this.name,
+      type: this.type,
+      config: this.config,
+      state: this.state,
+    };
   }
 
-  async page(offset: number, limit: number): Promise<Task[]> {
-    const res = await this.retriever.page(offset, limit);
+  async executeCommand(type: string, args?: UnknownRecord): Promise<string> {
+    const writer = await this.frameClient.openWriter(TASK_CMD_CHANNEL);
+    const key = nanoid();
+    await writer.write(TASK_CMD_CHANNEL, [{ task: this.key, type, key, args }]);
+    await writer.close();
+    return key;
+  }
+
+  async executeCommandSync<D extends UnknownRecord = UnknownRecord>(
+    type: string,
+    args: UnknownRecord,
+    timeout: CrudeTimeSpan,
+  ): Promise<State<D>> {
+    const streamer = await this.frameClient.openStreamer(TASK_STATE_CHANNEL);
+    const cmdKey = await this.executeCommand(type, args);
+    let res: State<D>;
+    const to = new Promise((resolve) =>
+      setTimeout(() => resolve(false), new TimeSpan(timeout).milliseconds),
+    );
+    while (true) {
+      const frame = (await Promise.any([streamer.read(), to])) as Frame | false;
+      if (frame === false) throw new Error("Command timed out");
+      const parsed = stateZ.safeParse(frame.at(-1).sy_task_state);
+      if (parsed.success) {
+        res = parsed.data as State<D>;
+        if (res.key === cmdKey) break;
+      } else {
+        console.error(parsed.error);
+      }
+    }
+    streamer.close();
     return res;
   }
 
-  async create(task: NewTask): Promise<Task> {
-    const res = await this.writer.create([task]);
-    return res[0];
+  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];
+        const state = parse.data as State<D>;
+        if (state.task !== this.key) return [null, false];
+        return [state, true];
+      },
+    );
+  }
+}
+
+const retrieveReqZ = z.object({
+  rack: rack.rackKeyZ.optional(),
+  keys: z.string().array().optional(),
+  names: z.string().array().optional(),
+  offset: z.number().optional(),
+  limit: z.number().optional(),
+  includeState: z.boolean().optional(),
+});
+
+const retrieveResZ = z.object({
+  tasks: nullableArrayZ(taskZ),
+});
+
+export type RetrieveRequest = z.infer<typeof retrieveReqZ>;
+
+export type RetrieveOptions = Pick<
+  RetrieveRequest,
+  "rack" | "offset" | "limit" | "includeState"
+>;
+
+const RETRIEVE_ENDPOINT = "/hardware/task/retrieve";
+const CREATE_ENDPOINT = "/hardware/task/create";
+const DELETE_ENDPOINT = "/hardware/task/delete";
+
+const createReqZ = z.object({ tasks: newTaskZ.array() });
+const createResZ = z.object({ tasks: taskZ.array() });
+const deleteReqZ = z.object({ keys: taskKeyZ.array() });
+const deleteResZ = z.object({});
+
+export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
+  readonly type: string = "task";
+  private readonly client: UnaryClient;
+  private readonly frameClient: framer.Client;
+
+  constructor(client: UnaryClient, frameClient: framer.Client) {
+    this.client = client;
+    this.frameClient = frameClient;
+  }
+
+  async create<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(task: NewTask<C, T>): Promise<Task<C, D, T>>;
+
+  async create<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(tasks: NewTask<C, T>[]): Promise<Task<C, D, T>[]>;
+
+  async create<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(
+    task: NewTask<C, T> | Array<NewTask<C, T>>,
+  ): Promise<Task<C, D, T> | Array<Task<C, D, T>>> {
+    const isSingle = !Array.isArray(task);
+    const res = await sendRequired<typeof createReqZ, typeof createResZ>(
+      this.client,
+      CREATE_ENDPOINT,
+      { tasks: toArray(task) },
+      createReqZ,
+      createResZ,
+    );
+    const sugared = this.sugar(res.tasks) as Array<Task<C, D, T>>;
+    return isSingle ? sugared[0] : sugared;
+  }
+
+  async delete(keys: bigint | bigint[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: toArray(keys) },
+      deleteReqZ,
+      deleteResZ,
+    );
   }
 
-  async retrieve(rack: number): Promise<Task[]>;
+  async search(term: string): Promise<Payload[]> {
+    return await this.execRetrieve({ keys: [term] });
+  }
+
+  async page(offset: number, limit: number): Promise<Payload[]> {
+    return this.execRetrieve({ offset, limit });
+  }
+
+  async retrieve<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(rack: number, options?: RetrieveOptions): Promise<Task<C, D, T>[]>;
+
+  async retrieve<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(keys: string[], options?: RetrieveOptions): Promise<Task<C, D, T>[]>;
 
-  async retrieve(keys: string[]): Promise<Task[]>;
+  async retrieve<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(key: string, options?: RetrieveOptions): Promise<Task<C, D, T>>;
 
-  async retrieve(key: string): Promise<Task>;
+  async retrieve<
+    C extends UnknownRecord = UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(
+    rack: number | string | string[],
+    options?: RetrieveOptions,
+  ): Promise<Task<C, D, T> | Task<C, D, T>[]> {
+    const { single, normalized, variant } = analyzeParams(
+      rack,
+      { number: "rack", string: "keys" },
+      { convertNumericStrings: false },
+    );
+    let req: RetrieveRequest = { ...options };
+    if (variant === "rack") req.rack = rack as number;
+    else req.keys = normalized as string[];
+    const tasks = await this.execRetrieve(req);
+    const sugared = this.sugar(tasks) as Array<Task<C, D, T>>;
+    return single && variant !== "rack" ? sugared[0] : sugared;
+  }
+
+  async retrieveByName(name: string, rack?: number): Promise<Task> {
+    const tasks = await this.execRetrieve({ names: [name], rack });
+    checkForMultipleOrNoResults("Task", name, tasks, true);
+    return this.sugar(tasks)[0];
+  }
+
+  private async execRetrieve(req: RetrieveRequest): Promise<Payload[]> {
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      req,
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return res.tasks;
+  }
 
-  async retrieve(rack: number | string | string[]): Promise<Task | Task[]> {
-    const params: RetrieveRequest = {};
-    let multi: boolean = true;
-    if (typeof rack === "number") params.rack = rack;
-    else if (typeof rack === "string") {
-      multi = false;
-      params.keys = [rack];
-    } else params.keys = toArray(rack);
-    const res = await this.retriever.retrieve(params);
-    return multi ? res : res[0];
+  private sugar(payloads: Payload[]): Task[] {
+    return payloads.map(
+      ({ key, name, type, config, state }) =>
+        new Task(key, name, type, config, this.frameClient, state),
+    );
   }
 }

package/src/hardware/task/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as task from "@/hardware/task/external";
+export * as task from "@/hardware/task/client";

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

@@ -10,6 +10,8 @@
 import { describe, expect, it } from "vitest";
 
 import { newClient } from "@/setupspecs";
+import { task } from "@/hardware/task";
+import { nanoid } from "nanoid";
 
 const client = newClient();
 
@@ -43,5 +45,44 @@ describe("Hardware", () => {
         expect(retrieved.type).toBe("ni");
       });
     });
+    describe("retrieveByName", () => {
+      it("should retrieve a task by its name", async () => {
+        const name = `test-${Date.now()}-${Math.random()}`;
+        const r = await client.hardware.racks.create({ name });
+        const m = await r.createTask({
+          name,
+          config: { a: "dog" },
+          type: "ni",
+        });
+        const retrieved = await client.hardware.tasks.retrieveByName(name);
+        expect(retrieved.key).toBe(m.key);
+      });
+    });
+    describe("retrieve with state", () => {
+      it("should also send the tasks state", async () => {
+        const r = await client.hardware.racks.create({ name: "test" });
+        const t = await r.createTask({
+          name: "test",
+          config: { a: "dog" },
+          type: "ni",
+        });
+        const w = await client.openWriter(["sy_task_state"]);
+        interface StateDetails {
+          dog: string;
+        }
+        const state: task.State<StateDetails> = {
+          key: nanoid(),
+          task: t.key,
+          variant: "success",
+        };
+        expect(await w.write("sy_task_state", [state])).toBeTruthy();
+        await w.close();
+        const retrieved = await client.hardware.tasks.retrieve(t.key, {
+          includeState: true,
+        });
+        expect(retrieved.state).not.toBeNull();
+        expect(retrieved.state?.variant).toBe(state.variant);
+      });
+    });
   });
 });

package/src/index.ts

@@ -15,8 +15,6 @@ export { Channel } from "@/channel/client";
 export {
   AuthError,
   ContiguityError,
-  GeneralError,
-  ParseError,
   QueryError,
   RouteError,
   UnexpectedError,
@@ -36,7 +34,7 @@ export {
   TimeSpan,
   TimeStamp,
   MultiSeries,
-} from "@synnaxlabs/x";
+} from "@synnaxlabs/x/telem";
 export type {
   TypedArray,
   CrudeDataType,
@@ -49,7 +47,7 @@ export type {
   NumericTelemValue,
   TimeStampStringFormat,
   TZInfo,
-} from "@synnaxlabs/x";
+} from "@synnaxlabs/x/telem";
 export { workspace } from "@/workspace";
 export { ranger } from "@/ranger";
 export { label } from "@/label";
@@ -57,3 +55,4 @@ export { hardware } from "@/hardware";
 export { rack } from "@/hardware/rack";
 export { task } from "@/hardware/task";
 export { device } from "@/hardware/device";
+export { signals } from "@/signals";

package/src/label/client.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { type AsyncTermSearcher } from "@synnaxlabs/x";
+import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 
 import { type framer } from "@/framer";
 import { type Key, type Label, labelZ } from "@/label/payload";
@@ -21,6 +21,7 @@ const LABEL_SET_NAME = "sy_label_set";
 const LABEL_DELETE_NAME = "sy_label_delete";
 
 export class Client implements AsyncTermSearcher<string, Key, Label> {
+  readonly type: string = "label";
   private readonly retriever: Retriever;
   private readonly writer: Writer;
   private readonly frameClient: framer.Client;
@@ -80,7 +81,7 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
   }
 
   async openChangeTracker(): Promise<signals.Observable<string, Label>> {
-    return await signals.Observable.open<string, Label>(
+    return await signals.openObservable<string, Label>(
       this.frameClient,
       LABEL_SET_NAME,
       LABEL_DELETE_NAME,

package/src/label/retriever.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { toArray } from "@synnaxlabs/x";
+import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
 import { keyZ, type Label, labelZ, type Params } from "@/label/payload";

package/src/label/writer.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { toArray } from "@synnaxlabs/x";
+import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
 import { type Key, keyZ, type Label, labelZ } from "@/label/payload";