@xylabs/mongo 5.0.83 → 5.0.86

package/README.md

@@ -15,6 +15,8 @@
 
 Base functionality used throughout XYO TypeScript/JavaScript libraries that access Mongo DB
 
+
+
 ## Reference
 
 **@xylabs/mongo**
@@ -23,17 +25,23 @@ Base functionality used throughout XYO TypeScript/JavaScript libraries that acce
 
 ## Classes
 
-- [BaseMongoSdk](#classes/BaseMongoSdk)
-- [MongoClientWrapper](#classes/MongoClientWrapper)
+| Class | Description |
+| ------ | ------ |
+| [BaseMongoSdk](#classes/BaseMongoSdk) | Provides a typed wrapper around common MongoDB collection operations. |
+| [MongoClientWrapper](#classes/MongoClientWrapper) | Manages a shared pool of MongoClient instances, reusing connections by URI. |
 
 ## Interfaces
 
-- [BaseMongoSdkPublicConfig](#interfaces/BaseMongoSdkPublicConfig)
-- [BaseMongoSdkPrivateConfig](#interfaces/BaseMongoSdkPrivateConfig)
+| Interface | Description |
+| ------ | ------ |
+| [BaseMongoSdkPublicConfig](#interfaces/BaseMongoSdkPublicConfig) | Public configuration options for the Mongo SDK, safe to expose to clients. |
+| [BaseMongoSdkPrivateConfig](#interfaces/BaseMongoSdkPrivateConfig) | Private configuration options for the Mongo SDK containing connection credentials. |
 
 ## Type Aliases
 
-- [BaseMongoSdkConfig](#type-aliases/BaseMongoSdkConfig)
+| Type Alias | Description |
+| ------ | ------ |
+| [BaseMongoSdkConfig](#type-aliases/BaseMongoSdkConfig) | Combined public and private MongoDB SDK configuration. |
 
 ### classes
 
@@ -43,25 +51,27 @@ Base functionality used throughout XYO TypeScript/JavaScript libraries that acce
 
 ***
 
-## Type Parameters
+Provides a typed wrapper around common MongoDB collection operations.
 
-### T
+## Type Parameters
 
-`T` *extends* `Document`
+| Type Parameter |
+| ------ |
+| `T` *extends* `Document` |
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new BaseMongoSdk<T>(config): BaseMongoSdk<T>;
+new BaseMongoSdk<T>(config: BaseMongoSdkConfig): BaseMongoSdk<T>;
 ```
 
 ### Parameters
 
-#### config
-
-[`BaseMongoSdkConfig`](#../type-aliases/BaseMongoSdkConfig)
+| Parameter | Type |
+| ------ | ------ |
+| `config` | [`BaseMongoSdkConfig`](#../type-aliases/BaseMongoSdkConfig) |
 
 ### Returns
 
@@ -69,11 +79,9 @@ new BaseMongoSdk<T>(config): BaseMongoSdk<T>;
 
 ## Properties
 
-### config
-
-```ts
-config: BaseMongoSdkConfig;
-```
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="config"></a> `config` | [`BaseMongoSdkConfig`](#../type-aliases/BaseMongoSdkConfig) | The MongoDB SDK configuration for this instance. |
 
 ## Accessors
 
@@ -85,6 +93,8 @@ config: BaseMongoSdkConfig;
 get uri(): string;
 ```
 
+Returns the MongoDB connection URI, either from the config or constructed from individual credential fields.
+
 #### Returns
 
 `string`
@@ -94,14 +104,16 @@ get uri(): string;
 ### deleteMany()
 
 ```ts
-deleteMany(filter): Promise<DeleteResult>;
+deleteMany(filter: Filter<T>): Promise<DeleteResult>;
 ```
 
-### Parameters
+Deletes all documents matching the filter.
 
-#### filter
+### Parameters
 
-`Filter`\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter to match documents for deletion |
 
 ### Returns
 
@@ -112,14 +124,16 @@ deleteMany(filter): Promise<DeleteResult>;
 ### deleteOne()
 
 ```ts
-deleteOne(filter): Promise<DeleteResult>;
+deleteOne(filter: Filter<T>): Promise<DeleteResult>;
 ```
 
-### Parameters
+Deletes the first document matching the filter.
 
-#### filter
+### Parameters
 
-`Filter`\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter to match a document for deletion |
 
 ### Returns
 
@@ -130,14 +144,16 @@ deleteOne(filter): Promise<DeleteResult>;
 ### find()
 
 ```ts
-find(filter): Promise<FindCursor<WithId<T>>>;
+find(filter: Filter<T>): Promise<FindCursor<WithId<T>>>;
 ```
 
-### Parameters
+Finds all documents matching the filter and returns a cursor.
 
-#### filter
+### Parameters
 
-`Filter`\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter |
 
 ### Returns
 
@@ -148,36 +164,39 @@ find(filter): Promise<FindCursor<WithId<T>>>;
 ### findOne()
 
 ```ts
-findOne(filter): Promise<WithId<T> | null>;
+findOne(filter: Filter<T>): Promise<WithId<T> | null>;
 ```
 
-### Parameters
+Finds a single document matching the filter.
 
-#### filter
+### Parameters
 
-`Filter`\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter |
 
 ### Returns
 
 `Promise`\<`WithId`\<`T`\> \| `null`\>
 
+The matched document, or `null` if not found
+
 ***
 
 ### insertMany()
 
 ```ts
-insertMany(items, options?): Promise<InsertManyResult<T>>;
+insertMany(items: OptionalUnlessRequiredId<T>[], options?: BulkWriteOptions): Promise<InsertManyResult<T>>;
 ```
 
-### Parameters
+Inserts multiple documents into the collection.
 
-#### items
-
-`OptionalUnlessRequiredId`\<`T`\>[]
-
-#### options?
+### Parameters
 
-`BulkWriteOptions`
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `items` | `OptionalUnlessRequiredId`\<`T`\>[] | The documents to insert |
+| `options?` | `BulkWriteOptions` | Optional bulk write options |
 
 ### Returns
 
@@ -188,18 +207,17 @@ insertMany(items, options?): Promise<InsertManyResult<T>>;
 ### insertOne()
 
 ```ts
-insertOne(item, options?): Promise<InsertOneResult<T>>;
+insertOne(item: OptionalUnlessRequiredId<T>, options?: InsertOneOptions): Promise<InsertOneResult<T>>;
 ```
 
-### Parameters
-
-#### item
+Inserts a single document into the collection.
 
-`OptionalUnlessRequiredId`\<`T`\>
-
-#### options?
+### Parameters
 
-`InsertOneOptions`
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `item` | `OptionalUnlessRequiredId`\<`T`\> | The document to insert |
+| `options?` | `InsertOneOptions` | Optional insert options |
 
 ### Returns
 
@@ -211,24 +229,20 @@ insertOne(item, options?): Promise<InsertOneResult<T>>;
 
 ```ts
 replaceOne(
-   filter, 
-   item, 
-options?): Promise<UpdateResult<T>>;
+   filter: Filter<T>, 
+   item: OptionalUnlessRequiredId<T>, 
+options?: ReplaceOptions): Promise<UpdateResult<T>>;
 ```
 
-### Parameters
-
-#### filter
-
-`Filter`\<`T`\>
+Replaces a single document matching the filter.
 
-#### item
-
-`OptionalUnlessRequiredId`\<`T`\>
-
-#### options?
+### Parameters
 
-`ReplaceOptions`
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter to match the document |
+| `item` | `OptionalUnlessRequiredId`\<`T`\> | The replacement document |
+| `options?` | `ReplaceOptions` | Optional replace options |
 
 ### Returns
 
@@ -239,18 +253,17 @@ options?): Promise<UpdateResult<T>>;
 ### updateOne()
 
 ```ts
-updateOne(filter, fields): Promise<UpdateResult<T>>;
+updateOne(filter: Filter<T>, fields: UpdateFilter<T>): Promise<UpdateResult<T>>;
 ```
 
-### Parameters
+Updates a single document matching the filter without upserting.
 
-#### filter
-
-`Filter`\<`T`\>
-
-#### fields
+### Parameters
 
-`UpdateFilter`\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter to match the document |
+| `fields` | `UpdateFilter`\<`T`\> | The update operations to apply |
 
 ### Returns
 
@@ -261,18 +274,17 @@ updateOne(filter, fields): Promise<UpdateResult<T>>;
 ### upsertOne()
 
 ```ts
-upsertOne(filter, fields): Promise<UpdateResult<T>>;
+upsertOne(filter: Filter<T>, fields: UpdateFilter<T>): Promise<UpdateResult<T>>;
 ```
 
-### Parameters
-
-#### filter
+Updates a single document matching the filter, inserting it if it does not exist.
 
-`Filter`\<`T`\>
-
-#### fields
+### Parameters
 
-`UpdateFilter`\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `filter` | `Filter`\<`T`\> | The query filter to match the document |
+| `fields` | `UpdateFilter`\<`T`\> | The update operations to apply |
 
 ### Returns
 
@@ -283,79 +295,83 @@ upsertOne(filter, fields): Promise<UpdateResult<T>>;
 ### useCollection()
 
 ```ts
-useCollection<R>(func): Promise<R>;
+useCollection<R>(func: (collection: Collection<T>) => R | Promise<R>): Promise<R>;
 ```
 
-### Type Parameters
+Executes a callback with access to the configured MongoDB collection.
 
-#### R
+### Type Parameters
 
-`R`
+| Type Parameter |
+| ------ |
+| `R` |
 
 ### Parameters
 
-#### func
-
-(`collection`) => `R` \| `Promise`\<`R`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `func` | (`collection`: `Collection`\<`T`\>) => `R` \| `Promise`\<`R`\> | A callback receiving the typed collection |
 
 ### Returns
 
 `Promise`\<`R`\>
 
+The result of the callback
+
 ***
 
 ### useMongo()
 
 ```ts
-useMongo<R>(func): Promise<R>;
+useMongo<R>(func: (client: MongoClient) => R | Promise<R>): Promise<R>;
 ```
 
-### Type Parameters
+Executes a callback with a connected MongoClient, handling connection and disconnection.
 
-#### R
+### Type Parameters
 
-`R`
+| Type Parameter |
+| ------ |
+| `R` |
 
 ### Parameters
 
-#### func
-
-(`client`) => `R` \| `Promise`\<`R`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `func` | (`client`: `MongoClient`) => `R` \| `Promise`\<`R`\> | A callback receiving the connected MongoClient |
 
 ### Returns
 
 `Promise`\<`R`\>
 
+The result of the callback
+
   ### <a id="MongoClientWrapper"></a>MongoClientWrapper
 
 [**@xylabs/mongo**](#../README)
 
 ***
 
+Manages a shared pool of MongoClient instances, reusing connections by URI.
+
 ## Constructors
 
 ### Constructor
 
 ```ts
 new MongoClientWrapper(
-   uri, 
-   maxPoolSize?, 
-   closeDelay?): MongoClientWrapper;
+   uri: string, 
+   maxPoolSize?: number, 
+   closeDelay?: number): MongoClientWrapper;
 ```
 
 ### Parameters
 
-#### uri
-
-`string`
-
-#### maxPoolSize?
-
-`number`
-
-#### closeDelay?
-
-`number`
+| Parameter | Type |
+| ------ | ------ |
+| `uri` | `string` |
+| `maxPoolSize?` | `number` |
+| `closeDelay?` | `number` |
 
 ### Returns
 
@@ -363,11 +379,9 @@ new MongoClientWrapper(
 
 ## Properties
 
-### clients
-
-```ts
-readonly static clients: Map<string, MongoClientWrapper>;
-```
+| Property | Modifier | Type | Description |
+| ------ | ------ | ------ | ------ |
+| <a id="clients"></a> `clients` | `readonly` | `Map`\<`string`, `MongoClientWrapper`\> | Global cache of wrapper instances keyed by connection URI. |
 
 ## Methods
 
@@ -375,29 +389,27 @@ readonly static clients: Map<string, MongoClientWrapper>;
 
 ```ts
 static get(
-   uri, 
-   poolSize?, 
-   closeDelay?): MongoClientWrapper;
+   uri: string, 
+   poolSize?: number, 
+   closeDelay?: number): MongoClientWrapper;
 ```
 
-### Parameters
-
-#### uri
-
-`string`
-
-#### poolSize?
+Gets or creates a cached MongoClientWrapper for the given URI.
 
-`number`
-
-#### closeDelay?
+### Parameters
 
-`number`
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `uri` | `string` | The MongoDB connection URI |
+| `poolSize?` | `number` | Maximum connection pool size |
+| `closeDelay?` | `number` | Delay in milliseconds before closing idle connections |
 
 ### Returns
 
 `MongoClientWrapper`
 
+A cached or newly created wrapper instance
+
 ***
 
 ### connect()
@@ -406,6 +418,8 @@ static get(
 connect(): Promise<MongoClient>;
 ```
 
+Connects to MongoDB and returns the underlying MongoClient.
+
 ### Returns
 
 `Promise`\<`MongoClient`\>
@@ -418,6 +432,8 @@ connect(): Promise<MongoClient>;
 disconnect(): Promise<number>;
 ```
 
+Disconnects from MongoDB.
+
 ### Returns
 
 `Promise`\<`number`\>
@@ -430,6 +446,8 @@ disconnect(): Promise<number>;
 initiateClose(): Promise<void>;
 ```
 
+Initiates a graceful close of the connection.
+
 ### Returns
 
 `Promise`\<`void`\>
@@ -442,45 +460,17 @@ initiateClose(): Promise<void>;
 
 ***
 
-## Properties
-
-### dbConnectionString?
-
-```ts
-optional dbConnectionString: string;
-```
-
-***
-
-### dbDomain?
-
-```ts
-optional dbDomain: string;
-```
-
-***
-
-### dbName?
-
-```ts
-optional dbName: string;
-```
+Private configuration options for the Mongo SDK containing connection credentials.
 
-***
-
-### dbPassword?
-
-```ts
-optional dbPassword: string;
-```
-
-***
-
-### dbUserName?
+## Properties
 
-```ts
-optional dbUserName: string;
-```
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="dbconnectionstring"></a> `dbConnectionString?` | `string` | A full MongoDB connection string, used instead of individual credential fields. |
+| <a id="dbdomain"></a> `dbDomain?` | `string` | The MongoDB Atlas cluster domain. |
+| <a id="dbname"></a> `dbName?` | `string` | The database name to connect to. |
+| <a id="dbpassword"></a> `dbPassword?` | `string` | The password for MongoDB authentication. |
+| <a id="dbusername"></a> `dbUserName?` | `string` | The username for MongoDB authentication. |
 
   ### <a id="BaseMongoSdkPublicConfig"></a>BaseMongoSdkPublicConfig
 
@@ -488,29 +478,15 @@ optional dbUserName: string;
 
 ***
 
-## Properties
-
-### closeDelay?
-
-```ts
-optional closeDelay: number;
-```
-
-***
-
-### collection
-
-```ts
-collection: string;
-```
-
-***
+Public configuration options for the Mongo SDK, safe to expose to clients.
 
-### maxPoolSize?
+## Properties
 
-```ts
-optional maxPoolSize: number;
-```
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="closedelay"></a> `closeDelay?` | `number` | Delay in milliseconds before closing idle connections. |
+| <a id="collection"></a> `collection` | `string` | The MongoDB collection name to operate on. |
+| <a id="maxpoolsize"></a> `maxPoolSize?` | `number` | Maximum number of connections in the connection pool. |
 
 ### type-aliases
 
@@ -524,6 +500,8 @@ optional maxPoolSize: number;
 type BaseMongoSdkConfig = BaseMongoSdkPublicConfig & BaseMongoSdkPrivateConfig;
 ```
 
+Combined public and private MongoDB SDK configuration.
+
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/mongo",
-  "version": "5.0.83",
+  "version": "5.0.86",
   "description": "Base functionality used throughout XYO TypeScript/JavaScript libraries that access Mongo DB",
   "keywords": [
     "mongo",
@@ -46,10 +46,10 @@
     "!**/*.test.*"
   ],
   "dependencies": {
-    "@xylabs/assert": "~5.0.83"
+    "@xylabs/assert": "~5.0.86"
   },
   "devDependencies": {
-    "@xylabs/tsconfig": "~7.4.11",
+    "@xylabs/tsconfig": "~7.4.16",
     "mongodb": "^7.1.0",
     "typescript": "~5.9.3",
     "vitest": "~4.0.18"