@synnaxlabs/client 0.15.2 → 0.16.3

package/src/channel/client.ts

@@ -7,6 +7,7 @@
 // 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 {
   DataType,
   Rate,
@@ -16,7 +17,7 @@ import {
   type TimeRange,
   type AsyncTermSearcher,
   toArray,
-  type CrudeTimeSpan,
+  type CrudeTimeStamp,
 } from "@synnaxlabs/x";
 
 import { type Creator } from "@/channel/creator";
@@ -28,24 +29,65 @@ import {
   payload,
   type NewPayload,
 } from "@/channel/payload";
-import { analyzeParams, type Retriever } from "@/channel/retriever";
-import { QueryError } from "@/errors";
+import {
+  analyzeParams,
+  CacheRetriever,
+  ClusterRetriever,
+  DebouncedBatchRetriever,
+  type Retriever,
+} from "@/channel/retriever";
+import { MultipleResultsError, NoResultsError, ValidationError } from "@/errors";
 import { type framer } from "@/framer";
 
 /**
- * Represents a Channel in a Synnax database. It should not be instantiated
- * directly, but rather created or retrieved from a {@link Client}.
+ * Represents a Channel in a Synnax database. Typically, channels should not be
+ * instantiated directly, but instead created via the `.channels.create` or retrieved
+ * via the `.channels.retrieve` method on a Synnax client.
+ *
+ * Please refer to the [Synnax documentation](https://docs.synnaxlabs.com) for detailed
+ * information on what channels are and how to use them.
  */
 export class Channel {
   private readonly _frameClient: framer.Client | null;
-  key: Key;
-  name: string;
-  rate: Rate;
-  dataType: DataType;
-  leaseholder: number;
-  index: Key;
-  isIndex: boolean;
-  alias: string | undefined;
+  /**
+   * A unique key identifying the channel in the Synnax database. This key is
+   * automatically assigned by Synnax.
+   */
+  readonly key: Key;
+  /**
+   * A human-readable name for the channel. This name is not guaranteed to be
+   * unique.
+   */
+  readonly name: string;
+  /**
+   * The rate at which the channel samples telemetry. This only applies to fixed rate
+   * channels, and will be 0 if the channel is indexed.
+   */
+  readonly rate: Rate;
+  /**
+   * The data type of the channel.
+   */
+  readonly dataType: DataType;
+  /**
+   * The key of the node in the Synnax cluster that holds the 'lease' over the channel
+   * i.e. it's the only node in the cluster allowed to accept writes to the channel. This
+   * property is mostly for internal use.
+   */
+  readonly leaseholder: number;
+  /**
+   * The key of the index channel that this channel is associated with i.e. the channel
+   * that stores its timestamps.
+   */
+  readonly index: Key;
+  /**
+   * This is set to true if the channel is an index channel, and false otherwise.
+   */
+  readonly isIndex: boolean;
+  /**
+   * An alias for the channel under a specific range. This parameter is unstable and
+   * should not be relied upon in the current version of Synnax.
+   */
+  readonly alias: string | undefined;
 
   constructor({
     dataType,
@@ -74,10 +116,15 @@ export class Channel {
 
   private get framer(): framer.Client {
     if (this._frameClient == null)
-      throw new Error("cannot read from a channel that has not been created");
+      throw new ValidationError("cannot read from a channel that has not been created");
     return this._frameClient;
   }
 
+  /**
+   * Returns the payload representation of this channel i.e. a pure JS object with
+   * all of the channel fields but without any methods. This is used internally for
+   * network transportation, but also provided to you as a convenience.
+   */
   get payload(): Payload {
     return payload.parse({
       key: this.key,
@@ -107,54 +154,144 @@ export class Channel {
    * @param start - The starting timestamp of the first sample in data.
    * @param data - THe telemetry to write to the channel.
    */
-  async write(start: CrudeTimeSpan, data: NativeTypedArray): Promise<void> {
+  async write(start: CrudeTimeStamp, data: NativeTypedArray): Promise<void> {
     return await this.framer.write(this.key, start, data);
   }
 }
 
 /**
  * The core client class for executing channel operations against a Synnax
- * cluster.
+ * 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> {
   private readonly frameClient: framer.Client;
   private readonly retriever: Retriever;
   private readonly creator: Creator;
+  private readonly client: UnaryClient;
 
-  constructor(segmentClient: framer.Client, retriever: Retriever, creator: Creator) {
-    this.frameClient = segmentClient;
+  constructor(
+    frameClient: framer.Client,
+    retriever: Retriever,
+    client: UnaryClient,
+    creator: Creator,
+  ) {
+    this.frameClient = frameClient;
     this.retriever = retriever;
+    this.client = client;
     this.creator = creator;
   }
 
+  /**
+   * Creates a single channel with the given properties.
+   *
+   * @param name - A human-readable name for the channel.
+   * @param rate - The rate of the channel. This only applies to fixed rate channels.
+   * @param dataType - The data type for the samples stored in the channel.
+   * @param index - The key of the index channel that this channel should be associated
+   * with. An 'index' channel is a channel that stores timestamps for other channels. Refer
+   * to the Synnax documentation (https://docs.synnaxlabs.com) for more information. The
+   * index channel must have already been created. This field does not need to be specified
+   * if the channel is an index channel, or the channel is a fixed rate channel. If this
+   * value is specified, the 'rate' parameter will be ignored.
+   * @param isIndex - Set to true if the channel is an index channel, and false otherwise.
+   * Index channels must have a data type of `DataType.TIMESTAMP`.
+   * @returns the created channel. {@see Channel}
+   * @throws {ValidationError} if any of the parameters for creating the channel are
+   * invalid.
+   *
+   * @example
+   * ```typescript
+   * const indexChannel = await client.channels.create({
+   *    name: "time",
+   *    dataType: DataType.TIMESTAMP,
+   *    isIndex: true,
+   * })
+   *
+   *
+   * const dataChannel = await client.channels.create({
+   *    name: "temperature",
+   *    dataType: DataType.FLOAT,
+   *    index: indexChannel.key,
+   * });
+   * ```
+   */
   async create(channel: NewPayload): Promise<Channel>;
 
-  async create(channels: NewPayload[]): Promise<Channel[]>;
-
   /**
-   * Creates a new channel with the given properties.
+   * Creates multiple channels with the given properties. The order of the channels
+   * returned is guaranteed to match the order of the channels passed in.
+   *
+   * @param channels - An array of channel properties to create.
+   * For each channel, the following properties should be considered:
+   *
+   * @param name - A human-readable name for the channel.
+   * @param rate - The rate of the channel. This only applies to fixed rate channels. If
+   * the 'index' parameter is specified or 'isIndex' is set to true, this parameter will
+   * be ignored.
+   * @param dataType - The data type for the samples stored in the channel.
+   * @param index - The key of the index channel that this channel should be associated
+   * with. An 'index' channel is a channel that stores timestamps for other channels. Refer
+   * to the Synnax documentation (https://docs.synnaxlabs.com) for more information. The
+   * index channel must have already been created. This field does not need to be specified
+   * if the channel is an index channel, or the channel is a fixed rate channel. If this
+   * value is specified, the 'rate' parameter will be ignored.
+   * @param isIndex - Set to true if the channel is an index channel, and false otherwise.
+   * Index channels must have a data type of `DataType.TIMESTAMP`.
    *
-   * @param props.rate - The rate of the channel.
-   * @param props.dataType - The data type of the channel.
-   * @param props.name - The name of the channel. Optional.
-   * @param props.nodeKey - The ID of the node that holds the lease on the
-   *   channel. If you don't know what this is, don't worry about it.
-   * @returns The created channel.
+   * @param channels
    */
+  async create(channels: NewPayload[]): Promise<Channel[]>;
+
   async create(channels: NewPayload | NewPayload[]): Promise<Channel | Channel[]> {
+    console.log("ABC");
     const single = !Array.isArray(channels);
-    const res = this.sugar(await this.creator.create(toArray(channels)));
+    const payloads = await this.creator.create(toArray(channels));
+    const res = this.sugar(payloads);
     return single ? res[0] : res;
   }
 
+  /**
+   * Retrieves a channel from the database using the given key or name.
+   *
+   * @param channel - 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.
+   * @param options.notDataTypes - Limits the query to only channels without the specified
+   * data type.
+   *
+   * @returns The retrieved channel.
+   * @throws {NotFoundError} if the channel does not exist in the cluster.
+   * @throws {MultipleResultsError} is only thrown if the channel is retrieved by name,
+   * and multiple channels with the same name exist in the cluster.
+   *
+   * @example
+   *
+   * ```typescript
+   * const channel = await client.channels.retrieve("temperature");
+   * const channel = await client.channels.retrieve(1);
+   * ```
+   */
   async retrieve(channel: KeyOrName, rangeKey?: string): 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
+   * 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
+   * type.
+   * @param options.notDataTypes - Limits the query to only channels without the specified
+   *
+   */
   async retrieve(channels: Params, rangeKey?: string): Promise<Channel[]>;
 
   /**
    * Retrieves a channel from the database using the given parameters.
-   * @param props.key - The key of the channel to retrieve.
-   * @param props.name - The name of the channel to retrieve. If props.key is set,
+   *
    * this will be ignored.
    * @returns The retrieved channel.
    * @raises {QueryError} If the channel does not exist or if multiple results are returned.
@@ -164,9 +301,10 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
     if (normalized.length === 0) return [];
     const res = this.sugar(await this.retriever.retrieve(channels, rangeKey));
     if (!single) return res;
-    if (res.length === 0) throw new QueryError(`channel matching ${actual} not found`);
+    if (res.length === 0)
+      throw new NoResultsError(`channel matching ${actual} not found`);
     if (res.length > 1)
-      throw new QueryError(`multiple channels matching ${actual} found`);
+      throw new MultipleResultsError(`multiple channels matching ${actual} found`);
     return res[0];
   }
 
@@ -182,6 +320,12 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
     return this.sugar(await this.retriever.page(offset, limit, rangeKey));
   }
 
+  createDebouncedBatchRetriever(deb: number = 10): Retriever {
+    return new CacheRetriever(
+      new DebouncedBatchRetriever(new ClusterRetriever(this.client), deb),
+    );
+  }
+
   private sugar(payloads: Payload[]): Channel[] {
     const { frameClient } = this;
     return payloads.map((p) => new Channel({ ...p, frameClient }));
@@ -208,4 +352,4 @@ class SearcherUnderRange implements AsyncTermSearcher<string, Key, Channel> {
   async retrieve(channels: Key[]): Promise<Channel[]> {
     return await this.client.retrieve(channels, this.rangeKey);
   }
-}
+}

package/src/channel/payload.ts

@@ -45,8 +45,8 @@ export type NewPayload = z.input<typeof newPayload>;
 export const parseChannels = (channels: NewPayload[]): NewPayload[] =>
   channels.map((channel) => ({
     name: channel.name,
-    dataType: new DataType(channel.dataType),
-    rate: new Rate(channel.rate ?? 0),
+    dataType: channel.dataType,
+    rate: channel.rate ?? 0,
     leaseholder: channel.leaseholder,
     index: channel.index,
     isIndex: channel.isIndex,

package/src/channel/retriever.ts

@@ -6,9 +6,8 @@
 // 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 { toArray } from "@synnaxlabs/x";
+import { debounce, toArray } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import {
@@ -22,6 +21,7 @@ import {
   type Payload,
   payload,
 } from "@/channel/payload";
+import { Mutex } from "async-mutex";
 
 const reqZ = z.object({
   leaseholder: z.number().optional(),
@@ -156,3 +156,63 @@ export const analyzeParams = (channels: Params): ParamAnalysisResult => {
     actual: channels,
   } as const as ParamAnalysisResult;
 };
+
+export interface PromiseFns<T> {
+  resolve: (value: T) => void;
+  reject: (reason?: any) => void;
+}
+
+// no interval
+export class DebouncedBatchRetriever implements Retriever {
+  private readonly mu = new Mutex();
+  private readonly requests = new Map<Keys, PromiseFns<Payload[]>>();
+  private readonly wrapped: Retriever;
+  private readonly debouncedRun: () => void;
+
+  constructor(wrapped: Retriever, deb: number) {
+    this.wrapped = wrapped;
+    this.debouncedRun = debounce(() => {
+      void this.run();
+    }, deb);
+  }
+
+  async search(term: string, rangeKey?: string): Promise<Payload[]> {
+    return await this.wrapped.search(term, rangeKey);
+  }
+
+  async page(offset: number, limit: number, rangeKey?: string): Promise<Payload[]> {
+    return await this.wrapped.page(offset, limit, rangeKey);
+  }
+
+  async retrieve(channels: Params): Promise<Payload[]> {
+    const { normalized, variant } = analyzeParams(channels);
+    // Bypass on name fetches for now.
+    if (variant === "names") 
+      return await this.wrapped.retrieve(normalized);
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    const a = new Promise<Payload[]>((resolve, reject) => {
+      void this.mu.runExclusive(() => {
+        this.requests.set(normalized, { resolve, reject });
+        this.debouncedRun();
+      });
+    });
+    return await a;
+  }
+
+  async run(): Promise<void> {
+    await this.mu.runExclusive(async () => {
+      const allKeys = new Set<Key>();
+      this.requests.forEach((_, keys) => keys.forEach((k) => allKeys.add(k)));
+      try {
+        const channels = await this.wrapped.retrieve(Array.from(allKeys));
+        this.requests.forEach((fns, keys) =>
+          fns.resolve(channels.filter((c) => keys.includes(c.key))),
+        );
+      } catch (e) {
+        this.requests.forEach((fns) => fns.reject(e));
+      } finally {
+        this.requests.clear();
+      }
+    });
+  }
+}

package/src/client.ts

@@ -15,16 +15,15 @@ import { channel } from "@/channel";
 import { connection } from "@/connection";
 import { errorsMiddleware } from "@/errors";
 import { framer } from "@/framer";
+import { hardware } from "@/hardware";
+import { device } from "@/hardware/device";
+import { rack } from "@/hardware/rack";
+import { task } from "@/hardware/task";
 import { label } from "@/label";
 import { ontology } from "@/ontology";
 import { ranger } from "@/ranger";
 import { Transport } from "@/transport";
 import { workspace } from "@/workspace";
-import { hardware } from "./hardware";
-import { device } from "./hardware/device";
-import { rack } from "./hardware/rack";
-import { task } from "./hardware/task";
-import { randomUUID } from "crypto";
 
 export const synnaxPropsZ = z.object({
   host: z.string().min(1),
@@ -97,7 +96,12 @@ export default class Synnax {
     );
     const chCreator = new channel.Creator(this.transport.unary);
     this.telem = new framer.Client(this.transport.stream, chRetriever);
-    this.channels = new channel.Client(this.telem, chRetriever, chCreator);
+    this.channels = new channel.Client(
+      this.telem,
+      chRetriever,
+      this.transport.unary,
+      chCreator,
+    );
     this.connectivity = new connection.Checker(
       this.transport.unary,
       connectivityPollFrequency,

package/src/errors.ts

@@ -95,6 +95,10 @@ export class UnexpectedError extends BaseError {
  */
 export class QueryError extends BaseError {}
 
+export class NoResultsError extends QueryError {}
+
+export class MultipleResultsError extends QueryError {}
+
 /**
  * RouteError is raised when a routing error occurs.
  */

package/src/framer/streamer.spec.ts

@@ -27,6 +27,7 @@ describe("Streamer", () => {
   test("happy path", async () => {
     const ch = await newChannel();
     const streamer = await client.telem.newStreamer(ch.key);
+    await new Promise((resolve) => setTimeout(resolve, 100));
     const writer = await client.telem.newWriter({
       start: TimeStamp.now(),
       channels: ch.key,

package/src/hardware/task/retriever.ts

@@ -21,7 +21,7 @@ const retrieveReqZ = z.object({
 });
 
 const rerieveResS = z.object({
-  tasks: taskZ.array(),
+  tasks: z.union([taskZ.array(), z.null().transform(() => [])]),
 });
 
 export type RetrieveRequest = z.infer<typeof retrieveReqZ>;