@xylabs/mongo 4.13.19 → 4.13.21

package/README.md

@@ -12,13 +12,518 @@
 [![snyk-badge][]][snyk-link]
 [![socket-badge][]][socket-link]
 
-Version: 4.13.15
 
 Base functionality used throughout XYO TypeScript/JavaScript libraries that access Mongo DB
 
-## Documentation
+## API Documentation
+
+**@xylabs/mongo**
+
+***
+
+## Classes
+
+- [BaseMongoSdk](#classes/BaseMongoSdk)
+- [MongoClientWrapper](#classes/MongoClientWrapper)
+
+## Interfaces
+
+- [BaseMongoSdkPublicConfig](#interfaces/BaseMongoSdkPublicConfig)
+- [BaseMongoSdkPrivateConfig](#interfaces/BaseMongoSdkPrivateConfig)
+
+## Type Aliases
+
+- [BaseMongoSdkConfig](#type-aliases/BaseMongoSdkConfig)
+
+### classes
+
+  ### <a id="BaseMongoSdk"></a>BaseMongoSdk
+
+[**@xylabs/mongo**](#../README)
+
+***
+
+## Type Parameters
+
+### T
+
+`T` *extends* `Document`
+
+## Constructors
+
+### Constructor
+
+```ts
+new BaseMongoSdk<T>(config): BaseMongoSdk<T>;
+```
+
+### Parameters
+
+#### config
+
+[`BaseMongoSdkConfig`](#../type-aliases/BaseMongoSdkConfig)
+
+### Returns
+
+`BaseMongoSdk`\<`T`\>
+
+## Properties
+
+### config
+
+```ts
+config: BaseMongoSdkConfig;
+```
+
+## Accessors
+
+### uri
+
+### Get Signature
+
+```ts
+get uri(): string;
+```
+
+#### Returns
+
+`string`
+
+## Methods
+
+### deleteMany()
+
+```ts
+deleteMany(filter): Promise<DeleteResult>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+### Returns
+
+`Promise`\<`DeleteResult`\>
+
+***
+
+### deleteOne()
+
+```ts
+deleteOne(filter): Promise<DeleteResult>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+### Returns
+
+`Promise`\<`DeleteResult`\>
+
+***
+
+### find()
+
+```ts
+find(filter): Promise<FindCursor<WithId<T>>>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+### Returns
+
+`Promise`\<`FindCursor`\<`WithId`\<`T`\>\>\>
+
+***
+
+### findOne()
+
+```ts
+findOne(filter): Promise<null | WithId<T>>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+### Returns
+
+`Promise`\<`null` \| `WithId`\<`T`\>\>
+
+***
+
+### insertMany()
+
+```ts
+insertMany(items, options?): Promise<InsertManyResult<T>>;
+```
+
+### Parameters
+
+#### items
+
+`OptionalUnlessRequiredId`\<`T`\>[]
+
+#### options?
+
+`BulkWriteOptions`
+
+### Returns
+
+`Promise`\<`InsertManyResult`\<`T`\>\>
+
+***
+
+### insertOne()
+
+```ts
+insertOne(item, options?): Promise<InsertOneResult<T>>;
+```
+
+### Parameters
+
+#### item
+
+`OptionalUnlessRequiredId`\<`T`\>
+
+#### options?
+
+`InsertOneOptions`
+
+### Returns
+
+`Promise`\<`InsertOneResult`\<`T`\>\>
+
+***
+
+### replaceOne()
+
+```ts
+replaceOne(
+   filter, 
+   item, 
+options?): Promise<UpdateResult<T>>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+#### item
+
+`OptionalUnlessRequiredId`\<`T`\>
+
+#### options?
+
+`ReplaceOptions`
+
+### Returns
+
+`Promise`\<`UpdateResult`\<`T`\>\>
+
+***
+
+### updateOne()
+
+```ts
+updateOne(filter, fields): Promise<UpdateResult<T>>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+#### fields
+
+`UpdateFilter`\<`T`\>
+
+### Returns
+
+`Promise`\<`UpdateResult`\<`T`\>\>
+
+***
+
+### upsertOne()
+
+```ts
+upsertOne(filter, fields): Promise<UpdateResult<T>>;
+```
+
+### Parameters
+
+#### filter
+
+`Filter`\<`T`\>
+
+#### fields
+
+`UpdateFilter`\<`T`\>
+
+### Returns
+
+`Promise`\<`UpdateResult`\<`T`\>\>
+
+***
+
+### useCollection()
+
+```ts
+useCollection<R>(func): Promise<R>;
+```
+
+### Type Parameters
+
+#### R
+
+`R`
+
+### Parameters
+
+#### func
+
+(`collection`) => `R` \| `Promise`\<`R`\>
+
+### Returns
+
+`Promise`\<`R`\>
+
+***
+
+### useMongo()
+
+```ts
+useMongo<R>(func): Promise<R>;
+```
+
+### Type Parameters
+
+#### R
+
+`R`
+
+### Parameters
+
+#### func
+
+(`client`) => `R` \| `Promise`\<`R`\>
+
+### Returns
+
+`Promise`\<`R`\>
+
+  ### <a id="MongoClientWrapper"></a>MongoClientWrapper
+
+[**@xylabs/mongo**](#../README)
+
+***
+
+## Constructors
+
+### Constructor
+
+```ts
+new MongoClientWrapper(
+   uri, 
+   maxPoolSize?, 
+   closeDelay?): MongoClientWrapper;
+```
+
+### Parameters
+
+#### uri
+
+`string`
+
+#### maxPoolSize?
+
+`number`
+
+#### closeDelay?
+
+`number`
+
+### Returns
+
+`MongoClientWrapper`
+
+## Properties
+
+### clients
+
+```ts
+readonly static clients: Map<string, MongoClientWrapper>;
+```
+
+## Methods
+
+### get()
+
+```ts
+static get(
+   uri, 
+   poolSize?, 
+   closeDelay?): MongoClientWrapper;
+```
+
+### Parameters
+
+#### uri
+
+`string`
+
+#### poolSize?
+
+`number`
+
+#### closeDelay?
+
+`number`
+
+### Returns
+
+`MongoClientWrapper`
+
+***
+
+### connect()
+
+```ts
+connect(): Promise<MongoClient>;
+```
+
+### Returns
+
+`Promise`\<`MongoClient`\>
+
+***
+
+### disconnect()
+
+```ts
+disconnect(): Promise<number>;
+```
+
+### Returns
+
+`Promise`\<`number`\>
+
+***
+
+### initiateClose()
+
+```ts
+initiateClose(): Promise<void>;
+```
+
+### Returns
+
+`Promise`\<`void`\>
+
+### interfaces
+
+  ### <a id="BaseMongoSdkPrivateConfig"></a>BaseMongoSdkPrivateConfig
+
+[**@xylabs/mongo**](#../README)
+
+***
+
+## Properties
+
+### dbConnectionString?
+
+```ts
+optional dbConnectionString: string;
+```
+
+***
+
+### dbDomain?
+
+```ts
+optional dbDomain: string;
+```
+
+***
+
+### dbName?
+
+```ts
+optional dbName: string;
+```
+
+***
+
+### dbPassword?
+
+```ts
+optional dbPassword: string;
+```
+
+***
+
+### dbUserName?
+
+```ts
+optional dbUserName: string;
+```
+
+  ### <a id="BaseMongoSdkPublicConfig"></a>BaseMongoSdkPublicConfig
+
+[**@xylabs/mongo**](#../README)
+
+***
+
+## Properties
+
+### closeDelay?
+
+```ts
+optional closeDelay: number;
+```
+
+***
+
+### collection
+
+```ts
+collection: string;
+```
+
+***
+
+### maxPoolSize?
+
+```ts
+optional maxPoolSize: number;
+```
+
+### type-aliases
+
+  ### <a id="BaseMongoSdkConfig"></a>BaseMongoSdkConfig
+
+[**@xylabs/mongo**](#../README)
+
+***
+
+```ts
+type BaseMongoSdkConfig = BaseMongoSdkPublicConfig & BaseMongoSdkPrivateConfig;
+```
 
-Coming Soon!
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/mongo",
-  "version": "4.13.19",
+  "version": "4.13.21",
   "description": "Base functionality used throughout XYO TypeScript/JavaScript libraries that access Mongo DB",
   "keywords": [
     "mongo",
@@ -26,26 +26,34 @@
     ".": {
       "browser": {
         "types": "./dist/browser/index.d.ts",
+        "source": "./src/index.ts",
         "default": "./dist/browser/index.mjs"
       },
       "node": {
         "types": "./dist/node/index.d.ts",
+        "source": "./src/index.ts",
         "default": "./dist/node/index.mjs"
       },
       "types": "./dist/node/index.d.ts",
+      "source": "./src/index.ts",
       "default": "./dist/node/index.mjs"
     },
     "./package.json": "./package.json"
   },
-  "module": "dist/node/index.mjs",
-  "types": "dist/node/index.d.ts",
+  "module": "./dist/node/index.mjs",
+  "source": "./src/index.ts",
+  "types": "./dist/node/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
   "dependencies": {
-    "@xylabs/assert": "^4.13.19",
+    "@xylabs/assert": "^4.13.21",
     "mongodb": "~6.17.0"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "^7.0.0-rc.27",
-    "@xylabs/tsconfig": "^7.0.0-rc.27",
+    "@xylabs/ts-scripts-yarn3": "^7.0.0",
+    "@xylabs/tsconfig": "^7.0.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },

package/src/spec/Base.spec.ts

@@ -0,0 +1,20 @@
+import {
+  describe, expect, test,
+} from 'vitest'
+
+import { BaseMongoSdk } from '../Base.js'
+import type { BaseMongoSdkConfig } from '../Config.js'
+
+describe('Base', () => {
+  test('checking happy path', () => {
+    const config: BaseMongoSdkConfig = {
+      collection: 'test',
+      dbDomain: 'test.test.com',
+      dbName: 'default',
+      dbPassword: 'password',
+      dbUserName: 'username',
+    }
+    const apiStage = new BaseMongoSdk(config)
+    expect(apiStage).toBeDefined()
+  })
+})

package/src/spec/Wrapper.spec.ts

@@ -0,0 +1,134 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// mongoClientWrapper.memory.test.ts
+import { mkdirSync, writeFileSync } from 'node:fs'
+import inspector from 'node:inspector'
+import path from 'node:path'
+
+import {
+  afterEach, beforeEach, describe, expect, it,
+} from 'vitest'
+
+import { MongoClientWrapper } from '../Wrapper.ts'
+
+// function randomIntBetween(min: number, max: number): number {
+//   const low = Math.ceil(min)
+//   const high = Math.floor(max)
+//   return Math.floor(Math.random() * (high - low + 1)) + low
+// }
+let session: inspector.Session | null = null
+let profileType: 'sampling' | 'snapshot' = 'sampling'
+let chunks: string[] = []
+
+/**
+ * Starts a heap profiler session.
+ * @param type 'sampling' or 'snapshot'
+ * @param outPath Output directory (default: './heap-profiles')
+ */
+export async function startHeapProfile(
+  type: 'sampling' | 'snapshot' = 'sampling',
+  outPath: string = './heap-profiles',
+): Promise<void> {
+  profileType = type
+  session = new inspector.Session()
+  session.connect()
+  mkdirSync(outPath, { recursive: true })
+
+  await post('HeapProfiler.enable')
+
+  if (type === 'sampling') {
+    await post('HeapProfiler.startSampling')
+  } else if (type === 'snapshot') {
+    chunks = []
+    session.on('HeapProfiler.addHeapSnapshotChunk', msg => chunks.push(msg.params.chunk))
+  }
+}
+
+/**
+ * Stops the heap profiler and writes the output to file.
+ * @param fileName Optional output filename
+ * @param outPath Output directory (default: './heap-profiles')
+ * @returns Full path to the heap profile file
+ */
+export async function stopHeapProfile(
+  fileName?: string,
+  outPath: string = './heap-profiles',
+): Promise<string> {
+  if (!session) throw new Error('No active profiling session. Call startHeapProfile() first.')
+
+  const timestamp = Date.now()
+  const outFile = path.join(outPath, fileName ?? `heap-${profileType}-${timestamp}.heapprofile`)
+
+  if (profileType === 'sampling') {
+    const result = await post<{ profile: any }>('HeapProfiler.stopSampling')
+    writeFileSync(outFile, JSON.stringify(result.profile))
+  } else {
+    await post('HeapProfiler.takeHeapSnapshot')
+    writeFileSync(outFile, chunks.join(''))
+  }
+
+  await post('HeapProfiler.disable')
+  session.disconnect()
+  session = null
+
+  return outFile
+}
+
+function post<T = void>(method: string, params: object = {}): Promise<T> {
+  return new Promise((resolve, reject) => {
+    session!.post(method, params, (err, result) => {
+      if (err) reject(err)
+      else resolve(result as T)
+    })
+  })
+}
+
+describe.skip('MongoClientWrapper memory profiling', () => {
+  const TEST_MONGO_URI = process.env.MONGO_CONNECTION_STRING
+  beforeEach(() => {
+    // Reset static map before each test run
+    ;(MongoClientWrapper as any).clients.clear()
+  })
+
+  afterEach(async () => {
+    // Disconnect all clients after each test
+    for (const client of (MongoClientWrapper as any).clients.values()) {
+      await client.disconnect()
+    }
+    ;(MongoClientWrapper as any).clients.clear()
+    globalThis.gc?.() // Only works if Node is run with --expose-gc
+  })
+
+  it('should not leak MongoClientWrapper instances after many connect/disconnect cycles', async () => {
+    expect(TEST_MONGO_URI).toBeDefined()
+    const uri = `${TEST_MONGO_URI}`
+    const cycleCount = 200_000
+    await startHeapProfile('sampling')
+    await Promise.all(
+      Array.from({ length: cycleCount }).map(async () => {
+        // await new Promise(r => setTimeout(r, randomIntBetween(1000, 3000)))
+        const wrapper = MongoClientWrapper.get(uri, 100, 1)
+        const client = await wrapper.connect()
+        expect(client).toBeDefined()
+        await wrapper.disconnect()
+      }),
+    )
+
+    // Trigger GC if available
+    globalThis.gc?.()
+
+    // Wait to allow async cleanup to complete
+    await new Promise(r => setTimeout(r, 20_000))
+
+    const filePath = await stopHeapProfile()
+    console.log('Heap profile written to:', filePath)
+
+    // Check how many entries remain
+    const clientMap = (MongoClientWrapper as any).clients as Map<string, any>
+    const remaining = [...clientMap.keys()]
+
+    console.log('Remaining keys in clients map:', remaining)
+
+    // Assert map doesn't grow without bound
+    expect(remaining.length).toBeLessThanOrEqual(5) // Allow a few survivors from timing edge cases
+  }, 240_000)
+})

package/typedoc.json

@@ -1,5 +0,0 @@
-{
-  "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["src/index.ts"],
-  "tsconfig": "./tsconfig.typedoc.json"
-}