@synnaxlabs/client 0.43.1 → 0.44.1

package/src/channel/client.ts

@@ -9,7 +9,6 @@
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { array } from "@synnaxlabs/x";
-import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import {
   type CrudeDensity,
   type CrudeTimeStamp,
@@ -18,17 +17,16 @@ import {
   type TimeRange,
   type TypedArray,
 } from "@synnaxlabs/x/telem";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import {
-  channelZ,
   type Key,
   type KeyOrName,
   type Name,
   type New,
-  ONTOLOGY_TYPE,
   type Params,
   type Payload,
+  payloadZ,
 } from "@/channel/payload";
 import {
   analyzeParams,
@@ -37,11 +35,12 @@ import {
   DebouncedBatchRetriever,
   type RetrieveOptions,
   type Retriever,
+  type RetrieveRequest,
 } from "@/channel/retriever";
 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";
 
@@ -49,6 +48,9 @@ interface CreateOptions {
   retrieveIfNameExists?: boolean;
 }
 
+export const SET_CHANNEL_NAME = "sy_channel_set";
+export const DELETE_CHANNEL_NAME = "sy_channel_delete";
+
 /**
  * Represents a Channel in a Synnax database. Typically, channels should not be
  * instantiated directly, but instead created via the `.channels.create` or retrieved
@@ -153,7 +155,7 @@ export class Channel {
    * network transportation, but also provided to you as a convenience.
    */
   get payload(): Payload {
-    return channelZ.parse({
+    return payloadZ.parse({
       key: this.key,
       name: this.name,
       dataType: this.dataType.valueOf(),
@@ -200,7 +202,7 @@ export class Channel {
   }
 }
 
-export const CALCULATION_STATE_CHANNEL_NAME = "sy_calculation_state";
+export const CALCULATION_STATUS_CHANNEL_NAME = "sy_calculation_status";
 
 const RETRIEVE_GROUP_ENDPOINT = "/channel/retrieve-group";
 
@@ -213,8 +215,8 @@ const retrieveGroupResZ = z.object({ group: group.groupZ });
  * cluster. This class should not be instantiated directly, and instead should be used
  * through the `channels` property of an {@link Synnax} client.
  */
-export class Client implements AsyncTermSearcher<string, Key, Channel> {
-  readonly type = ONTOLOGY_TYPE;
+export class Client {
+  readonly type = "channel";
   private readonly frameClient: framer.Client;
   private readonly client: UnaryClient;
   readonly retriever: Retriever;
@@ -315,7 +317,7 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
   /**
    * Retrieves a channel from the database using the given key or name.
    *
-   * @param channel - The key or name of the channel to retrieve.
+   * @param params - The key or name of the channel to retrieve.
    * @param options - Optional parameters to control the retrieval process.
    * @param options.dataTypes - Limits the query to only channels with the specified data
    * type.
@@ -334,13 +336,13 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    * const channel = await client.channels.retrieve(1);
    * ```
    */
-  async retrieve(channel: KeyOrName, options?: RetrieveOptions): Promise<Channel>;
+  async retrieve(params: KeyOrName, options?: RetrieveOptions): Promise<Channel>;
 
   /**
    * Retrieves multiple channels from the database using the provided keys or the
    * provided names.
    *
-   * @param channels - The keys or the names of the channels to retrieve. Note that
+   * @param params - The keys or the names of the channels to retrieve. Note that
    * this method does not support mixing keys and names in the same call.
    * @param options - Optional parameters to control the retrieval process.
    * @param options.dataTypes - Limits the query to only channels with the specified data
@@ -348,7 +350,9 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    * @param options.notDataTypes - Limits the query to only channels without the specified
    *
    */
-  async retrieve(channels: Params, options?: RetrieveOptions): Promise<Channel[]>;
+  async retrieve(params: Params, options?: RetrieveOptions): Promise<Channel[]>;
+
+  async retrieve(params: RetrieveRequest): Promise<Channel[]>;
 
   /**
    * Retrieves a channel from the database using the given parameters.
@@ -358,25 +362,24 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    * @raises {QueryError} If the channel does not exist or if multiple results are returned.
    */
   async retrieve(
-    channels: Params,
+    params: Params | RetrieveRequest,
     options?: RetrieveOptions,
   ): Promise<Channel | Channel[]> {
-    const isSingle = !Array.isArray(channels);
-    const res = this.sugar(await this.retriever.retrieve(channels, options));
-    checkForMultipleOrNoResults("channel", channels, res, isSingle);
-    return isSingle ? res[0] : res;
-  }
+    if (typeof params === "object" && !Array.isArray(params))
+      return this.sugar(await this.retriever.retrieve(params));
 
-  async search(term: string, options?: RetrieveOptions): Promise<Channel[]> {
-    return this.sugar(await this.retriever.search(term, options));
+    const isSingle = !Array.isArray(params);
+    const res = this.sugar(await this.retriever.retrieve(params, options));
+    checkForMultipleOrNoResults<Params, Channel>("channel", params, res, isSingle);
+    return isSingle ? res[0] : res;
   }
 
   /***
    * Deletes channels from the database using the given keys or names.
-   * @param channels - The keys or names of the channels to delete.
+   * @param params - The keys or names of the channels to delete.
    */
-  async delete(channels: Params): Promise<void> {
-    const { normalized, variant } = analyzeParams(channels);
+  async delete(params: Params): Promise<void> {
+    const { normalized, variant } = analyzeParams(params);
     if (variant === "keys")
       return await this.writer.delete({ keys: normalized as Key[] });
     return await this.writer.delete({ names: normalized as string[] });
@@ -388,26 +391,6 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
     return await this.writer.rename(array.toArray(keys), array.toArray(names));
   }
 
-  newSearcherWithOptions(
-    options: RetrieveOptions,
-  ): AsyncTermSearcher<string, Key, Channel> {
-    return {
-      type: this.type,
-      search: async (term: string) => await this.search(term, options),
-      retrieve: async (keys: Key[]) => await this.retrieve(keys, options),
-      page: async (offset: number, limit: number) =>
-        await this.page(offset, limit, options),
-    };
-  }
-
-  async page(
-    offset: number,
-    limit: number,
-    options?: Omit<RetrieveOptions, "limit" | "offset">,
-  ): Promise<Channel[]> {
-    return this.sugar(await this.retriever.page(offset, limit, options));
-  }
-
   createDebouncedBatchRetriever(deb: number = 10): Retriever {
     return new CacheRetriever(
       new DebouncedBatchRetriever(new ClusterRetriever(this.client), deb),
@@ -455,5 +438,7 @@ export const resolveCalculatedIndex = async (
   return null;
 };
 
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key: key.toString() });
+export const ontologyID = (key: Key): ontology.ID => ({
+  type: "channel",
+  key: key.toString(),
+});

package/src/channel/payload.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 { type CrudeDataType, DataType, status } from "@synnaxlabs/x";
-import { z } from "zod/v4";
+import { type CrudeDataType, DataType, status, zod } from "@synnaxlabs/x";
+import { z } from "zod";
 
 import { nullableArrayZ } from "@/util/zod";
 
@@ -21,9 +21,8 @@ export type Names = Name[];
 export type KeyOrName = Key | Name;
 export type KeysOrNames = Keys | Names;
 export type PrimitiveParams = Key | Name | Keys | Names;
-export type Params = Key | Name | Keys | Names | Payload | Payload[];
 
-export const channelZ = z.object({
+export const payloadZ = z.object({
   name: nameZ,
   key: keyZ,
   dataType: DataType.z,
@@ -36,9 +35,9 @@ export const channelZ = z.object({
   expression: z.string().default(""),
   requires: nullableArrayZ(keyZ),
 });
-export interface Payload extends z.infer<typeof channelZ> {}
+export interface Payload extends z.infer<typeof payloadZ> {}
 
-export const newZ = channelZ.extend({
+export const newZ = payloadZ.extend({
   key: keyZ.optional(),
   leaseholder: z.number().optional(),
   index: keyZ.optional(),
@@ -53,12 +52,12 @@ export interface New extends Omit<z.input<typeof newZ>, "dataType"> {
   dataType: CrudeDataType;
 }
 
-export const ONTOLOGY_TYPE = "channel";
-export type OntologyType = typeof ONTOLOGY_TYPE;
+export const calculationStatusZ = status.statusZ();
+export type CalculationStatus = z.infer<typeof calculationStatusZ>;
 
-export const calculationStateZ = z.object({
-  key: keyZ,
-  variant: status.variantZ,
-  message: z.string(),
-});
-export interface CalculationState extends z.infer<typeof calculationStateZ> {}
+export const paramsZ = z.union([
+  zod.toArray(keyZ),
+  zod.toArray(nameZ),
+  zod.toArray(payloadZ).transform((p) => p.map((c) => c.key)),
+]);
+export type Params = Key | Name | Keys | Names | Payload | Payload[];

package/src/channel/retriever.ts

@@ -11,10 +11,9 @@ import { type UnaryClient } from "@synnaxlabs/freighter";
 import { debounce } from "@synnaxlabs/x/debounce";
 import { DataType } from "@synnaxlabs/x/telem";
 import { Mutex } from "async-mutex";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import {
-  channelZ,
   type Key,
   type KeyOrName,
   type Keys,
@@ -24,6 +23,7 @@ import {
   type Names,
   type Params,
   type Payload,
+  payloadZ,
 } from "@/channel/payload";
 import { QueryError } from "@/errors";
 import {
@@ -36,7 +36,7 @@ const reqZ = z.object({
   leaseholder: z.number().optional(),
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
-  search: z.string().optional(),
+  searchTerm: z.string().optional(),
   rangeKey: z.string().optional(),
   limit: z.number().optional(),
   offset: z.number().optional(),
@@ -45,13 +45,15 @@ const reqZ = z.object({
   virtual: z.boolean().optional(),
   isIndex: z.boolean().optional(),
   internal: z.boolean().optional(),
+  calculated: z.boolean().optional(),
 });
-interface Request extends z.input<typeof reqZ> {}
+export interface RetrieveRequest extends z.input<typeof reqZ> {}
 
-export interface RetrieveOptions extends Omit<Request, "keys" | "names" | "search"> {}
+export interface RetrieveOptions
+  extends Omit<RetrieveRequest, "keys" | "names" | "search"> {}
 export interface PageOptions extends Omit<RetrieveOptions, "offset" | "limit"> {}
 
-const resZ = z.object({ channels: nullableArrayZ(channelZ) });
+const resZ = z.object({ channels: nullableArrayZ(payloadZ) });
 
 export const analyzeParams = (
   channels: Params,
@@ -66,9 +68,8 @@ export const analyzeParams = (
 };
 
 export interface Retriever {
-  retrieve: (channels: Params, opts?: RetrieveOptions) => Promise<Payload[]>;
-  search: (term: string, opts?: RetrieveOptions) => Promise<Payload[]>;
-  page: (offset: number, limit: number, opts?: PageOptions) => Promise<Payload[]>;
+  retrieve: ((channels: Params, opts?: RetrieveOptions) => Promise<Payload[]>) &
+    ((request: RetrieveRequest) => Promise<Payload[]>);
 }
 
 export class ClusterRetriever implements Retriever {
@@ -79,11 +80,12 @@ export class ClusterRetriever implements Retriever {
     this.client = client;
   }
 
-  async search(term: string, options?: RetrieveOptions): Promise<Payload[]> {
-    return await this.execute({ search: term, ...options });
-  }
-
-  async retrieve(channels: Params, options?: RetrieveOptions): Promise<Payload[]> {
+  async retrieve(
+    channels: Params | RetrieveRequest,
+    options?: RetrieveOptions,
+  ): Promise<Payload[]> {
+    if (!Array.isArray(channels) && typeof channels === "object")
+      return await this.execute(channels);
     const res = analyzeParams(channels);
     const { variant } = res;
     let { normalized } = res;
@@ -93,11 +95,7 @@ export class ClusterRetriever implements Retriever {
     return await this.execute({ [variant]: normalized, ...options });
   }
 
-  async page(offset: number, limit: number, options?: PageOptions): Promise<Payload[]> {
-    return await this.execute({ offset, limit, ...options });
-  }
-
-  private async execute(request: Request): Promise<Payload[]> {
+  private async execute(request: RetrieveRequest): Promise<Payload[]> {
     const [res, err] = await this.client.send(
       ClusterRetriever.ENDPOINT,
       request,
@@ -120,15 +118,12 @@ export class CacheRetriever implements Retriever {
     this.wrapped = wrapped;
   }
 
-  async search(term: string, options?: RetrieveOptions): Promise<Payload[]> {
-    return await this.wrapped.search(term, options);
-  }
-
-  async page(offset: number, limit: number, options?: PageOptions): Promise<Payload[]> {
-    return await this.wrapped.page(offset, limit, options);
-  }
-
-  async retrieve(channels: Params, options?: RetrieveOptions): Promise<Payload[]> {
+  async retrieve(
+    channels: Params | RetrieveRequest,
+    options?: RetrieveOptions,
+  ): Promise<Payload[]> {
+    if (!Array.isArray(channels) && typeof channels === "object")
+      return await this.wrapped.retrieve(channels);
     const { normalized } = analyzeParams(channels);
     const results: Payload[] = [];
     const toFetch: KeysOrNames = [];
@@ -226,19 +221,9 @@ export class DebouncedBatchRetriever implements Retriever {
     }, deb);
   }
 
-  async search(term: string, options?: RetrieveOptions): Promise<Payload[]> {
-    return await this.wrapped.search(term, options);
-  }
-
-  async page(
-    offset: number,
-    limit: number,
-    options?: RetrieveOptions,
-  ): Promise<Payload[]> {
-    return await this.wrapped.page(offset, limit, options);
-  }
-
-  async retrieve(channels: Params): Promise<Payload[]> {
+  async retrieve(channels: Params | RetrieveRequest): Promise<Payload[]> {
+    if (!Array.isArray(channels) && typeof channels === "object")
+      return await this.wrapped.retrieve(channels);
     const { normalized, variant } = analyzeParams(channels);
     // Bypass on name fetches for now.
     if (variant === "names") return await this.wrapped.retrieve(normalized);

package/src/channel/writer.ts

@@ -9,21 +9,21 @@
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { type DataType } from "@synnaxlabs/x";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import {
-  channelZ,
   type Key,
   keyZ,
   nameZ,
   type New,
   newZ,
   type Payload,
+  payloadZ,
 } from "@/channel/payload";
 import { type CacheRetriever } from "@/channel/retriever";
 
 const createReqZ = z.object({ channels: newZ.array() });
-const createResZ = z.object({ channels: channelZ.array() });
+const createResZ = z.object({ channels: payloadZ.array() });
 
 const deleteReqZ = z.object({
   keys: keyZ.array().optional(),

package/src/client.ts

@@ -10,7 +10,7 @@
 import { breaker } from "@synnaxlabs/x";
 import { TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { URL } from "@synnaxlabs/x/url";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { access } from "@/access";
 import { auth } from "@/auth";
@@ -132,7 +132,7 @@ export default class Synnax extends framer.Client {
     this.control = new control.Client(this);
     this.ontology = new ontology.Client(transport.unary, this);
     const rangeWriter = new ranger.Writer(this.transport.unary);
-    this.labels = new label.Client(this.transport.unary, this, this.ontology);
+    this.labels = new label.Client(this.transport.unary);
     this.ranges = new ranger.Client(
       this,
       rangeWriter,
@@ -144,14 +144,14 @@ export default class Synnax extends framer.Client {
     this.access = new access.Client(this.transport.unary);
     this.user = new user.Client(this.transport.unary);
     this.workspaces = new workspace.Client(this.transport.unary);
-    const devices = new device.Client(this.transport.unary, this);
+    const devices = new device.Client(this.transport.unary);
     const tasks = new task.Client(
       this.transport.unary,
       this,
       this.ontology,
       this.ranges,
     );
-    const racks = new rack.Client(this.transport.unary, tasks, this);
+    const racks = new rack.Client(this.transport.unary, tasks);
     this.hardware = new hardware.Client(tasks, racks, devices);
   }
 

package/src/connection/checker.ts

@@ -10,7 +10,7 @@
 import type { UnaryClient } from "@synnaxlabs/freighter";
 import { migrate } from "@synnaxlabs/x";
 import { TimeSpan } from "@synnaxlabs/x/telem";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 export const statusZ = z.enum(["disconnected", "connecting", "connected", "failed"]);
 export type Status = z.infer<typeof statusZ>;

package/src/connection/connection.spec.ts

@@ -9,20 +9,22 @@
 
 import { URL } from "@synnaxlabs/x/url";
 import { describe, expect, it } from "vitest";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { auth } from "@/auth";
 import { connection } from "@/connection";
-import { HOST, PORT } from "@/setupspecs";
+import { TEST_CLIENT_PROPS } from "@/testutil/client";
 import { Transport } from "@/transport";
 
 describe("connectivity", () => {
   it("should connect to the server", async () => {
-    const transport = new Transport(new URL({ host: HOST, port: PORT }));
-    const client = new auth.Client(transport.unary, {
-      username: "synnax",
-      password: "seldon",
-    });
+    const transport = new Transport(
+      new URL({
+        host: TEST_CLIENT_PROPS.host,
+        port: Number(TEST_CLIENT_PROPS.port),
+      }),
+    );
+    const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
     transport.use(client.middleware());
     const connectivity = new connection.Checker(
       transport.unary,
@@ -31,15 +33,17 @@ describe("connectivity", () => {
     );
     const state = await connectivity.check();
     expect(state.status).toEqual("connected");
-    expect(z.string().uuid().safeParse(state.clusterKey).success).toBe(true);
+    expect(z.uuid().safeParse(state.clusterKey).success).toBe(true);
   });
   describe("version compatibility", () => {
     it("should pull the server and client versions", async () => {
-      const transport = new Transport(new URL({ host: HOST, port: PORT }));
-      const client = new auth.Client(transport.unary, {
-        username: "synnax",
-        password: "seldon",
-      });
+      const transport = new Transport(
+        new URL({
+          host: TEST_CLIENT_PROPS.host,
+          port: Number(TEST_CLIENT_PROPS.port),
+        }),
+      );
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(
         transport.unary,
@@ -51,11 +55,13 @@ describe("connectivity", () => {
       expect(state.clientVersion).toBe(__VERSION__);
     });
     it("should adjust state if the server is too old", async () => {
-      const transport = new Transport(new URL({ host: HOST, port: PORT }));
-      const client = new auth.Client(transport.unary, {
-        username: "synnax",
-        password: "seldon",
-      });
+      const transport = new Transport(
+        new URL({
+          host: TEST_CLIENT_PROPS.host,
+          port: Number(TEST_CLIENT_PROPS.port),
+        }),
+      );
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(
         transport.unary,
@@ -67,11 +73,13 @@ describe("connectivity", () => {
       expect(state.clientVersion).toBe("50000.0.0");
     });
     it("should adjust state if the server is too new", async () => {
-      const transport = new Transport(new URL({ host: HOST, port: PORT }));
-      const client = new auth.Client(transport.unary, {
-        username: "synnax",
-        password: "seldon",
-      });
+      const transport = new Transport(
+        new URL({
+          host: TEST_CLIENT_PROPS.host,
+          port: Number(TEST_CLIENT_PROPS.port),
+        }),
+      );
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(transport.unary, undefined, "0.0.0");
       const state = await connectivity.check();

package/src/control/client.ts

@@ -10,7 +10,7 @@
 import { StateTracker } from "@/control/state";
 import { framer } from "@/framer";
 
-const CONTROL_STATE_KEY = "sy_node_1_control";
+export const CONTROL_STATE_CHANNEL_NAME = "sy_node_1_control";
 
 export class Client {
   private readonly framer: framer.Client;
@@ -22,7 +22,7 @@ export class Client {
   async openStateTracker(): Promise<StateTracker> {
     const stream = await framer.HardenedStreamer.open(
       async (p) => await this.framer.openStreamer(p),
-      CONTROL_STATE_KEY,
+      CONTROL_STATE_CHANNEL_NAME,
     );
     return new StateTracker(stream);
   }

package/src/control/state.spec.ts

@@ -9,14 +9,14 @@
 
 import { describe, expect, it } from "vitest";
 
-import { newClient } from "@/setupspecs";
+import { newTestClient } from "@/testutil/client";
 
-const client = newClient();
+const client = newTestClient();
 
 describe("state", () => {
   it("should receive the initial control state from the cluster", async () => {
     const s = await client.control.openStateTracker();
-    await expect.poll(() => s.states.size > 0).toBeTruthy();
+    await expect.poll(() => s.states.size > 0).toBe(true);
     await s.close();
   });
 });

package/src/control/state.ts

@@ -10,7 +10,7 @@
 import { control } from "@synnaxlabs/x";
 import { binary } from "@synnaxlabs/x/binary";
 import { type observe } from "@synnaxlabs/x/observe";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { type channel } from "@/channel";
 import { keyZ } from "@/channel/payload";

package/src/errors.spec.ts

@@ -14,23 +14,27 @@ import {
   AuthError,
   ContiguityError,
   ControlError,
-  FieldError,
   InvalidTokenError,
   MultipleFoundError,
   NotFoundError,
+  PathError,
   QueryError,
   RouteError,
   UnauthorizedError,
   UnexpectedError,
   ValidationError,
 } from "@/errors";
-import { newClient } from "@/setupspecs";
+import { newTestClient } from "@/testutil/client";
 
 describe("error", () => {
   describe("type matching", () => {
     const ERRORS: [string, Error, errors.Matchable][] = [
       [ValidationError.TYPE, new ValidationError(), ValidationError],
-      [FieldError.TYPE, new FieldError("field", "message"), FieldError],
+      [
+        PathError.TYPE,
+        new PathError("field", new ValidationError("message")),
+        PathError,
+      ],
       [AuthError.TYPE, new AuthError(), AuthError],
       [InvalidTokenError.TYPE, new InvalidTokenError(), InvalidTokenError],
       [UnexpectedError.TYPE, new UnexpectedError("message"), UnexpectedError],
@@ -44,13 +48,13 @@ describe("error", () => {
     ];
     ERRORS.forEach(([typeName, error, type]) =>
       test(`matches ${typeName}`, () => {
-        expect(type.matches(error)).toBeTruthy();
+        expect(type.matches(error)).toBe(true);
       }),
     );
   });
 });
 
-const client = newClient();
+const client = newTestClient();
 
 test("client", async () => {
   expect.assertions(2);