@depthbomb/common 2.1.0 → 2.2.0

package/dist/promise.d.mts

@@ -1,6 +1,9 @@
 import { Awaitable } from "./typing.mjs";
 
 //#region src/promise.d.ts
+/**
+ * Configuration for promise concurrency helpers.
+ */
 interface IConcurrencyOptions {
   concurrency?: number;
 }
@@ -11,6 +14,9 @@ interface IConcurrencyOptions {
  * @returns A promise that resolves to an array of successful results
  */
 declare function allSettledSuccessful<T>(promises: Array<Awaitable<T>>): Promise<T[]>;
+/**
+ * Detailed output from {@link allSettledDetailed}.
+ */
 interface SettledDetailed<T> {
   results: Array<PromiseSettledResult<T>>;
   fulfilled: T[];

package/dist/random.d.cts

@@ -1,11 +1,36 @@
 //#region src/random.d.ts
+/**
+ * A value paired with a non-negative selection weight.
+ */
 interface IWeightedItem<T> {
   value: T;
   weight: number;
 }
+/**
+ * Returns a random floating-point number in the half-open range `[min, max)`.
+ *
+ * @param min Lower bound.
+ * @param max Upper bound.
+ */
 declare function randomFloat(min?: number, max?: number): number;
+/**
+ * Returns a random integer in the inclusive range `[min, max]`.
+ *
+ * @param min Lower bound.
+ * @param max Upper bound.
+ */
 declare function randomInt(min: number, max: number): number;
+/**
+ * Picks a random element from a non-empty array.
+ *
+ * @param values Candidate values.
+ */
 declare function pickRandom<T>(values: readonly T[]): T;
+/**
+ * Picks a value from weighted candidates.
+ *
+ * @param items Weighted candidate items.
+ */
 declare function pickWeighted<T>(items: Array<IWeightedItem<T>>): T;
 //#endregion
 export { IWeightedItem, pickRandom, pickWeighted, randomFloat, randomInt };

package/dist/random.d.mts

@@ -1,11 +1,36 @@
 //#region src/random.d.ts
+/**
+ * A value paired with a non-negative selection weight.
+ */
 interface IWeightedItem<T> {
   value: T;
   weight: number;
 }
+/**
+ * Returns a random floating-point number in the half-open range `[min, max)`.
+ *
+ * @param min Lower bound.
+ * @param max Upper bound.
+ */
 declare function randomFloat(min?: number, max?: number): number;
+/**
+ * Returns a random integer in the inclusive range `[min, max]`.
+ *
+ * @param min Lower bound.
+ * @param max Upper bound.
+ */
 declare function randomInt(min: number, max: number): number;
+/**
+ * Picks a random element from a non-empty array.
+ *
+ * @param values Candidate values.
+ */
 declare function pickRandom<T>(values: readonly T[]): T;
+/**
+ * Picks a value from weighted candidates.
+ *
+ * @param items Weighted candidate items.
+ */
 declare function pickWeighted<T>(items: Array<IWeightedItem<T>>): T;
 //#endregion
 export { IWeightedItem, pickRandom, pickWeighted, randomFloat, randomInt };

package/dist/state.d.cts

@@ -76,10 +76,20 @@ declare class Flag extends ResettableValue<boolean> {
    */
   toggle(): void;
 }
+/**
+ * Creates a resettable lazy value accessor.
+ *
+ * @param factory Factory used to create the value.
+ */
 declare function resettableLazy<T>(factory: () => T): {
   get: () => T;
   reset: () => void;
 };
+/**
+ * Creates a resettable async lazy accessor.
+ *
+ * @param factory Async factory used to create the value.
+ */
 declare function resettableLazyAsync<T>(factory: () => Promise<T>): {
   get: () => Promise<T>;
   reset: () => void;

package/dist/state.d.mts

@@ -76,10 +76,20 @@ declare class Flag extends ResettableValue<boolean> {
    */
   toggle(): void;
 }
+/**
+ * Creates a resettable lazy value accessor.
+ *
+ * @param factory Factory used to create the value.
+ */
 declare function resettableLazy<T>(factory: () => T): {
   get: () => T;
   reset: () => void;
 };
+/**
+ * Creates a resettable async lazy accessor.
+ *
+ * @param factory Async factory used to create the value.
+ */
 declare function resettableLazyAsync<T>(factory: () => Promise<T>): {
   get: () => Promise<T>;
   reset: () => void;

package/dist/timing.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=function(e){return e[e.None=0]=`None`,e[e.Full=1]=`Full`,e[e.Equal=2]=`Equal`,e}({});function t(e){return new Promise(t=>setTimeout(t,e))}function n(e){return new Promise((t,n)=>setTimeout(n,e))}async function r(e,n=100,r=5e3){let i=Date.now();for(;!await e();){if(Date.now()-i>r)throw Error(`Timeout exceeded`);await t(n)}}async function i(e,t){let n;try{return await Promise.race([e,new Promise((e,r)=>{n=setTimeout(()=>r(Error(`Operation timed out`)),t)})])}finally{n!==void 0&&clearTimeout(n)}}function a(){let e=Error(`Aborted`);return e.name=`AbortError`,e}function o(e){if(e?.aborted)throw a()}async function s(e,t){if(e<=0){o(t);return}await new Promise((n,r)=>{let i=setTimeout(()=>{t&&t.removeEventListener(`abort`,o),n()},e);function o(){clearTimeout(i),t?.removeEventListener(`abort`,o),r(a())}t&&t.addEventListener(`abort`,o,{once:!0})})}function c(e){if(!Number.isFinite(e)||e<0)throw Error(`ms must be a finite number >= 0`);let t=new AbortController,n=setTimeout(()=>t.abort(),e);return t.signal.addEventListener(`abort`,()=>clearTimeout(n),{once:!0}),t.signal}function l(...e){let t=e.filter(e=>e!==void 0),n=new AbortController,r=new Map,i=()=>{if(!n.signal.aborted){n.abort();for(let[e,t]of r)e.removeEventListener(`abort`,t);r.clear()}};for(let e of t){if(e.aborted){i();break}let t=()=>i();r.set(e,t),e.addEventListener(`abort`,t,{once:!0})}return n.signal}async function u(e,t){return o(t),await new Promise((n,r)=>{function i(){t.removeEventListener(`abort`,i),r(a())}t.addEventListener(`abort`,i,{once:!0}),Promise.resolve(e).then(e=>{t.removeEventListener(`abort`,i),n(e)},e=>{t.removeEventListener(`abort`,i),r(e)})})}function d(t,n){return n===e.None?t:n===e.Full?Math.floor(Math.random()*t):Math.floor(t/2+t/2*Math.random())}async function f(t,n={}){let r=n.attempts??3,i=n.baseMs??100,a=n.maxMs??1/0,c=n.jitter??e.None;if(!Number.isInteger(r)||r<1)throw Error(`attempts must be an integer >= 1`);if(i<0||!Number.isFinite(i))throw Error(`baseMs must be a finite number >= 0`);if(a<0||Number.isNaN(a))throw Error(`maxMs must be a number >= 0`);for(let e=1;e<=r;e++){o(n.signal);try{return await t(e)}catch(t){if(e>=r||n.shouldRetry&&!await n.shouldRetry(t,e))throw t;await s(d(Math.min(i*2**(e-1),a),c),n.signal)}}throw Error(`Unreachable`)}exports.RetryJitter=e,exports.abortAfter=c,exports.pollUntil=r,exports.raceSignals=l,exports.rejectionTimeout=n,exports.retry=f,exports.timeout=t,exports.withAbort=u,exports.withTimeout=i;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=function(e){return e[e.None=0]=`None`,e[e.Full=1]=`Full`,e[e.Equal=2]=`Equal`,e}({});function t(e){return new Promise(t=>setTimeout(t,e))}function n(e){return new Promise((t,n)=>setTimeout(n,e))}async function r(e,n=100,r=5e3){let i=Date.now();for(;!await e();){if(Date.now()-i>r)throw Error(`Timeout exceeded`);await t(n)}}async function i(e,t){let n;try{return await Promise.race([e,new Promise((e,r)=>{n=setTimeout(()=>r(Error(`Operation timed out`)),t)})])}finally{n!==void 0&&clearTimeout(n)}}function a(e){if(!Number.isFinite(e)||e<0)throw Error(`ms must be a finite number >= 0`);let t=new AbortController,n=setTimeout(()=>t.abort(),e);return t.signal.addEventListener(`abort`,()=>clearTimeout(n),{once:!0}),t.signal}function o(...e){let t=e.filter(e=>e!==void 0),n=new AbortController,r=new Map,i=()=>{if(!n.signal.aborted){n.abort();for(let[e,t]of r)e.removeEventListener(`abort`,t);r.clear()}};for(let e of t){if(e.aborted){i();break}let t=()=>i();r.set(e,t),e.addEventListener(`abort`,t,{once:!0})}return n.signal}async function s(e,t){return u(t),await new Promise((n,r)=>{function i(){t.removeEventListener(`abort`,i),r(l())}t.addEventListener(`abort`,i,{once:!0}),Promise.resolve(e).then(e=>{t.removeEventListener(`abort`,i),n(e)},e=>{t.removeEventListener(`abort`,i),r(e)})})}async function c(t,n={}){let r=n.attempts??3,i=n.baseMs??100,a=n.maxMs??1/0,o=n.jitter??e.None;if(!Number.isInteger(r)||r<1)throw Error(`attempts must be an integer >= 1`);if(i<0||!Number.isFinite(i))throw Error(`baseMs must be a finite number >= 0`);if(a<0||Number.isNaN(a))throw Error(`maxMs must be a number >= 0`);for(let e=1;e<=r;e++){u(n.signal);try{return await t(e)}catch(t){if(e>=r||n.shouldRetry&&!await n.shouldRetry(t,e))throw t;await d(f(Math.min(i*2**(e-1),a),o),n.signal)}}throw Error(`Unreachable`)}function l(){let e=Error(`Aborted`);return e.name=`AbortError`,e}function u(e){if(e?.aborted)throw l()}async function d(e,t){if(e<=0){u(t);return}await new Promise((n,r)=>{let i=setTimeout(()=>{t&&t.removeEventListener(`abort`,a),n()},e);function a(){clearTimeout(i),t?.removeEventListener(`abort`,a),r(l())}t&&t.addEventListener(`abort`,a,{once:!0})})}function f(t,n){return n===e.None?t:n===e.Full?Math.floor(Math.random()*t):Math.floor(t/2+t/2*Math.random())}exports.RetryJitter=e,exports.abortAfter=a,exports.pollUntil=r,exports.raceSignals=o,exports.rejectionTimeout=n,exports.retry=c,exports.timeout=t,exports.withAbort=s,exports.withTimeout=i;

package/dist/timing.d.cts

@@ -1,6 +1,9 @@
-import { Awaitable } from "./typing.cjs";
+import { Awaitable, Maybe } from "./typing.cjs";
 
 //#region src/timing.d.ts
+/**
+ * Options for {@link retry}.
+ */
 interface IRetryOptions {
   attempts?: number;
   baseMs?: number;
@@ -9,6 +12,9 @@ interface IRetryOptions {
   signal?: AbortSignal;
   shouldRetry?: (error: unknown, attempt: number) => Awaitable<boolean>;
 }
+/**
+ * Jitter strategies for retry delays.
+ */
 declare const enum RetryJitter {
   None = 0,
   Full = 1,
@@ -52,7 +58,7 @@ declare function abortAfter(ms: number): AbortSignal;
  *
  * @param signals Input abort signals.
  */
-declare function raceSignals(...signals: Array<AbortSignal | undefined>): AbortSignal;
+declare function raceSignals(...signals: Array<Maybe<AbortSignal>>): AbortSignal;
 /**
  * Wraps a promise and rejects when the signal aborts before completion.
  *

package/dist/timing.d.mts

@@ -1,6 +1,9 @@
-import { Awaitable } from "./typing.mjs";
+import { Awaitable, Maybe } from "./typing.mjs";
 
 //#region src/timing.d.ts
+/**
+ * Options for {@link retry}.
+ */
 interface IRetryOptions {
   attempts?: number;
   baseMs?: number;
@@ -9,6 +12,9 @@ interface IRetryOptions {
   signal?: AbortSignal;
   shouldRetry?: (error: unknown, attempt: number) => Awaitable<boolean>;
 }
+/**
+ * Jitter strategies for retry delays.
+ */
 declare const enum RetryJitter {
   None = 0,
   Full = 1,
@@ -52,7 +58,7 @@ declare function abortAfter(ms: number): AbortSignal;
  *
  * @param signals Input abort signals.
  */
-declare function raceSignals(...signals: Array<AbortSignal | undefined>): AbortSignal;
+declare function raceSignals(...signals: Array<Maybe<AbortSignal>>): AbortSignal;
 /**
  * Wraps a promise and rejects when the signal aborts before completion.
  *

package/dist/timing.mjs

@@ -1 +1 @@
-let e=function(e){return e[e.None=0]=`None`,e[e.Full=1]=`Full`,e[e.Equal=2]=`Equal`,e}({});function t(e){return new Promise(t=>setTimeout(t,e))}function n(e){return new Promise((t,n)=>setTimeout(n,e))}async function r(e,n=100,r=5e3){let i=Date.now();for(;!await e();){if(Date.now()-i>r)throw Error(`Timeout exceeded`);await t(n)}}async function i(e,t){let n;try{return await Promise.race([e,new Promise((e,r)=>{n=setTimeout(()=>r(Error(`Operation timed out`)),t)})])}finally{n!==void 0&&clearTimeout(n)}}function a(){let e=Error(`Aborted`);return e.name=`AbortError`,e}function o(e){if(e?.aborted)throw a()}async function s(e,t){if(e<=0){o(t);return}await new Promise((n,r)=>{let i=setTimeout(()=>{t&&t.removeEventListener(`abort`,o),n()},e);function o(){clearTimeout(i),t?.removeEventListener(`abort`,o),r(a())}t&&t.addEventListener(`abort`,o,{once:!0})})}function c(e){if(!Number.isFinite(e)||e<0)throw Error(`ms must be a finite number >= 0`);let t=new AbortController,n=setTimeout(()=>t.abort(),e);return t.signal.addEventListener(`abort`,()=>clearTimeout(n),{once:!0}),t.signal}function l(...e){let t=e.filter(e=>e!==void 0),n=new AbortController,r=new Map,i=()=>{if(!n.signal.aborted){n.abort();for(let[e,t]of r)e.removeEventListener(`abort`,t);r.clear()}};for(let e of t){if(e.aborted){i();break}let t=()=>i();r.set(e,t),e.addEventListener(`abort`,t,{once:!0})}return n.signal}async function u(e,t){return o(t),await new Promise((n,r)=>{function i(){t.removeEventListener(`abort`,i),r(a())}t.addEventListener(`abort`,i,{once:!0}),Promise.resolve(e).then(e=>{t.removeEventListener(`abort`,i),n(e)},e=>{t.removeEventListener(`abort`,i),r(e)})})}function d(t,n){return n===e.None?t:n===e.Full?Math.floor(Math.random()*t):Math.floor(t/2+t/2*Math.random())}async function f(t,n={}){let r=n.attempts??3,i=n.baseMs??100,a=n.maxMs??1/0,c=n.jitter??e.None;if(!Number.isInteger(r)||r<1)throw Error(`attempts must be an integer >= 1`);if(i<0||!Number.isFinite(i))throw Error(`baseMs must be a finite number >= 0`);if(a<0||Number.isNaN(a))throw Error(`maxMs must be a number >= 0`);for(let e=1;e<=r;e++){o(n.signal);try{return await t(e)}catch(t){if(e>=r||n.shouldRetry&&!await n.shouldRetry(t,e))throw t;await s(d(Math.min(i*2**(e-1),a),c),n.signal)}}throw Error(`Unreachable`)}export{e as RetryJitter,c as abortAfter,r as pollUntil,l as raceSignals,n as rejectionTimeout,f as retry,t as timeout,u as withAbort,i as withTimeout};
+let e=function(e){return e[e.None=0]=`None`,e[e.Full=1]=`Full`,e[e.Equal=2]=`Equal`,e}({});function t(e){return new Promise(t=>setTimeout(t,e))}function n(e){return new Promise((t,n)=>setTimeout(n,e))}async function r(e,n=100,r=5e3){let i=Date.now();for(;!await e();){if(Date.now()-i>r)throw Error(`Timeout exceeded`);await t(n)}}async function i(e,t){let n;try{return await Promise.race([e,new Promise((e,r)=>{n=setTimeout(()=>r(Error(`Operation timed out`)),t)})])}finally{n!==void 0&&clearTimeout(n)}}function a(e){if(!Number.isFinite(e)||e<0)throw Error(`ms must be a finite number >= 0`);let t=new AbortController,n=setTimeout(()=>t.abort(),e);return t.signal.addEventListener(`abort`,()=>clearTimeout(n),{once:!0}),t.signal}function o(...e){let t=e.filter(e=>e!==void 0),n=new AbortController,r=new Map,i=()=>{if(!n.signal.aborted){n.abort();for(let[e,t]of r)e.removeEventListener(`abort`,t);r.clear()}};for(let e of t){if(e.aborted){i();break}let t=()=>i();r.set(e,t),e.addEventListener(`abort`,t,{once:!0})}return n.signal}async function s(e,t){return u(t),await new Promise((n,r)=>{function i(){t.removeEventListener(`abort`,i),r(l())}t.addEventListener(`abort`,i,{once:!0}),Promise.resolve(e).then(e=>{t.removeEventListener(`abort`,i),n(e)},e=>{t.removeEventListener(`abort`,i),r(e)})})}async function c(t,n={}){let r=n.attempts??3,i=n.baseMs??100,a=n.maxMs??1/0,o=n.jitter??e.None;if(!Number.isInteger(r)||r<1)throw Error(`attempts must be an integer >= 1`);if(i<0||!Number.isFinite(i))throw Error(`baseMs must be a finite number >= 0`);if(a<0||Number.isNaN(a))throw Error(`maxMs must be a number >= 0`);for(let e=1;e<=r;e++){u(n.signal);try{return await t(e)}catch(t){if(e>=r||n.shouldRetry&&!await n.shouldRetry(t,e))throw t;await d(f(Math.min(i*2**(e-1),a),o),n.signal)}}throw Error(`Unreachable`)}function l(){let e=Error(`Aborted`);return e.name=`AbortError`,e}function u(e){if(e?.aborted)throw l()}async function d(e,t){if(e<=0){u(t);return}await new Promise((n,r)=>{let i=setTimeout(()=>{t&&t.removeEventListener(`abort`,a),n()},e);function a(){clearTimeout(i),t?.removeEventListener(`abort`,a),r(l())}t&&t.addEventListener(`abort`,a,{once:!0})})}function f(t,n){return n===e.None?t:n===e.Full?Math.floor(Math.random()*t):Math.floor(t/2+t/2*Math.random())}export{e as RetryJitter,a as abortAfter,r as pollUntil,o as raceSignals,n as rejectionTimeout,c as retry,t as timeout,s as withAbort,i as withTimeout};

package/dist/typing.d.cts

@@ -1,9 +1,27 @@
 //#region src/typing.d.ts
+/**
+ * A value or a promise-like value.
+ */
 type Awaitable<T> = PromiseLike<T> | T;
+/**
+ * A value that may be `undefined`.
+ */
 type Maybe<T> = T | undefined;
+/**
+ * A value that may be `null`.
+ */
 type Nullable<T> = T | null;
+/**
+ * A single value or an array of values.
+ */
 type Arrayable<T> = T | Array<T>;
+/**
+ * Flattens mapped/intersection display in editor tooltips.
+ */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Discriminated result type for success/failure operations.
+ */
 type Result<T, E = unknown> = {
   ok: true;
   value: T;
@@ -11,19 +29,83 @@ type Result<T, E = unknown> = {
   ok: false;
   error: E;
 };
+/**
+ * A generic function type.
+ */
+type Fn<Return = void, Args extends unknown[] = unknown[]> = (...args: Args) => Return;
+/**
+ * A generic function type that may return either a value or a promise-like value.
+ */
+type AwaitableFn<Return = void, Args extends unknown[] = unknown[]> = (...args: Args) => Awaitable<Return>;
+/**
+ * Class constructor type.
+ */
 type Class<T, Args extends unknown[] = any[]> = new (...args: Args) => T;
+/**
+ * Recasts a value to a wider target type without runtime transformation.
+ *
+ * @param value Input value.
+ */
 declare const cast: <T, U extends T>(value: U) => U;
+/**
+ * Asserts an unknown value as type `T` at compile time.
+ *
+ * @param value Value to assert.
+ */
 declare function assume<T>(value: unknown): asserts value is T;
+/**
+ * Returns strongly typed `Object.entries` output.
+ *
+ * @param obj Object to enumerate.
+ */
 declare function typedEntries<T extends object>(obj: T): { [K in keyof T]: [K, T[K]] }[keyof T][];
+/**
+ * Creates a successful {@link Result}.
+ *
+ * @param value Success value.
+ */
 declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Creates a failed {@link Result}.
+ *
+ * @param error Failure value.
+ */
 declare function err<E>(error: E): Result<never, E>;
+/**
+ * Type guard for successful {@link Result} values.
+ *
+ * @param result Result to check.
+ */
 declare function isOk<T, E>(result: Result<T, E>): result is {
   ok: true;
   value: T;
 };
+/**
+ * Maps only the success branch of a {@link Result}.
+ *
+ * @param result Result to map.
+ * @param mapper Success mapper.
+ */
 declare function mapOk<T, U, E>(result: Result<T, E>, mapper: (value: T) => U): Result<U, E>;
+/**
+ * Maps only the error branch of a {@link Result}.
+ *
+ * @param result Result to map.
+ * @param mapper Error mapper.
+ */
 declare function mapErr<T, E, F>(result: Result<T, E>, mapper: (error: E) => F): Result<T, F>;
+/**
+ * Runs an async operation and converts thrown errors into a failed {@link Result}.
+ *
+ * @param operation Async operation to execute.
+ */
 declare function tryCatchAsync<T>(operation: () => Awaitable<T>): Promise<Result<T, unknown>>;
+/**
+ * Runs an async operation and maps thrown errors into a custom error type.
+ *
+ * @param operation Async operation to execute.
+ * @param mapError Error mapper.
+ */
 declare function tryCatchAsync<T, E>(operation: () => Awaitable<T>, mapError: (error: unknown) => E): Promise<Result<T, E>>;
 //#endregion
-export { Arrayable, Awaitable, Class, Maybe, Nullable, Prettify, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries };
+export { Arrayable, Awaitable, AwaitableFn, Class, Fn, Maybe, Nullable, Prettify, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries };

package/dist/typing.d.mts

@@ -1,9 +1,27 @@
 //#region src/typing.d.ts
+/**
+ * A value or a promise-like value.
+ */
 type Awaitable<T> = PromiseLike<T> | T;
+/**
+ * A value that may be `undefined`.
+ */
 type Maybe<T> = T | undefined;
+/**
+ * A value that may be `null`.
+ */
 type Nullable<T> = T | null;
+/**
+ * A single value or an array of values.
+ */
 type Arrayable<T> = T | Array<T>;
+/**
+ * Flattens mapped/intersection display in editor tooltips.
+ */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Discriminated result type for success/failure operations.
+ */
 type Result<T, E = unknown> = {
   ok: true;
   value: T;
@@ -11,19 +29,83 @@ type Result<T, E = unknown> = {
   ok: false;
   error: E;
 };
+/**
+ * A generic function type.
+ */
+type Fn<Return = void, Args extends unknown[] = unknown[]> = (...args: Args) => Return;
+/**
+ * A generic function type that may return either a value or a promise-like value.
+ */
+type AwaitableFn<Return = void, Args extends unknown[] = unknown[]> = (...args: Args) => Awaitable<Return>;
+/**
+ * Class constructor type.
+ */
 type Class<T, Args extends unknown[] = any[]> = new (...args: Args) => T;
+/**
+ * Recasts a value to a wider target type without runtime transformation.
+ *
+ * @param value Input value.
+ */
 declare const cast: <T, U extends T>(value: U) => U;
+/**
+ * Asserts an unknown value as type `T` at compile time.
+ *
+ * @param value Value to assert.
+ */
 declare function assume<T>(value: unknown): asserts value is T;
+/**
+ * Returns strongly typed `Object.entries` output.
+ *
+ * @param obj Object to enumerate.
+ */
 declare function typedEntries<T extends object>(obj: T): { [K in keyof T]: [K, T[K]] }[keyof T][];
+/**
+ * Creates a successful {@link Result}.
+ *
+ * @param value Success value.
+ */
 declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Creates a failed {@link Result}.
+ *
+ * @param error Failure value.
+ */
 declare function err<E>(error: E): Result<never, E>;
+/**
+ * Type guard for successful {@link Result} values.
+ *
+ * @param result Result to check.
+ */
 declare function isOk<T, E>(result: Result<T, E>): result is {
   ok: true;
   value: T;
 };
+/**
+ * Maps only the success branch of a {@link Result}.
+ *
+ * @param result Result to map.
+ * @param mapper Success mapper.
+ */
 declare function mapOk<T, U, E>(result: Result<T, E>, mapper: (value: T) => U): Result<U, E>;
+/**
+ * Maps only the error branch of a {@link Result}.
+ *
+ * @param result Result to map.
+ * @param mapper Error mapper.
+ */
 declare function mapErr<T, E, F>(result: Result<T, E>, mapper: (error: E) => F): Result<T, F>;
+/**
+ * Runs an async operation and converts thrown errors into a failed {@link Result}.
+ *
+ * @param operation Async operation to execute.
+ */
 declare function tryCatchAsync<T>(operation: () => Awaitable<T>): Promise<Result<T, unknown>>;
+/**
+ * Runs an async operation and maps thrown errors into a custom error type.
+ *
+ * @param operation Async operation to execute.
+ * @param mapError Error mapper.
+ */
 declare function tryCatchAsync<T, E>(operation: () => Awaitable<T>, mapError: (error: unknown) => E): Promise<Result<T, E>>;
 //#endregion
-export { Arrayable, Awaitable, Class, Maybe, Nullable, Prettify, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries };
+export { Arrayable, Awaitable, AwaitableFn, Class, Fn, Maybe, Nullable, Prettify, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries };

package/dist/url.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,...t){let n=``;for(let r=0;r<e.length;r++)n+=e[r],r<t.length&&(n+=encodeURIComponent(String(t[r])));return n}function t(e,n,r){if(r!=null){if(Array.isArray(r)){for(let i of r)t(e,n,i);return}if(typeof r==`object`){try{e.append(n,JSON.stringify(r))}catch{e.append(n,String(r))}return}e.append(n,String(r))}}var n=class e{#e;constructor(t,n){t instanceof e||t instanceof URL?this.#e=new URL(t.toString()):n?this.#e=new URL(t,n.toString()):this.#e=new URL(t)}get protocol(){return this.#e.protocol}get host(){return this.#e.host}get hostname(){return this.#e.hostname}get port(){return this.#e.port}get origin(){return this.#e.origin}get username(){return this.#e.username}get password(){return this.#e.password}get hash(){return this.#e.hash}get search(){return this.#e.search}get searchParams(){return new URLSearchParams(this.#e.search)}get pathname(){return this.#e.pathname}get parts(){return this.#e.pathname.split(`/`).filter(Boolean).map(decodeURIComponent)}get name(){return this.parts.at(-1)??``}get suffix(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(t):``}get stem(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(0,t):e}get parent(){let e=this.parts.slice(0,-1);return this.withPath(e)}joinpath(...e){let t=[...this.parts,...e.map(e=>e.replace(/^\/+|\/+$/g,``))];return this.withPath(t)}div(...e){return this.joinpath(...e)}withPath(t){let n=new URL(this.#e.toString());return n.pathname=`/`+t.map(encodeURIComponent).join(`/`),new e(n)}withQuery(n){let r=new URL(this.#e.toString());for(let[e,i]of Object.entries(n))r.searchParams.delete(e),t(r.searchParams,e,i);return new e(r)}withQueryPatch(e){return this.withQuery(e)}appendQuery(n){let r=new URL(this.#e.toString());for(let[e,i]of Object.entries(n))t(r.searchParams,e,i);return new e(r)}withoutEmptyQuery(){let t=new URL(this.#e.toString()),n=new Set;for(let e of t.searchParams.keys())n.has(e)||(n.add(e),t.searchParams.getAll(e).every(e=>e===``)&&t.searchParams.delete(e));return new e(t)}withoutQuery(...t){let n=new URL(this.#e.toString());for(let e of t)n.searchParams.delete(e);return new e(n)}withHash(t){let n=new URL(this.#e.toString());return n.hash=t.startsWith(`#`)?t:`#${t}`,new e(n)}withoutHash(){let t=new URL(this.#e.toString());return t.hash=``,new e(t)}async fetch(e){return fetch(this.#e,e)}resolve(t){return new e(t,this)}equals(t){return this.toString()===new e(t).toString()}toURL(){return new URL(this.#e.toString())}toString(){return this.#e.toString()}valueOf(){return this.toString()}[Symbol.toPrimitive](){return this.toString()}static from(t,n){return new e(t,n)}static parse(t){return new e(t)}};exports.URLPath=n,exports.url=e;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,...t){let n=``;for(let r=0;r<e.length;r++)n+=e[r],r<t.length&&(n+=encodeURIComponent(String(t[r])));return n}var t=class e{#e;constructor(t,n){t instanceof e||t instanceof URL?this.#e=new URL(t.toString()):n?this.#e=new URL(t,n.toString()):this.#e=new URL(t)}get protocol(){return this.#e.protocol}get host(){return this.#e.host}get hostname(){return this.#e.hostname}get port(){return this.#e.port}get origin(){return this.#e.origin}get username(){return this.#e.username}get password(){return this.#e.password}get hash(){return this.#e.hash}get search(){return this.#e.search}get searchParams(){return new URLSearchParams(this.#e.search)}get pathname(){return this.#e.pathname}get parts(){return this.#e.pathname.split(`/`).filter(Boolean).map(decodeURIComponent)}get name(){return this.parts.at(-1)??``}get suffix(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(t):``}get stem(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(0,t):e}get parent(){let e=this.parts.slice(0,-1);return this.withPath(e)}joinpath(...e){let t=[...this.parts,...e.map(e=>e.replace(/^\/+|\/+$/g,``))];return this.withPath(t)}div(...e){return this.joinpath(...e)}withPath(t){let n=new URL(this.#e.toString());return n.pathname=`/`+t.map(encodeURIComponent).join(`/`),new e(n)}withQuery(t){let n=new URL(this.#e.toString());for(let[e,r]of Object.entries(t))n.searchParams.delete(e),this.appendQueryValue(n.searchParams,e,r);return new e(n)}withQueryPatch(e){return this.withQuery(e)}appendQuery(t){let n=new URL(this.#e.toString());for(let[e,r]of Object.entries(t))this.appendQueryValue(n.searchParams,e,r);return new e(n)}withoutEmptyQuery(){let t=new URL(this.#e.toString()),n=new Set;for(let e of t.searchParams.keys())n.has(e)||(n.add(e),t.searchParams.getAll(e).every(e=>e===``)&&t.searchParams.delete(e));return new e(t)}withoutQuery(...t){let n=new URL(this.#e.toString());for(let e of t)n.searchParams.delete(e);return new e(n)}withHash(t){let n=new URL(this.#e.toString());return n.hash=t.startsWith(`#`)?t:`#${t}`,new e(n)}withoutHash(){let t=new URL(this.#e.toString());return t.hash=``,new e(t)}async fetch(e){return fetch(this.#e,e)}resolve(t){return new e(t,this)}equals(t){return this.toString()===new e(t).toString()}toURL(){return new URL(this.#e.toString())}toString(){return this.#e.toString()}valueOf(){return this.toString()}[Symbol.toPrimitive](){return this.toString()}static from(t,n){return new e(t,n)}static parse(t){return new e(t)}appendQueryValue(e,t,n){if(n!=null){if(Array.isArray(n)){for(let r of n)this.appendQueryValue(e,t,r);return}if(typeof n==`object`){try{e.append(t,JSON.stringify(n))}catch{e.append(t,String(n))}return}e.append(t,String(n))}}};exports.URLPath=t,exports.url=e;

package/dist/url.d.cts

@@ -1,6 +1,15 @@
 //#region src/url.d.ts
+/**
+ * Values accepted by {@link URLPath} constructors and helpers.
+ */
 type URLLike = string | URL | URLPath;
+/**
+ * A single query parameter value (including nested and array values).
+ */
 type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
+/**
+ * Query-object shape used by URL query mutation helpers.
+ */
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
 /**
  * Tagged-template helper for encoded URL path segments.
@@ -9,44 +18,186 @@ type QueryObject = Record<string, QueryValue | QueryValue[]>;
  * const path = url`/users/${userId}/posts/${postId}`;
  */
 declare function url(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Immutable URL utility wrapper with convenience path/query operations.
+ */
 declare class URLPath {
   #private;
+  /**
+   * Creates a `URLPath` from a URL-like input and optional base URL.
+   *
+   * @param input URL value to parse.
+   * @param base Optional base URL for relative inputs.
+   */
   constructor(input: URLLike, base?: URLLike);
+  /**
+   * URL protocol including trailing `:`.
+   */
   get protocol(): string;
+  /**
+   * Host including port when present.
+   */
   get host(): string;
+  /**
+   * Hostname without port.
+   */
   get hostname(): string;
+  /**
+   * Port component, or an empty string when absent.
+   */
   get port(): string;
+  /**
+   * URL origin (`protocol + // + host`).
+   */
   get origin(): string;
+  /**
+   * Username component.
+   */
   get username(): string;
+  /**
+   * Password component.
+   */
   get password(): string;
+  /**
+   * Hash fragment including leading `#` when present.
+   */
   get hash(): string;
+  /**
+   * Search component including leading `?` when present.
+   */
   get search(): string;
+  /**
+   * Returns a copy of query parameters.
+   */
   get searchParams(): URLSearchParams;
+  /**
+   * URL pathname component.
+   */
   get pathname(): string;
+  /**
+   * Decoded pathname segments without empty parts.
+   */
   get parts(): string[];
+  /**
+   * Final path segment (decoded).
+   */
   get name(): string;
+  /**
+   * File suffix from {@link name}, including the leading dot.
+   */
   get suffix(): string;
+  /**
+   * File name without suffix from {@link name}.
+   */
   get stem(): string;
+  /**
+   * Parent path with the last path segment removed.
+   */
   get parent(): URLPath;
+  /**
+   * Appends path segments and returns a new URL.
+   *
+   * @param segments Segments to append.
+   */
   joinpath(...segments: string[]): URLPath;
+  /**
+   * Alias of {@link joinpath}.
+   *
+   * @param segments Segments to append.
+   */
   div(...segments: string[]): URLPath;
+  /**
+   * Creates a copy with replaced pathname parts.
+   *
+   * @param parts Decoded path parts.
+   */
   private withPath;
+  /**
+   * Replaces query parameter values for the provided keys.
+   *
+   * @param params Query values to set.
+   */
   withQuery(params: QueryObject): URLPath;
+  /**
+   * Alias of {@link withQuery}.
+   *
+   * @param params Query values to set.
+   */
   withQueryPatch(params: QueryObject): URLPath;
+  /**
+   * Appends query parameter values without deleting existing values.
+   *
+   * @param params Query values to append.
+   */
   appendQuery(params: QueryObject): URLPath;
+  /**
+   * Removes query keys whose values are entirely empty strings.
+   */
   withoutEmptyQuery(): URLPath;
+  /**
+   * Removes selected query keys.
+   *
+   * @param keys Query keys to remove.
+   */
   withoutQuery(...keys: string[]): URLPath;
+  /**
+   * Sets the hash fragment and returns a new URL.
+   *
+   * @param hash Hash value with or without leading `#`.
+   */
   withHash(hash: string): URLPath;
+  /**
+   * Removes the hash fragment.
+   */
   withoutHash(): URLPath;
+  /**
+   * Calls global `fetch` with this URL as input.
+   *
+   * @param init Optional fetch options.
+   */
   fetch(init?: RequestInit): Promise<Response>;
+  /**
+   * Resolves a relative URL against this URL.
+   *
+   * @param relative Relative URL/path.
+   */
   resolve(relative: string): URLPath;
+  /**
+   * Compares URLs by normalized string value.
+   *
+   * @param other URL to compare.
+   */
   equals(other: URLLike): boolean;
+  /**
+   * Returns a new native `URL` instance.
+   */
   toURL(): URL;
+  /**
+   * Returns the URL as a string.
+   */
   toString(): string;
+  /**
+   * Primitive value representation.
+   */
   valueOf(): string;
+  /**
+   * Primitive coercion hook.
+   */
   [Symbol.toPrimitive](): string;
+  /**
+   * Creates a `URLPath` from URL-like input.
+   *
+   * @param input URL value to parse.
+   * @param base Optional base URL for relative inputs.
+   */
   static from(input: URLLike, base?: URLLike): URLPath;
+  /**
+   * Parses an absolute URL string.
+   *
+   * @param input URL string to parse.
+   */
   static parse(input: string): URLPath;
+  private appendQueryValue;
 }
 //#endregion
 export { QueryObject, QueryValue, URLLike, URLPath, url };