@synnaxlabs/client 0.20.0 → 0.22.0

package/src/client.ts

@@ -7,7 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { TimeSpan, TimeStamp, URL } from "@synnaxlabs/x";
+import { TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
+import { URL } from "@synnaxlabs/x/url";
 import { z } from "zod";
 
 import { auth } from "@/auth";
@@ -26,8 +27,20 @@ import { Transport } from "@/transport";
 import { workspace } from "@/workspace";
 
 export const synnaxPropsZ = z.object({
-  host: z.string().min(1),
-  port: z.number().or(z.string()),
+  host: z
+    .string({
+      required_error: "Host is required",
+    })
+    .min(1, "Host is required"),
+  port: z
+    .number({
+      required_error: "Port is required",
+    })
+    .or(
+      z.string({
+        required_error: "Port is required",
+      }),
+    ),
   username: z.string().optional(),
   password: z.string().optional(),
   connectivityPollFrequency: TimeSpan.z.default(TimeSpan.seconds(30)),
@@ -105,36 +118,26 @@ export default class Synnax extends framer.Client {
       props.name,
     );
     this.ontology = new ontology.Client(transport.unary, this);
-    const rangeRetriever = new ranger.Retriever(transport.unary);
     const rangeWriter = new ranger.Writer(this.transport.unary);
     this.labels = new label.Client(this.transport.unary, this);
     this.ranges = new ranger.Client(
       this,
-      rangeRetriever,
       rangeWriter,
       this.transport.unary,
       chRetriever,
       this.labels,
     );
     this.workspaces = new workspace.Client(this.transport.unary);
-    const devices = new device.Client(
-      new device.Retriever(this.transport.unary),
-      new device.Writer(this.transport.unary),
-      this,
-    );
-    const taskRetriever = new task.Retriever(this.transport.unary);
-    const taskWriter = new task.Writer(this.transport.unary);
-    const tasks = new task.Client(taskRetriever, taskWriter);
-    const racks = new rack.Client(
-      new rack.Retriever(this.transport.unary),
-      new rack.Writer(this.transport.unary),
-      this,
-      taskWriter,
-      taskRetriever,
-    );
+    const devices = new device.Client(this.transport.unary, this);
+    const tasks = new task.Client(this.transport.unary, this);
+    const racks = new rack.Client(this.transport.unary, this, tasks);
     this.hardware = new hardware.Client(tasks, racks, devices);
   }
 
+  get key(): string {
+    return this.createdAt.valueOf().toString();
+  }
+
   close(): void {
     this.connectivity.stopChecking();
   }

package/src/connection/checker.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import type { UnaryClient } from "@synnaxlabs/freighter";
-import { TimeSpan } from "@synnaxlabs/x";
+import { TimeSpan } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 const STATUSES = ["disconnected", "connecting", "connected", "failed"] as const;

package/src/connection/connection.spec.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { URL } from "@synnaxlabs/x";
+import { URL } from "@synnaxlabs/x/url";
 import { describe, expect, it } from "vitest";
 
 import { auth } from "@/auth";
@@ -22,13 +22,8 @@ describe("connectivity", () => {
       username: "synnax",
       password: "seldon",
     });
-    await client.authenticating;
-    expect(client.authenticated).toBeTruthy();
-
     transport.use(client.middleware());
-
     const connectivity = new Checker(transport.unary);
-
     await connectivity.check();
     expect(connectivity.state.status).toEqual("connected");
   });

package/src/control/state.ts

@@ -7,7 +7,9 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type Destructor, binary, observe } from "@synnaxlabs/x";
+import { binary } from "@synnaxlabs/x/binary";
+import { type Destructor } from "@synnaxlabs/x/destructor";
+import { observe } from "@synnaxlabs/x/observe";
 import { z } from "zod";
 
 import { type Key as ChannelKey } from "@/channel/payload";

package/src/errors.ts

@@ -8,77 +8,58 @@
 // 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",
-}
+const _FREIGHTER_EXCEPTION_PREFIX = "sy.";
 
 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];
-    }
-  }
+export class ValidationError extends Error {
+  static readonly TYPE = _FREIGHTER_EXCEPTION_PREFIX + "validation";
 }
 
-/**
- * GeneralError is raised when a general error occurs.
- */
-export class GeneralError extends BaseError {}
+export class FieldError extends ValidationError {
+  static readonly TYPE = ValidationError.TYPE + ".field";
+  readonly field: string;
+  readonly message: string;
+
+  constructor(field: string, message: string) {
+    super(field + ": " + message);
+    this.field = field;
+    this.message = message;
+  }
+}
 
 /**
- * ParseError is raised when a parse error occurs.
+ * AuthError is raised when an authentication error occurs.
  */
-export class ParseError extends BaseError {}
+export class AuthError extends Error {
+  static readonly TYPE = _FREIGHTER_EXCEPTION_PREFIX + "auth";
+}
 
 /**
- * AuthError is raised when an authentication error occurs.
+ * InvalidTokenError is raised when an authentication token is invalid.
  */
-export class AuthError extends BaseError {}
+export class InvalidTokenError extends AuthError {
+  static readonly TYPE = AuthError.TYPE + ".invalid-token";
+}
 
 /**
  * UnexpectedError is raised when an unexpected error occurs.
  */
-export class UnexpectedError extends BaseError {
+export class UnexpectedError extends Error {
+  static readonly TYPE = _FREIGHTER_EXCEPTION_PREFIX + "unexpected";
+
   constructor(message: string) {
     super(`
     Unexpected error encountered:
@@ -93,16 +74,23 @@ export class UnexpectedError extends BaseError {
 /**
  * QueryError is raised when a query error occurs.
  */
-export class QueryError extends BaseError {}
+export class QueryError extends Error {
+  static readonly TYPE = _FREIGHTER_EXCEPTION_PREFIX + "query";
+}
 
-export class NotFoundError extends QueryError {}
+export class NotFoundError extends QueryError {
+  static readonly TYPE = QueryError.TYPE + ".not_found";
+}
 
-export class MultipleFoundError extends QueryError {}
+export class MultipleFoundError extends QueryError {
+  static readonly TYPE = QueryError.TYPE + ".multiple_results";
+}
 
 /**
  * RouteError is raised when a routing error occurs.
  */
-export class RouteError extends BaseError {
+export class RouteError extends Error {
+  static readonly TYPE = _FREIGHTER_EXCEPTION_PREFIX + "route";
   path: string;
 
   constructor(message: string, path: string) {
@@ -114,28 +102,44 @@ export class RouteError extends BaseError {
 /**
  * Raised when time-series data is not contiguous.
  */
-export class ContiguityError extends BaseError {}
+export class ContiguityError extends Error {}
 
 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);
+  if (payload.type.startsWith(ValidationError.TYPE)) {
+    if (payload.type === FieldError.TYPE) {
+      const values = payload.data.split(": ");
+      if (values.length < 2) {
+        return new ValidationError(payload.data);
+      }
+      return new FieldError(values[0], values[1]);
+    }
+    return new ValidationError(payload.data);
+  }
+
+  if (payload.type.startsWith(AuthError.TYPE)) {
+    if (payload.type.startsWith(InvalidTokenError.TYPE))
+      return new InvalidTokenError(payload.data);
+    return new AuthError(payload.data);
   }
+
+  if (payload.type.startsWith(UnexpectedError.TYPE)) {
+    return new UnexpectedError(payload.data);
+  }
+
+  if (payload.type.startsWith(QueryError.TYPE)) {
+    if (payload.type.startsWith(NotFoundError.TYPE))
+      return new NotFoundError(payload.data);
+    if (payload.type.startsWith(MultipleFoundError.TYPE))
+      return new MultipleFoundError(payload.data);
+    return new QueryError(payload.data);
+  }
+
+  if (payload.type.startsWith(RouteError.TYPE)) {
+    return new RouteError(payload.data, payload.data);
+  }
+
+  return new UnexpectedError(payload.data);
 };
 
 const encode = (): ErrorPayload => {
@@ -149,7 +153,7 @@ export const validateFieldNotNull = (
   value: unknown,
   message: string = "must be provided",
 ): void => {
-  if (value == null) throw new ValidationError({ field: key, message });
+  if (value == null) throw new FieldError(key, message);
 };
 
 export const errorsMiddleware: Middleware = async (ctx, next) => {

package/src/framer/adapter.spec.ts

@@ -1,4 +1,4 @@
-import { DataType, Series, TimeStamp } from "@synnaxlabs/x";
+import { DataType, Series, TimeStamp } from "@synnaxlabs/x/telem";
 import { beforeAll, describe, expect, it } from "vitest";
 
 import { type channel } from "@/channel";
@@ -115,4 +115,36 @@ describe("WriteFrameAdapter", () => {
     expect(res.get(timeCh.key)).toHaveLength(1);
     expect(res.get(timeCh.key).at(0)).toEqual(ts);
   });
+
+  it("should correctly adapt a name and JSON value", async () => {
+    const jsonChannel = await client.channels.create({
+      name: `json-${Math.random()}-${TimeStamp.now().toString()}`,
+      dataType: DataType.JSON,
+      virtual: true,
+    });
+    const adapter = await WriteFrameAdapter.open(client.channels.retriever, [
+      jsonChannel.key,
+    ]);
+    const res = await adapter.adapt(jsonChannel.name, [{ dog: "blue" }]);
+    expect(res.columns).toHaveLength(1);
+    expect(res.series).toHaveLength(1);
+    expect(res.get(jsonChannel.key)).toHaveLength(1);
+    expect(res.get(jsonChannel.key).at(0)).toEqual({ dog: "blue" });
+  });
+
+  it("should correctly adapt a name and a json typed series", async () => {
+    const jsonChannel = await client.channels.create({
+      name: `json-${Math.random()}-${TimeStamp.now().toString()}`,
+      dataType: DataType.JSON,
+      virtual: true,
+    });
+    const adapter = await WriteFrameAdapter.open(client.channels.retriever, [
+      jsonChannel.key,
+    ]);
+    const res = await adapter.adapt(jsonChannel.name, new Series([{ dog: "blue" }]));
+    expect(res.columns).toHaveLength(1);
+    expect(res.series).toHaveLength(1);
+    expect(res.get(jsonChannel.key)).toHaveLength(1);
+    expect(res.get(jsonChannel.key).at(0)).toEqual({ dog: "blue" });
+  });
 });

package/src/framer/adapter.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type CrudeSeries, Series } from "@synnaxlabs/x";
+import { type CrudeSeries, Series } from "@synnaxlabs/x/telem";
 
 import {
   type Key,
@@ -16,7 +16,11 @@ import {
   type KeyOrName,
   type Payload,
 } from "@/channel/payload";
-import { type Retriever, analyzeParams, retrieveRequired } from "@/channel/retriever";
+import {
+  type Retriever,
+  analyzeChannelParams,
+  retrieveRequired,
+} from "@/channel/retriever";
 import { ValidationError } from "@/errors";
 import { type CrudeFrame, Frame } from "@/framer/frame";
 
@@ -38,10 +42,10 @@ export class ReadFrameAdapter {
   }
 
   async update(channels: Params): Promise<void> {
-    const { variant, normalized } = analyzeParams(channels);
+    const { variant, normalized } = analyzeChannelParams(channels);
     if (variant === "keys") {
       this.adapter = null;
-      this.keys = normalized;
+      this.keys = normalized as Key[];
       return;
     }
     const fetched = await this.retriever.retrieve(normalized);
@@ -111,12 +115,12 @@ export class WriteFrameAdapter {
         Received a single channel name or key but no series.
         `);
       if (Array.isArray(series)) {
-        if (series.length > 1) {
+        if (series.some((s) => s instanceof Series || Array.isArray(s))) {
           throw new ValidationError(`
           Received a single channel name or key but multiple series.
           `);
         }
-        series = series[0] as CrudeSeries;
+        series = series as CrudeSeries;
       }
       const pld = await this.fetchChannel(columnsOrData);
       const s = new Series({ data: series as CrudeSeries, dataType: pld.dataType });

package/src/framer/client.ts

@@ -13,10 +13,10 @@ import {
   type CrudeSeries,
   type CrudeTimeRange,
   type MultiSeries,
-} from "@synnaxlabs/x";
+} from "@synnaxlabs/x/telem";
 
-import { type KeysOrNames, type KeyOrName, type Params } from "@/channel/payload";
-import { type Retriever, analyzeParams } from "@/channel/retriever";
+import { KeysOrNames, type KeyOrName, type Params } from "@/channel/payload";
+import { type Retriever, analyzeChannelParams } from "@/channel/retriever";
 import { Frame } from "@/framer/frame";
 import { Iterator } from "@/framer/iterator";
 import { Streamer, type StreamerConfig } from "@/framer/streamer";
@@ -45,12 +45,13 @@ export class Client {
   /**
    * 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.
+   * @param config - The configuration for the created writer, see documentation for
+   * writerConfig for more detail.
    * @returns a new {@link RecordWriter}.
    */
-  async openWriter(config: WriterConfig): Promise<Writer> {
+  async openWriter(config: WriterConfig | Params): Promise<Writer> {
+    if (Array.isArray(config) || typeof config !== "object")
+      config = { channels: config as Params };
     return await Writer._open(this.retriever, this.stream, config);
   }
 
@@ -76,12 +77,12 @@ export class Client {
    * and then will start reading new values.
    *
    */
-  async openStreamer(config: StreamerConfig): Promise<Streamer>;
+  async openStreamer(config: StreamerConfig | Params): Promise<Streamer>;
 
   async openStreamer(config: StreamerConfig | Params): Promise<Streamer> {
-    const isObject = typeof config === "object";
-    if (Array.isArray(config) || !isObject) config = { channels: config as Params };
-    return await Streamer._open(this.retriever, this.stream, config as StreamerConfig);
+    if (Array.isArray(config) || typeof config !== "object")
+      config = { channels: config as Params };
+    return await Streamer._open(this.retriever, this.stream, config);
   }
 
   async write(
@@ -148,7 +149,7 @@ export class Client {
   async read(tr: CrudeTimeRange, channels: Params): Promise<Frame>;
 
   async read(tr: CrudeTimeRange, channels: Params): Promise<MultiSeries | Frame> {
-    const { single } = analyzeParams(channels);
+    const { single } = analyzeChannelParams(channels);
     const fr = await this.readFrame(tr, channels);
     if (single) return fr.get(channels as KeyOrName);
     return fr;

package/src/framer/frame.spec.ts

@@ -7,7 +7,7 @@
 // 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 { DataType, Series, TimeRange } from "@synnaxlabs/x/telem";
 import { describe, expect, it, test } from "vitest";
 
 import { framer } from "@/framer";

package/src/framer/frame.ts

@@ -11,13 +11,13 @@ import {
   Size,
   Series,
   TimeRange,
-  toArray,
   DataType,
-  unique,
   TimeStamp,
   type TelemValue,
   MultiSeries,
-} from "@synnaxlabs/x";
+} from "@synnaxlabs/x/telem";
+import { toArray } from "@synnaxlabs/x/toArray";
+import { unique } from "@synnaxlabs/x/unique";
 import { z } from "zod";
 
 import {
@@ -142,8 +142,8 @@ export class Frame {
     }
 
     throw new ValidationError(
-      `[Frame] - invalid frame construction parameters. data parameter ust be a frame 
-    payload, a list of lazy arrays, a lazy array, a map, or a record keyed by channel 
+      `[Frame] - invalid frame construction parameters. data parameter ust be a frame
+    payload, a list of lazy arrays, a lazy array, a map, or a record keyed by channel
     name. keys parameter must be a set of channel keys or channel names.`,
     );
   }
@@ -398,7 +398,10 @@ export class Frame {
 
 export const series = z.object({
   timeRange: TimeRange.z.optional(),
-  alignment: z.number().optional(),
+  alignment: z
+    .bigint()
+    .or(z.string().transform((s) => BigInt(s)))
+    .optional(),
   dataType: DataType.z,
   data: z.string().transform(
     (s) =>

package/src/framer/iterator.spec.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { DataType, Rate, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x";
+import { DataType, Rate, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, test, expect } from "vitest";
 
 import { type channel } from "@/channel";

package/src/framer/iterator.ts

@@ -15,7 +15,7 @@ import {
   TimeSpan,
   TimeStamp,
   type CrudeTimeRange,
-} from "@synnaxlabs/x";
+} from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 import { type Params } from "@/channel/payload";

package/src/framer/streamProxy.ts

@@ -33,19 +33,18 @@ export class StreamProxy<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny> {
 
   async closeAndAck(): Promise<void> {
     this.stream.closeSend();
-    const [res, err] = await this.stream.receive();
-    if (res != null)
-      throw new UnexpectedError(
-        `${this.name} received unexpected response on closure. 
-        Please report this error to the Synnax team.`,
-      );
-    if (err == null)
-      throw new UnexpectedError(
-        `${this.name} received unexpected null error on closure. 
-        Please report this error to Synnax team.
-      `,
-      );
-    if (!(err instanceof EOF)) throw err;
+    while (true) {
+      const [res, err] = await this.stream.receive();
+      if (res != null)
+        console.warn(
+          `${this.name} received unexpected response on closure. 
+        Please report this error to the Synnax team. ${JSON.stringify(res)}`,
+        );
+      if (err != null) {
+        if (err instanceof EOF) return;
+        throw err;
+      }
+    }
   }
 
   closeSend(): void {

package/src/framer/streamer.spec.ts

@@ -7,8 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { DataType, Rate, TimeStamp } from "@synnaxlabs/x";
 import { describe, test, expect, it } from "vitest";
+import { DataType, Rate, TimeStamp } from "@synnaxlabs/x/telem";
 
 import { type channel } from "@/channel";
 import { newClient } from "@/setupspecs";

package/src/framer/streamer.ts

@@ -8,7 +8,8 @@
 // included in the file licenses/APL.txt.
 
 import { errorZ, type Stream, type StreamClient } from "@synnaxlabs/freighter";
-import { TimeStamp, type CrudeTimeStamp } from "@synnaxlabs/x";
+import { observe } from "@synnaxlabs/x";
+import { TimeStamp, type CrudeTimeStamp } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 import { type Key, type Params } from "@/channel/payload";
@@ -88,3 +89,26 @@ export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
     return this;
   }
 }
+
+export class ObservableStreamer<V = Frame>
+  extends observe.Observer<Frame, V>
+  implements observe.ObservableAsyncCloseable<V>
+{
+  private readonly streamer: Streamer;
+  private readonly closePromise: Promise<void>;
+
+  constructor(streamer: Streamer, transform?: observe.Transform<Frame, V>) {
+    super(transform);
+    this.streamer = streamer;
+    this.closePromise = this.stream();
+  }
+
+  async close(): Promise<void> {
+    this.streamer.close();
+    await this.closePromise;
+  }
+
+  private async stream(): Promise<void> {
+    for await (const frame of this.streamer) this.notify(frame);
+  }
+}