@synnaxlabs/client 0.2.0 → 0.13.5

package/dist/connection/checker.d.ts

@@ -0,0 +1,66 @@
+import type { UnaryClient } from "@synnaxlabs/freighter";
+import { TimeSpan } from "@synnaxlabs/x";
+import { z } from "zod";
+export declare const status: z.ZodEnum<["disconnected", "connecting", "connected", "failed"]>;
+export type Status = z.infer<typeof status>;
+export declare const state: z.ZodObject<{
+    status: z.ZodEnum<["disconnected", "connecting", "connected", "failed"]>;
+    error: z.ZodOptional<z.ZodType<Error, z.ZodTypeDef, Error>>;
+    message: z.ZodOptional<z.ZodString>;
+    clusterKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "disconnected" | "connecting" | "connected" | "failed";
+    clusterKey: string;
+    error?: Error | undefined;
+    message?: string | undefined;
+}, {
+    status: "disconnected" | "connecting" | "connected" | "failed";
+    clusterKey: string;
+    error?: Error | undefined;
+    message?: string | undefined;
+}>;
+export type State = z.infer<typeof state>;
+/** Polls a synnax cluster for connectivity information. */
+export declare class Checker {
+    private static readonly ENDPOINT;
+    static readonly DEFAULT: State;
+    private readonly _state;
+    private readonly pollFrequency;
+    private readonly client;
+    private interval?;
+    private readonly onChangeHandlers;
+    static readonly connectionStateZ: z.ZodObject<{
+        status: z.ZodEnum<["disconnected", "connecting", "connected", "failed"]>;
+        error: z.ZodOptional<z.ZodType<Error, z.ZodTypeDef, Error>>;
+        message: z.ZodOptional<z.ZodString>;
+        clusterKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        status: "disconnected" | "connecting" | "connected" | "failed";
+        clusterKey: string;
+        error?: Error | undefined;
+        message?: string | undefined;
+    }, {
+        status: "disconnected" | "connecting" | "connected" | "failed";
+        clusterKey: string;
+        error?: Error | undefined;
+        message?: string | undefined;
+    }>;
+    /**
+     * @param client - The transport client to use for connectivity checks.
+     * @param pollFreq - The frequency at which to poll the cluster for
+     *   connectivity information.
+     */
+    constructor(client: UnaryClient, pollFreq?: TimeSpan);
+    /** Stops the connectivity client from polling the cluster for connectivity */
+    stopChecking(): void;
+    /**
+     * Executes a connectivity check and updates the client status and error, as
+     * well as calling any registered change handlers.
+     */
+    check(): Promise<State>;
+    /** @returns a copy of the current client state. */
+    get state(): State;
+    /** @param callback - The function to call when the client status changes. */
+    onChange(callback: (state: State) => void): void;
+    private startChecking;
+}

package/dist/connection/index.d.ts

@@ -0,0 +1 @@
+export * as connection from '../connection/checker';

package/dist/control/authority.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare class Authority extends Number {
+    static readonly ABSOLUTE = 255;
+    static readonly DEFAULT = 1;
+    static readonly z: z.ZodUnion<[z.ZodType<Authority, z.ZodTypeDef, Authority>, z.ZodEffects<z.ZodNumber, Authority, number>, z.ZodEffects<z.ZodType<Number, z.ZodTypeDef, Number>, Authority, Number>]>;
+}

package/dist/control/external.d.ts

@@ -0,0 +1,2 @@
+export * from '../control/authority';
+export * from '../control/state';

package/dist/control/index.d.ts

@@ -0,0 +1 @@
+export * as control from '../control/external';

package/dist/control/state.d.ts

@@ -0,0 +1,81 @@
+import { type Destructor, observe } from "@synnaxlabs/x";
+import { z } from "zod";
+import { type Key as ChannelKey } from '../channel/payload';
+import { Authority } from '../control/authority';
+import { type Client as FrameClient } from '../framer/client';
+export declare const subjectZ: z.ZodObject<{
+    name: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    key: string;
+}, {
+    name: string;
+    key: string;
+}>;
+export interface Subject {
+    name: string;
+    key: string;
+}
+export declare const stateZ: z.ZodObject<{
+    subject: z.ZodObject<{
+        name: z.ZodString;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        key: string;
+    }, {
+        name: string;
+        key: string;
+    }>;
+    resource: z.ZodNumber;
+    authority: z.ZodUnion<[z.ZodType<Authority, z.ZodTypeDef, Authority>, z.ZodEffects<z.ZodNumber, Authority, number>, z.ZodEffects<z.ZodType<Number, z.ZodTypeDef, Number>, Authority, Number>]>;
+}, "strip", z.ZodTypeAny, {
+    subject: {
+        name: string;
+        key: string;
+    };
+    resource: number;
+    authority: Authority;
+}, {
+    subject: {
+        name: string;
+        key: string;
+    };
+    resource: number;
+    authority: (number | Number | Authority) & (number | Number | Authority | undefined);
+}>;
+export interface State {
+    subject: Subject;
+    resource: ChannelKey;
+    authority: Authority;
+}
+export declare const filterTransfersByChannelKey: (...resources: ChannelKey[]) => (transfers: Transfer[]) => Transfer[];
+interface Release {
+    from: State;
+    to?: null;
+}
+interface Acquire {
+    from?: null;
+    to: State;
+}
+export type Transfer = {
+    from: State;
+    to: State;
+} | Release | Acquire;
+export declare const transferString: (t: Transfer) => string;
+export declare class StateTracker implements observe.Observable<Transfer[]> {
+    readonly states: Map<ChannelKey, State>;
+    private readonly streamer;
+    private readonly ecd;
+    private readonly observer;
+    private readonly closePromise;
+    private constructor();
+    subjects(): Subject[];
+    onChange(handler: observe.Handler<Transfer[]>): Destructor;
+    close(): Promise<void>;
+    static open(client: FrameClient): Promise<StateTracker>;
+    private stream;
+    private merge;
+}
+export {};

package/{build/main/lib → dist}/errors.d.ts

@@ -1,8 +1,8 @@
-import { BaseTypedError } from '@synnaxlabs/freighter';
-export declare type Field = {
+import { BaseTypedError, type Middleware } from "@synnaxlabs/freighter";
+export interface Field {
     field: string;
     message: string;
-};
+}
 declare class BaseError extends BaseTypedError {
     constructor(message: string);
 }
@@ -32,6 +32,7 @@ export declare class AuthError extends BaseError {
  * UnexpectedError is raised when an unexpected error occurs.
  */
 export declare class UnexpectedError extends BaseError {
+    constructor(message: string);
 }
 /**
  * QueryError is raised when a query error occurs.
@@ -50,4 +51,6 @@ export declare class RouteError extends BaseError {
  */
 export declare class ContiguityError extends BaseError {
 }
+export declare const validateFieldNotNull: (key: string, value: unknown, message?: string) => void;
+export declare const errorsMiddleware: Middleware;
 export {};

package/dist/framer/adapter.d.ts

@@ -0,0 +1,21 @@
+import { type Key, type Params } from '../channel/payload';
+import { type Retriever } from '../channel/retriever';
+import { type Frame } from '../framer/frame';
+export declare class BackwardFrameAdapter {
+    private adapter;
+    retriever: Retriever;
+    keys: Key[];
+    private constructor();
+    static open(retriever: Retriever, channels: Params): Promise<BackwardFrameAdapter>;
+    update(channels: Params): Promise<void>;
+    adapt(fr: Frame): Frame;
+}
+export declare class ForwardFrameAdapter {
+    private adapter;
+    retriever: Retriever;
+    keys: Key[];
+    private constructor();
+    static open(retriever: Retriever, channels: Params): Promise<ForwardFrameAdapter>;
+    update(channels: Params): Promise<void>;
+    adapt(fr: Frame): Frame;
+}

package/dist/framer/client.d.ts

@@ -0,0 +1,44 @@
+import { type StreamClient } from "@synnaxlabs/freighter";
+import { type NativeTypedArray, type Series, type TimeRange, type CrudeTimeStamp, TimeStamp } from "@synnaxlabs/x";
+import { type KeyOrName, type Params } from '../channel/payload';
+import { type Retriever } from '../channel/retriever';
+import { Frame } from '../framer/frame';
+import { Iterator } from '../framer/iterator';
+import { Streamer } from '../framer/streamer';
+import { Writer, type WriterConfig } from '../framer/writer';
+export declare class Client {
+    private readonly stream;
+    private readonly retriever;
+    constructor(stream: StreamClient, retriever: Retriever);
+    /**
+     * Opens a new iterator over the given channels within the provided time range.
+     *
+     * @param tr - A time range to iterate over.
+     * @param keys - A list of channel keys to iterate over.
+     * @returns a new {@link TypedIterator}.
+     */
+    newIterator(tr: TimeRange, channels: Params): Promise<Iterator>;
+    /**
+     * Opens a new writer on the given channels.
+     *
+     * @param keys - The keys of the channels to write to. A writer cannot write to
+     * a channel that is not in this list. See the {@link RecordWriter} documentation
+     * for more information.
+     * @returns a new {@link RecordWriter}.
+     */
+    newWriter({ start, channels, controlSubject, authorities, }: WriterConfig): Promise<Writer>;
+    newStreamer(params: Params, from?: TimeStamp): Promise<Streamer>;
+    /**
+     * Writes telemetry to the given channel starting at the given timestamp.
+     *
+     * @param to - The key of the channel to write to.
+     * @param start - The starting timestamp of the first sample in data.
+     * @param data  - The telemetry to write. This telemetry must have the same
+     * data type as the channel.
+     * @throws if the channel does not exist.
+     */
+    write(to: KeyOrName, start: CrudeTimeStamp, data: NativeTypedArray): Promise<void>;
+    read(tr: TimeRange, channel: KeyOrName): Promise<Series>;
+    read(tr: TimeRange, channels: Params): Promise<Frame>;
+    private readFrame;
+}

package/dist/framer/external.d.ts

@@ -0,0 +1,5 @@
+export * from '../framer/client';
+export * from '../framer/frame';
+export * from '../framer/iterator';
+export * from '../framer/streamer';
+export * from '../framer/writer';

package/dist/framer/frame.d.ts

@@ -0,0 +1,251 @@
+import { Size, Series, TimeRange, DataType } from "@synnaxlabs/x";
+import { z } from "zod";
+import { type KeyOrName, type Keys, type Names, type Params } from '../channel/payload';
+type ColumnType = "key" | "name" | null;
+export type CrudeFrame = Frame | FramePayload | Map<KeyOrName, Series[] | Series> | Record<KeyOrName, Series[] | Series>;
+/**
+ * A frame is a collection of related typed arrays keyed to a particular channel. Frames
+ * can be keyed by channel name or channel key, but not both.
+ *
+ * Frames have two important characteristics: alignment and orientation.
+ *
+ * A frame's alignment defines how correlated the arrays for different channels in the
+ * frame are:
+ *
+ * - 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 gaps betwen 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
+ * 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.
+ *
+ * - Unaligned frames don't meet the requirements for weakly or strongly aligned frames.
+ * Unaligned frames are common when reading from channels that don't have the same
+ * index/rate and are continuous in different periods of time.
+ *
+ * Frames also have an orientation: horizontal, vertical, or square.
+ *
+ * - 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.
+ *
+ * - 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
+ * vertical.
+ *
+ * - Square frames are both horizontal and vertical. Only a frame with a single channel
+ * and array can be square.
+ */
+export declare class Frame {
+    readonly columns: Keys | Names;
+    readonly series: Series[];
+    constructor(columnsOrData?: Params | CrudeFrame, arrays?: Series | Series[]);
+    /**
+     * @returns "key" if the frame columns are channel keys, "name" if the columns are
+     * channel names, and null if the frame has no columns.
+     */
+    get colType(): ColumnType;
+    /**
+     * @returns the channel keys if the frame is keyed by channel key, and throws an error
+     * otherwise.
+     */
+    get keys(): Keys;
+    /**
+     * @returns the unique channel keys if the frame is keyed by channel key, and throws an
+     * error otherwise.
+     */
+    get uniqueKeys(): Keys;
+    /**
+     * @returns the channel names if the frame is keyed by channel name, and throws an error
+     * otherwise.
+     */
+    get names(): Names;
+    /**
+     * @returns the unique channel names if the frame is keyed by channel name, and throws an
+     * otherwise.
+     */
+    get uniqueNames(): Names;
+    /**
+     * @returns the unique columns in the frame.
+     */
+    get uniqueColumns(): Keys | Names;
+    toPayload(): FramePayload;
+    /**
+     * @returns true if the frame is vertical. 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 vertical.
+     */
+    get isVertical(): boolean;
+    /**
+     * @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.
+     */
+    get isHorizontal(): boolean;
+    /**
+     * @returns true if the frame is square. Square frames are both horizontal and vertical.
+     * Only a frame with a single channel and array can be square.
+     */
+    get isSquare(): boolean;
+    /**
+     * @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
+     * gaps betwen them.
+     */
+    get isWeaklyAligned(): boolean;
+    timeRange(col?: KeyOrName): TimeRange;
+    get timeRanges(): TimeRange[];
+    /**
+     * @returns lazy arrays matching the given channel key or name.
+     * @param key the channel key or name.
+     */
+    get(key: KeyOrName): Series[];
+    /**
+     * @returns a frame with the given channel keys or names.
+     * @param keys the channel keys or names.
+     */
+    get(keys: Keys | Names): Frame;
+    /**
+     * Pushes a set of typed arrays for the given channel onto the frame.
+     *
+     * @param key the channel key or name;
+     * @param v the typed arrays to push.
+     */
+    push(key: KeyOrName, ...v: Series[]): void;
+    /**
+     * Pushes the frame onto the current frame.
+     *
+     * @param frame  - the frame to push.
+     */
+    push(frame: Frame): void;
+    /**
+     * @returns a shallow copy of this frame containing all typed arrays in the current frame and the
+     * provided frame.
+     */
+    concat(frame: Frame): Frame;
+    /**
+     * @returns true if the frame contains the provided channel key or name.
+     * @param channel the channel key or name to check.
+     */
+    has(channel: KeyOrName): boolean;
+    /**
+     * @returns a new frame containing the mapped output of the provided function.
+     * @param fn a function that takes a channel key and typed array and returns a
+     * boolean.
+     */
+    map(fn: (k: KeyOrName, arr: Series, i: number) => [KeyOrName, Series]): Frame;
+    /**
+     * Iterates over all typed arrays in the current frame.
+     *
+     * @param fn a function that takes a channel key and typed array.
+     */
+    forEach(fn: (k: KeyOrName, arr: Series, i: number) => void): void;
+    /**
+     * @returns a new frame containing all typed arrays in the current frame that pass
+     * the provided filter function.
+     * @param fn a function that takes a channel key and typed array and returns a boolean.
+     */
+    filter(fn: (k: KeyOrName, arr: Series, i: number) => boolean): Frame;
+    /** @returns the total number of bytes in the frame. */
+    get byteLength(): Size;
+    /** @returns the total number of samples in the frame. */
+    get length(): number;
+}
+export declare const series: z.ZodObject<{
+    timeRange: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+        start: z.ZodUnion<[z.ZodEffects<z.ZodType<Number, z.ZodTypeDef, Number>, import("@synnaxlabs/x").TimeStamp, Number>, z.ZodEffects<z.ZodNumber, import("@synnaxlabs/x").TimeStamp, number>, z.ZodType<import("@synnaxlabs/x").TimeStamp, z.ZodTypeDef, import("@synnaxlabs/x").TimeStamp>]>;
+        end: z.ZodUnion<[z.ZodEffects<z.ZodType<Number, z.ZodTypeDef, Number>, import("@synnaxlabs/x").TimeStamp, Number>, z.ZodEffects<z.ZodNumber, import("@synnaxlabs/x").TimeStamp, number>, z.ZodType<import("@synnaxlabs/x").TimeStamp, z.ZodTypeDef, import("@synnaxlabs/x").TimeStamp>]>;
+    }, "strip", z.ZodTypeAny, {
+        start: import("@synnaxlabs/x").TimeStamp;
+        end: import("@synnaxlabs/x").TimeStamp;
+    }, {
+        start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+    }>, TimeRange, {
+        start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+    }>, z.ZodType<TimeRange, z.ZodTypeDef, TimeRange>]>>;
+    alignment: z.ZodOptional<z.ZodNumber>;
+    dataType: z.ZodUnion<[z.ZodEffects<z.ZodString, DataType, string>, z.ZodType<DataType, z.ZodTypeDef, DataType>]>;
+    data: z.ZodEffects<z.ZodString, ArrayBuffer | SharedArrayBuffer, string>;
+}, "strip", z.ZodTypeAny, {
+    dataType: DataType;
+    data: (ArrayBuffer | SharedArrayBuffer) & (ArrayBuffer | SharedArrayBuffer | undefined);
+    timeRange?: TimeRange | undefined;
+    alignment?: number | undefined;
+}, {
+    dataType: (string | DataType) & (string | DataType | undefined);
+    data: string;
+    timeRange?: TimeRange | {
+        start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+    } | undefined;
+    alignment?: number | undefined;
+}>;
+export type SeriesPayload = z.infer<typeof series>;
+export declare const frameZ: z.ZodObject<{
+    keys: z.ZodUnion<[z.ZodEffects<z.ZodNull, number[], null>, z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>>]>;
+    series: z.ZodUnion<[z.ZodEffects<z.ZodNull, {
+        dataType: DataType;
+        data: (ArrayBuffer | SharedArrayBuffer) & (ArrayBuffer | SharedArrayBuffer | undefined);
+        timeRange?: TimeRange | undefined;
+        alignment?: number | undefined;
+    }[], null>, z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        timeRange: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+            start: z.ZodUnion<[z.ZodEffects<z.ZodType<Number, z.ZodTypeDef, Number>, import("@synnaxlabs/x").TimeStamp, Number>, z.ZodEffects<z.ZodNumber, import("@synnaxlabs/x").TimeStamp, number>, z.ZodType<import("@synnaxlabs/x").TimeStamp, z.ZodTypeDef, import("@synnaxlabs/x").TimeStamp>]>;
+            end: z.ZodUnion<[z.ZodEffects<z.ZodType<Number, z.ZodTypeDef, Number>, import("@synnaxlabs/x").TimeStamp, Number>, z.ZodEffects<z.ZodNumber, import("@synnaxlabs/x").TimeStamp, number>, z.ZodType<import("@synnaxlabs/x").TimeStamp, z.ZodTypeDef, import("@synnaxlabs/x").TimeStamp>]>;
+        }, "strip", z.ZodTypeAny, {
+            start: import("@synnaxlabs/x").TimeStamp;
+            end: import("@synnaxlabs/x").TimeStamp;
+        }, {
+            start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+            end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        }>, TimeRange, {
+            start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+            end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        }>, z.ZodType<TimeRange, z.ZodTypeDef, TimeRange>]>>;
+        alignment: z.ZodOptional<z.ZodNumber>;
+        dataType: z.ZodUnion<[z.ZodEffects<z.ZodString, DataType, string>, z.ZodType<DataType, z.ZodTypeDef, DataType>]>;
+        data: z.ZodEffects<z.ZodString, ArrayBuffer | SharedArrayBuffer, string>;
+    }, "strip", z.ZodTypeAny, {
+        dataType: DataType;
+        data: (ArrayBuffer | SharedArrayBuffer) & (ArrayBuffer | SharedArrayBuffer | undefined);
+        timeRange?: TimeRange | undefined;
+        alignment?: number | undefined;
+    }, {
+        dataType: (string | DataType) & (string | DataType | undefined);
+        data: string;
+        timeRange?: TimeRange | {
+            start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+            end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        } | undefined;
+        alignment?: number | undefined;
+    }>, "many">>>]>;
+}, "strip", z.ZodTypeAny, {
+    keys: number[];
+    series: {
+        dataType: DataType;
+        data: (ArrayBuffer | SharedArrayBuffer) & (ArrayBuffer | SharedArrayBuffer | undefined);
+        timeRange?: TimeRange | undefined;
+        alignment?: number | undefined;
+    }[];
+}, {
+    keys?: number[] | null | undefined;
+    series?: {
+        dataType: (string | DataType) & (string | DataType | undefined);
+        data: string;
+        timeRange?: TimeRange | {
+            start: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+            end: (number | Number | import("@synnaxlabs/x").TimeStamp) & (number | Number | import("@synnaxlabs/x").TimeStamp | undefined);
+        } | undefined;
+        alignment?: number | undefined;
+    }[] | null | undefined;
+}>;
+export type FramePayload = z.infer<typeof frameZ>;
+export declare const seriesFromPayload: (series: SeriesPayload) => Series;
+export declare const seriesToPayload: (series: Series) => SeriesPayload;
+export {};

package/dist/framer/index.d.ts

@@ -0,0 +1 @@
+export * as framer from '../framer/external';