trousse 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maciej Lamberski
+
+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,15 @@
+# trousse
+
+[![codecov](https://codecov.io/gh/macieklamberski/trousse/branch/main/graph/badge.svg)](https://codecov.io/gh/macieklamberski/trousse)
+[![npm version](https://img.shields.io/npm/v/trousse.svg)](https://www.npmjs.com/package/trousse)
+[![license](https://img.shields.io/npm/l/trousse.svg)](https://github.com/macieklamberski/trousse/blob/main/LICENSE)
+
+Personal toolbox of shared TypeScript utilities used across my projects: type guards, coercions, matching and array helpers.
+
+## Installation
+
+```bash
+npm add trousse
+```
+
+In published packages, prefer adding it as a dev dependency and bundling it at build time so it adds no runtime dependency.

package/dist/arrays.d.ts

@@ -0,0 +1,4 @@
+//#region src/arrays.d.ts
+declare const omitEmpty: <T>(array: Array<T | null | undefined>) => Array<T>;
+//#endregion
+export { omitEmpty };

package/dist/arrays.js

@@ -0,0 +1,9 @@
+import { isPresent } from "./is.js";
+//#region src/arrays.ts
+const omitEmpty = (array) => {
+	const result = [];
+	for (const item of array) if (isPresent(item) && item !== "") result.push(item);
+	return result;
+};
+//#endregion
+export { omitEmpty };

package/dist/coercions.d.ts

@@ -0,0 +1,11 @@
+import { Nullish } from "./types.js";
+
+//#region src/coercions.d.ts
+declare const coerceString: (value: unknown) => string | undefined;
+declare const coerceNumber: (value: unknown) => number | undefined;
+declare const coerceBoolean: (value: unknown) => boolean | undefined;
+declare const coerceDate: (value: unknown) => Date | undefined;
+declare const coerceSingular: <T>(value: T | Array<T>) => T;
+declare const coerceArray: <T>(value: Nullish<T | Array<T>>) => Array<T>;
+//#endregion
+export { coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString };

package/dist/coercions.js

@@ -0,0 +1,38 @@
+import { isBoolean, isNonEmptyString, isNullish, isNumber, isString, isValidDate } from "./is.js";
+//#region src/coercions.ts
+const coerceString = (value) => {
+	if (isString(value)) return value;
+	if (isNumber(value)) return String(value);
+};
+const coerceNumber = (value) => {
+	if (isNumber(value)) return Number.isNaN(value) ? void 0 : value;
+	if (isNonEmptyString(value)) {
+		const numeric = +value;
+		return Number.isNaN(numeric) ? void 0 : numeric;
+	}
+};
+const trueRegex = /^\p{White_Space}*true\p{White_Space}*$/iu;
+const falseRegex = /^\p{White_Space}*false\p{White_Space}*$/iu;
+const coerceBoolean = (value) => {
+	if (isBoolean(value)) return value;
+	if (isNonEmptyString(value)) {
+		if (trueRegex.test(value)) return true;
+		if (falseRegex.test(value)) return false;
+	}
+};
+const coerceDate = (value) => {
+	if (isValidDate(value)) return value;
+	if (isNumber(value) || isNonEmptyString(value)) {
+		const date = new Date(value);
+		return Number.isNaN(date.getTime()) ? void 0 : date;
+	}
+};
+const coerceSingular = (value) => {
+	return Array.isArray(value) ? value[0] : value;
+};
+const coerceArray = (value) => {
+	if (isNullish(value)) return [];
+	return Array.isArray(value) ? value : [value];
+};
+//#endregion
+export { coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { omitEmpty } from "./arrays.js";
+import { MaybePromise, Nullish, Pattern } from "./types.js";
+import { coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString } from "./coercions.js";
+import { isBoolean, isFunction, isNonEmptyString, isNullish, isNumber, isObject, isPlainObject, isPresent, isString, isValidDate } from "./is.js";
+import { isJsonLike, isParseableJson } from "./json.js";
+import { anyWordMatchesAnyOf, endsWithAnyOf, includesAnyOf, isAnyOf, startsWithAnyOf } from "./matching.js";
+import { sleep } from "./timers.js";
+import { getPathSegments, isHostOf, isSubdomainOf, parseUrl } from "./urls.js";
+export { type MaybePromise, type Nullish, type Pattern, anyWordMatchesAnyOf, coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString, endsWithAnyOf, getPathSegments, includesAnyOf, isAnyOf, isBoolean, isFunction, isHostOf, isJsonLike, isNonEmptyString, isNullish, isNumber, isObject, isParseableJson, isPlainObject, isPresent, isString, isSubdomainOf, isValidDate, omitEmpty, parseUrl, sleep, startsWithAnyOf };

package/dist/index.js

@@ -0,0 +1,8 @@
+import { isBoolean, isFunction, isNonEmptyString, isNullish, isNumber, isObject, isPlainObject, isPresent, isString, isValidDate } from "./is.js";
+import { omitEmpty } from "./arrays.js";
+import { coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString } from "./coercions.js";
+import { isJsonLike, isParseableJson } from "./json.js";
+import { anyWordMatchesAnyOf, endsWithAnyOf, includesAnyOf, isAnyOf, startsWithAnyOf } from "./matching.js";
+import { sleep } from "./timers.js";
+import { getPathSegments, isHostOf, isSubdomainOf, parseUrl } from "./urls.js";
+export { anyWordMatchesAnyOf, coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString, endsWithAnyOf, getPathSegments, includesAnyOf, isAnyOf, isBoolean, isFunction, isHostOf, isJsonLike, isNonEmptyString, isNullish, isNumber, isObject, isParseableJson, isPlainObject, isPresent, isString, isSubdomainOf, isValidDate, omitEmpty, parseUrl, sleep, startsWithAnyOf };

package/dist/is.d.ts

@@ -0,0 +1,13 @@
+//#region src/is.d.ts
+declare const isString: (value: unknown) => value is string;
+declare const isNumber: (value: unknown) => value is number;
+declare const isBoolean: (value: unknown) => value is boolean;
+declare const isFunction: (value: unknown) => value is (...args: Array<never>) => unknown;
+declare const isPresent: <T>(value: T) => value is NonNullable<T>;
+declare const isNullish: (value: unknown) => value is null | undefined;
+declare const isObject: (value: unknown) => value is object;
+declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+declare const isNonEmptyString: (value: unknown) => value is string;
+declare const isValidDate: (value: unknown) => value is Date;
+//#endregion
+export { isBoolean, isFunction, isNonEmptyString, isNullish, isNumber, isObject, isPlainObject, isPresent, isString, isValidDate };

package/dist/is.js

@@ -0,0 +1,34 @@
+//#region src/is.ts
+const isString = (value) => {
+	return typeof value === "string";
+};
+const isNumber = (value) => {
+	return typeof value === "number";
+};
+const isBoolean = (value) => {
+	return typeof value === "boolean";
+};
+const isFunction = (value) => {
+	return typeof value === "function";
+};
+const isPresent = (value) => {
+	return value != null;
+};
+const isNullish = (value) => {
+	return value == null;
+};
+const isObject = (value) => {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+const isPlainObject = (value) => {
+	return isObject(value) && value.constructor === Object;
+};
+const whitespaceOnlyRegex = /^\p{White_Space}*$/u;
+const isNonEmptyString = (value) => {
+	return isString(value) && value !== "" && !whitespaceOnlyRegex.test(value);
+};
+const isValidDate = (value) => {
+	return value instanceof Date && !Number.isNaN(value.getTime());
+};
+//#endregion
+export { isBoolean, isFunction, isNonEmptyString, isNullish, isNumber, isObject, isPlainObject, isPresent, isString, isValidDate };

package/dist/json.d.ts

@@ -0,0 +1,5 @@
+//#region src/json.d.ts
+declare const isJsonLike: (value: string) => boolean;
+declare const isParseableJson: (value: string) => boolean;
+//#endregion
+export { isJsonLike, isParseableJson };

package/dist/json.js

@@ -0,0 +1,19 @@
+//#region src/json.ts
+const jsonObjectStartRegex = /^\s*\{/;
+const jsonObjectEndRegex = /\}\s*$/;
+const jsonArrayStartRegex = /^\s*\[/;
+const jsonArrayEndRegex = /\]\s*$/;
+const isJsonLike = (value) => {
+	if (value.length < 2) return false;
+	return jsonObjectStartRegex.test(value) && jsonObjectEndRegex.test(value) || jsonArrayStartRegex.test(value) && jsonArrayEndRegex.test(value);
+};
+const isParseableJson = (value) => {
+	try {
+		JSON.parse(value);
+		return true;
+	} catch {
+		return false;
+	}
+};
+//#endregion
+export { isJsonLike, isParseableJson };

package/dist/matching.d.ts

@@ -0,0 +1,10 @@
+import { Pattern } from "./types.js";
+
+//#region src/matching.d.ts
+declare const isAnyOf: (value: string, patterns: Array<Pattern>, parser?: (value: string) => string) => boolean;
+declare const includesAnyOf: (value: string, patterns: Array<Pattern>, parser?: (value: string) => string) => boolean;
+declare const startsWithAnyOf: (value: string, patterns: Array<Pattern>) => boolean;
+declare const endsWithAnyOf: (value: string, patterns: Array<Pattern>) => boolean;
+declare const anyWordMatchesAnyOf: (value: string, patterns: Array<Pattern>) => boolean;
+//#endregion
+export { anyWordMatchesAnyOf, endsWithAnyOf, includesAnyOf, isAnyOf, startsWithAnyOf };

package/dist/matching.js

@@ -0,0 +1,35 @@
+//#region src/matching.ts
+const whitespaceRegex = /\s+/;
+const isAnyOf = (value, patterns, parser) => {
+	const parsedValue = parser ? parser(value) : value?.toLowerCase()?.trim();
+	return patterns.some((pattern) => {
+		if (pattern instanceof RegExp) return pattern.test(parsedValue);
+		return parsedValue === pattern.toLowerCase().trim();
+	});
+};
+const includesAnyOf = (value, patterns, parser) => {
+	const parsedValue = parser ? parser(value) : value?.toLowerCase();
+	return patterns.some((pattern) => {
+		if (pattern instanceof RegExp) return pattern.test(parsedValue);
+		return pattern && parsedValue?.includes(pattern.toLowerCase());
+	});
+};
+const startsWithAnyOf = (value, patterns) => {
+	const lowerValue = value.toLowerCase();
+	return patterns.some((pattern) => {
+		if (pattern instanceof RegExp) return pattern.test(lowerValue);
+		return pattern && lowerValue.startsWith(pattern.toLowerCase());
+	});
+};
+const endsWithAnyOf = (value, patterns) => {
+	const lowerValue = value.toLowerCase();
+	return patterns.some((pattern) => {
+		if (pattern instanceof RegExp) return pattern.test(lowerValue);
+		return pattern && lowerValue.endsWith(pattern.toLowerCase());
+	});
+};
+const anyWordMatchesAnyOf = (value, patterns) => {
+	return value.toLowerCase().split(whitespaceRegex).some((word) => isAnyOf(word, patterns));
+};
+//#endregion
+export { anyWordMatchesAnyOf, endsWithAnyOf, includesAnyOf, isAnyOf, startsWithAnyOf };

package/dist/timers.d.ts

@@ -0,0 +1,4 @@
+//#region src/timers.d.ts
+declare const sleep: (milliseconds: number) => Promise<void>;
+//#endregion
+export { sleep };

package/dist/timers.js

@@ -0,0 +1,8 @@
+//#region src/timers.ts
+const sleep = (milliseconds) => {
+	return new Promise((resolve) => {
+		setTimeout(resolve, milliseconds);
+	});
+};
+//#endregion
+export { sleep };

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+//#region src/types.d.ts
+type Nullish<T> = T | null | undefined;
+type MaybePromise<T> = T | Promise<T>;
+type Pattern = string | RegExp;
+//#endregion
+export { MaybePromise, Nullish, Pattern };

package/dist/urls.d.ts

@@ -0,0 +1,7 @@
+//#region src/urls.d.ts
+declare const parseUrl: (value: string | URL, base?: string | URL) => URL | undefined;
+declare const getPathSegments: (value: string | URL) => Array<string>;
+declare const isHostOf: (url: string | URL, hosts: string | Array<string>) => boolean;
+declare const isSubdomainOf: (url: string | URL, domains: string | Array<string>) => boolean;
+//#endregion
+export { getPathSegments, isHostOf, isSubdomainOf, parseUrl };

package/dist/urls.js

@@ -0,0 +1,23 @@
+import { endsWithAnyOf, isAnyOf } from "./matching.js";
+//#region src/urls.ts
+const parseUrl = (value, base) => {
+	if (value instanceof URL && base === void 0) return value;
+	try {
+		return new URL(value, base);
+	} catch {}
+};
+const getPathSegments = (value) => {
+	return parseUrl(value)?.pathname.split("/").filter(Boolean) ?? [];
+};
+const isHostOf = (url, hosts) => {
+	const hostname = parseUrl(url)?.hostname;
+	if (!hostname) return false;
+	return isAnyOf(hostname, Array.isArray(hosts) ? hosts : [hosts]);
+};
+const isSubdomainOf = (url, domains) => {
+	const hostname = parseUrl(url)?.hostname;
+	if (!hostname) return false;
+	return endsWithAnyOf(hostname, (Array.isArray(domains) ? domains : [domains]).map((domain) => `.${domain}`));
+};
+//#endregion
+export { getPathSegments, isHostOf, isSubdomainOf, parseUrl };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "trousse",
+  "description": "Personal toolbox of shared TypeScript utilities: type guards, coercions, matching and array helpers.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/macieklamberski/trousse.git"
+  },
+  "bugs": {
+    "url": "https://github.com/macieklamberski/trousse/issues"
+  },
+  "license": "MIT",
+  "author": "Maciej Lamberski",
+  "sideEffects": false,
+  "keywords": [
+    "utils",
+    "helpers",
+    "typescript",
+    "guards",
+    "coerce",
+    "predicates",
+    "toolbox"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare": "lefthook install",
+    "build": "tsdown src/index.ts --format esm --dts --clean --unbundle --no-fixed-extension",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "kvalita": "^1.15.0",
+    "tsdown": "^0.22.2"
+  },
+  "version": "1.0.0"
+}