@synnaxlabs/x 0.55.0 → 0.56.1

package/src/notation/notation.spec.ts

@@ -12,12 +12,13 @@ import { describe, expect, it } from "vitest";
 import { notation } from "@/notation";
 
 interface TestCase {
-  number: number;
+  number: number | bigint;
   precision: number;
   expected: Record<notation.Notation, string>;
 }
 
 const TEST_CASES: TestCase[] = [
+  // === Basic positive numbers ===
   {
     number: 12345.678,
     precision: 1,
@@ -28,6 +29,7 @@ const TEST_CASES: TestCase[] = [
     precision: 0,
     expected: { standard: "12346", scientific: "1ᴇ4", engineering: "12ᴇ3" },
   },
+  // === Zero ===
   {
     number: 0,
     precision: 1,
@@ -38,6 +40,18 @@ const TEST_CASES: TestCase[] = [
     precision: 0,
     expected: { standard: "0", scientific: "0ᴇ0", engineering: "0ᴇ0" },
   },
+  // === Negative zero — should render identically to positive zero ===
+  {
+    number: -0,
+    precision: 0,
+    expected: { standard: "0", scientific: "0ᴇ0", engineering: "0ᴇ0" },
+  },
+  {
+    number: -0,
+    precision: 2,
+    expected: { standard: "0.00", scientific: "0.00ᴇ0", engineering: "0.00ᴇ0" },
+  },
+  // === Negative numbers ===
   {
     number: -1234.5678,
     precision: 1,
@@ -48,21 +62,38 @@ const TEST_CASES: TestCase[] = [
     precision: 0,
     expected: { standard: "-1235", scientific: "-1ᴇ3", engineering: "-1ᴇ3" },
   },
+  // === Special values (precision must be ignored) ===
   {
     number: NaN,
     precision: 0,
     expected: { standard: "NaN", scientific: "NaN", engineering: "NaN" },
   },
+  {
+    number: NaN,
+    precision: 4,
+    expected: { standard: "NaN", scientific: "NaN", engineering: "NaN" },
+  },
   {
     number: Infinity,
     precision: 0,
     expected: { standard: "∞", scientific: "∞", engineering: "∞" },
   },
+  {
+    number: Infinity,
+    precision: 4,
+    expected: { standard: "∞", scientific: "∞", engineering: "∞" },
+  },
   {
     number: -Infinity,
     precision: 0,
     expected: { standard: "-∞", scientific: "-∞", engineering: "-∞" },
   },
+  {
+    number: -Infinity,
+    precision: 4,
+    expected: { standard: "-∞", scientific: "-∞", engineering: "-∞" },
+  },
+  // === Small fractional numbers ===
   {
     number: 0.0001234,
     precision: 1,
@@ -73,11 +104,238 @@ const TEST_CASES: TestCase[] = [
     precision: 0,
     expected: { standard: "0", scientific: "1ᴇ-4", engineering: "123ᴇ-6" },
   },
+  // === Negative small fractional numbers ===
+  {
+    number: -0.0001234,
+    precision: 1,
+    expected: { standard: "-0.0", scientific: "-1.2ᴇ-4", engineering: "-123.4ᴇ-6" },
+  },
+  {
+    number: -0.0001234,
+    precision: 0,
+    expected: { standard: "-0", scientific: "-1ᴇ-4", engineering: "-123ᴇ-6" },
+  },
+  // === Number 1 ===
+  {
+    number: 1,
+    precision: 0,
+    expected: { standard: "1", scientific: "1ᴇ0", engineering: "1ᴇ0" },
+  },
+  {
+    number: 1,
+    precision: 2,
+    expected: { standard: "1.00", scientific: "1.00ᴇ0", engineering: "1.00ᴇ0" },
+  },
+  // === Power-of-10 boundaries where engineering and scientific differ ===
+  {
+    number: 10,
+    precision: 0,
+    expected: { standard: "10", scientific: "1ᴇ1", engineering: "10ᴇ0" },
+  },
+  {
+    number: 100,
+    precision: 0,
+    expected: { standard: "100", scientific: "1ᴇ2", engineering: "100ᴇ0" },
+  },
+  {
+    number: 1000,
+    precision: 0,
+    expected: { standard: "1000", scientific: "1ᴇ3", engineering: "1ᴇ3" },
+  },
+  {
+    number: 10000,
+    precision: 0,
+    expected: { standard: "10000", scientific: "1ᴇ4", engineering: "10ᴇ3" },
+  },
+  {
+    number: 100000,
+    precision: 0,
+    expected: { standard: "100000", scientific: "1ᴇ5", engineering: "100ᴇ3" },
+  },
+  {
+    number: 1000000,
+    precision: 0,
+    expected: { standard: "1000000", scientific: "1ᴇ6", engineering: "1ᴇ6" },
+  },
+  // === Negative power-of-10 boundaries (fractions) ===
+  {
+    number: 0.1,
+    precision: 1,
+    expected: { standard: "0.1", scientific: "1.0ᴇ-1", engineering: "100.0ᴇ-3" },
+  },
+  {
+    number: 0.01,
+    precision: 1,
+    expected: { standard: "0.0", scientific: "1.0ᴇ-2", engineering: "10.0ᴇ-3" },
+  },
+  {
+    number: 0.001,
+    precision: 1,
+    expected: { standard: "0.0", scientific: "1.0ᴇ-3", engineering: "1.0ᴇ-3" },
+  },
+  // === Negative power-of-10 boundaries ===
+  {
+    number: -10,
+    precision: 0,
+    expected: { standard: "-10", scientific: "-1ᴇ1", engineering: "-10ᴇ0" },
+  },
+  {
+    number: -100,
+    precision: 0,
+    expected: { standard: "-100", scientific: "-1ᴇ2", engineering: "-100ᴇ0" },
+  },
+  // === Power of 10 with non-zero precision ===
+  {
+    number: 100,
+    precision: 2,
+    expected: { standard: "100.00", scientific: "1.00ᴇ2", engineering: "100.00ᴇ0" },
+  },
+  {
+    number: 1000,
+    precision: 3,
+    expected: { standard: "1000.000", scientific: "1.000ᴇ3", engineering: "1.000ᴇ3" },
+  },
+  // === Rounding overflow — toFixed pushes the mantissa past the canonical upper
+  //     bound (>= 10 for scientific, >= 1000 for engineering). The exponent must be
+  //     bumped so the mantissa stays in the canonical range. ===
+  {
+    number: 9.999,
+    precision: 1,
+    expected: { standard: "10.0", scientific: "1.0ᴇ1", engineering: "10.0ᴇ0" },
+  },
+  {
+    number: 9.999,
+    precision: 0,
+    expected: { standard: "10", scientific: "1ᴇ1", engineering: "10ᴇ0" },
+  },
+  {
+    number: 99.99,
+    precision: 0,
+    expected: { standard: "100", scientific: "1ᴇ2", engineering: "100ᴇ0" },
+  },
+  {
+    number: 999.99,
+    precision: 0,
+    expected: { standard: "1000", scientific: "1ᴇ3", engineering: "1ᴇ3" },
+  },
+  {
+    number: 9999.99,
+    precision: 0,
+    expected: { standard: "10000", scientific: "1ᴇ4", engineering: "10ᴇ3" },
+  },
+  {
+    number: -9.999,
+    precision: 1,
+    expected: { standard: "-10.0", scientific: "-1.0ᴇ1", engineering: "-10.0ᴇ0" },
+  },
+  {
+    number: -999.99,
+    precision: 0,
+    expected: { standard: "-1000", scientific: "-1ᴇ3", engineering: "-1ᴇ3" },
+  },
+  // === Positive bigint ===
+  {
+    number: 1n,
+    precision: 0,
+    expected: { standard: "1", scientific: "1ᴇ0", engineering: "1ᴇ0" },
+  },
+  {
+    number: 1n,
+    precision: 2,
+    expected: { standard: "1.00", scientific: "1.00ᴇ0", engineering: "1.00ᴇ0" },
+  },
+  {
+    number: 1778020940471336960n,
+    precision: 0,
+    expected: {
+      standard: "1778020940471336960",
+      scientific: "2ᴇ18",
+      engineering: "2ᴇ18",
+    },
+  },
+  {
+    number: 1778020940471336960n,
+    precision: 11,
+    expected: {
+      standard: "1778020940471336960.00000000000",
+      scientific: "1.77802094047ᴇ18",
+      engineering: "1.77802094047ᴇ18",
+    },
+  },
+  // === Negative bigint ===
+  {
+    number: -1n,
+    precision: 0,
+    expected: { standard: "-1", scientific: "-1ᴇ0", engineering: "-1ᴇ0" },
+  },
+  {
+    number: -1778020940471336960n,
+    precision: 0,
+    expected: {
+      standard: "-1778020940471336960",
+      scientific: "-2ᴇ18",
+      engineering: "-2ᴇ18",
+    },
+  },
+  {
+    number: -1778020940471336960n,
+    precision: 11,
+    expected: {
+      standard: "-1778020940471336960.00000000000",
+      scientific: "-1.77802094047ᴇ18",
+      engineering: "-1.77802094047ᴇ18",
+    },
+  },
+  // === Zero bigint ===
+  {
+    number: 0n,
+    precision: 0,
+    expected: { standard: "0", scientific: "0ᴇ0", engineering: "0ᴇ0" },
+  },
+  {
+    number: 0n,
+    precision: 11,
+    expected: {
+      standard: "0.00000000000",
+      scientific: "0.00000000000ᴇ0",
+      engineering: "0.00000000000ᴇ0",
+    },
+  },
+  // === Large-magnitude floats expressed with e-notation ===
+  // For values >= 10^21, JS's toFixed delegates to ToString, so standard output
+  // here is itself in e-notation. The scientific and engineering branches keep
+  // their canonical forms.
+  {
+    number: 9e124,
+    precision: 0,
+    expected: { standard: "9e+124", scientific: "9ᴇ124", engineering: "90ᴇ123" },
+  },
+  {
+    number: 9.99e124,
+    precision: 0,
+    expected: { standard: "9.99e+124", scientific: "1ᴇ125", engineering: "100ᴇ123" },
+  },
+  {
+    number: -3e10,
+    precision: 0,
+    expected: { standard: "-30000000000", scientific: "-3ᴇ10", engineering: "-30ᴇ9" },
+  },
+  // === Tiny-magnitude floats expressed with e-notation ===
+  {
+    number: 1e-200,
+    precision: 0,
+    expected: { standard: "0", scientific: "1ᴇ-200", engineering: "10ᴇ-201" },
+  },
+  {
+    number: 5e-50,
+    precision: 0,
+    expected: { standard: "0", scientific: "5ᴇ-50", engineering: "50ᴇ-51" },
+  },
 ];
 
 describe("stringifyNumber", () => {
   TEST_CASES.forEach(({ number, precision, expected }) =>
-    describe(`number: ${number}, precision: ${precision}`, () =>
+    describe(`${typeof number === "bigint" ? "bigint " : ""}number: ${number}, precision: ${precision}`, () =>
       notation.NOTATIONS.forEach((n) =>
         it(`should format correctly in ${n} notation`, () => {
           const result = notation.stringifyNumber(number, precision, n);

package/src/notation/notation.ts

@@ -7,11 +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";
-
-export const NOTATIONS = ["standard", "scientific", "engineering"] as const;
-export const notationZ = z.enum(NOTATIONS);
-export type Notation = z.infer<typeof notationZ>;
+import { type Notation } from "@/notation/types.gen";
 
 /**
  * Converts a number to a string representation with a specified precision and notation.
@@ -25,6 +21,9 @@ export type Notation = z.infer<typeof notationZ>;
  * - If the value is `NaN`, returns "NaN".
  * - If the value is `Infinity`, returns "∞".
  * - If the value is `-Infinity`, returns "-∞".
+ * - Scientific and engineering output is renormalized after rounding so the mantissa
+ *   stays in its canonical range (|m| < 10 for scientific, |m| < 1000 for engineering).
+ *   For example, 9.999 at precision 1 in scientific renders as "1.0ᴇ1", not "10.0ᴇ0".
  *
  * Examples:
  *
@@ -41,10 +40,16 @@ export type Notation = z.infer<typeof notationZ>;
  * ```
  */
 export const stringifyNumber = (
-  value: number,
+  value: number | bigint,
   precision: number,
   notation: Notation,
 ): string => {
+  // Standard notation on bigint must preserve full integer precision; coercing through
+  // Number() would quantize values above 2^53. All other branches are float-mantissa
+  // truncated by definition, so coercing bigint to number is safe.
+  if (typeof value === "bigint" && notation === "standard")
+    return precision === 0 ? value.toString() : `${value}.${"0".repeat(precision)}`;
+  if (typeof value === "bigint") value = Number(value);
   if (Number.isNaN(value)) return "NaN";
   if (value === Infinity) return "∞";
   if (value === -Infinity) return "-∞";
@@ -56,6 +61,19 @@ export const stringifyNumber = (
   let exp: number;
   if (notation === "scientific") exp = Math.floor(Math.log10(Math.abs(value)));
   else exp = Math.floor(Math.log10(Math.abs(value)) / 3) * 3;
-  const mantissa = value / 10 ** exp;
+  let mantissa = value / 10 ** exp;
+  // After rounding via toFixed, the mantissa may have crossed the canonical upper
+  // bound (>= 10 for scientific, >= 1000 for engineering). Predict the rounded
+  // magnitude with Math.round — for non-negative values it matches toFixed's
+  // half-away-from-zero semantics, and we're already taking Math.abs — so we avoid
+  // having to parseFloat the formatted string back into a number. Bump the exponent
+  // if needed so e.g. 9.999 at precision 1 in scientific becomes "1.0ᴇ1" rather
+  // than "10.0ᴇ0".
+  const upperBound = notation === "scientific" ? 10 : 1000;
+  const factor = 10 ** precision;
+  if (Math.round(Math.abs(mantissa) * factor) / factor >= upperBound) {
+    exp += notation === "scientific" ? 1 : 3;
+    mantissa = value / 10 ** exp;
+  }
   return `${mantissa.toFixed(precision)}ᴇ${exp}`;
 };

package/src/notation/types.gen.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 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.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { z } from "zod";
+
+export const NOTATIONS = ["standard", "scientific", "engineering"] as const;
+export const notationZ = z.enum(NOTATIONS);
+export type Notation = z.infer<typeof notationZ>;

package/src/primitive/primitive.spec.ts

@@ -54,13 +54,13 @@ describe("primitive", () => {
 
   describe("isStringer", () => {
     it("should return true for a stringer", () => {
-      expect(primitive.isStringer(new ExampleStringer("cat"))).toEqual(true);
+      expect(primitive.isStringer(new ExampleStringer("cat"))).toBe(true);
     });
     it("should return false for a non-stringer", () => {
-      expect(primitive.isStringer(0)).toEqual(false);
+      expect(primitive.isStringer(0)).toBe(false);
     });
     it("should return false for null", () => {
-      expect(primitive.isStringer(null)).toEqual(false);
+      expect(primitive.isStringer(null)).toBe(false);
     });
   });
 
@@ -178,12 +178,65 @@ describe("primitive", () => {
 
       describe("isCrudeValueExtension", () => {
         it("should return true for a CrudeValueExtension", () => {
-          expect(primitive.isCrudeValueExtension({ value: 12n })).toEqual(true);
+          expect(primitive.isCrudeValueExtension({ value: 12n })).toBe(true);
         });
         it("should return false for a non-CrudeValueExtension", () => {
-          expect(primitive.isCrudeValueExtension(12n)).toEqual(false);
+          expect(primitive.isCrudeValueExtension(12n)).toBe(false);
         });
       });
     });
   });
+
+  describe("isHashable", () => {
+    class HashableThing implements primitive.Hashable {
+      constructor(private readonly v: string) {}
+      hash(): string {
+        return this.v;
+      }
+    }
+
+    it("returns true for an object with a hash() method", () => {
+      expect(primitive.isHashable(new HashableThing("x"))).toBe(true);
+    });
+
+    it("returns true for a plain object literal with a hash function", () => {
+      expect(primitive.isHashable({ hash: () => "x" })).toBe(true);
+    });
+
+    it("narrows the type for downstream calls", () => {
+      const v: unknown = new HashableThing("abc");
+      if (primitive.isHashable(v)) expect(v.hash()).toEqual("abc");
+      else throw new Error("expected isHashable to narrow");
+    });
+
+    it("returns false for null", () => {
+      expect(primitive.isHashable(null)).toBe(false);
+    });
+
+    it("returns false for undefined", () => {
+      expect(primitive.isHashable(undefined)).toBe(false);
+    });
+
+    it("returns false for primitives", () => {
+      expect(primitive.isHashable("x")).toBe(false);
+      expect(primitive.isHashable(42)).toBe(false);
+      expect(primitive.isHashable(42n)).toBe(false);
+      expect(primitive.isHashable(true)).toBe(false);
+    });
+
+    it("returns false for plain objects without a hash function", () => {
+      expect(primitive.isHashable({})).toBe(false);
+      expect(primitive.isHashable({ key: "x" })).toBe(false);
+    });
+
+    it("returns false when hash is not a function", () => {
+      expect(primitive.isHashable({ hash: "not a function" })).toBe(false);
+      expect(primitive.isHashable({ hash: 42 })).toBe(false);
+      expect(primitive.isHashable({ hash: null })).toBe(false);
+    });
+
+    it("returns false for arrays", () => {
+      expect(primitive.isHashable([1, 2, 3])).toBe(false);
+    });
+  });
 });

package/src/primitive/primitive.ts

@@ -61,6 +61,28 @@ export interface Stringer {
 export const isStringer = (value: unknown): boolean =>
   value != null && typeof value === "object" && "toString" in value;
 
+/**
+ * Hashable is a duck-typed protocol for class instances that can produce a stable,
+ * canonical string representation of themselves. Implementers commit to: (1) the
+ * returned string uniquely identifies the value's logical content, and (2) two
+ * instances representing the same logical value return equal strings.
+ *
+ * Used by cache-key derivation paths (e.g. flux queryCache) so non-primitive query
+ * fields hash to a stable identifier rather than relying on enumerable own-property
+ * iteration, which is fragile for class instances.
+ */
+export interface Hashable {
+  /** @returns a stable, canonical string representation of the value. */
+  hash: () => string;
+}
+
+/** @returns true if the value implements primitive.Hashable, otherwise returns false. */
+export const isHashable = (value: unknown): value is Hashable =>
+  value != null &&
+  typeof value === "object" &&
+  "hash" in value &&
+  typeof value.hash === "function";
+
 /**
  * Type representing zero values for each primitive type
  */

package/src/record/record.spec.ts

@@ -353,6 +353,32 @@ describe("record", () => {
       const obj = { nested: { key: "value" }, arr: [1, 2, 3] };
       expect(record.nullishToEmpty().parse(obj)).toEqual(obj);
     });
+
+    describe("with typed key and value schemas", () => {
+      const schema = record.nullishToEmpty(z.string(), z.number());
+
+      it("should coerce null to empty object", () => {
+        expect(schema.parse(null)).toEqual({});
+      });
+
+      it("should coerce undefined to empty object", () => {
+        expect(schema.parse(undefined)).toEqual({});
+      });
+
+      it("should pass through populated record matching the value schema", () => {
+        expect(schema.parse({ a: 1, b: 2 })).toEqual({ a: 1, b: 2 });
+      });
+
+      it("should reject values that don't match the value schema", () => {
+        expect(() => schema.parse({ a: "not a number" })).toThrow();
+      });
+
+      it("should preserve the inferred typed shape", () => {
+        const parsed = schema.parse({ a: 1 });
+        const value: number = parsed.a;
+        expect(value).toBe(1);
+      });
+    });
   });
 
   describe("omit", () => {

package/src/record/record.ts

@@ -141,6 +141,14 @@ export const omit = <T, K extends keyof T>(obj: T, ...keys: K[]): Omit<T, K> =>
   return result;
 };
 
+export interface NullishToEmpty {
+  (): z.ZodType<Unknown>;
+  <K extends z.ZodType<Key>, V extends z.ZodType>(
+    key: K,
+    value: V,
+  ): z.ZodType<Record<z.infer<K>, z.infer<V>>>;
+}
+
 /**
  * For required JSON/record fields: coerces null/undefined to empty object {}.
  * Use when the record must always be present and iterable.
@@ -149,9 +157,16 @@ export const omit = <T, K extends keyof T>(obj: T, ...keys: K[]): Omit<T, K> =>
  * - undefined → {}
  * - {} → {}
  * - {data} → {data}
+ *
+ * Without arguments the value type is unknown. Pass key and value zod schemas
+ * to type the resulting record (e.g. for `map<string, Color>` fields).
  */
-export const nullishToEmpty = (): z.ZodType<Unknown> =>
-  z.union([
-    z.union([z.null(), z.undefined()]).transform<Unknown>(() => ({})),
-    unknownZ(),
-  ]);
+export const nullishToEmpty = ((key?: z.ZodType, value?: z.ZodType) => {
+  if (key === undefined || value === undefined)
+    return z
+      .union([z.null().transform<Unknown>(() => ({})), unknownZ()])
+      .default(() => ({}));
+  return z
+    .union([z.null().transform(() => ({})), z.record(key as z.ZodType<Key>, value)])
+    .default(() => ({}));
+}) as NullishToEmpty;

package/src/require/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 require from "@/require/require";

package/src/require/require.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 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 type Require<T, K extends keyof T> = Pick<Required<T>, K> & Omit<T, K>;