@furystack/mongodb-store 11.0.4 → 11.0.5

package/README.md

@@ -1,51 +1,51 @@
-# @furystack/mongodb-store
-
-MongoDB physical store implementation for FuryStack.
-
-## Installation
-
-```bash
-npm install @furystack/mongodb-store
-# or
-yarn add @furystack/mongodb-store
-```
-
-## Initialization
-
-`defineMongoDbStore` mints a `StoreToken` backed by a MongoDB collection.
-The shared `MongoClientFactory` singleton pools `MongoClient` instances by
-URL and closes them when the owning injector is disposed.
-
-```ts
-import { createInjector } from '@furystack/inject'
-import { defineMongoDbStore } from '@furystack/mongodb-store'
-import { defineDataSet } from '@furystack/repository'
-
-export class TestEntry {
-  declare _id: string
-  declare value: string
-}
-
-export const TestEntryStore = defineMongoDbStore<TestEntry, '_id'>({
-  name: 'my-app/TestEntryStore',
-  model: TestEntry,
-  primaryKey: '_id',
-  url: 'mongodb://localhost:27017',
-  db: 'test',
-  collection: 'TestEntries',
-})
-
-export const TestEntryDataSet = defineDataSet({
-  name: 'my-app/TestEntryDataSet',
-  store: TestEntryStore,
-})
-
-const myInjector = createInjector()
-const dataSet = myInjector.get(TestEntryDataSet)
-```
-
-> **Tip:** For application-level data access, always go through a
-> `DataSetToken` rather than resolving the `StoreToken` directly. The
-> DataSet layer runs authorization, modification hooks, and entity-sync
-> events; a direct store access skips all of them. The
-> `furystack/no-direct-store-token` lint rule guards against this.
+# @furystack/mongodb-store
+
+MongoDB physical store implementation for FuryStack.
+
+## Installation
+
+```bash
+npm install @furystack/mongodb-store
+# or
+yarn add @furystack/mongodb-store
+```
+
+## Initialization
+
+`defineMongoDbStore` mints a `StoreToken` backed by a MongoDB collection.
+The shared `MongoClientFactory` singleton pools `MongoClient` instances by
+URL and closes them when the owning injector is disposed.
+
+```ts
+import { createInjector } from '@furystack/inject'
+import { defineMongoDbStore } from '@furystack/mongodb-store'
+import { defineDataSet } from '@furystack/repository'
+
+export class TestEntry {
+  declare _id: string
+  declare value: string
+}
+
+export const TestEntryStore = defineMongoDbStore<TestEntry, '_id'>({
+  name: 'my-app/TestEntryStore',
+  model: TestEntry,
+  primaryKey: '_id',
+  url: 'mongodb://localhost:27017',
+  db: 'test',
+  collection: 'TestEntries',
+})
+
+export const TestEntryDataSet = defineDataSet({
+  name: 'my-app/TestEntryDataSet',
+  store: TestEntryStore,
+})
+
+const myInjector = createInjector()
+const dataSet = myInjector.get(TestEntryDataSet)
+```
+
+> **Tip:** For application-level data access, always go through a
+> `DataSetToken` rather than resolving the `StoreToken` directly. The
+> DataSet layer runs authorization, modification hooks, and entity-sync
+> events; a direct store access skips all of them. The
+> `furystack/no-direct-store-token` lint rule guards against this.

package/esm/store-manager-helpers.d.ts

@@ -0,0 +1,33 @@
+import type { Constructable, Injector } from '@furystack/inject';
+import type { MongoClientOptions } from 'mongodb';
+export declare const useMongoDb: <T extends object>({ injector, model, primaryKey, db, collection, url, options, }: {
+    /**
+     * The Injector instance to use
+     */
+    injector: Injector;
+    /**
+     * The constructable model class
+     */
+    model: Constructable<T>;
+    /**
+     * The name of the Primary Key property
+     */
+    primaryKey: keyof T;
+    /**
+     * Url of the MongoDb repository
+     */
+    url: string;
+    /**
+     * MongoDb Database name
+     */
+    db: string;
+    /**
+     * MongoDb Collection name
+     */
+    collection: string;
+    /**
+     * Optional options for the MongoDb Client
+     */
+    options?: MongoClientOptions;
+}) => void;
+//# sourceMappingURL=store-manager-helpers.d.ts.map

package/esm/store-manager-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-manager-helpers.d.ts","sourceRoot":"","sources":["../src/store-manager-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAIjD,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,gEAQ1C;IACD;;OAEG;IACH,QAAQ,EAAE,QAAQ,CAAA;IAClB;;OAEG;IACH,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IACvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC,CAAA;IACnB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;CAC7B,SAUA,CAAA"}

package/esm/store-manager-helpers.js

@@ -0,0 +1,15 @@
+import { addStore } from '@furystack/core';
+import { MongoClientFactory } from './mongo-client-factory.js';
+import { MongodbStore } from './mongodb-store.js';
+export const useMongoDb = ({ injector, model, primaryKey, db, collection, url, options, }) => {
+    const clientFactory = injector.getInstance(MongoClientFactory);
+    const store = new MongodbStore({
+        model,
+        primaryKey,
+        db,
+        collection,
+        mongoClient: () => clientFactory.getClientFor(url, options),
+    });
+    addStore(injector, store);
+};
+//# sourceMappingURL=store-manager-helpers.js.map

package/esm/store-manager-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-manager-helpers.js","sourceRoot":"","sources":["../src/store-manager-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAmB,EAC3C,QAAQ,EACR,KAAK,EACL,UAAU,EACV,EAAE,EACF,UAAU,EACV,GAAG,EACH,OAAO,GA+BR,EAAE,EAAE;IACH,MAAM,aAAa,GAAG,QAAQ,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAA;IAC9D,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC;QAC7B,KAAK;QACL,UAAU;QACV,EAAE;QACF,UAAU;QACV,WAAW,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC;KAC5D,CAAC,CAAA;IACF,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;AAC3B,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/mongodb-store",
-  "version": "11.0.4",
+  "version": "11.0.5",
   "description": "MongoDB Store implementation for FuryStack",
   "type": "module",
   "scripts": {
@@ -38,15 +38,15 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "dependencies": {
-    "@furystack/core": "^17.1.3",
-    "@furystack/inject": "^13.0.4",
-    "@furystack/utils": "^9.0.4",
-    "mongodb": "7.6.0"
+    "@furystack/core": "^17.1.4",
+    "@furystack/inject": "^13.0.5",
+    "@furystack/utils": "^9.0.5",
+    "mongodb": "7.8.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.6",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.1"
+    "vitest": "^5.1.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/define-mongodb-store.spec.ts

@@ -1,108 +1,108 @@
-import { createInjector } from '@furystack/inject'
-import type { MongoClient } from 'mongodb'
-import { describe, expect, it, vi } from 'vitest'
-import { defineMongoDbStore } from './define-mongodb-store.js'
-import { MongoClientFactory } from './mongo-client-factory.js'
-import { MongodbStore } from './mongodb-store.js'
-
-class Item {
-  declare id: string
-  declare value: string
-}
-
-describe('defineMongoDbStore (metadata)', () => {
-  it('propagates name, lifetime, model and primaryKey onto the returned token', () => {
-    const token = defineMongoDbStore<Item, 'id'>({
-      name: 'test/MongoItems',
-      model: Item,
-      primaryKey: 'id',
-      url: 'mongodb://localhost:27017',
-      db: 'unit-test',
-      collection: 'items',
-    })
-    expect(token.name).toBe('test/MongoItems')
-    expect(token.lifetime).toBe('singleton')
-    expect(token.model).toBe(Item)
-    expect(token.primaryKey).toBe('id')
-  })
-
-  it('mints a distinct token identity per call even when options match -- declare once at module scope', () => {
-    const options = {
-      name: 'test/MongoDupe',
-      model: Item,
-      primaryKey: 'id' as const,
-      url: 'mongodb://localhost:27017',
-      db: 'unit-test',
-      collection: 'items',
-    }
-    const a = defineMongoDbStore<Item, 'id'>(options)
-    const b = defineMongoDbStore<Item, 'id'>(options)
-    expect(a.id).not.toBe(b.id)
-  })
-})
-
-describe('defineMongoDbStore (factory + disposal)', () => {
-  const buildClientStub = () => {
-    const createIndex = vi.fn<() => Promise<string>>(() => Promise.resolve('id_1'))
-    const collection = vi.fn(() => ({ createIndex }))
-    const db = vi.fn(() => ({ collection }))
-    const client = { db } as unknown as MongoClient
-    return { client, db, collection, createIndex }
-  }
-
-  it('instantiates a MongodbStore whose lazy client pulls from the injected MongoClientFactory with the right url', async () => {
-    const { client, db, collection, createIndex } = buildClientStub()
-    const getClientFor = vi.fn(() => client)
-
-    const Token = defineMongoDbStore<Item, 'id'>({
-      name: 'test/MongoFactory',
-      model: Item,
-      primaryKey: 'id',
-      url: 'mongodb://stub-host:1234',
-      db: 'unit-db',
-      collection: 'unit-coll',
-      options: { appName: 'spec' },
-    })
-
-    const injector = createInjector()
-    injector.bind(MongoClientFactory, () => ({ getClientFor }))
-
-    try {
-      const store = injector.get(Token) as MongodbStore<Item, 'id'>
-      expect(store).toBeInstanceOf(MongodbStore)
-      expect(store.model).toBe(Item)
-      expect(store.primaryKey).toBe('id')
-      expect(getClientFor).not.toHaveBeenCalled()
-
-      await store.getCollection()
-
-      expect(getClientFor).toHaveBeenCalledTimes(1)
-      expect(getClientFor).toHaveBeenCalledWith('mongodb://stub-host:1234', { appName: 'spec' })
-      expect(db).toHaveBeenCalledWith('unit-db')
-      expect(collection).toHaveBeenCalledWith('unit-coll')
-      expect(createIndex).toHaveBeenCalledWith({ id: 1 }, { unique: true })
-    } finally {
-      await injector[Symbol.asyncDispose]()
-    }
-  })
-
-  it('disposing the injector tears down the bound MongoClientFactory', async () => {
-    const { client } = buildClientStub()
-    const getClientFor = vi.fn(() => client)
-
-    const Token = defineMongoDbStore<Item, 'id'>({
-      name: 'test/MongoDispose',
-      model: Item,
-      primaryKey: 'id',
-      url: 'mongodb://stub-host:1234',
-      db: 'unit-db',
-      collection: 'unit-coll',
-    })
-
-    const injector = createInjector()
-    injector.bind(MongoClientFactory, () => ({ getClientFor }))
-
-    injector.get(Token)
-    await expect(injector[Symbol.asyncDispose]()).resolves.toBeUndefined()
-  })
-})
+import { createInjector } from '@furystack/inject'
+import type { MongoClient } from 'mongodb'
+import { describe, expect, it, vi } from 'vitest'
+import { defineMongoDbStore } from './define-mongodb-store.js'
+import { MongoClientFactory } from './mongo-client-factory.js'
+import { MongodbStore } from './mongodb-store.js'
+
+class Item {
+  declare id: string
+  declare value: string
+}
+
+describe('defineMongoDbStore (metadata)', () => {
+  it('propagates name, lifetime, model and primaryKey onto the returned token', () => {
+    const token = defineMongoDbStore<Item, 'id'>({
+      name: 'test/MongoItems',
+      model: Item,
+      primaryKey: 'id',
+      url: 'mongodb://localhost:27017',
+      db: 'unit-test',
+      collection: 'items',
+    })
+    expect(token.name).toBe('test/MongoItems')
+    expect(token.lifetime).toBe('singleton')
+    expect(token.model).toBe(Item)
+    expect(token.primaryKey).toBe('id')
+  })
+
+  it('mints a distinct token identity per call even when options match -- declare once at module scope', () => {
+    const options = {
+      name: 'test/MongoDupe',
+      model: Item,
+      primaryKey: 'id' as const,
+      url: 'mongodb://localhost:27017',
+      db: 'unit-test',
+      collection: 'items',
+    }
+    const a = defineMongoDbStore<Item, 'id'>(options)
+    const b = defineMongoDbStore<Item, 'id'>(options)
+    expect(a.id).not.toBe(b.id)
+  })
+})
+
+describe('defineMongoDbStore (factory + disposal)', () => {
+  const buildClientStub = () => {
+    const createIndex = vi.fn<() => Promise<string>>(() => Promise.resolve('id_1'))
+    const collection = vi.fn(() => ({ createIndex }))
+    const db = vi.fn(() => ({ collection }))
+    const client = { db } as unknown as MongoClient
+    return { client, db, collection, createIndex }
+  }
+
+  it('instantiates a MongodbStore whose lazy client pulls from the injected MongoClientFactory with the right url', async () => {
+    const { client, db, collection, createIndex } = buildClientStub()
+    const getClientFor = vi.fn(() => client)
+
+    const Token = defineMongoDbStore<Item, 'id'>({
+      name: 'test/MongoFactory',
+      model: Item,
+      primaryKey: 'id',
+      url: 'mongodb://stub-host:1234',
+      db: 'unit-db',
+      collection: 'unit-coll',
+      options: { appName: 'spec' },
+    })
+
+    const injector = createInjector()
+    injector.bind(MongoClientFactory, () => ({ getClientFor }))
+
+    try {
+      const store = injector.get(Token) as MongodbStore<Item, 'id'>
+      expect(store).toBeInstanceOf(MongodbStore)
+      expect(store.model).toBe(Item)
+      expect(store.primaryKey).toBe('id')
+      expect(getClientFor).not.toHaveBeenCalled()
+
+      await store.getCollection()
+
+      expect(getClientFor).toHaveBeenCalledTimes(1)
+      expect(getClientFor).toHaveBeenCalledWith('mongodb://stub-host:1234', { appName: 'spec' })
+      expect(db).toHaveBeenCalledWith('unit-db')
+      expect(collection).toHaveBeenCalledWith('unit-coll')
+      expect(createIndex).toHaveBeenCalledWith({ id: 1 }, { unique: true })
+    } finally {
+      await injector[Symbol.asyncDispose]()
+    }
+  })
+
+  it('disposing the injector tears down the bound MongoClientFactory', async () => {
+    const { client } = buildClientStub()
+    const getClientFor = vi.fn(() => client)
+
+    const Token = defineMongoDbStore<Item, 'id'>({
+      name: 'test/MongoDispose',
+      model: Item,
+      primaryKey: 'id',
+      url: 'mongodb://stub-host:1234',
+      db: 'unit-db',
+      collection: 'unit-coll',
+    })
+
+    const injector = createInjector()
+    injector.bind(MongoClientFactory, () => ({ getClientFor }))
+
+    injector.get(Token)
+    await expect(injector[Symbol.asyncDispose]()).resolves.toBeUndefined()
+  })
+})

package/src/define-mongodb-store.ts

@@ -1,58 +1,58 @@
-import type { Constructable, StoreToken } from '@furystack/core'
-import { defineStore } from '@furystack/core'
-import type { MongoClient, MongoClientOptions } from 'mongodb'
-import { MongoClientFactory } from './mongo-client-factory.js'
-import { MongodbStore } from './mongodb-store.js'
-
-/**
- * Options accepted by {@link defineMongoDbStore}.
- */
-export type DefineMongoDbStoreOptions<T extends object, TPrimaryKey extends keyof T> = {
-  name: string
-  model: Constructable<T>
-  primaryKey: TPrimaryKey
-  /** MongoDB deployment URL (e.g. `mongodb://localhost:27017`) — also acts as the pool key. */
-  url: string
-  db: string
-  collection: string
-  options?: MongoClientOptions
-}
-
-/**
- * Mints a singleton {@link StoreToken} backed by a {@link MongodbStore}.
- *
- * Internally resolves the singleton {@link MongoClientFactory} so every store
- * declared against the same `url` shares one {@link MongoClient}. Declare the
- * token once at module scope — inline calls mint new identities and defeat
- * singleton caching.
- *
- * @example
- * ```ts
- * export const UserStore = defineMongoDbStore({
- *   name: 'my-app/UserStore',
- *   model: User,
- *   primaryKey: 'username',
- *   url: 'mongodb://localhost:27017',
- *   db: 'my-app',
- *   collection: 'users',
- * })
- * ```
- */
-export const defineMongoDbStore = <T extends object, const TPrimaryKey extends keyof T>(
-  options: DefineMongoDbStoreOptions<T, TPrimaryKey>,
-): StoreToken<T, TPrimaryKey> =>
-  defineStore<T, TPrimaryKey>({
-    name: options.name,
-    model: options.model,
-    primaryKey: options.primaryKey,
-    factory: ({ inject }) => {
-      const factory = inject(MongoClientFactory)
-      return new MongodbStore<T, TPrimaryKey>({
-        model: options.model,
-        primaryKey: options.primaryKey,
-        db: options.db,
-        collection: options.collection,
-        mongoClient: () => factory.getClientFor(options.url, options.options),
-      })
-    },
-  })
+import type { Constructable, StoreToken } from '@furystack/core'
+import { defineStore } from '@furystack/core'
+import type { MongoClient, MongoClientOptions } from 'mongodb'
+import { MongoClientFactory } from './mongo-client-factory.js'
+import { MongodbStore } from './mongodb-store.js'
+
+/**
+ * Options accepted by {@link defineMongoDbStore}.
+ */
+export type DefineMongoDbStoreOptions<T extends object, TPrimaryKey extends keyof T> = {
+  name: string
+  model: Constructable<T>
+  primaryKey: TPrimaryKey
+  /** MongoDB deployment URL (e.g. `mongodb://localhost:27017`) — also acts as the pool key. */
+  url: string
+  db: string
+  collection: string
+  options?: MongoClientOptions
+}
+
+/**
+ * Mints a singleton {@link StoreToken} backed by a {@link MongodbStore}.
+ *
+ * Internally resolves the singleton {@link MongoClientFactory} so every store
+ * declared against the same `url` shares one {@link MongoClient}. Declare the
+ * token once at module scope — inline calls mint new identities and defeat
+ * singleton caching.
+ *
+ * @example
+ * ```ts
+ * export const UserStore = defineMongoDbStore({
+ *   name: 'my-app/UserStore',
+ *   model: User,
+ *   primaryKey: 'username',
+ *   url: 'mongodb://localhost:27017',
+ *   db: 'my-app',
+ *   collection: 'users',
+ * })
+ * ```
+ */
+export const defineMongoDbStore = <T extends object, const TPrimaryKey extends keyof T>(
+  options: DefineMongoDbStoreOptions<T, TPrimaryKey>,
+): StoreToken<T, TPrimaryKey> =>
+  defineStore<T, TPrimaryKey>({
+    name: options.name,
+    model: options.model,
+    primaryKey: options.primaryKey,
+    factory: ({ inject }) => {
+      const factory = inject(MongoClientFactory)
+      return new MongodbStore<T, TPrimaryKey>({
+        model: options.model,
+        primaryKey: options.primaryKey,
+        db: options.db,
+        collection: options.collection,
+        mongoClient: () => factory.getClientFor(options.url, options.options),
+      })
+    },
+  })

package/src/index.ts

@@ -1,3 +1,3 @@
-export * from './define-mongodb-store.js'
-export * from './mongo-client-factory.js'
-export * from './mongodb-store.js'
+export * from './define-mongodb-store.js'
+export * from './mongo-client-factory.js'
+export * from './mongodb-store.js'

package/src/mongo-client-factory.ts

@@ -1,45 +1,45 @@
-import type { Token } from '@furystack/inject'
-import { defineService } from '@furystack/inject'
-import type { MongoClientOptions } from 'mongodb'
-import { MongoClient } from 'mongodb'
-
-import type { defineMongoDbStore } from './define-mongodb-store.js'
-
-/**
- * Pools {@link MongoClient} instances by URL so every store that targets the
- * same MongoDB deployment shares a single connection.
- *
- * Application code rarely calls this directly — {@link defineMongoDbStore}
- * resolves the factory token internally. Exported for tests and advanced
- * integrations that need raw client access (e.g. dropping a test database).
- */
-export interface MongoClientFactory {
-  getClientFor(url: string, options?: MongoClientOptions): MongoClient
-}
-
-/**
- * Singleton token for the {@link MongoClientFactory}. Closes every pooled
- * client when the owning injector is disposed.
- */
-export const MongoClientFactory: Token<MongoClientFactory, 'singleton'> = defineService({
-  name: '@furystack/mongodb-store/MongoClientFactory',
-  lifetime: 'singleton',
-  factory: ({ onDispose }) => {
-    const connections = new Map<string, MongoClient>()
-    onDispose(async () => {
-      await Promise.all([...connections.values()].map((c) => c.close(true)))
-      connections.clear()
-    })
-    return {
-      getClientFor(url: string, options?: MongoClientOptions): MongoClient {
-        const existing = connections.get(url)
-        if (existing) {
-          return existing
-        }
-        const client = new MongoClient(url, options)
-        connections.set(url, client)
-        return client
-      },
-    }
-  },
-})
+import type { Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
+import type { MongoClientOptions } from 'mongodb'
+import { MongoClient } from 'mongodb'
+
+import type { defineMongoDbStore } from './define-mongodb-store.js'
+
+/**
+ * Pools {@link MongoClient} instances by URL so every store that targets the
+ * same MongoDB deployment shares a single connection.
+ *
+ * Application code rarely calls this directly — {@link defineMongoDbStore}
+ * resolves the factory token internally. Exported for tests and advanced
+ * integrations that need raw client access (e.g. dropping a test database).
+ */
+export interface MongoClientFactory {
+  getClientFor(url: string, options?: MongoClientOptions): MongoClient
+}
+
+/**
+ * Singleton token for the {@link MongoClientFactory}. Closes every pooled
+ * client when the owning injector is disposed.
+ */
+export const MongoClientFactory: Token<MongoClientFactory, 'singleton'> = defineService({
+  name: '@furystack/mongodb-store/MongoClientFactory',
+  lifetime: 'singleton',
+  factory: ({ onDispose }) => {
+    const connections = new Map<string, MongoClient>()
+    onDispose(async () => {
+      await Promise.all([...connections.values()].map((c) => c.close(true)))
+      connections.clear()
+    })
+    return {
+      getClientFor(url: string, options?: MongoClientOptions): MongoClient {
+        const existing = connections.get(url)
+        if (existing) {
+          return existing
+        }
+        const client = new MongoClient(url, options)
+        connections.set(url, client)
+        return client
+      },
+    }
+  },
+})