@synnaxlabs/client 0.2.1 → 0.13.6

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);
+    });
+  });
+});