@synnaxlabs/client 0.2.0 → 0.13.5

package/src/errors.ts

@@ -0,0 +1,153 @@
+// Copyright 2023 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 {
+  BaseTypedError,
+  type Middleware,
+  registerError,
+  Unreachable,
+  type ErrorPayload,
+} from "@synnaxlabs/freighter";
+
+const _FREIGHTER_EXCEPTION_PREFIX = "sy.api.";
+
+enum APIErrorType {
+  General = _FREIGHTER_EXCEPTION_PREFIX + "general",
+  Parse = _FREIGHTER_EXCEPTION_PREFIX + "parse",
+  Auth = _FREIGHTER_EXCEPTION_PREFIX + "auth",
+  Unexpected = _FREIGHTER_EXCEPTION_PREFIX + "unexpected",
+  Validation = _FREIGHTER_EXCEPTION_PREFIX + "validation",
+  Query = _FREIGHTER_EXCEPTION_PREFIX + "query",
+  Route = _FREIGHTER_EXCEPTION_PREFIX + "route",
+}
+
+export interface Field {
+  field: string;
+  message: string;
+}
+
+class BaseError extends BaseTypedError {
+  constructor(message: string) {
+    super(message, _FREIGHTER_EXCEPTION_PREFIX);
+  }
+}
+
+/**
+ * Raised when a validation error occurs.
+ */
+export class ValidationError extends BaseError {
+  fields: Field[];
+
+  constructor(fieldsOrMessage: string | Field[] | Field) {
+    if (typeof fieldsOrMessage === "string") {
+      super(fieldsOrMessage);
+      this.fields = [];
+    } else if (Array.isArray(fieldsOrMessage)) {
+      super(
+        fieldsOrMessage.map((field) => `${field.field}: ${field.message}`).join("\n"),
+      );
+      this.fields = fieldsOrMessage;
+    } else {
+      super(`${fieldsOrMessage.field}: ${fieldsOrMessage.message}`);
+      this.fields = [fieldsOrMessage];
+    }
+  }
+}
+
+/**
+ * GeneralError is raised when a general error occurs.
+ */
+export class GeneralError extends BaseError {}
+
+/**
+ * ParseError is raised when a parse error occurs.
+ */
+export class ParseError extends BaseError {}
+
+/**
+ * AuthError is raised when an authentication error occurs.
+ */
+export class AuthError extends BaseError {}
+
+/**
+ * UnexpectedError is raised when an unexpected error occurs.
+ */
+export class UnexpectedError extends BaseError {}
+
+/**
+ * QueryError is raised when a query error occurs.
+ */
+export class QueryError extends BaseError {}
+
+/**
+ * RouteError is raised when a routing error occurs.
+ */
+export class RouteError extends BaseError {
+  path: string;
+
+  constructor(message: string, path: string) {
+    super(message);
+    this.path = path;
+  }
+}
+
+/**
+ * Raised when time-series data is not contiguous.
+ */
+export class ContiguityError extends BaseError {}
+
+const decode = (payload: ErrorPayload): Error | null => {
+  if (!payload.type.startsWith(_FREIGHTER_EXCEPTION_PREFIX)) return null;
+  switch (payload.type) {
+    case APIErrorType.General:
+      return new GeneralError(payload.data);
+    case APIErrorType.Parse:
+      return new ParseError(payload.data);
+    case APIErrorType.Auth:
+      return new AuthError(payload.data);
+    case APIErrorType.Unexpected:
+      return new UnexpectedError(payload.data);
+    case APIErrorType.Validation: 
+      return new ValidationError(payload.data);
+    case APIErrorType.Query:
+      return new QueryError(payload.data);
+    case APIErrorType.Route:
+      return new RouteError(payload.data, payload.data);
+    default:
+      return new UnexpectedError(payload.data);
+  }
+};
+
+const encode = (): ErrorPayload => {
+  throw new Error("Not implemented");
+};
+
+registerError({ encode, decode });
+
+export const validateFieldNotNull = (
+  key: string,
+  value: unknown,
+  message: string = "must be provided",
+): void => {
+  if (value == null) throw new ValidationError({ field: key, message });
+};
+
+export const errorsMiddleware: Middleware = async (ctx, next) => {
+  const [res, err] = await next(ctx);
+  if (err == null) return [res, err];
+  if (err instanceof Unreachable)
+    return [
+      res,
+      new Unreachable({
+        message: `Cannot reach cluster at ${err.url.host}:${err.url.port}`,
+        url: err.url,
+      }),
+    ];
+  return [res, err];
+};

package/src/framer/adapter.ts

@@ -0,0 +1,116 @@
+// Copyright 2023 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 { type Key, type Name, type Params } from "@/channel/payload";
+import { type Retriever, analyzeParams } from "@/channel/retriever";
+import { type Frame } from "@/framer/frame";
+
+export class BackwardFrameAdapter {
+  private adapter: Map<Key, Name> | null;
+  retriever: Retriever;
+  keys: Key[];
+
+  private constructor(retriever: Retriever) {
+    this.retriever = retriever;
+    this.adapter = null;
+    this.keys = [];
+  }
+
+  static async open(
+    retriever: Retriever,
+    channels: Params,
+  ): Promise<BackwardFrameAdapter> {
+    const adapter = new BackwardFrameAdapter(retriever);
+    await adapter.update(channels);
+    return adapter;
+  }
+
+  async update(channels: Params): Promise<void> {
+    const { variant, normalized } = analyzeParams(channels);
+    if (variant === "keys") {
+      this.adapter = null;
+      this.keys = normalized;
+      return;
+    }
+    const fetched = await this.retriever.retrieve(normalized);
+    const a = new Map<Key, Name>();
+    this.adapter = a;
+    normalized.forEach((name) => {
+      const channel = fetched.find((channel) => channel.name === name);
+      if (channel == null) throw new Error(`Channel ${name} not found`);
+      a.set(channel.key, channel.name);
+    });
+    this.keys = Array.from(this.adapter.keys());
+  }
+
+  adapt(fr: Frame): Frame {
+    if (this.adapter == null) return fr;
+    const a = this.adapter;
+    return fr.map((k, arr) => {
+      if (typeof k === "number") {
+        const name = a.get(k);
+        if (name == null) throw new Error(`Channel ${k} not found`);
+        return [name, arr];
+      }
+      return [k, arr];
+    });
+  }
+}
+
+export class ForwardFrameAdapter {
+  private adapter: Map<Name, Key> | null;
+  retriever: Retriever;
+  keys: Key[];
+
+  private constructor(retriever: Retriever) {
+    this.retriever = retriever;
+    this.adapter = null;
+    this.keys = [];
+  }
+
+  static async open(
+    retriever: Retriever,
+    channels: Params,
+  ): Promise<ForwardFrameAdapter> {
+    const adapter = new ForwardFrameAdapter(retriever);
+    await adapter.update(channels);
+    return adapter;
+  }
+
+  async update(channels: Params): Promise<void> {
+    const { variant, normalized } = analyzeParams(channels);
+    if (variant === "keys") {
+      this.adapter = null;
+      this.keys = normalized;
+      return;
+    }
+    const fetched = await this.retriever.retrieve(normalized);
+    const a = new Map<Name, Key>();
+    this.adapter = a;
+    normalized.forEach((name) => {
+      const channel = fetched.find((channel) => channel.name === name);
+      if (channel == null) throw new Error(`Channel ${name} not found`);
+      a.set(channel.name, channel.key);
+    });
+    this.keys = fetched.map((c) => c.key);
+  }
+
+  adapt(fr: Frame): Frame {
+    if (this.adapter == null) return fr;
+    const a = this.adapter;
+    return fr.map((k, arr) => {
+      if (typeof k === "string") {
+        const key = a.get(k);
+        if (key == null) throw new Error(`Channel ${k} not found`);
+        return [key, arr];
+      }
+      return [k, arr];
+    });
+  }
+}

package/src/framer/client.ts

@@ -0,0 +1,116 @@
+// Copyright 2023 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 { 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, analyzeParams } from "@/channel/retriever";
+import { Authority } from "@/control/authority";
+import { Frame } from "@/framer/frame";
+import { Iterator } from "@/framer/iterator";
+import { Streamer } from "@/framer/streamer";
+import { Writer, type WriterConfig } from "@/framer/writer";
+
+export class Client {
+  private readonly stream: StreamClient;
+  private readonly retriever: Retriever;
+
+  constructor(stream: StreamClient, retriever: Retriever) {
+    this.stream = stream;
+    this.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}.
+   */
+  async newIterator(tr: TimeRange, channels: Params): Promise<Iterator> {
+    return await Iterator._open(tr, channels, this.retriever, this.stream);
+  }
+
+  /**
+   * 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}.
+   */
+  async newWriter({
+    start,
+    channels,
+    controlSubject,
+    authorities = Authority.ABSOLUTE,
+  }: WriterConfig): Promise<Writer> {
+    return await Writer._open(this.retriever, this.stream, {
+      start: start ?? TimeStamp.now(),
+      controlSubject,
+      channels,
+      authorities,
+    });
+  }
+
+  async newStreamer(
+    params: Params,
+    from: TimeStamp = TimeStamp.now(),
+  ): Promise<Streamer> {
+    return await Streamer._open(from, params, this.retriever, this.stream);
+  }
+
+  /**
+   * 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.
+   */
+  async write(
+    to: KeyOrName,
+    start: CrudeTimeStamp,
+    data: NativeTypedArray,
+  ): Promise<void> {
+    const w = await this.newWriter({ start, channels: to });
+    try {
+      await w.write(to, data);
+      if (!(await w.commit())) throw (await w.error()) as Error;
+    } catch {
+      await w.close();
+    }
+  }
+
+  async read(tr: TimeRange, channel: KeyOrName): Promise<Series>;
+
+  async read(tr: TimeRange, channels: Params): Promise<Frame>;
+
+  async read(tr: TimeRange, channels: Params): Promise<Series | Frame> {
+    const { single } = analyzeParams(channels);
+    const fr = await this.readFrame(tr, channels);
+    if (single) return fr.series[0];
+    return fr;
+  }
+
+  private async readFrame(tr: TimeRange, params: Params): Promise<Frame> {
+    const i = await this.newIterator(tr, params);
+    const frame = new Frame();
+    for await (const f of i) frame.push(f);
+    return frame;
+  }
+}

package/src/framer/external.ts

@@ -0,0 +1,14 @@
+// Copyright 2023 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.
+
+export * from "@/framer/client";
+export * from "@/framer/frame";
+export * from "@/framer/iterator";
+export * from "@/framer/streamer";
+export * from "@/framer/writer";

package/src/framer/frame.spec.ts

@@ -0,0 +1,317 @@
+// Copyright 2023 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 { DataType, Series, TimeRange } from "@synnaxlabs/x";
+import { describe, expect, it, test } from "vitest";
+
+import { framer } from "@/framer";
+
+describe("framer.Frame", () => {
+  describe("construction", () => {
+    describe("valid", () => {
+      test("from an array of channel names and an array of arrays", () => {
+        const f = new framer.Frame(
+          ["a", "b", "c"],
+          [
+            new Series(new Float32Array([1, 2, 3])),
+            new Series(new Float32Array([1, 2, 3])),
+            new Series(new Float32Array([1, 2, 3])),
+          ],
+        );
+        expect(f.length).toEqual(9);
+        expect(f.colType).toEqual("name");
+      });
+
+      test("from an array of channel keys and an array of arrays", () => {
+        const f = new framer.Frame(
+          [12, 13, 14],
+          [
+            new Series(new Float32Array([1, 2, 3])),
+            new Series(new Float32Array([1, 2, 3])),
+            new Series(new Float32Array([1, 2, 3])),
+          ],
+        );
+        expect(f.length).toEqual(9);
+        expect(f.colType).toEqual("key");
+      });
+
+      test("from a single name and an array of arrays", () => {
+        const f = new framer.Frame("a", [new Series(new Float32Array([1, 2, 3]))]);
+        expect(f.length).toEqual(3);
+        expect(f.colType).toEqual("name");
+      });
+
+      test("from a single key and an array of arrays", () => {
+        const f = new framer.Frame(12, [new Series(new Float32Array([1, 2, 3]))]);
+        expect(f.length).toEqual(3);
+        expect(f.colType).toEqual("key");
+      });
+
+      test("from a single key and a single array", () => {
+        const f = new framer.Frame(12, new Series(new Float32Array([1, 2, 3])));
+        expect(f.length).toEqual(3);
+        expect(f.colType).toEqual("key");
+      });
+
+      test("from a single name and a single array", () => {
+        const f = new framer.Frame("a", new Series(new Float32Array([1, 2, 3])));
+        expect(f.length).toEqual(3);
+        expect(f.colType).toEqual("name");
+      });
+
+      test("from payload", () => {
+        const f = new framer.Frame({
+          keys: [12],
+          series: [
+            {
+              dataType: new DataType("float32"),
+              data: new SharedArrayBuffer(12),
+            },
+          ],
+        });
+        expect(f.length.valueOf()).toEqual(3);
+        expect(f.columns.length).toEqual(1);
+        expect(f.series.length).toEqual(1);
+      });
+
+      test("from record", () => {
+        const f = new framer.Frame({
+          a: new Series(new Float32Array([1, 2, 3])),
+        });
+        expect(f.length.valueOf()).toEqual(3);
+        expect(f.columns.length).toEqual(1);
+        expect(f.series.length).toEqual(1);
+      });
+
+      test("from map", () => {
+        const f = new framer.Frame(
+          new Map([[12, new Series(new Float32Array([1, 2, 3]))]]),
+        );
+        expect(f.length).toEqual(3);
+        expect(f.columns.length).toEqual(1);
+        expect(f.series.length).toEqual(1);
+      });
+    });
+
+    describe("invalid", () => {
+      test("mismatched lengths", () => {
+        expect(
+          () =>
+            new framer.Frame(
+              ["a", "b", "c"],
+              [
+                new Series(new Float32Array([1, 2, 3])),
+                new Series(new Float32Array([1, 2, 3])),
+              ],
+            ),
+        ).toThrow();
+      });
+    });
+  });
+
+  describe("vertical", () => {
+    it("should return false if a key has more than one array", () => {
+      const f = new framer.Frame(
+        new Map([
+          [12, [new Series(new Float32Array([1, 2, 3]))]],
+          [
+            13,
+            [
+              new Series(new Float32Array([1, 2, 3])),
+              new Series(new Float32Array([1, 2, 3])),
+            ],
+          ],
+        ]),
+      );
+      expect(f.isVertical).toEqual(false);
+    });
+  });
+
+  describe("horizontal", () => {
+    it("should return false if there is more than one key", () => {
+      const f = new framer.Frame(
+        new Map([
+          [12, [new Series(new Float32Array([1, 2, 3]))]],
+          [13, [new Series(new Float32Array([1, 2, 3]))]],
+        ]),
+      );
+      expect(f.isHorizontal).toEqual(false);
+    });
+  });
+
+  describe("weaklyAligned", () => {
+    it("should return true if all keys have the same timerange", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series(
+                new Float32Array([1, 2, 3]),
+                undefined,
+                new TimeRange(500, 50000),
+              ),
+            ],
+          ],
+          [
+            13,
+            [
+              new Series(
+                new Float32Array([1, 2, 3]),
+                undefined,
+                new TimeRange(500, 50000),
+              ),
+            ],
+          ],
+        ]),
+      );
+      expect(f.isWeaklyAligned).toEqual(true);
+    });
+
+    it("should return false if any key has a different timerange", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series(
+                new Float32Array([1, 2, 3]),
+                undefined,
+                new TimeRange(500, 50000),
+              ),
+            ],
+          ],
+          [
+            13,
+            [
+              new Series(
+                new Float32Array([1, 2, 3]),
+                undefined,
+                new TimeRange(500, 50001),
+              ),
+            ],
+          ],
+        ]),
+      );
+      expect(f.isWeaklyAligned).toEqual(false);
+    });
+  });
+
+  describe("timeRange", () => {
+    describe("no key provided", () => {
+      it("should return the maxium time range of the frame", () => {
+        const f = new framer.Frame(
+          new Map([
+            [
+              12,
+              [
+                new Series(
+                  new Float32Array([1, 2, 3]),
+                  undefined,
+                  new TimeRange(40, 50000),
+                ),
+              ],
+            ],
+            [
+              13,
+              [
+                new Series(
+                  new Float32Array([1, 2, 3]),
+                  undefined,
+                  new TimeRange(500, 50001),
+                ),
+              ],
+            ],
+          ]),
+        );
+        expect(f.timeRange()).toEqual(new TimeRange(40, 50001));
+      });
+    });
+
+    describe("key provided", () => {
+      it("should return the time range of the key", () => {
+        const f = new framer.Frame({
+          a: new Series(
+            new Float32Array([1, 2, 3]),
+            undefined,
+            new TimeRange(40, 50000),
+          ),
+          b: new Series(
+            new Float32Array([1, 2, 3]),
+            undefined,
+            new TimeRange(500, 50001),
+          ),
+        });
+        expect(f.timeRange("a")).toEqual(new TimeRange(40, 50000));
+      });
+    });
+
+    describe("filter", () => {
+      it("should return a frame filtered on a particular condition", () => {
+        const f = new framer.Frame(
+          new Map([
+            [
+              12,
+              [
+                new Series(
+                  new Float32Array([1, 2, 3]),
+                  undefined,
+                  new TimeRange(40, 50000),
+                ),
+              ],
+            ],
+            [
+              13,
+              [
+                new Series(
+                  new Float32Array([1, 2, 3]),
+                  undefined,
+                  new TimeRange(500, 50001),
+                ),
+              ],
+            ],
+          ]),
+        );
+        expect(f.filter((k) => k === 12).columns).toEqual([12]);
+      });
+    });
+  });
+
+  describe("toPayload", () => {
+    it("should return the frame as framer.FramePayload", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series(
+                new Float32Array([1, 2, 3]),
+                undefined,
+                new TimeRange(40, 50000),
+              ),
+            ],
+          ],
+          [
+            13,
+            [
+              new Series(
+                new Float32Array([1, 2, 3]),
+                undefined,
+                new TimeRange(500, 50001),
+              ),
+            ],
+          ],
+        ]),
+      );
+      const pld = f.toPayload();
+      expect(pld.keys).toEqual([12, 13]);
+      expect(pld.series?.[0].data.byteLength).toEqual(12);
+    });
+  });
+});