@forthtilliath/ts-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forthtilliath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @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.
+
+## Install
+
+Within the workspace:
+
+```json
+{
+  "dependencies": {
+    "@forthtilliath/ts-kit": "workspace:*"
+  }
+}
+```
+
+## Usage
+
+Each module is exported individually — import the file you need directly
+rather than a single barrel:
+
+```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`
+
+- `chunk(array, size)` — splits an array into chunks of a given size.
+- `flattenDeep(array)` — recursively flattens nested arrays.
+
+### `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).
+
+### `files`
+
+- `downloadText(filename, text)` — triggers a browser download of a text file
+  via a `data:` URI.
+- `downloadTextBlob(filename, text)` — same, but via a `Blob` + object URL
+  (better for larger content).
+
+### `maths`
+
+- `sum(numbers)` — sum of an array of numbers.
+- `avg(numbers)` — average of an array of numbers.
+
+## Scripts
+
+```bash
+pnpm run build          # tsc -> dist/ (excludes *.test.ts)
+pnpm run dev             # tsc --watch, same exclusion
+pnpm run check-types     # tsc --noEmit, includes test files
+pnpm run lint            # eslint
+pnpm run test            # vitest run
+```
+
+Type-checking and building use different `tsconfig`s on purpose:
+`tsconfig.json` includes `*.test.ts` (so lint/check-types see them),
+`tsconfig.build.json` excludes them (so they never end up in `dist/`).

package/dist/array/chunk.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Splits an array into chunks of a specified size.
+ *
+ * @param array - The array to chunk.
+ * @param size - The size of each chunk.
+ * @returns An array of arrays containing the chunked elements.
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
+ * chunk([1, 2, 3, 4, 5], 3); // => [[1, 2, 3], [4, 5]]
+ * chunk([1, 2, 3, 4, 5], 6); // => [[1, 2, 3, 4, 5]]
+ * chunk([1, 2, 3, 4, 5], 0); // => []
+ */
+export declare function chunk<T>(array: T[], size: number): T[][];
+//# sourceMappingURL=chunk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/array/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAOxD"}

package/dist/array/chunk.js

@@ -0,0 +1,21 @@
+/**
+ * Splits an array into chunks of a specified size.
+ *
+ * @param array - The array to chunk.
+ * @param size - The size of each chunk.
+ * @returns An array of arrays containing the chunked elements.
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
+ * chunk([1, 2, 3, 4, 5], 3); // => [[1, 2, 3], [4, 5]]
+ * chunk([1, 2, 3, 4, 5], 6); // => [[1, 2, 3, 4, 5]]
+ * chunk([1, 2, 3, 4, 5], 0); // => []
+ */
+export function chunk(array, size) {
+    if (size <= 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}

package/dist/array/flattenDeep.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Recursively flattens a nested array.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} array - The array to flatten.
+ * @return {T[]} The flattened array.
+ */
+export declare function flattenDeep<T>(array: T[]): T[];
+//# sourceMappingURL=flattenDeep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flattenDeep.d.ts","sourceRoot":"","sources":["../../src/array/flattenDeep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAM9C"}

package/dist/array/flattenDeep.js

@@ -0,0 +1,10 @@
+/**
+ * Recursively flattens a nested array.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} array - The array to flatten.
+ * @return {T[]} The flattened array.
+ */
+export function flattenDeep(array) {
+    return array.reduce((acc, val) => Array.isArray(val) ? acc.concat(flattenDeep(val)) : acc.concat(val), []);
+}

package/dist/array/index.d.ts

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

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

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

package/dist/array/index.js

@@ -0,0 +1,2 @@
+export * from "./chunk.js";
+export * from "./flattenDeep.js";

package/dist/classes/array.d.ts

@@ -0,0 +1,53 @@
+export declare class FArray<T> extends Array<T> {
+    /**
+     * Similar to `Array.includes`, but narrows the type of `searchElement` to `Include & T` if it is included in the array.
+     *
+     * @param searchElement The value to search for.
+     * @param fromIndex The position in this array at which to begin searching for searchElement.
+     * @returns true if the value is found, otherwise false.
+     *
+     * @example
+     * // Normal operation of Array.includes
+     * const bar = "bar";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr: FBB[] = ["foo", "bar", "baz"];
+     * if (arr.includes(bar)) {
+     * 	// bar is typed as "bar"
+     * } else {
+     * 	// bar is typed as "bar"
+     * }
+     *
+     * @example
+     * // FArray.includes
+     * const bar = "bar";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr = new FArray<FBB>("foo", "bar", "baz");
+     * if (arr.includes(bar)) {
+     * 	// bar is typed as "bar"
+     * } else {
+     * 	// bar is typed as never
+     * }
+     *
+     * @example
+     * // Normal operation of Array.includes
+     * const buz = "buz";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr: FBB[] = ["foo", "bar", "baz"];
+     * if (arr.includes(buz)) {}
+     * // ---------------^
+     * // The argument of type 'buz' is not assignable to the parameter of type 'FBB'.
+     *
+     * @example
+     * // FArray.includes
+     * const buz = "buz";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr = new FArray<FBB>("foo", "bar", "baz");
+     * if (arr.includes(buz)) {
+     * 	// bar is typed as never
+     * } else {
+     * 	// bar is typed as "buz"
+     * }
+     */
+    includes<S>(searchElement: S | T, fromIndex?: number): searchElement is S & T;
+}
+//# sourceMappingURL=array.d.ts.map

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

@@ -0,0 +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"}

package/dist/classes/array.js

@@ -0,0 +1,55 @@
+export class FArray extends Array {
+    /**
+     * Similar to `Array.includes`, but narrows the type of `searchElement` to `Include & T` if it is included in the array.
+     *
+     * @param searchElement The value to search for.
+     * @param fromIndex The position in this array at which to begin searching for searchElement.
+     * @returns true if the value is found, otherwise false.
+     *
+     * @example
+     * // Normal operation of Array.includes
+     * const bar = "bar";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr: FBB[] = ["foo", "bar", "baz"];
+     * if (arr.includes(bar)) {
+     * 	// bar is typed as "bar"
+     * } else {
+     * 	// bar is typed as "bar"
+     * }
+     *
+     * @example
+     * // FArray.includes
+     * const bar = "bar";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr = new FArray<FBB>("foo", "bar", "baz");
+     * if (arr.includes(bar)) {
+     * 	// bar is typed as "bar"
+     * } else {
+     * 	// bar is typed as never
+     * }
+     *
+     * @example
+     * // Normal operation of Array.includes
+     * const buz = "buz";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr: FBB[] = ["foo", "bar", "baz"];
+     * if (arr.includes(buz)) {}
+     * // ---------------^
+     * // The argument of type 'buz' is not assignable to the parameter of type 'FBB'.
+     *
+     * @example
+     * // FArray.includes
+     * const buz = "buz";
+     * type FBB = "foo" | "bar" | "baz";
+     * const arr = new FArray<FBB>("foo", "bar", "baz");
+     * if (arr.includes(buz)) {
+     * 	// bar is typed as never
+     * } else {
+     * 	// bar is typed as "buz"
+     * }
+     */
+    includes(searchElement, fromIndex = 0) {
+        // @ts-expect-error searchElement is unknown
+        return super.includes(searchElement, fromIndex);
+    }
+}

package/dist/files/downloadText.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Downloads a text blob as a file.
+ * @param filename The filename to save to.
+ * @param text The text to save.
+ */
+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.
+ */
+export declare function downloadTextBlob(filename: string, text: string): void;
+//# sourceMappingURL=downloadText.d.ts.map

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

@@ -0,0 +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"}

package/dist/files/downloadText.js

@@ -0,0 +1,30 @@
+/**
+ * Downloads a text blob as a file.
+ * @param filename The filename to save to.
+ * @param text The text to save.
+ */
+export function downloadText(filename, text) {
+    const element = document.createElement("a");
+    element.setAttribute("href", "data:text/plain;charset=utf-8," + encodeURIComponent(text));
+    element.setAttribute("download", filename);
+    element.style.display = "none";
+    document.body.appendChild(element);
+    element.click();
+    document.body.removeChild(element);
+}
+/**
+ * Downloads a text blob as a file.
+ * @param filename The filename to save to.
+ * @param text The text to save.
+ */
+export function downloadTextBlob(filename, text) {
+    const url = URL.createObjectURL(new Blob([text], { type: "text/plain" }));
+    const a = document.createElement("a");
+    a.setAttribute("download", filename);
+    a.setAttribute("href", url);
+    a.style.setProperty("display", "none");
+    document.body.appendChild(a);
+    a.click();
+    URL.revokeObjectURL(url);
+    document.body.removeChild(a);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/maths/average.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Calculates the average of all numbers in an array.
+ *
+ * @param {number[]} arr - The array of numbers to average.
+ * @return {number} The average of all numbers in the array.
+ */
+export declare function avg(arr: number[]): number;
+//# sourceMappingURL=average.d.ts.map

package/dist/maths/average.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"average.d.ts","sourceRoot":"","sources":["../../src/maths/average.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzC"}

package/dist/maths/average.js

@@ -0,0 +1,10 @@
+import { sum } from "./sum.js";
+/**
+ * Calculates the average of all numbers in an array.
+ *
+ * @param {number[]} arr - The array of numbers to average.
+ * @return {number} The average of all numbers in the array.
+ */
+export function avg(arr) {
+    return sum(arr) / arr.length;
+}

package/dist/maths/index.d.ts

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

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

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

package/dist/maths/index.js

@@ -0,0 +1,2 @@
+export * from "./average.js";
+export * from "./sum.js";

package/dist/maths/sum.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Calculates the sum of all numbers in an array.
+ *
+ * @param {number[]} arr - The array of numbers to sum.
+ * @return {number} The sum of all numbers in the array.
+ */
+export declare function sum(arr: number[]): number;
+//# sourceMappingURL=sum.d.ts.map

package/dist/maths/sum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sum.d.ts","sourceRoot":"","sources":["../../src/maths/sum.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzC"}

package/dist/maths/sum.js

@@ -0,0 +1,9 @@
+/**
+ * Calculates the sum of all numbers in an array.
+ *
+ * @param {number[]} arr - The array of numbers to sum.
+ * @return {number} The sum of all numbers in the array.
+ */
+export function sum(arr) {
+    return arr.reduce((total, n) => total + n, 0);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@forthtilliath/ts-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Forthtilliath/forthtilliath-packages.git",
+    "directory": "packages/ts-kit"
+  },
+  "homepage": "https://github.com/Forthtilliath/forthtilliath-packages/tree/main/packages/ts-kit#readme",
+  "bugs": "https://github.com/Forthtilliath/forthtilliath-packages/issues",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./*": "./dist/*.js"
+  },
+  "devDependencies": {
+    "eslint": "10.7.0",
+    "jsdom": "^29.1.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@forthtilliath/eslint-config": "0.0.0",
+    "@forthtilliath/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}