@synnaxlabs/client 0.15.3 → 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,25 +29,65 @@ import {
   payload,
   type NewPayload,
 } from "@/channel/payload";
-import { analyzeParams, CacheRetriever, ClusterRetriever, DebouncedBatchRetriever, 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";
-import { UnaryClient } from "@synnaxlabs/freighter";
 
 /**
- * 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,
@@ -75,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,
@@ -108,14 +154,15 @@ 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;
@@ -124,45 +171,127 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
   private readonly client: UnaryClient;
 
   constructor(
-    segmentClient: framer.Client, 
+    frameClient: framer.Client,
     retriever: Retriever,
     client: UnaryClient,
-    creator: Creator
-    ) {
-    this.frameClient = segmentClient;
+    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 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 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 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.
@@ -172,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];
   }
 
@@ -190,8 +320,10 @@ 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))
+  createDebouncedBatchRetriever(deb: number = 10): Retriever {
+    return new CacheRetriever(
+      new DebouncedBatchRetriever(new ClusterRetriever(this.client), deb),
+    );
   }
 
   private sugar(payloads: Payload[]): Channel[] {
@@ -220,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/client.ts

@@ -15,15 +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";
 
 export const synnaxPropsZ = z.object({
   host: z.string().min(1),
@@ -96,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, this.transport.unary, 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,