@biorate/mongodb 2.0.2 → 2.1.1

package/README.md

@@ -1,88 +1,142 @@
-# Mongodb
+# @biorate/mongodb
 
-Mongodb ORM connector based on mongoose and typegoose
+MongoDB ORM connector — connection manager for Mongoose with `@typegoose/typegoose` model injection.
 
-### Examples:
+## Features
+
+- **Auto-connect** — creates Mongoose `Connection` on `@init()` via config namespace `MongoDB`.
+- **`@model()` decorator** — inject a typed TypeGoose model bound to a connection.
+- **`@typegoose/typegoose` re-exports** — `@Prop()`, `@modelOptions()`, `Severity`, `ReturnModelType`, etc.
+- **Connection verification** — waits for `open` event.
+- **Multi-connection** — multiple connections, `@model()` optional name parameter.
+
+## Installation
+
+```bash
+pnpm add @biorate/mongodb
+```
+
+Requires `@biorate/connector`, `@biorate/inversion`, `@biorate/config`, `@biorate/tools`, `mongoose`, `@typegoose/typegoose`.
+
+## Quick start
 
 ```ts
 import { inject, container, Types, Core } from '@biorate/inversion';
 import { IConfig, Config } from '@biorate/config';
 import {
-  Severity,
-  modelOptions,
-  Prop,
-  MongoDBConnector,
-  IMongoDBConnector,
-  model,
-  ReturnModelType,
+  Severity, modelOptions, Prop,
+  MongoDBConnector, model, ReturnModelType,
 } from '@biorate/mongodb';
 
-// Define models
 @modelOptions({
-  options: {
-    allowMixed: Severity.ALLOW,
-  },
+  options: { allowMixed: Severity.ALLOW },
   schemaOptions: { collection: 'test', versionKey: false },
 })
-export class TestModel {
-  @Prop()
-  firstName: string;
-
-  @Prop()
-  lastName: string;
-
-  @Prop()
-  age: number;
+class TestModel {
+  @Prop() firstName: string;
+  @Prop() lastName: string;
+  @Prop() age: number;
 }
 
-// Define root
-export class Root extends Core() {
-  @inject(MongoDBConnector) public connector: IMongoDBConnector;
+class Root extends Core() {
+  @inject(MongoDBConnector) public connector: MongoDBConnector;
   @model(TestModel) public test: ReturnModelType<typeof TestModel>;
 }
 
-// Bind dependencies
 container.bind<IConfig>(Types.Config).to(Config).inSingletonScope();
-container.bind<IMongoDBConnector>(MongoDBConnector).toSelf().inSingletonScope();
+container.bind<MongoDBConnector>(MongoDBConnector).toSelf().inSingletonScope();
 container.bind<Root>(Root).toSelf().inSingletonScope();
 
-// Configure
 container.get<IConfig>(Types.Config).merge({
-  MongoDB: [
-    {
-      name: 'connection',
-      host: 'mongodb://localhost:27017/',
-      options: {
-        useNewUrlParser: true,
-        useUnifiedTopology: true,
-        dbName: 'test',
-      },
-    },
-  ],
+  MongoDB: [{
+    name: 'connection',
+    host: 'mongodb://localhost:27017/',
+    options: { dbName: 'test' },
+  }],
 });
 
 (async () => {
   const root = container.get<Root>(Root);
   await root.$run();
-  await root.connector.connection().dropDatabase();
+  await new root.test({ firstName: 'Vasya', lastName: 'Pupkin', age: 36 }).save();
+  const data = await root.test.find({ firstName: 'Vasya' }, { _id: 0 });
+  console.log(data); // [{ firstName: 'Vasya', lastName: 'Pupkin', age: 36 }]
+})();
+```
 
-  const connection = root.connector.connection('connection'); // Get connection instance
-  console.log(connection);
+## API Reference
 
-  await new root.test({
-    firstName: 'Vasya',
-    lastName: 'Pupkin',
-    age: 36,
-  }).save(); // insert data into test collection
+### `MongoDBConnector`
 
-  // Get data from database
-  const data = await root.test.find({ firstName: 'Vasya' }, { _id: 0 });
-  console.log(data); // {
-                     //   firstName: 'Vasya',
-                     //   lastName: 'Pupkin',
-                     //   age: 36,
-                     // }
-})();
+| Member           | Type                                        | Description                              |
+|------------------|---------------------------------------------|------------------------------------------|
+| `namespace`      | `'MongoDB'`                                 | Config key for connection definitions.   |
+| `connect(config)` | `(config) => Promise<IMongoDBConnection>`   | Creates Mongoose connection via `createConnection`. |
+
+### `@model()` decorator
+
+```ts
+@model(ModelClass, connectionName?, options?)
+```
+
+Binds a TypeGoose model class to a specific named connection (or the first connection if omitted).
+
+### Config
+
+```ts
+interface IMongoDBConfig extends IConnectorConfig {
+  host: string;                           // mongodb://host:port/
+  options: ConnectOptions;                // dbName, auth, ssl, etc.
+}
+```
+
+### Errors
+
+| Error                              | Condition                                      |
+|------------------------------------|------------------------------------------------|
+| `MongoDBCantConnectError`          | `createConnection()` or `open` event fails.    |
+| `MongoDBConnectionNotExistsError`  | `@model()` references a non-existent connection. |
+
+## Usage patterns
+
+### Multi-connection with named models
+
+```ts
+config: {
+  MongoDB: [
+    { name: 'primary', host: 'mongodb://primary:27017/', options: { dbName: 'app' } },
+    { name: 'archive', host: 'mongodb://archive:27017/', options: { dbName: 'archive' } },
+  ],
+}
+
+class Root extends Core() {
+  @model(UserModel, 'primary') public users: ReturnModelType<typeof UserModel>;
+  @model(LogModel, 'archive') public logs: ReturnModelType<typeof LogModel>;
+}
+```
+
+### Raw connection access
+
+```ts
+const conn = root.connector.connection('primary');
+// conn is a mongoose.Connection — use conn.collection(), conn.model(), etc.
+```
+
+## Architecture
+
+```
+MongoDBConnector extends Connector<IMongoDBConfig, IMongoDBConnection>
+│
+├── namespace = 'MongoDB'
+├── connect(config) → createConnection(host, options)
+│   └── await events.once(connection, 'open')
+│
+├── @init() initialize()
+│   ├── store connections reference globally (for @model decorator)
+│   └── super.initialize() — creates all connections from config
+│
+└── model(Model, connectionName?, options?) → property decorator
+    └── getter → getModelForClass(Model, { existingConnection })
 ```
 
 ### Learn
@@ -93,8 +147,6 @@ container.get<IConfig>(Types.Config).merge({
 
 See the [CHANGELOG](https://github.com/biorate/core/blob/master/packages/%40biorate/mongodb/CHANGELOG.md)
 
-### License
+## License
 
 [MIT](https://github.com/biorate/core/blob/master/packages/%40biorate/mongodb/LICENSE)
-
-Copyright (c) 2021-present [Leonid Levkin (llevkin)](mailto:llevkin@yandex.ru)

package/dist/types/src/index.d.ts

@@ -7,7 +7,7 @@ export * from 'mongodb';
 export declare class MongoDBConnector extends Connector<IMongoDBConfig, IMongoDBConnection> {
     private '#connections';
     private '#current';
-    protected readonly namespace = "MongoDB";
+    protected readonly namespace: string;
     protected connect(config: IMongoDBConfig): Promise<import("mongoose").Connection>;
     protected initialize(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biorate/mongodb",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Mongodb ORM connector based on mongoose and typegoose",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -48,13 +48,13 @@
   ],
   "author": "llevkin",
   "license": "MIT",
-  "gitHead": "ca18c1129712e77a6ec8fb2033a54f94e5620ce0",
+  "gitHead": "ff1dcf14a733ce8004ca582d2c421a2154ce97cb",
   "dependencies": {
-    "@biorate/config": "3.1.0",
-    "@biorate/connector": "3.0.2",
-    "@biorate/errors": "3.0.0",
-    "@biorate/inversion": "3.0.2",
-    "@biorate/tools": "3.0.1",
+    "@biorate/config": "3.2.1",
+    "@biorate/connector": "3.1.1",
+    "@biorate/errors": "3.1.1",
+    "@biorate/inversion": "3.1.1",
+    "@biorate/tools": "3.1.1",
     "@typegoose/typegoose": "^11.0.2",
     "mongodb": "^5.9.1",
     "mongoose": "^7.0.4"