@xylabs/mongo

@xylabs/mongo

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

Install

Using npm:

npm install {{name}}

Using yarn:

yarn add {{name}}

Using pnpm:

pnpm add {{name}}

Using bun:

bun add {{name}}

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Reference

packages

mongo

### .temp-typedoc

  ### classes

    ### <a id="BaseMongoSdk"></a>BaseMongoSdk

@xylabs/mongo

Provides a typed wrapper around common MongoDB collection operations.

Type Parameters

T

T extends Document

Constructors

Constructor

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

Parameters

config

BaseMongoSdkConfig

Returns

BaseMongoSdk<T>

Properties

config

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): Promise<DeleteResult>;

Deletes all documents matching the filter.

Parameters

filter

Filter<T>

The query filter to match documents for deletion

Returns

Promise<DeleteResult>

deleteOne()

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>

find()

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

findOne()

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

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

insertOne()

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

replaceOne()

replaceOne(
   filter, 
   item, 
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>>

updateOne()

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

upsertOne()

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

useCollection()

useCollection<R>(func): Promise<R>;

Executes a callback with access to the configured MongoDB collection.

Type Parameters

R

R

Parameters

func

(collection) => R | Promise<R>

A callback receiving the typed collection

Returns

Promise<R>

The result of the callback

useMongo()

useMongo<R>(func): Promise<R>;

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

Type Parameters

R

R

Parameters

func

(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

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

Constructors

Constructor

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

Parameters

uri

string

maxPoolSize?

number

closeDelay?

number

Returns

MongoClientWrapper

Properties

clients

readonly static clients: Map<string, MongoClientWrapper>;

Global cache of wrapper instances keyed by connection URI.

Methods

get()

static get(
   uri, 
   poolSize?, 
   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()

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

    ### <a id="BaseMongoSdkPrivateConfig"></a>BaseMongoSdkPrivateConfig

@xylabs/mongo

Private configuration options for the Mongo SDK containing connection credentials.

Properties

dbConnectionString?

optional dbConnectionString?: string;

A full MongoDB connection string, used instead of individual credential fields.

dbDomain?

optional dbDomain?: string;

The MongoDB Atlas cluster domain.

dbName?

optional dbName?: string;

The database name to connect to.

dbPassword?

optional dbPassword?: string;

The password for MongoDB authentication.

dbUserName?

optional dbUserName?: string;

The username for MongoDB authentication.

    ### <a id="BaseMongoSdkPublicConfig"></a>BaseMongoSdkPublicConfig

@xylabs/mongo

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

Properties

closeDelay?

optional closeDelay?: number;

Delay in milliseconds before closing idle connections.

collection

collection: string;

The MongoDB collection name to operate on.

maxPoolSize?

optional maxPoolSize?: number;

Maximum number of connections in the connection pool.

  ### type-aliases

    ### <a id="BaseMongoSdkConfig"></a>BaseMongoSdkConfig

@xylabs/mongo

type BaseMongoSdkConfig = BaseMongoSdkPublicConfig & BaseMongoSdkPrivateConfig;

Combined public and private MongoDB SDK configuration.