@synnaxlabs/x 0.44.1 → 0.44.3

package/src/deep/path.ts

@@ -126,6 +126,16 @@ const defaultGetter = (obj: record.Unknown, key: string): unknown => {
   return undefined;
 };
 
+export const resolvePath = <T = record.Unknown>(path: string, obj: T): string => {
+  const parts = path.split(".");
+  parts.forEach((part, i) => {
+    obj = defaultGetter(obj as record.Unknown, part) as T;
+    if (obj != null && typeof obj === "object" && "key" in obj)
+      parts[i] = obj.key as string;
+  });
+  return parts.join(".");
+};
+
 /**
  * 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
@@ -158,6 +168,12 @@ export const get = (<V = record.Unknown, T = record.Unknown>(
   return result as V;
 }) as Get;
 
+const getIndex = (part: string): number | null => {
+  // in order to be considered an index, all characters must be numbers
+  for (const char of part) if (isNaN(parseInt(char))) return null;
+  return parseInt(part);
+};
+
 /**
  * Sets the value at the given path on the object. If the parents of the deep path
  * do not exist, new objects will be created.
@@ -180,8 +196,9 @@ export const set = <V>(obj: V, path: string, value: unknown): void => {
       return;
     }
     if (result.length === 0) return;
-    const index = parseInt(parts[parts.length - 1]);
-    if (isNaN(index)) {
+    const index = getIndex(parts[parts.length - 1]);
+    // If we can't parse an index, try to interpret it as an object key.
+    if (index == null) {
       const first = result[0];
       if (typeof first === "object" && "key" in first) {
         const objIndex = result.findIndex((o) => o.key === parts[parts.length - 1]);

package/src/id/id.ts

@@ -9,15 +9,19 @@
 
 import { customAlphabet } from "nanoid/non-secure";
 
-const ALPHANUMERIC = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ALPHANUMERIC = `0123456789${ALPHABET}`;
 
 export const LENGTH = 11;
 
-const createInternal = customAlphabet(ALPHANUMERIC, LENGTH);
+const createPrefix = customAlphabet(ALPHABET, 1);
+const createInternal = customAlphabet(ALPHANUMERIC, LENGTH - 1);
 
 /**
- * Creates a unique alphanumeric string of length 11.
+ * Creates a unique alphanumeric string of length 11. The returned id always begins
+ * with a letter to disambiguate from values that can be potentially interpreted as
+ * numbers.
  *
  * @returns {string} A unique alphanumeric string.
  */
-export const create = (): string => createInternal();
+export const create = (): string => `${createPrefix()}${createInternal()}`;

package/src/math/math.spec.ts

@@ -73,6 +73,10 @@ describe("math", () => {
     it("should return false if a bigint and a number are not equal", () => {
       expect(math.equal(1n, 2)).toBe(false);
     });
+    it("should handle bigint a and decimal b correctly", () => {
+      expect(math.equal(5n, 5.5)).toBe(false);
+      expect(math.equal(5n, 5.0)).toBe(true);
+    });
   });
   describe("roundToNearestMagnitude", () => {
     it("should round to the nearest magnitude of 10", () => {
@@ -94,6 +98,10 @@ describe("math", () => {
     it("should return the minimum of a bigint and a number", () => {
       expect(math.min(1n, 2)).toBe(1n);
     });
+    it("should handle bigint a and decimal b correctly", () => {
+      expect(math.min(10n, 5.5)).toBe(6n);
+      expect(math.min(3n, 7.8)).toBe(3n);
+    });
   });
   describe("max", () => {
     it("should return the maximum of two numbers", () => {
@@ -108,6 +116,10 @@ describe("math", () => {
     it("should return the maximum of a bigint and a number", () => {
       expect(math.max(1n, 2)).toBe(2n);
     });
+    it("should handle bigint a and decimal b correctly", () => {
+      expect(math.max(3n, 5.5)).toBe(6n);
+      expect(math.max(10n, 7.8)).toBe(10n);
+    });
   });
   describe("abs", () => {
     it("should return the absolute value of a number", () => {
@@ -130,6 +142,10 @@ describe("math", () => {
     it("should multiply a bigint and a number", () => {
       expect(math.mult(1n, 2)).toBe(2n);
     });
+    it("should handle bigint a and decimal b correctly", () => {
+      expect(math.mult(3n, 2.5)).toBe(8n);
+      expect(math.mult(4n, 0.5)).toBe(2n);
+    });
   });
 
   describe("div", () => {
@@ -145,5 +161,9 @@ describe("math", () => {
     it("should divide a bigint and a number", () => {
       expect(math.div(2n, 1)).toBe(2n);
     });
+    it("should handle bigint a and decimal b correctly", () => {
+      expect(math.div(10n, 2.5)).toBe(4n);
+      expect(math.div(8n, 0.5)).toBe(16n);
+    });
   });
 });

package/src/math/math.ts

@@ -10,27 +10,38 @@
 /** A numeric value is either a a number, or a bigint. */
 export type Numeric = number | bigint;
 
+const multiCoercedOp =
+  (func: (a: number, b: number) => Numeric) =>
+  <V extends Numeric>(a: V, b: Numeric): V => {
+    if (typeof a === "bigint") {
+      if (isInteger(b))
+        return func(a as unknown as number, BigInt(b) as unknown as number) as V;
+      const res = func(Number(a), Number(b)) as number;
+      if (typeof res === "number") return BigInt(Math.round(res)) as V;
+      return res;
+    }
+    return func(Number(a), Number(b)) as V;
+  };
+
 /**
  * @returns the product of a and b, coercing b to the type of a if necessary. */
-export const sub = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (typeof a === "bigint") return (a - BigInt(b)) as V;
-  return (a - Number(b)) as V;
-};
+export const sub = multiCoercedOp((a, b) => a - b);
 
 /** @returns the sum of a and b, coercing b to the type of a if necessary. */
-export const add = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (typeof a === "bigint") return (a + BigInt(b)) as V;
-  return ((a as unknown as number) + Number(b)) as V;
-};
+export const add = multiCoercedOp((a, b) => a + b);
 
 /** @returns true if a is close to b within epsilon. */
 export const closeTo = (a: number, b: number, epsilon = 0.0001): boolean =>
   Math.abs(a - b) < epsilon;
 
 /** @returns true if a is equal to b, coercing b to the type of a if necessary. */
-export const equal = <V extends Numeric>(a: V, b: Numeric): boolean => {
-  if (typeof a === "bigint") return a === BigInt(b);
-  return a === Number(b);
+export const equal = (a: Numeric, b: Numeric): boolean => {
+  const aIsBigInt = typeof a === "bigint";
+  const bIsBigInt = typeof b === "bigint";
+  if (aIsBigInt && bIsBigInt) return a === b;
+  if (aIsBigInt && isInteger(b)) return a === BigInt(b);
+  if (bIsBigInt && isInteger(a)) return b === BigInt(a);
+  return a === b;
 };
 
 /**
@@ -45,32 +56,24 @@ export const roundToNearestMagnitude = (num: number): number => {
 };
 
 /** @returns the minimum of a and b, coercing b to the type of a if necessary. */
-export const min = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (a <= b) return a;
-  if (typeof a === "bigint") return (a <= b ? a : BigInt(b)) as V;
-  return (a <= b ? a : Number(b)) as V;
+export const min = multiCoercedOp((a, b) => (a <= b ? a : b));
+
+export const isInteger = (a: Numeric): boolean => {
+  if (typeof a === "bigint") return true;
+  return Number.isInteger(a);
 };
 
 /** @returns the maximum of a and b, coercing b to the type of a if necessary. */
-export const max = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (typeof a === "bigint") return (a >= b ? a : BigInt(b)) as V;
-  return (a >= b ? a : Number(b)) as V;
-};
+export const max = multiCoercedOp((a, b) => (a >= b ? a : b));
 
 /** @returns the absolute value of a. */
 export const abs = <V extends Numeric>(a: V): V => {
-  if (a < 0) return -a as V;
-  return a;
+  if (typeof a === "bigint") return (a < 0n ? -a : a) as V;
+  return (a < 0 ? -a : a) as V;
 };
 
 /** @returns the multiplication of a and b, coercing b to the type of a if necessary. */
-export const mult = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (typeof a === "bigint") return (a * BigInt(b)) as V;
-  return (a * Number(b)) as V;
-};
+export const mult = multiCoercedOp((a, b) => a * b);
 
 /** @returns the division of a and b, coercing b to the type of a if necessary. */
-export const div = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (typeof a === "bigint") return (a / BigInt(b)) as V;
-  return (a / Number(b)) as V;
-};
+export const div = multiCoercedOp((a, b) => a / b);

package/src/observe/observe.ts

@@ -12,6 +12,8 @@ import { type Destructor } from "@/destructor";
 /** Handler is called when the value of an Observable changes. */
 export type Handler<T> = (value: T) => void;
 
+export type AsyncHandler<T> = (value: T) => Promise<void>;
+
 /** A generic interface for an entity whose value can be observed when it changes. */
 export interface Observable<T> {
   /**

package/src/primitive/primitive.spec.ts

@@ -7,11 +7,12 @@
 // 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 { describe, expect, it, test } from "vitest";
 import { z } from "zod";
 
 import { binary } from "@/binary";
 import { primitive } from "@/primitive";
+import { testutil } from "@/testutil";
 
 class ExampleStringer implements primitive.Stringer {
   readonly value: string;
@@ -25,7 +26,7 @@ class ExampleStringer implements primitive.Stringer {
 }
 
 describe("primitive", () => {
-  describe("isZero", () => {
+  describe("isZero and isNonZero", () => {
     interface Spec {
       value: primitive.Value;
       expected: boolean;
@@ -42,10 +43,12 @@ describe("primitive", () => {
       { value: new ExampleStringer("cat"), expected: false },
     ];
     SPECS.forEach(({ value, expected }) => {
-      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-      it(`should return ${expected} for ${value} ${typeof value}`, () => {
+      test(`isZero should return ${expected} for ${testutil.toString(value)}`, () => {
         expect(primitive.isZero(value)).toEqual(expected);
       });
+      test(`isNonZero should return ${!expected} for ${testutil.toString(value)}`, () => {
+        expect(primitive.isNonZero(value)).toEqual(!expected);
+      });
     });
   });
 

package/src/primitive/primitive.ts

@@ -52,6 +52,16 @@ export interface Stringer {
 export const isStringer = (value: unknown): boolean =>
   value != null && typeof value === "object" && "toString" in value;
 
+/**
+ * Type representing zero values for each primitive type
+ */
+export type ZeroValue = "" | 0 | 0n | false | null | undefined;
+
+/**
+ * Type representing non-zero values for each primitive type
+ */
+export type NonZeroValue = Exclude<Value, ZeroValue>;
+
 /**
  * @returns true if the given primitive is the zero value for its type.
  * For strings value == ""
@@ -61,7 +71,7 @@ export const isStringer = (value: unknown): boolean =>
  * For objects value == null
  * For undefined returns true
  */
-export const isZero = <V extends Value>(value: V): boolean => {
+export const isZero = <V extends Value>(value: V): value is V & ZeroValue => {
   if (isStringer(value)) return value?.toString().length === 0;
   switch (typeof value) {
     case "string":
@@ -80,3 +90,9 @@ export const isZero = <V extends Value>(value: V): boolean => {
       return false;
   }
 };
+
+/**
+ * Type predicate function that narrows to non-zero values
+ */
+export const isNonZero = <V extends Value>(value: V): value is V & NonZeroValue =>
+  !isZero(value);

package/src/spatial/bounds/bounds.ts

@@ -615,7 +615,7 @@ export const traverse = <T extends numeric.Value = number>(
           currentPosition,
           dir > 0 ? moveDist : -moveDist,
         ) as T;
-        remainingDist = math.sub(remainingDist, dir > 0 ? moveDist : -moveDist);
+        remainingDist = math.sub<T>(remainingDist, dir > 0 ? moveDist : -moveDist);
 
         // If we've exhausted the distance, return the current position
         if (math.equal(remainingDist, 0)) return currentPosition as T;

package/src/status/status.ts

@@ -89,3 +89,14 @@ export const create = <D = undefined, V extends Variant = Variant>(
     time: TimeStamp.now(),
     ...spec,
   }) as unknown as Status<D, V>;
+
+export const filterVariant = (
+  variant: Variant,
+  only: Variant | Variant[] = [],
+): Variant | undefined => {
+  if (Array.isArray(only)) {
+    if (only.includes(variant)) return variant;
+    return undefined;
+  }
+  return only === variant ? variant : undefined;
+};

package/src/strings/strings.spec.ts

@@ -15,6 +15,9 @@ describe("naturalLanguageJoin", () => {
   it("should return an empty string for an empty array", () =>
     expect(strings.naturalLanguageJoin([])).toBe(""));
 
+  it("should return the string for a single string", () =>
+    expect(strings.naturalLanguageJoin("apple")).toBe("apple"));
+
   it("should return the zeroLength string for an empty array if provided", () =>
     expect(strings.naturalLanguageJoin([], "No items")).toBe("No items"));
 

package/src/strings/strings.ts

@@ -24,9 +24,10 @@
  * ```
  */
 export const naturalLanguageJoin = (
-  strings: string[],
+  strings: string | string[],
   zeroLength: string = "",
 ): string => {
+  if (typeof strings === "string") return strings;
   const length = strings.length;
   if (length === 0) return zeroLength;
   if (length === 1) return strings[0];