@synnaxlabs/client 0.17.6 → 0.18.1

package/src/framer/frame.spec.ts

@@ -400,4 +400,110 @@ describe("framer.Frame", () => {
       expect(f.latest()).toEqual({ 12: 3, 13: 3 });
     });
   });
+
+  describe("sample access", () => {
+    it("should return the sample at the given index", () => {
+      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.get(12).at(0)).toEqual(1);
+    });
+  });
+
+  describe("at", () => {
+    it("should return the sample at the given index", () => {
+      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.at(0)).toEqual({ 12: 1, 13: 1 });
+    });
+    it("should throw an error if required is true and the index is out of bounds", () => {
+      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.at(3, true)).toThrow();
+    });
+    it("should return undefined if required is false and the index is out of bounds", () => {
+      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]),
+                timeRange: new TimeRange(500, 50001),
+              }),
+            ],
+          ],
+        ]),
+      );
+      expect(f.at(2)).toEqual({ 12: 3, 13: undefined });
+    });
+  });
 });

package/src/framer/frame.ts

@@ -16,6 +16,7 @@ import {
   unique,
   TimeStamp,
   type TelemValue,
+  MultiSeries,
 } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -34,6 +35,7 @@ const columnType = (columns: Params): ColumnType => {
   const arrKeys = toArray(columns);
   if (arrKeys.length === 0) return null;
   if (typeof arrKeys[0] === "number") return "key";
+  if (!isNaN(parseInt(arrKeys[0]))) return "key";
   return "name";
 };
 
@@ -252,18 +254,11 @@ export class Frame {
     }
     const group = this.get(col);
     if (group == null) return TimeRange.ZERO;
-    return new TimeRange(
-      group[0].timeRange.start,
-      group[group.length - 1].timeRange.end,
-    );
+    return group.timeRange;
   }
 
-  latest(): Record<string, TelemValue> {
-    return Object.fromEntries(
-      this.columns
-        .map((c, i) => [c, this.series[i].at(-1)])
-        .filter(([_, v]) => v != null),
-    );
+  latest(): Record<string, TelemValue | undefined> {
+    return this.at(-1);
   }
 
   get timeRanges(): TimeRange[] {
@@ -274,7 +269,7 @@ export class Frame {
    * @returns lazy arrays matching the given channel key or name.
    * @param key the channel key or name.
    */
-  get(key: KeyOrName): Series[];
+  get(key: KeyOrName): MultiSeries;
 
   /**
    * @returns a frame with the given channel keys or names.
@@ -282,9 +277,9 @@ export class Frame {
    */
   get(keys: Keys | Names): Frame;
 
-  get(key: KeyOrName | Keys | Names): Series[] | Frame {
+  get(key: KeyOrName | Keys | Names): MultiSeries | Frame {
     if (Array.isArray(key)) return this.filter((k) => (key as Keys).includes(k as Key));
-    return this.series.filter((_, i) => this.columns[i] === key);
+    return new MultiSeries(this.series.filter((_, i) => this.columns[i] === key));
   }
 
   /**
@@ -364,6 +359,18 @@ export class Frame {
     });
   }
 
+  at(index: number, required: true): Record<KeyOrName, TelemValue>;
+
+  at(index: number, required?: false): Record<KeyOrName, TelemValue | undefined>;
+
+  at(index: number, required = false): Record<KeyOrName, TelemValue | undefined> {
+    const res: Record<KeyOrName, TelemValue> = {};
+    this.uniqueColumns.forEach((k) => {
+      res[k] = this.get(k).at(index, required as true);
+    });
+    return res;
+  }
+
   /**
    * @returns a new frame containing all typed arrays in the current frame that pass
    * the provided filter function.

package/src/framer/iterator.spec.ts

@@ -28,7 +28,7 @@ const newChannel = async (): Promise<channel.Channel> => {
 describe("Iterator", () => {
   test("happy path", async () => {
     const ch = await newChannel();
-    const writer = await client.telem.newWriter({
+    const writer = await client.telem.openWriter({
       start: TimeStamp.SECOND,
       channels: ch.key,
     });
@@ -42,7 +42,7 @@ describe("Iterator", () => {
       await writer.close();
     }
 
-    const iter = await client.telem.newIterator(
+    const iter = await client.telem.openIterator(
       new TimeRange(TimeSpan.ZERO, TimeSpan.seconds(4)),
       [ch.key],
     );
@@ -52,7 +52,7 @@ describe("Iterator", () => {
       let c = 0;
       while (await iter.next(TimeSpan.seconds(1))) {
         c++;
-        expect(iter.value.get(ch.key)[0]).toHaveLength(25);
+        expect(iter.value.get(ch.key)).toHaveLength(25);
       }
       expect(c).toEqual(3);
     } finally {

package/src/framer/streamer.spec.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { DataType, Rate, TimeStamp } from "@synnaxlabs/x";
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, it } from "vitest";
 
 import { type channel } from "@/channel";
 import { newClient } from "@/setupspecs";
@@ -26,9 +26,9 @@ const newChannel = async (): Promise<channel.Channel> =>
 describe("Streamer", () => {
   test("happy path", async () => {
     const ch = await newChannel();
-    const streamer = await client.telem.newStreamer(ch.key);
+    const streamer = await client.telem.openStreamer(ch.key);
     await new Promise((resolve) => setTimeout(resolve, 100));
-    const writer = await client.telem.newWriter({
+    const writer = await client.telem.openWriter({
       start: TimeStamp.now(),
       channels: ch.key,
     });
@@ -38,6 +38,18 @@ describe("Streamer", () => {
       await writer.close();
     }
     const d = await streamer.read();
-    expect(d.get(ch.key)[0].data).toEqual(new Float64Array([1, 2, 3]));
+    expect(Array.from(d.get(ch.key))).toEqual([1, 2, 3]);
+  });
+  test("open with config", async () => {
+    const ch = await newChannel();
+    await expect(
+      client.telem.openStreamer({
+        channels: ch.key,
+        from: TimeStamp.now(),
+      }),
+    ).resolves.not.toThrow();
+  });
+  it("should not throw an error when the streamer is opened with zero channels", async () => {
+    await expect(client.telem.openStreamer([])).resolves.not.toThrow();
   });
 });

package/src/framer/streamer.ts

@@ -29,6 +29,11 @@ const resZ = z.object({
 
 const ENDPOINT = "/frame/stream";
 
+export interface StreamerConfig {
+  channels: Params;
+  from?: CrudeTimeStamp;
+}
+
 export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
   private readonly adapter: ReadFrameAdapter;
@@ -46,15 +51,14 @@ export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
   }
 
   static async _open(
-    start: CrudeTimeStamp,
-    channels: Params,
     retriever: Retriever,
     client: StreamClient,
+    { channels, from }: StreamerConfig,
   ): Promise<Streamer> {
     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 });
+    stream.send({ start: new TimeStamp(from), keys: adapter.keys });
     return streamer;
   }
 

package/src/framer/writer.spec.ts

@@ -29,7 +29,7 @@ describe("Writer", () => {
   describe("Writer", () => {
     test("basic write", async () => {
       const ch = await newChannel();
-      const writer = await client.telem.newWriter({ start: 0, channels: ch.key });
+      const writer = await client.telem.openWriter({ start: 0, channels: ch.key });
       try {
         await writer.write(ch.key, randomSeries(10, ch.dataType));
         await writer.commit();
@@ -40,7 +40,7 @@ describe("Writer", () => {
     });
     test("write to unknown channel key", async () => {
       const ch = await newChannel();
-      const writer = await client.telem.newWriter({ start: 0, channels: ch.key });
+      const writer = await client.telem.openWriter({ start: 0, channels: ch.key });
       await expect(
         writer.write("billy bob", randomSeries(10, DataType.FLOAT64)),
       ).rejects.toThrow("Channel billy bob not found");
@@ -48,8 +48,8 @@ describe("Writer", () => {
     });
     test("stream when mode is set ot persist only", async () => {
       const ch = await newChannel();
-      const stream = await client.telem.newStreamer(ch.key);
-      const writer = await client.telem.newWriter({
+      const stream = await client.telem.openStreamer(ch.key);
+      const writer = await client.telem.openWriter({
         start: 0,
         channels: ch.key,
         mode: WriterMode.PersistOnly,

package/src/framer/writer.ts

@@ -74,8 +74,8 @@ const resZ = z.object({
 type Response = z.infer<typeof resZ>;
 
 export interface WriterConfig {
-  start: CrudeTimeStamp;
   channels: Params;
+  start?: CrudeTimeStamp;
   controlSubject?: ControlSubject;
   authorities?: Authority | Authority[];
   mode?: WriterMode;
@@ -83,35 +83,35 @@ export interface WriterConfig {
 
 /**
  * Writer is used to write telemetry to a set of channels in time order.
- * It should not be instantiated directly, and should instead be instantited via the
+ * It should not be instantiated directly, and should instead be instantiated via the
  * FramerClient {@link FrameClient#openWriter}.
  *
- * The writer is a streaming protocol that is heavily optimized for prerformance. This
- * comes at the cost of icnreased complexity, and should only be used directly when
- * writing large volumes of data (such as recording telemetry from a sensor or ingsting
- * data froma file). Simpler methods (such as the frame client's write method) should
+ * The writer is a streaming protocol that is heavily optimized for performance. This
+ * comes at the cost of increased complexity, and should only be used directly when
+ * writing large volumes of data (such as recording telemetry from a sensor or ingesting
+ * data from file). Simpler methods (such as the frame client's write method) should
  * be used for most use cases.
  *
  * The protocol is as follows:
  *
  * 1. The writer is opened with a starting timestamp and a list of channel keys. The
- * writer will fail to open if the starting timstamp overlaps with any existing telemetry
- * for any channels specified. If the writer opens successfuly, the caller is then
+ * writer will fail to open if the starting timestamp overlaps with any existing telemetry
+ * for any channels specified. If the writer opens successfully, the caller is then
  * free to write frames to the writer.
  *
  * 2. To write a frame, the caller can use the write method and follow the validation
  * rules described in its method's documentation. This process is asynchronous, meaning
  * that write calls may return before teh frame has been written to the cluster. This
  * also means that the writer can accumulate an error after write is called. If the writer
- * accumulates an erorr, all subsequent write and commit calls will return False. The
- * caller can check for errors by calling the error mehtod, which returns the accumulated
+ * accumulates an error, all subsequent write and commit calls will return False. The
+ * caller can check for errors by calling the error method, which returns the accumulated
  * error and resets the writer for future use. The caller can also check for errors by
  * closing the writer, which will throw any accumulated error.
  *
  * 3. To commit the written frames to the cluster, the caller can call the commit method.
  * Unlike write, commit is synchronous, meaning that it will not return until the frames
- * have been written to the cluster. If the writer has accumulated an erorr, commit will
- * return false. After the caller acknowledges the erorr, they can attempt to commit again.
+ * have been written to the cluster. If the writer has accumulated an error, commit will
+ * return false. After the caller acknowledges the error, they can attempt to commit again.
  * Commit can be called several times throughout a writer's lifetime, and will only
  * commit the frames that have been written since the last commit.
  *
@@ -137,10 +137,10 @@ export class Writer {
     client: StreamClient,
     {
       channels,
+      start = TimeStamp.now(),
       authorities = Authority.Absolute,
       controlSubject: subject,
-      start,
-      mode,
+      mode = WriterMode.PersistStream,
     }: WriterConfig,
   ): Promise<Writer> {
     const adapter = await WriteFrameAdapter.open(retriever, channels);

package/src/index.ts

@@ -35,6 +35,7 @@ export {
   TimeRange,
   TimeSpan,
   TimeStamp,
+  MultiSeries,
 } from "@synnaxlabs/x";
 export type {
   TypedArray,
@@ -44,7 +45,8 @@ export type {
   CrudeSize,
   CrudeTimeSpan,
   CrudeTimeStamp,
-  SampleValue,
+  TelemValue,
+  NumericTelemValue,
   TimeStampStringFormat,
   TZInfo,
 } from "@synnaxlabs/x";

package/src/ontology/signals.ts

@@ -72,15 +72,15 @@ export class ChangeTracker {
     if (allResources.length > 0) this.resourceObs.notify(resSets.concat(resDeletes));
     const relSets = this.parseRelationshipSets(frame);
     const relDeletes = this.parseRelationshipDeletes(frame);
-    const allRels = relSets.concat(relDeletes);
-    if (allRels.length > 0) this.relationshipObs.notify(relSets.concat(relDeletes));
+    const allRelationships = relSets.concat(relDeletes);
+    if (allRelationships.length > 0)
+      this.relationshipObs.notify(relSets.concat(relDeletes));
   }
 
   private parseRelationshipSets(frame: Frame): RelationshipChange[] {
     const relationships = frame.get(RELATIONSHIP_SET_NAME);
     if (relationships.length === 0) return [];
-    // We should only ever get one series of relationships
-    return relationships[0].toStrings().map((rel) => ({
+    return Array.from(relationships.as("string")).map((rel) => ({
       variant: "set",
       key: parseRelationship(rel),
       value: undefined,
@@ -90,8 +90,7 @@ export class ChangeTracker {
   private parseRelationshipDeletes(frame: Frame): RelationshipChange[] {
     const relationships = frame.get(RELATIONSHIP_DELETE_NAME);
     if (relationships.length === 0) return [];
-    // We should only ever get one series of relationships
-    return relationships[0].toStrings().map((rel) => ({
+    return Array.from(relationships.as("string")).map((rel) => ({
       variant: "delete",
       key: parseRelationship(rel),
     }));
@@ -101,7 +100,7 @@ export class ChangeTracker {
     const sets = frame.get(RESOURCE_SET_NAME);
     if (sets.length === 0) return [];
     // We should only ever get one series of sets
-    const ids = sets[0].toStrings().map((id) => new ID(id));
+    const ids = Array.from(sets.as("string")).map((id: string) => new ID(id));
     try {
       const resources = await this.retriever.retrieve(ids);
       return resources.map((resource) => ({
@@ -122,13 +121,14 @@ export class ChangeTracker {
     const deletes = frame.get(RESOURCE_DELETE_NAME);
     if (deletes.length === 0) return [];
     // We should only ever get one series of deletes
-    return deletes[0]
-      .toStrings()
-      .map((str) => ({ variant: "delete", key: new ID(str) }));
+    return Array.from(deletes.as("string")).map((str) => ({
+      variant: "delete",
+      key: new ID(str),
+    }));
   }
 
   static async open(client: FrameClient, retriever: Retriever): Promise<ChangeTracker> {
-    const streamer = await client.newStreamer([
+    const streamer = await client.openStreamer([
       RESOURCE_SET_NAME,
       RESOURCE_DELETE_NAME,
       RELATIONSHIP_SET_NAME,

package/src/signals/observable.ts

@@ -55,11 +55,11 @@ export class Observable<K, V>
       const changes: Array<change.Change<K, V>> = [];
       if (this.deleteChannel != null) {
         const deletes = frame.get(this.deleteChannel);
-        changes.push(...deletes.flatMap((s) => this.decoder("delete", s)));
+        changes.push(...deletes.series.flatMap((s) => this.decoder("delete", s)));
       }
       if (this.setChannel != null) {
         const sets = frame.get(this.setChannel);
-        changes.push(...sets.flatMap((s) => this.decoder("set", s)));
+        changes.push(...sets.series.flatMap((s) => this.decoder("set", s)));
       }
       this.base.notify(changes);
     }
@@ -71,7 +71,7 @@ export class Observable<K, V>
     deleteChannel: channel.Key | channel.Name,
     ecd: Decoder<K, V>,
   ): Promise<Observable<K, V>> {
-    const stream = await client.newStreamer([
+    const stream = await client.openStreamer([
       setChannel,
       deleteChannel,
     ] as channel.Keys);