@synnaxlabs/client 0.17.3 → 0.17.5

package/src/framer/adapter.ts

@@ -7,12 +7,20 @@
 // 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 CrudeSeries, Series } from "@synnaxlabs/x";
+
+import {
+  type Key,
+  type Name,
+  type Params,
+  type KeyOrName,
+  type Payload,
+} from "@/channel/payload";
+import { type Retriever, analyzeParams, retrieveRequired } from "@/channel/retriever";
 import { ValidationError } from "@/errors";
-import { type Frame } from "@/framer/frame";
+import { type CrudeFrame, Frame } from "@/framer/frame";
 
-export class BackwardFrameAdapter {
+export class ReadFrameAdapter {
   private adapter: Map<Key, Name> | null;
   retriever: Retriever;
   keys: Key[];
@@ -23,11 +31,8 @@ export class BackwardFrameAdapter {
     this.keys = [];
   }
 
-  static async open(
-    retriever: Retriever,
-    channels: Params,
-  ): Promise<BackwardFrameAdapter> {
-    const adapter = new BackwardFrameAdapter(retriever);
+  static async open(retriever: Retriever, channels: Params): Promise<ReadFrameAdapter> {
+    const adapter = new ReadFrameAdapter(retriever);
     await adapter.update(channels);
     return adapter;
   }
@@ -50,10 +55,10 @@ export class BackwardFrameAdapter {
     this.keys = Array.from(this.adapter.keys());
   }
 
-  adapt(fr: Frame): Frame {
-    if (this.adapter == null) return fr;
+  adapt(columnsOrData: Frame): Frame {
+    if (this.adapter == null) return columnsOrData;
     const a = this.adapter;
-    return fr.map((k, arr) => {
+    return columnsOrData.map((k, arr) => {
       if (typeof k === "number") {
         const name = a.get(k);
         if (name == null) throw new Error(`Channel ${k} not found`);
@@ -64,7 +69,7 @@ export class BackwardFrameAdapter {
   }
 }
 
-export class ForwardFrameAdapter {
+export class WriteFrameAdapter {
   private adapter: Map<Name, Key> | null;
   retriever: Retriever;
   keys: Key[];
@@ -78,46 +83,100 @@ export class ForwardFrameAdapter {
   static async open(
     retriever: Retriever,
     channels: Params,
-  ): Promise<ForwardFrameAdapter> {
-    const adapter = new ForwardFrameAdapter(retriever);
+  ): Promise<WriteFrameAdapter> {
+    const adapter = new WriteFrameAdapter(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 ValidationError(`Channel ${name} was not provided in the list of channels when opening the writer`);
-      a.set(channel.name, channel.key);
-    });
-    this.keys = fetched.map((c) => c.key);
+    const results = await retrieveRequired(this.retriever, channels);
+    this.adapter = new Map<Name, Key>(results.map((c) => [c.name, c.key]));
+    this.keys = results.map((c) => c.key);
   }
 
-  adapt(fr: Frame): Frame {
-    if (this.adapter == null) {
-      // assert that every col if of type number
-      fr.columns.forEach((col) => { 
-        if (typeof col !== "number") throw new ValidationError(`Channel ${col} was not provided in the list of channels when opening the writer`);
-      });
-      return fr;
+  private async fetchChannel(ch: Key | Name): Promise<Payload> {
+    const res = await this.retriever.retrieve(ch);
+    if (res.length === 0) throw new Error(`Channel ${ch} not found`);
+    return res[0];
+  }
+
+  async adapt(
+    columnsOrData: Params | Record<KeyOrName, CrudeSeries> | CrudeFrame,
+    series?: CrudeSeries | CrudeSeries[],
+  ): Promise<Frame> {
+    if (typeof columnsOrData === "string" || typeof columnsOrData === "number") {
+      if (series == null)
+        throw new ValidationError(`
+        Received a single channel name or key but no series.
+        `);
+      if (Array.isArray(series)) {
+        if (series.length > 1) {
+          throw new ValidationError(`
+          Received a single channel name or key but multiple series.
+          `);
+        }
+        series = series[0] as CrudeSeries;
+      }
+      const pld = await this.fetchChannel(columnsOrData);
+      const s = new Series({ data: series as CrudeSeries, dataType: pld.dataType });
+      return new Frame(pld.key, s);
     }
-    const a = this.adapter;
-    return fr.map((col, arr) => {
-      if (typeof col === "string") {
-        const key = a.get(col);
-        if (key == null) throw new Error(`Channel ${col} not found`);
-        return [key, arr];
+
+    if (Array.isArray(columnsOrData)) {
+      if (series == null)
+        throw new ValidationError(`
+          Received an array of channel names or keys but no series.
+          `);
+      if (!Array.isArray(series))
+        throw new ValidationError(`
+        Received an array of channel names or keys but no array of series.
+        `);
+      const cols = [];
+      const data = [];
+      for (let i = 0; i < columnsOrData.length; i++) {
+        const pld = await this.fetchChannel(columnsOrData[i]);
+        if (i >= series.length) {
+          throw new ValidationError(`
+          Received an array of channel names or keys but not enough series.
+          `);
+        }
+        const s = new Series({
+          data: series[i] as CrudeSeries,
+          dataType: pld.dataType,
+        });
+        cols.push(pld.key);
+        data.push(s);
       }
-      return [col, arr];
-    });
+      return new Frame(cols, data);
+    }
+
+    if (columnsOrData instanceof Frame || columnsOrData instanceof Map) {
+      const fr = new Frame(columnsOrData);
+      if (this.adapter == null) return fr;
+      let cols: Key[] = [];
+      cols = fr.columns.map((col_) => {
+        const col = typeof col_ === "string" ? this.adapter?.get(col_) : col_;
+        if (col == null)
+          throw new ValidationError(`
+          Channel ${col_} was not provided in the list of channels when opening the writer
+        `);
+        return col;
+      });
+      return new Frame(cols, fr.series);
+    }
+
+    const cols = [];
+    const data = [];
+    const kvs = Object.entries(columnsOrData);
+    for (let i = 0; i < kvs.length; i++) {
+      const [k, v] = kvs[i];
+      const pld = await this.fetchChannel(k);
+      const s = new Series({ data: v, dataType: pld.dataType });
+      cols.push(pld.key);
+      data.push(s);
+    }
+
+    return new Frame(cols, data);
   }
 }

package/src/framer/client.ts

@@ -9,7 +9,7 @@
 
 import { type StreamClient } from "@synnaxlabs/freighter";
 import {
-  type NativeTypedArray,
+  type TypedArray,
   type Series,
   type TimeRange,
   type CrudeTimeStamp,
@@ -84,11 +84,7 @@ export class Client {
    * data type as the channel.
    * @throws if the channel does not exist.
    */
-  async write(
-    to: KeyOrName,
-    start: CrudeTimeStamp,
-    data: NativeTypedArray,
-  ): Promise<void> {
+  async write(to: KeyOrName, start: CrudeTimeStamp, data: TypedArray): Promise<void> {
     const w = await this.newWriter({
       start,
       channels: to,

package/src/framer/frame.spec.ts

@@ -19,9 +19,9 @@ describe("framer.Frame", () => {
         const f = new framer.Frame(
           ["a", "b", "c"],
           [
-            new Series({data: new Float32Array([1, 2, 3])}),
-            new Series({data: new Float32Array([1, 2, 3])}),
-            new Series({data: new Float32Array([1, 2, 3])}),
+            new Series({ data: new Float32Array([1, 2, 3]) }),
+            new Series({ data: new Float32Array([1, 2, 3]) }),
+            new Series({ data: new Float32Array([1, 2, 3]) }),
           ],
         );
         expect(f.length).toEqual(9);
@@ -32,9 +32,9 @@ describe("framer.Frame", () => {
         const f = new framer.Frame(
           [12, 13, 14],
           [
-            new Series({data: new Float32Array([1, 2, 3])}),
-            new Series({data: new Float32Array([1, 2, 3])}),
-            new Series({data: new Float32Array([1, 2, 3])}),
+            new Series({ data: new Float32Array([1, 2, 3]) }),
+            new Series({ data: new Float32Array([1, 2, 3]) }),
+            new Series({ data: new Float32Array([1, 2, 3]) }),
           ],
         );
         expect(f.length).toEqual(9);
@@ -42,25 +42,35 @@ describe("framer.Frame", () => {
       });
 
       test("from a single name and an array of arrays", () => {
-        const f = new framer.Frame("a", [new Series({data: new Float32Array([1, 2, 3])})]);
+        const f = new framer.Frame("a", [
+          new Series({ data: 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({data: new Float32Array([1, 2, 3])})]);
+        const f = new framer.Frame(12, [
+          new Series({ data: 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({data: new Float32Array([1, 2, 3])}));
+        const f = new framer.Frame(
+          12,
+          new Series({ data: 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({data: new Float32Array([1, 2, 3])}));
+        const f = new framer.Frame(
+          "a",
+          new Series({ data: new Float32Array([1, 2, 3]) }),
+        );
         expect(f.length).toEqual(3);
         expect(f.colType).toEqual("name");
       });
@@ -82,7 +92,7 @@ describe("framer.Frame", () => {
 
       test("from record", () => {
         const f = new framer.Frame({
-          a: new Series({data: new Float32Array([1, 2, 3])}),
+          a: new Series({ data: new Float32Array([1, 2, 3]) }),
         });
         expect(f.length.valueOf()).toEqual(3);
         expect(f.columns.length).toEqual(1);
@@ -91,7 +101,7 @@ describe("framer.Frame", () => {
 
       test("from map", () => {
         const f = new framer.Frame(
-          new Map([[12, new Series({data: new Float32Array([1, 2, 3])})]]),
+          new Map([[12, new Series({ data: new Float32Array([1, 2, 3]) })]]),
         );
         expect(f.length).toEqual(3);
         expect(f.columns.length).toEqual(1);
@@ -106,8 +116,8 @@ describe("framer.Frame", () => {
             new framer.Frame(
               ["a", "b", "c"],
               [
-                new Series({data: new Float32Array([1, 2, 3])}),
-                new Series({data: new Float32Array([1, 2, 3])}),
+                new Series({ data: new Float32Array([1, 2, 3]) }),
+                new Series({ data: new Float32Array([1, 2, 3]) }),
               ],
             ),
         ).toThrow();
@@ -119,12 +129,12 @@ describe("framer.Frame", () => {
     it("should return false if a key has more than one array", () => {
       const f = new framer.Frame(
         new Map([
-          [12, [new Series({data: new Float32Array([1, 2, 3])})]],
+          [12, [new Series({ data: new Float32Array([1, 2, 3]) })]],
           [
             13,
             [
-              new Series({data: new Float32Array([1, 2, 3])}),
-              new Series({data: new Float32Array([1, 2, 3])}),
+              new Series({ data: new Float32Array([1, 2, 3]) }),
+              new Series({ data: new Float32Array([1, 2, 3]) }),
             ],
           ],
         ]),
@@ -137,8 +147,8 @@ describe("framer.Frame", () => {
     it("should return false if there is more than one key", () => {
       const f = new framer.Frame(
         new Map([
-          [12, [new Series({data: new Float32Array([1, 2, 3])})]],
-          [13, [new Series({data: new Float32Array([1, 2, 3])})]],
+          [12, [new Series({ data: new Float32Array([1, 2, 3]) })]],
+          [13, [new Series({ data: new Float32Array([1, 2, 3]) })]],
         ]),
       );
       expect(f.isHorizontal).toEqual(false);
@@ -164,7 +174,7 @@ describe("framer.Frame", () => {
               new Series({
                 data: new Float32Array([1, 2, 3]),
                 timeRange: new TimeRange(500, 50000),
-    }),
+              }),
             ],
           ],
         ]),
@@ -181,7 +191,7 @@ describe("framer.Frame", () => {
               new Series({
                 data: new Float32Array([1, 2, 3]),
                 timeRange: new TimeRange(500, 50000),
-    }),
+              }),
             ],
           ],
           [
@@ -190,7 +200,7 @@ describe("framer.Frame", () => {
               new Series({
                 data: new Float32Array([1, 2, 3]),
                 timeRange: new TimeRange(500, 50001),
-    }),
+              }),
             ],
           ],
         ]),
@@ -201,7 +211,7 @@ describe("framer.Frame", () => {
 
   describe("timeRange", () => {
     describe("no key provided", () => {
-      it("should return the maxium time range of the frame", () => {
+      it("should return the maximum time range of the frame", () => {
         const f = new framer.Frame(
           new Map([
             [
@@ -210,7 +220,7 @@ describe("framer.Frame", () => {
                 new Series({
                   data: new Float32Array([1, 2, 3]),
                   timeRange: new TimeRange(40, 50000),
-      }),
+                }),
               ],
             ],
             [
@@ -219,7 +229,7 @@ describe("framer.Frame", () => {
                 new Series({
                   data: new Float32Array([1, 2, 3]),
                   timeRange: new TimeRange(500, 50001),
-      }),
+                }),
               ],
             ],
           ]),
@@ -234,11 +244,11 @@ describe("framer.Frame", () => {
           a: new Series({
             data: new Float32Array([1, 2, 3]),
             timeRange: new TimeRange(40, 50000),
-        }),
+          }),
           b: new Series({
             data: new Float32Array([1, 2, 3]),
             timeRange: new TimeRange(500, 50001),
-        }),
+          }),
         });
         expect(f.timeRange("a")).toEqual(new TimeRange(40, 50000));
       });
@@ -254,7 +264,7 @@ describe("framer.Frame", () => {
                 new Series({
                   data: new Float32Array([1, 2, 3]),
                   timeRange: new TimeRange(40, 50000),
-      }),
+                }),
               ],
             ],
             [
@@ -263,7 +273,7 @@ describe("framer.Frame", () => {
                 new Series({
                   data: new Float32Array([1, 2, 3]),
                   timeRange: new TimeRange(500, 50001),
-      }),
+                }),
               ],
             ],
           ]),
@@ -283,7 +293,7 @@ describe("framer.Frame", () => {
               new Series({
                 data: new Float32Array([1, 2, 3]),
                 timeRange: new TimeRange(40, 50000),
-    }),
+              }),
             ],
           ],
           [
@@ -292,7 +302,7 @@ describe("framer.Frame", () => {
               new Series({
                 data: new Float32Array([1, 2, 3]),
                 timeRange: new TimeRange(500, 50001),
-    }),
+              }),
             ],
           ],
         ]),
@@ -302,4 +312,65 @@ describe("framer.Frame", () => {
       expect(pld.series?.[0].data.byteLength).toEqual(12);
     });
   });
+
+  describe("latest", () => {
+    it("should return the latest sample from each column in the frame", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(40, 50000),
+              }),
+            ],
+          ],
+          [
+            13,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(500, 50001),
+              }),
+            ],
+          ],
+        ]),
+      );
+      expect(f.latest()).toEqual({ 12: 3, 13: 3 });
+    });
+    it("should return the latest sample for each col in the frame - even with multiple series per col", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(40, 50000),
+              }),
+              new Series({
+                data: new Float32Array([4, 5, 6]),
+                timeRange: new TimeRange(40, 50000),
+              }),
+            ],
+          ],
+          [
+            13,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(500, 50001),
+              }),
+              new Series({
+                data: new Float32Array([4, 5, 7]),
+                timeRange: new TimeRange(500, 50001),
+              }),
+            ],
+          ],
+        ]),
+      );
+      expect(f.latest()).toEqual({ 12: 6, 13: 7 });
+    });
+  });
 });

package/src/framer/frame.ts

@@ -7,7 +7,16 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { Size, Series, TimeRange, toArray, DataType, unique, TimeStamp } from "@synnaxlabs/x";
+import {
+  Size,
+  Series,
+  TimeRange,
+  toArray,
+  DataType,
+  unique,
+  TimeStamp,
+  type TelemValue,
+} from "@synnaxlabs/x";
 import { z } from "zod";
 
 import {
@@ -59,7 +68,7 @@ export type CrudeFrame =
  *
  * - 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.
+ * arrays for a particular channel can have gaps between 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
@@ -113,7 +122,7 @@ export class Frame {
         Object.entries(columnsOrData).forEach(([k, v]) => {
           const key = parseInt(k);
           if (!isNaN(key)) return this.push(key, ...toArray(v));
-          else this.push(k, ...toArray(v))
+          else this.push(k, ...toArray(v));
         });
       return;
     }
@@ -249,6 +258,14 @@ export class Frame {
     );
   }
 
+  latest(): Record<string, TelemValue> {
+    return Object.fromEntries(
+      this.columns
+        .map((c, i) => [c, this.series[i].at(-1)])
+        .filter(([_, v]) => v != null),
+    );
+  }
+
   get timeRanges(): TimeRange[] {
     return this.uniqueColumns.map((col) => this.timeRange(col));
   }
@@ -403,7 +420,7 @@ export type FramePayload = z.infer<typeof frameZ>;
 
 export const seriesFromPayload = (series: SeriesPayload): Series => {
   const { dataType, data, timeRange, alignment } = series;
-  return new Series({data, dataType, timeRange, glBufferUsage: "static", alignment});
+  return new Series({ data, dataType, timeRange, glBufferUsage: "static", alignment });
 };
 
 export const seriesToPayload = (series: Series): SeriesPayload => {

package/src/framer/iterator.ts

@@ -19,7 +19,7 @@ import { z } from "zod";
 
 import { type Params } from "@/channel/payload";
 import { type Retriever } from "@/channel/retriever";
-import { BackwardFrameAdapter } from "@/framer/adapter";
+import { ReadFrameAdapter } from "@/framer/adapter";
 import { Frame, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
 
@@ -72,12 +72,12 @@ const resZ = z.object({
 export class Iterator {
   private static readonly ENDPOINT = "/frame/iterate";
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
-  private readonly adapter: BackwardFrameAdapter;
+  private readonly adapter: ReadFrameAdapter;
   value: Frame;
 
   private constructor(
     stream: Stream<typeof reqZ, typeof resZ>,
-    adapter: BackwardFrameAdapter,
+    adapter: ReadFrameAdapter,
   ) {
     this.stream = new StreamProxy("Iterator", stream);
     this.value = new Frame();
@@ -97,7 +97,7 @@ export class Iterator {
     retriever: Retriever,
     client: StreamClient,
   ): Promise<Iterator> {
-    const adapter = await BackwardFrameAdapter.open(retriever, channels);
+    const adapter = await ReadFrameAdapter.open(retriever, channels);
     const stream = await client.stream(Iterator.ENDPOINT, reqZ, resZ);
     const iter = new Iterator(stream, adapter);
     await iter.execute({ command: Command.Open, keys: adapter.keys, bounds: tr });

package/src/framer/streamer.ts

@@ -13,7 +13,7 @@ import { z } from "zod";
 
 import { type Key, type Params } from "@/channel/payload";
 import { type Retriever } from "@/channel/retriever";
-import { BackwardFrameAdapter } from "@/framer/adapter";
+import { ReadFrameAdapter } from "@/framer/adapter";
 import { Frame, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
 
@@ -31,11 +31,11 @@ const ENDPOINT = "/frame/stream";
 
 export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
-  private readonly adapter: BackwardFrameAdapter;
+  private readonly adapter: ReadFrameAdapter;
 
   private constructor(
     stream: Stream<typeof reqZ, typeof resZ>,
-    adapter: BackwardFrameAdapter,
+    adapter: ReadFrameAdapter,
   ) {
     this.stream = new StreamProxy("Streamer", stream);
     this.adapter = adapter;
@@ -51,7 +51,7 @@ export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
     retriever: Retriever,
     client: StreamClient,
   ): Promise<Streamer> {
-    const adapter = await BackwardFrameAdapter.open(retriever, channels);
+    const adapter = await ReadFrameAdapter.open(retriever, channels);
     const stream = await client.stream(ENDPOINT, reqZ, resZ);
     const streamer = new Streamer(stream, adapter);
     stream.send({ start: new TimeStamp(start), keys: adapter.keys });

package/src/framer/writer.spec.ts

@@ -43,7 +43,7 @@ describe("Writer", () => {
       const writer = await client.telem.newWriter({ start: 0, channels: ch.key });
       await expect(
         writer.write("billy bob", randomSeries(10, DataType.FLOAT64)),
-      ).rejects.toThrow("Channel billy bob was not provided");
+      ).rejects.toThrow("Channel billy bob not found");
       await writer.close();
     });
     test("stream when mode is set ot persist only", async () => {