@depthbomb/common 1.3.1 → 2.0.0

package/dist/promise.d.cts

@@ -0,0 +1,48 @@
+import { Awaitable } from "./typing.cjs";
+
+//#region src/promise.d.ts
+interface IConcurrencyOptions {
+  concurrency?: number;
+}
+/**
+ * Waits for all promises to settle and returns an array of successful results.
+ *
+ * @param promises An array of promises to wait for
+ * @returns A promise that resolves to an array of successful results
+ */
+declare function allSettledSuccessful<T>(promises: Array<Awaitable<T>>): Promise<T[]>;
+interface SettledDetailed<T> {
+  results: Array<PromiseSettledResult<T>>;
+  fulfilled: T[];
+  rejected: unknown[];
+}
+/**
+ * Waits for all values to settle and returns full settled results plus split fulfilled/rejected lists.
+ *
+ * @param promises Values or promises to settle.
+ */
+declare function allSettledDetailed<T>(promises: Array<Awaitable<T>>): Promise<SettledDetailed<T>>;
+/**
+ * Executes an array of asynchronous tasks sequentially.
+ *
+ * @param tasks An array of functions that return promises
+ * @returns A promise that resolves to an array of results from the input tasks
+ */
+declare function sequential<T>(tasks: Array<() => Awaitable<T>>): Promise<T[]>;
+/**
+ * Runs asynchronous tasks with a concurrency limit while preserving result order.
+ *
+ * @param tasks Task functions to execute.
+ * @param options Concurrency options.
+ */
+declare function pool<T>(tasks: Array<() => Awaitable<T>>, options?: IConcurrencyOptions): Promise<T[]>;
+/**
+ * Maps values using an async mapper with a concurrency limit.
+ *
+ * @param values Input values.
+ * @param mapper Mapping function.
+ * @param options Concurrency options.
+ */
+declare function pMap<T, U>(values: Iterable<T>, mapper: (value: T, index: number) => Awaitable<U>, options?: IConcurrencyOptions): Promise<U[]>;
+//#endregion
+export { IConcurrencyOptions, SettledDetailed, allSettledDetailed, allSettledSuccessful, pMap, pool, sequential };

package/dist/promise.d.mts

@@ -0,0 +1,48 @@
+import { Awaitable } from "./typing.mjs";
+
+//#region src/promise.d.ts
+interface IConcurrencyOptions {
+  concurrency?: number;
+}
+/**
+ * Waits for all promises to settle and returns an array of successful results.
+ *
+ * @param promises An array of promises to wait for
+ * @returns A promise that resolves to an array of successful results
+ */
+declare function allSettledSuccessful<T>(promises: Array<Awaitable<T>>): Promise<T[]>;
+interface SettledDetailed<T> {
+  results: Array<PromiseSettledResult<T>>;
+  fulfilled: T[];
+  rejected: unknown[];
+}
+/**
+ * Waits for all values to settle and returns full settled results plus split fulfilled/rejected lists.
+ *
+ * @param promises Values or promises to settle.
+ */
+declare function allSettledDetailed<T>(promises: Array<Awaitable<T>>): Promise<SettledDetailed<T>>;
+/**
+ * Executes an array of asynchronous tasks sequentially.
+ *
+ * @param tasks An array of functions that return promises
+ * @returns A promise that resolves to an array of results from the input tasks
+ */
+declare function sequential<T>(tasks: Array<() => Awaitable<T>>): Promise<T[]>;
+/**
+ * Runs asynchronous tasks with a concurrency limit while preserving result order.
+ *
+ * @param tasks Task functions to execute.
+ * @param options Concurrency options.
+ */
+declare function pool<T>(tasks: Array<() => Awaitable<T>>, options?: IConcurrencyOptions): Promise<T[]>;
+/**
+ * Maps values using an async mapper with a concurrency limit.
+ *
+ * @param values Input values.
+ * @param mapper Mapping function.
+ * @param options Concurrency options.
+ */
+declare function pMap<T, U>(values: Iterable<T>, mapper: (value: T, index: number) => Awaitable<U>, options?: IConcurrencyOptions): Promise<U[]>;
+//#endregion
+export { IConcurrencyOptions, SettledDetailed, allSettledDetailed, allSettledSuccessful, pMap, pool, sequential };

package/dist/promise.mjs

@@ -0,0 +1 @@
+async function e(e){return(await Promise.allSettled(e)).filter(e=>e.status===`fulfilled`).map(e=>e.value)}async function t(e){let t=await Promise.allSettled(e),n=[],r=[];for(let e of t){if(e.status===`fulfilled`){n.push(e.value);continue}r.push(e.reason)}return{results:t,fulfilled:n,rejected:r}}async function n(e){let t=[];for(let n of e)t.push(await n());return t}function r(e){if(!Number.isInteger(e)||e<1)throw Error(`concurrency must be an integer >= 1`);return e}async function i(e,t={}){if(e.length===0)return[];let n=r(t.concurrency??e.length),i=Array(e.length),a=0;async function o(){for(;;){let t=a++;if(t>=e.length)return;i[t]=await e[t]()}}let s=Math.min(n,e.length),c=Array.from({length:s},()=>o());return await Promise.all(c),i}async function a(e,t,n={}){let r=[],a=0;for(let n of e){let e=a++;r.push(()=>t(n,e))}return i(r,n)}export{t as allSettledDetailed,e as allSettledSuccessful,a as pMap,i as pool,n as sequential};

package/dist/random.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t){if(!Number.isFinite(e)||!Number.isFinite(t))throw Error(`min and max must be finite numbers`);if(e>t)throw Error(`min must be <= max`)}function t(t=0,n=1){return e(t,n),Math.random()*(n-t)+t}function n(n,r){if(!Number.isInteger(n)||!Number.isInteger(r))throw Error(`min and max must be integers`);return e(n,r),Math.floor(t(n,r+1))}function r(e){if(e.length===0)throw Error(`cannot pick from empty array`);return e[n(0,e.length-1)]}function i(e){if(e.length===0)throw Error(`cannot pick from empty weighted items`);let n=0;for(let t of e){if(!Number.isFinite(t.weight)||t.weight<0)throw Error(`weights must be finite numbers >= 0`);n+=t.weight}if(n<=0)throw Error(`total weight must be > 0`);let r=t(0,n);for(let t of e)if(r-=t.weight,r<=0)return t.value;return e[e.length-1].value}exports.pickRandom=r,exports.pickWeighted=i,exports.randomFloat=t,exports.randomInt=n;

package/dist/random.d.cts

@@ -0,0 +1,11 @@
+//#region src/random.d.ts
+interface IWeightedItem<T> {
+  value: T;
+  weight: number;
+}
+declare function randomFloat(min?: number, max?: number): number;
+declare function randomInt(min: number, max: number): number;
+declare function pickRandom<T>(values: readonly T[]): T;
+declare function pickWeighted<T>(items: Array<IWeightedItem<T>>): T;
+//#endregion
+export { IWeightedItem, pickRandom, pickWeighted, randomFloat, randomInt };

package/dist/random.d.mts

@@ -0,0 +1,11 @@
+//#region src/random.d.ts
+interface IWeightedItem<T> {
+  value: T;
+  weight: number;
+}
+declare function randomFloat(min?: number, max?: number): number;
+declare function randomInt(min: number, max: number): number;
+declare function pickRandom<T>(values: readonly T[]): T;
+declare function pickWeighted<T>(items: Array<IWeightedItem<T>>): T;
+//#endregion
+export { IWeightedItem, pickRandom, pickWeighted, randomFloat, randomInt };

package/dist/random.mjs

@@ -0,0 +1 @@
+function e(e,t){if(!Number.isFinite(e)||!Number.isFinite(t))throw Error(`min and max must be finite numbers`);if(e>t)throw Error(`min must be <= max`)}function t(t=0,n=1){return e(t,n),Math.random()*(n-t)+t}function n(n,r){if(!Number.isInteger(n)||!Number.isInteger(r))throw Error(`min and max must be integers`);return e(n,r),Math.floor(t(n,r+1))}function r(e){if(e.length===0)throw Error(`cannot pick from empty array`);return e[n(0,e.length-1)]}function i(e){if(e.length===0)throw Error(`cannot pick from empty weighted items`);let n=0;for(let t of e){if(!Number.isFinite(t.weight)||t.weight<0)throw Error(`weights must be finite numbers >= 0`);n+=t.weight}if(n<=0)throw Error(`total weight must be > 0`);let r=t(0,n);for(let t of e)if(r-=t.weight,r<=0)return t.value;return e[e.length-1].value}export{r as pickRandom,i as pickWeighted,t as randomFloat,n as randomInt};

package/dist/state.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class{value;#e;constructor(e){this.value=e,this.#e=e}set(e){this.value=e}reset(){this.value=this.#e}valueOf(){return this.value}toString(){return String(this.value)}},t=class extends e{constructor(e=!1){super(e)}get isTrue(){return this.value===!0}get isFalse(){return!this.isTrue}set(e){super.set(e)}setTrue(){this.value=!0}setFalse(){this.value=!1}toggle(){this.value=!this.value}};function n(e){let t,n=!1;function r(){return n||=(t=e(),!0),t}function i(){n=!1,t=void 0}return{get:r,reset:i}}function r(e){let t;function n(){return t||=e().catch(e=>{throw t=void 0,e}),t}function r(){t=void 0}return{get:n,reset:r}}exports.Flag=t,exports.ResettableValue=e,exports.resettableLazy=n,exports.resettableLazyAsync=r;

package/dist/state.d.cts

@@ -0,0 +1,88 @@
+//#region src/state.d.ts
+/**
+ * Holds a mutable value and remembers its initial value so it can be restored.
+ *
+ * @typeParam T Type of the held value.
+ */
+declare class ResettableValue<T> {
+  #private;
+  /**
+   * The current value.
+   */
+  value: T;
+  /**
+   * Create a resettable value.
+   *
+   * @param value Initial value to store and reset back to.
+   */
+  constructor(value: T);
+  /**
+   * Set the current value.
+   *
+   * @param value New value to assign.
+   */
+  set(value: T): void;
+  /**
+   * Restore the value back to its initial constructor value.
+   */
+  reset(): void;
+  /**
+   * Return the current value for primitive coercion.
+   *
+   * @returns The current value.
+   */
+  valueOf(): T;
+  /**
+   * Convert the current value to a string.
+   *
+   * @returns The string representation of the current value.
+   */
+  toString(): string;
+}
+/**
+ * A resettable boolean helper with convenience setters and state checks.
+ */
+declare class Flag extends ResettableValue<boolean> {
+  /**
+   * Create a new flag.
+   *
+   * @param value Initial flag value. Defaults to `false`.
+   */
+  constructor(value?: boolean);
+  /**
+   * Whether the flag is currently `true`.
+   */
+  get isTrue(): boolean;
+  /**
+   * Whether the flag is currently `false`.
+   */
+  get isFalse(): boolean;
+  /**
+   * Set the flag value.
+   *
+   * @param value Value to assign.
+   */
+  set(value: boolean): void;
+  /**
+   * Set the flag to `true`.
+   */
+  setTrue(): void;
+  /**
+   * Set the flag to `false`.
+   */
+  setFalse(): void;
+  /**
+   * Invert the current flag value.
+   */
+  toggle(): void;
+}
+declare function resettableLazy<T>(factory: () => T): {
+  get: () => T;
+  reset: () => void;
+};
+declare function resettableLazyAsync<T>(factory: () => Promise<T>): {
+  get: () => Promise<T>;
+  reset: () => void;
+};
+//#endregion
+export { Flag, ResettableValue, resettableLazy, resettableLazyAsync };

package/dist/state.d.mts

@@ -0,0 +1,88 @@
+//#region src/state.d.ts
+/**
+ * Holds a mutable value and remembers its initial value so it can be restored.
+ *
+ * @typeParam T Type of the held value.
+ */
+declare class ResettableValue<T> {
+  #private;
+  /**
+   * The current value.
+   */
+  value: T;
+  /**
+   * Create a resettable value.
+   *
+   * @param value Initial value to store and reset back to.
+   */
+  constructor(value: T);
+  /**
+   * Set the current value.
+   *
+   * @param value New value to assign.
+   */
+  set(value: T): void;
+  /**
+   * Restore the value back to its initial constructor value.
+   */
+  reset(): void;
+  /**
+   * Return the current value for primitive coercion.
+   *
+   * @returns The current value.
+   */
+  valueOf(): T;
+  /**
+   * Convert the current value to a string.
+   *
+   * @returns The string representation of the current value.
+   */
+  toString(): string;
+}
+/**
+ * A resettable boolean helper with convenience setters and state checks.
+ */
+declare class Flag extends ResettableValue<boolean> {
+  /**
+   * Create a new flag.
+   *
+   * @param value Initial flag value. Defaults to `false`.
+   */
+  constructor(value?: boolean);
+  /**
+   * Whether the flag is currently `true`.
+   */
+  get isTrue(): boolean;
+  /**
+   * Whether the flag is currently `false`.
+   */
+  get isFalse(): boolean;
+  /**
+   * Set the flag value.
+   *
+   * @param value Value to assign.
+   */
+  set(value: boolean): void;
+  /**
+   * Set the flag to `true`.
+   */
+  setTrue(): void;
+  /**
+   * Set the flag to `false`.
+   */
+  setFalse(): void;
+  /**
+   * Invert the current flag value.
+   */
+  toggle(): void;
+}
+declare function resettableLazy<T>(factory: () => T): {
+  get: () => T;
+  reset: () => void;
+};
+declare function resettableLazyAsync<T>(factory: () => Promise<T>): {
+  get: () => Promise<T>;
+  reset: () => void;
+};
+//#endregion
+export { Flag, ResettableValue, resettableLazy, resettableLazyAsync };

package/dist/state.mjs

@@ -0,0 +1 @@
+var e=class{value;#e;constructor(e){this.value=e,this.#e=e}set(e){this.value=e}reset(){this.value=this.#e}valueOf(){return this.value}toString(){return String(this.value)}},t=class extends e{constructor(e=!1){super(e)}get isTrue(){return this.value===!0}get isFalse(){return!this.isTrue}set(e){super.set(e)}setTrue(){this.value=!0}setFalse(){this.value=!1}toggle(){this.value=!this.value}};function n(e){let t,n=!1;function r(){return n||=(t=e(),!0),t}function i(){n=!1,t=void 0}return{get:r,reset:i}}function r(e){let t;function n(){return t||=e().catch(e=>{throw t=void 0,e}),t}function r(){t=void 0}return{get:n,reset:r}}export{t as Flag,e as ResettableValue,n as resettableLazy,r as resettableLazyAsync};

package/dist/timing.cjs

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

package/dist/timing.d.cts

@@ -0,0 +1,71 @@
+import { Awaitable } from "./typing.cjs";
+
+//#region src/timing.d.ts
+interface IRetryOptions {
+  attempts?: number;
+  baseMs?: number;
+  maxMs?: number;
+  jitter?: RetryJitter;
+  signal?: AbortSignal;
+  shouldRetry?: (error: unknown, attempt: number) => Awaitable<boolean>;
+}
+declare const enum RetryJitter {
+  None = 0,
+  Full = 1,
+  Equal = 2
+}
+/**
+ * Returns a promise after the provided {@link ms} has passed
+ * @param ms The number of milliseconds to wait
+ */
+declare function timeout(ms: number): Promise<unknown>;
+/**
+ * Rejects a promise after the provided {@link ms} has passed
+ * @param ms The number of milliseconds to wait
+ */
+declare function rejectionTimeout(ms: number): Promise<unknown>;
+/**
+ * Polls until the provided condition is met, or the timeout is exceeded.
+ *
+ * @param condition A function that returns a boolean or a promise that resolves to a boolean
+ * @param interval The interval in milliseconds to wait between checks
+ * @param timeoutMs The maximum time in milliseconds to wait before throwing an error
+ */
+declare function pollUntil(condition: () => Awaitable<boolean>, interval?: number, timeoutMs?: number): Promise<void>;
+/**
+ * Wraps a promise with a timeout. If the promise does not resolve within the specified time, an error is thrown.
+ *
+ * @param promise The promise to wrap with a timeout
+ * @param ms The number of milliseconds to wait before timing out
+ *
+ * @returns The result of the promise if it resolves before the timeout, otherwise throws an error
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * Returns an AbortSignal that aborts automatically after the given number of milliseconds.
+ *
+ * @param ms Delay before automatic abort.
+ */
+declare function abortAfter(ms: number): AbortSignal;
+/**
+ * Returns a signal that aborts when any of the input signals aborts.
+ *
+ * @param signals Input abort signals.
+ */
+declare function raceSignals(...signals: Array<AbortSignal | undefined>): AbortSignal;
+/**
+ * Wraps a promise and rejects when the signal aborts before completion.
+ *
+ * @param promise Promise or value to await.
+ * @param signal Abort signal to monitor.
+ */
+declare function withAbort<T>(promise: Awaitable<T>, signal: AbortSignal): Promise<T>;
+/**
+ * Retries an operation with exponential backoff.
+ *
+ * @param fn Operation to run for each attempt.
+ * @param options Retry options controlling attempts, backoff, jitter, and cancellation.
+ */
+declare function retry<T>(fn: (attempt: number) => Awaitable<T>, options?: IRetryOptions): Promise<T>;
+//#endregion
+export { IRetryOptions, RetryJitter, abortAfter, pollUntil, raceSignals, rejectionTimeout, retry, timeout, withAbort, withTimeout };

package/dist/timing.d.mts

@@ -0,0 +1,71 @@
+import { Awaitable } from "./typing.mjs";
+
+//#region src/timing.d.ts
+interface IRetryOptions {
+  attempts?: number;
+  baseMs?: number;
+  maxMs?: number;
+  jitter?: RetryJitter;
+  signal?: AbortSignal;
+  shouldRetry?: (error: unknown, attempt: number) => Awaitable<boolean>;
+}
+declare const enum RetryJitter {
+  None = 0,
+  Full = 1,
+  Equal = 2
+}
+/**
+ * Returns a promise after the provided {@link ms} has passed
+ * @param ms The number of milliseconds to wait
+ */
+declare function timeout(ms: number): Promise<unknown>;
+/**
+ * Rejects a promise after the provided {@link ms} has passed
+ * @param ms The number of milliseconds to wait
+ */
+declare function rejectionTimeout(ms: number): Promise<unknown>;
+/**
+ * Polls until the provided condition is met, or the timeout is exceeded.
+ *
+ * @param condition A function that returns a boolean or a promise that resolves to a boolean
+ * @param interval The interval in milliseconds to wait between checks
+ * @param timeoutMs The maximum time in milliseconds to wait before throwing an error
+ */
+declare function pollUntil(condition: () => Awaitable<boolean>, interval?: number, timeoutMs?: number): Promise<void>;
+/**
+ * Wraps a promise with a timeout. If the promise does not resolve within the specified time, an error is thrown.
+ *
+ * @param promise The promise to wrap with a timeout
+ * @param ms The number of milliseconds to wait before timing out
+ *
+ * @returns The result of the promise if it resolves before the timeout, otherwise throws an error
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * Returns an AbortSignal that aborts automatically after the given number of milliseconds.
+ *
+ * @param ms Delay before automatic abort.
+ */
+declare function abortAfter(ms: number): AbortSignal;
+/**
+ * Returns a signal that aborts when any of the input signals aborts.
+ *
+ * @param signals Input abort signals.
+ */
+declare function raceSignals(...signals: Array<AbortSignal | undefined>): AbortSignal;
+/**
+ * Wraps a promise and rejects when the signal aborts before completion.
+ *
+ * @param promise Promise or value to await.
+ * @param signal Abort signal to monitor.
+ */
+declare function withAbort<T>(promise: Awaitable<T>, signal: AbortSignal): Promise<T>;
+/**
+ * Retries an operation with exponential backoff.
+ *
+ * @param fn Operation to run for each attempt.
+ * @param options Retry options controlling attempts, backoff, jitter, and cancellation.
+ */
+declare function retry<T>(fn: (attempt: number) => Awaitable<T>, options?: IRetryOptions): Promise<T>;
+//#endregion
+export { IRetryOptions, RetryJitter, abortAfter, pollUntil, raceSignals, rejectionTimeout, retry, timeout, withAbort, withTimeout };

package/dist/timing.mjs

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

package/dist/typing.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=e=>e;function t(e){}function n(e){return Object.entries(e)}function r(e){return{ok:!0,value:e}}function i(e){return{ok:!1,error:e}}function a(e){return e.ok}function o(e,t){return e.ok?r(t(e.value)):e}function s(e,t){return e.ok?e:i(t(e.error))}async function c(e,t){try{return r(await e())}catch(e){return i(t?t(e):e)}}exports.assume=t,exports.cast=e,exports.err=i,exports.isOk=a,exports.mapErr=s,exports.mapOk=o,exports.ok=r,exports.tryCatchAsync=c,exports.typedEntries=n;

package/dist/typing.d.cts

@@ -0,0 +1,26 @@
+//#region src/typing.d.ts
+type Awaitable<T> = PromiseLike<T> | T;
+type Maybe<T> = T | undefined;
+type Nullable<T> = T | null;
+type Result<T, E = unknown> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: E;
+};
+declare const cast: <T, U extends T>(value: U) => U;
+declare function assume<T>(value: unknown): asserts value is T;
+declare function typedEntries<T extends object>(obj: T): { [K in keyof T]: [K, T[K]] }[keyof T][];
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+declare function isOk<T, E>(result: Result<T, E>): result is {
+  ok: true;
+  value: T;
+};
+declare function mapOk<T, U, E>(result: Result<T, E>, mapper: (value: T) => U): Result<U, E>;
+declare function mapErr<T, E, F>(result: Result<T, E>, mapper: (error: E) => F): Result<T, F>;
+declare function tryCatchAsync<T>(operation: () => Awaitable<T>): Promise<Result<T, unknown>>;
+declare function tryCatchAsync<T, E>(operation: () => Awaitable<T>, mapError: (error: unknown) => E): Promise<Result<T, E>>;
+//#endregion
+export { Awaitable, Maybe, Nullable, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries };

package/dist/typing.d.mts

@@ -0,0 +1,26 @@
+//#region src/typing.d.ts
+type Awaitable<T> = PromiseLike<T> | T;
+type Maybe<T> = T | undefined;
+type Nullable<T> = T | null;
+type Result<T, E = unknown> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: E;
+};
+declare const cast: <T, U extends T>(value: U) => U;
+declare function assume<T>(value: unknown): asserts value is T;
+declare function typedEntries<T extends object>(obj: T): { [K in keyof T]: [K, T[K]] }[keyof T][];
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+declare function isOk<T, E>(result: Result<T, E>): result is {
+  ok: true;
+  value: T;
+};
+declare function mapOk<T, U, E>(result: Result<T, E>, mapper: (value: T) => U): Result<U, E>;
+declare function mapErr<T, E, F>(result: Result<T, E>, mapper: (error: E) => F): Result<T, F>;
+declare function tryCatchAsync<T>(operation: () => Awaitable<T>): Promise<Result<T, unknown>>;
+declare function tryCatchAsync<T, E>(operation: () => Awaitable<T>, mapError: (error: unknown) => E): Promise<Result<T, E>>;
+//#endregion
+export { Awaitable, Maybe, Nullable, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries };

package/dist/typing.mjs

@@ -0,0 +1 @@
+const e=e=>e;function t(e){}function n(e){return Object.entries(e)}function r(e){return{ok:!0,value:e}}function i(e){return{ok:!1,error:e}}function a(e){return e.ok}function o(e,t){return e.ok?r(t(e.value)):e}function s(e,t){return e.ok?e:i(t(e.error))}async function c(e,t){try{return r(await e())}catch(e){return i(t?t(e):e)}}export{t as assume,e as cast,i as err,a as isOk,s as mapErr,o as mapOk,r as ok,c as tryCatchAsync,n as typedEntries};

package/dist/url.cjs

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

package/dist/{urllib.d.cts → url.d.cts}

@@ -1,7 +1,14 @@
-//#region src/urllib.d.ts
+//#region src/url.d.ts
 type URLLike = string | URL | URLPath;
 type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
+/**
+ * Tagged-template helper for encoded URL path segments.
+ *
+ * @example
+ * const path = url`/users/${userId}/posts/${postId}`;
+ */
+declare function url(strings: TemplateStringsArray, ...values: unknown[]): string;
 declare class URLPath {
   #private;
   constructor(input: URLLike, base?: URLLike);
@@ -25,6 +32,9 @@ declare class URLPath {
   div(...segments: string[]): URLPath;
   private withPath;
   withQuery(params: QueryObject): URLPath;
+  withQueryPatch(params: QueryObject): URLPath;
+  appendQuery(params: QueryObject): URLPath;
+  withoutEmptyQuery(): URLPath;
   withoutQuery(...keys: string[]): URLPath;
   withHash(hash: string): URLPath;
   withoutHash(): URLPath;
@@ -39,4 +49,4 @@ declare class URLPath {
   static parse(input: string): URLPath;
 }
 //#endregion
-export { QueryObject, QueryValue, URLLike, URLPath };
+export { QueryObject, QueryValue, URLLike, URLPath, url };

package/dist/{urllib.d.mts → url.d.mts}

@@ -1,7 +1,14 @@
-//#region src/urllib.d.ts
+//#region src/url.d.ts
 type URLLike = string | URL | URLPath;
 type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
+/**
+ * Tagged-template helper for encoded URL path segments.
+ *
+ * @example
+ * const path = url`/users/${userId}/posts/${postId}`;
+ */
+declare function url(strings: TemplateStringsArray, ...values: unknown[]): string;
 declare class URLPath {
   #private;
   constructor(input: URLLike, base?: URLLike);
@@ -25,6 +32,9 @@ declare class URLPath {
   div(...segments: string[]): URLPath;
   private withPath;
   withQuery(params: QueryObject): URLPath;
+  withQueryPatch(params: QueryObject): URLPath;
+  appendQuery(params: QueryObject): URLPath;
+  withoutEmptyQuery(): URLPath;
   withoutQuery(...keys: string[]): URLPath;
   withHash(hash: string): URLPath;
   withoutHash(): URLPath;
@@ -39,4 +49,4 @@ declare class URLPath {
   static parse(input: string): URLPath;
 }
 //#endregion
-export { QueryObject, QueryValue, URLLike, URLPath };
+export { QueryObject, QueryValue, URLLike, URLPath, url };

package/dist/url.mjs

@@ -0,0 +1 @@
+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)}};export{n as URLPath,e as url};