@synnaxlabs/client 0.15.3 → 0.16.4

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @synnaxlabs/client@0.15.3 build /home/runner/work/synnax/synnax/client/ts
+> @synnaxlabs/client@0.16.4 build /home/runner/work/synnax/synnax/client/ts
 > tsc --noEmit && vite build
 
 vite v5.1.2 building for production...
@@ -9,8 +9,8 @@ rendering chunks...
 
 [vite:dts] Start generate declaration files...
 computing gzip size...
-dist/client.es.js  521.17 kB │ gzip: 114.65 kB │ map: 1,285.87 kB
-[vite:dts] Declaration files built in 3563ms.
+dist/client.js  525.40 kB │ gzip: 115.77 kB │ map: 1,305.16 kB
+[vite:dts] Declaration files built in 3559ms.
 
-dist/client.cjs.js  347.31 kB │ gzip: 91.63 kB │ map: 1,231.44 kB
-✓ built in 5.10s
+dist/client.cjs  349.36 kB │ gzip: 92.12 kB │ map: 1,250.30 kB
+✓ built in 5.09s

package/README.md

@@ -1,3 +1,12 @@
-# synnax
+# Synnax Client
+
+A client library for interacting with a Synnax cluster. It supports Typescript and can be used in both node and browser environments.
+
+Detailed documentation is available [here](https://docs.synnaxlabs.com/typescript-client/get-started]).
+
+## Installation
+
+```bash
+npm install @synnaxlabs/client
+```
 
-synnax Client Library

package/dist/channel/client.d.ts

@@ -1,28 +1,68 @@
-import { DataType, Rate, type NativeTypedArray, type CrudeDensity, type Series, type TimeRange, type AsyncTermSearcher, type CrudeTimeSpan } from "@synnaxlabs/x";
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { DataType, Rate, type NativeTypedArray, type CrudeDensity, type Series, type TimeRange, type AsyncTermSearcher, type CrudeTimeStamp } from "@synnaxlabs/x";
 import { type Creator } from './creator';
 import { type Key, type KeyOrName, type Params, type Payload, type NewPayload } from './payload';
 import { type Retriever } from './retriever';
 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 declare class Channel {
     private readonly _frameClient;
-    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, rate, name, leaseholder, key, isIndex, index, frameClient, alias, }: NewPayload & {
         frameClient?: framer.Client;
         density?: CrudeDensity;
     });
     private get framer();
+    /**
+     * 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;
     /**
      * Reads telemetry from the channel between the two timestamps.
@@ -38,21 +78,113 @@ export declare class Channel {
      * @param start - The starting timestamp of the first sample in data.
      * @param data - THe telemetry to write to the channel.
      */
-    write(start: CrudeTimeSpan, data: NativeTypedArray): Promise<void>;
+    write(start: CrudeTimeStamp, data: NativeTypedArray): Promise<void>;
 }
 /**
  * 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 declare class Client implements AsyncTermSearcher<string, Key, Channel> {
     private readonly frameClient;
     private readonly retriever;
     private readonly creator;
     private readonly client;
-    constructor(segmentClient: framer.Client, retriever: Retriever, client: UnaryClient, creator: Creator);
+    constructor(frameClient: framer.Client, retriever: Retriever, client: UnaryClient, 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,
+     * });
+     * ```
+     */
     create(channel: NewPayload): Promise<Channel>;
+    /**
+     * 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 channels
+     */
     create(channels: NewPayload[]): Promise<Channel[]>;
+    /**
+     * 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);
+     * ```
+     */
     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
+     *
+     */
     retrieve(channels: Params, rangeKey?: string): Promise<Channel[]>;
     search(term: string, rangeKey?: string): Promise<Channel[]>;
     newSearcherUnderRange(rangeKey?: string): AsyncTermSearcher<string, Key, Channel>;