@depthbomb/common 1.3.2 → 2.0.0

package/README.md

@@ -6,4 +6,289 @@ A set of common utilities for TypeScript/JavaScript that I use in my projects.
 
 ---
 
-Documentation and additional TSDocs coming soon.
+## Modules
+
+### `timing`
+
+Timing and timeout flow-control helpers.
+
+```ts
+import {
+	timeout,
+	rejectionTimeout,
+	pollUntil,
+	withTimeout,
+	retry,
+	abortAfter,
+	withAbort,
+	raceSignals,
+	RetryJitter,
+} from '@depthbomb/common/timing';
+
+await timeout(250);
+await rejectionTimeout(100).catch(() => {});
+
+let ready = false;
+setTimeout(() => { ready = true; }, 200);
+await pollUntil(() => ready, 50, 1_000);
+
+const value = await withTimeout(Promise.resolve('ok'), 500);
+
+const data = await retry(
+	async (attempt) => {
+		const response = await fetch('https://example.com/data');
+		if (!response.ok) {
+			throw new Error(`request failed on attempt ${attempt}`);
+		}
+		return response.json();
+	},
+	{
+		attempts: 4,
+		baseMs: 100,
+		maxMs: 1_000,
+		jitter: RetryJitter.Full,
+	}
+);
+
+const signal = abortAfter(1_000);
+await withAbort(fetch('https://example.com/slow'), signal);
+
+const parent = new AbortController();
+const child = abortAfter(500);
+const combined = raceSignals(parent.signal, child);
+```
+
+### `promise`
+
+Promise composition helpers, including detailed settled results and concurrency-limited execution.
+
+```ts
+import { allSettledSuccessful, allSettledDetailed, sequential, pool, pMap } from '@depthbomb/common/promise';
+
+const successful = await allSettledSuccessful([
+	Promise.resolve(1),
+	Promise.reject(new Error('x')),
+	Promise.resolve(2)
+]); // [1, 2]
+
+const ordered = await sequential([
+	async () => 'first',
+	async () => 'second'
+]); // ['first', 'second']
+
+const detailed = await allSettledDetailed([
+	Promise.resolve('ok'),
+	Promise.reject(new Error('x')),
+]); // { results, fulfilled: ['ok'], rejected: [Error('x')] }
+
+const pooled = await pool([
+	async () => 1,
+	async () => 2,
+	async () => 3,
+], { concurrency: 2 });
+
+const mapped = await pMap([1, 2, 3], async (v) => v * 10, { concurrency: 2 });
+```
+
+### `decorators`
+
+TypeScript decorators for reusable behavior. Currently includes a TTL-based `cache` decorator for memoizing method results per instance and argument set.
+
+```ts
+import { cache } from '@depthbomb/common/decorators';
+
+class Service {
+	calls = 0;
+
+	@cache(1_000)
+	getUser(id: string) {
+		this.calls++;
+		return { id, calls: this.calls };
+	}
+}
+
+const s = new Service();
+s.getUser('1');
+s.getUser('1'); // cached for 1 second
+```
+
+### `state`
+
+State primitives: `ResettableValue`, `Flag`, `resettableLazy`, and `resettableLazyAsync`.
+
+```ts
+import { Flag, ResettableValue, resettableLazy, resettableLazyAsync } from '@depthbomb/common/state';
+
+const flag = new Flag();
+flag.setTrue();
+flag.toggle();
+flag.reset();
+
+const retries = new ResettableValue(3);
+retries.set(1);
+retries.reset(); // back to 3
+
+const counter = resettableLazy(() => Math.random());
+const first = counter.get();
+counter.reset();
+const second = counter.get(); // recomputed
+
+const tokenCache = resettableLazyAsync(async () => {
+	const response = await fetch('https://example.com/token');
+	return response.text();
+});
+const token = await tokenCache.get();
+tokenCache.reset();
+```
+
+### `functional`
+
+General function utilities. Currently includes `once`, which ensures a function runs only on its first invocation and then reuses the same result.
+
+```ts
+import { once } from '@depthbomb/common/functional';
+
+const init = once(() => ({ startedAt: Date.now() }));
+
+const a = init();
+const b = init();
+console.log(a === b); // true
+```
+
+### `lazy`
+
+Lazy initialization utilities for sync and async values.
+
+```ts
+import { lazy, lazyAsync } from '@depthbomb/common/lazy';
+
+const getConfig = lazy(() => ({ env: 'prod' }));
+const config = getConfig(); // factory runs once
+
+const getToken = lazyAsync(async () => 'token');
+const token = await getToken(); // promise created once
+```
+
+### `collections`
+
+A lightweight generic FIFO queue with `enqueue`, `dequeue`, `peek`, iteration support, and internal compaction to keep long-running usage efficient. Also includes `BoundedQueue` for fixed-capacity use cases.
+
+```ts
+import { Queue, BoundedQueue, BoundedQueueOverflow } from '@depthbomb/common/collections';
+
+const q = new Queue<number>([1, 2]);
+q.enqueue(3);
+
+console.log(q.peek());    // 1
+console.log(q.dequeue()); // 1
+console.log(q.toArray()); // [2, 3]
+
+const bounded = new BoundedQueue<number>({ maxSize: 3, overflow: BoundedQueueOverflow.DropOldest }, [1, 2, 3]);
+bounded.enqueue(4);
+console.log(bounded.toArray()); // [2, 3, 4]
+```
+
+### `number`
+
+Numeric helpers for clamping, range checks, rounding, and aggregation.
+
+```ts
+import { clamp, inRange, roundTo, sum, average } from '@depthbomb/common/number';
+
+const bounded = clamp(12, 0, 10); // 10
+const valid = inRange(5, 1, 10); // true
+const rounded = roundTo(3.14159, 2); // 3.14
+const total = sum([1, 2, 3, 4]); // 10
+const mean = average([1, 2, 3, 4]); // 2.5
+```
+
+### `random`
+
+Cross-environment random helpers for ranges and selection.
+
+```ts
+import { randomFloat, randomInt, pickRandom, pickWeighted } from '@depthbomb/common/random';
+
+const f = randomFloat(5, 10); // 5 <= f < 10
+const i = randomInt(1, 6); // inclusive
+const choice = pickRandom(['red', 'green', 'blue']);
+const weighted = pickWeighted([
+	{ value: 'small', weight: 1 },
+	{ value: 'medium', weight: 3 },
+	{ value: 'large', weight: 6 },
+]);
+```
+
+### `guards`
+
+Runtime type guards for common narrowing patterns.
+
+```ts
+import { isRecord, isNonEmptyString, isNumber, isDateLike } from '@depthbomb/common/guards';
+
+const input: unknown = { name: 'Ada', createdAt: '2026-01-01' };
+
+if (isRecord(input) && isNonEmptyString(input.name) && isDateLike(input.createdAt)) {
+	// narrowed shape at runtime
+}
+
+const maybeCount: unknown = 42;
+if (isNumber(maybeCount)) {
+	console.log(maybeCount + 1);
+}
+```
+
+### `typing`
+
+Shared type aliases and type-oriented helpers such as `Awaitable`, `Maybe`, `Nullable`, `Result`, `cast`, `assume`, `typedEntries`, `ok`, `err`, `isOk`, `mapOk`, `mapErr`, and `tryCatchAsync`.
+
+```ts
+import {
+	cast, assume, typedEntries,
+	ok, err, isOk, mapOk, mapErr, tryCatchAsync,
+	type Awaitable, type Maybe, type Result
+} from '@depthbomb/common/typing';
+
+const v = cast<object, { id: string }>({ id: 'a' });
+
+const unknownValue: unknown = 'hello';
+assume<string>(unknownValue); // assertion helper
+
+const entries = typedEntries({ a: 1, b: 2 }); // typed key/value tuples
+
+const maybeName: Maybe<string> = undefined;
+const task: Awaitable<number> = Promise.resolve(1);
+
+const initial: Result<number, string> = ok(2);
+const doubled = mapOk(initial, (value) => value * 2);
+const message = mapErr(err('bad'), (e) => `error: ${e}`);
+
+const parsed = await tryCatchAsync(async () => JSON.parse('{"x":1}'));
+if (isOk(parsed)) {
+	console.log(parsed.value.x);
+}
+```
+
+### `url`
+
+URL-focused utilities centered around `URLPath`, an ergonomic wrapper for URL parsing, path composition, query/hash manipulation, and request dispatch via `fetch`.
+
+```ts
+import { URLPath, url } from '@depthbomb/common/url';
+
+const api = new URLPath('https://example.com/api');
+const usersUrl = api
+	.joinpath('users', '42')
+	.withQuery({ include: ['roles', 'profile'] })
+	.withQueryPatch({ page: 1 })
+	.appendQuery({ include: 'permissions' })
+	.withoutEmptyQuery()
+	.withHash('details');
+
+const userPath = url`/users/${'john/doe'}/posts/${'my first post'}`;
+
+console.log(usersUrl.toString());
+// https://example.com/api/users/42?include=roles&include=profile#details
+console.log(userPath);
+// /users/john%2Fdoe/posts/my%20first%20post
+```

package/dist/collections.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=function(e){return e[e.DropOldest=0]=`DropOldest`,e[e.DropNewest=1]=`DropNewest`,e[e.Throw=2]=`Throw`,e}({});var t=class{#e=[];#t=0;constructor(e){e&&(this.#e=[...e])}get size(){return this.#e.length-this.#t}get isEmpty(){return this.size===0}enqueue(e){this.#e.push(e)}dequeue(){if(this.#t>=this.#e.length)return;let e=this.#e[this.#t++];return this.#t>=64&&this.#t*2>=this.#e.length&&(this.#e=this.#e.slice(this.#t),this.#t=0),e}peek(){return this.#e[this.#t]}clear(){this.#e=[],this.#t=0}[Symbol.iterator](){return this.toArray()[Symbol.iterator]()}toArray(){return this.#e.slice(this.#t)}},n=class{#e;#t;#n;constructor(n,r){if(!Number.isInteger(n.maxSize)||n.maxSize<1)throw Error(`maxSize must be an integer >= 1`);if(this.#e=n.maxSize,this.#t=n.overflow??e.DropOldest,this.#n=new t,r)for(let e of r)this.enqueue(e)}get size(){return this.#n.size}get isEmpty(){return this.#n.isEmpty}get isFull(){return this.size>=this.#e}get maxSize(){return this.#e}get overflow(){return this.#t}enqueue(t){if(!this.isFull){this.#n.enqueue(t);return}if(this.#t!==e.DropNewest){if(this.#t===e.Throw)throw Error(`BoundedQueue overflow`);this.#n.dequeue(),this.#n.enqueue(t)}}dequeue(){return this.#n.dequeue()}peek(){return this.#n.peek()}clear(){this.#n.clear()}[Symbol.iterator](){return this.#n[Symbol.iterator]()}toArray(){return this.#n.toArray()}};exports.BoundedQueue=n,exports.BoundedQueueOverflow=e,exports.Queue=t;

package/dist/{queue.d.cts → collections.d.cts}

@@ -1,9 +1,17 @@
-import { Maybe } from "./types.cjs";
+import { Maybe } from "./typing.cjs";
 
-//#region src/queue.d.ts
+//#region src/collections.d.ts
+interface IBoundedQueueOptions {
+  maxSize: number;
+  overflow?: BoundedQueueOverflow;
+}
+declare const enum BoundedQueueOverflow {
+  DropOldest = 0,
+  DropNewest = 1,
+  Throw = 2
+}
 declare class Queue<T> {
-  private items;
-  private head;
+  #private;
   constructor(initial?: Iterable<T>);
   /**
    * Get the number of items in the queue.
@@ -48,5 +56,20 @@ declare class Queue<T> {
    */
   toArray(): T[];
 }
+declare class BoundedQueue<T> {
+  #private;
+  constructor(options: IBoundedQueueOptions, initial?: Iterable<T>);
+  get size(): number;
+  get isEmpty(): boolean;
+  get isFull(): boolean;
+  get maxSize(): number;
+  get overflow(): BoundedQueueOverflow;
+  enqueue(item: T): void;
+  dequeue(): Maybe<T>;
+  peek(): Maybe<T>;
+  clear(): void;
+  [Symbol.iterator](): Iterator<T>;
+  toArray(): T[];
+}
 //#endregion
-export { Queue };
+export { BoundedQueue, BoundedQueueOverflow, IBoundedQueueOptions, Queue };

package/dist/{queue.d.mts → collections.d.mts}

@@ -1,9 +1,17 @@
-import { Maybe } from "./types.mjs";
+import { Maybe } from "./typing.mjs";
 
-//#region src/queue.d.ts
+//#region src/collections.d.ts
+interface IBoundedQueueOptions {
+  maxSize: number;
+  overflow?: BoundedQueueOverflow;
+}
+declare const enum BoundedQueueOverflow {
+  DropOldest = 0,
+  DropNewest = 1,
+  Throw = 2
+}
 declare class Queue<T> {
-  private items;
-  private head;
+  #private;
   constructor(initial?: Iterable<T>);
   /**
    * Get the number of items in the queue.
@@ -48,5 +56,20 @@ declare class Queue<T> {
    */
   toArray(): T[];
 }
+declare class BoundedQueue<T> {
+  #private;
+  constructor(options: IBoundedQueueOptions, initial?: Iterable<T>);
+  get size(): number;
+  get isEmpty(): boolean;
+  get isFull(): boolean;
+  get maxSize(): number;
+  get overflow(): BoundedQueueOverflow;
+  enqueue(item: T): void;
+  dequeue(): Maybe<T>;
+  peek(): Maybe<T>;
+  clear(): void;
+  [Symbol.iterator](): Iterator<T>;
+  toArray(): T[];
+}
 //#endregion
-export { Queue };
+export { BoundedQueue, BoundedQueueOverflow, IBoundedQueueOptions, Queue };

package/dist/collections.mjs

@@ -0,0 +1 @@
+let e=function(e){return e[e.DropOldest=0]=`DropOldest`,e[e.DropNewest=1]=`DropNewest`,e[e.Throw=2]=`Throw`,e}({});var t=class{#e=[];#t=0;constructor(e){e&&(this.#e=[...e])}get size(){return this.#e.length-this.#t}get isEmpty(){return this.size===0}enqueue(e){this.#e.push(e)}dequeue(){if(this.#t>=this.#e.length)return;let e=this.#e[this.#t++];return this.#t>=64&&this.#t*2>=this.#e.length&&(this.#e=this.#e.slice(this.#t),this.#t=0),e}peek(){return this.#e[this.#t]}clear(){this.#e=[],this.#t=0}[Symbol.iterator](){return this.toArray()[Symbol.iterator]()}toArray(){return this.#e.slice(this.#t)}},n=class{#e;#t;#n;constructor(n,r){if(!Number.isInteger(n.maxSize)||n.maxSize<1)throw Error(`maxSize must be an integer >= 1`);if(this.#e=n.maxSize,this.#t=n.overflow??e.DropOldest,this.#n=new t,r)for(let e of r)this.enqueue(e)}get size(){return this.#n.size}get isEmpty(){return this.#n.isEmpty}get isFull(){return this.size>=this.#e}get maxSize(){return this.#e}get overflow(){return this.#t}enqueue(t){if(!this.isFull){this.#n.enqueue(t);return}if(this.#t!==e.DropNewest){if(this.#t===e.Throw)throw Error(`BoundedQueue overflow`);this.#n.dequeue(),this.#n.enqueue(t)}}dequeue(){return this.#n.dequeue()}peek(){return this.#n.peek()}clear(){this.#n.clear()}[Symbol.iterator](){return this.#n[Symbol.iterator]()}toArray(){return this.#n.toArray()}};export{n as BoundedQueue,e as BoundedQueueOverflow,t as Queue};

package/dist/{fn.d.cts → functional.d.cts}

@@ -1,4 +1,4 @@
-//#region src/fn.d.ts
+//#region src/functional.d.ts
 /**
  * Creates a function that calls the given function only once.
  *

package/dist/{fn.d.mts → functional.d.mts}

@@ -1,4 +1,4 @@
-//#region src/fn.d.ts
+//#region src/functional.d.ts
 /**
  * Creates a function that calls the given function only once.
  *

package/dist/guards.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){return!Number.isNaN(e.getTime())}function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e){return typeof e==`string`&&e.length>0}function r(e){return typeof e==`number`&&Number.isFinite(e)}function i(t){return t instanceof Date?e(t):typeof t==`number`?Number.isFinite(t)&&e(new Date(t)):typeof t==`string`?t.length>0&&e(new Date(t)):!1}exports.isDateLike=i,exports.isNonEmptyString=n,exports.isNumber=r,exports.isRecord=t;

package/dist/guards.d.cts

@@ -0,0 +1,7 @@
+//#region src/guards.d.ts
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function isNonEmptyString(value: unknown): value is string;
+declare function isNumber(value: unknown): value is number;
+declare function isDateLike(value: unknown): value is Date | number | string;
+//#endregion
+export { isDateLike, isNonEmptyString, isNumber, isRecord };

package/dist/guards.d.mts

@@ -0,0 +1,7 @@
+//#region src/guards.d.ts
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function isNonEmptyString(value: unknown): value is string;
+declare function isNumber(value: unknown): value is number;
+declare function isDateLike(value: unknown): value is Date | number | string;
+//#endregion
+export { isDateLike, isNonEmptyString, isNumber, isRecord };

package/dist/guards.mjs

@@ -0,0 +1 @@
+function e(e){return!Number.isNaN(e.getTime())}function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e){return typeof e==`string`&&e.length>0}function r(e){return typeof e==`number`&&Number.isFinite(e)}function i(t){return t instanceof Date?e(t):typeof t==`number`?Number.isFinite(t)&&e(new Date(t)):typeof t==`string`?t.length>0&&e(new Date(t)):!1}export{i as isDateLike,n as isNonEmptyString,r as isNumber,t as isRecord};

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./async.cjs`),t=require(`./decorators.cjs`),n=require(`./fn.cjs`),r=require(`./lazy.cjs`),i=require(`./queue.cjs`),a=require(`./types.cjs`),o=require(`./urllib.cjs`);exports.Queue=i.Queue,exports.URLPath=o.URLPath,exports.allSettledSuccessful=e.allSettledSuccessful,exports.assume=a.assume,exports.cache=t.cache,exports.cast=a.cast,exports.lazy=r.lazy,exports.lazyAsync=r.lazyAsync,exports.once=n.once,exports.pollUntil=e.pollUntil,exports.rejectionTimeout=e.rejectionTimeout,exports.resettableLazy=r.resettableLazy,exports.sequential=e.sequential,exports.timeout=e.timeout,exports.typedEntries=a.typedEntries,exports.withTimeout=e.withTimeout;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./collections.cjs`),t=require(`./decorators.cjs`),n=require(`./functional.cjs`),r=require(`./guards.cjs`),i=require(`./timing.cjs`),a=require(`./promise.cjs`),o=require(`./lazy.cjs`),s=require(`./number.cjs`),c=require(`./random.cjs`),l=require(`./state.cjs`),u=require(`./typing.cjs`),d=require(`./url.cjs`);exports.BoundedQueue=e.BoundedQueue,exports.BoundedQueueOverflow=e.BoundedQueueOverflow,exports.Flag=l.Flag,exports.Queue=e.Queue,exports.ResettableValue=l.ResettableValue,exports.RetryJitter=i.RetryJitter,exports.URLPath=d.URLPath,exports.abortAfter=i.abortAfter,exports.allSettledDetailed=a.allSettledDetailed,exports.allSettledSuccessful=a.allSettledSuccessful,exports.assume=u.assume,exports.average=s.average,exports.cache=t.cache,exports.cast=u.cast,exports.clamp=s.clamp,exports.err=u.err,exports.inRange=s.inRange,exports.isDateLike=r.isDateLike,exports.isNonEmptyString=r.isNonEmptyString,exports.isNumber=r.isNumber,exports.isOk=u.isOk,exports.isRecord=r.isRecord,exports.lazy=o.lazy,exports.lazyAsync=o.lazyAsync,exports.mapErr=u.mapErr,exports.mapOk=u.mapOk,exports.ok=u.ok,exports.once=n.once,exports.pMap=a.pMap,exports.pickRandom=c.pickRandom,exports.pickWeighted=c.pickWeighted,exports.pollUntil=i.pollUntil,exports.pool=a.pool,exports.raceSignals=i.raceSignals,exports.randomFloat=c.randomFloat,exports.randomInt=c.randomInt,exports.rejectionTimeout=i.rejectionTimeout,exports.resettableLazy=l.resettableLazy,exports.resettableLazyAsync=l.resettableLazyAsync,exports.retry=i.retry,exports.roundTo=s.roundTo,exports.sequential=a.sequential,exports.sum=s.sum,exports.timeout=i.timeout,exports.tryCatchAsync=u.tryCatchAsync,exports.typedEntries=u.typedEntries,exports.url=d.url,exports.withAbort=i.withAbort,exports.withTimeout=i.withTimeout;

package/dist/index.d.cts

@@ -1,8 +1,13 @@
-import { allSettledSuccessful, pollUntil, rejectionTimeout, sequential, timeout, withTimeout } from "./async.cjs";
+import { Awaitable, Maybe, Nullable, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries } from "./typing.cjs";
+import { BoundedQueue, BoundedQueueOverflow, IBoundedQueueOptions, Queue } from "./collections.cjs";
 import { cache } from "./decorators.cjs";
-import { once } from "./fn.cjs";
-import { lazy, lazyAsync, resettableLazy } from "./lazy.cjs";
-import { Awaitable, Maybe, Nullable, assume, cast, typedEntries } from "./types.cjs";
-import { Queue } from "./queue.cjs";
-import { QueryObject, QueryValue, URLLike, URLPath } from "./urllib.cjs";
-export { Awaitable, Maybe, Nullable, QueryObject, QueryValue, Queue, URLLike, URLPath, allSettledSuccessful, assume, cache, cast, lazy, lazyAsync, once, pollUntil, rejectionTimeout, resettableLazy, sequential, timeout, typedEntries, withTimeout };
+import { once } from "./functional.cjs";
+import { isDateLike, isNonEmptyString, isNumber, isRecord } from "./guards.cjs";
+import { IRetryOptions, RetryJitter, abortAfter, pollUntil, raceSignals, rejectionTimeout, retry, timeout, withAbort, withTimeout } from "./timing.cjs";
+import { IConcurrencyOptions, SettledDetailed, allSettledDetailed, allSettledSuccessful, pMap, pool, sequential } from "./promise.cjs";
+import { lazy, lazyAsync } from "./lazy.cjs";
+import { average, clamp, inRange, roundTo, sum } from "./number.cjs";
+import { IWeightedItem, pickRandom, pickWeighted, randomFloat, randomInt } from "./random.cjs";
+import { Flag, ResettableValue, resettableLazy, resettableLazyAsync } from "./state.cjs";
+import { QueryObject, QueryValue, URLLike, URLPath, url } from "./url.cjs";
+export { Awaitable, BoundedQueue, BoundedQueueOverflow, Flag, IBoundedQueueOptions, IConcurrencyOptions, IRetryOptions, IWeightedItem, Maybe, Nullable, QueryObject, QueryValue, Queue, ResettableValue, Result, RetryJitter, SettledDetailed, URLLike, URLPath, abortAfter, allSettledDetailed, allSettledSuccessful, assume, average, cache, cast, clamp, err, inRange, isDateLike, isNonEmptyString, isNumber, isOk, isRecord, lazy, lazyAsync, mapErr, mapOk, ok, once, pMap, pickRandom, pickWeighted, pollUntil, pool, raceSignals, randomFloat, randomInt, rejectionTimeout, resettableLazy, resettableLazyAsync, retry, roundTo, sequential, sum, timeout, tryCatchAsync, typedEntries, url, withAbort, withTimeout };

package/dist/index.d.mts

@@ -1,8 +1,13 @@
-import { allSettledSuccessful, pollUntil, rejectionTimeout, sequential, timeout, withTimeout } from "./async.mjs";
+import { Awaitable, Maybe, Nullable, Result, assume, cast, err, isOk, mapErr, mapOk, ok, tryCatchAsync, typedEntries } from "./typing.mjs";
+import { BoundedQueue, BoundedQueueOverflow, IBoundedQueueOptions, Queue } from "./collections.mjs";
 import { cache } from "./decorators.mjs";
-import { once } from "./fn.mjs";
-import { lazy, lazyAsync, resettableLazy } from "./lazy.mjs";
-import { Awaitable, Maybe, Nullable, assume, cast, typedEntries } from "./types.mjs";
-import { Queue } from "./queue.mjs";
-import { QueryObject, QueryValue, URLLike, URLPath } from "./urllib.mjs";
-export { Awaitable, Maybe, Nullable, QueryObject, QueryValue, Queue, URLLike, URLPath, allSettledSuccessful, assume, cache, cast, lazy, lazyAsync, once, pollUntil, rejectionTimeout, resettableLazy, sequential, timeout, typedEntries, withTimeout };
+import { once } from "./functional.mjs";
+import { isDateLike, isNonEmptyString, isNumber, isRecord } from "./guards.mjs";
+import { IRetryOptions, RetryJitter, abortAfter, pollUntil, raceSignals, rejectionTimeout, retry, timeout, withAbort, withTimeout } from "./timing.mjs";
+import { IConcurrencyOptions, SettledDetailed, allSettledDetailed, allSettledSuccessful, pMap, pool, sequential } from "./promise.mjs";
+import { lazy, lazyAsync } from "./lazy.mjs";
+import { average, clamp, inRange, roundTo, sum } from "./number.mjs";
+import { IWeightedItem, pickRandom, pickWeighted, randomFloat, randomInt } from "./random.mjs";
+import { Flag, ResettableValue, resettableLazy, resettableLazyAsync } from "./state.mjs";
+import { QueryObject, QueryValue, URLLike, URLPath, url } from "./url.mjs";
+export { Awaitable, BoundedQueue, BoundedQueueOverflow, Flag, IBoundedQueueOptions, IConcurrencyOptions, IRetryOptions, IWeightedItem, Maybe, Nullable, QueryObject, QueryValue, Queue, ResettableValue, Result, RetryJitter, SettledDetailed, URLLike, URLPath, abortAfter, allSettledDetailed, allSettledSuccessful, assume, average, cache, cast, clamp, err, inRange, isDateLike, isNonEmptyString, isNumber, isOk, isRecord, lazy, lazyAsync, mapErr, mapOk, ok, once, pMap, pickRandom, pickWeighted, pollUntil, pool, raceSignals, randomFloat, randomInt, rejectionTimeout, resettableLazy, resettableLazyAsync, retry, roundTo, sequential, sum, timeout, tryCatchAsync, typedEntries, url, withAbort, withTimeout };

package/dist/index.mjs

@@ -1 +1 @@
-import{allSettledSuccessful as e,pollUntil as t,rejectionTimeout as n,sequential as r,timeout as i,withTimeout as a}from"./async.mjs";import{cache as o}from"./decorators.mjs";import{once as s}from"./fn.mjs";import{lazy as c,lazyAsync as l,resettableLazy as u}from"./lazy.mjs";import{Queue as d}from"./queue.mjs";import{assume as f,cast as p,typedEntries as m}from"./types.mjs";import{URLPath as h}from"./urllib.mjs";export{d as Queue,h as URLPath,e as allSettledSuccessful,f as assume,o as cache,p as cast,c as lazy,l as lazyAsync,s as once,t as pollUntil,n as rejectionTimeout,u as resettableLazy,r as sequential,i as timeout,m as typedEntries,a as withTimeout};
+import{BoundedQueue as e,BoundedQueueOverflow as t,Queue as n}from"./collections.mjs";import{cache as r}from"./decorators.mjs";import{once as i}from"./functional.mjs";import{isDateLike as a,isNonEmptyString as o,isNumber as s,isRecord as c}from"./guards.mjs";import{RetryJitter as l,abortAfter as u,pollUntil as d,raceSignals as f,rejectionTimeout as p,retry as m,timeout as h,withAbort as g,withTimeout as _}from"./timing.mjs";import{allSettledDetailed as v,allSettledSuccessful as y,pMap as b,pool as x,sequential as S}from"./promise.mjs";import{lazy as C,lazyAsync as w}from"./lazy.mjs";import{average as T,clamp as E,inRange as D,roundTo as O,sum as k}from"./number.mjs";import{pickRandom as A,pickWeighted as j,randomFloat as M,randomInt as N}from"./random.mjs";import{Flag as P,ResettableValue as F,resettableLazy as I,resettableLazyAsync as L}from"./state.mjs";import{assume as R,cast as z,err as B,isOk as V,mapErr as H,mapOk as U,ok as W,tryCatchAsync as G,typedEntries as K}from"./typing.mjs";import{URLPath as q,url as J}from"./url.mjs";export{e as BoundedQueue,t as BoundedQueueOverflow,P as Flag,n as Queue,F as ResettableValue,l as RetryJitter,q as URLPath,u as abortAfter,v as allSettledDetailed,y as allSettledSuccessful,R as assume,T as average,r as cache,z as cast,E as clamp,B as err,D as inRange,a as isDateLike,o as isNonEmptyString,s as isNumber,V as isOk,c as isRecord,C as lazy,w as lazyAsync,H as mapErr,U as mapOk,W as ok,i as once,b as pMap,A as pickRandom,j as pickWeighted,d as pollUntil,x as pool,f as raceSignals,M as randomFloat,N as randomInt,p as rejectionTimeout,I as resettableLazy,L as resettableLazyAsync,m as retry,O as roundTo,S as sequential,k as sum,h as timeout,G as tryCatchAsync,K as typedEntries,J as url,g as withAbort,_ as withTimeout};

package/dist/lazy.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){let t,n=!1;return()=>(n||=(t=e(),!0),t)}function t(e){let t;return()=>(t||=e(),t)}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}}exports.lazy=e,exports.lazyAsync=t,exports.resettableLazy=n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){let t,n=!1;return()=>(n||=(t=e(),!0),t)}function t(e){let t;return()=>(t||=e(),t)}exports.lazy=e,exports.lazyAsync=t;

package/dist/lazy.d.cts

@@ -1,9 +1,5 @@
 //#region src/lazy.d.ts
 declare function lazy<T>(factory: () => T): () => T;
 declare function lazyAsync<T>(factory: () => Promise<T>): () => Promise<T>;
-declare function resettableLazy<T>(factory: () => T): {
-  get: () => T;
-  reset: () => void;
-};
 //#endregion
-export { lazy, lazyAsync, resettableLazy };
+export { lazy, lazyAsync };

package/dist/lazy.d.mts

@@ -1,9 +1,5 @@
 //#region src/lazy.d.ts
 declare function lazy<T>(factory: () => T): () => T;
 declare function lazyAsync<T>(factory: () => Promise<T>): () => Promise<T>;
-declare function resettableLazy<T>(factory: () => T): {
-  get: () => T;
-  reset: () => void;
-};
 //#endregion
-export { lazy, lazyAsync, resettableLazy };
+export { lazy, lazyAsync };

package/dist/lazy.mjs

@@ -1 +1 @@
-function e(e){let t,n=!1;return()=>(n||=(t=e(),!0),t)}function t(e){let t;return()=>(t||=e(),t)}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}}export{e as lazy,t as lazyAsync,n as resettableLazy};
+function e(e){let t,n=!1;return()=>(n||=(t=e(),!0),t)}function t(e){let t;return()=>(t||=e(),t)}export{e as lazy,t as lazyAsync};

package/dist/number.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t,n){if(t>n)throw Error(`min must be <= max`);return Math.min(Math.max(e,t),n)}function t(e,t,n,r=!0){if(t>n)throw Error(`min must be <= max`);return r?e>=t&&e<=n:e>t&&e<n}function n(e,t=0){if(!Number.isInteger(t)||t<0)throw Error(`decimals must be an integer >= 0`);let n=10**t;return Math.round((e+2**-52)*n)/n}function r(e){let t=0;for(let n of e)t+=n;return t}function i(e){let t=0,n=0;for(let r of e)t+=r,n++;if(n===0)throw Error(`cannot compute average of empty iterable`);return t/n}exports.average=i,exports.clamp=e,exports.inRange=t,exports.roundTo=n,exports.sum=r;

package/dist/number.d.cts

@@ -0,0 +1,8 @@
+//#region src/number.d.ts
+declare function clamp(value: number, min: number, max: number): number;
+declare function inRange(value: number, min: number, max: number, inclusive?: boolean): boolean;
+declare function roundTo(value: number, decimals?: number): number;
+declare function sum(values: Iterable<number>): number;
+declare function average(values: Iterable<number>): number;
+//#endregion
+export { average, clamp, inRange, roundTo, sum };

package/dist/number.d.mts

@@ -0,0 +1,8 @@
+//#region src/number.d.ts
+declare function clamp(value: number, min: number, max: number): number;
+declare function inRange(value: number, min: number, max: number, inclusive?: boolean): boolean;
+declare function roundTo(value: number, decimals?: number): number;
+declare function sum(values: Iterable<number>): number;
+declare function average(values: Iterable<number>): number;
+//#endregion
+export { average, clamp, inRange, roundTo, sum };

package/dist/number.mjs

@@ -0,0 +1 @@
+function e(e,t,n){if(t>n)throw Error(`min must be <= max`);return Math.min(Math.max(e,t),n)}function t(e,t,n,r=!0){if(t>n)throw Error(`min must be <= max`);return r?e>=t&&e<=n:e>t&&e<n}function n(e,t=0){if(!Number.isInteger(t)||t<0)throw Error(`decimals must be an integer >= 0`);let n=10**t;return Math.round((e+2**-52)*n)/n}function r(e){let t=0;for(let n of e)t+=n;return t}function i(e){let t=0,n=0;for(let r of e)t+=r,n++;if(n===0)throw Error(`cannot compute average of empty iterable`);return t/n}export{i as average,e as clamp,t as inRange,n as roundTo,r as sum};

package/dist/promise.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});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)}exports.allSettledDetailed=t,exports.allSettledSuccessful=e,exports.pMap=a,exports.pool=i,exports.sequential=n;

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 };