@synnaxlabs/client 0.43.0 → 0.44.1

package/src/framer/writer.ts

@@ -8,14 +8,9 @@
 // included in the file licenses/APL.txt.
 
 import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
-import { array, control, errors } from "@synnaxlabs/x";
-import {
-  type CrudeSeries,
-  type CrudeTimeStamp,
-  TimeSpan,
-  TimeStamp,
-} from "@synnaxlabs/x/telem";
-import { z } from "zod/v4";
+import { control, errors } from "@synnaxlabs/x";
+import { type CrudeSeries, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
+import { z } from "zod";
 
 import { channel } from "@/channel";
 import { SynnaxError } from "@/errors";
@@ -36,22 +31,6 @@ export enum WriterMode {
   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:
-      if (typeof mode === "number" && mode in WriterMode) return mode;
-      throw new Error(`invalid writer mode: ${mode}`);
-  }
-};
-
 export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
 
 export class WriterClosedError extends SynnaxError.sub("writer_closed") {
@@ -60,27 +39,75 @@ export class WriterClosedError extends SynnaxError.sub("writer_closed") {
   }
 }
 
-const netConfigZ = z.object({
+const writerModeZ = z.enum(WriterMode).or(
+  z.enum(["persist", "stream", "persistStream"]).transform((mode) => {
+    switch (mode) {
+      case "persist":
+        return WriterMode.Persist;
+      case "stream":
+        return WriterMode.Stream;
+      case "persistStream":
+        return WriterMode.PersistStream;
+    }
+  }),
+);
+
+export type CrudeWriterMode = z.input<typeof writerModeZ>;
+
+const baseWriterConfigZ = z.object({
+  // start sets the starting timestamp for the first sample in the writer.
   start: TimeStamp.z.optional(),
+  // controlSubject sets the control subject of the writer.
   controlSubject: control.subjectZ.optional(),
+  // authorities set the control authority to set for each channel on the writer.
+  // Defaults to absolute authority. If not working with concurrent control,
+  // it's best to leave this as the default.
+  authorities: z
+    .union([control.authorityZ.transform((a) => [a]), control.authorityZ.array()])
+    .default([control.ABSOLUTE_AUTHORITY]),
+  // mode sets the persistence and streaming mode of the writer. The default
+  // mode is WriterModePersistStream.
+  mode: writerModeZ.default(WriterMode.PersistStream),
+  // errOnUnauthorized sets whether the writer raises an error when it attempts to write
+  // to a channel without permission.
+  errOnUnauthorized: z.boolean().default(false),
+  // 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.
+  enableAutoCommit: z.boolean().default(false),
+  // autoIndexPersistInterval sets the interval at which commits to the index will be
+  autoIndexPersistInterval: TimeSpan.z.default(TimeSpan.SECOND),
+  // useExperimentalCodec sets whether the writer will use the experimental codec.
+  useExperimentalCodec: z.boolean().default(false),
+});
+
+const netWriterConfigZ = baseWriterConfigZ.extend({
   keys: channel.keyZ.array().optional(),
-  authorities: control.authorityZ.array().optional(),
-  mode: z.enum(WriterMode).optional(),
-  errOnUnauthorized: z.boolean().optional(),
-  enableAutoCommit: z.boolean().optional(),
-  autoIndexPersistInterval: TimeSpan.z.optional(),
 });
 
-interface Config extends z.infer<typeof netConfigZ> {}
+export type NetWriterConfig = z.input<typeof netWriterConfigZ>;
+
+// Intermediate utility type to allow for the use of paramsZ in the writer config.
+const intermediateWriterConfigZ = baseWriterConfigZ.extend({
+  channels: channel.paramsZ,
+});
+
+export const writerConfigZ = intermediateWriterConfigZ.or(
+  channel.paramsZ.transform((channels) =>
+    intermediateWriterConfigZ.parse({ channels, start: TimeStamp.now() }),
+  ),
+);
+
+export type WriterConfig = z.input<typeof writerConfigZ>;
 
 const reqZ = z.object({
   command: z.enum(WriterCommand),
-  config: netConfigZ.optional(),
+  config: netWriterConfigZ.optional(),
   frame: frameZ.optional(),
   buffer: z.instanceof(Uint8Array).optional(),
 });
 
-export interface WriteRequest extends z.infer<typeof reqZ> {}
+export interface WriteRequest extends z.input<typeof reqZ> {}
 
 const resZ = z.object({
   command: z.enum(WriterCommand),
@@ -88,35 +115,32 @@ const resZ = z.object({
   err: errors.payloadZ.optional(),
 });
 
-interface Response extends z.infer<typeof resZ> {}
+const authorityArgsZ = z
+  .tuple([
+    z.union([
+      z.record(channel.keyZ.or(channel.nameZ), control.authorityZ),
+      channel.keyZ.or(channel.nameZ),
+      control.authorityZ,
+    ]),
+    control.authorityZ.optional(),
+  ])
+  .transform(([value, authority]) => {
+    if (control.authorityZ.safeParse(value).success)
+      return { keys: [], authorities: [value as control.Authority] };
+    if (channel.keyZ.or(channel.nameZ).safeParse(value).success) {
+      if (authority == null)
+        throw new Error(
+          "authority is required when setting authority for a single channel",
+        );
+      return { keys: [value] as channel.KeysOrNames, authorities: [authority] };
+    }
+    const oValue = value as Record<channel.KeyOrName, control.Authority>;
+    return { keys: Object.keys(oValue), authorities: Object.values(oValue) };
+  });
 
-export interface WriterConfig {
-  // channels denote the channels to write to.
-  channels: channel.Params;
-  // start sets the starting timestamp for the first sample in the writer.
-  start?: CrudeTimeStamp;
-  // controlSubject sets the control subject of the writer.
-  controlSubject?: control.Subject;
-  // authorities set the control authority to set for each channel on the writer.
-  // Defaults to absolute authority. If not working with concurrent control,
-  // it's best to leave this as the default.
-  authorities?: control.Authority | control.Authority[];
-  // mode sets the persistence and streaming mode of the writer. The default
-  // mode is WriterModePersistStream.
-  mode?: CrudeWriterMode;
-  // errOnUnauthorized sets whether the writer raises an error when it attempts to write
-  // to a channel without permission.
-  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.
-  enableAutoCommit?: boolean;
-  // autoIndexPersistInterval sets the interval at which commits to the index will be
-  // persisted. To persist every commit to guarantee minimal loss of data, set
-  // auto_index_persist_interval to AlwaysAutoIndexPersist.
-  autoIndexPersistInterval?: TimeSpan;
-  useExperimentalCodec?: boolean;
-}
+export type AuthorityArgs = z.input<typeof authorityArgsZ>;
+
+interface Response extends z.infer<typeof resZ> {}
 
 /**
  * Writer is used to write telemetry to a set of channels in time order.
@@ -170,35 +194,17 @@ export class Writer {
   static async _open(
     retriever: channel.Retriever,
     client: WebSocketClient,
-    {
-      channels,
-      start = TimeStamp.now(),
-      authorities = control.ABSOLUTE_AUTHORITY,
-      controlSubject: subject,
-      mode = WriterMode.PersistStream,
-      errOnUnauthorized = false,
-      enableAutoCommit = false,
-      autoIndexPersistInterval = TimeSpan.SECOND,
-      useExperimentalCodec = true,
-    }: WriterConfig,
+    config: WriterConfig,
   ): Promise<Writer> {
-    const adapter = await WriteAdapter.open(retriever, channels);
-    if (useExperimentalCodec)
+    const cfg = writerConfigZ.parse(config);
+    const adapter = await WriteAdapter.open(retriever, cfg.channels);
+    if (cfg.useExperimentalCodec)
       client = client.withCodec(new WSWriterCodec(adapter.codec));
     const stream = await client.stream(Writer.ENDPOINT, reqZ, resZ);
     const writer = new Writer(stream, adapter);
     await writer.execute({
       command: WriterCommand.Open,
-      config: {
-        start: new TimeStamp(start),
-        keys: adapter.keys,
-        controlSubject: subject,
-        authorities: array.toArray(authorities),
-        mode: constructWriterMode(mode),
-        errOnUnauthorized,
-        enableAutoCommit,
-        autoIndexPersistInterval,
-      },
+      config: { ...cfg, keys: adapter.keys },
     });
     return writer;
   }
@@ -243,36 +249,16 @@ export class Writer {
     this.stream.send({ command: WriterCommand.Write, frame: frame.toPayload() });
   }
 
-  async setAuthority(value: number): Promise<void>;
-
   async setAuthority(
-    key: channel.KeyOrName,
-    authority: control.Authority,
-  ): Promise<void>;
-
-  async setAuthority(
-    value: Record<channel.KeyOrName, control.Authority>,
-  ): Promise<void>;
-
-  async setAuthority(
-    value: Record<channel.KeyOrName, control.Authority> | channel.KeyOrName | number,
-    authority?: control.Authority,
+    value: AuthorityArgs[0],
+    authority?: AuthorityArgs[1],
   ): Promise<void> {
     if (this.closeErr != null) throw this.closeErr;
-    let config: Config;
-    if (typeof value === "number" && authority == null)
-      config = { keys: [], authorities: [value] };
-    else {
-      let oValue: Record<channel.KeyOrName, control.Authority>;
-      if (typeof value === "string" || typeof value === "number")
-        oValue = { [value]: authority } as Record<channel.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 parsed = authorityArgsZ.parse([value, authority]);
+    const config = {
+      keys: await this.adapter.adaptParams(parsed.keys),
+      authorities: parsed.authorities,
+    };
     await this.execute({ command: WriterCommand.SetAuthority, config });
   }
 

package/src/hardware/device/client.ts

@@ -8,11 +8,9 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { array, type UnknownRecord } from "@synnaxlabs/x";
-import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
-import { z } from "zod/v4";
+import { array, type record } from "@synnaxlabs/x";
+import { z } from "zod";
 
-import { framer } from "@/framer";
 import {
   type Device,
   deviceZ,
@@ -20,150 +18,109 @@ import {
   keyZ,
   type New,
   newZ,
-  ONTOLOGY_TYPE,
-  type State,
-  stateZ,
 } from "@/hardware/device/payload";
 import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
-import { ontology } from "@/ontology";
-import { signals } from "@/signals";
+import { type ontology } from "@/ontology";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
 
-const SET_CHANNEL_NAME = "sy_device_set";
-const DELETE_CHANNEL_NAME = "sy_device_delete";
-const STATE_CHANNEL_NAME = "sy_device_state";
+export const SET_CHANNEL_NAME = "sy_device_set";
+export const DELETE_CHANNEL_NAME = "sy_device_delete";
+export const STATUS_CHANNEL_NAME = "sy_device_status";
 
 const RETRIEVE_ENDPOINT = "/hardware/device/retrieve";
 const CREATE_ENDPOINT = "/hardware/device/create";
 const DELETE_ENDPOINT = "/hardware/device/delete";
 
 const createReqZ = z.object({ devices: newZ.array() });
-
 const createResZ = z.object({ devices: deviceZ.array() });
 
 const deleteReqZ = z.object({ keys: keyZ.array() });
-
 const deleteResZ = z.object({});
 
-const retrieveReqZ = z.object({
+const retrieveRequestZ = z.object({
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   makes: z.string().array().optional(),
   models: z.string().array().optional(),
   locations: z.string().array().optional(),
   racks: rackKeyZ.array().optional(),
-  search: z.string().optional(),
+  searchTerm: z.string().optional(),
   limit: z.number().optional(),
   offset: z.number().optional(),
-  ignoreNotFound: z.boolean().optional(),
-  includeState: z.boolean().optional(),
+  includeStatus: z.boolean().optional(),
 });
+const retrieveResZ = z.object({ devices: nullableArrayZ(deviceZ) });
 
-interface RetrieveRequest extends z.input<typeof retrieveReqZ> {}
+const singleRetrieveArgsZ = z
+  .object({
+    key: keyZ,
+    includeStatus: z.boolean().optional(),
+  })
+  .transform(({ key, includeStatus }) => ({
+    keys: [key],
+    includeStatus,
+  }));
 
-export interface RetrieveOptions
-  extends Pick<
-    RetrieveRequest,
-    "limit" | "offset" | "makes" | "ignoreNotFound" | "includeState"
-  > {}
+export type SingleRetrieveArgs = z.input<typeof singleRetrieveArgsZ>;
+export type MultiRetrieveArgs = z.input<typeof retrieveRequestZ>;
 
-interface PageOptions extends Pick<RetrieveOptions, "makes"> {}
+const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveRequestZ]);
 
-const retrieveResZ = z.object({ devices: nullableArrayZ(deviceZ) });
+export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
 
-export class Client implements AsyncTermSearcher<string, Key, Device> {
-  readonly type = ONTOLOGY_TYPE;
+export class Client {
+  readonly type = "device";
   private readonly client: UnaryClient;
-  private readonly frameClient: framer.Client;
 
-  constructor(client: UnaryClient, frameClient: framer.Client) {
+  constructor(client: UnaryClient) {
     this.client = client;
-    this.frameClient = frameClient;
   }
 
   async retrieve<
-    Properties extends UnknownRecord = UnknownRecord,
+    Properties extends record.Unknown = record.Unknown,
     Make extends string = string,
     Model extends string = string,
-    StateDetails extends {} = UnknownRecord,
-  >(
-    key: string,
-    options?: RetrieveOptions,
-  ): Promise<Device<Properties, Make, Model, StateDetails>>;
+  >(args: SingleRetrieveArgs): Promise<Device<Properties, Make, Model>>;
 
   async retrieve<
-    Properties extends UnknownRecord = UnknownRecord,
+    Properties extends record.Unknown = record.Unknown,
     Make extends string = string,
     Model extends string = string,
-    StateDetails extends {} = UnknownRecord,
-  >(
-    keys: string[],
-    options?: RetrieveOptions,
-  ): Promise<Array<Device<Properties, Make, Model, StateDetails>>>;
+  >(args: MultiRetrieveArgs): Promise<Array<Device<Properties, Make, Model>>>;
 
   async retrieve<
-    Properties extends UnknownRecord = UnknownRecord,
+    Properties extends record.Unknown = record.Unknown,
     Make extends string = string,
     Model extends string = string,
-    StateDetails extends {} = UnknownRecord,
   >(
-    keys: string | string[],
-    options?: RetrieveOptions,
-  ): Promise<
-    | Device<Properties, Make, Model, StateDetails>
-    | Array<Device<Properties, Make, Model, StateDetails>>
-  > {
-    const isSingle = !Array.isArray(keys);
+    args: RetrieveArgs,
+  ): Promise<Device<Properties, Make, Model> | Array<Device<Properties, Make, Model>>> {
+    const isSingle = typeof args === "object" && "key" in args;
     const res = await sendRequired(
       this.client,
       RETRIEVE_ENDPOINT,
-      { keys: array.toArray(keys), ...options },
-      retrieveReqZ,
+      args,
+      retrieveArgsZ,
       retrieveResZ,
     );
-    checkForMultipleOrNoResults("Device", keys, res.devices, isSingle);
-    return isSingle
-      ? (res.devices[0] as Device<Properties, Make, Model, StateDetails>)
-      : (res.devices as Array<Device<Properties, Make, Model, StateDetails>>);
-  }
-
-  async search(term: string, options?: RetrieveOptions): Promise<Device[]> {
-    return (
-      await sendRequired(
-        this.client,
-        RETRIEVE_ENDPOINT,
-        { search: term, ...options },
-        retrieveReqZ,
-        retrieveResZ,
-      )
-    ).devices;
-  }
-
-  async page(offset: number, limit: number, options?: PageOptions): Promise<Device[]> {
-    return (
-      await sendRequired(
-        this.client,
-        RETRIEVE_ENDPOINT,
-        { offset, limit, ...options },
-        retrieveReqZ,
-        retrieveResZ,
-      )
-    ).devices;
+    checkForMultipleOrNoResults("Device", args, res.devices, isSingle);
+    const devices = res.devices as Device<Properties, Make, Model>[];
+    return isSingle ? devices[0] : devices;
   }
 
   async create<
-    Properties extends UnknownRecord = UnknownRecord,
+    Properties extends record.Unknown = record.Unknown,
     Make extends string = string,
     Model extends string = string,
   >(device: New<Properties, Make>): Promise<Device<Properties, Make, Model>>;
   async create<
-    Properties extends UnknownRecord = UnknownRecord,
+    Properties extends record.Unknown = record.Unknown,
     Make extends string = string,
     Model extends string = string,
   >(devices: New<Properties, Make>[]): Promise<Device<Properties, Make, Model>[]>;
   async create<
-    Properties extends UnknownRecord = UnknownRecord,
+    Properties extends record.Unknown = record.Unknown,
     Make extends string = string,
     Model extends string = string,
   >(
@@ -177,9 +134,8 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
       createReqZ,
       createResZ,
     );
-    return isSingle
-      ? (res.devices[0] as Device<Properties, Make, Model>)
-      : (res.devices as Device<Properties, Make, Model>[]);
+    const created = res.devices as Device<Properties, Make, Model>[];
+    return isSingle ? created[0] : created;
   }
 
   async delete(keys: string | string[]): Promise<void> {
@@ -191,48 +147,6 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
       deleteResZ,
     );
   }
-
-  async openDeviceTracker(): Promise<signals.Observable<string, Device>> {
-    return await signals.openObservable<string, Device>(
-      this.frameClient,
-      SET_CHANNEL_NAME,
-      DELETE_CHANNEL_NAME,
-      decodeDeviceChanges,
-    );
-  }
-
-  async openStateObserver<Details extends {} = UnknownRecord>(): Promise<
-    framer.ObservableStreamer<State<Details>[]>
-  > {
-    return new framer.ObservableStreamer<State<Details>[]>(
-      await this.frameClient.openStreamer(STATE_CHANNEL_NAME),
-      (frame) => {
-        const s = frame.get(STATE_CHANNEL_NAME);
-        if (s.length === 0) return [null, false];
-        const states = s.parseJSON(stateZ);
-        return [states as State<Details>[], true];
-      },
-    );
-  }
-
-  newSearcherWithOptions(
-    options: RetrieveOptions,
-  ): AsyncTermSearcher<string, Key, Device> {
-    return {
-      type: this.type,
-      search: async (term: string) => await this.search(term, options),
-      retrieve: async (keys: string[]) => await this.retrieve(keys, options),
-      page: async (offset: number, limit: number) =>
-        await this.page(offset, limit, options),
-    };
-  }
 }
 
-const decodeDeviceChanges: signals.Decoder<string, Device> = (variant, data) => {
-  if (variant === "delete")
-    return data.toStrings().map((k) => ({ variant, key: k, value: undefined }));
-  return data.parseJSON(deviceZ).map((d) => ({ variant, key: d.key, value: d }));
-};
-
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key });
+export const ontologyID = (key: Key): ontology.ID => ({ type: "device", key });