@forthtilliath/ts-kit 0.1.0 → 0.3.0

package/dist/classes/array.js

@@ -52,4 +52,78 @@ export class FArray extends Array {
         // @ts-expect-error searchElement is unknown
         return super.includes(searchElement, fromIndex);
     }
+    /**
+     * Same as `Array.indexOf`, but accepts a search value outside of `T`
+     * instead of rejecting it at compile-time (the native typings only accept
+     * `T`, exactly like `Array.includes` before the override above).
+     *
+     * @param searchElement The value to search for — no longer restricted to `T`.
+     * @param fromIndex The position in this array at which to begin searching for searchElement.
+     * @returns The index of the first match, or -1 if not found.
+     *
+     * @example
+     * // Normal operation of Array.indexOf
+     * const buz = "buz";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr: FBB[] = ["foo", "bar", "baz"];
+     * arr.indexOf(buz);
+     * // -----------^
+     * // The argument of type 'buz' is not assignable to the parameter of type 'FBB'.
+     *
+     * @example
+     * // FArray.indexOf
+     * const buz = "buz";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr = new FArray<FBB>("foo", "bar", "baz");
+     * arr.indexOf(buz); // compiles fine, returns -1
+     */
+    indexOf(searchElement, fromIndex = 0) {
+        // @ts-expect-error searchElement is unknown
+        return super.indexOf(searchElement, fromIndex);
+    }
+    /**
+     * Same as `Array.lastIndexOf`, but accepts a search value outside of `T`
+     * instead of rejecting it at compile-time. See {@link FArray.indexOf}.
+     *
+     * @param searchElement The value to search for — no longer restricted to `T`.
+     * @param fromIndex The position in this array at which to start searching backwards. Defaults to the last index, like the native method.
+     * @returns The index of the last match, or -1 if not found.
+     */
+    lastIndexOf(searchElement, fromIndex) {
+        if (fromIndex === undefined) {
+            // @ts-expect-error searchElement is unknown
+            return super.lastIndexOf(searchElement);
+        }
+        // @ts-expect-error searchElement is unknown
+        return super.lastIndexOf(searchElement, fromIndex);
+    }
+    filter(predicate, thisArg) {
+        return super.filter(predicate, thisArg);
+    }
+    static from(iterable, mapfn, thisArg) {
+        return (mapfn ? super.from(iterable, mapfn, thisArg) : super.from(iterable));
+    }
+    /**
+     * Same as `Array.of`, but returns an `FArray`. See {@link FArray.from}.
+     *
+     * @example
+     * const fa = FArray.of(1, 2, 3); // FArray<number>, not number[]
+     */
+    static of(...items) {
+        return super.of(...items);
+    }
+    /**
+     * Converts this `FArray` back into a plain `Array` instance — the
+     * reverse of {@link FArray.from}/{@link FArray.of}. `FArray` is already
+     * assignable to `T[]` anywhere a plain array is expected (it extends
+     * `Array`), so this is mostly useful when the runtime type matters too
+     * (e.g. a library that special-cases `Array` and rejects subclasses).
+     *
+     * @example
+     * const fa = new FArray(1, 2, 3);
+     * const plain = fa.toArray(); // Array(3) [1, 2, 3], not instanceof FArray
+     */
+    toArray() {
+        return [...this];
+    }
 }

package/dist/classes/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./array.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/classes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/classes/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/classes/index.js

@@ -0,0 +1 @@
+export * from "./array.js";

package/dist/date/formatRelativeTime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Formats the difference between two dates as a human-readable relative
+ * string ("3 hours ago", "in 2 days"), backed by `Intl.RelativeTimeFormat`.
+ *
+ * @param date - The date to describe.
+ * @param baseDate - The reference date to compare against (defaults to now).
+ * @param locale - The locale to format with (defaults to `"en"`).
+ * @returns The formatted relative time.
+ * @example
+ * formatRelativeTime(new Date(Date.now() - 3_600_000)); // => "1 hour ago"
+ */
+export declare function formatRelativeTime(date: Date, baseDate?: Date, locale?: string): string;
+//# sourceMappingURL=formatRelativeTime.d.ts.map

package/dist/date/formatRelativeTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatRelativeTime.d.ts","sourceRoot":"","sources":["../../src/date/formatRelativeTime.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,QAAQ,GAAE,IAAiB,EAC3B,MAAM,SAAO,GACZ,MAAM,CAWR"}

package/dist/date/formatRelativeTime.js

@@ -0,0 +1,30 @@
+const UNITS = [
+    { unit: "year", ms: 365 * 24 * 60 * 60 * 1000 },
+    { unit: "month", ms: 30 * 24 * 60 * 60 * 1000 },
+    { unit: "week", ms: 7 * 24 * 60 * 60 * 1000 },
+    { unit: "day", ms: 24 * 60 * 60 * 1000 },
+    { unit: "hour", ms: 60 * 60 * 1000 },
+    { unit: "minute", ms: 60 * 1000 },
+    { unit: "second", ms: 1000 },
+];
+/**
+ * Formats the difference between two dates as a human-readable relative
+ * string ("3 hours ago", "in 2 days"), backed by `Intl.RelativeTimeFormat`.
+ *
+ * @param date - The date to describe.
+ * @param baseDate - The reference date to compare against (defaults to now).
+ * @param locale - The locale to format with (defaults to `"en"`).
+ * @returns The formatted relative time.
+ * @example
+ * formatRelativeTime(new Date(Date.now() - 3_600_000)); // => "1 hour ago"
+ */
+export function formatRelativeTime(date, baseDate = new Date(), locale = "en") {
+    const diffMs = date.getTime() - baseDate.getTime();
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+    for (const { unit, ms } of UNITS) {
+        if (Math.abs(diffMs) >= ms || unit === "second") {
+            return rtf.format(Math.round(diffMs / ms), unit);
+        }
+    }
+    return rtf.format(0, "second");
+}

package/dist/date/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./formatRelativeTime.js";
+export * from "./isSameDay.js";
+export * from "./startOfDay.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/date/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/date/index.js

@@ -0,0 +1,3 @@
+export * from "./formatRelativeTime.js";
+export * from "./isSameDay.js";
+export * from "./startOfDay.js";

package/dist/date/isSameDay.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Checks whether two dates fall on the same local calendar day.
+ *
+ * @param a - The first date.
+ * @param b - The second date.
+ * @returns `true` if both dates share the same year, month and day.
+ * @example
+ * isSameDay(new Date("2026-03-14T08:00"), new Date("2026-03-14T22:00")); // => true
+ */
+export declare function isSameDay(a: Date, b: Date): boolean;
+//# sourceMappingURL=isSameDay.d.ts.map

package/dist/date/isSameDay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isSameDay.d.ts","sourceRoot":"","sources":["../../src/date/isSameDay.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAMnD"}

package/dist/date/isSameDay.js

@@ -0,0 +1,14 @@
+/**
+ * Checks whether two dates fall on the same local calendar day.
+ *
+ * @param a - The first date.
+ * @param b - The second date.
+ * @returns `true` if both dates share the same year, month and day.
+ * @example
+ * isSameDay(new Date("2026-03-14T08:00"), new Date("2026-03-14T22:00")); // => true
+ */
+export function isSameDay(a, b) {
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate());
+}

package/dist/date/startOfDay.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns a new `Date` set to midnight (00:00:00.000) of the same local day.
+ *
+ * @param date - The reference date (defaults to now).
+ * @returns A new `Date` at the start of that day.
+ * @example
+ * startOfDay(new Date("2026-03-14T18:30:00")); // => 2026-03-14T00:00:00.000
+ */
+export declare function startOfDay(date?: Date): Date;
+//# sourceMappingURL=startOfDay.d.ts.map

package/dist/date/startOfDay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startOfDay.d.ts","sourceRoot":"","sources":["../../src/date/startOfDay.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,IAAiB,GAAG,IAAI,CAIxD"}

package/dist/date/startOfDay.js

@@ -0,0 +1,13 @@
+/**
+ * Returns a new `Date` set to midnight (00:00:00.000) of the same local day.
+ *
+ * @param date - The reference date (defaults to now).
+ * @returns A new `Date` at the start of that day.
+ * @example
+ * startOfDay(new Date("2026-03-14T18:30:00")); // => 2026-03-14T00:00:00.000
+ */
+export function startOfDay(date = new Date()) {
+    const result = new Date(date);
+    result.setHours(0, 0, 0, 0);
+    return result;
+}

package/dist/files/downloadText.d.ts

@@ -8,6 +8,7 @@ export declare function downloadText(filename: string, text: string): void;
  * Downloads a text blob as a file.
  * @param filename The filename to save to.
  * @param text The text to save.
+ * @param mimeType The MIME type of the blob (defaults to `"text/plain"`).
  */
-export declare function downloadTextBlob(filename: string, text: string): void;
+export declare function downloadTextBlob(filename: string, text: string, mimeType?: string): void;
 //# sourceMappingURL=downloadText.d.ts.map

package/dist/files/downloadText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"downloadText.d.ts","sourceRoot":"","sources":["../../src/files/downloadText.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAcjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAYrE"}
+{"version":3,"file":"downloadText.d.ts","sourceRoot":"","sources":["../../src/files/downloadText.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAcjE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,SAAe,GACtB,IAAI,CAcN"}

package/dist/files/downloadText.js

@@ -16,9 +16,10 @@ export function downloadText(filename, text) {
  * Downloads a text blob as a file.
  * @param filename The filename to save to.
  * @param text The text to save.
+ * @param mimeType The MIME type of the blob (defaults to `"text/plain"`).
  */
-export function downloadTextBlob(filename, text) {
-    const url = URL.createObjectURL(new Blob([text], { type: "text/plain" }));
+export function downloadTextBlob(filename, text, mimeType = "text/plain") {
+    const url = URL.createObjectURL(new Blob([text], { type: `${mimeType};charset=utf-8` }));
     const a = document.createElement("a");
     a.setAttribute("download", filename);
     a.setAttribute("href", url);

package/dist/files/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./downloadText.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/files/index.js

@@ -0,0 +1 @@
+export * from "./downloadText.js";

package/dist/id/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./randomId.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/id/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/id/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/id/index.js

@@ -0,0 +1 @@
+export * from "./randomId.js";

package/dist/id/randomId.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `crypto.randomUUID()` with a fallback. That API only exists in a secure
+ * context (HTTPS or `localhost`) and is missing on a few older browsers. The
+ * fallbacks are not cryptographically secure but are good enough for local
+ * identifiers.
+ *
+ * @returns {string} A UUID-v4-shaped string, or a timestamp-based id as a last resort.
+ */
+export declare function randomId(): string;
+//# sourceMappingURL=randomId.d.ts.map

package/dist/id/randomId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"randomId.d.ts","sourceRoot":"","sources":["../../src/id/randomId.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA6BjC"}

package/dist/id/randomId.js

@@ -0,0 +1,33 @@
+/**
+ * `crypto.randomUUID()` with a fallback. That API only exists in a secure
+ * context (HTTPS or `localhost`) and is missing on a few older browsers. The
+ * fallbacks are not cryptographically secure but are good enough for local
+ * identifiers.
+ *
+ * @returns {string} A UUID-v4-shaped string, or a timestamp-based id as a last resort.
+ */
+export function randomId() {
+    // `globalThis.crypto` is typed as always present by lib.dom, but it can be
+    // missing at runtime (older browser, insecure context) — cast it away so
+    // the checks below are not flagged as unnecessary.
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function") {
+        return c.randomUUID();
+    }
+    if (typeof c?.getRandomValues === "function") {
+        const bytes = c.getRandomValues(new Uint8Array(16));
+        bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40; // version 4
+        bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80; // variant
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0"));
+        return (hex.slice(0, 4).join("") +
+            "-" +
+            hex.slice(4, 6).join("") +
+            "-" +
+            hex.slice(6, 8).join("") +
+            "-" +
+            hex.slice(8, 10).join("") +
+            "-" +
+            hex.slice(10, 16).join(""));
+    }
+    return `id-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+}

package/dist/index.d.ts

@@ -1,2 +1,11 @@
-export {};
+export * from "./array/index.js";
+export * from "./async/index.js";
+export * from "./classes/index.js";
+export * from "./date/index.js";
+export * from "./files/index.js";
+export * from "./id/index.js";
+export * from "./maths/index.js";
+export * from "./number/index.js";
+export * from "./object/index.js";
+export * from "./string/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -1 +1,15 @@
-export {};
+// Barrel: re-exports every category so consumers can do a single
+//   import { chunk, pick, sleep, clamp } from "@forthtilliath/ts-kit";
+// instead of one import line per module. Subpath imports
+// (`@forthtilliath/ts-kit/array/chunk`) still work if you want to keep
+// bundles minimal, but this is the default, low-friction entry point.
+export * from "./array/index.js";
+export * from "./async/index.js";
+export * from "./classes/index.js";
+export * from "./date/index.js";
+export * from "./files/index.js";
+export * from "./id/index.js";
+export * from "./maths/index.js";
+export * from "./number/index.js";
+export * from "./object/index.js";
+export * from "./string/index.js";

package/dist/number/clamp.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param value - The value to clamp.
+ * @param min - The lower bound.
+ * @param max - The upper bound.
+ * @returns `value`, or the nearest bound if it falls outside `[min, max]`.
+ * @example
+ * clamp(15, 0, 10); // => 10
+ * clamp(-5, 0, 10); // => 0
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+//# sourceMappingURL=clamp.d.ts.map

package/dist/number/clamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp.d.ts","sourceRoot":"","sources":["../../src/number/clamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/number/clamp.js

@@ -0,0 +1,14 @@
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param value - The value to clamp.
+ * @param min - The lower bound.
+ * @param max - The upper bound.
+ * @returns `value`, or the nearest bound if it falls outside `[min, max]`.
+ * @example
+ * clamp(15, 0, 10); // => 10
+ * clamp(-5, 0, 10); // => 0
+ */
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}

package/dist/number/formatBytes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Formats a byte count as a human-readable string (`"1.5 MB"`).
+ *
+ * @param bytes - The number of bytes.
+ * @param decimals - The number of decimal places to keep (default: 2).
+ * @returns The formatted string.
+ * @example
+ * formatBytes(1536); // => "1.5 KB"
+ * formatBytes(0); // => "0 B"
+ */
+export declare function formatBytes(bytes: number, decimals?: number): string;
+//# sourceMappingURL=formatBytes.d.ts.map

package/dist/number/formatBytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatBytes.d.ts","sourceRoot":"","sources":["../../src/number/formatBytes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAW/D"}

package/dist/number/formatBytes.js

@@ -0,0 +1,19 @@
+const UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
+/**
+ * Formats a byte count as a human-readable string (`"1.5 MB"`).
+ *
+ * @param bytes - The number of bytes.
+ * @param decimals - The number of decimal places to keep (default: 2).
+ * @returns The formatted string.
+ * @example
+ * formatBytes(1536); // => "1.5 KB"
+ * formatBytes(0); // => "0 B"
+ */
+export function formatBytes(bytes, decimals = 2) {
+    if (bytes === 0)
+        return "0 B";
+    const exponent = Math.min(Math.floor(Math.log(Math.abs(bytes)) / Math.log(1024)), UNITS.length - 1);
+    const value = bytes / 1024 ** exponent;
+    const formatted = value.toFixed(Math.max(decimals, 0)).replace(/\.?0+$/, "");
+    return `${formatted} ${UNITS[exponent]}`;
+}

package/dist/number/formatDuration.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Formats a duration in milliseconds as a human-readable string
+ * (`"1d 1h 1m 1s"`, `"500ms"`).
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns The formatted string.
+ * @example
+ * formatDuration(90_061_000); // => "1d 1h 1m 1s"
+ * formatDuration(500); // => "500ms"
+ */
+export declare function formatDuration(ms: number): string;
+//# sourceMappingURL=formatDuration.d.ts.map

package/dist/number/formatDuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatDuration.d.ts","sourceRoot":"","sources":["../../src/number/formatDuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAgBjD"}

package/dist/number/formatDuration.js

@@ -0,0 +1,29 @@
+/**
+ * Formats a duration in milliseconds as a human-readable string
+ * (`"1d 1h 1m 1s"`, `"500ms"`).
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns The formatted string.
+ * @example
+ * formatDuration(90_061_000); // => "1d 1h 1m 1s"
+ * formatDuration(500); // => "500ms"
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const totalSeconds = Math.floor(ms / 1000);
+    const days = Math.floor(totalSeconds / 86400);
+    const hours = Math.floor((totalSeconds % 86400) / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (seconds > 0 || parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(" ");
+}

package/dist/number/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./clamp.js";
+export * from "./formatBytes.js";
+export * from "./formatDuration.js";
+export * from "./round.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/number/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/number/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}

package/dist/number/index.js

@@ -0,0 +1,4 @@
+export * from "./clamp.js";
+export * from "./formatBytes.js";
+export * from "./formatDuration.js";
+export * from "./round.js";

package/dist/number/round.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rounds a number to a given number of decimal places.
+ *
+ * @param value - The number to round.
+ * @param decimals - The number of decimal places (default: 0).
+ * @returns The rounded number.
+ * @example
+ * round(1.2345, 2); // => 1.23
+ * round(1.005, 2); // => 1.01
+ */
+export declare function round(value: number, decimals?: number): number;
+//# sourceMappingURL=round.d.ts.map

package/dist/number/round.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round.d.ts","sourceRoot":"","sources":["../../src/number/round.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAGzD"}

package/dist/number/round.js

@@ -0,0 +1,14 @@
+/**
+ * Rounds a number to a given number of decimal places.
+ *
+ * @param value - The number to round.
+ * @param decimals - The number of decimal places (default: 0).
+ * @returns The rounded number.
+ * @example
+ * round(1.2345, 2); // => 1.23
+ * round(1.005, 2); // => 1.01
+ */
+export function round(value, decimals = 0) {
+    const factor = 10 ** decimals;
+    return Math.round((value + Number.EPSILON) * factor) / factor;
+}

package/dist/object/deepClone.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deep clones a value.
+ *
+ * Uses the native `structuredClone` when available (handles `Date`, `Map`,
+ * `Set`, circular references, etc.), and falls back to a JSON round-trip
+ * otherwise — which loses `undefined` values, functions, and non-JSON types.
+ *
+ * @param value - The value to clone.
+ * @returns A deep copy of `value`.
+ */
+export declare function deepClone<T>(value: T): T;
+//# sourceMappingURL=deepClone.d.ts.map

package/dist/object/deepClone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepClone.d.ts","sourceRoot":"","sources":["../../src/object/deepClone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAKxC"}

package/dist/object/deepClone.js

@@ -0,0 +1,16 @@
+/**
+ * Deep clones a value.
+ *
+ * Uses the native `structuredClone` when available (handles `Date`, `Map`,
+ * `Set`, circular references, etc.), and falls back to a JSON round-trip
+ * otherwise — which loses `undefined` values, functions, and non-JSON types.
+ *
+ * @param value - The value to clone.
+ * @returns A deep copy of `value`.
+ */
+export function deepClone(value) {
+    if (typeof structuredClone === "function") {
+        return structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/object/deepEqual.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Recursively compares two values for structural equality.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @returns `true` if `a` and `b` are deeply equal.
+ * @example
+ * deepEqual({ a: [1, 2] }, { a: [1, 2] }); // => true
+ * deepEqual({ a: 1 }, { a: 2 }); // => false
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=deepEqual.d.ts.map

package/dist/object/deepEqual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepEqual.d.ts","sourceRoot":"","sources":["../../src/object/deepEqual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAwBzD"}

package/dist/object/deepEqual.js

@@ -0,0 +1,31 @@
+/**
+ * Recursively compares two values for structural equality.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @returns `true` if `a` and `b` are deeply equal.
+ * @example
+ * deepEqual({ a: [1, 2] }, { a: [1, 2] }); // => true
+ * deepEqual({ a: 1 }, { a: 2 }); // => false
+ */
+export function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}

package/dist/object/groupBy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Groups the elements of an array by a key derived from each element.
+ *
+ * @param array - The array to group.
+ * @param getKey - Computes the group key for an element.
+ * @returns A record mapping each key to the array of matching elements.
+ * @example
+ * groupBy([1, 2, 3, 4], (n) => (n % 2 === 0 ? "even" : "odd"));
+ * // => { odd: [1, 3], even: [2, 4] }
+ */
+export declare function groupBy<T, K extends PropertyKey>(array: readonly T[], getKey: (item: T) => K): Record<K, T[]>;
+//# sourceMappingURL=groupBy.d.ts.map

package/dist/object/groupBy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupBy.d.ts","sourceRoot":"","sources":["../../src/object/groupBy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,EAC9C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GACrB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAOhB"}