@synnaxlabs/x 0.7.0

package/src/runtime/detect.ts

@@ -0,0 +1,34 @@
+// Copyright 2023 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.
+
+/** JavaScript runtime environments. */
+export type Runtime = "browser" | "node" | "webworker";
+
+/**
+ * Does best effort detection of the runtime environment.
+ *
+ * @returns The runtime environment.
+ */
+export const detect = (): Runtime => {
+  if (
+    // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+    typeof process !== "undefined" &&
+    process.versions != null &&
+    process.versions.node != null
+  )
+    return "node";
+
+  // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+  if (typeof window === "undefined" || window.document === undefined)
+    return "webworker";
+
+  return "browser";
+};
+
+export const RUNTIME = detect();

package/src/runtime/external.ts

@@ -0,0 +1,11 @@
+// Copyright 2023 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 "@/runtime/detect";
+export * from "@/runtime/os";

package/src/runtime/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 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 runtime from "@/runtime/external";

package/src/runtime/os.ts

@@ -0,0 +1,38 @@
+// Copyright 2023 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 { z } from "zod";
+
+export const OPERATING_SYSTEMS = ["MacOS", "Windows", "Linux", "Docker"] as const;
+export const osZ = z.enum(OPERATING_SYSTEMS);
+export type OS = (typeof OPERATING_SYSTEMS)[number];
+
+export interface GetOSProps {
+  force?: OS;
+  default?: OS;
+}
+
+let os: OS | undefined;
+
+const evalOS = (): OS | undefined => {
+  if (typeof window === "undefined") return undefined;
+  const userAgent = window.navigator.userAgent.toLowerCase();
+  if (userAgent.includes("mac")) return "MacOS";
+  else if (userAgent.includes("win")) return "Windows";
+  else if (userAgent.includes("linux")) return "Linux";
+  return undefined;
+};
+
+export const getOS = (props: GetOSProps = {}): OS | undefined => {
+  const { force, default: default_ } = props;
+  if (force != null) return force;
+  if (os != null) return os;
+  os = evalOS();
+  return os ?? default_;
+};

package/src/search.ts

@@ -0,0 +1,40 @@
+// Copyright 2023 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 CompareF } from "@/compare/compare";
+import { type Key, type KeyedRecord } from "@/record";
+
+const binary = <T>(arr: T[], target: T, compare: CompareF<T>): number => {
+  let left = 0;
+  let right = arr.length - 1;
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const cmp = compare(arr[mid], target);
+    if (cmp === 0) return mid;
+    if (cmp < 0) left = mid + 1;
+    else right = mid - 1;
+  }
+  return -1;
+};
+
+export const Search = {
+  binary,
+};
+
+export interface TermSearcher<T, K extends Key, E extends KeyedRecord<K, E>> {
+  search: (term: T) => E[];
+  retrieve: (keys: K[]) => E[];
+  page: (offset: number, limit: number) => E[];
+}
+
+export interface AsyncTermSearcher<T, K extends Key, E extends KeyedRecord<K, E>> {
+  search: (term: T) => Promise<E[]>;
+  retrieve: (keys: K[]) => Promise<E[]>;
+  page: (offset: number, limit: number) => Promise<E[]>;
+}

package/src/spatial/base.ts

@@ -0,0 +1,80 @@
+// Copyright 2023 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 { z } from "zod";
+
+export const numberCouple = z.tuple([z.number(), z.number()]);
+export type NumberCouple = z.infer<typeof numberCouple>;
+
+// Dimensions
+
+export const dimensions = z.object({ width: z.number(), height: z.number() });
+export type Dimensions = z.infer<typeof dimensions>;
+export const signedDimensions = z.object({
+  signedWidth: z.number(),
+  signedHeight: z.number(),
+});
+export const DIMENSIONS = ["width", "height"] as const;
+export const dimension = z.enum(DIMENSIONS);
+export type Dimension = (typeof DIMENSIONS)[number];
+export const ALIGNMENTS = ["start", "center", "end"] as const;
+export const SIGNED_DIMENSIONS = ["signedWidth", "signedHeight"] as const;
+export const signedDimension = z.enum(SIGNED_DIMENSIONS);
+export type SignedDimension = (typeof SIGNED_DIMENSIONS)[number];
+
+// XY
+
+export const xy = z.object({ x: z.number(), y: z.number() });
+export type XY = z.infer<typeof xy>;
+export const clientXY = z.object({ clientX: z.number(), clientY: z.number() });
+export type ClientXY = z.infer<typeof clientXY>;
+
+// Direction
+
+export const DIRECTIONS = ["x", "y"] as const;
+export const direction = z.enum(DIRECTIONS);
+export type Direction = z.infer<typeof direction>;
+
+// Location
+
+export const OUTER_LOCATIONS = ["top", "right", "bottom", "left"] as const;
+export const outerLocation = z.enum(OUTER_LOCATIONS);
+export type OuterLocation = (typeof OUTER_LOCATIONS)[number];
+export const X_LOCATIONS = ["left", "right"] as const;
+export const xLocation = z.enum(X_LOCATIONS);
+export type XLocation = (typeof X_LOCATIONS)[number];
+export const Y_LOCATIONS = ["top", "bottom"] as const;
+export const yLocation = z.enum(Y_LOCATIONS);
+export type YLocation = (typeof Y_LOCATIONS)[number];
+export const CENTER_LOCATIONS = ["center"] as const;
+export const centerlocation = z.enum(CENTER_LOCATIONS);
+export type CenterLocation = (typeof CENTER_LOCATIONS)[number];
+export const LOCATIONS = [...OUTER_LOCATIONS, ...CENTER_LOCATIONS] as const;
+export const location = z.enum(LOCATIONS);
+export type Location = z.infer<typeof location>;
+
+// Alignment
+
+export const alignment = z.enum(ALIGNMENTS);
+export type Alignment = (typeof ALIGNMENTS)[number];
+export const ORDERS = ["first", "last"] as const;
+export const order = z.enum(ORDERS);
+export type Order = (typeof ORDERS)[number];
+
+// Bounds
+
+export const bounds = z.object({ lower: z.number(), upper: z.number() });
+export type Bounds = z.infer<typeof bounds>;
+
+export const crudeBounds = z.union([bounds, numberCouple]);
+export type CrudeBounds = z.infer<typeof crudeBounds>;
+export const crudeDirection = z.union([direction, location]);
+export type CrudeDirection = z.infer<typeof crudeDirection>;
+export const crudeLocation = z.union([direction, location, z.instanceof(String)]);
+export type CrudeLocation = z.infer<typeof crudeLocation>;

package/src/spatial/bounds.spec.ts

@@ -0,0 +1,99 @@
+// Copyright 2023 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, test } from "vitest";
+
+import * as bounds from "@/spatial/bounds";
+
+describe("Bounds", () => {
+  describe("construction", () => {
+    type T = [string, bounds.Crude];
+    const TESTS: T[] = [
+      ["from couple", [1, 2]],
+      ["from bounds", { lower: 1, upper: 2 }],
+      ["from invalid bounds", { upper: 1, lower: 2 }],
+    ];
+    TESTS.forEach(([name, arg]) => {
+      test(name, () => {
+        const bound = bounds.construct(arg);
+        expect(bound.lower).toEqual(1);
+        expect(bound.upper).toEqual(2);
+      });
+    });
+    it("should consider a single argument as the upper bound", () => {
+      const bound = bounds.construct(1);
+      expect(bound.lower).toEqual(0);
+      expect(bound.upper).toEqual(1);
+    });
+  });
+  describe("contains", () => {
+    it("should return true if the value is within the bounds", () => {
+      const b = bounds.construct([1, 2]);
+      expect(bounds.contains(b, 1.5)).toEqual(true);
+    });
+    it("should return false if the value is outside the bounds", () => {
+      const b = bounds.construct([1, 2]);
+      expect(bounds.contains(b, 2.5)).toEqual(false);
+    });
+    it("should return true if the value is equal to the lower bound", () => {
+      const b = bounds.construct([1, 2]);
+      expect(bounds.contains(b, 1)).toEqual(true);
+    });
+    it("should return false if the value is equal to the upper bound", () => {
+      const b = bounds.construct([1, 2]);
+      expect(bounds.contains(b, 2)).toEqual(false);
+    });
+  });
+  describe("span", () => {
+    it("should return the span of the bound", () => {
+      const b = bounds.construct([1, 2]);
+      expect(bounds.span(b)).toEqual(1);
+    });
+  });
+  test("isZero", () => {
+    const b = bounds.construct([0, 0]);
+    expect(bounds.isZero(b)).toEqual(true);
+  });
+  test("spanIsZero", () => {
+    const b = bounds.construct([1, 1]);
+    expect(bounds.spanIsZero(b)).toEqual(true);
+  });
+  describe("max", () => {
+    it("should return the bound with the maximum possible span", () => {
+      const args: bounds.Crude[] = [
+        [1, 2],
+        [-1, 1],
+      ];
+      const bound = bounds.max(args);
+      expect(bound.lower).toEqual(-1);
+      expect(bound.upper).toEqual(2);
+    });
+  });
+  describe("min", () => {
+    it("should return the bound with the minimum possible span", () => {
+      const args: bounds.Crude[] = [
+        [1, 2],
+        [-1, 1],
+      ];
+      const bound = bounds.min(args);
+      expect(bound.lower).toEqual(1);
+      expect(bound.upper).toEqual(1);
+    });
+  });
+  describe("isFinite", () => {
+    it("should return false if either bound is infinite", () => {
+      const b = bounds.construct([1, Infinity]);
+      expect(bounds.isFinite(b)).toEqual(false);
+    });
+    it("should return true if both bounds are finite", () => {
+      const b = bounds.construct([1, 2]);
+      expect(bounds.isFinite(b)).toEqual(true);
+    });
+  });
+});

package/src/spatial/bounds.ts

@@ -0,0 +1,80 @@
+// Copyright 2023 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 Bounds, bounds, type CrudeBounds } from "@/spatial/base";
+
+export { type Bounds, bounds };
+
+export type Crude = CrudeBounds;
+
+export const construct = (lower: number | Crude, upper?: number): Bounds => {
+  const b = { lower: 0, upper: 0 };
+  if (typeof lower === "number") {
+    if (upper != null) {
+      b.lower = lower;
+      b.upper = upper;
+    } else {
+      b.lower = 0;
+      b.upper = lower;
+    }
+  } else if (Array.isArray(lower)) {
+    [b.lower, b.upper] = lower;
+  } else {
+    b.lower = lower.lower;
+    b.upper = lower.upper;
+  }
+  return makeValid(b);
+};
+
+export const ZERO = { lower: 0, upper: 0 };
+
+export const INFINITE = { lower: -Infinity, upper: Infinity };
+
+export const DECIMAL = { lower: 0, upper: 1 };
+
+export const CLIP = { lower: -1, upper: 1 };
+
+export const equals = (a?: Bounds, b?: Bounds): boolean =>
+  a?.lower === b?.lower && a?.upper === b?.upper;
+
+export const makeValid = (a: Bounds): Bounds => {
+  if (a.lower > a.upper) return { lower: a.upper, upper: a.lower };
+  return a;
+};
+
+export const clamp = (bounds: Bounds, target: number): number => {
+  if (target < bounds.lower) return bounds.lower;
+  if (target >= bounds.upper) return bounds.upper - 1;
+  return target;
+};
+
+export const contains = (bounds: Bounds, target: number): boolean =>
+  target >= bounds.lower && target < bounds.upper;
+
+export const overlapsWith = (a: Bounds, b: Bounds): boolean =>
+  contains(a, a.lower) || contains(b, b.upper - 1);
+
+export const span = (a: Bounds): number => a.upper - a.lower;
+
+export const isZero = (a: Bounds): boolean => a.lower === 0 && a.upper === 0;
+
+export const spanIsZero = (a: Bounds): boolean => span(a) === 0;
+
+export const isFinite = (a: Bounds): boolean =>
+  Number.isFinite(a.lower) && Number.isFinite(a.upper);
+
+export const max = (bounds: Crude[]): Bounds => ({
+  lower: Math.min(...bounds.map((b) => construct(b).lower)),
+  upper: Math.max(...bounds.map((b) => construct(b).upper)),
+});
+
+export const min = (bounds: Crude[]): Bounds => ({
+  lower: Math.max(...bounds.map((b) => construct(b).lower)),
+  upper: Math.min(...bounds.map((b) => construct(b).upper)),
+});

package/src/spatial/box.spec.ts

@@ -0,0 +1,137 @@
+// Copyright 2023 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, test, expect, it } from "vitest";
+
+import * as box from "@/spatial/box";
+import * as location from "@/spatial/location";
+import type * as xy from "@/spatial/xy";
+
+describe("Box", () => {
+  describe("construction", () => {
+    test("from dom rect", () => {
+      const b = box.construct({ left: 0, top: 0, right: 10, bottom: 10 });
+      expect(box.topLeft(b)).toEqual({ x: 0, y: 0 });
+      expect(box.topRight(b)).toEqual({ x: 10, y: 0 });
+      expect(box.bottomLeft(b)).toEqual({ x: 0, y: 10 });
+      expect(box.bottomRight(b)).toEqual({ x: 10, y: 10 });
+    });
+    test("from two points", () => {
+      const b = box.construct({ x: 0, y: 0 }, { x: 10, y: 10 });
+      expect(box.topLeft(b)).toEqual({ x: 0, y: 0 });
+      expect(box.topRight(b)).toEqual({ x: 10, y: 0 });
+      expect(box.bottomLeft(b)).toEqual({ x: 0, y: 10 });
+      expect(box.bottomRight(b)).toEqual({ x: 10, y: 10 });
+    });
+    test("from point and dimensions", () => {
+      const b = box.construct({ x: 0, y: 0 }, { width: 10, height: 10 });
+      expect(box.topLeft(b)).toEqual({ x: 0, y: 0 });
+      expect(box.topRight(b)).toEqual({ x: 10, y: 0 });
+      expect(box.bottomLeft(b)).toEqual({ x: 0, y: 10 });
+      expect(box.bottomRight(b)).toEqual({ x: 10, y: 10 });
+    });
+    test("from point and width and height", () => {
+      const b = box.construct({ x: 0, y: 0 }, 10, 10);
+      expect(box.topLeft(b)).toEqual({ x: 0, y: 0 });
+      expect(box.topRight(b)).toEqual({ x: 10, y: 0 });
+      expect(box.bottomLeft(b)).toEqual({ x: 0, y: 10 });
+      expect(box.bottomRight(b)).toEqual({ x: 10, y: 10 });
+    });
+    test("from raw params", () => {
+      const b = box.construct(0, 0, 10, 10);
+      expect(box.topLeft(b)).toEqual({ x: 0, y: 0 });
+      expect(box.topRight(b)).toEqual({ x: 10, y: 0 });
+      expect(box.bottomLeft(b)).toEqual({ x: 0, y: 10 });
+      expect(box.bottomRight(b)).toEqual({ x: 10, y: 10 });
+    });
+  });
+  describe("zod schema", () => {
+    const CASES: Array<[string, unknown]> = [
+      [
+        "raw string root",
+        {
+          root: { x: "left", y: "top" },
+          one: { x: 0, y: 0 },
+          two: { x: 10, y: 10 },
+        },
+      ],
+      [
+        "string instance root",
+        {
+          root: { x: String("left"), y: String("top") },
+          one: { x: 0, y: 0 },
+          two: { x: 10, y: 10 },
+        },
+      ],
+    ];
+    CASES.forEach(([title, value]) => {
+      it(`should parse ${title}`, () => {
+        expect(() => box.box.parse(value)).not.toThrow();
+      });
+    });
+  });
+  describe("properties", () => {
+    const b = box.construct(20, 30, 40, 50);
+    describe("loc", () => {
+      const v: location.Location[] = ["left", "right", "top", "bottom"];
+      const expected: number[] = [20, 60, 30, 80];
+      v.forEach((v, i) => {
+        test(`loc-${v}`, () => expect(box.loc(b, v)).toEqual(expected[i]));
+      });
+    });
+    describe("xyLoc", () => {
+      const v: location.XY[] = [
+        location.BOTTOM_CENTER,
+        location.LEFT_CENTER,
+        location.RIGHT_CENTER,
+        location.TOP_CENTER,
+        location.BOTTOM_LEFT,
+        location.BOTTOM_RIGHT,
+        location.TOP_LEFT,
+        location.TOP_RIGHT,
+      ];
+      const expected: xy.Crude[] = [
+        { x: 40, y: 80 },
+        { x: 20, y: 55 },
+        { x: 60, y: 55 },
+        { x: 40, y: 30 },
+        { x: 20, y: 80 },
+        { x: 60, y: 80 },
+        { x: 20, y: 30 },
+        { x: 60, y: 30 },
+      ];
+      v.forEach((v, i) => {
+        test(`xyLoc-${location.xyToString(v)}`, () =>
+          expect(box.xyLoc(b, v)).toEqual(expected[i]));
+      });
+    });
+  });
+  describe("equality", () => {
+    it("should be equal to itself", () => {
+      const b = box.construct(0, 0, 10, 10);
+      expect(box.equals(b, b)).toBe(true);
+    });
+    it("should be equal to a box with the same values", () => {
+      const b = box.construct(0, 0, 10, 10);
+      const b2 = box.construct(0, 0, 10, 10);
+      expect(box.equals(b, b2)).toBe(true);
+    });
+  });
+  describe("positionInCenterOf", () => {
+    it("should position the box in the center of the other box", () => {
+      let b = box.construct(0, 0, 10, 10);
+      const b2 = box.construct(0, 0, 20, 20);
+      b = box.positionInCenter(b, b2);
+      expect(box.topLeft(b)).toEqual({ x: 5, y: 5 });
+      expect(box.topRight(b)).toEqual({ x: 15, y: 5 });
+      expect(box.bottomLeft(b)).toEqual({ x: 5, y: 15 });
+      expect(box.bottomRight(b)).toEqual({ x: 15, y: 15 });
+    });
+  });
+});