with-bottleneck 0.0.0 → 0.1.0

package/dist/domain.objects/Bottleneck.d.ts

@@ -0,0 +1,60 @@
+import type { IsoDuration } from 'iso-time';
+/**
+ * .what = semaphore interface for concurrency control
+ * .why = limits simultaneous operations via slot-based acquire/release
+ */
+export interface BottleneckSemaphore {
+    /** acquire a slot, blocks until available */
+    acquire: () => Promise<void>;
+    /** release a slot */
+    release: () => void;
+    /** count of queued waiters */
+    readonly queued: number;
+    /** count of active slots */
+    readonly active: number;
+}
+/**
+ * .what = throttle interface for velocity control
+ * .why = limits operations per time via token bucket
+ */
+export interface BottleneckThrottle {
+    /** acquire a token, blocks until available */
+    acquire: () => Promise<void>;
+    /** count of available tokens */
+    readonly tokens: number;
+}
+/**
+ * .what = bottleneck instance with semaphore and schedule
+ * .why = provides unified concurrency and velocity control
+ */
+export interface Bottleneck {
+    /** the inner semaphore for concurrency control */
+    readonly semaphore: BottleneckSemaphore;
+    /**
+     * schedule fn for execution with bottleneck control
+     *
+     * acquires semaphore slot, then throttle token if configured,
+     * runs function, then releases semaphore slot (always, even on error)
+     */
+    schedule: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+/**
+ * .what = limits configuration for genBottleneck
+ * .why = specifies concurrency and/or velocity constraints
+ */
+export interface BottleneckLimits {
+    /** max concurrent operations (how many at once) */
+    concurrency?: number;
+    /** rate limit (how many per time) */
+    velocity?: {
+        /** how many operations */
+        quantity: number;
+        /** per duration */
+        duration: IsoDuration;
+    };
+}
+/**
+ * .what = supplier type for bottleneck resolution
+ * .why = enables static instance or per-call derivation from context
+ */
+export type BottleneckSupplier<TInput, TContext> = Bottleneck | ((input: TInput, context: TContext) => Bottleneck);

package/dist/domain.objects/Bottleneck.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Bottleneck.js.map

package/dist/domain.objects/Bottleneck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Bottleneck.js","sourceRoot":"","sources":["../../src/domain.objects/Bottleneck.ts"],"names":[],"mappings":""}

package/dist/domain.operations/genBottleneck/asConcurrencyLimit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * .what = derives concurrency limit from optional input
+ * .why = extracts default logic for unlimited concurrency
+ */
+export declare const asConcurrencyLimit: (input: {
+    concurrency: number | undefined;
+}) => number;

package/dist/domain.operations/genBottleneck/asConcurrencyLimit.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asConcurrencyLimit = void 0;
+/**
+ * .what = derives concurrency limit from optional input
+ * .why = extracts default logic for unlimited concurrency
+ */
+const asConcurrencyLimit = (input) => input.concurrency ?? Infinity;
+exports.asConcurrencyLimit = asConcurrencyLimit;
+//# sourceMappingURL=asConcurrencyLimit.js.map

package/dist/domain.operations/genBottleneck/asConcurrencyLimit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asConcurrencyLimit.js","sourceRoot":"","sources":["../../../src/domain.operations/genBottleneck/asConcurrencyLimit.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACI,MAAM,kBAAkB,GAAG,CAAC,KAElC,EAAU,EAAE,CAAC,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC;AAF/B,QAAA,kBAAkB,sBAEa"}

package/dist/domain.operations/genBottleneck/assertLimitsValid.d.ts

@@ -0,0 +1,8 @@
+import type { BottleneckLimits } from '../../domain.objects/Bottleneck';
+/**
+ * .what = validates bottleneck limits configuration
+ * .why = fails fast on invalid limits with actionable error
+ */
+export declare const assertLimitsValid: (input: {
+    limits: BottleneckLimits | null;
+}) => void;

package/dist/domain.operations/genBottleneck/assertLimitsValid.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertLimitsValid = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const iso_time_1 = require("iso-time");
+/**
+ * .what = validates bottleneck limits configuration
+ * .why = fails fast on invalid limits with actionable error
+ */
+const assertLimitsValid = (input) => {
+    const { limits } = input;
+    // null limits are valid (defaults apply)
+    if (limits === null)
+        return;
+    // validate concurrency: must be positive integer or Infinity
+    if (limits.concurrency !== undefined && limits.concurrency <= 0)
+        throw new helpful_errors_1.BadRequestError('concurrency must be positive', {
+            field: 'concurrency',
+            value: limits.concurrency,
+            hint: 'use a positive integer for concurrency limit, or omit for unlimited',
+        });
+    if (limits.concurrency !== undefined &&
+        limits.concurrency !== Infinity &&
+        !Number.isInteger(limits.concurrency))
+        throw new helpful_errors_1.BadRequestError('concurrency must be an integer', {
+            field: 'concurrency',
+            value: limits.concurrency,
+            hint: 'use a positive integer for concurrency limit, or Infinity for unlimited',
+        });
+    // validate velocity.quantity: must be positive integer
+    if (limits.velocity !== undefined && limits.velocity.quantity <= 0)
+        throw new helpful_errors_1.BadRequestError('velocity.quantity must be positive', {
+            field: 'velocity.quantity',
+            value: limits.velocity.quantity,
+            hint: 'use a positive integer for velocity quantity',
+        });
+    if (limits.velocity !== undefined &&
+        !Number.isInteger(limits.velocity.quantity))
+        throw new helpful_errors_1.BadRequestError('velocity.quantity must be an integer', {
+            field: 'velocity.quantity',
+            value: limits.velocity.quantity,
+            hint: 'use a positive integer for velocity quantity',
+        });
+    // validate velocity.duration: must be present and positive
+    if (limits.velocity !== undefined && limits.velocity.duration === undefined)
+        throw new helpful_errors_1.BadRequestError('velocity.duration is required', {
+            field: 'velocity.duration',
+            value: limits.velocity.duration,
+            hint: 'specify duration as { seconds: 1 } or ISO 8601 string',
+        });
+    if (limits.velocity !== undefined &&
+        (0, iso_time_1.toMilliseconds)(limits.velocity.duration) <= 0)
+        throw new helpful_errors_1.BadRequestError('velocity.duration must be positive', {
+            field: 'velocity.duration',
+            value: limits.velocity.duration,
+            hint: 'specify duration as { seconds: 1 } or ISO 8601 string',
+        });
+};
+exports.assertLimitsValid = assertLimitsValid;
+//# sourceMappingURL=assertLimitsValid.js.map

package/dist/domain.operations/genBottleneck/assertLimitsValid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertLimitsValid.js","sourceRoot":"","sources":["../../../src/domain.operations/genBottleneck/assertLimitsValid.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AACjD,uCAA0C;AAI1C;;;GAGG;AACI,MAAM,iBAAiB,GAAG,CAAC,KAEjC,EAAQ,EAAE;IACT,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAEzB,yCAAyC;IACzC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO;IAE5B,6DAA6D;IAC7D,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC;QAC7D,MAAM,IAAI,gCAAe,CAAC,8BAA8B,EAAE;YACxD,KAAK,EAAE,aAAa;YACpB,KAAK,EAAE,MAAM,CAAC,WAAW;YACzB,IAAI,EAAE,qEAAqE;SAC5E,CAAC,CAAC;IAEL,IACE,MAAM,CAAC,WAAW,KAAK,SAAS;QAChC,MAAM,CAAC,WAAW,KAAK,QAAQ;QAC/B,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC;QAErC,MAAM,IAAI,gCAAe,CAAC,gCAAgC,EAAE;YAC1D,KAAK,EAAE,aAAa;YACpB,KAAK,EAAE,MAAM,CAAC,WAAW;YACzB,IAAI,EAAE,yEAAyE;SAChF,CAAC,CAAC;IAEL,uDAAuD;IACvD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC;QAChE,MAAM,IAAI,gCAAe,CAAC,oCAAoC,EAAE;YAC9D,KAAK,EAAE,mBAAmB;YAC1B,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;YAC/B,IAAI,EAAE,8CAA8C;SACrD,CAAC,CAAC;IAEL,IACE,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC7B,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAE3C,MAAM,IAAI,gCAAe,CAAC,sCAAsC,EAAE;YAChE,KAAK,EAAE,mBAAmB;YAC1B,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;YAC/B,IAAI,EAAE,8CAA8C;SACrD,CAAC,CAAC;IAEL,2DAA2D;IAC3D,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS;QACzE,MAAM,IAAI,gCAAe,CAAC,+BAA+B,EAAE;YACzD,KAAK,EAAE,mBAAmB;YAC1B,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;YAC/B,IAAI,EAAE,uDAAuD;SAC9D,CAAC,CAAC;IAEL,IACE,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC7B,IAAA,yBAAc,EAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAE7C,MAAM,IAAI,gCAAe,CAAC,oCAAoC,EAAE;YAC9D,KAAK,EAAE,mBAAmB;YAC1B,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;YAC/B,IAAI,EAAE,uDAAuD;SAC9D,CAAC,CAAC;AACP,CAAC,CAAC;AA9DW,QAAA,iBAAiB,qBA8D5B"}

package/dist/domain.operations/genBottleneck/scheduleWithLimits.d.ts

@@ -0,0 +1,30 @@
+import type { BottleneckSemaphore, BottleneckThrottle } from '../../domain.objects/Bottleneck';
+/**
+ * .what = schedules fn with semaphore and optional throttle control
+ * .why = encapsulates acquire/run/release pattern with guaranteed cleanup
+ *
+ * .note = order-dependence (intentional architecture)
+ *
+ * semaphore is acquired before throttle. when both are configured,
+ * a slot is held while blocked for velocity tokens. this is intentional:
+ * it prevents more than N operations from queued at the velocity limit.
+ *
+ * without this order, unlimited operations could pile up blocked for
+ * tokens, which leads to memory pressure. the order-dependence is a
+ * deliberate trade-off:
+ *
+ * | order           | memory           | behavior                      |
+ * |-----------------|------------------|-------------------------------|
+ * | semaphore first | bounded (N)      | velocity wait holds slot      |
+ * | throttle first  | unbounded        | unlimited queue at throttle   |
+ *
+ * if you need independent limits, compose two separate bottlenecks.
+ *
+ * .mitigation = the order is documented here and in genBottleneck.
+ *               tests verify the bounded memory behavior explicitly.
+ */
+export declare const scheduleWithLimits: <T>(input: {
+    fn: () => Promise<T>;
+    semaphore: BottleneckSemaphore;
+    throttle: BottleneckThrottle | null;
+}) => Promise<T>;

package/dist/domain.operations/genBottleneck/scheduleWithLimits.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduleWithLimits = void 0;
+/**
+ * .what = schedules fn with semaphore and optional throttle control
+ * .why = encapsulates acquire/run/release pattern with guaranteed cleanup
+ *
+ * .note = order-dependence (intentional architecture)
+ *
+ * semaphore is acquired before throttle. when both are configured,
+ * a slot is held while blocked for velocity tokens. this is intentional:
+ * it prevents more than N operations from queued at the velocity limit.
+ *
+ * without this order, unlimited operations could pile up blocked for
+ * tokens, which leads to memory pressure. the order-dependence is a
+ * deliberate trade-off:
+ *
+ * | order           | memory           | behavior                      |
+ * |-----------------|------------------|-------------------------------|
+ * | semaphore first | bounded (N)      | velocity wait holds slot      |
+ * | throttle first  | unbounded        | unlimited queue at throttle   |
+ *
+ * if you need independent limits, compose two separate bottlenecks.
+ *
+ * .mitigation = the order is documented here and in genBottleneck.
+ *               tests verify the bounded memory behavior explicitly.
+ */
+const scheduleWithLimits = async (input) => {
+    // acquire semaphore (blocks if at concurrency limit)
+    await input.semaphore.acquire();
+    try {
+        // acquire throttle token if configured (blocks if at velocity limit)
+        if (input.throttle) {
+            await input.throttle.acquire();
+        }
+        // run function
+        return await input.fn();
+    }
+    finally {
+        // always release semaphore slot
+        input.semaphore.release();
+    }
+};
+exports.scheduleWithLimits = scheduleWithLimits;
+//# sourceMappingURL=scheduleWithLimits.js.map

package/dist/domain.operations/genBottleneck/scheduleWithLimits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduleWithLimits.js","sourceRoot":"","sources":["../../../src/domain.operations/genBottleneck/scheduleWithLimits.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,MAAM,kBAAkB,GAAG,KAAK,EAAK,KAI3C,EAAc,EAAE;IACf,qDAAqD;IACrD,MAAM,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAEhC,IAAI,CAAC;QACH,qEAAqE;QACrE,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACjC,CAAC;QAED,eAAe;QACf,OAAO,MAAM,KAAK,CAAC,EAAE,EAAE,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,gCAAgC;QAChC,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC,CAAC;AApBW,QAAA,kBAAkB,sBAoB7B"}

package/dist/domain.operations/genBottleneck.d.ts

@@ -0,0 +1,6 @@
+import type { Bottleneck, BottleneckLimits } from '../domain.objects/Bottleneck';
+/**
+ * .what = creates a bottleneck instance with concurrency and/or velocity limits
+ * .why = provides unified rate limit and concurrency control
+ */
+export declare const genBottleneck: (input?: BottleneckLimits | null) => Bottleneck;

package/dist/domain.operations/genBottleneck.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genBottleneck = void 0;
+const asConcurrencyLimit_1 = require("./genBottleneck/asConcurrencyLimit");
+const assertLimitsValid_1 = require("./genBottleneck/assertLimitsValid");
+const scheduleWithLimits_1 = require("./genBottleneck/scheduleWithLimits");
+const genSemaphore_1 = require("./semaphore/genSemaphore");
+const genThrottle_1 = require("./throttle/genThrottle");
+/**
+ * .what = creates a bottleneck instance with concurrency and/or velocity limits
+ * .why = provides unified rate limit and concurrency control
+ */
+const genBottleneck = (input) => {
+    // validate limits
+    (0, assertLimitsValid_1.assertLimitsValid)({ limits: input ?? null });
+    // derive concurrency limit (Infinity if not configured)
+    const concurrency = (0, asConcurrencyLimit_1.asConcurrencyLimit)({ concurrency: input?.concurrency });
+    const semaphore = (0, genSemaphore_1.genSemaphore)({ concurrency });
+    // derive throttle (null if velocity not configured)
+    const throttle = (0, genThrottle_1.genThrottle)({ velocity: input?.velocity ?? null });
+    // compose schedule with limits
+    const schedule = async (fn) => (0, scheduleWithLimits_1.scheduleWithLimits)({ fn, semaphore, throttle });
+    return {
+        semaphore,
+        schedule,
+    };
+};
+exports.genBottleneck = genBottleneck;
+//# sourceMappingURL=genBottleneck.js.map

package/dist/domain.operations/genBottleneck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genBottleneck.js","sourceRoot":"","sources":["../../src/domain.operations/genBottleneck.ts"],"names":[],"mappings":";;;AAIA,2EAAwE;AACxE,yEAAsE;AACtE,2EAAwE;AACxE,2DAAwD;AACxD,wDAAqD;AAErD;;;GAGG;AACI,MAAM,aAAa,GAAG,CAAC,KAA+B,EAAc,EAAE;IAC3E,kBAAkB;IAClB,IAAA,qCAAiB,EAAC,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC;IAE7C,wDAAwD;IACxD,MAAM,WAAW,GAAG,IAAA,uCAAkB,EAAC,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC5E,MAAM,SAAS,GAAG,IAAA,2BAAY,EAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IAEhD,oDAAoD;IACpD,MAAM,QAAQ,GAAG,IAAA,yBAAW,EAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,IAAI,IAAI,EAAE,CAAC,CAAC;IAEpE,+BAA+B;IAC/B,MAAM,QAAQ,GAAG,KAAK,EAAK,EAAoB,EAAc,EAAE,CAC7D,IAAA,uCAAkB,EAAC,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAElD,OAAO;QACL,SAAS;QACT,QAAQ;KACT,CAAC;AACJ,CAAC,CAAC;AAnBW,QAAA,aAAa,iBAmBxB"}

package/dist/domain.operations/semaphore/genSemaphore.d.ts

@@ -0,0 +1,34 @@
+import type { BottleneckSemaphore } from '../../domain.objects/Bottleneck';
+/**
+ * .what = creates a semaphore for concurrency control
+ * .why = limits simultaneous operations via slot-based acquire/release
+ *
+ * .exemption = rule.require.immutable-vars (scoped mutation zone)
+ *
+ * semaphores are fundamentally stateful — they track available resources
+ * and a queue of waiters. there is no immutable alternative:
+ *
+ * | alternative considered | why it fails                        |
+ * |------------------------|-------------------------------------|
+ * | immutable counter      | cannot share state across acquire() |
+ * | functional reduce      | no lock/wake mechanism              |
+ * | external store         | same mutation, different location   |
+ *
+ * this matches the canonical semaphore (Dijkstra, 1965) and all major
+ * implementations (async-sema, p-queue, bottleneck npm).
+ *
+ * .safety = single-threaded JS event loop
+ *
+ * javascript guarantees synchronous blocks complete atomically.
+ * the read-modify-write (if < limit then count += 1) is safe because:
+ * - no preemption mid-block
+ * - async boundaries (await) are explicit
+ * - queue mutations are synchronous
+ *
+ * .boundaries = unsafe in worker threads or shared memory
+ *
+ * must not share via SharedArrayBuffer. for distributed, use redis/etcd.
+ */
+export declare const genSemaphore: (input: {
+    concurrency: number;
+}) => BottleneckSemaphore;

package/dist/domain.operations/semaphore/genSemaphore.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genSemaphore = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = creates a semaphore for concurrency control
+ * .why = limits simultaneous operations via slot-based acquire/release
+ *
+ * .exemption = rule.require.immutable-vars (scoped mutation zone)
+ *
+ * semaphores are fundamentally stateful — they track available resources
+ * and a queue of waiters. there is no immutable alternative:
+ *
+ * | alternative considered | why it fails                        |
+ * |------------------------|-------------------------------------|
+ * | immutable counter      | cannot share state across acquire() |
+ * | functional reduce      | no lock/wake mechanism              |
+ * | external store         | same mutation, different location   |
+ *
+ * this matches the canonical semaphore (Dijkstra, 1965) and all major
+ * implementations (async-sema, p-queue, bottleneck npm).
+ *
+ * .safety = single-threaded JS event loop
+ *
+ * javascript guarantees synchronous blocks complete atomically.
+ * the read-modify-write (if < limit then count += 1) is safe because:
+ * - no preemption mid-block
+ * - async boundaries (await) are explicit
+ * - queue mutations are synchronous
+ *
+ * .boundaries = unsafe in worker threads or shared memory
+ *
+ * must not share via SharedArrayBuffer. for distributed, use redis/etcd.
+ */
+const genSemaphore = (input) => {
+    // .mutation-zone = semaphore state (scoped, const reference with mutable properties)
+    const state = {
+        active: 0,
+        queue: [],
+    };
+    /**
+     * acquire a slot, blocks until available
+     */
+    const acquire = () => {
+        // slot available: proceed immediately
+        if (state.active < input.concurrency) {
+            state.active += 1;
+            return Promise.resolve();
+        }
+        // at capacity: queue and wait
+        return new Promise((onSlotAvailable) => {
+            state.queue.push(onSlotAvailable);
+        });
+    };
+    /**
+     * release a slot, allows next waiter to proceed
+     */
+    const release = () => {
+        // guard: release without acquire is a bug
+        if (state.active === 0) {
+            throw new helpful_errors_1.UnexpectedCodePathError('release called without prior acquire', { active: 0, hint: 'ensure acquire() is awaited before release()' });
+        }
+        // release slot
+        state.active -= 1;
+        // wake next waiter if any
+        const next = state.queue.shift();
+        if (next) {
+            state.active += 1;
+            next();
+        }
+    };
+    return {
+        acquire,
+        release,
+        get queued() {
+            return state.queue.length;
+        },
+        get active() {
+            return state.active;
+        },
+    };
+};
+exports.genSemaphore = genSemaphore;
+//# sourceMappingURL=genSemaphore.js.map

package/dist/domain.operations/semaphore/genSemaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genSemaphore.js","sourceRoot":"","sources":["../../../src/domain.operations/semaphore/genSemaphore.ts"],"names":[],"mappings":";;;AAAA,mDAAyD;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACI,MAAM,YAAY,GAAG,CAAC,KAE5B,EAAuB,EAAE;IACxB,qFAAqF;IACrF,MAAM,KAAK,GAAG;QACZ,MAAM,EAAE,CAAC;QACT,KAAK,EAAE,EAAuB;KAC/B,CAAC;IAEF;;OAEG;IACH,MAAM,OAAO,GAAG,GAAkB,EAAE;QAClC,sCAAsC;QACtC,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;YAClB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,8BAA8B;QAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,eAAe,EAAE,EAAE;YACrC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF;;OAEG;IACH,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,0CAA0C;QAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,wCAAuB,CAC/B,sCAAsC,EACtC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,8CAA8C,EAAE,CACpE,CAAC;QACJ,CAAC;QAED,eAAe;QACf,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QAElB,0BAA0B;QAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,EAAE,CAAC;YACT,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;YAClB,IAAI,EAAE,CAAC;QACT,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,OAAO;QACP,IAAI,MAAM;YACR,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;QAC5B,CAAC;QACD,IAAI,MAAM;YACR,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC,CAAC;AA1DW,QAAA,YAAY,gBA0DvB"}

package/dist/domain.operations/throttle/genThrottle.d.ts

@@ -0,0 +1,48 @@
+import type { IsoDuration } from 'iso-time';
+import type { BottleneckThrottle } from '../../domain.objects/Bottleneck';
+/**
+ * .what = creates a throttle for velocity control
+ * .why = limits operations per time via token bucket algorithm
+ *
+ * .exemption = rule.require.immutable-vars (scoped mutation zone)
+ *
+ * token bucket requires mutable state: token count, waiter queue, refill
+ * timer. there is no immutable alternative for rate limits:
+ *
+ * | alternative considered | why it fails                         |
+ * |------------------------|--------------------------------------|
+ * | immutable counter      | cannot share token state over time   |
+ * | functional timestamp   | no queue/wake mechanism              |
+ * | external store         | same mutation, different location    |
+ *
+ * this matches the canonical token bucket (Leaky Bucket, 1986) and
+ * all major implementations (bottleneck npm, limiter, p-ratelimit).
+ *
+ * .safety = single-threaded JS event loop
+ *
+ * javascript guarantees synchronous blocks complete atomically:
+ * - tokens -= 1 and queue.shift() execute in same sync block
+ * - setTimeout callback runs in fresh event loop turn
+ * - no preemption between read and write
+ *
+ * .timer = setTimeout precision (intentional trade-off)
+ *
+ * setTimeout is not precise — delays may exceed requested duration under
+ * CPU load. this means actual rate may be lower than configured (more
+ * time between refills). this is safe: we never exceed the configured
+ * rate, only potentially undershoot.
+ *
+ * | precision need     | solution                           |
+ * |--------------------|------------------------------------|
+ * | approximate (here) | setTimeout, safe undershoot        |
+ * | high precision     | setImmediate + hrtime (not needed) |
+ * | distributed        | redis-based (rate-limiter-flexible)|
+ *
+ * .boundaries = unsafe in worker threads or shared memory
+ */
+export declare const genThrottle: (input: {
+    velocity: {
+        quantity: number;
+        duration: IsoDuration;
+    } | null;
+}) => BottleneckThrottle | null;

package/dist/domain.operations/throttle/genThrottle.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genThrottle = void 0;
+const iso_time_1 = require("iso-time");
+/**
+ * .what = creates a throttle for velocity control
+ * .why = limits operations per time via token bucket algorithm
+ *
+ * .exemption = rule.require.immutable-vars (scoped mutation zone)
+ *
+ * token bucket requires mutable state: token count, waiter queue, refill
+ * timer. there is no immutable alternative for rate limits:
+ *
+ * | alternative considered | why it fails                         |
+ * |------------------------|--------------------------------------|
+ * | immutable counter      | cannot share token state over time   |
+ * | functional timestamp   | no queue/wake mechanism              |
+ * | external store         | same mutation, different location    |
+ *
+ * this matches the canonical token bucket (Leaky Bucket, 1986) and
+ * all major implementations (bottleneck npm, limiter, p-ratelimit).
+ *
+ * .safety = single-threaded JS event loop
+ *
+ * javascript guarantees synchronous blocks complete atomically:
+ * - tokens -= 1 and queue.shift() execute in same sync block
+ * - setTimeout callback runs in fresh event loop turn
+ * - no preemption between read and write
+ *
+ * .timer = setTimeout precision (intentional trade-off)
+ *
+ * setTimeout is not precise — delays may exceed requested duration under
+ * CPU load. this means actual rate may be lower than configured (more
+ * time between refills). this is safe: we never exceed the configured
+ * rate, only potentially undershoot.
+ *
+ * | precision need     | solution                           |
+ * |--------------------|------------------------------------|
+ * | approximate (here) | setTimeout, safe undershoot        |
+ * | high precision     | setImmediate + hrtime (not needed) |
+ * | distributed        | redis-based (rate-limiter-flexible)|
+ *
+ * .boundaries = unsafe in worker threads or shared memory
+ */
+const genThrottle = (input) => {
+    // guard: no velocity = no throttle
+    if (!input.velocity)
+        return null;
+    const { quantity, duration } = input.velocity;
+    const durationMs = (0, iso_time_1.toMilliseconds)(duration);
+    // .mutation-zone = token bucket state (scoped, const reference with mutable properties)
+    const state = {
+        tokens: quantity,
+        queue: [],
+        refillTimer: null,
+    };
+    /**
+     * schedule refill after duration passes
+     */
+    const scheduleRefill = () => {
+        // guard: only one refill timer at a time
+        if (state.refillTimer !== null)
+            return;
+        state.refillTimer = setTimeout(() => {
+            // refill tokens
+            state.tokens = quantity;
+            state.refillTimer = null;
+            // wake queued waiters (up to available tokens)
+            while (state.queue.length > 0 && state.tokens > 0) {
+                const next = state.queue.shift();
+                if (next) {
+                    state.tokens -= 1;
+                    next();
+                }
+            }
+            // if still waiters, schedule another refill
+            if (state.queue.length > 0) {
+                scheduleRefill();
+            }
+        }, durationMs);
+    };
+    /**
+     * acquire a token, blocks until available
+     */
+    const acquire = () => {
+        // token available: proceed immediately
+        if (state.tokens > 0) {
+            state.tokens -= 1;
+            // start refill timer if this is first token consumed
+            if (state.tokens < quantity && state.refillTimer === null) {
+                scheduleRefill();
+            }
+            return Promise.resolve();
+        }
+        // no tokens: queue and wait for refill
+        return new Promise((onTokenAvailable) => {
+            state.queue.push(onTokenAvailable);
+        });
+    };
+    return {
+        acquire,
+        get tokens() {
+            return state.tokens;
+        },
+    };
+};
+exports.genThrottle = genThrottle;
+//# sourceMappingURL=genThrottle.js.map

package/dist/domain.operations/throttle/genThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genThrottle.js","sourceRoot":"","sources":["../../../src/domain.operations/throttle/genThrottle.ts"],"names":[],"mappings":";;;AACA,uCAA0C;AAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACI,MAAM,WAAW,GAAG,CAAC,KAK3B,EAA6B,EAAE;IAC9B,mCAAmC;IACnC,IAAI,CAAC,KAAK,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC;IAC9C,MAAM,UAAU,GAAG,IAAA,yBAAc,EAAC,QAAQ,CAAC,CAAC;IAE5C,wFAAwF;IACxF,MAAM,KAAK,GAAG;QACZ,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,EAAuB;QAC9B,WAAW,EAAE,IAA4C;KAC1D,CAAC;IAEF;;OAEG;IACH,MAAM,cAAc,GAAG,GAAS,EAAE;QAChC,yCAAyC;QACzC,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI;YAAE,OAAO;QAEvC,KAAK,CAAC,WAAW,GAAG,UAAU,CAAC,GAAG,EAAE;YAClC,gBAAgB;YAChB,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC;YACxB,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;YAEzB,+CAA+C;YAC/C,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;gBACjC,IAAI,IAAI,EAAE,CAAC;oBACT,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;oBAClB,IAAI,EAAE,CAAC;gBACT,CAAC;YACH,CAAC;YAED,4CAA4C;YAC5C,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,cAAc,EAAE,CAAC;YACnB,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC;IAEF;;OAEG;IACH,MAAM,OAAO,GAAG,GAAkB,EAAE;QAClC,uCAAuC;QACvC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;YAElB,qDAAqD;YACrD,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;gBAC1D,cAAc,EAAE,CAAC;YACnB,CAAC;YAED,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,uCAAuC;QACvC,OAAO,IAAI,OAAO,CAAC,CAAC,gBAAgB,EAAE,EAAE;YACtC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,IAAI,MAAM;YACR,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC,CAAC;AA3EW,QAAA,WAAW,eA2EtB"}

package/dist/domain.operations/withBottleneck/getBottleneckFromSupplier.d.ts

@@ -0,0 +1,9 @@
+import type { Bottleneck } from '../../domain.objects/Bottleneck';
+/**
+ * .what = derives bottleneck from supplier or static instance
+ * .why = transforms polymorphic bottleneck option to concrete instance
+ */
+export declare const getBottleneckFromSupplier: <TArgs extends unknown[]>(input: {
+    bottleneck: Bottleneck | ((...args: TArgs) => Bottleneck);
+    args: TArgs;
+}) => Bottleneck;

package/dist/domain.operations/withBottleneck/getBottleneckFromSupplier.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBottleneckFromSupplier = void 0;
+/**
+ * .what = derives bottleneck from supplier or static instance
+ * .why = transforms polymorphic bottleneck option to concrete instance
+ */
+const getBottleneckFromSupplier = (input) => {
+    // static instance: return directly
+    if (typeof input.bottleneck !== 'function') {
+        return input.bottleneck;
+    }
+    // supplier function: invoke with args
+    return input.bottleneck(...input.args);
+};
+exports.getBottleneckFromSupplier = getBottleneckFromSupplier;
+//# sourceMappingURL=getBottleneckFromSupplier.js.map

package/dist/domain.operations/withBottleneck/getBottleneckFromSupplier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getBottleneckFromSupplier.js","sourceRoot":"","sources":["../../../src/domain.operations/withBottleneck/getBottleneckFromSupplier.ts"],"names":[],"mappings":";;;AAEA;;;GAGG;AACI,MAAM,yBAAyB,GAAG,CAA0B,KAGlE,EAAc,EAAE;IACf,mCAAmC;IACnC,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC,UAAU,CAAC;IAC1B,CAAC;IAED,sCAAsC;IACtC,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC,CAAC;AAXW,QAAA,yBAAyB,6BAWpC"}

package/dist/domain.operations/withBottleneck.d.ts

@@ -0,0 +1,8 @@
+import type { Bottleneck } from '../domain.objects/Bottleneck';
+/**
+ * .what = wraps function with bottleneck control
+ * .why = enables declarative rate limit and concurrency control via HOF
+ */
+export declare const withBottleneck: <TLogic extends (...args: Parameters<TLogic>) => Promise<Awaited<ReturnType<TLogic>>>>(logic: TLogic, options: {
+    bottleneck: Bottleneck | ((...args: Parameters<TLogic>) => Bottleneck);
+}) => TLogic;

package/dist/domain.operations/withBottleneck.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withBottleneck = void 0;
+const getBottleneckFromSupplier_1 = require("./withBottleneck/getBottleneckFromSupplier");
+/**
+ * .what = wraps function with bottleneck control
+ * .why = enables declarative rate limit and concurrency control via HOF
+ */
+const withBottleneck = (logic, options) => {
+    const wrapped = async (...args) => {
+        // derive bottleneck from static instance or supplier function
+        const bottleneck = (0, getBottleneckFromSupplier_1.getBottleneckFromSupplier)({
+            bottleneck: options.bottleneck,
+            args,
+        });
+        // delegate to bottleneck.schedule
+        /**
+         * .cast = sdk boundary (external org code boundary)
+         * .why = TypeScript cannot infer that Promise<T> from schedule matches Awaited<ReturnType<TLogic>>
+         *        because schedule is generic over T while TLogic is the outer constraint
+         * .safe = schedule returns Promise<T> where T is the return type of logic(...args)
+         *         which is exactly Awaited<ReturnType<TLogic>> by construction
+         * .removal = requires higher-kinded types or const type parameters
+         *            to flow TLogic's return type through schedule's generic
+         *            blocked on microsoft/TypeScript#1213
+         */
+        return bottleneck.schedule(() => logic(...args));
+    };
+    /**
+     * .cast = sdk boundary (external org code boundary)
+     * .why = preserves exact TLogic type for consumers
+     *        TypeScript cannot infer that wrapped satisfies TLogic because:
+     *        - TLogic may have additional properties (e.g., displayName)
+     *        - the wrapped signature is derived via Parameters<>/ReturnType<>
+     * .safe = wrapped has identical call signature to TLogic
+     * .removal = requires TypeScript to support exact function type inference
+     *            blocked on microsoft/TypeScript#34319 (exactOptionalPropertyTypes)
+     *            until then, this cast is the standard HOF pattern
+     */
+    return wrapped;
+};
+exports.withBottleneck = withBottleneck;
+//# sourceMappingURL=withBottleneck.js.map

package/dist/domain.operations/withBottleneck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withBottleneck.js","sourceRoot":"","sources":["../../src/domain.operations/withBottleneck.ts"],"names":[],"mappings":";;;AACA,0FAAuF;AAEvF;;;GAGG;AACI,MAAM,cAAc,GAAG,CAK5B,KAAa,EACb,OAEC,EACO,EAAE;IACV,MAAM,OAAO,GAAG,KAAK,EACnB,GAAG,IAAwB,EACW,EAAE;QACxC,8DAA8D;QAC9D,MAAM,UAAU,GAAG,IAAA,qDAAyB,EAAC;YAC3C,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,IAAI;SACL,CAAC,CAAC;QAEH,kCAAkC;QAClC;;;;;;;;;WASG;QACH,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAE9C,CAAC;IACJ,CAAC,CAAC;IAEF;;;;;;;;;;OAUG;IACH,OAAO,OAAiB,CAAC;AAC3B,CAAC,CAAC;AA/CW,QAAA,cAAc,kBA+CzB"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Bottleneck, BottleneckLimits, BottleneckSemaphore, BottleneckSupplier, } from './domain.objects/Bottleneck';
+export { genBottleneck } from './domain.operations/genBottleneck';
+export { withBottleneck } from './domain.operations/withBottleneck';

package/dist/index.js

@@ -1,3 +1,9 @@
 "use strict";
-// todo
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withBottleneck = exports.genBottleneck = void 0;
+// domain operations
+var genBottleneck_1 = require("./domain.operations/genBottleneck");
+Object.defineProperty(exports, "genBottleneck", { enumerable: true, get: function () { return genBottleneck_1.genBottleneck; } });
+var withBottleneck_1 = require("./domain.operations/withBottleneck");
+Object.defineProperty(exports, "withBottleneck", { enumerable: true, get: function () { return withBottleneck_1.withBottleneck; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,OAAO"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAOA,oBAAoB;AACpB,mEAAkE;AAAzD,8GAAA,aAAa,OAAA;AACtB,qEAAoE;AAA3D,gHAAA,cAAc,OAAA"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "with-bottleneck",
   "author": "ehmpathy",
   "description": "rate limit and concurrency control utilities",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "repository": "ehmpathy/with-bottleneck",
   "homepage": "https://github.com/ehmpathy/with-bottleneck",
   "keywords": [
@@ -21,7 +21,46 @@
   "files": [
     "/dist"
   ],
-  "dependencies": {},
+  "scripts": {
+    "build:ts": "tsc -p ./tsconfig.build.json",
+    "commit:with-cli": "npx cz",
+    "fix:format:biome": "biome check --write",
+    "fix:format": "npm run fix:format:biome",
+    "fix:lint": "biome check --write",
+    "fix": "npm run fix:format && npm run fix:lint",
+    "build:clean:bun": "rm -f ./bin/*.bc",
+    "build:clean:tsc": "(chmod -R u+w dist 2>/dev/null || true) && rm -rf dist/",
+    "build:clean": "npm run build:clean:tsc && npm run build:clean:bun",
+    "build:compile:tsc": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
+    "build:compile": "npm run build:compile:tsc && npm run build:compile:bun --if-present",
+    "build": "npm run build:clean && npm run build:compile && npm run build:complete --if-present",
+    "test:auth": "[ \"$ECHO\" = 'true' ] && echo '. .agent/repo=.this/role=any/skills/use.apikeys.sh' || . .agent/repo=.this/role=any/skills/use.apikeys.sh",
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
+    "test:types": "tsc -p ./tsconfig.json --noEmit",
+    "test:format:biome": "biome format",
+    "test:format": "npm run test:format:biome",
+    "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
+    "test:lint:biome": "biome check --diagnostic-level=error",
+    "test:lint:biome:all": "biome check",
+    "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
+    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test": "eval $(ECHO=true npm run --silent test:auth) && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "prepush": "npm run test && npm run build",
+    "prepublish": "npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "prepare:husky": "husky install && chmod ug+x .husky/*",
+    "prepare:rhachet": "rhachet init --hooks --roles behaver mechanic reviewer",
+    "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
+    "upgrade:rhachet": "rhachet upgrade"
+  },
+  "dependencies": {
+    "helpful-errors": "1.5.3",
+    "iso-time": "1.11.7"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.3.8",
     "@commitlint/cli": "19.5.0",
@@ -42,7 +81,6 @@
     "depcheck": "1.4.3",
     "domain-objects": "0.31.9",
     "esbuild-register": "3.6.0",
-    "helpful-errors": "1.5.3",
     "husky": "8.0.3",
     "jest": "30.2.0",
     "rhachet": "1.41.9",
@@ -64,39 +102,5 @@
       "path": "./node_modules/cz-conventional-changelog"
     }
   },
-  "scripts": {
-    "build:ts": "tsc -p ./tsconfig.build.json",
-    "commit:with-cli": "npx cz",
-    "fix:format:biome": "biome check --write",
-    "fix:format": "npm run fix:format:biome",
-    "fix:lint": "biome check --write",
-    "fix": "npm run fix:format && npm run fix:lint",
-    "build:clean:bun": "rm -f ./bin/*.bc",
-    "build:clean:tsc": "(chmod -R u+w dist 2>/dev/null || true) && rm -rf dist/",
-    "build:clean": "npm run build:clean:tsc && npm run build:clean:bun",
-    "build:compile:tsc": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
-    "build:compile": "npm run build:compile:tsc && npm run build:compile:bun --if-present",
-    "build": "npm run build:clean && npm run build:compile && npm run build:complete --if-present",
-    "test:auth": "[ \"$ECHO\" = 'true' ] && echo '. .agent/repo=.this/role=any/skills/use.apikeys.sh' || . .agent/repo=.this/role=any/skills/use.apikeys.sh",
-    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
-    "test:types": "tsc -p ./tsconfig.json --noEmit",
-    "test:format:biome": "biome format",
-    "test:format": "npm run test:format:biome",
-    "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
-    "test:lint:biome": "biome check --diagnostic-level=error",
-    "test:lint:biome:all": "biome check",
-    "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
-    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
-    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
-    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
-    "test": "eval $(ECHO=true npm run --silent test:auth) && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
-    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
-    "prepush": "npm run test && npm run build",
-    "prepublish": "npm run build",
-    "preversion": "npm run prepush",
-    "postversion": "git push origin HEAD --tags --no-verify",
-    "prepare:husky": "husky install && chmod ug+x .husky/*",
-    "prepare:rhachet": "rhachet init --hooks --roles behaver mechanic reviewer",
-    "upgrade:rhachet": "rhachet upgrade"
-  }
-}
+  "packageManager": "pnpm@10.24.0"
+}

package/readme.md

@@ -176,3 +176,25 @@ same here: we *want* a bottleneck to control flow.
 pour one out to the og, [`bottleneck`](https://www.npmjs.com/package/bottleneck), who paved the intuitive frame — abandoned since 2020.
 
 we pick up where bottleneck left off; now, with wrappers and dependency injection.
+
+# defaults
+
+`genBottleneck()` with no config returns an unlimited bottleneck:
+- `concurrency: Infinity` — no concurrency limit
+- `velocity: null` — no rate limit
+
+this is intentional:
+- tests run instantly without delays
+- inject unlimited bottleneck for test mocks
+- only configure limits where you need them
+
+```ts
+// no config = unlimited = fast tests
+const testBottleneck = genBottleneck();
+
+await Promise.all([
+  wrapped({ n: 1 }, { bottleneck: testBottleneck }),
+  wrapped({ n: 2 }, { bottleneck: testBottleneck }),
+  wrapped({ n: 3 }, { bottleneck: testBottleneck }),
+]);
+```