@synnaxlabs/client 0.26.7 → 0.28.0

package/src/framer/frame.ts

@@ -39,17 +39,17 @@ const columnType = (columns: Params): ColumnType => {
   return "name";
 };
 
-const validateMatchedColsAndArrays = (columns: Params, arrays: Series[]): void => {
+const validateMatchedColsAndSeries = (columns: Params, series: Series[]): void => {
   const colsArr = toArray(columns);
-  if (colsArr.length === arrays.length) return;
+  if (colsArr.length === series.length) return;
   const colType = columnType(columns);
   if (columnType === null)
     throw new ValidationError(
       "[Frame] - channel keys or names must be provided when constructing a frame.",
     );
   throw new ValidationError(
-    `[Frame] - ${colType as string}s and arrays must be the same length.
-    Got ${colsArr.length} ${colType as string}s and ${arrays.length} arrays.`,
+    `[Frame] - ${colType as string}s and series must be the same length.
+    Got ${colsArr.length} ${colType as string}s and ${series.length} series.`,
   );
 };
 
@@ -65,15 +65,15 @@ export type CrudeFrame =
  *
  * Frames have two important characteristics: alignment and orientation.
  *
- * A frame's alignment defines how correlated the arrays for different channels in the
+ * A frame's alignment defines how correlated the series for different channels in the
  * frame are:
  *
- * - A frame is weakly aligned if it meets the time range occupied by all arrays of a
+ * - A frame is weakly aligned if the time range occupied by all series of a
  * particular channel is the same for all channels in the frame. This means that the
- * arrays for a particular channel can have gaps between them.
+ * series for a particular channel can have gaps between them.
  *
  * - A strongly aligned frame means that all channels share the same rate/index and
- * there are no gaps in time between arrays. Strongly aligned frames are natural
+ * there are no gaps in time between series. Strongly aligned frames are natural
  * to interpret, as the values in a particular 'row' of the frame share the same
  * timestamp. All frames written to Synnax must be strongly aligned.
  *
@@ -85,7 +85,7 @@ export type CrudeFrame =
  *
  * - Horizontal frames have a single channel, and are strongly aligned by default.
  * A horizontal frame typically has a single array (in which case, it's also 'square'),
- * although it can have multiple arrays if all the arrays are continuous in time.
+ * although it can have multiple series if all the series are continuous in time.
  *
  * - Vertical frames are strongly aligned and have on or more channels, but ONLY a single
  * array per channel. Synnax requires that all frames written to the database are
@@ -98,7 +98,7 @@ export class Frame {
   readonly columns: Keys | Names = [];
   readonly series: Series[] = [];
 
-  constructor(columnsOrData: Params | CrudeFrame = [], arrays: Series | Series[] = []) {
+  constructor(columnsOrData: Params | CrudeFrame = [], series: Series | Series[] = []) {
     if (columnsOrData instanceof Frame) {
       this.columns = columnsOrData.columns;
       this.series = columnsOrData.series;
@@ -117,9 +117,9 @@ export class Frame {
     if (isObject) {
       if ("keys" in columnsOrData && "series" in columnsOrData) {
         const data_ = columnsOrData as FramePayload;
-        const arrays = data_.series.map((a) => seriesFromPayload(a));
-        validateMatchedColsAndArrays(data_.keys, arrays);
-        data_.keys.forEach((key, i) => this.push(key, arrays[i]));
+        const series = data_.series.map((a) => seriesFromPayload(a));
+        validateMatchedColsAndSeries(data_.keys, series);
+        data_.keys.forEach((key, i) => this.push(key, series[i]));
       } else
         Object.entries(columnsOrData).forEach(([k, v]) => {
           const key = parseInt(k);
@@ -129,21 +129,21 @@ export class Frame {
       return;
     }
 
-    // Construction from a set of arrays and columns.
+    // Construction from a set of series and columns.
     if (
       Array.isArray(columnsOrData) ||
       ["string", "number"].includes(typeof columnsOrData)
     ) {
-      const data_ = toArray(arrays);
+      const data_ = toArray(series);
       const cols = toArray(columnsOrData) as Keys | Names;
-      validateMatchedColsAndArrays(cols, data_);
+      validateMatchedColsAndSeries(cols, data_);
       data_.forEach((d, i) => this.push(cols[i], d));
       return;
     }
 
     throw new ValidationError(
       `[Frame] - invalid frame construction parameters. data parameter ust be a frame
-    payload, a list of lazy arrays, a lazy array, a map, or a record keyed by channel
+    payload, a list of lazy series, a lazy array, a map, or a record keyed by channel
     name. keys parameter must be a set of channel keys or channel names.`,
     );
   }
@@ -218,8 +218,8 @@ export class Frame {
   /**
    * @returns true if the frame is horizontal. Horizontal frames have a single channel,
    * and are strongly aligned by default.A horizontal frame typically has a single array
-   * (in which case, it's also 'square'), although it can have multiple arrays if all
-   * the arrays are continuous in time.
+   * (in which case, it's also 'square'), although it can have multiple series if all
+   * the series are continuous in time.
    */
   get isHorizontal(): boolean {
     return this.uniqueColumns.length === 1;
@@ -235,8 +235,8 @@ export class Frame {
 
   /**
    * @returns true if the frame is weakly aligned. A frame is weakly aligned if it meets
-   * the time range occupied by all arrays of a particular channel is the same for all
-   * channels in the frame. This means that the arrays for a particular channel can have
+   * the time range occupied by all series of a particular channel is the same for all
+   * channels in the frame. This means that the series for a particular channel can have
    * gaps between them.
    */
   get isWeaklyAligned(): boolean {
@@ -266,7 +266,7 @@ export class Frame {
   }
 
   /**
-   * @returns lazy arrays matching the given channel key or name.
+   * @returns lazy series matching the given channel key or name.
    * @param key the channel key or name.
    */
   get(key: KeyOrName): MultiSeries;

package/src/framer/writer.ts

@@ -54,7 +54,8 @@ const constructWriterMode = (mode: CrudeWriterMode): WriterMode => {
     case "persistStream":
       return WriterMode.PersistStream;
     default:
-      return mode;
+      if (typeof mode === "number" && mode in WriterMode) return mode;
+      throw new Error(`invalid writer mode: ${mode}`);
   }
 };
 

package/src/hardware/device/payload.ts

@@ -1,3 +1,12 @@
+// 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 { binary, UnknownRecord } from "@synnaxlabs/x";
 import { z } from "zod";
 

package/src/hardware/rack/payload.ts

@@ -1,3 +1,12 @@
+// 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 { z } from "zod";
 
 import { ontology } from "@/ontology";

package/src/hardware/task/client.ts

@@ -18,7 +18,19 @@ import { z } from "zod";
 import { framer } from "@/framer";
 import { type Frame } from "@/framer/frame";
 import { rack } from "@/hardware/rack";
-import { NewTask, newTaskZ, Payload, State, StateObservable, stateZ, TaskKey, taskKeyZ, taskZ } from "@/hardware/task/payload";
+import {
+  NewTask,
+  newTaskZ,
+  Payload,
+  State,
+  StateObservable,
+  stateZ,
+  TaskKey,
+  taskKeyZ,
+  taskZ,
+} from "@/hardware/task/payload";
+import { ontology } from "@/ontology";
+import { ranger } from "@/ranger";
 import { signals } from "@/signals";
 import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
@@ -26,6 +38,8 @@ import { nullableArrayZ } from "@/util/zod";
 const TASK_STATE_CHANNEL = "sy_task_state";
 const TASK_CMD_CHANNEL = "sy_task_cmd";
 
+const TASK_NOT_CREATED = new Error("Task not created");
+
 export class Task<
   C extends UnknownRecord = UnknownRecord,
   D extends {} = UnknownRecord,
@@ -36,25 +50,34 @@ export class Task<
   readonly internal: boolean;
   readonly type: T;
   readonly config: C;
+  readonly snapshot: boolean;
   state?: State<D>;
-  private readonly frameClient: framer.Client;
+  private readonly frameClient: framer.Client | null;
+  private readonly ontologyClient: ontology.Client | null;
+  private readonly rangeClient: ranger.Client | null;
 
   constructor(
     key: TaskKey,
     name: string,
     type: T,
     config: C,
-    frameClient: framer.Client,
     internal: boolean = false,
+    snapshot: boolean = false,
     state?: State<D> | null,
+    frameClient: framer.Client | null = null,
+    ontologyClient: ontology.Client | null = null,
+    rangeClient: ranger.Client | null = null,
   ) {
     this.key = key;
     this.name = name;
     this.type = type;
     this.config = config;
     this.internal = internal;
+    this.snapshot = snapshot;
     if (state !== null) this.state = state;
     this.frameClient = frameClient;
+    this.ontologyClient = ontologyClient;
+    this.rangeClient = rangeClient;
   }
 
   get payload(): Payload<C, D> {
@@ -68,7 +91,12 @@ export class Task<
     };
   }
 
+  get ontologyID(): ontology.ID {
+    return new ontology.ID({ type: "task", key: this.key });
+  }
+
   async executeCommand(type: string, args?: UnknownRecord): Promise<string> {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
     const writer = await this.frameClient.openWriter(TASK_CMD_CHANNEL);
     const key = id.id();
     await writer.write(TASK_CMD_CHANNEL, [{ task: this.key, type, key, args }]);
@@ -81,6 +109,7 @@ export class Task<
     args: UnknownRecord,
     timeout: CrudeTimeSpan,
   ): Promise<State<D>> {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
     const streamer = await this.frameClient.openStreamer(TASK_STATE_CHANNEL);
     const cmdKey = await this.executeCommand(type, args);
     let res: State<D>;
@@ -105,6 +134,7 @@ export class Task<
   async openStateObserver<D extends UnknownRecord = UnknownRecord>(): Promise<
     StateObservable<D>
   > {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
     return new framer.ObservableStreamer<State<D>>(
       await this.frameClient.openStreamer(TASK_STATE_CHANNEL),
       (frame) => {
@@ -118,6 +148,14 @@ export class Task<
       },
     );
   }
+
+  async snapshottedTo(): Promise<ontology.Resource | null> {
+    if (this.ontologyClient == null || this.rangeClient == null) throw TASK_NOT_CREATED;
+    if (!this.snapshot) return null;
+    const parents = await this.ontologyClient.retrieveParents(this.ontologyID);
+    if (parents.length == 0) return null;
+    return parents[0];
+  }
 }
 
 const retrieveReqZ = z.object({
@@ -143,20 +181,36 @@ export type RetrieveOptions = Pick<
 const RETRIEVE_ENDPOINT = "/hardware/task/retrieve";
 const CREATE_ENDPOINT = "/hardware/task/create";
 const DELETE_ENDPOINT = "/hardware/task/delete";
+const COPY_ENDPOINT = "/hardware/task/copy";
 
 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({});
+const copyReqZ = z.object({
+  key: taskKeyZ,
+  name: z.string(),
+  snapshot: z.boolean(),
+});
+const copyResZ = z.object({ task: taskZ });
 
 export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
   readonly type: string = "task";
   private readonly client: UnaryClient;
   private readonly frameClient: framer.Client;
+  private readonly ontologyClient: ontology.Client;
+  private readonly rangeClient: ranger.Client;
 
-  constructor(client: UnaryClient, frameClient: framer.Client) {
+  constructor(
+    client: UnaryClient,
+    frameClient: framer.Client,
+    ontologyClient: ontology.Client,
+    rangeClient: ranger.Client,
+  ) {
     this.client = client;
     this.frameClient = frameClient;
+    this.ontologyClient = ontologyClient;
+    this.rangeClient = rangeClient;
   }
 
   async create<
@@ -251,6 +305,17 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
     return single && variant !== "rack" ? sugared[0] : sugared;
   }
 
+  async copy(key: string, name: string, snapshot: boolean): Promise<Task> {
+    const res = await sendRequired(
+      this.client,
+      COPY_ENDPOINT,
+      { key, name, snapshot },
+      copyReqZ,
+      copyResZ,
+    );
+    return this.sugar([res.task])[0];
+  }
+
   async retrieveByName(name: string, rack?: number): Promise<Task> {
     const tasks = await this.execRetrieve({ names: [name], rack });
     checkForMultipleOrNoResults("Task", name, tasks, true);
@@ -270,8 +335,19 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
 
   private sugar(payloads: Payload[]): Task[] {
     return payloads.map(
-      ({ key, name, type, config, state, internal }) =>
-        new Task(key, name, type, config, this.frameClient, internal, state),
+      ({ key, name, type, config, state, internal, snapshot }) =>
+        new Task(
+          key,
+          name,
+          type,
+          config,
+          internal,
+          snapshot,
+          state,
+          this.frameClient,
+          this.ontologyClient,
+          this.rangeClient,
+        ),
     );
   }