@synnaxlabs/x 0.47.0 → 0.49.0

package/src/narrow/narrow.spec.ts

@@ -0,0 +1,70 @@
+// 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 { narrow } from "@/narrow";
+
+describe("narrow", () => {
+  describe("isObject", () => {
+    it("should return true for plain objects", () => {
+      expect(narrow.isObject({})).toBe(true);
+      expect(narrow.isObject({ a: 1 })).toBe(true);
+      expect(narrow.isObject({ nested: { obj: true } })).toBe(true);
+    });
+
+    it("should return false for null", () => {
+      expect(narrow.isObject(null)).toBe(false);
+    });
+
+    it("should return false for undefined", () => {
+      expect(narrow.isObject(undefined)).toBe(false);
+      expect(narrow.isObject()).toBe(false);
+    });
+
+    it("should return false for arrays", () => {
+      expect(narrow.isObject([])).toBe(false);
+      expect(narrow.isObject([1, 2, 3])).toBe(false);
+      expect(narrow.isObject([{ a: 1 }])).toBe(false);
+    });
+
+    it("should return false for primitives", () => {
+      expect(narrow.isObject(0)).toBe(false);
+      expect(narrow.isObject(1)).toBe(false);
+      expect(narrow.isObject("")).toBe(false);
+      expect(narrow.isObject("string")).toBe(false);
+      expect(narrow.isObject(true)).toBe(false);
+      expect(narrow.isObject(false)).toBe(false);
+      expect(narrow.isObject(Symbol("test"))).toBe(false);
+      expect(narrow.isObject(42n)).toBe(false);
+    });
+
+    it("should return true for class instances", () => {
+      class TestClass {}
+      expect(narrow.isObject(new TestClass())).toBe(true);
+      expect(narrow.isObject(new Date())).toBe(true);
+      expect(narrow.isObject(new Map())).toBe(true);
+      expect(narrow.isObject(new Set())).toBe(true);
+    });
+
+    it("should return true for Object.create(null)", () => {
+      expect(narrow.isObject(Object.create(null))).toBe(true);
+    });
+
+    it("should return false for functions", () => {
+      expect(narrow.isObject(() => {})).toBe(false);
+      expect(narrow.isObject(() => {})).toBe(false);
+      expect(narrow.isObject(async () => {})).toBe(false);
+    });
+
+    it("should return true for regex", () => {
+      expect(narrow.isObject(/test/)).toBe(true);
+    });
+  });
+});

package/src/{identity.ts → narrow/narrow.ts}

@@ -9,6 +9,12 @@
 
 import { type record } from "@/record";
 
+export type IsUndefined<T> = [T] extends [undefined] // T can be assigned to undefined
+  ? [undefined] extends [T] // undefined can be assigned to T
+    ? true // both directions → exactly undefined
+    : false
+  : false;
+
 export const isObject = <T extends record.Unknown = record.Unknown>(
   item?: unknown,
 ): item is T => item != null && typeof item === "object" && !Array.isArray(item);

package/src/numeric/numeric.ts

@@ -8,8 +8,3 @@
 // included in the file licenses/APL.txt.
 
 export type Value = number | bigint;
-export type ValueGuard<T> = [T] extends [number]
-  ? number
-  : [T] extends [bigint]
-    ? bigint
-    : never;

package/src/observe/observe.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 { type Destructor } from "@/destructor";
+import { type destructor } from "@/destructor";
 
 /** Handler is called when the value of an Observable changes. */
 export type Handler<T> = (value: T) => void;
@@ -22,7 +22,7 @@ export interface Observable<T> {
    * @param handler The handler to bind to the Observable.
    * @returns A function that can be called to unbind the handler from the Observable.
    */
-  onChange: (handler: Handler<T>) => Destructor;
+  onChange: (handler: Handler<T>) => destructor.Destructor;
 }
 
 /** An Observable that can be closed using an async function. */
@@ -52,7 +52,7 @@ export class Observer<I, O = I> implements ObservableAsyncCloseable<O> {
   }
 
   /** Implements the observable interface. */
-  onChange(handler: Handler<O>): Destructor {
+  onChange(handler: Handler<O>): destructor.Destructor {
     this.handlers.set(handler, null);
     return () => this.handlers.delete(handler);
   }
@@ -84,7 +84,7 @@ export class BaseObserver<V> implements Observable<V> {
     this.handlers = handlers ?? new Map();
   }
 
-  onChange(handler: Handler<V>): Destructor {
+  onChange(handler: Handler<V>): destructor.Destructor {
     this.handlers.set(handler, null);
     return () => this.handlers.delete(handler);
   }

package/src/{replace.ts → optional/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 type Replace<T, R> = Omit<T, keyof R> & R;
+export * as optional from "@/optional/optional";

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

package/src/scheduler/scheduler.spec.ts

@@ -0,0 +1,82 @@
+// 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 { scheduler } from "@/scheduler";
+
+describe("scheduler", () => {
+  describe("flushMicrotasks", () => {
+    it("should return a resolved promise", async () => {
+      const result = scheduler.flushMicrotasks();
+      expect(result).toBeInstanceOf(Promise);
+      await expect(result).resolves.toBeUndefined();
+    });
+
+    it("should flush microtasks before continuing", async () => {
+      const order: number[] = [];
+      void Promise.resolve().then(() => order.push(1));
+      void Promise.resolve().then(() => order.push(2));
+      await scheduler.flushMicrotasks();
+      expect(order).toEqual([1, 2]);
+    });
+
+    it("should resolve immediately without waiting for macrotasks", async () => {
+      const order: number[] = [];
+      setTimeout(() => order.push(1), 0);
+      await scheduler.flushMicrotasks();
+      expect(order).toEqual([]);
+    });
+  });
+
+  describe("flushTaskQueue", () => {
+    it("should return a promise", async () => {
+      const result = scheduler.flushTaskQueue();
+      expect(result).toBeInstanceOf(Promise);
+      await expect(result).resolves.toBeUndefined();
+    });
+
+    it("should flush macrotasks from setTimeout", async () => {
+      const order: number[] = [];
+      setTimeout(() => order.push(1), 0);
+      setTimeout(() => order.push(2), 0);
+      await scheduler.flushTaskQueue();
+      expect(order).toEqual([1, 2]);
+    });
+
+    it("should execute after microtasks", async () => {
+      const order: string[] = [];
+      void Promise.resolve().then(() => order.push("micro"));
+      setTimeout(() => order.push("macro"), 0);
+      await scheduler.flushTaskQueue();
+      expect(order).toEqual(["micro", "macro"]);
+    });
+
+    it("should handle nested flushes", async () => {
+      const order: number[] = [];
+      setTimeout(() => order.push(1), 0);
+      await scheduler.flushTaskQueue();
+      setTimeout(() => order.push(2), 0);
+      await scheduler.flushTaskQueue();
+      expect(order).toEqual([1, 2]);
+    });
+  });
+
+  describe("flush order", () => {
+    it("should flush microtasks before macrotasks", async () => {
+      const order: string[] = [];
+      setTimeout(() => order.push("macro"), 0);
+      void Promise.resolve().then(() => order.push("micro"));
+      await scheduler.flushMicrotasks();
+      expect(order).toEqual(["micro"]);
+      await scheduler.flushTaskQueue();
+      expect(order).toEqual(["micro", "macro"]);
+    });
+  });
+});

package/src/shallow/copy.spec.ts

@@ -0,0 +1,141 @@
+// 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 { shallow } from "@/shallow";
+
+describe("shallow", () => {
+  describe("copy", () => {
+    it("should shallow copy plain objects", () => {
+      const obj = { a: 1, b: 2 };
+      const copied = shallow.copy(obj);
+      expect(copied).toEqual(obj);
+      expect(copied).not.toBe(obj);
+    });
+
+    it("should shallow copy arrays", () => {
+      const arr = [1, 2, 3];
+      const copied = shallow.copy(arr);
+      expect(copied).toEqual(arr);
+      expect(copied).not.toBe(arr);
+    });
+
+    it("should not deep copy nested objects", () => {
+      const obj = { a: 1, nested: { b: 2 } };
+      const copied = shallow.copy(obj);
+      expect(copied.nested).toBe(obj.nested);
+      copied.nested.b = 999;
+      expect(obj.nested.b).toBe(999);
+    });
+
+    it("should not deep copy nested arrays", () => {
+      const arr = [1, [2, 3]];
+      const copied = shallow.copy(arr);
+      expect(copied[1]).toBe(arr[1]);
+      (copied[1] as number[])[0] = 999;
+      expect((arr[1] as number[])[0]).toBe(999);
+    });
+
+    it("should return primitives as-is", () => {
+      expect(shallow.copy(42)).toBe(42);
+      expect(shallow.copy("string")).toBe("string");
+      expect(shallow.copy(true)).toBe(true);
+      expect(shallow.copy(false)).toBe(false);
+    });
+
+    it("should return null as-is", () => {
+      expect(shallow.copy(null)).toBe(null);
+    });
+
+    it("should return undefined as-is", () => {
+      expect(shallow.copy(undefined)).toBe(undefined);
+    });
+
+    it("should copy arrays with objects", () => {
+      const arr = [{ a: 1 }, { b: 2 }];
+      const copied = shallow.copy(arr);
+      expect(copied).not.toBe(arr);
+      expect(copied[0]).toBe(arr[0]);
+      expect(copied[1]).toBe(arr[1]);
+    });
+
+    it("should copy objects with various types", () => {
+      const obj = {
+        num: 42,
+        str: "test",
+        bool: true,
+        arr: [1, 2],
+        nested: { x: 1 },
+      };
+      const copied = shallow.copy(obj);
+      expect(copied).toEqual(obj);
+      expect(copied).not.toBe(obj);
+      expect(copied.arr).toBe(obj.arr);
+      expect(copied.nested).toBe(obj.nested);
+    });
+
+    it("should copy empty objects", () => {
+      const obj = {};
+      const copied = shallow.copy(obj);
+      expect(copied).toEqual({});
+      expect(copied).not.toBe(obj);
+    });
+
+    it("should copy empty arrays", () => {
+      const arr: unknown[] = [];
+      const copied = shallow.copy(arr);
+      expect(copied).toEqual([]);
+      expect(copied).not.toBe(arr);
+    });
+
+    it("should handle class instances", () => {
+      class TestClass {
+        value = 42;
+      }
+      const instance = new TestClass();
+      const copied = shallow.copy(instance);
+      expect(copied).not.toBe(instance);
+      expect(copied.value).toBe(42);
+    });
+
+    it("should spread Date objects into plain objects", () => {
+      const date = new Date("2025-01-01");
+      const copied = shallow.copy(date);
+      expect(copied).not.toBe(date);
+      expect(copied).toEqual({});
+    });
+
+    it("should handle objects with symbol keys", () => {
+      const sym = Symbol("test");
+      const obj = { [sym]: "value", regular: 1 };
+      const copied = shallow.copy(obj);
+      expect(copied[sym]).toBe("value");
+      expect(copied.regular).toBe(1);
+    });
+
+    it("should lose prototype when spreading objects", () => {
+      class Custom {
+        x = 1;
+      }
+      const obj = new Custom();
+      const copied = shallow.copy(obj);
+      expect(copied).not.toBeInstanceOf(Custom);
+      expect(copied.x).toBe(1);
+    });
+
+    it("should fill holes in sparse arrays", () => {
+      const arr = [1, undefined, 3];
+      const copied = shallow.copy(arr);
+      expect(copied).not.toBe(arr);
+      expect(copied).toEqual([1, undefined, 3]);
+      expect(1 in copied).toBe(true);
+    });
+  });
+});

package/src/{shallowCopy.ts → shallow/copy.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.
 
-export const shallowCopy = <T>(obj: T): T => {
+export const copy = <T>(obj: T): T => {
   if (Array.isArray(obj)) return [...obj] as T;
   if (typeof obj === "object" && obj !== null) return { ...obj };
   return obj;

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

package/src/spatial/base.ts

@@ -10,7 +10,6 @@
 import { z } from "zod";
 
 export const numberCouple = z.tuple([z.number(), z.number()]);
-export const bigNumberCouple = z.tuple([z.bigint(), z.bigint()]);
 export type NumberCouple<T extends number | bigint = number> = [T, T];
 
 // Dimensions
@@ -21,13 +20,9 @@ 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 type Dimension = "width" | "height";
 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];
+export type SignedDimension = "signedWidth" | "signedHeight";
 
 // XY
 
@@ -56,7 +51,7 @@ 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;
+const LOCATIONS = [...OUTER_LOCATIONS, ...CENTER_LOCATIONS] as const;
 export const location = z.enum(LOCATIONS);
 export type Location = z.infer<typeof location>;
 
@@ -71,22 +66,18 @@ export type Order = (typeof ORDERS)[number];
 // Bounds
 
 export const bounds = z.object({ lower: z.number(), upper: z.number() });
-export const bigBounds = z.object({ lower: z.bigint(), upper: z.bigint() });
 export interface Bounds<T extends number | bigint = number> {
   lower: T;
   upper: T;
 }
 
-export const crudeBounds = z.union([bounds, numberCouple]);
-export const bigCrudeBounds = z.union([bigBounds, numberCouple]);
 export type CrudeBounds<T extends number | bigint = number> =
   | Bounds<T>
   | NumberCouple<T>;
 export const crudeDirection = z.enum([...direction.options, ...location.options]);
-export const crudeXDirection = z.enum(["x", "left", "right"]);
-export const crudeYDirection = z.enum(["y", "top", "bottom"]);
 export type CrudeDirection = z.infer<typeof crudeDirection>;
-export type CrudeXDirection = z.infer<typeof crudeXDirection>;
-export type CrudeYDirection = z.infer<typeof crudeYDirection>;
+export type CrudeXDirection = "x" | "left" | "right";
+export type CrudeYDirection = "y" | "top" | "bottom";
+export type AngularDirection = "clockwise" | "counterclockwise";
 export const crudeLocation = z.union([direction, location, z.instanceof(String)]);
 export type CrudeLocation = z.infer<typeof crudeLocation>;

package/src/spatial/direction/direction.ts

@@ -8,6 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import {
+  type AngularDirection,
   type CrudeDirection,
   crudeDirection,
   type CrudeXDirection,
@@ -29,6 +30,7 @@ export const crude = crudeDirection;
 export type Crude = CrudeDirection;
 export type CrudeX = CrudeXDirection;
 export type CrudeY = CrudeYDirection;
+export type Angular = AngularDirection;
 
 export const construct = (c: Crude): Direction => {
   if (DIRECTIONS.includes(c as Direction)) return c as Direction;

package/src/spatial/external.ts

@@ -8,10 +8,11 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/spatial/bounds";
-export { box } from "@/spatial/box";
+export * from "@/spatial/box";
 export * from "@/spatial/dimensions";
 export * from "@/spatial/direction";
 export * from "@/spatial/location";
 export * from "@/spatial/scale";
 export * as spatial from "@/spatial/spatial";
+export * from "@/spatial/sticky";
 export * from "@/spatial/xy";

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

@@ -21,4 +21,20 @@ describe("Location", () => {
       test(name, () => expect(location.construct(arg)).toEqual("left")),
     );
   });
+
+  describe("rotate", () => {
+    test("should rotate clockwise", () => {
+      expect(location.rotate("top", "clockwise")).toEqual("left");
+      expect(location.rotate("left", "clockwise")).toEqual("bottom");
+      expect(location.rotate("bottom", "clockwise")).toEqual("right");
+      expect(location.rotate("right", "clockwise")).toEqual("top");
+    });
+
+    test("should rotate counterclockwise", () => {
+      expect(location.rotate("top", "counterclockwise")).toEqual("right");
+      expect(location.rotate("left", "counterclockwise")).toEqual("top");
+      expect(location.rotate("bottom", "counterclockwise")).toEqual("left");
+      expect(location.rotate("right", "counterclockwise")).toEqual("bottom");
+    });
+  });
 });

package/src/spatial/location/location.ts

@@ -11,6 +11,7 @@ import { z } from "zod";
 
 import { caseconv } from "@/caseconv";
 import {
+  type AngularDirection,
   CENTER_LOCATIONS,
   type CenterLocation,
   centerLocation,
@@ -58,12 +59,11 @@ const SWAPPED: Record<Location, Location> = {
   center: "center",
 };
 
-const ROTATE_90: Record<Location, Location> = {
-  top: "left",
-  right: "top",
-  bottom: "right",
-  left: "bottom",
-  center: "center",
+const ROTATIONS: Record<Outer, Record<AngularDirection, Outer>> = {
+  top: { clockwise: "left", counterclockwise: "right" },
+  right: { clockwise: "top", counterclockwise: "bottom" },
+  bottom: { clockwise: "right", counterclockwise: "left" },
+  left: { clockwise: "bottom", counterclockwise: "top" },
 };
 
 export const crude = crudeLocation;
@@ -79,7 +79,7 @@ export const construct = (cl: Crude): Location => {
 
 export const swap = (cl: Crude): Location => SWAPPED[construct(cl)];
 
-export const rotate90 = (cl: Crude): Location => ROTATE_90[construct(cl)];
+export const rotate = (loc: Outer, dir: AngularDirection): Outer => ROTATIONS[loc][dir];
 
 export const direction = (cl: Crude): Direction => {
   const l = construct(cl);

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