@theshelf/connection 0.3.1

package/README.md

@@ -0,0 +1,106 @@
+
+# Connection | The Shelf
+
+The connection package provides connection resilience for other TheShelf packages by monitoring and restoring connections to external services. It wraps a connectable (such as a database or event broker) and manages its connection lifecycle, ensuring robust error handling and automatic recovery.
+
+## Features
+
+- **Automatic Connection Monitoring:** Periodically checks and restores lost connections.
+- **Graceful Error Handling:** Connection errors are caught, logged, and do not block application startup.
+- **Configurable Monitoring Interval:** Set custom timeouts for connection checks.
+- **State Management:** Tracks connection states (`DISCONNECTED`, `CONNECTING`, `CONNECTED`, `DISCONNECTING`).
+- **Pluggable Logging:** Integrates with any logger implementing the `@theshelf/logging` interface.
+
+## Installation
+
+```bash
+npm install @theshelf/connection
+```
+
+## Configuration
+
+Create a `ConnectionManager` by providing a configuration object:
+
+```ts
+const manager = new ConnectionManager({
+    name: 'DATABASE', // Unique name for logging
+    connectable, // Must implement Connectable interface (all TheShelf packages are compatible)
+    logger, // Must implement Logger interface
+    monitoringTimeout: 3000 // Optional, default: 3000ms
+});
+```
+
+**Configuration Properties:**
+
+- `name` (string): Unique identifier for the connection (used in logs).
+- `connectable` (Connectable): The object to manage (must implement `connect()` and `disconnect()` methods, and a `connected` property).
+- `logger` (Logger): Logger instance for info, warn, error, and debug messages.
+- `monitoringTimeout` (number, optional): Interval in milliseconds for connection monitoring (default: 3000).
+
+## API Reference
+
+### `ConnectionManager`
+
+#### Properties
+
+- `name`: Returns the name of the connection.
+- `state`: Returns the current connection state.
+
+#### Methods
+
+- `connect(): Promise<void>`
+    - Initiates connection. If already connected or connecting, logs a warning.
+    - Starts monitoring after successful connection.
+- `disconnect(): Promise<void>`
+    - Disconnects the connectable. If already disconnected or disconnecting, logs a warning.
+    - Stops monitoring after disconnect.
+
+## Monitoring & Recovery
+
+After connecting, the manager periodically checks the connection status:
+
+- If the connection is lost, it logs a warning and attempts to reconnect automatically.
+- Monitoring can be started/stopped manually via `connect()` and `disconnect()`.
+
+## Error Handling
+
+- **Connection Errors:**
+    - Errors during `connect()` are caught, logged, and do not throw (non-blocking).
+    - The manager will keep trying to reconnect at each monitoring interval.
+- **Disconnection Errors:**
+    - Errors during `disconnect()` are logged and re-thrown.
+
+## Example Usage
+
+```ts
+import ConnectionManager from '@theshelf/connection';
+import { database } from './your-database-instance';
+import { logger } from './your-logger-instance';
+
+const manager = new ConnectionManager({
+    name: 'DATABASE',
+    connectable: database, // a @theshelf/database instance
+    monitoringTimeout: 3000, // optional, default: 3000
+    logger // must be a @theshelf/logging instance
+});
+
+// Connect and start monitoring
+await manager.connect();
+
+// ... your application logic ...
+
+// Disconnect and stop monitoring
+await manager.disconnect();
+```
+
+## Connectable Interface
+
+Your connectable object should implement the following interface:
+
+```ts
+interface Connectable {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    connected: boolean;
+}
+```

package/dist/ConnectionManager.d.ts

@@ -0,0 +1,18 @@
+import type Logger from '@theshelf/logging';
+import type { State } from './definitions/constants.js';
+import type { Connectable } from './definitions/interfaces.js';
+type Configuration = {
+    readonly name: string;
+    readonly connectable: Connectable;
+    readonly logger: Logger;
+    readonly monitoringTimeout?: number;
+};
+export default class ConnectionManager {
+    #private;
+    constructor(configuration: Configuration);
+    get name(): string;
+    get state(): State;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+}
+export {};

package/dist/ConnectionManager.js

@@ -0,0 +1,116 @@
+import { States } from './definitions/constants.js';
+const DEFAULT_MONITORING_TIMEOUT = 3000;
+export default class ConnectionManager {
+    #name;
+    #connectable;
+    #logger;
+    #timeoutDuration;
+    #state = States.DISCONNECTED;
+    #monitorTimeout;
+    #connectPromise;
+    #disconnectPromise;
+    constructor(configuration) {
+        this.#name = configuration.name;
+        this.#connectable = configuration.connectable;
+        this.#logger = configuration.logger;
+        this.#timeoutDuration = configuration.monitoringTimeout ?? DEFAULT_MONITORING_TIMEOUT;
+    }
+    get name() { return this.#name; }
+    get state() { return this.#state; }
+    async connect() {
+        if (this.#connectPromise !== undefined) {
+            this.#logger.logWarn(this.#createLogMessage('connect already in progress'));
+            return this.#connectPromise;
+        }
+        if (this.#state !== States.DISCONNECTED) {
+            this.#logger.logWarn(this.#createLogMessage('connect in invalid state'));
+            return;
+        }
+        await this.#connect();
+        this.#startMonitoring();
+    }
+    async disconnect() {
+        if (this.#disconnectPromise !== undefined) {
+            this.#logger.logWarn(this.#createLogMessage('disconnect already in progress'));
+            return this.#disconnectPromise;
+        }
+        if (this.#state !== States.CONNECTED) {
+            this.#logger.logWarn(this.#createLogMessage('disconnect in invalid state'));
+            return;
+        }
+        this.#stopMonitoring();
+        await this.#disconnect();
+    }
+    async #connect() {
+        this.#state = States.CONNECTING;
+        try {
+            this.#connectPromise = this.#connectable.connect();
+            await this.#connectPromise;
+            this.#state = States.CONNECTED;
+            this.#logger.logInfo(this.#createLogMessage('connected successfully'));
+        }
+        catch (error) {
+            this.#state = States.DISCONNECTED;
+            this.#logger.logError(this.#createLogMessage('connection failure'), error);
+            // The error isn't re-thrown to make it non-blocking, and let the monitoring do its work.
+        }
+        finally {
+            this.#connectPromise = undefined;
+        }
+    }
+    async #disconnect() {
+        this.#state = States.DISCONNECTING;
+        try {
+            this.#disconnectPromise = this.#connectable.disconnect();
+            await this.#disconnectPromise;
+            this.#state = States.DISCONNECTED;
+            this.#logger.logInfo(this.#createLogMessage('disconnected successfully'));
+        }
+        catch (error) {
+            this.#state = States.CONNECTED;
+            this.#logger.logError(this.#createLogMessage('disconnection failure'), error);
+            throw error;
+        }
+        finally {
+            this.#disconnectPromise = undefined;
+        }
+    }
+    #startMonitoring() {
+        if (this.#monitorTimeout !== undefined) {
+            this.#logger.logWarn(this.#createLogMessage('monitoring already started'));
+            return;
+        }
+        this.#scheduleMonitoring();
+        this.#logger.logInfo(this.#createLogMessage('monitoring started'));
+    }
+    #scheduleMonitoring() {
+        this.#monitorTimeout = setTimeout(async () => {
+            await this.#monitorConnection();
+            this.#scheduleMonitoring();
+        }, this.#timeoutDuration);
+    }
+    #stopMonitoring() {
+        if (this.#monitorTimeout === undefined) {
+            this.#logger.logWarn(this.#createLogMessage('monitoring already stopped'));
+            return;
+        }
+        clearTimeout(this.#monitorTimeout);
+        this.#monitorTimeout = undefined;
+        this.#logger.logInfo(this.#createLogMessage('monitoring stopped'));
+    }
+    async #monitorConnection() {
+        this.#logger.logDebug(this.#createLogMessage('monitoring connection'));
+        if (this.#connectable.connected) {
+            return;
+        }
+        if (this.#connectPromise !== undefined) {
+            return this.#connectPromise;
+        }
+        this.#logger.logWarn(this.#createLogMessage('connection lost'));
+        this.#state = States.DISCONNECTED;
+        return this.#connect();
+    }
+    #createLogMessage(message) {
+        return `[CONNECTION][${this.#name}] ${message}`;
+    }
+}

package/dist/definitions/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const States: {
+    readonly DISCONNECTED: "DISCONNECTED";
+    readonly CONNECTING: "CONNECTING";
+    readonly CONNECTED: "CONNECTED";
+    readonly DISCONNECTING: "DISCONNECTING";
+};
+export type State = typeof States[keyof typeof States];

package/dist/definitions/constants.js

@@ -0,0 +1,6 @@
+export const States = {
+    DISCONNECTED: 'DISCONNECTED',
+    CONNECTING: 'CONNECTING',
+    CONNECTED: 'CONNECTED',
+    DISCONNECTING: 'DISCONNECTING'
+};

package/dist/definitions/interfaces.d.ts

@@ -0,0 +1,5 @@
+export interface Connectable {
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/definitions/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './definitions/constants.js';
+export type * from './definitions/constants.js';
+export type * from './definitions/interfaces.js';
+export { default } from './ConnectionManager.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './definitions/constants.js';
+export { default } from './ConnectionManager.js';

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@theshelf/connection",
+  "private": false,
+  "version": "0.3.1",
+  "type": "module",
+  "repository": {
+    "url": "git+https://github.com/MaskingTechnology/theshelf.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test-coverage": "vitest run --coverage",
+    "lint": "eslint",
+    "review": "npm run build && npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "peerDependencies": {
+    "@theshelf/logging": "^0.3.0"
+  }
+}