@synnaxlabs/x 0.46.2 → 0.47.0

package/src/compare/binary.spec.ts

@@ -0,0 +1,308 @@
+// 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 { insert, search } from "@/compare/binary";
+
+describe("compare", () => {
+  describe("search", () => {
+    describe("number arrays", () => {
+      interface Spec {
+        name: string;
+        array: number[];
+        value: number;
+        expected: number;
+      }
+      const SPECS: Spec[] = [
+        {
+          name: "finds element at start",
+          array: [1, 2, 3, 4, 5],
+          value: 1,
+          expected: 0,
+        },
+        {
+          name: "finds element in middle",
+          array: [1, 2, 3, 4, 5],
+          value: 3,
+          expected: 2,
+        },
+        {
+          name: "finds element at end",
+          array: [1, 2, 3, 4, 5],
+          value: 5,
+          expected: 4,
+        },
+        {
+          name: "returns insertion point for missing element (start)",
+          array: [2, 4, 6, 8],
+          value: 1,
+          expected: 0,
+        },
+        {
+          name: "returns insertion point for missing element (middle)",
+          array: [1, 3, 5, 7],
+          value: 4,
+          expected: 2,
+        },
+        {
+          name: "returns insertion point for missing element (end)",
+          array: [1, 2, 3, 4],
+          value: 5,
+          expected: 4,
+        },
+        {
+          name: "handles empty array",
+          array: [],
+          value: 1,
+          expected: 0,
+        },
+        {
+          name: "handles single element array (found)",
+          array: [5],
+          value: 5,
+          expected: 0,
+        },
+        {
+          name: "handles single element array (not found, before)",
+          array: [5],
+          value: 3,
+          expected: 0,
+        },
+        {
+          name: "handles single element array (not found, after)",
+          array: [5],
+          value: 7,
+          expected: 1,
+        },
+      ];
+      SPECS.forEach((spec) => {
+        it(spec.name, () => {
+          expect(search(spec.array, spec.value)).toBe(spec.expected);
+        });
+      });
+    });
+
+    describe("string arrays", () => {
+      interface Spec {
+        name: string;
+        array: string[];
+        value: string;
+        expected: number;
+      }
+      const SPECS: Spec[] = [
+        {
+          name: "finds string element",
+          array: ["apple", "banana", "cherry", "date"],
+          value: "cherry",
+          expected: 2,
+        },
+        {
+          name: "returns insertion point for missing string",
+          array: ["apple", "banana", "date"],
+          value: "cherry",
+          expected: 2,
+        },
+        {
+          name: "handles not found string",
+          array: ["apple", "banana", "date"],
+          value: "cherry",
+          expected: 2,
+        },
+      ];
+      SPECS.forEach((spec) => {
+        it(spec.name, () => {
+          expect(search(spec.array, spec.value)).toBe(spec.expected);
+        });
+      });
+    });
+
+    describe("custom comparator", () => {
+      interface Item {
+        id: number;
+        name: string;
+      }
+      interface Spec {
+        name: string;
+        array: Item[];
+        value: Item;
+        expected: number;
+      }
+      const SPECS: Spec[] = [
+        {
+          name: "finds element with custom comparator",
+          array: [
+            { id: 1, name: "a" },
+            { id: 2, name: "b" },
+            { id: 3, name: "c" },
+          ],
+          value: { id: 2, name: "b" },
+          expected: 1,
+        },
+        {
+          name: "returns insertion point with custom comparator",
+          array: [
+            { id: 1, name: "a" },
+            { id: 3, name: "c" },
+            { id: 5, name: "e" },
+          ],
+          value: { id: 4, name: "d" },
+          expected: 2,
+        },
+      ];
+      SPECS.forEach((spec) => {
+        it(spec.name, () => {
+          const comparator = (a: Item, b: Item) => a.id - b.id;
+          expect(search(spec.array, spec.value, comparator)).toBe(spec.expected);
+        });
+      });
+    });
+  });
+
+  describe("insert", () => {
+    describe("number arrays", () => {
+      interface Spec {
+        name: string;
+        array: number[];
+        value: number;
+        expected: number[];
+      }
+      const SPECS: Spec[] = [
+        {
+          name: "inserts into empty array",
+          array: [],
+          value: 5,
+          expected: [5],
+        },
+        {
+          name: "inserts at beginning",
+          array: [2, 3, 4],
+          value: 1,
+          expected: [1, 2, 3, 4],
+        },
+        {
+          name: "inserts in middle",
+          array: [1, 2, 4, 5],
+          value: 3,
+          expected: [1, 2, 3, 4, 5],
+        },
+        {
+          name: "inserts at end",
+          array: [1, 2, 3],
+          value: 4,
+          expected: [1, 2, 3, 4],
+        },
+        {
+          name: "inserts duplicate value",
+          array: [1, 2, 3, 4],
+          value: 2,
+          expected: [1, 2, 2, 3, 4],
+        },
+      ];
+      SPECS.forEach((spec) => {
+        it(spec.name, () => {
+          const arr = [...spec.array];
+          insert(arr, spec.value);
+          expect(arr).toEqual(spec.expected);
+        });
+      });
+    });
+
+    describe("string arrays", () => {
+      interface Spec {
+        name: string;
+        array: string[];
+        value: string;
+        expected: string[];
+      }
+      const SPECS: Spec[] = [
+        {
+          name: "inserts string in correct position",
+          array: ["apple", "banana", "date"],
+          value: "cherry",
+          expected: ["apple", "banana", "cherry", "date"],
+        },
+        {
+          name: "inserts at beginning of string array",
+          array: ["banana", "cherry"],
+          value: "apple",
+          expected: ["apple", "banana", "cherry"],
+        },
+        {
+          name: "handles not found string",
+          array: ["apple", "banana", "date"],
+          value: "cherry",
+          expected: ["apple", "banana", "cherry", "date"],
+        },
+        {
+          name: "handles empty array",
+          array: [],
+          value: "cherry",
+          expected: ["cherry"],
+        },
+      ];
+      SPECS.forEach((spec) => {
+        it(spec.name, () => {
+          const arr = [...spec.array];
+          insert(arr, spec.value);
+          expect(arr).toEqual(spec.expected);
+        });
+      });
+    });
+
+    describe("custom comparator", () => {
+      interface Item {
+        id: number;
+        name: string;
+      }
+      interface Spec {
+        name: string;
+        array: Item[];
+        value: Item;
+        expected: Item[];
+      }
+      const SPECS: Spec[] = [
+        {
+          name: "inserts with custom comparator",
+          array: [
+            { id: 1, name: "a" },
+            { id: 3, name: "c" },
+          ],
+          value: { id: 2, name: "b" },
+          expected: [
+            { id: 1, name: "a" },
+            { id: 2, name: "b" },
+            { id: 3, name: "c" },
+          ],
+        },
+        {
+          name: "maintains sort order with custom comparator",
+          array: [
+            { id: 5, name: "e" },
+            { id: 10, name: "j" },
+          ],
+          value: { id: 7, name: "g" },
+          expected: [
+            { id: 5, name: "e" },
+            { id: 7, name: "g" },
+            { id: 10, name: "j" },
+          ],
+        },
+      ];
+      SPECS.forEach((spec) => {
+        it(spec.name, () => {
+          const arr = [...spec.array];
+          const comparator = (a: Item, b: Item) => a.id - b.id;
+          insert(arr, spec.value, comparator);
+          expect(arr).toEqual(spec.expected);
+        });
+      });
+    });
+  });
+});

package/src/compare/binary.ts

@@ -0,0 +1,50 @@
+// 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 { type Comparator, newF } from "@/compare/compare";
+
+/**
+ * Performs a binary search on the given array. If the array is not sorted, or the
+ * comparator does not correctly order the values, the behavior of this function is
+ * undefined. If the value is not found, the index of the first element greater than the
+ * value is returned. If the value is greater than all elements in the array, the length
+ * of the array is returned.
+ *
+ * @param array - The array to search.
+ * @param value - The value to search for.
+ * @param comparator - The comparator to use.
+ * @returns The index of the value in the array.
+ */
+export const search = <T>(array: T[], value: T, comparator?: Comparator<T>): number => {
+  let left = 0;
+  let right = array.length;
+  const cf = comparator ?? newF(value);
+  while (left < right) {
+    const mid = Math.floor((left + right) / 2);
+    const cmp = cf(array[mid], value);
+    if (cmp === 0) return mid;
+    if (cmp < 0) left = mid + 1;
+    else right = mid;
+  }
+  return left;
+};
+
+/**
+ * Inserts a value into the given sorted array and maintains the sort order of the
+ * array. If the array is not sorted, or the comparator does not correctly order the
+ * values, the behavior of this function is undefined.
+ *
+ * @param array - The array to insert the value into.
+ * @param value - The value to insert.
+ * @param comparator - The comparator to use.
+ */
+export const insert = <T>(array: T[], value: T, comparator?: Comparator<T>): void => {
+  const idx = search(array, value, comparator);
+  array.splice(idx, 0, value);
+};

package/src/compare/external.ts

@@ -0,0 +1,11 @@
+// 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 * from "@/compare/binary";
+export * from "@/compare/compare";

package/src/compare/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as compare from "@/compare/compare";
+export * as compare from "@/compare/external";

package/src/csv/csv.spec.ts

@@ -0,0 +1,28 @@
+// 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 { csv } from "@/csv";
+
+describe("csv", () => {
+  describe("maybeEscapeField", () => {
+    it("shouldn't escape fields without special characters", () => {
+      expect(csv.maybeEscapeField("hello")).toBe("hello");
+      expect(csv.maybeEscapeField("123")).toBe("123");
+      expect(csv.maybeEscapeField("Call me Ishmael")).toBe("Call me Ishmael");
+    });
+    it("should escape fields with special characters", () => {
+      expect(csv.maybeEscapeField("hello,world")).toBe('"hello,world"');
+      expect(csv.maybeEscapeField("hello\nworld")).toBe('"hello\nworld"');
+      expect(csv.maybeEscapeField("hello\r\nworld")).toBe('"hello\r\nworld"');
+      expect(csv.maybeEscapeField('"hello"')).toBe('"""hello"""');
+    });
+  });
+});

package/src/csv/csv.ts

@@ -0,0 +1,26 @@
+// 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 regex = /[",\n]/;
+
+/**
+ * Escapes a CSV field by wrapping it in double quotes if it contains a comma, double
+ * quote, or newline. Also escapes any internal double quotes by doubling them. For
+ * example, the field foo"bar,baz becomes "foo""bar,baz"
+ *
+ * @param field -  The string field to potentially escape for CSV output.
+ * @returns The escaped CSV-safe field.
+ */
+export const maybeEscapeField = (field: string): string => {
+  if (!regex.test(field)) return field;
+  const escaped = field.replace(/"/g, '""');
+  return `"${escaped}"`;
+};
+
+export type RecordDelimiter = "\r\n" | "\n";

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

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "@/clamp/clamp";
 export * from "@/color";
 export * from "@/compare";
 export * from "@/control";
+export * from "@/csv";
 export * from "@/debounce/debounce";
 export * from "@/deep";
 export * from "@/destructor";

package/src/jsonrpc/jsonrpc.spec.ts

@@ -1,3 +1,12 @@
+// 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 { jsonRPC } from "@/jsonrpc";

package/src/math/round.spec.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-loss-of-precision */
 // Copyright 2025 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
@@ -8,6 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+/* eslint-disable no-loss-of-precision */
+
 import { describe, expect, it } from "vitest";
 
 import { math } from "@/math";

package/src/spatial/bounds/bounds.spec.ts

@@ -10,7 +10,7 @@
 import { describe, expect, it, test } from "vitest";
 
 import { type numeric } from "@/numeric";
-import * as bounds from "@/spatial/bounds/bounds";
+import { bounds } from "@/spatial/bounds";
 import { testutil } from "@/testutil";
 
 describe("Bounds", () => {

package/src/spatial/bounds/bounds.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 { math } from "@/math";
+import { abs, add, equal as mathEqual, min as mathMin, sub } from "@/math/math";
 import { type numeric } from "@/numeric";
 import { type Bounds, bounds, type CrudeBounds } from "@/spatial/base";
 
@@ -479,7 +479,7 @@ export const buildInsertionPlan = <T extends numeric.Value>(
   }
   let deleteInBetween = upper.index - lower.index;
   let insertInto = lower.index;
-  let removeBefore = math.sub(Number(span(_bounds[lower.index])), lower.position);
+  let removeBefore = sub(Number(span(_bounds[lower.index])), lower.position);
   // If we're overlapping with the previous bound, we need to slice out one less
   // and insert one further up.
   if (lower.position !== 0) {
@@ -596,7 +596,7 @@ export const traverse = <T extends numeric.Value = number>(
   let remainingDist = dist;
   let currentPosition = start as number | bigint;
 
-  while (math.equal(remainingDist, 0) === false) {
+  while (mathEqual(remainingDist, 0) === false) {
     // Find the bound we're currently in or adjacent to
     const index = _bounds.findIndex((b) => {
       if (dir > 0) return currentPosition >= b.lower && currentPosition < b.upper;
@@ -606,19 +606,16 @@ export const traverse = <T extends numeric.Value = number>(
     if (index !== -1) {
       const b = _bounds[index];
       let distanceInBound: T;
-      if (dir > 0) distanceInBound = math.sub(b.upper, currentPosition);
-      else distanceInBound = math.sub(currentPosition, b.lower) as T;
+      if (dir > 0) distanceInBound = sub(b.upper, currentPosition);
+      else distanceInBound = sub(currentPosition, b.lower) as T;
 
       if (distanceInBound > (0 as T)) {
-        const moveDist = math.min(math.abs(remainingDist), distanceInBound);
-        currentPosition = math.add(
-          currentPosition,
-          dir > 0 ? moveDist : -moveDist,
-        ) as T;
-        remainingDist = math.sub<T>(remainingDist, dir > 0 ? moveDist : -moveDist);
+        const moveDist = mathMin(abs(remainingDist), distanceInBound);
+        currentPosition = add(currentPosition, dir > 0 ? moveDist : -moveDist) as T;
+        remainingDist = 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;
+        if (mathEqual(remainingDist, 0)) return currentPosition as T;
         continue;
       }
     }

package/src/spatial/box/box.spec.ts

@@ -9,9 +9,9 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as box from "@/spatial/box/box";
-import * as location from "@/spatial/location/location";
-import type * as xy from "@/spatial/xy/xy";
+import { box } from "@/spatial/box";
+import { location } from "@/spatial/location";
+import { type xy } from "@/spatial/xy";
 
 describe("Box", () => {
   describe("construction", () => {

package/src/spatial/box/box.ts

@@ -9,11 +9,11 @@
 
 import { z } from "zod";
 
-import type * as bounds from "@/spatial/bounds/bounds";
-import type * as dimensions from "@/spatial/dimensions/dimensions";
-import * as direction from "@/spatial/direction/direction";
-import * as location from "@/spatial/location/location";
-import * as xy from "@/spatial/xy/xy";
+import { type bounds } from "@/spatial/bounds";
+import { type dimensions } from "@/spatial/dimensions";
+import { direction } from "@/spatial/direction";
+import { location } from "@/spatial/location";
+import { xy } from "@/spatial/xy";
 
 const cssPos = z.union([z.number(), z.string()]);
 

package/src/spatial/dimensions/dimensions.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, test } from "vitest";
 
-import * as dimensions from "@/spatial/dimensions/dimensions";
+import { dimensions } from "@/spatial/dimensions";
 
 describe("Dimensions", () => {
   describe("construction", () => {

package/src/spatial/direction/direction.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as direction from "@/spatial/direction/direction";
+import { direction } from "@/spatial/direction";
 
 describe("Direction", () => {
   describe("construction", () => {

package/src/spatial/location/location.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, test } from "vitest";
 
-import * as location from "@/spatial/location/location";
+import { location } from "@/spatial/location";
 
 describe("Location", () => {
   describe("construction", () => {

package/src/spatial/scale/scale.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as box from "@/spatial/box/box";
+import { box } from "@/spatial/box";
 import { Scale, XY } from "@/spatial/scale/scale";
 
 type ScaleSpec = [name: string, scale: Scale<number>, i: number, o: number];

package/src/spatial/scale/scale.ts

@@ -11,12 +11,12 @@ import { z } from "zod";
 
 import { clamp } from "@/clamp/clamp";
 import { type numeric } from "@/numeric";
-import * as bounds from "@/spatial/bounds/bounds";
+import { bounds } from "@/spatial/bounds";
+import { box } from "@/spatial/box";
 import { type Box, isBox } from "@/spatial/box/box";
-import * as box from "@/spatial/box/box";
-import type * as dims from "@/spatial/dimensions/dimensions";
-import * as location from "@/spatial/location/location";
-import * as xy from "@/spatial/xy/xy";
+import { type dimensions } from "@/spatial/dimensions";
+import { location } from "@/spatial/location";
+import { xy } from "@/spatial/xy";
 
 export const crudeXYTransform = z.object({ offset: xy.crudeZ, scale: xy.crudeZ });
 export type XYTransformT = z.infer<typeof crudeXYTransform>;
@@ -449,7 +449,7 @@ export class XY {
     return new XY().magnify(xy);
   }
 
-  static scale(box: dims.Dimensions | Box): XY {
+  static scale(box: dimensions.Dimensions | Box): XY {
     return new XY().scale(box);
   }
 
@@ -484,7 +484,7 @@ export class XY {
     return next;
   }
 
-  scale(b: Box | dims.Dimensions): XY {
+  scale(b: Box | dimensions.Dimensions): XY {
     const next = this.copy();
     if (isBox(b)) {
       const prevRoot = this.currRoot;

package/tsconfig.json

@@ -4,5 +4,5 @@
     "baseUrl": ".",
     "composite": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*", "eslint.config.ts"]
 }