@synnaxlabs/x 0.40.0 → 0.42.0

package/src/errors/errors.spec.ts

@@ -0,0 +1,152 @@
+// Copyright 2025 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 { describe, expect, it, test } from "vitest";
+
+import { errors } from "@/errors";
+
+class ErrorOne extends errors.createTyped("one") {}
+
+class ErrorTwo extends errors.createTyped("two") {}
+
+class SubError extends ErrorOne.sub("child") {}
+
+const myCustomErrorEncoder = (error: errors.Typed): errors.Payload | null => {
+  if (error.type !== "one") return null;
+  return { type: "one", data: error.message };
+};
+
+const myCustomErrorDecoder = (encoded: errors.Payload): errors.Typed =>
+  new ErrorOne(encoded.data);
+
+describe("errors", () => {
+  describe("isTypedError", () => {
+    it("should return true if the error implements the TypedError interface", () => {
+      const error = new ErrorOne("test");
+      const fError = errors.isTyped(error);
+      expect(fError).toBeTruthy();
+      expect(error.type).toEqual("one");
+    });
+
+    it("should return false if the error does not implement the TypedError interface", () => {
+      const error = new Error("rando");
+      const fError = errors.isTyped(error);
+      expect(fError).toBeFalsy();
+    });
+  });
+
+  describe("encoding/decoding", () => {
+    it("should encode and decode a custom error through the registry", () => {
+      errors.register({
+        encode: myCustomErrorEncoder,
+        decode: myCustomErrorDecoder,
+      });
+      const error = new ErrorOne("test");
+      const encoded = errors.encode(error);
+      const decoded = errors.decode(encoded);
+      expect(ErrorOne.matches(decoded)).toBeTruthy();
+    });
+
+    test("should correctly encode/decode a null error", () => {
+      const encoded = errors.encode(null);
+      expect(encoded.type).toEqual(errors.NONE);
+      expect(encoded.data).toEqual("");
+      const decoded = errors.decode(encoded);
+      expect(decoded).toBeNull();
+    });
+
+    it("should correctly encode/decode an undefined error", () => {
+      const encoded = errors.encode(undefined);
+      expect(encoded.type).toEqual(errors.NONE);
+      expect(encoded.data).toEqual("");
+      const decoded = errors.decode(encoded);
+      expect(decoded).toBeNull();
+    });
+
+    it("should correctly encode/decode a generic error", () => {
+      const error = new Error("test");
+      const encoded = errors.encode(error);
+      expect(encoded.type).toEqual(errors.UNKNOWN);
+      expect(encoded.data).toEqual("test");
+      const decoded = errors.decode(encoded);
+      expect(decoded).toBeInstanceOf(Error);
+      expect((decoded as Error).message).toEqual(error.message);
+    });
+
+    it("should correctly encode/decode a string that is not an error", () => {
+      const error = "test";
+      const encoded = errors.encode(error);
+      expect(encoded.type).toEqual(errors.UNKNOWN);
+      expect(encoded.data).toEqual("test");
+      const decoded = errors.decode(encoded);
+      expect(errors.Unknown.matches(decoded)).toBeTruthy();
+    });
+
+    it("should correctly encode/decode a random object", () => {
+      const error = { foo: "bar" };
+      const encoded = errors.encode(error);
+      expect(encoded.type).toEqual(errors.UNKNOWN);
+      expect(encoded.data).toEqual(JSON.stringify(error));
+      const decoded = errors.decode(encoded);
+      expect(errors.Unknown.matches(decoded)).toBeTruthy();
+    });
+  });
+
+  describe("matches", () => {
+    it("should return true if the errors are exactly the same", () => {
+      const v = new ErrorOne("test");
+      expect(ErrorOne.matches(v)).toBeTruthy();
+      const v2 = new ErrorOne("test");
+      expect(v2.matches(v)).toBeTruthy();
+    });
+
+    it("should return false if the errors are typed and clearly different", () => {
+      const e1 = new ErrorOne("test");
+      const e2 = new ErrorTwo("test");
+      expect(e1.matches(e2)).toBeFalsy();
+      expect(ErrorOne.matches(e2)).toBeFalsy();
+      expect(ErrorTwo.matches(e1)).toBeFalsy();
+    });
+
+    it("should return false if the error is not typed", () => {
+      const e1 = new ErrorOne("test");
+      const e2 = new Error("rando");
+      expect(e1.matches(e2)).toBeFalsy();
+      expect(ErrorOne.matches(e2)).toBeFalsy();
+    });
+
+    it("should return false if the error is not actually an error", () => {
+      const e1 = new ErrorOne("test");
+      const e2 = "rando";
+      expect(e1.matches(e2)).toBeFalsy();
+      expect(ErrorOne.matches(e2)).toBeFalsy();
+    });
+
+    it("should return false if hte error is undefined", () => {
+      const e1 = new ErrorOne("test");
+      const e2 = undefined;
+      expect(e1.matches(e2)).toBeFalsy();
+      expect(ErrorOne.matches(e2)).toBeFalsy();
+    });
+
+    it("should return true if the the matching error is a parent", () => {
+      const e1 = new ErrorOne("rando");
+      const e2 = new SubError("rando");
+      expect(e1.matches(e2)).toBeTruthy();
+      expect(ErrorOne.matches(e1)).toBeTruthy();
+    });
+
+    it("should return false if the matching error is a sub-error", () => {
+      const e1 = new ErrorOne("random");
+      const e2 = new SubError("random");
+      expect(e2.matches(e1)).toBeFalsy();
+      expect(SubError.matches(e1)).toBeFalsy();
+    });
+  });
+});

package/src/errors/errors.ts

@@ -7,20 +7,235 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-class Canceled extends Error {
-  static readonly MESSAGE = "canceled";
-  constructor() {
-    super(Canceled.MESSAGE);
+import { z } from "zod";
+
+import { singleton } from "@/singleton";
+
+/**
+ * @returns general function that returns true if an error matches a set of
+ * abstracted criteria
+ */
+export type Matcher = (e: string | Error | unknown) => boolean;
+
+/** @description an error type that can match against other errors. */
+export interface Matchable {
+  /**
+   * @returns a function that matches errors of the given type. Returns true if
+   * the provided instance of Error or a string message contains the provided error type.
+   */
+  matches: Matcher;
+}
+
+/**
+ * @description an error that has a network-portable type, allowing it to be encoded/
+ * decoded by freighter. Also allows for simpler matching using @method matches instead
+ * of using instanceof, which has a number of caveats.
+ */
+export interface Typed extends Error, Matchable {
+  discriminator: "FreighterError";
+  /**
+   * @description Returns a unique type identifier for the error. Freighter uses this to
+   * determine the correct decoder to use on the other end of the freighter.
+   */
+  type: string;
+}
+
+/**
+ * @description a class that, when constructed, implements the TypedError interface.
+ * Also provides utilities for matching and creating subclasses.
+ */
+export interface TypedClass extends Matchable {
+  /**
+   * @description constructs a new TypedError. Identical to the Error constructor.
+   * @param message - the error message.
+   * @param options - the error options.
+   * @returns a new TypedError.
+   */
+  new (message?: string, options?: ErrorOptions): Typed;
+  /**
+   * @description the type of the error.
+   */
+  TYPE: string;
+  /**
+   * @description creates a new subclass of the error that extends its type. So if
+   * the type of this class is `dog` and subType is `labrador`, the type of the new
+   * class will be `dog.labrador`.
+   * @param subType - the type of the new error.
+   * @returns a new TypedErrorClass.
+   */
+  sub: (subType: string) => TypedClass;
+}
+
+/**
+ * @param type - the error type to match
+ * @returns a function that matches errors of the given type. Returns true if
+ * the provided instance of Error or a string message contains the provided error type.
+ */
+const createTypeMatcher =
+  (type: string): Matcher =>
+  (e) => {
+    if (e != null && typeof e === "object" && "type" in e && typeof e.type === "string")
+      return e.type.startsWith(type);
+    if (e instanceof Error) return e.message.startsWith(type);
+    if (typeof e !== "string") return false;
+    return e.startsWith(type);
+  };
+
+/**
+ * Creates a new class definition that implements the TypedErrorClass interface.
+ * @param type - the type of the error.
+ * @returns a new TypedErrorClass.
+ * @example
+ * ```ts
+ * class MyError extends createTypedError("my_error") {}
+ * ```
+ */
+export const createTyped = (type: string): TypedClass =>
+  class Internal extends Error implements Typed {
+    static readonly discriminator = "FreighterError";
+    readonly discriminator = Internal.discriminator;
+
+    static readonly TYPE = type;
+    readonly type: string = Internal.TYPE;
+
+    static readonly matches = createTypeMatcher(type);
+    readonly matches: Matcher = Internal.matches;
+
+    constructor(message?: string, options?: ErrorOptions) {
+      super(message, options);
+      this.name = Internal.TYPE;
+    }
+    static sub(subType: string): TypedClass {
+      return createTyped(`${type}.${subType}`);
+    }
+  };
+
+/**
+ * @description Function that decodes an encoded error payload back into an error object
+ * @param encoded - The encoded error payload to decode
+ * @returns The decoded error object or null if the decoder cannot handle this error type
+ */
+export type Decoder = (encoded: Payload) => Error | null;
+
+/**
+ * @description Function that encodes a typed error into a network-portable payload
+ * @param error - The typed error to encode
+ * @returns The encoded error payload or null if the encoder cannot handle this error type
+ */
+export type Encoder = (error: Typed) => Payload | null;
+
+/**
+ * @description Checks if an unknown value is a TypedError
+ * @param error - The value to check
+ * @returns True if the value is a TypedError, false otherwise
+ */
+export const isTyped = (error: unknown): error is Typed => {
+  if (error == null || typeof error !== "object") return false;
+  const typedError = error as Typed;
+  if (typedError.discriminator !== "FreighterError") return false;
+  if (!("type" in typedError))
+    throw new Error(
+      `Freighter error is missing its type property: ${JSON.stringify(typedError)}`,
+    );
+  return true;
+};
+
+/** @description Constant representing an unknown error type */
+export const UNKNOWN = "unknown";
+
+/** @description Constant representing no error (null) */
+export const NONE = "nil";
+
+interface provider {
+  encode: Encoder;
+  decode: Decoder;
+}
+
+class Registry {
+  private readonly providers: provider[] = [];
+
+  register(provider: provider): void {
+    this.providers.push(provider);
   }
 
-  /** Returns true if the error or message is a cancellation error" */
-  matches(e: Error | string): boolean {
-    if (typeof e === "string") return e.includes(Canceled.MESSAGE);
-    return e instanceof Canceled || e.message.includes(Canceled.MESSAGE);
+  encode(error: unknown): Payload {
+    if (error == null) return { type: NONE, data: "" };
+    if (isTyped(error))
+      for (const provider of this.providers) {
+        const payload = provider.encode(error);
+        if (payload != null) return payload;
+      }
+    if (error instanceof Error) return { type: UNKNOWN, data: error.message };
+    if (typeof error === "string") return { type: UNKNOWN, data: error };
+    try {
+      return { type: UNKNOWN, data: JSON.stringify(error) };
+    } catch {
+      return { type: UNKNOWN, data: "unable to encode error information" };
+    }
+  }
+
+  decode(payload?: Payload | null): Error | null {
+    if (payload == null || payload.type === NONE) return null;
+    if (payload.type === UNKNOWN) return new Unknown(payload.data);
+    for (const provider of this.providers) {
+      const error = provider.decode(payload);
+      if (error != null) return error;
+    }
+    return new Unknown(payload.data);
   }
 }
 
+const getRegistry = singleton.define("synnax-error-registry", () => new Registry());
+
 /**
- * CANCELED should be thrown to indicate the cancellation of an operation.
+ * Registers a custom error type with the error registry, which allows it to be
+ * encoded/decoded and sent over the network.
+ *
+ * @param type - A unique string identifier for the error type.
+ * @param encode - A function that encodes the error into a string.
+ * @param decode - A function that decodes the error from a string.
  */
-export const CANCELED = new Canceled();
+export const register = ({
+  encode,
+  decode,
+}: {
+  encode: Encoder;
+  decode: Decoder;
+}): void => getRegistry().register({ encode, decode });
+
+/**
+ * Encodes an error into a payload that can be sent between a freighter server
+ * and client.
+ * @param error - The error to encode.
+ * @returns The encoded error.
+ */
+export const encode = (error: unknown): Payload => getRegistry().encode(error);
+
+/**
+ * Decodes an error payload into an exception. If a custom decoder can be found
+ * for the error type, it will be used. Otherwise, a generic Error containing
+ * the error data is returned.
+ *
+ * @param payload - The encoded error payload.
+ * @returns The decoded error.
+ */
+export const decode = (payload?: Payload | null): Error | null => {
+  if (payload == null) return null;
+  return getRegistry().decode(payload);
+};
+
+/**
+ * @description Generic error for representing unknown errors
+ */
+export class Unknown extends createTyped("unknown") {}
+
+/** @description Zod schema for validating error payloads */
+export const payloadZ = z.object({ type: z.string(), data: z.string() });
+
+/** @description Network-portable representation of an error */
+export type Payload = z.infer<typeof payloadZ>;
+
+/** @description Error for representing the cancellation of an operation */
+export class Canceled extends createTyped("canceled") {}
+
+export type Return<T> = [T, null] | [null, Error];

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "@/breaker";
 export * from "@/caseconv";
 export * from "@/change";
 export * from "@/clamp/clamp";
+export * from "@/color";
 export * from "@/compare";
 export * from "@/control";
 export * from "@/debounce/debounce";
@@ -26,17 +27,21 @@ export * from "@/kv";
 export * from "@/link";
 export * from "@/math";
 export * from "@/migrate";
+export * from "@/notation";
 export * from "@/observe";
 export * from "@/optional";
 export * from "@/primitive";
 export * from "@/record";
 export * from "@/renderable";
+export * from "@/replace";
 export * from "@/runtime";
 export * from "@/runtime";
 export * from "@/search";
 export * from "@/shallowCopy";
+export * from "@/sleep";
 export * from "@/spatial";
 export * from "@/strings";
+export * from "@/sync";
 export * from "@/telem";
 export * from "@/toArray";
 export * from "@/transform";

package/src/jsonrpc/jsonrpc.ts

@@ -7,15 +7,19 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+import z from "zod";
+
 import { binary } from "@/binary";
 
-export interface Message {
-  jsonrpc: string;
-  id?: number;
-  method?: string;
-  params?: unknown;
-  result?: unknown;
-}
+const messageZ = z.object({
+  jsonrpc: z.string(),
+  id: z.number().optional(),
+  method: z.string().optional(),
+  params: z.unknown().optional(),
+  result: z.unknown().optional(),
+});
+
+export type Message = z.infer<typeof messageZ>;
 
 export interface ChunkParser {
   (chunk: Uint8Array | ArrayBuffer | string): void;
@@ -77,7 +81,7 @@ export const streamDecodeChunks = (
         buffer = buffer.slice(expectedLength);
         expectedLength = null;
         const messageStr = decoder.decode(messageBytes);
-        const parsed = binary.JSON_CODEC.decodeString(messageStr);
+        const parsed = binary.JSON_CODEC.decodeString(messageStr, messageZ);
         onMessage(parsed);
       } else break;
     }

package/src/math/external.ts

@@ -0,0 +1,11 @@
+// Copyright 2025 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 "@/math/math";
+export * from "@/math/round";

package/src/math/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as math from "@/math/math";
+export * as math from "@/math/external";

package/src/math/round.spec.ts

@@ -0,0 +1,81 @@
+// Copyright 2025 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 { describe, expect, it } from "vitest";
+
+import { math } from "@/math";
+import { type bounds } from "@/spatial";
+
+interface TestCase {
+  name: string;
+  value: number;
+  bounds: bounds.Bounds<number>;
+  expected: number;
+}
+
+const TEST_CASES: TestCase[] = [
+  {
+    name: "should handle large spans (>= 1000)",
+    value: 1234.5678,
+    bounds: { lower: 0, upper: 2000 },
+    expected: 1234.57,
+  },
+  {
+    name: "should handle medium spans (>= 1)",
+    value: 1.23456,
+    bounds: { lower: 0, upper: 2 },
+    expected: 1.235,
+  },
+  {
+    name: "should handle small spans (< 1)",
+    value: 0.123456,
+    bounds: { lower: 0, upper: 0.2 },
+    expected: 0.123,
+  },
+  {
+    name: "should handle very small spans",
+    value: 0.0001234,
+    bounds: { lower: 0, upper: 0.0002 },
+    expected: 0.000123,
+  },
+  {
+    name: "should handle negative values",
+    value: -1.23456,
+    bounds: { lower: -2, upper: 0 },
+    expected: -1.235,
+  },
+  {
+    name: "should handle NaN",
+    value: NaN,
+    bounds: { lower: 0, upper: 1 },
+    expected: NaN,
+  },
+  {
+    name: "should handle Infinity",
+    value: Infinity,
+    bounds: { lower: 0, upper: 1 },
+    expected: Infinity,
+  },
+  {
+    name: "should handle zero span bounds",
+    value: 1.23456,
+    bounds: { lower: 1, upper: 1 },
+    expected: 1.23456,
+  },
+];
+
+describe("roundBySpan", () => {
+  TEST_CASES.forEach(({ name, value, bounds, expected }) => {
+    it(name, () => {
+      const result = math.roundBySpan(value, bounds);
+      if (Number.isNaN(expected)) expect(Number.isNaN(result)).toBe(true);
+      else expect(result).toBe(expected);
+    });
+  });
+});

package/src/math/round.ts

@@ -0,0 +1,68 @@
+// Copyright 2025 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 { bounds } from "@/spatial/bounds";
+
+const LARGE_SPAN_DECIMAL_PLACES = 2;
+const MEDIUM_SPAN_DECIMAL_PLACES = 3;
+
+// The number of additional decimal places to show past the precision of the span.
+const EXTRA_DECIMAL_PLACES = 2;
+
+/**
+ * Rounds a number  based on the span of the provided bounds. The function adjusts the
+ * number of decimal places based on the magnitude of the bounds.
+ *
+ * @param value - The number to be rounded.
+ * @param bounds - The bounds object containing the min and max values that provide
+ * context for rounding.
+ * @returns The rounded number.
+ *
+ * Rules for decimal places:
+ * - For spans >= 1000: 2 decimal places
+ * - For spans >= 1: 3 decimal places
+ * - For spans < 1: 2 decimal places + 2 decimal places past the precision of the span
+ *
+ * Edge cases:
+ * - If the value is `NaN`, returns `NaN`
+ * - If the value is `Infinity` or `-Infinity`, returns the original value
+ * - If the bounds span is 0, returns the original value
+ *
+ * Examples:
+ * ```typescript
+ * // Large spans (>= 1000) use 2 decimal places
+ * roundBySpan(1234.5678, { start: 0, end: 2000 }); // 1200
+ *
+ * // Medium spans (>= 1) use 3 decimal places
+ * roundBySpan(1.23456, { start: 0, end: 2 }); // 1.235
+ *
+ * // Small spans (< 1) adapt based on the span
+ * roundBySpan(0.123456, { start: 0, end: 0.2 }); // 0.123 = 1 + 2 decimal places
+ * roundBySpan(0.0001234, { start: 0, end: 0.001 }); // 0.00012 = 3 + 2 decimal places
+ *
+ * // Edge cases
+ * roundBySpan(NaN, { start: 0, end: 1 }); // NaN
+ * roundBySpan(Infinity, { start: 0, end: 1 }); // Infinity
+ * roundBySpan(123, { start: 1, end: 1 }); // 123 (span is 0)
+ * ```
+ */
+export const roundBySpan = (value: number, b: bounds.Bounds<number>): number => {
+  if (Number.isNaN(value) || !Number.isFinite(value)) return value;
+  const span = bounds.span(b);
+  if (span == 0) return value;
+  let decimalPlaces: number;
+  if (span >= 1000) decimalPlaces = LARGE_SPAN_DECIMAL_PLACES;
+  else if (span >= 1) decimalPlaces = MEDIUM_SPAN_DECIMAL_PLACES;
+  else {
+    const decimalPlacesInSpan = Math.ceil(-Math.log10(span));
+    decimalPlaces = decimalPlacesInSpan + EXTRA_DECIMAL_PLACES;
+  }
+  const multiplier = 10 ** decimalPlaces;
+  return Math.round(value * multiplier) / multiplier;
+};

package/src/migrate/migrate.ts

@@ -189,8 +189,8 @@ export const migrator = <
         return def;
       }
       try {
-        if (targetSchema != null) return targetSchema.parse(v);
-        return v;
+        if (targetSchema != null) return targetSchema.parse(v) as O;
+        return v as unknown as O;
       } catch (e) {
         console.log(`${name} failed to parse default. Exiting with default`);
         console.error(e);

package/src/notation/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2025 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 * as notation from "@/notation/notation";