@synnaxlabs/x 0.43.0 → 0.44.0

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

@@ -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 { z } from "zod/v4";
+import { z } from "zod";
 
 import { singleton } from "@/singleton";
 
@@ -260,3 +260,6 @@ export interface NativePayload {
   /** 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

@@ -20,6 +20,7 @@ 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";
@@ -27,6 +28,7 @@ export * from "@/invert";
 export * from "@/jsonrpc";
 export * from "@/kv";
 export * from "@/link";
+export * from "@/map";
 export * from "@/math";
 export * from "@/migrate";
 export * from "@/notation";
@@ -38,7 +40,6 @@ export * from "@/renderable";
 export * from "@/replace";
 export * from "@/runtime";
 export * from "@/runtime";
-export * from "@/search";
 export * from "@/shallowCopy";
 export * from "@/sleep";
 export * from "@/spatial";
@@ -46,6 +47,7 @@ export * from "@/status";
 export * from "@/strings";
 export * from "@/sync";
 export * from "@/telem";
+export * from "@/testutil";
 export * from "@/transform";
 export * from "@/unique";
 export * from "@/url";

package/src/instance/matcher.spec.ts

@@ -9,15 +9,15 @@
 
 import { describe, expect, it } from "vitest";
 
-import { createMatcher, type Discriminated } from "./matcher";
+import { instance } from "@/instance";
 
 describe("createMatcher", () => {
-  class TestClass implements Discriminated {
+  class TestClass implements instance.Discriminated {
     discriminator = "test";
     constructor(public value: string) {}
   }
 
-  const isTestClass = createMatcher("test", TestClass);
+  const isTestClass = instance.createMatcher("test", TestClass);
 
   it("should return true for instances of the class", () => {
     const instance = new TestClass("value");
@@ -54,18 +54,18 @@ describe("createMatcher", () => {
   });
 
   it("should work with multiple class instances", () => {
-    class ClassA implements Discriminated {
+    class ClassA implements instance.Discriminated {
       discriminator = "a";
       constructor(public value: string) {}
     }
 
-    class ClassB implements Discriminated {
+    class ClassB implements instance.Discriminated {
       discriminator = "b";
       constructor(public value: string) {}
     }
 
-    const isClassA = createMatcher("a", ClassA);
-    const isClassB = createMatcher("b", ClassB);
+    const isClassA = instance.createMatcher("a", ClassA);
+    const isClassB = instance.createMatcher("b", ClassB);
 
     const instanceA = new ClassA("value");
     const instanceB = new ClassB("value");

package/src/jsonrpc/jsonrpc.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 z from "zod/v4";
+import z from "zod";
 
 import { binary } from "@/binary";
 

package/src/kv/types.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 { z } from "zod/v4";
+import { z } from "zod";
 
 export interface Reader<V = unknown> {
   /** @returns the value for a given key, or null if the key is not present. */

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

package/src/map/map.spec.ts

@@ -0,0 +1,132 @@
+// 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 { map } from "@/map";
+
+describe("map", () => {
+  describe("getOrSetDefault", () => {
+    it("should return existing value when key exists", () => {
+      const testMap = new Map<string, number>();
+      testMap.set("existing", 42);
+
+      const result = map.getOrSetDefault(testMap, "existing", 100);
+
+      expect(result).toEqual(42);
+      expect(testMap.get("existing")).toEqual(42);
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should set and return default value when key doesn't exist", () => {
+      const testMap = new Map<string, number>();
+
+      const result = map.getOrSetDefault(testMap, "new", 100);
+
+      expect(result).toEqual(100);
+      expect(testMap.get("new")).toEqual(100);
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should replace the value when key exists with undefined value", () => {
+      const testMap = new Map<string, number | undefined>();
+      testMap.set("undefined", undefined);
+
+      const result = map.getOrSetDefault(testMap, "undefined", 100);
+
+      expect(result).toEqual(100);
+      expect(testMap.get("undefined")).toEqual(100);
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should return null when key exists with null value", () => {
+      const testMap = new Map<string, number | null>();
+      testMap.set("null", null);
+
+      const result = map.getOrSetDefault(testMap, "null", 100);
+
+      expect(result).toBeNull();
+      expect(testMap.get("null")).toBeNull();
+      expect(testMap.size).toEqual(1);
+    });
+
+    it("should work with different key types", () => {
+      const numberMap = new Map<number, string>();
+      const result1 = map.getOrSetDefault(numberMap, 1, "default");
+      expect(result1).toEqual("default");
+      expect(numberMap.get(1)).toEqual("default");
+      const objKey = { id: 1 };
+      const objectMap = new Map<object, string>();
+      const result2 = map.getOrSetDefault(objectMap, objKey, "object-default");
+      expect(result2).toEqual("object-default");
+      expect(objectMap.get(objKey)).toEqual("object-default");
+    });
+
+    it("should work with different value types", () => {
+      const stringMap = new Map<string, string>();
+      const result1 = map.getOrSetDefault(stringMap, "key", "default");
+      expect(result1).toEqual("default");
+      const boolMap = new Map<string, boolean>();
+      const result2 = map.getOrSetDefault(boolMap, "key", true);
+      expect(result2).toEqual(true);
+      const objValue = { name: "test" };
+      const objMap = new Map<string, object>();
+      const result3 = map.getOrSetDefault(objMap, "key", objValue);
+      expect(result3).toEqual(objValue);
+      expect(result3).toBe(objValue);
+    });
+
+    it("should handle empty maps", () => {
+      const emptyMap = new Map<string, number>();
+
+      const result = map.getOrSetDefault(emptyMap, "first", 42);
+
+      expect(result).toEqual(42);
+      expect(emptyMap.get("first")).toEqual(42);
+      expect(emptyMap.size).toEqual(1);
+    });
+
+    it("should handle multiple operations on same map", () => {
+      const testMap = new Map<string, number>();
+      const result1 = map.getOrSetDefault(testMap, "key1", 10);
+      expect(result1).toEqual(10);
+      expect(testMap.size).toEqual(1);
+      const result2 = map.getOrSetDefault(testMap, "key1", 20);
+      expect(result2).toEqual(10); // Original value, not new default
+      expect(testMap.size).toEqual(1);
+      const result3 = map.getOrSetDefault(testMap, "key2", 30);
+      expect(result3).toEqual(30);
+      expect(testMap.size).toEqual(2);
+    });
+
+    it("should handle falsy values correctly", () => {
+      const testMap = new Map<string, number | string | boolean>();
+      testMap.set("zero", 0);
+      const result1 = map.getOrSetDefault(testMap, "zero", 100);
+      expect(result1).toEqual(0);
+      testMap.set("empty", "");
+      const result2 = map.getOrSetDefault(testMap, "empty", "default");
+      expect(result2).toEqual("");
+      testMap.set("false", false);
+      const result3 = map.getOrSetDefault(testMap, "false", true);
+      expect(result3).toEqual(false);
+    });
+
+    it("should handle arrays and complex objects", () => {
+      const testMap = new Map<string, number[]>();
+      const defaultArray = [1, 2, 3];
+
+      const result = map.getOrSetDefault(testMap, "array", defaultArray);
+
+      expect(result).toEqual([1, 2, 3]);
+      expect(result).toBe(defaultArray); // Same reference
+      expect(testMap.get("array")).toBe(defaultArray);
+    });
+  });
+});

package/src/map/map.ts

@@ -0,0 +1,17 @@
+// 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 const getOrSetDefault = <K, V>(map: Map<K, V>, key: K, defaultValue: V): V => {
+  const value = map.get(key);
+  if (value === undefined) {
+    map.set(key, defaultValue);
+    return defaultValue;
+  }
+  return value;
+};