@xylabs/mongo

Base functionality used throughout XYO TypeScript/JavaScript libraries that access Mongo DB

Reference

@xylabs/mongo

Classes

| Class | Description | | ------ | ------ | | BaseMongoSdk | Provides a typed wrapper around common MongoDB collection operations. | | MongoClientWrapper | Manages a shared pool of MongoClient instances, reusing connections by URI. |

Interfaces

| Interface | Description | | ------ | ------ | | BaseMongoSdkPublicConfig | Public configuration options for the Mongo SDK, safe to expose to clients. | | BaseMongoSdkPrivateConfig | Private configuration options for the Mongo SDK containing connection credentials. |

Type Aliases

| Type Alias | Description | | ------ | ------ | | BaseMongoSdkConfig | Combined public and private MongoDB SDK configuration. |

classes

BaseMongoSdk

@xylabs/mongo

Provides a typed wrapper around common MongoDB collection operations.

Type Parameters

| Type Parameter | | ------ | | T extends Document |

Constructors

Constructor

new BaseMongoSdk<T>(config: BaseMongoSdkConfig): BaseMongoSdk<T>;

Parameters

| Parameter | Type | | ------ | ------ | | config | BaseMongoSdkConfig |

Returns

BaseMongoSdk<T>

Properties

| Property | Type | Description | | ------ | ------ | ------ | | config | BaseMongoSdkConfig | The MongoDB SDK configuration for this instance. |

Accessors

uri

Get Signature

get uri(): string;

Returns the MongoDB connection URI, either from the config or constructed from individual credential fields.

Returns

string

Methods

deleteMany()

deleteMany(filter: Filter<T>): Promise<DeleteResult>;

Deletes all documents matching the filter.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | filter | Filter<T> | The query filter to match documents for deletion |

Returns

Promise<DeleteResult>

deleteOne()

deleteOne(filter: Filter<T>): Promise<DeleteResult>;

Deletes the first document matching the filter.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | filter | Filter<T> | The query filter to match a document for deletion |

Returns

Promise<DeleteResult>

find()

find(filter: Filter<T>): Promise<FindCursor<WithId<T>>>;

Finds all documents matching the filter and returns a cursor.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | filter | Filter<T> | The query filter |

Returns

Promise<FindCursor<WithId<T>>>

findOne()

findOne(filter: Filter<T>): Promise<WithId<T> | null>;

Finds a single document matching the filter.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | filter | Filter<T> | The query filter |

Returns

Promise<WithId<T> | null>

The matched document, or null if not found

insertMany()

insertMany(items: OptionalUnlessRequiredId<T>[], options?: BulkWriteOptions): Promise<InsertManyResult<T>>;

Inserts multiple documents into the collection.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | items | OptionalUnlessRequiredId<T>[] | The documents to insert | | options? | BulkWriteOptions | Optional bulk write options |

Returns

Promise<InsertManyResult<T>>

insertOne()

insertOne(item: OptionalUnlessRequiredId<T>, options?: InsertOneOptions): Promise<InsertOneResult<T>>;

Inserts a single document into the collection.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | item | OptionalUnlessRequiredId<T> | The document to insert | | options? | InsertOneOptions | Optional insert options |

Returns

Promise<InsertOneResult<T>>

replaceOne()

replaceOne(
   filter: Filter<T>, 
   item: OptionalUnlessRequiredId<T>, 
options?: ReplaceOptions): Promise<UpdateResult<T>>;

Replaces a single document matching the filter.

Parameters

| 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

Promise<UpdateResult<T>>

updateOne()

updateOne(filter: Filter<T>, fields: UpdateFilter<T>): Promise<UpdateResult<T>>;

Updates a single document matching the filter without upserting.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | filter | Filter<T> | The query filter to match the document | | fields | UpdateFilter<T> | The update operations to apply |

Returns

Promise<UpdateResult<T>>

upsertOne()

upsertOne(filter: Filter<T>, fields: UpdateFilter<T>): Promise<UpdateResult<T>>;

Updates a single document matching the filter, inserting it if it does not exist.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | filter | Filter<T> | The query filter to match the document | | fields | UpdateFilter<T> | The update operations to apply |

Returns

Promise<UpdateResult<T>>

useCollection()

useCollection<R>(func: (collection: Collection<T>) => R | Promise<R>): Promise<R>;

Executes a callback with access to the configured MongoDB collection.

Type Parameters

| Type Parameter | | ------ | | R |

Parameters

| 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()

useMongo<R>(func: (client: MongoClient) => R | Promise<R>): Promise<R>;

Executes a callback with a connected MongoClient, handling connection and disconnection.

Type Parameters

| Type Parameter | | ------ | | R |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | func | (client: MongoClient) => R | Promise<R> | A callback receiving the connected MongoClient |

Returns

Promise<R>

The result of the callback

MongoClientWrapper

@xylabs/mongo

Manages a shared pool of MongoClient instances, reusing connections by URI.

Constructors

Constructor

new MongoClientWrapper(
   uri: string, 
   maxPoolSize?: number, 
   closeDelay?: number): MongoClientWrapper;

Parameters

| Parameter | Type | | ------ | ------ | | uri | string | | maxPoolSize? | number | | closeDelay? | number |

Returns

MongoClientWrapper

Properties

| Property | Modifier | Type | Description | | ------ | ------ | ------ | ------ | | clients | readonly | Map<string, MongoClientWrapper> | Global cache of wrapper instances keyed by connection URI. |

Methods

get()

static get(
   uri: string, 
   poolSize?: number, 
   closeDelay?: number): MongoClientWrapper;

Gets or creates a cached MongoClientWrapper for the given URI.

Parameters

| 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()

connect(): Promise<MongoClient>;

Connects to MongoDB and returns the underlying MongoClient.

Returns

Promise<MongoClient>

disconnect()

disconnect(): Promise<number>;

Disconnects from MongoDB.

Returns

Promise<number>

initiateClose()

initiateClose(): Promise<void>;

Initiates a graceful close of the connection.

Returns

Promise<void>

interfaces

BaseMongoSdkPrivateConfig

@xylabs/mongo

Private configuration options for the Mongo SDK containing connection credentials.

Properties

| Property | Type | Description | | ------ | ------ | ------ | | dbConnectionString? | string | A full MongoDB connection string, used instead of individual credential fields. | | dbDomain? | string | The MongoDB Atlas cluster domain. | | dbName? | string | The database name to connect to. | | dbPassword? | string | The password for MongoDB authentication. | | dbUserName? | string | The username for MongoDB authentication. |

BaseMongoSdkPublicConfig

@xylabs/mongo

Public configuration options for the Mongo SDK, safe to expose to clients.

Properties

| Property | Type | Description | | ------ | ------ | ------ | | closeDelay? | number | Delay in milliseconds before closing idle connections. | | collection | string | The MongoDB collection name to operate on. | | maxPoolSize? | number | Maximum number of connections in the connection pool. |

type-aliases

BaseMongoSdkConfig

@xylabs/mongo

type BaseMongoSdkConfig = BaseMongoSdkPublicConfig & BaseMongoSdkPrivateConfig;

Combined public and private MongoDB SDK configuration.

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs