@da440dil/cbr 0.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x, 16.x, 18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run test:coverage
+
+      - name: Coveralls
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Anatoly Demidovich
+
+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/README.md

@@ -0,0 +1,138 @@
+# @da440dil/cbr
+
+![GitHub Actions](https://github.com/da440dil/js-cbr/actions/workflows/ci.yml/badge.svg)
+[![Coverage Status](https://coveralls.io/repos/github/da440dil/js-cbr/badge.svg?branch=main)](https://coveralls.io/github/da440dil/js-cbr?branch=main)
+
+[Circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html).
+
+[Example](./examples/decorator.ts) decorator ([typescript](https://www.typescriptlang.org/) [version](https://github.com/microsoft/TypeScript/releases/tag/v5.0.2) >= 5):
+```typescript
+import { promisify } from 'util';
+import http from 'http';
+import { CircuitBreaker } from '@da440dil/cbr';
+
+// Create the circuit breaker which switches from "Closed" to "Open" state on first error,
+// from "Open" to "HalfOpen" state after 100ms, from "HalfOpen" to "Closed" state on first success.
+const breaker = new CircuitBreaker({ errorThreshold: 1, resetTimeout: 100, successThreshold: 1 });
+
+class Client {
+	private url = 'http://localhost:3000';
+	// Decorate the class method with circuit breaker logic.
+	@CircuitBreaker.Breakable(breaker)
+	public get(): Promise<string> {
+		return new Promise((resolve, reject) => {
+			const req = http.get(this.url, (res) => {
+				if (res.statusCode !== 200) {
+					res.resume();
+					return reject(new Error(`Failed with statusCode ${String(res.statusCode)}`));
+				}
+				let data = '';
+				res.on('data', (chunk) => { data += chunk; });
+				res.on('end', () => { resolve(data); });
+			});
+			req.on('error', reject);
+		});
+	}
+}
+const client = new Client();
+const get = async () => {
+	try {
+		const data = await client.get();
+		console.log(`DATA: ${data}`);
+	} catch (err) {
+		console.log(err instanceof Error ? `ERROR: ${(err).message}` : err);
+	}
+};
+
+let x = 0;
+const server = http.createServer((_, res) => {
+	const statusCode = x > 2 || x % 2 ? 418 : 200; // { 0 => 200, 1 => 418, 2 => 200, ... => 418 }
+	res.writeHead(statusCode).end(`{ x: ${x} }`);
+	x++;
+});
+server.listen(3000);
+
+async function main() {
+	for (let i = 0; i < 3; i++) {
+		await get();
+	}
+	await promisify(setTimeout)(100);
+	await get();
+	// Output:
+	// DATA: { x: 0 }
+	// ERROR: Failed with statusCode 418
+	// ERROR: Circuit broken
+	// DATA: { x: 2 }
+}
+
+main().then(() => { process.exit(0); }).catch((err) => { console.error(err); process.exit(1); });
+```
+```
+npm run file examples/decorator.ts
+```
+
+[Example](./examples/function.ts) function:
+```typescript
+import { promisify } from 'util';
+import http from 'http';
+import { CircuitBreaker } from '@da440dil/cbr';
+
+class Client {
+	// Create the circuit breaker which switches from "Closed" to "Open" state on first error,
+	// from "Open" to "HalfOpen" state after 100ms, from "HalfOpen" to "Closed" state on first success.
+	private breaker = new CircuitBreaker({ errorThreshold: 1, resetTimeout: 100, successThreshold: 1 });
+	private url = 'http://localhost:3000';
+	public get(): Promise<string> {
+		// Execute the function with circuit breaker logic.
+		return this.breaker.exec(() => {
+			return new Promise((resolve, reject) => {
+				const req = http.get(this.url, (res) => {
+					if (res.statusCode !== 200) {
+						res.resume();
+						return reject(new Error(`Failed with statusCode ${String(res.statusCode)}`));
+					}
+					let data = '';
+					res.on('data', (chunk) => { data += chunk; });
+					res.on('end', () => { resolve(data); });
+				});
+				req.on('error', reject);
+			});
+		});
+	}
+}
+const client = new Client();
+const get = async () => {
+	try {
+		const data = await client.get();
+		console.log(`DATA: ${data}`);
+	} catch (err) {
+		console.log(err instanceof Error ? `ERROR: ${(err).message}` : err);
+	}
+};
+
+let x = 0;
+const server = http.createServer((_, res) => {
+	const statusCode = x > 2 || x % 2 ? 418 : 200; // { 0 => 200, 1 => 418, 2 => 200, ... => 418 }
+	res.writeHead(statusCode).end(`{ x: ${x} }`);
+	x++;
+});
+server.listen(3000);
+
+async function main() {
+	for (let i = 0; i < 3; i++) {
+		await get();
+	}
+	await promisify(setTimeout)(100);
+	await get();
+	// Output:
+	// DATA: { x: 0 }
+	// ERROR: Failed with statusCode 418
+	// ERROR: Circuit broken
+	// DATA: { x: 2 }
+}
+
+main().then(() => { process.exit(0); }).catch((err) => { console.error(err); process.exit(1); });
+```
+```
+npm run file examples/function.ts
+```

package/lib/CircuitBreaker.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+export declare class CircuitBreaker extends EventEmitter {
+    /** Decorate a class method with circuit breaker logic. */
+    static Breakable<This, Args extends unknown[], Return>(breaker: CircuitBreaker): (fn: (this: This, ...args: Args) => Promise<Return>, _: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>) => (this: This, ...args: Args) => Promise<Return>;
+    private state;
+    private requestCount;
+    private failureCount;
+    private successCount;
+    private expiresAt;
+    private errorThreshold;
+    private resetTimeout;
+    private successThreshold;
+    constructor({ errorThreshold, resetTimeout, successThreshold, isBreakable }: {
+        /** The number of consecutive errors, if reached the circuit state switches from "Closed" to "Open". By default equals 1. */
+        errorThreshold?: number;
+        /** The period of time, when passed the circuit state switches from "Open" to "HalfOpen". */
+        resetTimeout: number;
+        /** The number of consecutive successes, if reached the circuit state switches from "HalfOpen" to "Closed". By default equals 1. */
+        successThreshold?: number;
+        /** Error checking function. Answers the question: should the error be taken into account or not. By default, all errors are taken into account. */
+        isBreakable?: (err: unknown) => boolean;
+    });
+    /** Execute a function with circuit breaker logic. */
+    exec<T>(fn: () => Promise<T>): Promise<T>;
+    private broken;
+    private success;
+    private failure;
+    private setExpiresAt;
+    private setState;
+    private isBreakable;
+}

package/lib/CircuitBreaker.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+const events_1 = require("events");
+const CircuitState_1 = require("./CircuitState");
+const CircuitError_1 = require("./CircuitError");
+class CircuitBreaker extends events_1.EventEmitter {
+    /** Decorate a class method with circuit breaker logic. */
+    static Breakable(breaker) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        return (fn, _) => {
+            return function breakable(...args) {
+                return breaker.exec(() => fn.apply(this, args));
+            };
+        };
+    }
+    constructor({ errorThreshold = 1, resetTimeout, successThreshold = 1, isBreakable }) {
+        super();
+        this.state = CircuitState_1.CircuitState.Closed;
+        this.requestCount = 0;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.expiresAt = 0;
+        this.errorThreshold = errorThreshold;
+        this.resetTimeout = resetTimeout;
+        this.successThreshold = successThreshold;
+        if (isBreakable) {
+            this.isBreakable = isBreakable;
+        }
+    }
+    /** Execute a function with circuit breaker logic. */
+    async exec(fn) {
+        if (this.broken()) {
+            throw new CircuitError_1.CircuitError();
+        }
+        try {
+            const v = await fn();
+            this.success();
+            return v;
+        }
+        catch (err) {
+            if (this.isBreakable(err)) {
+                this.failure();
+            }
+            throw err;
+        }
+    }
+    broken() {
+        if (this.state === CircuitState_1.CircuitState.Open) {
+            if (this.expiresAt < Date.now()) {
+                this.setState(CircuitState_1.CircuitState.HalfOpen);
+                this.expiresAt = 0;
+            }
+            else {
+                return true;
+            }
+        }
+        else if (this.state === CircuitState_1.CircuitState.HalfOpen && this.requestCount >= this.successThreshold) {
+            return true;
+        }
+        this.requestCount++;
+        return false;
+    }
+    success() {
+        if (this.state !== CircuitState_1.CircuitState.Open) {
+            this.successCount++;
+            if (this.state === CircuitState_1.CircuitState.HalfOpen && this.successCount >= this.successThreshold) {
+                this.setState(CircuitState_1.CircuitState.Closed);
+            }
+        }
+    }
+    failure() {
+        if (this.state === CircuitState_1.CircuitState.Closed) {
+            this.failureCount++;
+            if (this.failureCount >= this.errorThreshold) {
+                this.setState(CircuitState_1.CircuitState.Open);
+                this.setExpiresAt();
+            }
+        }
+        else if (this.state === CircuitState_1.CircuitState.HalfOpen) {
+            this.setState(CircuitState_1.CircuitState.Open);
+            this.setExpiresAt();
+        }
+    }
+    setExpiresAt() {
+        this.expiresAt = Date.now() + this.resetTimeout;
+    }
+    setState(state) {
+        this.state = state;
+        this.requestCount = 0;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.emit('state', this.state);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    isBreakable(_) {
+        return true;
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;

package/lib/CircuitError.d.ts

@@ -0,0 +1,4 @@
+/** Service unavailable: either the circuit state is "Open", or the circuit state is "HalfOpen" and the number of requests exceeds the limit. */
+export declare const CircuitBroken = "Circuit broken";
+export declare class CircuitError extends Error {
+}

package/lib/CircuitError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitError = exports.CircuitBroken = void 0;
+/** Service unavailable: either the circuit state is "Open", or the circuit state is "HalfOpen" and the number of requests exceeds the limit. */
+exports.CircuitBroken = 'Circuit broken';
+class CircuitError extends Error {
+}
+exports.CircuitError = CircuitError;
+CircuitError.prototype.name = 'CircuitError';
+CircuitError.prototype.message = exports.CircuitBroken;

package/lib/CircuitState.d.ts

@@ -0,0 +1,10 @@
+/** Circuit state: "Closed", "Open", "HalfOpen". */
+export declare const CircuitState: {
+    /** Requests are allowed. Switches to "Open" state if errors threshold is reached. */
+    readonly Closed: 0;
+    /** Requests are disallowed. Switches to "HalfOpen" state after reset timeout passed. */
+    readonly Open: 1;
+    /** Limited number of requests are allowed. Switches to "Closed" state if success threshold is reached. */
+    readonly HalfOpen: 2;
+};
+export type CircuitState = typeof CircuitState[keyof typeof CircuitState];

package/lib/CircuitState.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitState = void 0;
+/** Circuit state: "Closed", "Open", "HalfOpen". */
+exports.CircuitState = {
+    /** Requests are allowed. Switches to "Open" state if errors threshold is reached. */
+    Closed: 0,
+    /** Requests are disallowed. Switches to "HalfOpen" state after reset timeout passed. */
+    Open: 1,
+    /** Limited number of requests are allowed. Switches to "Closed" state if success threshold is reached. */
+    HalfOpen: 2
+};

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { CircuitBreaker } from './CircuitBreaker';
+export { CircuitError, CircuitBroken } from './CircuitError';

package/lib/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBroken = exports.CircuitError = exports.CircuitBreaker = void 0;
+var CircuitBreaker_1 = require("./CircuitBreaker");
+Object.defineProperty(exports, "CircuitBreaker", { enumerable: true, get: function () { return CircuitBreaker_1.CircuitBreaker; } });
+var CircuitError_1 = require("./CircuitError");
+Object.defineProperty(exports, "CircuitError", { enumerable: true, get: function () { return CircuitError_1.CircuitError; } });
+Object.defineProperty(exports, "CircuitBroken", { enumerable: true, get: function () { return CircuitError_1.CircuitBroken; } });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@da440dil/cbr",
+  "version": "0.0.0",
+  "description": "Circuit breaker",
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "jest --runInBand",
+    "test:coverage": "jest --runInBand --coverage",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint --ext .ts src",
+    "file": "ts-node"
+  },
+  "keywords": [
+    "circuit breaker",
+    "circuit-breaker",
+    "fail-fast",
+    "circuit",
+    "breaker"
+  ],
+  "author": "Anatoly Demidovich",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@typescript-eslint/eslint-plugin": "^5.57.0",
+    "@typescript-eslint/parser": "^5.57.0",
+    "eslint": "^8.37.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4"
+  }
+}