@forthtilliath/ts-kit 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,8 @@
 # @forthtilliath/ts-kit
 
-Framework-agnostic TypeScript utility functions — arrays, maths, browser file
-downloads, and a couple of `Array` extensions with better type-narrowing.
-
-> **Status**: not currently consumed by any other package in this monorepo.
-> Built, linted, tested and type-checked like everything else, but nothing
-> imports it yet.
+Framework-agnostic TypeScript utility functions — arrays, objects, strings,
+async control-flow, dates, numbers, browser file downloads, and a couple of
+`Array` extensions with better type-narrowing.
 
 ## Install
 
@@ -21,19 +18,19 @@ Within the workspace:
 
 ## Usage
 
-Each module is exported individually — import the file you need directly
-rather than a single barrel:
+Import everything you need from the package root — a single barrel re-exports
+every category, so there's no need to remember (or type out) one import line
+per module:
+
+```ts
+import { chunk, clamp, debounce, pick, slugify } from "@forthtilliath/ts-kit";
+```
+
+Subpath imports still work if you'd rather import one module at a time (e.g.
+to keep a bundle's included code obvious at a glance):
 
 ```ts
 import { chunk } from "@forthtilliath/ts-kit/array/chunk";
-import { flattenDeep } from "@forthtilliath/ts-kit/array/flattenDeep";
-import { FArray } from "@forthtilliath/ts-kit/classes/array";
-import {
-  downloadText,
-  downloadTextBlob,
-} from "@forthtilliath/ts-kit/files/downloadText";
-import { avg } from "@forthtilliath/ts-kit/maths/average";
-import { sum } from "@forthtilliath/ts-kit/maths/sum";
 ```
 
 ### `array`
@@ -41,11 +38,46 @@ import { sum } from "@forthtilliath/ts-kit/maths/sum";
 - `chunk(array, size)` — splits an array into chunks of a given size.
 - `flattenDeep(array)` — recursively flattens nested arrays.
 
+### `async`
+
+- `sleep(ms)` — resolves after a delay.
+- `retry(fn, options)` — retries an async operation with exponential backoff.
+- `debounce(fn, wait)` — delays `fn` until calls stop for `wait` ms; exposes
+  `cancel()` / `flush()`.
+- `throttle(fn, wait)` — runs `fn` at most once per `wait` ms (leading +
+  trailing edge); exposes `cancel()`.
+- `memoize(fn, getKey?)` — caches `fn`'s results per argument tuple; exposes
+  the underlying `cache` map.
+- `withTimeout(promise, ms, message?)` — rejects with a `TimeoutError` if
+  `promise` doesn't settle in time.
+
 ### `classes`
 
-- `FArray` — an `Array` subclass whose `includes()` narrows the type of the
-  searched value when it's found (unlike the native `Array.prototype.includes`,
-  which only narrows the _array's_ element type).
+- `FArray` — an `Array` subclass that fixes a handful of spots where the
+  native `Array` typings are wrong or overly restrictive:
+  - `includes()` narrows the type of the searched value when it's found
+    (the native `Array.prototype.includes` only narrows the _array's_
+    element type).
+  - `indexOf()` / `lastIndexOf()` accept a search value outside of the
+    array's element type instead of rejecting it at compile-time (same
+    root cause as `includes`, fixed the same way).
+  - `filter(Boolean)` strips `null`/`undefined` from the result's type
+    (the native typings don't recognize `Boolean` as a type guard, so the
+    result keeps the nullish types even though they're removed at runtime).
+  - `FArray.from(...)` / `FArray.of(...)` are typed to return an `FArray`
+    instead of a plain array (the native static typings return a plain
+    array even though these methods already construct an instance of the
+    calling class at runtime).
+  - `toArray()` converts an `FArray` back into a plain `Array` instance —
+    rarely needed since `FArray` is already assignable to `T[]` anywhere a
+    plain array is expected, but useful when the runtime type matters too.
+
+### `date`
+
+- `startOfDay(date?)` — returns a new `Date` at local midnight.
+- `isSameDay(a, b)` — checks whether two dates fall on the same local day.
+- `formatRelativeTime(date, baseDate?, locale?)` — human-readable relative
+  time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`.
 
 ### `files`
 
@@ -54,11 +86,43 @@ import { sum } from "@forthtilliath/ts-kit/maths/sum";
 - `downloadTextBlob(filename, text)` — same, but via a `Blob` + object URL
   (better for larger content).
 
+### `id`
+
+- `randomId()` — `crypto.randomUUID()` with fallbacks for older/insecure
+  contexts.
+
 ### `maths`
 
 - `sum(numbers)` — sum of an array of numbers.
 - `avg(numbers)` — average of an array of numbers.
 
+### `number`
+
+- `clamp(value, min, max)` — clamps a number between two bounds.
+- `round(value, decimals?)` — rounds to a given number of decimal places.
+- `formatBytes(bytes, decimals?)` — human-readable byte size ("1.5 MB").
+- `formatDuration(ms)` — human-readable duration ("1d 1h 1m 1s").
+
+### `object`
+
+- `pick(obj, keys)` / `omit(obj, keys)` — keep or drop a set of keys.
+- `groupBy(array, getKey)` — groups elements by a computed key.
+- `uniqueBy(array, getKey)` — deduplicates elements by a computed key.
+- `deepClone(value)` — deep clone (via `structuredClone`, with a JSON
+  fallback).
+- `deepEqual(a, b)` — recursive structural equality check.
+- `mapValues(obj, fn)` — maps every value of an object through `fn`.
+
+### `string`
+
+- `capitalize(str)` — uppercases the first letter, lowercases the rest.
+- `truncate(str, maxLength, suffix?)` — truncates with an ellipsis (or custom
+  suffix).
+- `slugify(str)` — URL-friendly slug (accents stripped, lower-cased,
+  hyphenated).
+- `pluralize(count, singular, plural?)` — naive English pluralization, with an
+  override for irregular words.
+
 ## Scripts
 
 ```bash

package/dist/async/debounce.d.ts

@@ -0,0 +1,20 @@
+export interface DebouncedFunction<Args extends unknown[]> {
+    (...args: Args): void;
+    /** Cancels a pending invocation, if any. */
+    cancel: () => void;
+    /** Immediately invokes a pending call, if any. */
+    flush: () => void;
+}
+/**
+ * Returns a debounced version of `fn` that only runs after `wait`
+ * milliseconds have elapsed without another call.
+ *
+ * @param fn - The function to debounce.
+ * @param wait - The delay in milliseconds.
+ * @returns The debounced function, with `cancel()` and `flush()` helpers.
+ * @example
+ * const onResize = debounce(() => recompute(), 200);
+ * window.addEventListener("resize", onResize);
+ */
+export declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, wait: number): DebouncedFunction<Args>;
+//# sourceMappingURL=debounce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/async/debounce.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,OAAO,EAAE;IACvD,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,IAAI,SAAS,OAAO,EAAE,EAC7C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,IAAI,EAAE,MAAM,GACX,iBAAiB,CAAC,IAAI,CAAC,CA+BzB"}

package/dist/async/debounce.js

@@ -0,0 +1,44 @@
+/**
+ * Returns a debounced version of `fn` that only runs after `wait`
+ * milliseconds have elapsed without another call.
+ *
+ * @param fn - The function to debounce.
+ * @param wait - The delay in milliseconds.
+ * @returns The debounced function, with `cancel()` and `flush()` helpers.
+ * @example
+ * const onResize = debounce(() => recompute(), 200);
+ * window.addEventListener("resize", onResize);
+ */
+export function debounce(fn, wait) {
+    let timer;
+    let pendingArgs;
+    const debounced = ((...args) => {
+        pendingArgs = args;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            const callArgs = pendingArgs;
+            pendingArgs = undefined;
+            if (callArgs)
+                fn(...callArgs);
+        }, wait);
+    });
+    debounced.cancel = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        pendingArgs = undefined;
+    };
+    debounced.flush = () => {
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        timer = undefined;
+        const callArgs = pendingArgs;
+        pendingArgs = undefined;
+        if (callArgs)
+            fn(...callArgs);
+    };
+    return debounced;
+}

package/dist/async/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./debounce.js";
+export * from "./memoize.js";
+export * from "./retry.js";
+export * from "./sleep.js";
+export * from "./throttle.js";
+export * from "./withTimeout.js";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/async/index.js

@@ -0,0 +1,6 @@
+export * from "./debounce.js";
+export * from "./memoize.js";
+export * from "./retry.js";
+export * from "./sleep.js";
+export * from "./throttle.js";
+export * from "./withTimeout.js";

package/dist/async/memoize.d.ts

@@ -0,0 +1,19 @@
+export interface MemoizedFunction<Args extends unknown[], R> {
+    (...args: Args): R;
+    /** The underlying cache, exposed for inspection or manual clearing. */
+    cache: Map<string, R>;
+}
+/**
+ * Caches the result of `fn` per argument tuple (JSON-stringified by
+ * default).
+ *
+ * @param fn - The function to memoize.
+ * @param getKey - Computes the cache key for a set of arguments (defaults to `JSON.stringify`).
+ * @returns A memoized version of `fn`, with a `cache` map exposed.
+ * @example
+ * const square = memoize((n: number) => expensiveSquare(n));
+ * square(4); // computed
+ * square(4); // cached
+ */
+export declare function memoize<Args extends unknown[], R>(fn: (...args: Args) => R, getKey?: (...args: Args) => string): MemoizedFunction<Args, R>;
+//# sourceMappingURL=memoize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/async/memoize.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC;IACzD,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC;IACnB,uEAAuE;IACvE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EAC/C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,EACxB,MAAM,GAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAA0C,GACpE,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,CAa3B"}

package/dist/async/memoize.js

@@ -0,0 +1,25 @@
+/**
+ * Caches the result of `fn` per argument tuple (JSON-stringified by
+ * default).
+ *
+ * @param fn - The function to memoize.
+ * @param getKey - Computes the cache key for a set of arguments (defaults to `JSON.stringify`).
+ * @returns A memoized version of `fn`, with a `cache` map exposed.
+ * @example
+ * const square = memoize((n: number) => expensiveSquare(n));
+ * square(4); // computed
+ * square(4); // cached
+ */
+export function memoize(fn, getKey = (...args) => JSON.stringify(args)) {
+    const cache = new Map();
+    const memoized = ((...args) => {
+        const key = getKey(...args);
+        if (cache.has(key))
+            return cache.get(key);
+        const result = fn(...args);
+        cache.set(key, result);
+        return result;
+    });
+    memoized.cache = cache;
+    return memoized;
+}

package/dist/async/retry.d.ts

@@ -0,0 +1,25 @@
+export interface RetryOptions {
+    /** Maximum number of attempts, including the first one (default: 3). */
+    attempts?: number;
+    /** Base delay in milliseconds before retrying (default: 200). */
+    delayMs?: number;
+    /** Backoff multiplier applied to `delayMs` after each failed attempt (default: 2). */
+    backoffFactor?: number;
+    /** Called with the error and the 1-based attempt number after each failure. */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/**
+ * Retries an async operation with exponential backoff.
+ *
+ * @param fn - The operation to retry. Receives the 1-based attempt number.
+ * @param options - Retry configuration.
+ * @returns The result of the first successful attempt.
+ * @throws The last error, if every attempt failed.
+ * @example
+ * const data = await retry(() => fetch("/api").then((r) => r.json()), {
+ *   attempts: 5,
+ *   delayMs: 300,
+ * });
+ */
+export declare function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/async/retry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAoBZ"}

package/dist/async/retry.js

@@ -0,0 +1,33 @@
+import { sleep } from "./sleep.js";
+/**
+ * Retries an async operation with exponential backoff.
+ *
+ * @param fn - The operation to retry. Receives the 1-based attempt number.
+ * @param options - Retry configuration.
+ * @returns The result of the first successful attempt.
+ * @throws The last error, if every attempt failed.
+ * @example
+ * const data = await retry(() => fetch("/api").then((r) => r.json()), {
+ *   attempts: 5,
+ *   delayMs: 300,
+ * });
+ */
+export async function retry(fn, options = {}) {
+    const { attempts = 3, delayMs = 200, backoffFactor = 2, onRetry } = options;
+    let lastError;
+    let currentDelay = delayMs;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (error) {
+            lastError = error;
+            onRetry?.(error, attempt);
+            if (attempt < attempts) {
+                await sleep(currentDelay);
+                currentDelay *= backoffFactor;
+            }
+        }
+    }
+    throw lastError;
+}

package/dist/async/sleep.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves after the given number of milliseconds.
+ *
+ * @param ms - The delay in milliseconds.
+ * @example
+ * await sleep(1000); // waits 1 second
+ */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/async/sleep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/async/sleep.js

@@ -0,0 +1,10 @@
+/**
+ * Resolves after the given number of milliseconds.
+ *
+ * @param ms - The delay in milliseconds.
+ * @example
+ * await sleep(1000); // waits 1 second
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/async/throttle.d.ts

@@ -0,0 +1,20 @@
+export interface ThrottledFunction<Args extends unknown[]> {
+    (...args: Args): void;
+    /** Cancels any pending trailing invocation. */
+    cancel: () => void;
+}
+/**
+ * Returns a throttled version of `fn` that runs at most once every `wait`
+ * milliseconds: immediately on the first call (leading edge), then once more
+ * at the end of the window if further calls came in during it (trailing
+ * edge).
+ *
+ * @param fn - The function to throttle.
+ * @param wait - The minimum delay in milliseconds between calls.
+ * @returns The throttled function, with a `cancel()` helper.
+ * @example
+ * const onScroll = throttle(() => updatePosition(), 100);
+ * window.addEventListener("scroll", onScroll);
+ */
+export declare function throttle<Args extends unknown[]>(fn: (...args: Args) => void, wait: number): ThrottledFunction<Args>;
+//# sourceMappingURL=throttle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../src/async/throttle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,OAAO,EAAE;IACvD,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,SAAS,OAAO,EAAE,EAC7C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,IAAI,EAAE,MAAM,GACX,iBAAiB,CAAC,IAAI,CAAC,CAkCzB"}

package/dist/async/throttle.js

@@ -0,0 +1,43 @@
+/**
+ * Returns a throttled version of `fn` that runs at most once every `wait`
+ * milliseconds: immediately on the first call (leading edge), then once more
+ * at the end of the window if further calls came in during it (trailing
+ * edge).
+ *
+ * @param fn - The function to throttle.
+ * @param wait - The minimum delay in milliseconds between calls.
+ * @returns The throttled function, with a `cancel()` helper.
+ * @example
+ * const onScroll = throttle(() => updatePosition(), 100);
+ * window.addEventListener("scroll", onScroll);
+ */
+export function throttle(fn, wait) {
+    let lastCallTime;
+    let timer;
+    let pendingArgs;
+    const throttled = ((...args) => {
+        const now = Date.now();
+        if (lastCallTime === undefined || now - lastCallTime >= wait) {
+            lastCallTime = now;
+            fn(...args);
+            return;
+        }
+        pendingArgs = args;
+        timer ??= setTimeout(() => {
+            lastCallTime = Date.now();
+            timer = undefined;
+            const callArgs = pendingArgs;
+            pendingArgs = undefined;
+            if (callArgs)
+                fn(...callArgs);
+        }, wait - (now - lastCallTime));
+    });
+    throttled.cancel = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        pendingArgs = undefined;
+        lastCallTime = undefined;
+    };
+    return throttled;
+}

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"}