@forthtilliath/ts-kit 0.2.0 → 0.4.0

package/dist/async/withTimeout.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown by {@link withTimeout} when the wrapped promise does not settle in
+ * time.
+ */
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Rejects with a {@link TimeoutError} if `promise` has not settled within
+ * `ms` milliseconds.
+ *
+ * @param promise - The promise to race against the timeout.
+ * @param ms - The timeout in milliseconds.
+ * @param message - Optional error message (defaults to a generic one).
+ * @example
+ * await withTimeout(fetch("/api"), 5000);
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+//# sourceMappingURL=withTimeout.d.ts.map

package/dist/async/withTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTimeout.d.ts","sourceRoot":"","sources":["../../src/async/withTimeout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,SAAwB;CAI5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/async/withTimeout.js

@@ -0,0 +1,34 @@
+/**
+ * Thrown by {@link withTimeout} when the wrapped promise does not settle in
+ * time.
+ */
+export class TimeoutError extends Error {
+    constructor(message = "Operation timed out") {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Rejects with a {@link TimeoutError} if `promise` has not settled within
+ * `ms` milliseconds.
+ *
+ * @param promise - The promise to race against the timeout.
+ * @param ms - The timeout in milliseconds.
+ * @param message - Optional error message (defaults to a generic one).
+ * @example
+ * await withTimeout(fetch("/api"), 5000);
+ */
+export function withTimeout(promise, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new TimeoutError(message));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}

package/dist/classes/array.d.ts

@@ -49,5 +49,93 @@ export declare class FArray<T> extends Array<T> {
      * }
      */
     includes<S>(searchElement: S | T, fromIndex?: number): searchElement is S & T;
+    /**
+     * 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: unknown, fromIndex?: number): number;
+    /**
+     * 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: unknown, fromIndex?: number): number;
+    /**
+     * Same as `Array.filter`, but recognizes the `Boolean` global constructor
+     * as a type guard — the native typings don't, so `arr.filter(Boolean)`
+     * keeps `null`/`undefined` in the result's element type even though
+     * they're removed at runtime.
+     *
+     * Note: like the native runtime behavior, this also drops other falsy
+     * values (`0`, `""`, `NaN`, `false`) — but the type only reflects the
+     * removal of `null`/`undefined`, since narrowing those further would
+     * require them to be literal members of `T`.
+     *
+     * @example
+     * // Normal operation of Array.filter
+     * const arr: (number | null | undefined)[] = [1, null, 2, undefined];
+     * const result = arr.filter(Boolean); // still (number | null | undefined)[]
+     *
+     * @example
+     * // FArray.filter
+     * const arr = new FArray<number | null | undefined>(1, null, 2, undefined);
+     * const result = arr.filter(Boolean); // FArray<number>
+     */
+    filter(predicate: BooleanConstructor): FArray<NonNullable<T>>;
+    filter<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: unknown): FArray<S>;
+    filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: unknown): FArray<T>;
+    /**
+     * Same as `Array.from`, but returns an `FArray` — the native typings
+     * return a plain `T[]`/`U[]` even though `Array.from` (and `Array.of`
+     * below) already construct an instance of the calling class at runtime.
+     *
+     * @example
+     * const fromPlain = FArray.from([1, 2, 3]); // FArray<number>, not number[]
+     */
+    static from<T>(iterable: Iterable<T> | ArrayLike<T>): FArray<T>;
+    static from<T, U>(iterable: Iterable<T> | ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: unknown): FArray<U>;
+    /**
+     * 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<T>(...items: T[]): FArray<T>;
+    /**
+     * 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(): T[];
 }
 //# sourceMappingURL=array.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/classes/array.ts"],"names":[],"mappings":"AAAA,qBAAa,MAAM,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,QAAQ,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,EAAE,SAAS,SAAI,GAAG,aAAa,IAAI,CAAC,GAAG,CAAC;CAIzE"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/classes/array.ts"],"names":[],"mappings":"AAAA,qBAAa,MAAM,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,QAAQ,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,EAAE,SAAS,SAAI,GAAG,aAAa,IAAI,CAAC,GAAG,CAAC;IAKxE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,SAAS,SAAI,GAAG,MAAM;IAKtD;;;;;;;OAOG;IACH,WAAW,CAAC,aAAa,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAS/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAC,CAAC,SAAS,CAAC,EAChB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC,EAC9D,OAAO,CAAC,EAAE,OAAO,GAChB,MAAM,CAAC,CAAC,CAAC;IACZ,MAAM,CACJ,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,EAC3D,OAAO,CAAC,EAAE,OAAO,GAChB,MAAM,CAAC,CAAC,CAAC;IAQZ;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAC/D,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EACd,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,EAC7B,OAAO,CAAC,EAAE,OAAO,GAChB,MAAM,CAAC,CAAC,CAAC;IAWZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;IAItC;;;;;;;;;;OAUG;IACH,OAAO,IAAI,CAAC,EAAE;CAGf"}

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/getPeriodStartMs.d.ts

@@ -0,0 +1,16 @@
+export type PeriodFilter = "all" | "today" | "7d" | "30d";
+/**
+ * Returns the timestamp (ms) from which a record is included for a given
+ * period filter, or `null` for `"all"` (no date filter). `"today"` starts at
+ * the current calendar day, not a rolling 24h window.
+ *
+ * @param period - The period filter.
+ * @param now - The reference date. Defaults to `new Date()`.
+ * @returns The period's start timestamp in ms, or `null` for `"all"`.
+ * @example
+ * getPeriodStartMs("today"); // => start of today, local time, in ms
+ * getPeriodStartMs("7d"); // => now minus 7 days, in ms
+ * getPeriodStartMs("all"); // => null
+ */
+export declare function getPeriodStartMs(period: PeriodFilter, now?: Date): number | null;
+//# sourceMappingURL=getPeriodStartMs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getPeriodStartMs.d.ts","sourceRoot":"","sources":["../../src/date/getPeriodStartMs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,GAAG,OAAa,GACf,MAAM,GAAG,IAAI,CASf"}

package/dist/date/getPeriodStartMs.js

@@ -0,0 +1,24 @@
+/**
+ * Returns the timestamp (ms) from which a record is included for a given
+ * period filter, or `null` for `"all"` (no date filter). `"today"` starts at
+ * the current calendar day, not a rolling 24h window.
+ *
+ * @param period - The period filter.
+ * @param now - The reference date. Defaults to `new Date()`.
+ * @returns The period's start timestamp in ms, or `null` for `"all"`.
+ * @example
+ * getPeriodStartMs("today"); // => start of today, local time, in ms
+ * getPeriodStartMs("7d"); // => now minus 7 days, in ms
+ * getPeriodStartMs("all"); // => null
+ */
+export function getPeriodStartMs(period, now = new Date()) {
+    if (period === "all")
+        return null;
+    if (period === "today") {
+        const startOfDay = new Date(now);
+        startOfDay.setHours(0, 0, 0, 0);
+        return startOfDay.getTime();
+    }
+    const days = period === "7d" ? 7 : 30;
+    return now.getTime() - days * 24 * 60 * 60 * 1000;
+}

package/dist/date/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./formatRelativeTime.js";
+export * from "./getPeriodStartMs.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,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/date/index.js

@@ -0,0 +1,4 @@
+export * from "./formatRelativeTime.js";
+export * from "./getPeriodStartMs.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/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/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/formatCsvNumber.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats a number as a raw value (no unit suffix) for use in a spreadsheet
+ * (sum, average...), with a comma decimal separator as expected by
+ * French-locale spreadsheets instead of JS's dot.
+ *
+ * @param value - The number to format.
+ * @param decimals - Number of decimal places. Defaults to `1`.
+ * @returns The formatted number, comma as decimal separator.
+ * @example
+ * formatCsvNumber(1.5); // => "1,5"
+ * formatCsvNumber(12.345, 2); // => "12,35"
+ */
+export declare function formatCsvNumber(value: number, decimals?: number): string;
+//# sourceMappingURL=formatCsvNumber.d.ts.map

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

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

package/dist/number/formatCsvNumber.js

@@ -0,0 +1,15 @@
+/**
+ * Formats a number as a raw value (no unit suffix) for use in a spreadsheet
+ * (sum, average...), with a comma decimal separator as expected by
+ * French-locale spreadsheets instead of JS's dot.
+ *
+ * @param value - The number to format.
+ * @param decimals - Number of decimal places. Defaults to `1`.
+ * @returns The formatted number, comma as decimal separator.
+ * @example
+ * formatCsvNumber(1.5); // => "1,5"
+ * formatCsvNumber(12.345, 2); // => "12,35"
+ */
+export function formatCsvNumber(value, decimals = 1) {
+    return value.toFixed(decimals).replace(".", ",");
+}

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,6 @@
+export * from "./clamp.js";
+export * from "./formatBytes.js";
+export * from "./formatCsvNumber.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,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}