@synnaxlabs/x 0.46.2 → 0.48.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";