@synnaxlabs/client 0.43.0 → 0.44.1

package/src/hardware/task/payload.ts

@@ -7,14 +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 {
-  binary,
-  type observe,
-  status,
-  type UnknownRecord,
-  unknownRecordZ,
-} from "@synnaxlabs/x";
-import { z } from "zod/v4";
+import { binary, type observe, record, status } from "@synnaxlabs/x";
+import { z } from "zod";
 
 import { type Key as RackKey } from "@/hardware/rack/payload";
 import { decodeJSONString } from "@/util/decodeJSONString";
@@ -27,77 +21,107 @@ export const keyZ = z.union([
 ]);
 export type Key = z.infer<typeof keyZ>;
 
-export const stateZ = z.object({
-  task: keyZ,
-  variant: status.variantZ,
-  key: z.string().optional(),
-  details: unknownRecordZ
-    .or(z.string().transform(parseWithoutKeyConversion))
-    .or(z.array(z.unknown()))
-    .or(z.null()) as z.ZodType<UnknownRecord | undefined>,
-});
+export const statusDetailsZ = <D extends z.ZodType>(data: D) =>
+  z.object({ task: keyZ, running: z.boolean(), data });
 
-export interface State<Details extends {} = UnknownRecord>
-  extends Omit<z.infer<typeof stateZ>, "details"> {
-  details?: Details;
-}
+export type StatusDetails<D extends z.ZodType> = z.infer<
+  ReturnType<typeof statusDetailsZ<D>>
+>;
 
-export const taskZ = z.object({
-  key: keyZ,
-  name: z.string(),
-  type: z.string(),
-  internal: z.boolean().optional(),
-  config: unknownRecordZ.or(z.string().transform(decodeJSONString)),
-  state: stateZ.optional().nullable(),
-  snapshot: z.boolean().optional(),
-});
+export const statusZ = <D extends z.ZodType>(data: D) =>
+  status.statusZ(statusDetailsZ(data));
 
-export interface Payload<
-  Config extends UnknownRecord = UnknownRecord,
-  Details extends {} = UnknownRecord,
-  Type extends string = string,
-> extends Omit<z.infer<typeof taskZ>, "config" | "type" | "state"> {
-  type: Type;
-  config: Config;
-  state?: State<Details> | null;
-}
+export type Status<StatusData extends z.ZodType = z.ZodUnknown> = z.infer<
+  ReturnType<typeof statusZ<StatusData>>
+>;
 
-export const newZ = taskZ.omit({ key: true }).extend({
-  key: keyZ.transform((k) => k.toString()).optional(),
-  config: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
-});
+export const taskZ = <
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodUnknown,
+>(
+  schemas: Schemas<Type, Config, StatusData> = {
+    typeSchema: z.string() as unknown as Type,
+    configSchema: z.unknown() as unknown as Config,
+    statusDataSchema: z.unknown() as unknown as StatusData,
+  },
+) =>
+  z.object({
+    key: keyZ,
+    name: z.string(),
+    type: schemas.typeSchema,
+    internal: z.boolean().optional(),
+    config: z.string().transform(decodeJSONString).or(schemas.configSchema),
+    status: statusZ(schemas.statusDataSchema).optional().nullable(),
+    snapshot: z.boolean().optional(),
+  });
 
-export interface New<
-  Config extends UnknownRecord = UnknownRecord,
-  Type extends string = string,
-> extends Omit<z.input<typeof newZ>, "config" | "state"> {
-  type: Type;
-  config: Config;
+export interface Schemas<
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+> {
+  typeSchema: Type;
+  configSchema: Config;
+  statusDataSchema: StatusData;
 }
 
+export type Payload<
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+> = {
+  key: Key;
+  name: string;
+  type: z.infer<Type>;
+  config: z.infer<Config>;
+  status?: Status<StatusData>;
+  snapshot?: boolean;
+  internal?: boolean;
+};
+
+export const newZ = <
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodUnknown,
+>(
+  schemas?: Schemas<Type, Config, StatusData>,
+) =>
+  taskZ(schemas)
+    .omit({ key: true })
+    .extend({
+      key: keyZ.transform((k) => k.toString()).optional(),
+      config: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
+    });
+
+export type New<
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+> = {
+  key?: Key;
+  name: string;
+  type: z.infer<Type>;
+  config: z.infer<Config>;
+};
+
 export const commandZ = z.object({
   task: keyZ,
   type: z.string(),
   key: z.string(),
-  args: unknownRecordZ
+  args: record.unknownZ
     .or(z.string().transform(parseWithoutKeyConversion))
     .or(z.array(z.unknown()))
     .or(z.null())
-    .optional() as z.ZodOptional<z.ZodType<UnknownRecord>>,
+    .optional() as z.ZodOptional<z.ZodType<record.Unknown>>,
 });
 
-export interface Command<Args extends {} = UnknownRecord>
-  extends Omit<z.infer<typeof commandZ>, "args"> {
-  args?: Args;
+export interface Command extends Omit<z.infer<typeof commandZ>, "args"> {
+  args?: record.Unknown;
 }
 
-export interface StateObservable<Details extends {} = UnknownRecord>
-  extends observe.ObservableAsyncCloseable<State<Details>> {}
-
-export interface CommandObservable<Args extends {} = UnknownRecord>
-  extends observe.ObservableAsyncCloseable<Command<Args>> {}
+export interface StateObservable<StatusData extends z.ZodType>
+  extends observe.ObservableAsyncCloseable<Status<StatusData>> {}
 
-export const ONTOLOGY_TYPE = "task";
-export type OntologyType = typeof ONTOLOGY_TYPE;
+export interface CommandObservable extends observe.ObservableAsyncCloseable<Command> {}
 
-export const getRackKey = (key: Key): RackKey => Number(BigInt(key) >> 32n);
+export const rackKey = (key: Key): RackKey => Number(BigInt(key) >> 32n);

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

@@ -7,13 +7,13 @@
 // 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 { describe, expect, it } from "vitest";
+import { id, TimeStamp } from "@synnaxlabs/x";
+import { beforeAll, describe, expect, it } from "vitest";
 
-import { type task } from "@/hardware/task";
-import { newClient } from "@/setupspecs";
+import { task } from "@/hardware/task";
+import { newTestClient } from "@/testutil/client";
 
-const client = newClient();
+const client = newTestClient();
 
 describe("Task", async () => {
   const testRack = await client.hardware.racks.create({ name: "test" });
@@ -57,7 +57,7 @@ describe("Task", async () => {
         name: "updated",
       });
       expect(updated.name).toBe("updated");
-      const retrieved = await client.hardware.tasks.retrieve(m.key);
+      const retrieved = await client.hardware.tasks.retrieve({ key: m.key });
       expect(retrieved.name).toBe("updated");
     });
   });
@@ -68,46 +68,200 @@ describe("Task", async () => {
         config: { a: "dog" },
         type: "ni",
       });
-      const retrieved = await client.hardware.tasks.retrieve(m.key);
+      const retrieved = await client.hardware.tasks.retrieve({ key: m.key });
       expect(retrieved.key).toBe(m.key);
       expect(retrieved.name).toBe("test");
       expect(retrieved.config).toStrictEqual({ a: "dog" });
       expect(retrieved.type).toBe("ni");
     });
-    describe("retrieveByName", () => {
-      it("should retrieve a task by its name", async () => {
-        const name = `test-${Date.now()}-${Math.random()}`;
-        const m = await testRack.createTask({ name, config: { a: "dog" }, type: "ni" });
-        const retrieved = await client.hardware.tasks.retrieveByName(name);
-        expect(retrieved.key).toBe(m.key);
-      });
+
+    it("should retrieve a task by its name", async () => {
+      const name = `test-${Date.now()}-${Math.random()}`;
+      const m = await testRack.createTask({ name, config: { a: "dog" }, type: "ni" });
+      const retrieved = await client.hardware.tasks.retrieve({ name });
+      expect(retrieved.key).toBe(m.key);
     });
-    describe("retrieve with state", () => {
-      it("should also send the tasks state", async () => {
+
+    describe("state", () => {
+      it("should include task status when requested", async () => {
         const t = await testRack.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> = {
+        const w = await client.openWriter([task.STATUS_CHANNEL_NAME]);
+        const communicatedStatus: task.Status = {
           key: id.create(),
-          task: t.key,
           variant: "success",
+          details: { task: t.key, running: false, data: {} },
+          message: "test",
+          time: TimeStamp.now(),
         };
-        await w.write("sy_task_state", [state]);
+        await w.write(task.STATUS_CHANNEL_NAME, [communicatedStatus]);
         await w.close();
         await expect
           .poll(async () => {
-            const retrieved = await client.hardware.tasks.retrieve(t.key, {
-              includeState: true,
+            const retrieved = await client.hardware.tasks.retrieve({
+              key: t.key,
+              includeStatus: true,
+            });
+            return retrieved.status?.variant === communicatedStatus.variant;
+          })
+          .toBe(true);
+      });
+    });
+
+    describe("request object format", () => {
+      const testTasks: Array<{ key: string; name: string; type: string }> = [];
+      let secondRack: any;
+
+      beforeAll(async () => {
+        secondRack = await client.hardware.racks.create({ name: "test-rack-2" });
+
+        const taskConfigs = [
+          { name: "sensor_task1", type: "ni", rack: testRack },
+          { name: "sensor_task2", type: "ni", rack: testRack },
+          { name: "actuator_task1", type: "labjack", rack: testRack },
+          { name: "actuator_task2", type: "labjack", rack: secondRack },
+          { name: "controller_task", type: "opc", rack: secondRack },
+        ];
+
+        for (const config of taskConfigs) {
+          const task = await config.rack.createTask({
+            name: config.name,
+            type: config.type,
+            config: { test: true },
+          });
+          testTasks.push({ key: task.key, name: config.name, type: config.type });
+        }
+      });
+
+      it("should retrieve tasks by rack", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          rack: testRack.key,
+        });
+        expect(result.length).toBeGreaterThanOrEqual(3);
+        expect(result.every((t) => task.rackKey(t.key) === testRack.key)).toBe(true);
+      });
+
+      it("should retrieve tasks by multiple keys", async () => {
+        const keysToQuery = testTasks.slice(0, 2).map((t) => t.key);
+        const result = await client.hardware.tasks.retrieve({
+          keys: keysToQuery,
+        });
+        expect(result).toHaveLength(2);
+        expect(result.map((t) => t.key).sort()).toEqual(keysToQuery.sort());
+      });
+
+      it("should retrieve tasks by multiple names", async () => {
+        const namesToQuery = ["sensor_task1", "actuator_task1"];
+        const result = await client.hardware.tasks.retrieve({
+          names: namesToQuery,
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(result.every((t) => namesToQuery.includes(t.name))).toBe(true);
+      });
+
+      it("should retrieve tasks by types", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          types: ["ni"],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        expect(result.every((t) => t.type === "ni")).toBe(true);
+      });
+
+      it("should retrieve tasks by multiple types", async () => {
+        const typesToQuery = ["ni", "labjack"];
+        const result = await client.hardware.tasks.retrieve({
+          types: typesToQuery,
+        });
+        expect(result.length).toBeGreaterThanOrEqual(4);
+        expect(result.every((t) => typesToQuery.includes(t.type))).toBe(true);
+      });
+
+      it("should support pagination with limit and offset", async () => {
+        const firstPage = await client.hardware.tasks.retrieve({
+          rack: testRack.key,
+          limit: 2,
+          offset: 0,
+        });
+        expect(firstPage.length).toBeLessThanOrEqual(2);
+
+        if (firstPage.length === 2) {
+          const secondPage = await client.hardware.tasks.retrieve({
+            rack: testRack.key,
+            limit: 2,
+            offset: 2,
+          });
+
+          const firstPageKeys = firstPage.map((t) => t.key);
+          const secondPageKeys = secondPage.map((t) => t.key);
+          expect(firstPageKeys.every((key) => !secondPageKeys.includes(key))).toBe(
+            true,
+          );
+        }
+      });
+
+      it("should support combined filters", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          rack: testRack.key,
+          types: ["ni"],
+          includeStatus: true,
+        });
+        expect(result.length).toBeGreaterThanOrEqual(1);
+        expect(result.every((t) => t.type === "ni")).toBe(true);
+
+        await expect
+          .poll(async () => {
+            const tasks = await client.hardware.tasks.retrieve({
+              rack: testRack.key,
+              types: ["ni"],
+              includeStatus: true,
             });
-            return retrieved.state?.variant === state.variant;
+            return tasks.every((t) => t.status !== undefined);
           })
-          .toBeTruthy();
+          .toBe(true);
+      });
+
+      it("should handle empty results gracefully", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          types: ["nonexistent_type"],
+        });
+        expect(result).toEqual([]);
+      });
+
+      it("should combine rack and type filters", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          rack: secondRack.key,
+          types: ["labjack"],
+        });
+        expect(result.length).toBeGreaterThanOrEqual(1);
+        expect(result.every((t) => t.type === "labjack")).toBe(true);
+      });
+
+      it("should handle limit without offset", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          limit: 1,
+        });
+        expect(result).toHaveLength(1);
+      });
+
+      it("should retrieve tasks with includeStatus in request object", async () => {
+        const result = await client.hardware.tasks.retrieve({
+          rack: testRack.key,
+          includeStatus: true,
+        });
+        expect(result.length).toBeGreaterThanOrEqual(1);
+
+        await expect
+          .poll(async () => {
+            const tasks = await client.hardware.tasks.retrieve({
+              rack: testRack.key,
+              includeStatus: true,
+            });
+            return tasks.every((t) => t.status !== undefined);
+          })
+          .toBe(true);
       });
     });
   });
@@ -125,11 +279,33 @@ describe("Task", async () => {
     });
   });
 
-  describe("list", () => {
-    it("should list all tasks", async () => {
-      await testRack.createTask({ name: "test", config: { a: "dog" }, type: "ni" });
-      const tasks = await client.hardware.tasks.list();
-      expect(tasks.length).toBeGreaterThan(0);
+  describe("executeCommand", () => {
+    it("should execute a command on a task", async () => {
+      const type = "testCmd";
+      const args = { a: "dog" };
+      const t = await testRack.createTask({
+        name: "test",
+        config: { a: "dog" },
+        type: "ni",
+      });
+      const streamer = await client.openStreamer(task.COMMAND_CHANNEL_NAME);
+      const key = await client.hardware.tasks.executeCommand(t.key, type, args);
+      await expect
+        .poll<Promise<task.Command>>(async () => {
+          const fr = await streamer.read();
+          const sample = fr.at(-1)[task.COMMAND_CHANNEL_NAME];
+          return task.commandZ.parse(sample);
+        })
+        .toMatchObject({ key, task: t.key, type, args });
+      streamer.close();
+    });
+    it("should timeout on a synchronously executed command", async () => {
+      const t = await testRack.createTask({
+        name: "test",
+        config: {},
+        type: "ni",
+      });
+      await expect(t.executeCommandSync("test", 0)).rejects.toThrow("timed out");
     });
   });
 });

package/src/index.ts

@@ -17,6 +17,7 @@ export { control } from "@/control";
 export {
   AuthError,
   ContiguityError,
+  DisconnectedError,
   MultipleFoundError,
   NotFoundError,
   QueryError,
@@ -34,7 +35,7 @@ export { label } from "@/label";
 export { ontology } from "@/ontology";
 export { group } from "@/ontology/group";
 export { ranger } from "@/ranger";
-export { signals } from "@/signals";
+export { newTestClient, TEST_CLIENT_PROPS } from "@/testutil/client";
 export { user } from "@/user";
 export { workspace } from "@/workspace";
 export { linePlot } from "@/workspace/lineplot";