@synnaxlabs/x 0.41.0 → 0.42.1

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";
@@ -32,12 +33,15 @@ 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/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/primitive.ts

@@ -41,6 +41,6 @@ export const primitiveIsZero = <V extends Primitive>(value: V): boolean => {
     case "undefined":
       return true;
     case "object":
-      return value === null;
+      return true;
   }
 };

package/src/record.ts

@@ -13,6 +13,8 @@ export type Key = string | number;
 
 export type UnknownRecord = Record<Key, unknown>;
 
+export type UnknownStringRecord = Record<string, unknown>;
+
 export interface Keyed<K extends Key> {
   key: K;
 }
@@ -40,4 +42,6 @@ export const mapValues = <T extends Record<Key, unknown>, U>(
   obj: T,
   fn: (value: T[keyof T], key: Key) => U,
 ): Record<Key, U> =>
-  Object.fromEntries(getEntries(obj).map(([key, value]) => [key, fn(value, key as Key)]));
+  Object.fromEntries(
+    getEntries(obj).map(([key, value]) => [key, fn(value, key as Key)]),
+  );

package/src/replace.ts

@@ -0,0 +1 @@
+export type Replace<T, R> = Omit<T, keyof R> & R;

package/src/singleton/define.spec.ts

@@ -0,0 +1,93 @@
+// 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 { define } from "@/singleton/define";
+
+describe("define", () => {
+  it("should create and return a singleton instance", () => {
+    const key = "test-singleton-1";
+    let constructorCallCount = 0;
+
+    const createInstance = () => {
+      constructorCallCount++;
+      return { value: "singleton-value" };
+    };
+
+    const getInstance = define(key, createInstance);
+    const instance1 = getInstance();
+
+    expect(constructorCallCount).toBe(1);
+    expect(instance1).toEqual({ value: "singleton-value" });
+
+    const instance2 = getInstance();
+    expect(constructorCallCount).toBe(1);
+    expect(instance2).toBe(instance1); // Same instance reference
+  });
+
+  it("should maintain separate singletons for different keys", () => {
+    const key1 = "test-singleton-2";
+    const key2 = "test-singleton-3";
+
+    const getInstance1 = define(key1, () => ({ id: 1 }));
+    const getInstance2 = define(key2, () => ({ id: 2 }));
+
+    const instance1 = getInstance1();
+    const instance2 = getInstance2();
+
+    expect(instance1).toEqual({ id: 1 });
+    expect(instance2).toEqual({ id: 2 });
+    expect(instance1).not.toBe(instance2);
+  });
+
+  it("should retrieve the same singleton when defining with the same key multiple times", () => {
+    const key = "test-singleton-4";
+    let constructorCallCount = 0;
+
+    const createInstance1 = () => {
+      constructorCallCount++;
+      return { id: constructorCallCount };
+    };
+
+    const getInstance1 = define(key, createInstance1);
+    const firstInstance = getInstance1();
+    expect(firstInstance).toEqual({ id: 1 });
+    expect(constructorCallCount).toBe(1);
+
+    // Second definition with the same key but different factory
+    const createInstance2 = () => {
+      constructorCallCount++;
+      return { id: 999 }; // Different value
+    };
+
+    const getInstance2 = define(key, createInstance2);
+    const secondInstance = getInstance2();
+
+    expect(secondInstance).toBe(firstInstance);
+    expect(secondInstance).toEqual({ id: 1 });
+    expect(constructorCallCount).toBe(1); // Still 1, not 2
+  });
+
+  it("should handle object instances as singleton values", () => {
+    class TestClass {
+      public value: number;
+      constructor(value: number) {
+        this.value = value;
+      }
+    }
+
+    const key = "test-singleton-5";
+    const getInstance = define(key, () => new TestClass(42));
+
+    const instance = getInstance();
+    expect(instance).toBeInstanceOf(TestClass);
+    expect(instance.value).toBe(42);
+  });
+});

package/src/singleton/define.ts

@@ -0,0 +1,27 @@
+// 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.
+
+const isDefined = (key: symbol): boolean =>
+  Object.getOwnPropertySymbols(globalThis).includes(key);
+
+/**
+ * Defines a new global singleton instance of a value.
+ *
+ * @param key - The unique identifier for the singleton.
+ * @param value - A function that returns the singleton instance.
+ * @returns A function that returns the singleton instance.
+ */
+export const define = <T>(key: string, value: () => T): (() => T) => {
+  const symbol = Symbol.for(key);
+  if (!isDefined(symbol)) {
+    const singleton = value();
+    Object.defineProperty(globalThis, symbol, { value: singleton });
+  }
+  return () => (globalThis as any)[symbol] as T;
+};

package/src/singleton/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 singleton from "@/singleton/define";

package/src/sync/index.ts

@@ -0,0 +1 @@
+export * as sync from "@/sync/mutex";

package/src/sync/mutex.ts

@@ -0,0 +1,16 @@
+import { Mutex as Core } from "async-mutex";
+
+export type Mutex<G> = G & Core;
+
+export class mutex<G> extends Core {
+  static new<G>(guard: G): Mutex<G> & G {
+    return new mutex(guard) as Mutex<G> & G;
+  }
+
+  constructor(guard: G) {
+    super();
+    Object.assign(this, guard);
+  }
+}
+
+export const newMutex = <G>(guard: G): Mutex<G> => new mutex(guard) as Mutex<G>;