utilful 2.4.0 → 2.5.0

package/README.md

@@ -13,7 +13,6 @@ A collection of TypeScript utilities that I use across my projects.
   - [JSON](#json)
   - [Module](#module)
   - [Object](#object)
-  - [Path](#path)
   - [Result](#result)
   - [String](#string)
 
@@ -150,13 +149,7 @@ Recursively assign default properties. Simplified version based on [unjs/defu](h
 
 Recursively assigns missing properties from defaults to the source object. The source object takes precedence over defaults.
 
-**Key Features:**
-
-- **Nullish handling**: `null` and `undefined` values in source are replaced with defaults
-- **Array concatenation**: Arrays are concatenated (source + defaults)
-- **Deep merging**: Nested objects are recursively merged
-- **Type safety**: Preserves TypeScript types
-- **Prototype pollution protection**: Ignores `__proto__` and `constructor` keys
+The function replaces `null` and `undefined` values in the source with defaults, concatenates arrays (source + defaults), and recursively merges nested objects.
 
 ```ts
 type PlainObject = Record<PropertyKey, any>
@@ -358,191 +351,170 @@ Deeply applies a callback to every key-value pair in the given object, as well a
 declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void
 ```
 
-### Path
-
-#### `withoutLeadingSlash`
-
-Removes the leading slash from the given path if it has one.
-
-```ts
-declare function withoutLeadingSlash(path?: string): string
-```
-
-#### `withLeadingSlash`
+### Result
 
-Adds a leading slash to the given path if it does not already have one.
+The `Result` type represents either success (`Ok`) or failure (`Err`). It provides a type-safe way to handle errors without relying on exceptions.
 
 ```ts
-declare function withLeadingSlash(path?: string): string
+type Result<T, E> = Ok<T, E> | Err<T, E>
 ```
 
-#### `withoutTrailingSlash`
+Both `Ok` and `Err` carry phantom types for proper type inference in unions.
 
-Removes the trailing slash from the given path if it has one.
+**Basic example:**
 
 ```ts
-declare function withoutTrailingSlash(path?: string): string
-```
-
-#### `withTrailingSlash`
+import { err, ok } from 'utilful'
 
-Adds a trailing slash to the given path if it does not already have one.
+function divide(a: number, b: number) {
+  if (b === 0) {
+    return err('Division by zero')
+  }
+  return ok(a / b)
+}
 
-```ts
-declare function withTrailingSlash(path?: string): string
+const result = divide(10, 2)
+if (result.ok)
+  console.log('Result:', result.value)
+else
+  console.error('Error:', result.error)
 ```
 
-#### `joinURL`
-
-Joins the given URL path segments, ensuring that there is only one slash between them.
+**Fluent chaining:**
 
 ```ts
-declare function joinURL(...paths: (string | undefined)[]): string
-```
-
-#### `withBase`
+import { toResult } from 'utilful'
 
-Adds the base path to the input path, if it is not already present.
-
-```ts
-declare function withBase(input?: string, base?: string): string
+const name = toResult(() => JSON.parse(jsonString))
+  .map(data => data.user)
+  .map(user => user.name)
+  .unwrapOr('Anonymous')
 ```
 
-#### `withoutBase`
+#### `ok`
 
-Removes the base path from the input path, if it is present.
+Creates a successful result.
 
 ```ts
-declare function withoutBase(input?: string, base?: string): string
+declare function ok<T, E = never>(value: T): Ok<T, E>
 ```
 
-#### `getPathname`
+#### `err`
 
-Returns the pathname of the given path, which is the path without the query string.
+Creates an error result.
 
 ```ts
-declare function getPathname(path?: string): string
+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>
 ```
 
-#### `withQuery`
+#### `isOk` / `isErr`
 
-Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
+Type guards for narrowing `Result` types.
 
 ```ts
-declare function withQuery(input: string, query?: QueryObject): string
+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>
 ```
 
 **Example:**
 
 ```ts
-import { withQuery } from 'utilful'
-
-const url = withQuery('https://example.com', {
-  foo: 'bar',
-  // This key is omitted
-  baz: undefined,
-  // Object values are stringified
-  baz: { qux: 'quux' }
-})
+const result = toResult(() => JSON.parse(str))
+if (isOk(result)) {
+  console.log(result.value) // TypeScript knows this is Ok
+}
 ```
 
-### Result
-
-The `Result` type that represents either success (`Ok`) or failure (`Err`). It helps to handle errors in a more explicit and type-safe way, without relying on exceptions.
+#### `Result.map`
 
-A common use case for `Result` is error handling in functions that might fail. Here's an example of a function that divides two numbers and returns a `Result`:
+Transforms the success value. No-op on `Err`.
 
 ```ts
-import { err, ok } from 'utilful'
-
-function divide(a: number, b: number) {
-  if (b === 0) {
-    return err('Division by zero')
-  }
-  return ok(a / b)
-}
-
-const result = divide(10, 2)
-if (result.ok)
-  console.log('Result:', result.value)
-else
-  console.error('Error:', result.error)
+ok(2).map(x => x * 3) // Ok(6)
+err('fail').map(x => x * 3) // Err('fail')
 ```
 
-#### `Result`
+#### `Result.mapError`
 
-The `Result` type represents either success (`Ok`) or failure (`Err`).
+Transforms the error value. No-op on `Ok`.
 
 ```ts
-type Result<T, E> = Ok<T> | Err<E>
+err('fail').mapError(e => e.toUpperCase()) // Err('FAIL')
+ok(42).mapError(e => e.toUpperCase()) // Ok(42)
 ```
 
-#### `Ok`
+#### `Result.andThen`
 
-The `Ok` type wraps a successful value.
-
-**Example:**
+Chains a function that returns a `Result`. Useful for composing fallible operations.
 
 ```ts
-const result = new Ok(42)
+ok(2).andThen(x => x > 0 ? ok(x) : err('negative')) // Ok(2)
+err('fail').andThen(x => ok(x * 2)) // Err('fail') - short-circuits
 ```
 
-#### `Err`
+#### `Result.unwrap`
 
-The `Err` type wraps an error value.
-
-**Example:**
+Extracts the value or throws an error.
 
 ```ts
-const result = new Err('Something went wrong')
+ok(42).unwrap() // 42
+err('fail').unwrap() // throws Error
+err('fail').unwrap('custom message') // throws Error('custom message')
 ```
 
-#### `ok`
+#### `Result.unwrapOr`
 
-Shorthand function to create an `Ok` result. Use it to wrap a successful value.
+Extracts the value or returns a fallback.
 
 ```ts
-declare function ok<T>(value: T): Ok<T>
+ok(42).unwrapOr(0) // 42
+err('fail').unwrapOr(0) // 0
 ```
 
-#### `err`
+#### `Result.match`
 
-Shorthand function to create an `Err` result. Use it to wrap an error value.
+Pattern matches on the result.
 
 ```ts
-declare function err<E extends string = string>(err: E): Err<E>
-declare function err<E = unknown>(err: E): Err<E>
+result.match({
+  ok: value => `Success: ${value}`,
+  err: error => `Error: ${error}`,
+})
 ```
 
 #### `toResult`
 
-Wraps a function that might throw an error and returns a `Result` with the result of the function.
+Wraps a function or promise that might throw and returns a `Result`.
 
 ```ts
 declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>
 declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
 ```
 
-#### `unwrapResult`
-
-Unwraps a `Result`, `Ok`, or `Err` value and returns the value or error in an object. If the result is an `Ok`, the object contains the value and an `undefined` error. If the result is an `Err`, the object contains an `undefined` value and the error.
+**Example:**
 
 ```ts
-declare function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
-declare function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
-declare function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
+// Synchronous
+const result = toResult(() => JSON.parse('{"foo":"bar"}'))
+
+// Asynchronous
+const result = await toResult(fetch('https://api.example.com'))
 ```
 
-**Example:**
+#### `unwrapResult`
+
+Converts a `Result` to a plain object with `value` and `error` properties.
 
 ```ts
-const result = toResult(() => JSON.parse('{"foo":"bar"}'))
-const { value, error } = unwrapResult(result)
+declare function unwrapResult<T, E>(result: Ok<T, E>): { value: T, error: undefined }
+declare function unwrapResult<T, E>(result: Err<T, E>): { value: undefined, error: E }
+declare function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
 ```
 
 #### `tryCatch`
 
-A simpler alternative to `toResult` + `unwrapResult`. It executes a function that might throw an error and directly returns the result in a `ResultData` format. Works with both synchronous functions and promises.
+Combines `toResult` and `unwrapResult` into one step. Executes a function and returns `{ value, error }` directly.
 
 ```ts
 declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
@@ -552,13 +524,11 @@ declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value:
 **Example:**
 
 ```ts
-import { tryCatch } from 'utilful'
-
-// Synchronous usage
+// Synchronous
 const { value, error } = tryCatch(() => JSON.parse('{"foo":"bar"}'))
 
-// Asynchronous usage
-const { value, error } = await tryCatch(fetch('https://api.example.com/data').then(r => r.json()))
+// Asynchronous
+const { value, error } = await tryCatch(fetch('https://api.example.com').then(r => r.json()))
 ```
 
 ### String

package/dist/index.d.mts

@@ -6,7 +6,7 @@ import { cloneJSON, tryParseJSON } from "./json.mjs";
 import { interopDefault } from "./module.mjs";
 import { deepApply, memoize, objectEntries, objectKeys } from "./object.mjs";
 import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
-import { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
+import { Err, ErrData, Ok, OkData, Result, ResultData, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { generateRandomId, template } from "./string.mjs";
 import { AutocompletableString, BrandedType, LooseAutocomplete, UnifyIntersection } from "./types.mjs";
-export { AutocompletableString, BrandedType, CSVCreateOptions, CSVRow, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { AutocompletableString, BrandedType, CSVCreateOptions, CSVRow, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, isErr, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { cloneJSON, tryParseJSON } from "./json.mjs";
 import { interopDefault } from "./module.mjs";
 import { deepApply, memoize, objectEntries, objectKeys } from "./object.mjs";
 import { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
-import { Err, Ok, err, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
+import { Err, Ok, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { generateRandomId, template } from "./string.mjs";
 
-export { Err, Ok, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { Err, Ok, cloneJSON, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, isErr, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVFromLines, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/path.d.mts

@@ -10,11 +10,13 @@ declare function withoutLeadingSlash(path?: string): string;
 */
 declare function withLeadingSlash(path?: string): string;
 /**
-* Removes the trailing slash from the given path if it has one.
+* Removes the trailing slash from the given path if it has one,
+* preserving query strings and hash fragments.
 */
 declare function withoutTrailingSlash(path?: string): string;
 /**
-* Adds a trailing slash to the given path if it does not already have one
+* Adds a trailing slash to the given path if it does not already have one,
+* preserving query strings and hash fragments.
 */
 declare function withTrailingSlash(path?: string): string;
 /**
@@ -30,7 +32,7 @@ declare function withBase(input?: string, base?: string): string;
 */
 declare function withoutBase(input?: string, base?: string): string;
 /**
-* Returns the pathname of the given path, which is the path without the query string.
+* Returns the pathname of the given path, which is the path without the query string or hash.
 */
 declare function getPathname(path?: string): string;
 /**

package/dist/path.mjs

@@ -3,7 +3,7 @@
 * Removes the leading slash from the given path if it has one.
 */
 function withoutLeadingSlash(path) {
-	if (!path || path === "/") return "/";
+	if (!path) return "";
 	return path[0] === "/" ? path.slice(1) : path;
 }
 /**
@@ -14,31 +14,48 @@ function withLeadingSlash(path) {
 	return path[0] === "/" ? path : `/${path}`;
 }
 /**
-* Removes the trailing slash from the given path if it has one.
+* Removes the trailing slash from the given path if it has one,
+* preserving query strings and hash fragments.
 */
 function withoutTrailingSlash(path) {
 	if (!path || path === "/") return "/";
-	return path[path.length - 1] === "/" ? path.slice(0, -1) : path;
+	let pathEnd = path.length;
+	const queryIndex = path.indexOf("?");
+	const hashIndex = path.indexOf("#");
+	if (queryIndex !== -1) pathEnd = queryIndex;
+	if (hashIndex !== -1 && hashIndex < pathEnd) pathEnd = hashIndex;
+	if (pathEnd > 0 && path[pathEnd - 1] === "/") {
+		if (pathEnd === 1) return path;
+		return path.slice(0, pathEnd - 1) + path.slice(pathEnd);
+	}
+	return path;
 }
 /**
-* Adds a trailing slash to the given path if it does not already have one
+* Adds a trailing slash to the given path if it does not already have one,
+* preserving query strings and hash fragments.
 */
 function withTrailingSlash(path) {
 	if (!path || path === "/") return "/";
-	return path[path.length - 1] === "/" ? path : `${path}/`;
+	let pathEnd = path.length;
+	const queryIndex = path.indexOf("?");
+	const hashIndex = path.indexOf("#");
+	if (queryIndex !== -1) pathEnd = queryIndex;
+	if (hashIndex !== -1 && hashIndex < pathEnd) pathEnd = hashIndex;
+	if (pathEnd > 0 && path[pathEnd - 1] === "/") return path;
+	return `${path.slice(0, pathEnd)}/${path.slice(pathEnd)}`;
 }
 /**
 * Joins the given URL path segments, ensuring that there is only one slash between them.
 */
 function joinURL(...paths) {
 	let result = "";
-	for (let i = 0; i < paths.length; i++) {
-		const path = paths[i];
-		if (!result || result === "/") {
-			result = path || "/";
+	for (const path of paths) {
+		if (!path) continue;
+		if (!result) {
+			result = path;
 			continue;
 		}
-		if (!path || path === "/") continue;
+		if (path === "/") continue;
 		const resultHasTrailing = result[result.length - 1] === "/";
 		const pathHasLeading = path[0] === "/";
 		if (resultHasTrailing && pathHasLeading) result += path.slice(1);
@@ -53,7 +70,7 @@ function joinURL(...paths) {
 function withBase(input = "", base = "") {
 	if (!base || base === "/") return input;
 	const _base = withoutTrailingSlash(base);
-	if (input.startsWith(_base)) return input;
+	if (input.startsWith(_base) && (input.length === _base.length || input[_base.length] === "/" || input[_base.length] === "?")) return input;
 	return joinURL(_base, input);
 }
 /**
@@ -62,15 +79,21 @@ function withBase(input = "", base = "") {
 function withoutBase(input = "", base = "") {
 	if (!base || base === "/") return input;
 	const _base = withoutTrailingSlash(base);
-	if (!input.startsWith(_base)) return input;
+	if (!input.startsWith(_base) || input.length !== _base.length && input[_base.length] !== "/" && input[_base.length] !== "?") return input;
 	const trimmed = input.slice(_base.length);
 	return trimmed[0] === "/" ? trimmed : `/${trimmed}`;
 }
 /**
-* Returns the pathname of the given path, which is the path without the query string.
+* Returns the pathname of the given path, which is the path without the query string or hash.
 */
 function getPathname(path = "/") {
-	return path.startsWith("/") ? path.split("?")[0] : new URL(path, "http://localhost").pathname;
+	if (!path.startsWith("/")) return new URL(path, "http://localhost").pathname;
+	let pathEnd = path.length;
+	const queryIndex = path.indexOf("?");
+	const hashIndex = path.indexOf("#");
+	if (queryIndex !== -1) pathEnd = queryIndex;
+	if (hashIndex !== -1 && hashIndex < pathEnd) pathEnd = hashIndex;
+	return path.slice(0, pathEnd) || "/";
 }
 /**
 * Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
@@ -80,7 +103,7 @@ function withQuery(input, query) {
 	const searchIndex = input.indexOf("?");
 	const hasExistingParams = searchIndex !== -1;
 	const base = hasExistingParams ? input.slice(0, searchIndex) : input;
-	const searchParams = hasExistingParams ? new URLSearchParams(input.slice(searchIndex + 1)) : new URLSearchParams();
+	const searchParams = new URLSearchParams(hasExistingParams ? input.slice(searchIndex + 1) : void 0);
 	for (const [key, value] of Object.entries(query)) {
 		if (value === void 0) {
 			searchParams.delete(key);

package/dist/result.d.mts

@@ -1,5 +1,5 @@
 //#region src/result.d.ts
-type Result<T, E> = Ok<T> | Err<E>;
+type Result<T, E> = Ok<T, E> | Err<T, E>;
 interface OkData<T> {
   value: T;
   error: undefined;
@@ -9,25 +9,67 @@ interface ErrData<E> {
   error: E;
 }
 type ResultData<T, E> = OkData<T> | ErrData<E>;
-declare class Ok<T> {
+/**
+* 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;
   constructor(value: T);
+  /** Transforms the success value. */
+  map<U>(fn: (value: T) => U): Ok<U, E>;
+  /** No-op on Ok, returns self with new error type. */
+  mapError<E2>(_fn: (error: E) => E2): Ok<T, E2>;
+  /** Chains a Result-returning function. */
+  andThen<U, E2>(fn: (value: T) => Result<U, E2>): Result<U, E | E2>;
+  /** Extracts the value. */
+  unwrap(_message?: string): T;
+  /** Returns the value, ignoring the fallback. */
+  unwrapOr<U>(_fallback: U): T;
+  /** Pattern matches on the Result. */
+  match<R>(handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+  }): R;
 }
-declare class Err<E> {
+/**
+* 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;
   constructor(error: E);
+  /** No-op on Err, returns self with new value type. */
+  map<U>(_fn: (value: T) => U): Err<U, E>;
+  /** Transforms the error value. */
+  mapError<E2>(fn: (error: E) => E2): Err<T, E2>;
+  /** No-op on Err, returns self with widened error type. */
+  andThen<U, E2>(_fn: (value: T) => Result<U, E2>): Err<U, E | E2>;
+  /** Throws an error with the given message. */
+  unwrap(message?: string): never;
+  /** Returns the fallback value. */
+  unwrapOr<U>(fallback: U): T | U;
+  /** Pattern matches on the Result. */
+  match<R>(handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+  }): R;
 }
-declare function ok<T>(value: T): Ok<T>;
-declare function err<E extends string = string>(error: E): Err<E>;
-declare function err<E = unknown>(error: E): Err<E>;
+declare function ok<T, E = never>(value: T): Ok<T, E>;
+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>;
 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>(result: Ok<T>): OkData<T>;
-declare function unwrapResult<E>(result: Err<E>): ErrData<E>;
+declare function unwrapResult<T, E>(result: Ok<T, E>): OkData<T>;
+declare function unwrapResult<T, E>(result: Err<T, E>): ErrData<E>;
 declare function unwrapResult<T, E>(result: Result<T, E>): ResultData<T, E>;
 declare function tryCatch<T, E = unknown>(fn: () => T): ResultData<T, E>;
 declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<ResultData<T, E>>;
 //#endregion
-export { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult };
+export { Err, ErrData, Ok, OkData, Result, ResultData, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult };

package/dist/result.mjs

@@ -1,17 +1,75 @@
 //#region src/result.ts
-var Ok = class {
+/**
+* Successful result variant.
+* @template T Success value type.
+* @template E Error type (phantom - for type unification).
+*/
+var Ok = class Ok {
 	value;
 	ok = true;
 	constructor(value) {
 		this.value = value;
 	}
+	/** Transforms the success value. */
+	map(fn) {
+		return new Ok(fn(this.value));
+	}
+	/** No-op on Ok, returns self with new error type. */
+	mapError(_fn) {
+		return this;
+	}
+	/** Chains a Result-returning function. */
+	andThen(fn) {
+		return fn(this.value);
+	}
+	/** Extracts the value. */
+	unwrap(_message) {
+		return this.value;
+	}
+	/** Returns the value, ignoring the fallback. */
+	unwrapOr(_fallback) {
+		return this.value;
+	}
+	/** Pattern matches on the Result. */
+	match(handlers) {
+		return handlers.ok(this.value);
+	}
 };
-var Err = class {
+/**
+* Error result variant.
+* @template T Success type (phantom - for type unification).
+* @template E Error value type.
+*/
+var Err = class Err {
 	error;
 	ok = false;
 	constructor(error) {
 		this.error = error;
 	}
+	/** No-op on Err, returns self with new value type. */
+	map(_fn) {
+		return this;
+	}
+	/** Transforms the error value. */
+	mapError(fn) {
+		return new Err(fn(this.error));
+	}
+	/** No-op on Err, returns self with widened error type. */
+	andThen(_fn) {
+		return this;
+	}
+	/** Throws an error with the given message. */
+	unwrap(message) {
+		throw new Error(message ?? `Unwrap called on Err: ${String(this.error)}`);
+	}
+	/** Returns the fallback value. */
+	unwrapOr(fallback) {
+		return fallback;
+	}
+	/** Pattern matches on the Result. */
+	match(handlers) {
+		return handlers.err(this.error);
+	}
 };
 function ok(value) {
 	return new Ok(value);
@@ -19,6 +77,12 @@ function ok(value) {
 function err(error) {
 	return new Err(error);
 }
+function isOk(result) {
+	return result.ok === true;
+}
+function isErr(result) {
+	return result.ok === false;
+}
 function toResult(fnOrPromise) {
 	if (fnOrPromise instanceof Promise) return fnOrPromise.then(ok).catch(err);
 	try {
@@ -42,4 +106,4 @@ function tryCatch(fnOrPromise) {
 }
 
 //#endregion
-export { Err, Ok, err, ok, toResult, tryCatch, unwrapResult };
+export { Err, Ok, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "2.4.0",
-  "packageManager": "pnpm@10.21.0",
+  "version": "2.5.0",
+  "packageManager": "pnpm@10.28.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -78,13 +78,13 @@
     "release": "bumpp"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^6.2.0",
-    "@types/node": "^24.10.0",
-    "bumpp": "^10.3.1",
-    "eslint": "^9.39.1",
-    "tsdown": "^0.16.1",
+    "@antfu/eslint-config": "^7.0.1",
+    "@types/node": "^25.0.9",
+    "bumpp": "^10.4.0",
+    "eslint": "^9.39.2",
+    "tsdown": "^0.19.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.8"
+    "vitest": "^4.0.17"
   },
   "pnpm": {
     "onlyBuiltDependencies": [