with-bottleneck 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Uladzimir Kasacheuski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// todo
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,OAAO"}

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 ehmpathy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "with-bottleneck",
+  "author": "ehmpathy",
+  "description": "rate limit and concurrency control utilities",
+  "version": "0.0.0",
+  "repository": "ehmpathy/with-bottleneck",
+  "homepage": "https://github.com/ehmpathy/with-bottleneck",
+  "keywords": [
+    "bottleneck",
+    "rate-limit",
+    "throttle",
+    "concurrency",
+    "limiter"
+  ],
+  "bugs": "https://github.com/ehmpathy/with-bottleneck/issues",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/dist"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@commitlint/cli": "19.5.0",
+    "@commitlint/config-conventional": "19.5.0",
+    "@swc/core": "1.15.3",
+    "@swc/jest": "0.2.39",
+    "@tsconfig/node-lts-strictest": "18.12.1",
+    "@tsconfig/node20": "20.1.5",
+    "@tsconfig/strictest": "2.0.5",
+    "@types/jest": "30.0.0",
+    "@types/node": "22.15.21",
+    "core-js": "3.26.1",
+    "cz-conventional-changelog": "3.3.0",
+    "declapract": "0.13.14",
+    "declapract-typescript-ehmpathy": "0.47.36",
+    "declastruct": "1.7.3",
+    "declastruct-github": "1.3.0",
+    "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",
+    "rhachet-brains-anthropic": "0.4.1",
+    "rhachet-brains-xai": "0.3.3",
+    "rhachet-roles-bhrain": "0.27.6",
+    "rhachet-roles-bhuild": "0.21.9",
+    "rhachet-roles-ehmpathy": "1.35.5",
+    "test-fns": "1.7.2",
+    "ts-jest": "29.1.3",
+    "ts-node": "10.9.2",
+    "tsc-alias": "1.8.10",
+    "tsx": "4.20.6",
+    "typescript": "5.4.5",
+    "yalc": "1.0.0-pre.53"
+  },
+  "config": {
+    "commitizen": {
+      "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"
+  }
+}

package/readme.md

@@ -0,0 +1,178 @@
+# with-bottleneck
+
+![test](https://github.com/ehmpathy/with-bottleneck/workflows/test/badge.svg)
+![publish](https://github.com/ehmpathy/with-bottleneck/workflows/publish/badge.svg)
+
+simple, ergonomic rate limit and concurrency control utilities
+
+# install
+
+```sh
+npm install with-bottleneck
+```
+
+# why
+
+don't spill your drink down your shirt — use a bottleneck to control the pour.
+
+- limit api calls to avoid rate limit bans
+- limit db connections to avoid saturation
+- limit concurrent requests to respect server capacity
+
+**bottleneck = intentional, precise flow control**
+
+# use
+
+## two usecases
+
+`withBottleneck` supports two patterns for where the bottleneck comes from:
+
+| usecase | bind time | bottleneck source | when |
+|---------|-----------|-------------------|------|
+| **per declaration** | declaration | static instance | global limits, scripts |
+| **per context** | call time | extracted from context | per-tenant, DI, testability |
+
+## usecase 1: per declaration
+
+bottleneck created once, bound at declaration. all calls share same instance.
+
+```ts
+import { withBottleneck, genBottleneck } from 'with-bottleneck';
+
+// create bottleneck at module level
+const bottleneck = genBottleneck({
+  concurrency: 5,
+  velocity: { quantity: 10, duration: { seconds: 1 } }
+});
+
+// bind to function at declaration
+const fetchLimited = withBottleneck(fetch, { bottleneck });
+
+// all calls share the same bottleneck
+await fetchLimited('https://api.example.com/a');
+await fetchLimited('https://api.example.com/b');
+await fetchLimited('https://api.example.com/c');
+```
+
+## usecase 2: per context
+
+bottleneck resolved from context at call time. each call can use different bottleneck.
+
+```ts
+import { withBottleneck, genBottleneck, Bottleneck } from 'with-bottleneck';
+
+// declare function — bottleneck comes from context
+const fetchLimited = withBottleneck(fetch, {
+  bottleneck: (_input, context) => context.usecase.bottleneck,
+});
+
+// create different bottlenecks for different tenants
+const customerBottleneck = genBottleneck({
+  concurrency: 2,
+  velocity: { quantity: 5, duration: { seconds: 1 } }
+});
+const adminBottleneck = genBottleneck({
+  concurrency: 10,
+  velocity: { quantity: 100, duration: { seconds: 1 } }
+});
+
+// each call uses bottleneck from its context
+await fetchLimited('https://api.example.com/data', {
+  usecase: { bottleneck: customerBottleneck }
+});
+
+await fetchLimited('https://api.example.com/data', {
+  usecase: { bottleneck: adminBottleneck }
+});
+```
+
+# exports
+
+| export | purpose |
+|--------|---------|
+| `Bottleneck` | type — the bottleneck instance shape |
+| `genBottleneck(config)` | create `Bottleneck` instance |
+| `withBottleneck(fn, { bottleneck })` | wrap fn with bottleneck |
+
+# genBottleneck config
+
+```ts
+interface BottleneckConfig {
+  /** max concurrent operations (how many at once) */
+  concurrency?: number;
+
+  /** rate limit (how many per time) */
+  velocity?: {
+    /** how many operations */
+    quantity: number;
+    /** per duration (IsoDuration from iso-time) */
+    duration: IsoDuration;
+  };
+}
+```
+
+examples:
+
+```ts
+// concurrency only: max 5 at once
+genBottleneck({ concurrency: 5 });
+
+// velocity only: max 10 per second
+genBottleneck({ velocity: { quantity: 10, duration: { seconds: 1 } } });
+
+// both: max 5 at once, max 100 per minute
+genBottleneck({
+  concurrency: 5,
+  velocity: { quantity: 100, duration: { minutes: 1 } }
+});
+```
+
+# Bottleneck shape
+
+```ts
+interface Bottleneck {
+  /** the inner semaphore — for manual acquire/release */
+  semaphore: {
+    acquire: () => Promise<void>;
+    release: () => void;
+    queued: number;
+    active: number;
+  };
+
+  /** schedule fn for execution — acquires, runs, releases automatically */
+  schedule: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+```
+
+direct semaphore access for complex flows:
+
+```ts
+// manual control
+await bottleneck.semaphore.acquire();
+try {
+  const a = await fetchA();
+  const b = await fetchB(a);
+  return transform(b);
+} finally {
+  bottleneck.semaphore.release();
+}
+
+// check state
+if (bottleneck.semaphore.queued > 100) {
+  throw new Error('queue too deep, backpressure');
+}
+```
+
+# why "bottleneck"
+
+a bottleneck is not a defect — it's precision design.
+
+the neck of a beer bottle is *intentional*: controls pour rate, prevents spills, enables clean pour.
+
+same here: we *want* a bottleneck to control flow.
+
+# background
+
+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.