@biorate/connector 3.0.2 → 3.1.1

package/README.md

@@ -1,49 +1,209 @@
-# Connector
+# @biorate/connector
 
-Connector interface
+Abstract base class for creating typed, config‑driven connection managers backed by `@biorate/inversion` and `@biorate/config`.
 
-### Examples:
+## Features
 
-```ts
-import { Connector, IConnector } from '../..';
-import { inject, container, Types, Core } from '@biorate/inversion';
-import { IConfig, Config } from '@biorate/config';
+- **Abstract `Connector<C, R>`** — define `connect(config): Promise<R>` for any resource.
+- **Config‑driven** — reads an array of connection configs from `this.namespace` in `@biorate/config`.
+- **Auto‑connect** — on `@init()`, creates all connections defined in config.
+- **Named connections** — access by name via `.connection(name)` or `.get(name)`.
+- **Current connection** — first config entry becomes the default; switch via `.use(name)`.
+- **Error handling** — typed errors for missing or empty connections.
 
-export class Connection {
-  public name: string;
+## Installation
 
-  public constructor(name: string) {
-    this.name = name;
-  }
+```bash
+pnpm add @biorate/connector
+```
+
+Requires `@biorate/config`, `@biorate/errors`, `@biorate/inversion`.
+
+## Quick start
+
+```ts
+import { Connector } from '@biorate/connector';
+
+class Connection {
+  constructor(public name: string) {}
 }
 
-export class TestConnector extends Connector<{ name: string }, Connection> {
-  protected namespace = 'TestConnector';
+class MyConnector extends Connector<{ name: string }, Connection> {
+  protected namespace = 'MyConnector';
 
-  protected async connect(config) {
+  protected async connect(config: { name: string }) {
     return new Connection(config.name);
   }
 }
+```
+
+With DI:
+
+```ts
+import { Core, container, Types } from '@biorate/inversion';
+import { IConfig, Config } from '@biorate/config';
 
-export class Root extends Core() {
-  @inject(TestConnector) public connector: IConnector<{ name: string }, Connection>;
+class Root extends Core() {
+  @inject(MyConnector) public connector: MyConnector;
 }
 
 container.bind(Types.Config).to(Config).inSingletonScope();
-container.bind(TestConnector).toSelf().inSingletonScope();
+container.bind(MyConnector).toSelf().inSingletonScope();
 container.bind(Root).toSelf().inSingletonScope();
 
 container.get<IConfig>(Types.Config).merge({
-  TestConnector: [{ name: 'test-connection' }],
+  MyConnector: [{ name: 'db-1' }, { name: 'db-2' }],
 });
 
 (async () => {
   const root = container.get<Root>(Root);
   await root.$run();
-  console.log(root.connector.connection('test-connection')); // Connection { name: 'test-connection' }
+
+  console.log(root.connector.connection('db-1')); // Connection { name: 'db-1' }
+  console.log(root.connector.current);            // Connection { name: 'db-1' }
+
+  root.connector.use('db-2');
+  console.log(root.connector.current);            // Connection { name: 'db-2' }
 })();
 ```
 
+## API Reference
+
+### `Connector<C, R>` abstract class
+
+| Member                    | Type                          | Description                                    |
+|---------------------------|-------------------------------|------------------------------------------------|
+| `namespace` (abstract)    | `string`                      | Config key — array of `C` objects.             |
+| `connect(config)` (abstract) | `(config: C) => Promise<R>`  | Create a single connection.                    |
+| `current`                 | `R \| undefined`              | Currently selected connection.                 |
+| `connections`             | `Map<string, R>`              | All created connections (name → instance).     |
+| `create(config)`          | `(config: C) => Promise<R>`  | Create connection if not already cached.       |
+| `connection(name?)`       | `(name?: string) => R`        | Get connection by name (or current).           |
+| `get(name?)`              | `(name?: string) => R`        | Alias for `connection()`.                      |
+| `use(name)`               | `(name: string) => void`      | Switch current connection.                     |
+| `initialize()`            | `@init()`                     | Reads config array, creates all connections.   |
+
+### Config interface
+
+```ts
+interface IConnectorConfig {
+  name: string;  // connection identifier (unique per connector)
+  // … plus any additional fields for your resource
+}
+```
+
+### Errors
+
+| Error                              | Condition                                        |
+|------------------------------------|--------------------------------------------------|
+| `ConnectorConnectionNotExistsError`| Calling `connection(name)` / `use(name)` with unknown name. |
+| `ConnectorEmptyConnectionsError`   | Calling `connection()` when no connections exist.             |
+
+## Usage patterns
+
+### Single connection
+
+```ts
+class MyConnector extends Connector<{ name: string; host: string; port: number }, Client> {
+  protected namespace = 'MyConnector';
+
+  protected async connect(config: { name: string; host: string; port: number }) {
+    const client = new Client();
+    await client.connect(config.host, config.port);
+    return client;
+  }
+}
+```
+
+Config:
+
+```json
+{
+  "MyConnector": [{ "name": "default", "host": "localhost", "port": 5432 }]
+}
+```
+
+### Multi‑connection (read replicas)
+
+```ts
+{
+  "MyConnector": [
+    { "name": "primary",   "host": "db-1.internal", "port": 5432 },
+    { "name": "replica-1", "host": "db-2.internal", "port": 5432 },
+    { "name": "replica-2", "host": "db-3.internal", "port": 5432 },
+  ]
+}
+```
+
+```ts
+// Switch for read operations:
+connector.use('replica-1');
+const data = await connector.current.query('SELECT …');
+
+// Switch back for writes:
+connector.use('primary');
+```
+
+### Dynamic connection creation
+
+```ts
+class MyConnector extends Connector<{ name: string; url: string }, Resource> {
+  protected namespace = 'MyConnector';
+  protected async connect(config: { name: string; url: string }) {
+    return new Resource(config.url);
+  }
+}
+
+// At runtime:
+await connector.create({ name: 'ad-hoc', url: 'https://…' });
+const resource = connector.connection('ad-hoc');
+```
+
+### Type override for config
+
+```ts
+interface RedisConfig extends IConnectorConfig {
+  host: string;
+  port: number;
+  db: number;
+}
+
+class RedisConnector extends Connector<RedisConfig, RedisClient> {
+  protected namespace = 'RedisConnector';
+  protected async connect(config: RedisConfig) {
+    return new RedisClient({ host: config.host, port: config.port, db: config.db });
+  }
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                   Connector                  │  abstract class
+├─────────────────────────────────────────────┤
+│  namespace: string  ─── config key          │
+│  #connections: Map<name, R>                 │
+│  #current: R         ─── selected           │
+│                                              │
+│  @init() initialize()                        │
+│    ├── for each config in namespace[]        │
+│    │   └── this.create(config)               │
+│    │       └── this.connect(config)  ← abstract
+│    └── set #current = first entry            │
+│                                              │
+│  connection(name?) → R                       │
+│  use(name) → void                            │
+│  create(config) → Promise<R>                 │
+└─────────────────────────────────────────────┘
+         ▲             extends
+         │
+┌─────────────────────────────────────────────┐
+│         RedisConnector / MongoConnector …      │
+│         connect(config) → Promise<R>         │
+└─────────────────────────────────────────────┘
+```
+
 ### Learn
 
 - Documentation can be found here - [docs](https://biorate.github.io/core/modules/connector.html).
@@ -52,7 +212,7 @@ container.get<IConfig>(Types.Config).merge({
 
 See the [CHANGELOG](https://github.com/biorate/core/blob/master/packages/%40biorate/connector/CHANGELOG.md)
 
-### License
+## License
 
 [MIT](https://github.com/biorate/core/blob/master/packages/%40biorate/connector/LICENSE)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biorate/connector",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "description": "Connector interface",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -45,10 +45,10 @@
   "keywords": [],
   "author": "llevkin",
   "license": "MIT",
-  "gitHead": "ca18c1129712e77a6ec8fb2033a54f94e5620ce0",
+  "gitHead": "ff1dcf14a733ce8004ca582d2c421a2154ce97cb",
   "dependencies": {
-    "@biorate/config": "3.1.0",
-    "@biorate/errors": "3.0.0",
-    "@biorate/inversion": "3.0.2"
+    "@biorate/config": "3.2.1",
+    "@biorate/errors": "3.1.1",
+    "@biorate/inversion": "3.1.1"
   }
 }