@depthbomb/common 1.3.2 → 2.1.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 typeof e==`string`}function t(t){return e(t)&&t.length>0}function n(e){return typeof e==`number`&&Number.isFinite(e)}function r(e){return n(e)&&e>0}function i(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function a(e){return typeof e==`function`}function o(e){return a(e)&&e.toString().startsWith(`class`)}function s(e){return e===null}function c(e){return e===void 0}function l(e){return s(e)||c(e)}function u(e){return typeof e==`boolean`}function d(e){return!!e}function f(e){return!e}function p(t){return t instanceof Date?h(t):n(t)||e(t)?h(new Date(t)):!1}const m={string:e,nonEmptyString:t,number:n,positiveNumber:r,record:i,function:a,class:o,null:s,undefined:c,nullOrUndefined:l,boolean:u,truthy:d,falsy:f,dateLike:p};function h(e){return!Number.isNaN(e.getTime())}exports.is=m,exports.isBoolean=u,exports.isClass=o,exports.isDateLike=p,exports.isFalsy=f,exports.isFunction=a,exports.isNonEmptyString=t,exports.isNull=s,exports.isNullOrUndefined=l,exports.isNumber=n,exports.isPositiveNumber=r,exports.isRecord=i,exports.isString=e,exports.isTruthy=d,exports.isUndefined=c;

package/dist/guards.d.cts

@@ -0,0 +1,37 @@
+import { Class } from "./typing.cjs";
+
+//#region src/guards.d.ts
+type Falsy = false | 0 | 0n | '' | null | undefined;
+type DateLike = Date | string | number;
+declare function isString(value: unknown): value is string;
+declare function isNonEmptyString(value: unknown): value is string;
+declare function isNumber(value: unknown): value is number;
+declare function isPositiveNumber(value: unknown): value is number;
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function isFunction(value: unknown): value is Function;
+declare function isClass<T = unknown>(value: unknown): value is Class<T>;
+declare function isNull(value: unknown): value is null;
+declare function isUndefined(value: unknown): value is undefined;
+declare function isNullOrUndefined(value: unknown): value is null | undefined;
+declare function isBoolean(value: unknown): value is boolean;
+declare function isTruthy<T>(value: T | Falsy): value is T;
+declare function isFalsy(value: unknown): value is Falsy;
+declare function isDateLike(value: unknown): value is DateLike;
+declare const is: {
+  string: typeof isString;
+  nonEmptyString: typeof isNonEmptyString;
+  number: typeof isNumber;
+  positiveNumber: typeof isPositiveNumber;
+  record: typeof isRecord;
+  function: typeof isFunction;
+  class: typeof isClass;
+  null: typeof isNull;
+  undefined: typeof isUndefined;
+  nullOrUndefined: typeof isNullOrUndefined;
+  boolean: typeof isBoolean;
+  truthy: typeof isTruthy;
+  falsy: typeof isFalsy;
+  dateLike: typeof isDateLike;
+};
+//#endregion
+export { DateLike, Falsy, is, isBoolean, isClass, isDateLike, isFalsy, isFunction, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isPositiveNumber, isRecord, isString, isTruthy, isUndefined };

package/dist/guards.d.mts

@@ -0,0 +1,37 @@
+import { Class } from "./typing.mjs";
+
+//#region src/guards.d.ts
+type Falsy = false | 0 | 0n | '' | null | undefined;
+type DateLike = Date | string | number;
+declare function isString(value: unknown): value is string;
+declare function isNonEmptyString(value: unknown): value is string;
+declare function isNumber(value: unknown): value is number;
+declare function isPositiveNumber(value: unknown): value is number;
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function isFunction(value: unknown): value is Function;
+declare function isClass<T = unknown>(value: unknown): value is Class<T>;
+declare function isNull(value: unknown): value is null;
+declare function isUndefined(value: unknown): value is undefined;
+declare function isNullOrUndefined(value: unknown): value is null | undefined;
+declare function isBoolean(value: unknown): value is boolean;
+declare function isTruthy<T>(value: T | Falsy): value is T;
+declare function isFalsy(value: unknown): value is Falsy;
+declare function isDateLike(value: unknown): value is DateLike;
+declare const is: {
+  string: typeof isString;
+  nonEmptyString: typeof isNonEmptyString;
+  number: typeof isNumber;
+  positiveNumber: typeof isPositiveNumber;
+  record: typeof isRecord;
+  function: typeof isFunction;
+  class: typeof isClass;
+  null: typeof isNull;
+  undefined: typeof isUndefined;
+  nullOrUndefined: typeof isNullOrUndefined;
+  boolean: typeof isBoolean;
+  truthy: typeof isTruthy;
+  falsy: typeof isFalsy;
+  dateLike: typeof isDateLike;
+};
+//#endregion
+export { DateLike, Falsy, is, isBoolean, isClass, isDateLike, isFalsy, isFunction, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isPositiveNumber, isRecord, isString, isTruthy, isUndefined };

package/dist/guards.mjs

@@ -0,0 +1 @@
+function e(e){return typeof e==`string`}function t(t){return e(t)&&t.length>0}function n(e){return typeof e==`number`&&Number.isFinite(e)}function r(e){return n(e)&&e>0}function i(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function a(e){return typeof e==`function`}function o(e){return a(e)&&e.toString().startsWith(`class`)}function s(e){return e===null}function c(e){return e===void 0}function l(e){return s(e)||c(e)}function u(e){return typeof e==`boolean`}function d(e){return!!e}function f(e){return!e}function p(t){return t instanceof Date?h(t):n(t)||e(t)?h(new Date(t)):!1}const m={string:e,nonEmptyString:t,number:n,positiveNumber:r,record:i,function:a,class:o,null:s,undefined:c,nullOrUndefined:l,boolean:u,truthy:d,falsy:f,dateLike:p};function h(e){return!Number.isNaN(e.getTime())}export{m as is,u as isBoolean,o as isClass,p as isDateLike,f as isFalsy,a as isFunction,t as isNonEmptyString,s as isNull,l as isNullOrUndefined,n as isNumber,r as isPositiveNumber,i as isRecord,e as isString,d as isTruthy,c as isUndefined};

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.is=r.is,exports.isBoolean=r.isBoolean,exports.isClass=r.isClass,exports.isDateLike=r.isDateLike,exports.isFalsy=r.isFalsy,exports.isFunction=r.isFunction,exports.isNonEmptyString=r.isNonEmptyString,exports.isNull=r.isNull,exports.isNullOrUndefined=r.isNullOrUndefined,exports.isNumber=r.isNumber,exports.isOk=u.isOk,exports.isPositiveNumber=r.isPositiveNumber,exports.isRecord=r.isRecord,exports.isString=r.isString,exports.isTruthy=r.isTruthy,exports.isUndefined=r.isUndefined,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 { Arrayable, Awaitable, Class, Maybe, Nullable, Prettify, 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 { DateLike, Falsy, is, isBoolean, isClass, isDateLike, isFalsy, isFunction, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isPositiveNumber, isRecord, isString, isTruthy, isUndefined } 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 { Arrayable, Awaitable, BoundedQueue, BoundedQueueOverflow, Class, DateLike, Falsy, Flag, IBoundedQueueOptions, IConcurrencyOptions, IRetryOptions, IWeightedItem, Maybe, Nullable, Prettify, QueryObject, QueryValue, Queue, ResettableValue, Result, RetryJitter, SettledDetailed, URLLike, URLPath, abortAfter, allSettledDetailed, allSettledSuccessful, assume, average, cache, cast, clamp, err, inRange, is, isBoolean, isClass, isDateLike, isFalsy, isFunction, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isOk, isPositiveNumber, isRecord, isString, isTruthy, isUndefined, 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 { Arrayable, Awaitable, Class, Maybe, Nullable, Prettify, 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 { DateLike, Falsy, is, isBoolean, isClass, isDateLike, isFalsy, isFunction, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isPositiveNumber, isRecord, isString, isTruthy, isUndefined } 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 { Arrayable, Awaitable, BoundedQueue, BoundedQueueOverflow, Class, DateLike, Falsy, Flag, IBoundedQueueOptions, IConcurrencyOptions, IRetryOptions, IWeightedItem, Maybe, Nullable, Prettify, QueryObject, QueryValue, Queue, ResettableValue, Result, RetryJitter, SettledDetailed, URLLike, URLPath, abortAfter, allSettledDetailed, allSettledSuccessful, assume, average, cache, cast, clamp, err, inRange, is, isBoolean, isClass, isDateLike, isFalsy, isFunction, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isOk, isPositiveNumber, isRecord, isString, isTruthy, isUndefined, 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{is as a,isBoolean as o,isClass as s,isDateLike as c,isFalsy as l,isFunction as u,isNonEmptyString as d,isNull as f,isNullOrUndefined as p,isNumber as m,isPositiveNumber as h,isRecord as g,isString as _,isTruthy as v,isUndefined as y}from"./guards.mjs";import{RetryJitter as b,abortAfter as x,pollUntil as S,raceSignals as C,rejectionTimeout as w,retry as T,timeout as E,withAbort as D,withTimeout as O}from"./timing.mjs";import{allSettledDetailed as k,allSettledSuccessful as A,pMap as j,pool as M,sequential as N}from"./promise.mjs";import{lazy as P,lazyAsync as F}from"./lazy.mjs";import{average as I,clamp as L,inRange as R,roundTo as z,sum as B}from"./number.mjs";import{pickRandom as V,pickWeighted as H,randomFloat as U,randomInt as W}from"./random.mjs";import{Flag as G,ResettableValue as K,resettableLazy as q,resettableLazyAsync as J}from"./state.mjs";import{assume as Y,cast as X,err as Z,isOk as Q,mapErr as $,mapOk as ee,ok as te,tryCatchAsync as ne,typedEntries as re}from"./typing.mjs";import{URLPath as ie,url as ae}from"./url.mjs";export{e as BoundedQueue,t as BoundedQueueOverflow,G as Flag,n as Queue,K as ResettableValue,b as RetryJitter,ie as URLPath,x as abortAfter,k as allSettledDetailed,A as allSettledSuccessful,Y as assume,I as average,r as cache,X as cast,L as clamp,Z as err,R as inRange,a as is,o as isBoolean,s as isClass,c as isDateLike,l as isFalsy,u as isFunction,d as isNonEmptyString,f as isNull,p as isNullOrUndefined,m as isNumber,Q as isOk,h as isPositiveNumber,g as isRecord,_ as isString,v as isTruthy,y as isUndefined,P as lazy,F as lazyAsync,$ as mapErr,ee as mapOk,te as ok,i as once,j as pMap,V as pickRandom,H as pickWeighted,S as pollUntil,M as pool,C as raceSignals,U as randomFloat,W as randomInt,w as rejectionTimeout,q as resettableLazy,J as resettableLazyAsync,T as retry,z as roundTo,N as sequential,B as sum,E as timeout,ne as tryCatchAsync,re as typedEntries,ae as url,D as withAbort,O 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;