@synnaxlabs/x 0.54.2 → 0.56.0

package/src/text/external.ts

@@ -0,0 +1,11 @@
+// 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 * from "@/text/types";
+export * from "@/text/types.gen";

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

package/src/text/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 LEVELS = ["h1", "h2", "h3", "h4", "h5", "p", "small"] as const;
+export const levelZ = z.enum(LEVELS);
+export type Level = z.infer<typeof levelZ>;

package/src/text/types.ts

@@ -0,0 +1,37 @@
+// 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.
+
+import { z } from "zod";
+
+import { type Level, LEVELS } from "@/text/types.gen";
+
+/** Steps a typography level down by one rank; bottoms out at the smallest. */
+export const downLevel = (level: Level): Level => {
+  const index = LEVELS.indexOf(level);
+  if (index === -1 || index === LEVELS.length - 1) return level;
+  return LEVELS[index + 1];
+};
+
+export const weightZ = z.union([
+  z.number(),
+  z.enum(["normal", "bold", "bolder", "lighter"]),
+]);
+
+/** Weight sets the weight of the text. */
+export type Weight = z.infer<typeof weightZ>;
+
+export const specZ = z.object({
+  size: z.number(),
+  weight: z.union([z.number(), z.string()]),
+  lineHeight: z.number(),
+  textTransform: z.string().optional(),
+});
+
+/** Defines a particular typography style. */
+export type Spec = z.infer<typeof specZ>;

package/src/{worker → throttle}/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 * from "@/worker/worker";
+export * from "@/throttle/throttle";

package/src/throttle/throttle.spec.ts

@@ -0,0 +1,147 @@
+// 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.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { TimeSpan } from "@/telem/telem";
+import { throttle } from "@/throttle/throttle";
+
+describe("throttle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should execute immediately on the leading edge", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+    expect(fn).toHaveBeenCalledTimes(0);
+    throttled(10);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(10);
+  });
+
+  it("should throttle repeated calls during the wait period", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+    expect(fn).toHaveBeenCalledTimes(0);
+    throttled(10);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(10);
+    throttled(20);
+    throttled(30);
+    throttled(40);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("should run a trailing call with the latest arguments", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+    expect(fn).toHaveBeenCalledTimes(0);
+    throttled(10);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(10);
+    throttled(20);
+    throttled(30);
+    throttled(40);
+    expect(fn).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenLastCalledWith(40);
+  });
+
+  it("should schedule the trailing call after only the remaining wait time", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+    throttled(10);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(10);
+    vi.advanceTimersByTime(90);
+    throttled(20);
+    expect(fn).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(9);
+    expect(fn).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenLastCalledWith(20);
+  });
+
+  it("should not schedule multiple trailing calls", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+    throttled(10);
+    throttled(20);
+    throttled(30);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenNthCalledWith(1, 10);
+    expect(fn).toHaveBeenNthCalledWith(2, 30);
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("should execute again immediately after the wait period has passed", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+
+    throttled(10);
+    vi.advanceTimersByTime(100);
+    throttled(20);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenNthCalledWith(1, 10);
+    expect(fn).toHaveBeenNthCalledWith(2, 20);
+  });
+
+  it("should preserve null arguments", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+    throttled(null);
+    throttled(20);
+    throttled(null);
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenNthCalledWith(1, null);
+    expect(fn).toHaveBeenNthCalledWith(2, null);
+  });
+
+  it("should clear pending state before invoking the function", () => {
+    const fn = vi.fn();
+    fn.mockImplementation((value: number) => {
+      if (value === 20) throttled(30);
+    });
+
+    const throttled = throttle(fn, TimeSpan.milliseconds(100));
+
+    throttled(10);
+    throttled(20);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenNthCalledWith(1, 10);
+    expect(fn).toHaveBeenNthCalledWith(2, 20);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(3);
+    expect(fn).toHaveBeenNthCalledWith(3, 30);
+  });
+
+  it("should not throttle the execution of the given function if the time is 0", () => {
+    const fn = vi.fn();
+    const throttled = throttle(fn, TimeSpan.ZERO);
+    expect(throttled).toBe(fn);
+  });
+});

package/src/throttle/throttle.ts

@@ -0,0 +1,44 @@
+// 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.
+
+import { type CrudeTimeSpan, TimeSpan, TimeStamp } from "@/telem/telem";
+
+export const throttle = <Args extends unknown[]>(
+  func: (...args: Args) => void,
+  waitFor: CrudeTimeSpan,
+): ((...args: Args) => void) => {
+  const throttlePeriod = new TimeSpan(waitFor);
+  if (throttlePeriod.valueOf() <= 0) return func;
+  let timeout: NodeJS.Timeout | undefined;
+  let lastInvokeTime: TimeStamp = TimeStamp.MIN;
+  let latestArgs: Args | null = null;
+  const invoke = (): void => {
+    if (latestArgs === null) return;
+    lastInvokeTime = TimeStamp.now();
+    const args = latestArgs;
+    latestArgs = null;
+    func(...args);
+  };
+  return (...args: Args): void => {
+    const timeSinceLastInvoke = TimeStamp.since(lastInvokeTime);
+    latestArgs = args;
+    const remaining = throttlePeriod.sub(timeSinceLastInvoke);
+    if (remaining.valueOf() <= 0 || remaining.greaterThan(throttlePeriod)) {
+      clearTimeout(timeout);
+      timeout = undefined;
+      invoke();
+      return;
+    }
+    if (timeout != null) return;
+    timeout = setTimeout(() => {
+      timeout = undefined;
+      invoke();
+    }, remaining.milliseconds);
+  };
+};

package/src/zod/parse.ts

@@ -164,7 +164,7 @@ const flattenIssues = (
       out.push(...flattenIssues(issue.issues, fullPath));
       continue;
     }
-    out.push({ ...issue, path: fullPath } as z.core.$ZodIssue);
+    out.push({ ...issue, path: fullPath });
   }
   return out;
 };
@@ -184,8 +184,7 @@ const expandUnrecognizedKeys = (
       "keys" in issue &&
       Array.isArray(issue.keys)
     ) {
-      for (const key of issue.keys)
-        out.push({ ...issue, path: [...issue.path, key] } as z.core.$ZodIssue);
+      for (const key of issue.keys) out.push({ ...issue, path: [...issue.path, key] });
       continue;
     }
     out.push(issue);