@synnaxlabs/x 0.42.3 → 0.44.0

package/src/deep/path.spec.ts

@@ -10,6 +10,7 @@
 import { describe, expect, it } from "vitest";
 
 import { deep } from "@/deep";
+import { type record } from "@/record";
 
 interface TestRecord {
   a: number;
@@ -72,8 +73,22 @@ describe("path", () => {
           }),
         ).toEqual(0);
       });
+
+      it("should get an array of keyed records", () => {
+        interface TestKeyedRecord {
+          values: record.KeyedNamed[];
+        }
+        const a: TestKeyedRecord = {
+          values: [
+            { key: "a", name: "a" },
+            { key: "b", name: "b" },
+          ],
+        };
+        expect(deep.get(a, "values.a.name")).toEqual("a");
+      });
     });
   });
+
   describe("set", () => {
     it("should set a key", () => {
       const a: TestRecord = {
@@ -111,6 +126,32 @@ describe("path", () => {
       deep.set(a, "c.1", 4);
       expect(a).toEqual(b);
     });
+
+    it("should set a value on a nested object in the array by key", () => {
+      const data = {
+        config: {
+          channels: [{ key: "tMnAnJeQmn6", type: "ai_voltage" }],
+        },
+      };
+      deep.set(data, "config.channels.tMnAnJeQmn6.type", "ai_force_bridge_table");
+      expect(data.config.channels[0].type).toEqual("ai_force_bridge_table");
+    });
+
+    it("should set an entire item in the array by its key", () => {
+      const data = {
+        config: {
+          channels: [{ key: "tMnAnJeQmn6", type: "ai_voltage" }],
+        },
+      };
+      deep.set(data, "config.channels.tMnAnJeQmn6", {
+        key: "tMnAnJeQmn6",
+        type: "ai_force_bridge_table",
+      });
+      expect(data.config.channels[0]).toEqual({
+        key: "tMnAnJeQmn6",
+        type: "ai_force_bridge_table",
+      });
+    });
   });
 
   describe("transformPath", () => {

package/src/deep/path.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { type Join } from "@/join";
-import { type UnknownRecord } from "@/record";
+import { type record } from "@/record";
 
 type Prev = [
   never,
@@ -53,7 +53,7 @@ export type Key<T, D extends number = 5> = [D] extends [never]
 /** Options for the get function. */
 export interface GetOptions<O extends boolean | undefined = boolean | undefined> {
   optional: O;
-  getter?: (obj: UnknownRecord, key: string) => unknown;
+  getter?: (obj: record.Unknown, key: string) => unknown;
   separator?: string;
 }
 
@@ -69,12 +69,12 @@ export interface GetOptions<O extends boolean | undefined = boolean | undefined>
  * @returns the value at the given path on the object.
  */
 export interface Get {
-  <V = unknown, T = UnknownRecord>(
+  <V = record.Unknown, T = record.Unknown>(
     obj: T,
     path: string,
     options?: GetOptions<false>,
   ): V;
-  <V = unknown, T = UnknownRecord>(
+  <V = record.Unknown, T = record.Unknown>(
     obj: T,
     path: string,
     options?: GetOptions<boolean | undefined>,
@@ -82,7 +82,7 @@ export interface Get {
 }
 
 /** A strongly typed version of the @link Get function. */
-export interface TypedGet<V = unknown, T = UnknownRecord> {
+export interface TypedGet<V = record.Unknown, T = record.Unknown> {
   (obj: T, path: string, options?: GetOptions<false>): V;
   (obj: T, path: string, options?: GetOptions<boolean | undefined>): V | null;
 }
@@ -116,6 +116,16 @@ export const transformPath = (
   return result.join(separator);
 };
 
+const defaultGetter = (obj: record.Unknown, key: string): unknown => {
+  if (!Array.isArray(obj)) return obj[key];
+  const res = obj[key];
+  if (res != null || obj.length == 0) return res;
+  const first = obj[0];
+  if (typeof first === "object" && "key" in first)
+    return obj.find((o) => o.key === key);
+  return undefined;
+};
+
 /**
  * Gets the value at the given path on the object. If the path does not exist
  * and the optional flag is set to true, null will be returned. If the path does
@@ -127,23 +137,23 @@ export const transformPath = (
  * @param opts.getter a custom getter function to use on each part of the path.
  * @returns the value at the given path on the object.
  */
-export const get = (<V = unknown, T = UnknownRecord>(
+export const get = (<V = record.Unknown, T = record.Unknown>(
   obj: T,
   path: string,
   opts: GetOptions = { optional: false, separator: "." },
 ): V | null => {
   opts.separator ??= ".";
-  const { optional, getter = (obj, key) => (obj)[key] } = opts;
+  const { optional, getter = defaultGetter } = opts;
   const parts = path.split(opts.separator);
-  if (parts.length === 1 && parts[0] === "") return obj as unknown as V;
-  let result: UnknownRecord = obj as UnknownRecord;
+  if (parts.length === 1 && parts[0] === "") return obj as record.Unknown as V;
+  let result: record.Unknown = obj as record.Unknown;
   for (const part of parts) {
     const v = getter(result, part);
     if (v == null) {
       if (optional) return null;
       throw new Error(`Path ${path} does not exist. ${part} is null`);
     }
-    result = v as UnknownRecord;
+    result = v as record.Unknown;
   }
   return result as V;
 }) as Get;
@@ -157,14 +167,32 @@ export const get = (<V = unknown, T = UnknownRecord>(
  */
 export const set = <V>(obj: V, path: string, value: unknown): void => {
   const parts = path.split(".");
-  let result: UnknownRecord = obj as UnknownRecord;
+  let result: record.Unknown = obj as record.Unknown;
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
-    result[part] ??= {};
-    result = result[part] as UnknownRecord;
+    const v = defaultGetter(result, part);
+    if (v == null) throw new Error(`Path ${path} does not exist. ${part} is null`);
+    result = v as record.Unknown;
   }
   try {
-    result[parts[parts.length - 1]] = value;
+    if (!Array.isArray(result)) {
+      result[parts[parts.length - 1]] = value;
+      return;
+    }
+    if (result.length === 0) return;
+    const index = parseInt(parts[parts.length - 1]);
+    if (isNaN(index)) {
+      const first = result[0];
+      if (typeof first === "object" && "key" in first) {
+        const objIndex = result.findIndex((o) => o.key === parts[parts.length - 1]);
+        if (objIndex !== -1) {
+          result[objIndex] = value;
+          return;
+        }
+      }
+      return;
+    }
+    result[index] = value;
   } catch (e) {
     console.error("failed to set value", value, "at path", path, "on object", obj);
     throw e;
@@ -179,11 +207,11 @@ export const set = <V>(obj: V, path: string, value: unknown): void => {
  */
 export const remove = <V>(obj: V, path: string): void => {
   const parts = path.split(".");
-  let result: UnknownRecord = obj as UnknownRecord;
+  let result: record.Unknown = obj as record.Unknown;
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
     if (result[part] == null) return;
-    result = result[part] as UnknownRecord;
+    result = result[part] as record.Unknown;
   }
   // if its an array, we need to splice it
   if (Array.isArray(result)) {
@@ -213,7 +241,10 @@ export const element = (path: string, index: number): string => {
  * @param path the path to check
  * @returns whether the path exists in the object
  */
-export const has = <V = unknown, T = UnknownRecord>(obj: T, path: string): boolean => {
+export const has = <V = record.Unknown, T = record.Unknown>(
+  obj: T,
+  path: string,
+): boolean => {
   try {
     get<V, T>(obj, path);
     return true;

package/src/destructor.ts

@@ -7,6 +7,10 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export type Destructor = () => void;
+export interface Destructor {
+  (): void;
+}
 
-export type AsyncDestructor = () => Promise<void>;
+export interface AsyncDestructor {
+  (): Promise<void>;
+}

package/src/errors/errors.spec.ts

@@ -30,14 +30,14 @@ describe("errors", () => {
     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(fError).toBe(true);
       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();
+      expect(fError).toBe(false);
     });
   });
 
@@ -50,7 +50,7 @@ describe("errors", () => {
       const error = new ErrorOne("test");
       const encoded = errors.encode(error);
       const decoded = errors.decode(encoded);
-      expect(ErrorOne.matches(decoded)).toBeTruthy();
+      expect(ErrorOne.matches(decoded)).toBe(true);
     });
 
     test("should correctly encode/decode a null error", () => {
@@ -85,7 +85,7 @@ describe("errors", () => {
       expect(encoded.type).toEqual(errors.UNKNOWN);
       expect(encoded.data).toEqual("test");
       const decoded = errors.decode(encoded);
-      expect(errors.Unknown.matches(decoded)).toBeTruthy();
+      expect(errors.Unknown.matches(decoded)).toBe(true);
     });
 
     it("should correctly encode/decode a random object", () => {
@@ -94,59 +94,59 @@ describe("errors", () => {
       expect(encoded.type).toEqual(errors.UNKNOWN);
       expect(encoded.data).toEqual(JSON.stringify(error));
       const decoded = errors.decode(encoded);
-      expect(errors.Unknown.matches(decoded)).toBeTruthy();
+      expect(errors.Unknown.matches(decoded)).toBe(true);
     });
   });
 
   describe("matches", () => {
     it("should return true if the errors are exactly the same", () => {
       const v = new ErrorOne("test");
-      expect(ErrorOne.matches(v)).toBeTruthy();
+      expect(ErrorOne.matches(v)).toBe(true);
       const v2 = new ErrorOne("test");
-      expect(v2.matches(v)).toBeTruthy();
+      expect(v2.matches(v)).toBe(true);
     });
 
     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();
+      expect(e1.matches(e2)).toBe(false);
+      expect(ErrorOne.matches(e2)).toBe(false);
+      expect(ErrorTwo.matches(e1)).toBe(false);
     });
 
     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();
+      expect(e1.matches(e2)).toBe(false);
+      expect(ErrorOne.matches(e2)).toBe(false);
     });
 
     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();
+      expect(e1.matches(e2)).toBe(false);
+      expect(ErrorOne.matches(e2)).toBe(false);
     });
 
     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();
+      expect(e1.matches(e2)).toBe(false);
+      expect(ErrorOne.matches(e2)).toBe(false);
     });
 
     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();
+      expect(e1.matches(e2)).toBe(true);
+      expect(ErrorOne.matches(e1)).toBe(true);
     });
 
     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();
+      expect(e2.matches(e1)).toBe(false);
+      expect(SubError.matches(e1)).toBe(false);
     });
   });
 });

package/src/errors/errors.ts

@@ -11,55 +11,56 @@ import { z } from "zod";
 
 import { singleton } from "@/singleton";
 
+const ERROR_DISCRIMINATOR = "sy_x_error";
+
 /**
  * @returns general function that returns true if an error matches a set of
  * abstracted criteria
  */
-export type Matcher = (e: string | Error | unknown) => boolean;
+export type Matcher = (e: unknown) => boolean;
 
-/** @description an error type that can match against other errors. */
+/** 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.
+   * @returns true if the provided error matches the matchable.
    */
   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.
+ * An error that has a network-portable type, allowing it to be encoded/decoded into
+ * a JSON representation. 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";
+  discriminator: typeof ERROR_DISCRIMINATOR;
   /**
-   * @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.
+   * Returns a unique type identifier for the error. The errors package uses this to
+   *  determine the correct decoder to use when encoding/decoding errors.
    */
   type: string;
 }
 
 /**
- * @description a class that, when constructed, implements the TypedError interface.
- * Also provides utilities for matching and creating subclasses.
+ * 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.
+   * 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.
+   * 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`.
+   * 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.
    */
@@ -92,7 +93,7 @@ const createTypeMatcher =
  */
 export const createTyped = (type: string): TypedClass =>
   class Internal extends Error implements Typed {
-    static readonly discriminator = "FreighterError";
+    static readonly discriminator = ERROR_DISCRIMINATOR;
     readonly discriminator = Internal.discriminator;
 
     static readonly TYPE = type;
@@ -111,50 +112,67 @@ export const createTyped = (type: string): TypedClass =>
   };
 
 /**
- * @description Function that decodes an encoded error payload back into an error object
+ * 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
+ * @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
+ * 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
+ * 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 (typedError.discriminator !== ERROR_DISCRIMINATOR) return false;
   if (!("type" in typedError))
     throw new Error(
-      `Freighter error is missing its type property: ${JSON.stringify(typedError)}`,
+      `X Error is missing its type property: ${JSON.stringify(typedError)}`,
     );
   return true;
 };
 
-/** @description Constant representing an unknown error type */
+/** Constant representing an unknown error type */
 export const UNKNOWN = "unknown";
 
-/** @description Constant representing no error (null) */
+/** Constant representing no error (null) */
 export const NONE = "nil";
 
-interface provider {
+/**
+ * provides custom encoding/decoding mechanisms for specific error
+ * categories.
+ */
+interface Provider {
+  /**
+   * Encodes an error into a primitive payload that can be sent over the network or stored
+   * on disk.
+   * @param error - The error to encode.
+   * @returns The encoded error.
+   */
   encode: Encoder;
+  /**
+   * Decodes an error from a primitive payload that can be sent over the network or stored
+   * on disk.
+   * @param payload - The encoded error.
+   * @returns The decoded error.
+   */
   decode: Decoder;
 }
 
 class Registry {
-  private readonly providers: provider[] = [];
+  private readonly providers: Provider[] = [];
 
-  register(provider: provider): void {
+  register(provider: Provider): void {
     this.providers.push(provider);
   }
 
@@ -195,17 +213,12 @@ const getRegistry = singleton.define("synnax-error-registry", () => new Registry
  * @param encode - A function that encodes the error into a string.
  * @param decode - A function that decodes the error from a string.
  */
-export const register = ({
-  encode,
-  decode,
-}: {
-  encode: Encoder;
-  decode: Decoder;
-}): void => getRegistry().register({ encode, decode });
+export const register = ({ encode, decode }: Provider): void =>
+  getRegistry().register({ encode, decode });
 
 /**
- * Encodes an error into a payload that can be sent between a freighter server
- * and client.
+ * Encodes an error into a primitive payload that can be sent over the network or stored
+ * on disk.
  * @param error - The error to encode.
  * @returns The encoded error.
  */
@@ -225,17 +238,28 @@ export const decode = (payload?: Payload | null): Error | null => {
 };
 
 /**
- * @description Generic error for representing unknown errors
+ * Generic error for representing unknown errors
  */
 export class Unknown extends createTyped("unknown") {}
 
-/** @description Zod schema for validating error payloads */
+/** Zod schema for validating error payloads */
 export const payloadZ = z.object({ type: z.string(), data: z.string() });
 
-/** @description Network-portable representation of an error */
+/** Network-portable representation of an error */
 export type Payload = z.infer<typeof payloadZ>;
 
-/** @description Error for representing the cancellation of an operation */
+/** Error for representing the cancellation of an operation */
 export class Canceled extends createTyped("canceled") {}
 
-export type Return<T> = [T, null] | [null, Error];
+/** A payload representing a native JavaScript Error */
+export interface NativePayload {
+  /** The name of the error */
+  name: string;
+  /** The message of the error */
+  message: string;
+  /** The stack trace of the error */
+  stack?: string;
+}
+
+/** Error for representing a method that is not implemented */
+export class NotImplemented extends createTyped("not_implemented") {}

package/src/flush.ts

@@ -0,0 +1,21 @@
+// 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.
+
+/**
+ * Flushes the microtask queue.
+ * @returns A promise that resolves when the microtask queue is flushed.
+ */
+export const flushMicrotasks = (): Promise<void> => Promise.resolve();
+
+/**
+ * Flushes the task queue.
+ * @returns A promise that resolves when the task queue is flushed.
+ */
+export const flushTaskQueue = (): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, 0));

package/src/id/id.spec.ts

@@ -20,7 +20,7 @@ describe("id", () => {
 
     it("should create a string of length 11", () => {
       const newID = id.create();
-      expect(newID.length).toBe(11);
+      expect(newID.length).toBe(id.LENGTH);
     });
 
     it("should only contain alphanumeric characters", () => {

package/src/id/id.ts

@@ -11,7 +11,9 @@ import { customAlphabet } from "nanoid/non-secure";
 
 const ALPHANUMERIC = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 
-const createInternal = customAlphabet(ALPHANUMERIC, 11);
+export const LENGTH = 11;
+
+const createInternal = customAlphabet(ALPHANUMERIC, LENGTH);
 
 /**
  * Creates a unique alphanumeric string of length 11.

package/src/identity.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 { type UnknownRecord } from "@/record";
+import { type record } from "@/record";
 
-export const isObject = <T extends UnknownRecord = UnknownRecord>(
+export const isObject = <T extends record.Unknown = record.Unknown>(
   item?: unknown,
 ): item is T => item != null && typeof item === "object" && !Array.isArray(item);

package/src/index.ts

@@ -7,6 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/array";
 export * from "@/binary";
 export * from "@/breaker";
 export * from "@/caseconv";
@@ -19,12 +20,15 @@ export * from "@/debounce/debounce";
 export * from "@/deep";
 export * from "@/destructor";
 export * from "@/errors";
+export * from "@/flush";
 export * from "@/id";
 export * from "@/identity";
+export * from "@/instance";
 export * from "@/invert";
 export * from "@/jsonrpc";
 export * from "@/kv";
 export * from "@/link";
+export * from "@/map";
 export * from "@/math";
 export * from "@/migrate";
 export * from "@/notation";
@@ -36,16 +40,17 @@ 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 "@/status";
 export * from "@/strings";
 export * from "@/sync";
 export * from "@/telem";
-export * from "@/toArray";
+export * from "@/testutil";
 export * from "@/transform";
 export * from "@/unique";
 export * from "@/url";
+export * from "@/uuid";
 export * from "@/worker";
 export * from "@/zod";

package/src/instance/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 instance from "@/instance/matcher";