@synnaxlabs/client 0.34.0 → 0.36.0

package/src/hardware/task/client.ts

@@ -19,6 +19,9 @@ import { framer } from "@/framer";
 import { type Frame } from "@/framer/frame";
 import { rack } from "@/hardware/rack";
 import {
+  type Command,
+  type CommandObservable,
+  commandZ,
   type NewTask,
   newTaskZ,
   type Payload,
@@ -46,7 +49,7 @@ export class Task<
   T extends string = string,
 > {
   readonly key: TaskKey;
-  readonly name: string;
+  name: string;
   readonly internal: boolean;
   readonly type: T;
   config: C;
@@ -139,7 +142,10 @@ export class Task<
         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];
+        if (!parse.success) {
+          console.error(parse.error);
+          return [null, false];
+        }
         const state = parse.data as State<D>;
         if (state.task !== this.key) return [null, false];
         return [state, true];
@@ -147,6 +153,27 @@ export class Task<
     );
   }
 
+  async openCommandObserver<A extends UnknownRecord = UnknownRecord>(): Promise<
+    CommandObservable<A>
+  > {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
+    return new framer.ObservableStreamer<Command<A>>(
+      await this.frameClient.openStreamer(TASK_CMD_CHANNEL),
+      (frame) => {
+        const s = frame.get(TASK_CMD_CHANNEL);
+        if (s.length === 0) return [null, false];
+        const parse = commandZ.safeParse(s.at(-1));
+        if (!parse.success) {
+          console.error(parse.error);
+          return [null, false];
+        }
+        const cmd = parse.data as Command<A>;
+        if (cmd.task !== this.key) return [null, false];
+        return [cmd, true];
+      },
+    );
+  }
+
   async snapshottedTo(): Promise<ontology.Resource | null> {
     if (this.ontologyClient == null || this.rangeClient == null) throw TASK_NOT_CREATED;
     if (!this.snapshot) return null;
@@ -376,9 +403,30 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
         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];
+        if (!parse.success) {
+          console.error(parse.error);
+          return [null, false];
+        }
         return [parse.data as State<D>, true];
       },
     );
   }
+
+  async openCommandObserver<A extends UnknownRecord = UnknownRecord>(): Promise<
+    CommandObservable<A>
+  > {
+    return new framer.ObservableStreamer<Command<A>>(
+      await this.frameClient.openStreamer(TASK_CMD_CHANNEL),
+      (frame) => {
+        const s = frame.get(TASK_CMD_CHANNEL);
+        if (s.length === 0) return [null, false];
+        const parse = commandZ.safeParse(s.at(-1));
+        if (!parse.success) {
+          console.error(parse.error);
+          return [null, false];
+        }
+        return [parse.data as Command<A>, true];
+      },
+    );
+  }
 }

package/src/hardware/task/payload.ts

@@ -85,17 +85,32 @@ 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>,
+  args: z
+    .record(z.unknown())
+    .or(
+      z.string().transform((c) => {
+        if (c === "") return {};
+        return JSON.parse(c);
+      }),
+    )
+    .or(z.array(z.unknown()))
+    .or(z.null())
+    .optional() as z.ZodOptional<z.ZodType<UnknownRecord>>,
 });
 
+export type Command<A extends {} = UnknownRecord> = Omit<
+  z.infer<typeof commandZ>,
+  "args"
+> & {
+  args?: A;
+};
+
 export type StateObservable<D extends UnknownRecord = UnknownRecord> =
   observe.ObservableAsyncCloseable<State<D>>;
 
+export type CommandObservable<A extends UnknownRecord = UnknownRecord> =
+  observe.ObservableAsyncCloseable<Command<A>>;
+
 export const ONTOLOGY_TYPE: ontology.ResourceType = "task";
 
 export const ontologyID = (key: TaskKey): ontology.ID =>

package/src/index.ts

@@ -32,6 +32,7 @@ export { rack } from "@/hardware/rack";
 export { task } from "@/hardware/task";
 export { label } from "@/label";
 export { ontology } from "@/ontology";
+export { group } from "@/ontology/group";
 export { ranger } from "@/ranger";
 export { signals } from "@/signals";
 export { user } from "@/user";
@@ -39,6 +40,7 @@ export { workspace } from "@/workspace";
 export { linePlot } from "@/workspace/lineplot";
 export { log } from "@/workspace/log";
 export { schematic } from "@/workspace/schematic";
+export { table } from "@/workspace/table";
 export {
   type CrudeDataType,
   type CrudeDensity,

package/src/ontology/group/payload.ts

@@ -9,6 +9,7 @@
 
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
+import { ontology } from "@/ontology";
 
 export const keyZ = z.string().uuid();
 export type Key = z.infer<typeof keyZ>;
@@ -17,10 +18,7 @@ export type Keys = Key[];
 export type Names = Name[];
 export type Params = Key | Name | Keys | Names;
 
-export const groupZ = z.object({
-  key: keyZ,
-  name: z.string(),
-});
+export const groupZ = z.object({ key: keyZ, name: z.string() });
 
 export type Payload = z.infer<typeof groupZ>;
 
@@ -52,9 +50,7 @@ export type ParamAnalysisResult =
 
 export const analyzeParams = (groups: Params): ParamAnalysisResult => {
   const normal = toArray(groups) as Keys | Names;
-  if (normal.length === 0) 
-    throw new Error("No groups specified");
-  
+  if (normal.length === 0) throw new Error("No groups specified");
   const isKey = keyZ.safeParse(normal[0]).success;
   return {
     single: !Array.isArray(groups),
@@ -63,3 +59,8 @@ export const analyzeParams = (groups: Params): ParamAnalysisResult => {
     actual: groups,
   } as const as ParamAnalysisResult;
 };
+
+export const ONTOLOGY_TYPE: ontology.ResourceType = "group";
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: ONTOLOGY_TYPE, key });

package/src/ontology/payload.ts

@@ -37,6 +37,7 @@ export const resourceTypeZ = z.union([
   z.literal("device"),
   z.literal("task"),
   z.literal("policy"),
+  z.literal("table"),
 ]);
 export type ResourceType = z.infer<typeof resourceTypeZ>;
 

package/src/ranger/client.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { type CrudeTimeRange, observe, TimeRange } from "@synnaxlabs/x";
+import { type CrudeTimeRange, observe, sortTimeRange, TimeRange } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { type Series } from "@synnaxlabs/x/telem";
 import { toArray } from "@synnaxlabs/x/toArray";
@@ -192,6 +192,9 @@ export class Range {
   }
 }
 
+export const sort = (a: Range, b: Range): -1 | 0 | 1 =>
+  sortTimeRange(a.timeRange, b.timeRange);
+
 const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.array(z.string()).optional(),

package/src/transport.ts

@@ -12,8 +12,10 @@ import {
   type Middleware,
   type StreamClient,
   type UnaryClient,
+  unaryWithBreaker,
   WebSocketClient,
 } from "@synnaxlabs/freighter";
+import { breaker } from "@synnaxlabs/x";
 import { binary } from "@synnaxlabs/x/binary";
 import { type URL } from "@synnaxlabs/x/url";
 
@@ -25,12 +27,15 @@ export class Transport {
   readonly stream: StreamClient;
   readonly secure: boolean;
 
-  constructor(url: URL, secure: boolean = false) {
+  constructor(url: URL, breakerCfg: breaker.Config = {}, secure: boolean = false) {
     this.secure = secure;
     this.url = url.child(baseAPIEndpoint);
     const codec = new binary.JSONCodec();
-    this.unary = new HTTPClient(this.url, codec, this.secure);
-    this.stream = new WebSocketClient(this.url, codec, this.secure);
+    (this.unary = unaryWithBreaker(
+      new HTTPClient(this.url, codec, this.secure),
+      breakerCfg,
+    )),
+      (this.stream = new WebSocketClient(this.url, codec, this.secure));
   }
 
   use(...middleware: Middleware[]): void {

package/src/workspace/client.ts

@@ -1,80 +1,184 @@
-// Copyright 2024 Synnax Labs, Inc.
-//
-// Use of this software is governed by the Business Source License included in the file
-// licenses/BSL.txt.
-//
-// As of the Change Date specified in that file, in accordance with the Business Source
-// License, use of this software will be governed by the Apache License, Version 2.0,
-// included in the file licenses/APL.txt.
-
-import { type UnaryClient } from "@synnaxlabs/freighter";
-import { type UnknownRecord } from "@synnaxlabs/x/record";
-import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
-
+import { ontology } from "@/ontology";
+import { sendRequired, UnaryClient } from "@synnaxlabs/freighter";
+import { toArray, UnknownRecord } from "@synnaxlabs/x";
+import { unknownRecordZ } from "@synnaxlabs/x/record";
+import { z } from "zod";
+import { AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { linePlot } from "@/workspace/lineplot";
 import { log } from "@/workspace/log";
-import { type Key, type Workspace } from "@/workspace/payload";
-import { Retriever } from "@/workspace/retriever";
 import { schematic } from "@/workspace/schematic";
-import { type NewWorkspace, Writer } from "@/workspace/writer";
+import { table } from "@/workspace/table";
+import { nullableArrayZ } from "@/util/zod";
+
+export const keyZ = z.string().uuid();
+export type Key = z.infer<typeof keyZ>;
+export type Params = Key | Key[];
+
+// --- VERY IMPORTANT ---
+// Synnax's encoders (in the binary package inside x) automatically convert the case
+// of keys in objects to snake_case and back to camelCase when encoding and decoding
+// respectively. This is done to ensure that the keys are consistent across all
+// languages and platforms. Sometimes workspaces have keys that are uuids, which have
+// dashes, and those get messed up. So we just use regular JSON for workspaces.
+const parse = (s: string): UnknownRecord => JSON.parse(s) as UnknownRecord;
+
+export const workspaceZ = z.object({
+  key: z.string(),
+  name: z.string(),
+  layout: unknownRecordZ.or(z.string().transform((s) => parse(s) as UnknownRecord)),
+});
+
+export type Workspace = z.infer<typeof workspaceZ>;
+
+export const ONTOLOGY_TYPE: ontology.ResourceType = "workspace";
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: ONTOLOGY_TYPE, key });
+
+const RETRIEVE_ENDPOINT = "/workspace/retrieve";
+const CREATE_ENDPOINT = "/workspace/create";
+const RENAME_ENDPOINT = "/workspace/rename";
+const SET_LAYOUT_ENDPOINT = "/workspace/set-layout";
+const DELETE_ENDPOINT = "/workspace/delete";
+
+export const newWorkspaceZ = workspaceZ.partial({ key: true }).transform((p) => ({
+  ...p,
+  layout: JSON.stringify(p.layout),
+}));
+
+export const workspaceRemoteZ = workspaceZ.omit({ layout: true }).extend({
+  layout: z.string().transform((s) => parse(s) as UnknownRecord),
+});
+
+export type NewWorkspace = z.input<typeof newWorkspaceZ>;
+
+const retrieveReqZ = z.object({
+  keys: z.string().array().optional(),
+  search: z.string().optional(),
+  author: z.string().uuid().optional(),
+  offset: z.number().optional(),
+  limit: z.number().optional(),
+});
+const createReqZ = z.object({ workspaces: newWorkspaceZ.array() });
+const renameReqZ = z.object({ key: z.string(), name: z.string() });
+const setLayoutReqZ = z.object({ key: z.string(), layout: z.string() });
+const deleteReqZ = z.object({ keys: z.string().array() });
+
+const retrieveResZ = z.object({ workspaces: nullableArrayZ(workspaceZ) });
+const createResZ = z.object({ workspaces: workspaceRemoteZ.array() });
+const emptyResZ = z.object({});
 
 export class Client implements AsyncTermSearcher<string, Key, Workspace> {
   readonly type = "workspace";
   readonly schematic: schematic.Client;
   readonly linePlot: linePlot.Client;
   readonly log: log.Client;
-  private readonly retriever: Retriever;
-  private readonly writer: Writer;
+  readonly table: table.Client;
+  private readonly client: UnaryClient;
 
   constructor(client: UnaryClient) {
+    this.client = client;
     this.schematic = new schematic.Client(client);
     this.linePlot = new linePlot.Client(client);
-    this.retriever = new Retriever(client);
     this.log = new log.Client(client);
-    this.writer = new Writer(client);
+    this.table = new table.Client(client);
   }
 
-  async search(term: string): Promise<Workspace[]> {
-    return await this.retriever.search(term);
+  async create(workspace: NewWorkspace): Promise<Workspace>;
+  async create(workspaces: NewWorkspace[]): Promise<Workspace[]>;
+  async create(
+    workspaces: NewWorkspace | NewWorkspace[],
+  ): Promise<Workspace | Workspace[]> {
+    const isMany = Array.isArray(workspaces);
+    const normalized = toArray(workspaces);
+    const res = await sendRequired(
+      this.client,
+      CREATE_ENDPOINT,
+      { workspaces: normalized },
+      createReqZ,
+      createResZ,
+    );
+    return isMany ? res.workspaces : res.workspaces[0];
   }
 
-  async retrieveByAuthor(author: string): Promise<Workspace[]> {
-    return await this.retriever.retrieveByAuthor(author);
+  async rename(key: Key, name: string): Promise<void> {
+    await sendRequired(
+      this.client,
+      RENAME_ENDPOINT,
+      { key, name },
+      renameReqZ,
+      emptyResZ,
+    );
   }
 
-  async retrieve(key: Key): Promise<Workspace>;
+  async setLayout(key: Key, layout: UnknownRecord): Promise<void> {
+    await sendRequired(
+      this.client,
+      SET_LAYOUT_ENDPOINT,
+      { key, layout: JSON.stringify(layout) },
+      setLayoutReqZ,
+      emptyResZ,
+    );
+  }
 
+  async retrieve(key: Key): Promise<Workspace>;
   async retrieve(keys: Key[]): Promise<Workspace[]>;
-
-  async retrieve(keys: Key | Key[]): Promise<Workspace | Workspace[]> {
+  async retrieve(keys: Params): Promise<Workspace | Workspace[]> {
     const isMany = Array.isArray(keys);
-    const res = await this.retriever.retrieve(keys);
-    return isMany ? res : res[0];
+    const normalized = toArray(keys);
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { keys: normalized },
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return isMany ? res.workspaces : res.workspaces[0];
   }
 
-  async page(offset: number, limit: number): Promise<Workspace[]> {
-    return await this.retriever.page(offset, limit);
-  }
-
-  async create(workspace: NewWorkspace): Promise<Workspace>;
-
-  async create(
-    workspaces: NewWorkspace | NewWorkspace[],
-  ): Promise<Workspace | Workspace[]> {
-    const isMany = Array.isArray(workspaces);
-    const res = await this.writer.create(workspaces);
-    return isMany ? res : res[0];
+  async retrieveByAuthor(author: string): Promise<Workspace[]> {
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { author },
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return res.workspaces;
   }
 
-  async rename(key: Key, name: string): Promise<void> {
-    await this.writer.rename(key, name);
+  async search(term: string): Promise<Workspace[]> {
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { search: term },
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return res.workspaces;
   }
 
-  async setLayout(key: Key, layout: UnknownRecord): Promise<void> {
-    await this.writer.setLayout(key, layout);
+  async page(offset: number, limit: number): Promise<Workspace[]> {
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { offset, limit },
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return res.workspaces;
   }
 
-  async delete(...keys: Key[]): Promise<void> {
-    await this.writer.delete(keys);
+  async delete(key: Key): Promise<void>;
+  async delete(keys: Key[]): Promise<void>;
+  async delete(keys: Params): Promise<void> {
+    const normalized = toArray(keys);
+    await sendRequired(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: normalized },
+      deleteReqZ,
+      emptyResZ,
+    );
   }
 }

package/src/workspace/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 workspace from "@/workspace/external";
+export * as workspace from "@/workspace/client";

package/src/workspace/lineplot/client.ts

@@ -1,51 +1,119 @@
-// Copyright 2024 Synnax Labs, Inc.
-//
-// Use of this software is governed by the Business Source License included in the file
-// licenses/BSL.txt.
-//
-// As of the Change Date specified in that file, in accordance with the Business Source
-// License, use of this software will be governed by the Apache License, Version 2.0,
-// included in the file licenses/APL.txt.
-
-import { type UnaryClient } from "@synnaxlabs/freighter";
-import { type UnknownRecord } from "@synnaxlabs/x/record";
-
-import { type Key, type LinePlot, type Params } from "@/workspace/lineplot/payload";
-import { Retriever } from "@/workspace/lineplot/retriever";
-import { type NewLinePlot, Writer } from "@/workspace/lineplot/writer";
+import { ontology } from "@/ontology";
+import { nullableArrayZ } from "@/util/zod";
+import { sendRequired, UnaryClient } from "@synnaxlabs/freighter";
+import { breaker, TimeSpan, toArray, UnknownRecord } from "@synnaxlabs/x";
+import { unknownRecordZ } from "@synnaxlabs/x/record";
+import { z } from "zod";
+
+export const keyZ = z.string().uuid();
+export type Key = z.infer<typeof keyZ>;
+export type Params = Key | Key[];
+
+export const linePlotZ = z.object({
+  key: z.string(),
+  name: z.string(),
+  data: unknownRecordZ.or(z.string().transform((s) => JSON.parse(s) as UnknownRecord)),
+});
+
+export type LinePlot = z.infer<typeof linePlotZ>;
+
+export const ONTOLOGY_TYPE: ontology.ResourceType = "lineplot";
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: ONTOLOGY_TYPE, key });
+
+const RETRIEVE_ENDPOINT = "/workspace/lineplot/retrieve";
+const CREATE_ENDPOINT = "/workspace/lineplot/create";
+const RENAME_ENDPOINT = "/workspace/lineplot/rename";
+const SET_DATA_ENDPOINT = "/workspace/lineplot/set-data";
+const DELETE_ENDPOINT = "/workspace/lineplot/delete";
+
+export const newLinePlotZ = linePlotZ.partial({ key: true }).transform((p) => ({
+  ...p,
+  data: JSON.stringify(p.data),
+}));
+
+export type NewLinePlot = z.input<typeof newLinePlotZ>;
+
+const retrieveReqZ = z.object({ keys: keyZ.array() });
+const createReqZ = z.object({ workspace: z.string(), linePlots: newLinePlotZ.array() });
+const renameReqZ = z.object({ key: keyZ, name: z.string() });
+const setDataReqZ = z.object({ key: keyZ, data: z.string() });
+const deleteReqZ = z.object({ keys: keyZ.array() });
+const retrieveResZ = z.object({ linePlots: nullableArrayZ(linePlotZ) });
+const createResZ = z.object({ linePlots: linePlotZ.array() });
+const emptyResZ = z.object({});
 
 export class Client {
-  private readonly writer: Writer;
-  private readonly retriever: Retriever;
+  private readonly client: UnaryClient;
 
   constructor(client: UnaryClient) {
-    this.writer = new Writer(client);
-    this.retriever = new Retriever(client);
+    this.client = client;
   }
 
-  async create(workspace: string, linePlot: NewLinePlot): Promise<LinePlot> {
-    return await this.writer.create(workspace, linePlot);
+  async create(workspace: string, linePlot: NewLinePlot): Promise<LinePlot>;
+  async create(workspace: string, linePlots: NewLinePlot[]): Promise<LinePlot[]>;
+  async create(
+    workspace: string,
+    linePlots: NewLinePlot | NewLinePlot[],
+  ): Promise<LinePlot | LinePlot[]> {
+    const isMany = Array.isArray(linePlots);
+    const normalized = toArray(linePlots);
+    const res = await sendRequired(
+      this.client,
+      CREATE_ENDPOINT,
+      { workspace, linePlots: normalized },
+      createReqZ,
+      createResZ,
+    );
+    return isMany ? res.linePlots : res.linePlots[0];
   }
 
   async rename(key: Key, name: string): Promise<void> {
-    await this.writer.rename(key, name);
+    await sendRequired(
+      this.client,
+      RENAME_ENDPOINT,
+      { key, name },
+      renameReqZ,
+      emptyResZ,
+    );
   }
 
   async setData(key: Key, data: UnknownRecord): Promise<void> {
-    await this.writer.setData(key, data);
+    await sendRequired(
+      this.client,
+      SET_DATA_ENDPOINT,
+      { key, data: JSON.stringify(data) },
+      setDataReqZ,
+      emptyResZ,
+    );
   }
 
   async retrieve(key: Key): Promise<LinePlot>;
-
   async retrieve(keys: Key[]): Promise<LinePlot[]>;
-
   async retrieve(keys: Params): Promise<LinePlot | LinePlot[]> {
     const isMany = Array.isArray(keys);
-    const res = await this.retriever.retrieve(keys);
-    return isMany ? res : res[0];
+    const normalized = toArray(keys);
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { keys: normalized },
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    return isMany ? res.linePlots : res.linePlots[0];
   }
 
+  async delete(key: Key): Promise<void>;
+  async delete(keys: Key[]): Promise<void>;
   async delete(keys: Params): Promise<void> {
-    await this.writer.delete(keys);
+    const normalized = toArray(keys);
+    await sendRequired(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: normalized },
+      deleteReqZ,
+      emptyResZ,
+    );
   }
 }

package/src/workspace/lineplot/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 linePlot from "@/workspace/lineplot/external";
+export * as linePlot from "@/workspace/lineplot/client";