utilful 2.5.2 → 3.0.0

package/dist/path.mjs

@@ -56,7 +56,7 @@ function joinURL(...paths) {
 			continue;
 		}
 		if (path === "/") continue;
-		const resultHasTrailing = result[result.length - 1] === "/";
+		const resultHasTrailing = result.at(-1) === "/";
 		const pathHasLeading = path[0] === "/";
 		if (resultHasTrailing && pathHasLeading) result += path.slice(1);
 		else if (!resultHasTrailing && !pathHasLeading) result += `/${path}`;
@@ -70,7 +70,7 @@ function joinURL(...paths) {
 function withBase(input = "", base = "") {
 	if (!base || base === "/") return input;
 	const _base = withoutTrailingSlash(base);
-	if (input.startsWith(_base) && (input.length === _base.length || input[_base.length] === "/" || input[_base.length] === "?")) return input;
+	if (input.startsWith(_base) && (input.length === _base.length || input[_base.length] === "/" || input[_base.length] === "?" || input[_base.length] === "#")) return input;
 	return joinURL(_base, input);
 }
 /**
@@ -79,15 +79,20 @@ function withBase(input = "", base = "") {
 function withoutBase(input = "", base = "") {
 	if (!base || base === "/") return input;
 	const _base = withoutTrailingSlash(base);
-	if (!input.startsWith(_base) || input.length !== _base.length && input[_base.length] !== "/" && input[_base.length] !== "?") return input;
+	if (!input.startsWith(_base) || input.length !== _base.length && input[_base.length] !== "/" && input[_base.length] !== "?" && input[_base.length] !== "#") return input;
 	const trimmed = input.slice(_base.length);
 	return trimmed[0] === "/" ? trimmed : `/${trimmed}`;
 }
+const URL_SCHEME_RE = /^[a-z][\w+.-]*:\/\//i;
 /**
 * Returns the pathname of the given path, which is the path without the query string or hash.
+*
+* @remarks
+* Absolute URLs (with a scheme, e.g. `https://example.com/foo`) return the URL's pathname.
+* All other inputs are returned unchanged with the query string and hash removed.
 */
 function getPathname(path = "/") {
-	if (!path.startsWith("/")) return new URL(path, "http://localhost").pathname;
+	if (URL_SCHEME_RE.test(path)) return new URL(path).pathname;
 	let pathEnd = path.length;
 	const queryIndex = path.indexOf("?");
 	const hashIndex = path.indexOf("#");

package/dist/result.d.mts

@@ -10,10 +10,10 @@ interface ErrData<E> {
 }
 type ResultData<T, E> = OkData<T> | ErrData<E>;
 /**
-* Successful result variant.
-* @template T Success value type.
-* @template E Error type (phantom - for type unification).
-*/
+ * Successful result variant.
+ * @template T Success value type.
+ * @template E Error type (phantom - for type unification).
+ */
 declare class Ok<T, E = never> {
   readonly value: T;
   readonly ok = true;
@@ -35,10 +35,10 @@ declare class Ok<T, E = never> {
   }): R;
 }
 /**
-* Error result variant.
-* @template T Success type (phantom - for type unification).
-* @template E Error value type.
-*/
+ * Error result variant.
+ * @template T Success type (phantom - for type unification).
+ * @template E Error value type.
+ */
 declare class Err<T, E> {
   readonly error: E;
   readonly ok = false;
@@ -64,6 +64,14 @@ declare function err<T = never, E extends string = string>(error: E): Err<T, E>;
 declare function err<T = never, E = unknown>(error: E): Err<T, E>;
 declare function isOk<T, E>(result: Result<T, E>): result is Ok<T, E>;
 declare function isErr<T, E>(result: Result<T, E>): result is Err<T, E>;
+/**
+ * Wraps a function call or promise in a `Result`.
+ *
+ * @remarks
+ * The function overload must be synchronous. For asynchronous work, pass the
+ * promise itself (e.g. `toResult(fn())`) – a function returning a promise
+ * throws a `TypeError`, since its rejection could not be captured as `Err`.
+ */
 declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>;
 declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>;
 declare function unwrapResult<T, E>(result: Ok<T, E>): OkData<T>;

package/dist/result.mjs

@@ -5,9 +5,8 @@
 * @template E Error type (phantom - for type unification).
 */
 var Ok = class Ok {
-	value;
-	ok = true;
 	constructor(value) {
+		this.ok = true;
 		this.value = value;
 	}
 	/** Transforms the success value. */
@@ -41,9 +40,8 @@ var Ok = class Ok {
 * @template E Error value type.
 */
 var Err = class Err {
-	error;
-	ok = false;
 	constructor(error) {
+		this.ok = false;
 		this.error = error;
 	}
 	/** No-op on Err, returns self with new value type. */
@@ -85,11 +83,14 @@ function isErr(result) {
 }
 function toResult(fnOrPromise) {
 	if (fnOrPromise instanceof Promise) return fnOrPromise.then(ok).catch(err);
+	let value;
 	try {
-		return ok(fnOrPromise());
+		value = fnOrPromise();
 	} catch (error) {
 		return err(error);
 	}
+	if (value instanceof Promise) throw new TypeError("[toResult] The function returned a promise. Pass the promise itself instead, e.g. toResult(fn())");
+	return ok(value);
 }
 function unwrapResult(result) {
 	return result.ok ? {

package/dist/string.d.mts

@@ -1,20 +1,24 @@
 //#region src/string.d.ts
 /**
-* Simple template engine to replace variables in a string.
-*
-* @example
-* const str = 'Hello, {name}!'
-* const variables = { name: 'world' }
-*
-* console.log(template(str, variables)) // Hello, world!
-*/
+ * Simple template engine to replace variables in a string.
+ *
+ * @remarks
+ * Only own properties of `variables` are substituted, so placeholders like
+ * `{constructor}` cannot leak prototype members.
+ *
+ * @example
+ * const str = 'Hello, {name}!'
+ * const variables = { name: 'world' }
+ *
+ * console.log(template(str, variables)) // Hello, world!
+ */
 declare function template(str: string, variables: Record<string | number, any>, fallback?: string | ((key: string) => string)): string;
 /**
-* Generates a random string.
-*
-* @remarks Ported from `nanoid`.
-* @see https://github.com/ai/nanoid
-*/
+ * Generates a random string.
+ *
+ * @remarks Ported from `nanoid`.
+ * @see https://github.com/ai/nanoid
+ */
 declare function generateRandomId(size?: number, dict?: string): string;
 //#endregion
 export { generateRandomId, template };

package/dist/string.mjs

@@ -1,8 +1,13 @@
 //#region src/string.ts
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+const TEMPLATE_PLACEHOLDER_RE = /\{(\w+)\}/g;
 /**
 * Simple template engine to replace variables in a string.
 *
+* @remarks
+* Only own properties of `variables` are substituted, so placeholders like
+* `{constructor}` cannot leak prototype members.
+*
 * @example
 * const str = 'Hello, {name}!'
 * const variables = { name: 'world' }
@@ -10,8 +15,9 @@ const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvw
 * console.log(template(str, variables)) // Hello, world!
 */
 function template(str, variables, fallback) {
-	return str.replace(/\{(\w+)\}/g, (_, key) => {
-		return variables[key] != null ? String(variables[key]) : (typeof fallback === "function" ? fallback(key) : fallback) ?? key;
+	return str.replace(TEMPLATE_PLACEHOLDER_RE, (_, key) => {
+		const value = Object.hasOwn(variables, key) ? variables[key] : void 0;
+		return value != null ? String(value) : (typeof fallback === "function" ? fallback(key) : fallback) ?? key;
 	});
 }
 /**

package/dist/types.d.mts

@@ -2,7 +2,7 @@
 type AutocompletableString = string & {};
 type LooseAutocomplete<T extends string> = T | AutocompletableString;
 /** Also commonly referred to as `Prettify` */
-type UnifyIntersection<T> = { [K in keyof T]: T[K] } & {};
+type UnifyIntersection<T> = { [K in keyof T]: T[K]; } & {};
 declare const brand: unique symbol;
 type BrandedType<T, B> = T & {
   [brand]: B;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "2.5.2",
-  "packageManager": "pnpm@10.30.3",
+  "version": "3.0.0",
+  "packageManager": "pnpm@11.15.1",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -78,19 +78,13 @@
     "release": "bumpp"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^7.6.1",
-    "@types/node": "^25.3.5",
-    "bumpp": "^10.4.1",
-    "eslint": "^10.0.2",
-    "eslint-flat-config-utils": "^3.0.1",
-    "tsdown": "^0.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "unrs-resolver"
-    ]
+    "@antfu/eslint-config": "^9.1.0",
+    "@types/node": "^26.1.1",
+    "bumpp": "^12.0.0",
+    "eslint": "^10.7.0",
+    "eslint-flat-config-utils": "^3.2.0",
+    "tsdown": "^0.22.13",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
 }