@xylabs/mongo 5.0.83 → 5.0.84

package/README.md

@@ -43,6 +43,8 @@ Base functionality used throughout XYO TypeScript/JavaScript libraries that acce
 
 ***
 
+Provides a typed wrapper around common MongoDB collection operations.
+
 ## Type Parameters
 
 ### T
@@ -75,6 +77,8 @@ new BaseMongoSdk<T>(config): BaseMongoSdk<T>;
 config: BaseMongoSdkConfig;
 ```
 
+The MongoDB SDK configuration for this instance.
+
 ## Accessors
 
 ### uri
@@ -85,6 +89,8 @@ config: BaseMongoSdkConfig;
 get uri(): string;
 ```
 
+Returns the MongoDB connection URI, either from the config or constructed from individual credential fields.
+
 #### Returns
 
 `string`
@@ -97,12 +103,16 @@ get uri(): string;
 deleteMany(filter): Promise<DeleteResult>;
 ```
 
+Deletes all documents matching the filter.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter to match documents for deletion
+
 ### Returns
 
 `Promise`\<`DeleteResult`\>
@@ -115,12 +125,16 @@ deleteMany(filter): Promise<DeleteResult>;
 deleteOne(filter): Promise<DeleteResult>;
 ```
 
+Deletes the first document matching the filter.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter to match a document for deletion
+
 ### Returns
 
 `Promise`\<`DeleteResult`\>
@@ -133,12 +147,16 @@ deleteOne(filter): Promise<DeleteResult>;
 find(filter): Promise<FindCursor<WithId<T>>>;
 ```
 
+Finds all documents matching the filter and returns a cursor.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter
+
 ### Returns
 
 `Promise`\<`FindCursor`\<`WithId`\<`T`\>\>\>
@@ -151,16 +169,22 @@ find(filter): Promise<FindCursor<WithId<T>>>;
 findOne(filter): Promise<WithId<T> | null>;
 ```
 
+Finds a single document matching the filter.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter
+
 ### Returns
 
 `Promise`\<`WithId`\<`T`\> \| `null`\>
 
+The matched document, or `null` if not found
+
 ***
 
 ### insertMany()
@@ -169,16 +193,22 @@ findOne(filter): Promise<WithId<T> | null>;
 insertMany(items, options?): Promise<InsertManyResult<T>>;
 ```
 
+Inserts multiple documents into the collection.
+
 ### Parameters
 
 #### items
 
 `OptionalUnlessRequiredId`\<`T`\>[]
 
+The documents to insert
+
 #### options?
 
 `BulkWriteOptions`
 
+Optional bulk write options
+
 ### Returns
 
 `Promise`\<`InsertManyResult`\<`T`\>\>
@@ -191,16 +221,22 @@ insertMany(items, options?): Promise<InsertManyResult<T>>;
 insertOne(item, options?): Promise<InsertOneResult<T>>;
 ```
 
+Inserts a single document into the collection.
+
 ### Parameters
 
 #### item
 
 `OptionalUnlessRequiredId`\<`T`\>
 
+The document to insert
+
 #### options?
 
 `InsertOneOptions`
 
+Optional insert options
+
 ### Returns
 
 `Promise`\<`InsertOneResult`\<`T`\>\>
@@ -216,20 +252,28 @@ replaceOne(
 options?): Promise<UpdateResult<T>>;
 ```
 
+Replaces a single document matching the filter.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter to match the document
+
 #### item
 
 `OptionalUnlessRequiredId`\<`T`\>
 
+The replacement document
+
 #### options?
 
 `ReplaceOptions`
 
+Optional replace options
+
 ### Returns
 
 `Promise`\<`UpdateResult`\<`T`\>\>
@@ -242,16 +286,22 @@ options?): Promise<UpdateResult<T>>;
 updateOne(filter, fields): Promise<UpdateResult<T>>;
 ```
 
+Updates a single document matching the filter without upserting.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter to match the document
+
 #### fields
 
 `UpdateFilter`\<`T`\>
 
+The update operations to apply
+
 ### Returns
 
 `Promise`\<`UpdateResult`\<`T`\>\>
@@ -264,16 +314,22 @@ updateOne(filter, fields): Promise<UpdateResult<T>>;
 upsertOne(filter, fields): Promise<UpdateResult<T>>;
 ```
 
+Updates a single document matching the filter, inserting it if it does not exist.
+
 ### Parameters
 
 #### filter
 
 `Filter`\<`T`\>
 
+The query filter to match the document
+
 #### fields
 
 `UpdateFilter`\<`T`\>
 
+The update operations to apply
+
 ### Returns
 
 `Promise`\<`UpdateResult`\<`T`\>\>
@@ -286,6 +342,8 @@ upsertOne(filter, fields): Promise<UpdateResult<T>>;
 useCollection<R>(func): Promise<R>;
 ```
 
+Executes a callback with access to the configured MongoDB collection.
+
 ### Type Parameters
 
 #### R
@@ -298,10 +356,14 @@ useCollection<R>(func): Promise<R>;
 
 (`collection`) => `R` \| `Promise`\<`R`\>
 
+A callback receiving the typed collection
+
 ### Returns
 
 `Promise`\<`R`\>
 
+The result of the callback
+
 ***
 
 ### useMongo()
@@ -310,6 +372,8 @@ useCollection<R>(func): Promise<R>;
 useMongo<R>(func): Promise<R>;
 ```
 
+Executes a callback with a connected MongoClient, handling connection and disconnection.
+
 ### Type Parameters
 
 #### R
@@ -322,16 +386,22 @@ useMongo<R>(func): Promise<R>;
 
 (`client`) => `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
@@ -369,6 +439,8 @@ new MongoClientWrapper(
 readonly static clients: Map<string, MongoClientWrapper>;
 ```
 
+Global cache of wrapper instances keyed by connection URI.
+
 ## Methods
 
 ### get()
@@ -380,24 +452,34 @@ static get(
    closeDelay?): MongoClientWrapper;
 ```
 
+Gets or creates a cached MongoClientWrapper for the given URI.
+
 ### Parameters
 
 #### 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 +488,8 @@ static get(
 connect(): Promise<MongoClient>;
 ```
 
+Connects to MongoDB and returns the underlying MongoClient.
+
 ### Returns
 
 `Promise`\<`MongoClient`\>
@@ -418,6 +502,8 @@ connect(): Promise<MongoClient>;
 disconnect(): Promise<number>;
 ```
 
+Disconnects from MongoDB.
+
 ### Returns
 
 `Promise`\<`number`\>
@@ -430,6 +516,8 @@ disconnect(): Promise<number>;
 initiateClose(): Promise<void>;
 ```
 
+Initiates a graceful close of the connection.
+
 ### Returns
 
 `Promise`\<`void`\>
@@ -442,6 +530,8 @@ initiateClose(): Promise<void>;
 
 ***
 
+Private configuration options for the Mongo SDK containing connection credentials.
+
 ## Properties
 
 ### dbConnectionString?
@@ -450,6 +540,8 @@ initiateClose(): Promise<void>;
 optional dbConnectionString: string;
 ```
 
+A full MongoDB connection string, used instead of individual credential fields.
+
 ***
 
 ### dbDomain?
@@ -458,6 +550,8 @@ optional dbConnectionString: string;
 optional dbDomain: string;
 ```
 
+The MongoDB Atlas cluster domain.
+
 ***
 
 ### dbName?
@@ -466,6 +560,8 @@ optional dbDomain: string;
 optional dbName: string;
 ```
 
+The database name to connect to.
+
 ***
 
 ### dbPassword?
@@ -474,6 +570,8 @@ optional dbName: string;
 optional dbPassword: string;
 ```
 
+The password for MongoDB authentication.
+
 ***
 
 ### dbUserName?
@@ -482,12 +580,16 @@ optional dbPassword: string;
 optional dbUserName: string;
 ```
 
+The username for MongoDB authentication.
+
   ### <a id="BaseMongoSdkPublicConfig"></a>BaseMongoSdkPublicConfig
 
 [**@xylabs/mongo**](#../README)
 
 ***
 
+Public configuration options for the Mongo SDK, safe to expose to clients.
+
 ## Properties
 
 ### closeDelay?
@@ -496,6 +598,8 @@ optional dbUserName: string;
 optional closeDelay: number;
 ```
 
+Delay in milliseconds before closing idle connections.
+
 ***
 
 ### collection
@@ -504,6 +608,8 @@ optional closeDelay: number;
 collection: string;
 ```
 
+The MongoDB collection name to operate on.
+
 ***
 
 ### maxPoolSize?
@@ -512,6 +618,8 @@ collection: string;
 optional maxPoolSize: number;
 ```
 
+Maximum number of connections in the connection pool.
+
 ### type-aliases
 
   ### <a id="BaseMongoSdkConfig"></a>BaseMongoSdkConfig
@@ -524,6 +632,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.84",
   "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.84"
   },
   "devDependencies": {
-    "@xylabs/tsconfig": "~7.4.11",
+    "@xylabs/tsconfig": "~7.4.13",
     "mongodb": "^7.1.0",
     "typescript": "~5.9.3",
     "vitest": "~4.0.18"