monsqlize 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,14 +1,19 @@
 # CHANGELOG
 
-> Summary index — the latest stable release details are in [changelogs/v3.2.0.md](./changelogs/v3.2.0.md); the earlier RC note remains an unpublished rehearsal archive.
-> **Last updated**: 2026-08-07
+> Summary index — the newest versioned release details are in [changelogs/v3.3.0.md](./changelogs/v3.3.0.md); the earlier RC note remains an unpublished rehearsal archive.
+> **Last updated**: 2026-08-11
 
 ---
 
+## Unreleased
+
+No changes are currently recorded after v3.3.0.
+
 ## Version Overview
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v3.3.0](./changelogs/v3.3.0.md) | 2026-08-11 | Minor: static Model schema type inference, schema-dsl 3.0.4, and silent-by-default Pool logging | [View](./changelogs/v3.3.0.md) |
 | [v3.2.0](./changelogs/v3.2.0.md) | 2026-08-07 | Minor: Vector Search APIs, relation-safe Model deletion, and relation projection improvements | [View](./changelogs/v3.2.0.md) |
 | [v3.1.0](./changelogs/v3.1.0.md) | 2026-07-15 | Minor: schema-dsl v3 GA consumption, canonical validation errors, and normalized full-document persistence | [View](./changelogs/v3.1.0.md) |
 | [v3.0.0](./changelogs/v3.0.0.md) | 2026-07-14 | Major: two-instance preview/apply/restore data tasks, write-path policy, runtime-scoped schema DSL, stricter OCC/sync/query contracts, and release recovery controls | [View](./changelogs/v3.0.0.md) |

package/README.md

@@ -14,7 +14,7 @@ Upgrade and security: [Migration Guide](./MIGRATION.md) · [Private Vulnerabilit
 
 The npm `latest` dist-tag and GitHub Pages are the stable channel; `main` may contain the next release. Pages deployment accepts only a versioned Git tag whose package version is already present on npm, so unpublished APIs are not promoted as stable documentation.
 
-This source tree contains the stable `3.1.0` release candidate, pinned to verified registry `schema-dsl@3.0.0`. The v3 package remains subject to the full release gate before its immutable tag and npm publication.
+This development source is pinned to verified registry `schema-dsl@3.0.4`. The v3 package remains subject to the full release gate before an immutable tag and npm publication.
 
 ```bash
 npm install monsqlize
@@ -234,6 +234,30 @@ const user = await User.insertOne({
 });
 ```
 
+### TypeScript Schema Inference
+
+For a static object-literal schema, `defineModel()` carries the schema-derived document type from definition through registration to runtime access. Registration remains explicit, so it does not change the process-wide Model registry behavior.
+
+```ts
+import { defineModel, Model } from 'monsqlize';
+
+const User = defineModel('users', {
+  schema: {
+    email: 'email!',
+    age: 'number?'
+  }
+});
+
+Model.define(User);
+
+const users = msq.model(User);
+const user = await users.findOne({ email: 'ada@example.com' });
+// user?.email: string
+// user?.age: number | undefined
+```
+
+Call `Model.define(User)` before `model(User)`, `use(...).model(User)`, or `pool(...).model(User)`. Callback-based or dynamically composed schemas continue to use the existing explicit generic API, such as `msq.model<UserDocument>('users')`; managed fields added by timestamps, soft delete, versioning, relations, or virtuals are not synthesized into this schema-derived type.
+
 When a service needs runtime-local custom types, messages, locale, or an already-owned schema-dsl runtime, configure `schemaDsl` on the MonSQLize instance:
 
 ```js

package/changelogs/v3.3.0.md

@@ -0,0 +1,29 @@
+# monSQLize v3.3.0
+
+> Release date: 2026-08-11
+
+## Highlights
+
+- Added schema-derived TypeScript document inference for static Model definitions.
+- Made Pool logging silent by default while preserving explicit logger delivery.
+
+## Added
+
+- Added `defineModel()` and `ModelDescriptor` so object-literal `schema` definitions carry their inferred document type through `Model.define()`, `model()`, `scopedModel()`, `use().model()`, and `pool().model()`.
+- Added CJS, ESM, public-type, compatibility, pack-consumer, and registry-consumer verification for the descriptor API.
+
+## Changed
+
+- Updated the exact production dependency from `schema-dsl@3.0.0` to `schema-dsl@3.0.4`.
+- Extended current-version validation so README and bilingual dependency-governance documents must match the exact `schema-dsl` version in `package.json`.
+
+## Fixed
+
+- Forwarded the configured `ConnectionPoolManager` logger to `PoolSelector`, `HealthChecker`, and `PoolStatsManager`.
+- Removed implicit `console` fallback logging from Pool helpers when no logger is configured.
+
+## Compatibility boundaries
+
+- This is a backward-compatible minor release. Existing string-based Model registration/access, manual TypeScript generics, Pool APIs, and explicit process-wide Model registry lifecycle remain unchanged.
+- `defineModel()` creates a static descriptor; it does not register the Model. Call `Model.define(descriptor)` before binding it through a runtime accessor.
+- Callback or dynamically composed schemas continue to use explicit document generics. Schema-derived types do not synthesize timestamp, soft-delete, version, relation, or virtual fields.

package/dist/cjs/cli/data-task.cjs

@@ -31,7 +31,7 @@ var import_node_url = require("node:url");
 // package.json
 var package_default = {
   name: "monsqlize",
-  version: "3.2.0",
+  version: "3.3.0",
   description: "TypeScript production data runtime layer for MongoDB today, with cache, transactions, pools, models, sync, and observability",
   type: "commonjs",
   main: "./dist/cjs/index.cjs",
@@ -52,6 +52,7 @@ var package_default = {
     "./package.json": "./package.json"
   },
   files: [
+    "changelogs/v3.3.0.md",
     "changelogs/v3.2.0.md",
     "changelogs/v3.1.14.md",
     "changelogs/v3.1.13.md",
@@ -191,7 +192,7 @@ var package_default = {
     "cache-hub": "2.2.4",
     ioredis: "5.11.1",
     mongodb: "6.21.0",
-    "schema-dsl": "3.0.0",
+    "schema-dsl": "3.0.4",
     ssh2: "1.17.0"
   },
   overrides: {

package/dist/cjs/index.cjs

@@ -549,6 +549,9 @@ function normalizePopulateConfig(path5) {
 }
 
 // src/capabilities/model/model-registry.ts
+function defineModel(collectionName, definition) {
+  return { collectionName, definition };
+}
 var Model = class {
   static {
     // collection name → registered model definition
@@ -563,21 +566,19 @@ var Model = class {
     /** Collection names that have been redefined (used by the runtime to trigger hot-reload). */
     this._redefinedNames = /* @__PURE__ */ new Set();
   }
-  /**
-   * Register a new model definition.
-   * Throws MODEL_ALREADY_EXISTS if a model with the same name already exists.
-   * Validates the definition and resolves the timestamps option.
-   */
-  static define(collectionName, definition) {
+  static define(collectionNameOrDescriptor, definition) {
+    const collectionName = typeof collectionNameOrDescriptor === "string" ? collectionNameOrDescriptor : collectionNameOrDescriptor.collectionName;
+    const modelDefinition = typeof collectionNameOrDescriptor === "string" ? definition : collectionNameOrDescriptor.definition;
     const normalizedName = validateCollectionName(collectionName);
     if (this.registry.has(normalizedName)) {
       throw createError(ErrorCodes.MODEL_ALREADY_EXISTS, `Model '${normalizedName}' is already defined.`);
     }
-    validateDefinition(definition);
-    processTimestamps(definition);
+    validateDefinition(modelDefinition);
+    const resolvedDefinition = modelDefinition;
+    processTimestamps(resolvedDefinition);
     this.registry.set(normalizedName, {
       collectionName: normalizedName,
-      definition
+      definition: resolvedDefinition
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     });
     this.bumpRevision(normalizedName);
@@ -7677,6 +7678,7 @@ var CountQueue = class {
 };
 
 // src/capabilities/pool/pool-health-checker.ts
+var SILENT_HEALTH_CHECKER_LOGGER = {};
 var HealthChecker = class {
   constructor(options = {}) {
     this._healthStatus = /* @__PURE__ */ new Map();
@@ -7686,7 +7688,7 @@ var HealthChecker = class {
     this._inProgress = /* @__PURE__ */ new Set();
     this._started = false;
     this._poolManager = options.poolManager ?? null;
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_HEALTH_CHECKER_LOGGER;
   }
   register(poolNameOrConfig, configOrClient) {
     let poolName;
@@ -7810,6 +7812,7 @@ var HealthChecker = class {
 };
 
 // src/capabilities/pool/pool-selector.ts
+var SILENT_POOL_SELECTOR_LOGGER = {};
 var POOL_STRATEGY_ALIASES = {
   "round-robin": "roundRobin",
   "least-connections": "leastConnections",
@@ -7823,7 +7826,7 @@ var PoolSelector = class {
   constructor(options = {}) {
     this._roundRobinIndex = /* @__PURE__ */ new Map();
     this._strategy = normalizePoolStrategy(options.strategy);
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_SELECTOR_LOGGER;
   }
   select(pools, context) {
     if (!pools || pools.length === 0) {
@@ -7954,11 +7957,12 @@ var PoolSelector = class {
 };
 
 // src/capabilities/pool/pool-stats-manager.ts
+var SILENT_POOL_STATS_LOGGER = {};
 var PoolStatsManager = class {
   constructor(options = {}) {
     this._stats = /* @__PURE__ */ new Map();
     this._buffer = [];
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_STATS_LOGGER;
     this._batchInterval = setInterval(() => {
       this._flush();
     }, 100);
@@ -8206,9 +8210,9 @@ var ConnectionPoolManager = class {
     this._fallbackConfig = this.fallback;
     this._fallback = this.fallback;
     this._pools = this.pools;
-    this._selector = new PoolSelector({ strategy: this.strategy });
-    this._healthChecker = new HealthChecker({ poolManager: this });
-    this._stats = new PoolStatsManager({ logger: options.logger ?? void 0 });
+    this._selector = new PoolSelector({ strategy: this.strategy, logger: this.logger ?? void 0 });
+    this._healthChecker = new HealthChecker({ poolManager: this, logger: this.logger ?? void 0 });
+    this._stats = new PoolStatsManager({ logger: this.logger ?? void 0 });
   }
   /**
    * Add a connection pool.
@@ -12783,10 +12787,10 @@ function assertCompatPoolExists(poolManager, poolName) {
 function createPoolScope(runtime, poolName) {
   return {
     collection: (name) => runtime.scopedCollection(name, { pool: poolName }),
-    model: (name) => runtime.scopedModel(name, { pool: poolName }),
+    model: (model) => runtime.scopedModel(model, { pool: poolName }),
     use: (dbName) => ({
       collection: (name) => runtime.scopedCollection(name, { pool: poolName, database: dbName }),
-      model: (name) => runtime.scopedModel(name, { pool: poolName, database: dbName })
+      model: (model) => runtime.scopedModel(model, { pool: poolName, database: dbName })
     })
   };
 }
@@ -16942,7 +16946,7 @@ var MonSQLizeRuntime = class {
     requireCompatDbInstance(this);
     return {
       collection: (collectionName) => this.scopedCollection(collectionName, { database: name }),
-      model: (modelName) => this.scopedModel(modelName, { database: name })
+      model: (model) => this.scopedModel(model, { database: name })
     };
   }
   pool(poolName) {
@@ -16974,7 +16978,8 @@ var MonSQLizeRuntime = class {
     });
   }
   // Model accessors ---------------------------------------------------------
-  scopedModel(name, options = {}) {
+  scopedModel(model, options = {}) {
+    const name = typeof model === "string" ? model : model.collectionName;
     const dbInstance = requireCompatDbInstance(this);
     if (this._client) {
       return this.createModelInstance(name, options);
@@ -16998,7 +17003,8 @@ var MonSQLizeRuntime = class {
       schemaEngine: this._schemaDslEngine
     });
   }
-  model(name) {
+  model(model) {
+    const name = typeof model === "string" ? model : model.collectionName;
     if (this._client) {
       this.ensureConnected();
       return this.createModelInstance(name, {
@@ -18799,6 +18805,7 @@ MonSQLize.PoolSelector = PoolSelector;
 MonSQLize.PoolStats = PoolStatsManager;
 MonSQLize.validatePoolConfig = validatePoolConfig;
 MonSQLize.validatePoolConfigSafe = validatePoolConfigSafe;
+MonSQLize.defineModel = defineModel;
 MonSQLize.Model = Model;
 MonSQLize.expr = expr;
 MonSQLize.createExpression = createExpression;

package/dist/esm/index.mjs

@@ -532,6 +532,9 @@ function normalizePopulateConfig(path5) {
 }
 
 // src/capabilities/model/model-registry.ts
+function defineModel(collectionName, definition) {
+  return { collectionName, definition };
+}
 var Model = class {
   static {
     // collection name → registered model definition
@@ -546,21 +549,19 @@ var Model = class {
     /** Collection names that have been redefined (used by the runtime to trigger hot-reload). */
     this._redefinedNames = /* @__PURE__ */ new Set();
   }
-  /**
-   * Register a new model definition.
-   * Throws MODEL_ALREADY_EXISTS if a model with the same name already exists.
-   * Validates the definition and resolves the timestamps option.
-   */
-  static define(collectionName, definition) {
+  static define(collectionNameOrDescriptor, definition) {
+    const collectionName = typeof collectionNameOrDescriptor === "string" ? collectionNameOrDescriptor : collectionNameOrDescriptor.collectionName;
+    const modelDefinition = typeof collectionNameOrDescriptor === "string" ? definition : collectionNameOrDescriptor.definition;
     const normalizedName = validateCollectionName(collectionName);
     if (this.registry.has(normalizedName)) {
       throw createError(ErrorCodes.MODEL_ALREADY_EXISTS, `Model '${normalizedName}' is already defined.`);
     }
-    validateDefinition(definition);
-    processTimestamps(definition);
+    validateDefinition(modelDefinition);
+    const resolvedDefinition = modelDefinition;
+    processTimestamps(resolvedDefinition);
     this.registry.set(normalizedName, {
       collectionName: normalizedName,
-      definition
+      definition: resolvedDefinition
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     });
     this.bumpRevision(normalizedName);
@@ -7660,6 +7661,7 @@ var CountQueue = class {
 };
 
 // src/capabilities/pool/pool-health-checker.ts
+var SILENT_HEALTH_CHECKER_LOGGER = {};
 var HealthChecker = class {
   constructor(options = {}) {
     this._healthStatus = /* @__PURE__ */ new Map();
@@ -7669,7 +7671,7 @@ var HealthChecker = class {
     this._inProgress = /* @__PURE__ */ new Set();
     this._started = false;
     this._poolManager = options.poolManager ?? null;
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_HEALTH_CHECKER_LOGGER;
   }
   register(poolNameOrConfig, configOrClient) {
     let poolName;
@@ -7793,6 +7795,7 @@ var HealthChecker = class {
 };
 
 // src/capabilities/pool/pool-selector.ts
+var SILENT_POOL_SELECTOR_LOGGER = {};
 var POOL_STRATEGY_ALIASES = {
   "round-robin": "roundRobin",
   "least-connections": "leastConnections",
@@ -7806,7 +7809,7 @@ var PoolSelector = class {
   constructor(options = {}) {
     this._roundRobinIndex = /* @__PURE__ */ new Map();
     this._strategy = normalizePoolStrategy(options.strategy);
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_SELECTOR_LOGGER;
   }
   select(pools, context) {
     if (!pools || pools.length === 0) {
@@ -7937,11 +7940,12 @@ var PoolSelector = class {
 };
 
 // src/capabilities/pool/pool-stats-manager.ts
+var SILENT_POOL_STATS_LOGGER = {};
 var PoolStatsManager = class {
   constructor(options = {}) {
     this._stats = /* @__PURE__ */ new Map();
     this._buffer = [];
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_STATS_LOGGER;
     this._batchInterval = setInterval(() => {
       this._flush();
     }, 100);
@@ -8189,9 +8193,9 @@ var ConnectionPoolManager = class {
     this._fallbackConfig = this.fallback;
     this._fallback = this.fallback;
     this._pools = this.pools;
-    this._selector = new PoolSelector({ strategy: this.strategy });
-    this._healthChecker = new HealthChecker({ poolManager: this });
-    this._stats = new PoolStatsManager({ logger: options.logger ?? void 0 });
+    this._selector = new PoolSelector({ strategy: this.strategy, logger: this.logger ?? void 0 });
+    this._healthChecker = new HealthChecker({ poolManager: this, logger: this.logger ?? void 0 });
+    this._stats = new PoolStatsManager({ logger: this.logger ?? void 0 });
   }
   /**
    * Add a connection pool.
@@ -12766,10 +12770,10 @@ function assertCompatPoolExists(poolManager, poolName) {
 function createPoolScope(runtime, poolName) {
   return {
     collection: (name) => runtime.scopedCollection(name, { pool: poolName }),
-    model: (name) => runtime.scopedModel(name, { pool: poolName }),
+    model: (model) => runtime.scopedModel(model, { pool: poolName }),
     use: (dbName) => ({
       collection: (name) => runtime.scopedCollection(name, { pool: poolName, database: dbName }),
-      model: (name) => runtime.scopedModel(name, { pool: poolName, database: dbName })
+      model: (model) => runtime.scopedModel(model, { pool: poolName, database: dbName })
     })
   };
 }
@@ -16928,7 +16932,7 @@ var MonSQLizeRuntime = class {
     requireCompatDbInstance(this);
     return {
       collection: (collectionName) => this.scopedCollection(collectionName, { database: name }),
-      model: (modelName) => this.scopedModel(modelName, { database: name })
+      model: (model) => this.scopedModel(model, { database: name })
     };
   }
   pool(poolName) {
@@ -16960,7 +16964,8 @@ var MonSQLizeRuntime = class {
     });
   }
   // Model accessors ---------------------------------------------------------
-  scopedModel(name, options = {}) {
+  scopedModel(model, options = {}) {
+    const name = typeof model === "string" ? model : model.collectionName;
     const dbInstance = requireCompatDbInstance(this);
     if (this._client) {
       return this.createModelInstance(name, options);
@@ -16984,7 +16989,8 @@ var MonSQLizeRuntime = class {
       schemaEngine: this._schemaDslEngine
     });
   }
-  model(name) {
+  model(model) {
+    const name = typeof model === "string" ? model : model.collectionName;
     if (this._client) {
       this.ensureConnected();
       return this.createModelInstance(name, {
@@ -18785,6 +18791,7 @@ MonSQLize.PoolSelector = PoolSelector;
 MonSQLize.PoolStats = PoolStatsManager;
 MonSQLize.validatePoolConfig = validatePoolConfig;
 MonSQLize.validatePoolConfigSafe = validatePoolConfigSafe;
+MonSQLize.defineModel = defineModel;
 MonSQLize.Model = Model;
 MonSQLize.ModelInstance = ModelInstance;
 MonSQLize.expr = expr;
@@ -18874,6 +18881,7 @@ export {
   dataTasks,
   decodeCursor2 as decodeCursor,
   index_default as default,
+  defineModel,
   encodeCursor2 as encodeCursor,
   expr,
   generateQueryHash,

package/dist/types/model.d.mts

@@ -1,4 +1,5 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult, VectorSearchHit, VectorSearchOptions } from './collection.mjs';
+import type { InferSchema } from 'schema-dsl';
 import type { SchemaDslRuntime } from 'schema-dsl/runtime';
 
 /**
@@ -12,6 +13,42 @@ export type ModelSchemaDsl = SchemaDslRuntime['s'];
  */
 export type SchemaDSL = (s: ModelSchemaDsl) => unknown;
 
+/**
+ * A statically typed Model registration descriptor.
+ *
+ * The descriptor preserves the document type inferred from an object-literal
+ * schema while keeping Model registration explicit at runtime.
+ * @since v3.3.0
+ */
+export interface ModelDescriptor<TName extends string = string, TDocument = Record<string, unknown>> {
+    readonly collectionName: TName;
+    readonly definition: ModelDefinition<TDocument>;
+    readonly __document?: TDocument;
+}
+
+/**
+ * Extract the document type carried by a Model descriptor.
+ * @since v3.3.0
+ */
+export type InferModelDocument<TDescriptor> = TDescriptor extends ModelDescriptor<string, infer TDocument>
+    ? TDocument
+    : never;
+
+/**
+ * Create a typed Model descriptor from a static object-literal schema.
+ *
+ * Register the returned descriptor with `Model.define(descriptor)` before
+ * binding it through a MonSQLize runtime. Callback schemas continue to use
+ * the existing explicit generic APIs because their static shape is not stable.
+ * @since v3.3.0
+ */
+export declare function defineModel<
+    const TName extends string,
+    const TSchema extends Record<string, unknown>,
+>(collectionName: TName, definition: Omit<ModelDefinition<InferSchema<TSchema>>, 'schema'> & {
+    schema: TSchema;
+}): ModelDescriptor<TName, InferSchema<TSchema>>;
+
 /**
  * Default value for a model field — either a static value or a factory function.
  * @template T Field value type
@@ -739,6 +776,8 @@ export interface ModelInstance<TDocument = any> {
 }
 
 export declare class Model {
+    /** @since v3.3.0 */
+    static define<TName extends string, TDocument>(descriptor: ModelDescriptor<TName, TDocument>): void;
     static define<TDocument = Record<string, unknown>>(collectionName: string, definition: ModelDefinition<TDocument>): void;
     static get<TDocument = Record<string, unknown>>(collectionName: string): RegisteredModel<TDocument> | undefined;
     static has(collectionName: string): boolean;

package/dist/types/model.d.ts

@@ -1,4 +1,5 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult, VectorSearchHit, VectorSearchOptions } from './collection';
+import type { InferSchema } from 'schema-dsl';
 import type { SchemaDslRuntime } from 'schema-dsl/runtime';
 
 /**
@@ -12,6 +13,42 @@ export type ModelSchemaDsl = SchemaDslRuntime['s'];
  */
 export type SchemaDSL = (s: ModelSchemaDsl) => unknown;
 
+/**
+ * A statically typed Model registration descriptor.
+ *
+ * The descriptor preserves the document type inferred from an object-literal
+ * schema while keeping Model registration explicit at runtime.
+ * @since v3.3.0
+ */
+export interface ModelDescriptor<TName extends string = string, TDocument = Record<string, unknown>> {
+    readonly collectionName: TName;
+    readonly definition: ModelDefinition<TDocument>;
+    readonly __document?: TDocument;
+}
+
+/**
+ * Extract the document type carried by a Model descriptor.
+ * @since v3.3.0
+ */
+export type InferModelDocument<TDescriptor> = TDescriptor extends ModelDescriptor<string, infer TDocument>
+    ? TDocument
+    : never;
+
+/**
+ * Create a typed Model descriptor from a static object-literal schema.
+ *
+ * Register the returned descriptor with `Model.define(descriptor)` before
+ * binding it through a MonSQLize runtime. Callback schemas continue to use
+ * the existing explicit generic APIs because their static shape is not stable.
+ * @since v3.3.0
+ */
+export declare function defineModel<
+    const TName extends string,
+    const TSchema extends Record<string, unknown>,
+>(collectionName: TName, definition: Omit<ModelDefinition<InferSchema<TSchema>>, 'schema'> & {
+    schema: TSchema;
+}): ModelDescriptor<TName, InferSchema<TSchema>>;
+
 /**
  * Default value for a model field — either a static value or a factory function.
  * @template T Field value type
@@ -739,6 +776,8 @@ export interface ModelInstance<TDocument = any> {
 }
 
 export declare class Model {
+    /** @since v3.3.0 */
+    static define<TName extends string, TDocument>(descriptor: ModelDescriptor<TName, TDocument>): void;
     static define<TDocument = Record<string, unknown>>(collectionName: string, definition: ModelDefinition<TDocument>): void;
     static get<TDocument = Record<string, unknown>>(collectionName: string): RegisteredModel<TDocument> | undefined;
     static has(collectionName: string): boolean;

package/dist/types/monsqlize.d.mts

@@ -35,7 +35,7 @@ export interface SSHConfig {
 import type { Collection, CursorValueNormalizer, CursorValueType, DbAccessor, HealthView } from './collection.mjs';
 import type { DataTaskJobError } from './data-tasks.mjs';
 import type { Lock, LockOptions, LockStats } from './lock.mjs';
-import type { ModelAutoIndexOptions, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model.mjs';
+import type { ModelAutoIndexOptions, ModelDescriptor, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model.mjs';
 import type { MongoConnectConfig } from './mongodb.mjs';
 import type { ConnectionPoolManagerOptions, PoolConfig, PoolHealthStatus, PoolStats, PoolStrategy } from './pool.mjs';
 import type {
@@ -70,6 +70,15 @@ import type { SlowQueryLogConfigInput, SlowQueryLogEntry, SlowQueryLogFilter, Sl
 import type { ChangeStreamSyncManager, SyncConfig, SyncStats } from './sync.mjs';
 import type { Transaction, TransactionOptions, TransactionStats } from './transaction.mjs';
 
+/**
+ * Callable model accessor that preserves a descriptor's inferred document type.
+ * @since v3.3.0
+ */
+export interface ModelBindingAccessor {
+    <TDocument>(descriptor: ModelDescriptor<string, TDocument>): ModelInstance<TDocument>;
+    <TDocument = any>(modelName: string): ModelInstance<TDocument>;
+}
+
 /** Write path policy mode. `allow-both` preserves the existing collection and model write behavior. */
 export type WritePathPolicyMode = 'allow-both' | 'model-only';
 
@@ -283,7 +292,7 @@ export interface MonSQLizeInstance {
         db: (name?: string) => DbAccessor;
         use: (name: string) => {
             collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-            model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
         instance: MonSQLize;
     }>;
@@ -315,7 +324,7 @@ export interface MonSQLizeInstance {
      */
     use(name: string): {
         collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-        model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
     };
     /**
      * Return collection and model accessors for the named connection pool.
@@ -323,10 +332,10 @@ export interface MonSQLizeInstance {
      */
     pool(poolName: string): {
         collection: <TSchema = any>(name: string) => Collection<TSchema>;
-        model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
         use: (dbName: string) => {
             collection: <TSchema = any>(name: string) => Collection<TSchema>;
-            model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
     };
     /**
@@ -341,12 +350,16 @@ export interface MonSQLizeInstance {
      * @param name Model name.
      * @param options Optional database or pool scope options.
      */
+    /** @since v3.3.0 */
+    scopedModel<TDocument>(descriptor: ModelDescriptor<string, TDocument>, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel<TDocument = any>(name: string, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel(name: string, options?: { database?: string; pool?: string; }): ModelInstance<any>;
     /**
      * Return the registered model instance for the given model name.
      * @param name Model name used during registration.
      */
+    /** @since v3.3.0 */
+    model<TDocument>(descriptor: ModelDescriptor<string, TDocument>): ModelInstance<TDocument>;
     model<TDocument = any>(name: string): ModelInstance<TDocument>;
     model(name: string): ModelInstance<any>;
     /**
@@ -516,7 +529,7 @@ export default class MonSQLize implements MonSQLizeInstance {
         db: (name?: string) => DbAccessor;
         use: (name: string) => {
             collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-            model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
         instance: MonSQLize;
     }>;
@@ -529,20 +542,24 @@ export default class MonSQLize implements MonSQLizeInstance {
     db(name?: string): DbAccessor;
     use(name: string): {
         collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-        model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
     };
     pool(poolName: string): {
         collection: <TSchema = any>(name: string) => Collection<TSchema>;
-        model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
         use: (dbName: string) => {
             collection: <TSchema = any>(name: string) => Collection<TSchema>;
-            model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
     };
     scopedCollection<TSchema = any>(name: string, options?: { database?: string; pool?: string; }): Collection<TSchema>;
     scopedCollection(name: string, options?: { database?: string; pool?: string; }): Collection<any>;
+    /** @since v3.3.0 */
+    scopedModel<TDocument>(descriptor: ModelDescriptor<string, TDocument>, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel<TDocument = any>(name: string, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel(name: string, options?: { database?: string; pool?: string; }): ModelInstance<any>;
+    /** @since v3.3.0 */
+    model<TDocument>(descriptor: ModelDescriptor<string, TDocument>): ModelInstance<TDocument>;
     model<TDocument = any>(name: string): ModelInstance<TDocument>;
     model(name: string): ModelInstance<any>;
     ensureModelIndexes(options?: ModelEnsureAllIndexesOptions): Promise<ModelIndexEnsureSummary>;
@@ -601,6 +618,8 @@ export default class MonSQLize implements MonSQLizeInstance {
     static LockTimeoutError: typeof import('./lock.mjs').LockTimeoutError;
     static DistributedCacheInvalidator: typeof DistributedCacheInvalidator;
     static ConnectionPoolManager: typeof import('./pool.mjs').ConnectionPoolManager;
+    /** @since v3.3.0 */
+    static defineModel: typeof import('./model.mjs').defineModel;
     static Model: typeof import('./runtime.mjs').Model;
     static ModelInstance: typeof import('./runtime.mjs').ModelInstance;
     static expr: typeof expr;

package/dist/types/monsqlize.d.ts

@@ -35,7 +35,7 @@ export interface SSHConfig {
 import type { Collection, CursorValueNormalizer, CursorValueType, DbAccessor, HealthView } from './collection';
 import type { DataTaskJobError } from './data-tasks';
 import type { Lock, LockOptions, LockStats } from './lock';
-import type { ModelAutoIndexOptions, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model';
+import type { ModelAutoIndexOptions, ModelDescriptor, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model';
 import type { MongoConnectConfig } from './mongodb';
 import type { ConnectionPoolManagerOptions, PoolConfig, PoolHealthStatus, PoolStats, PoolStrategy } from './pool';
 import type {
@@ -70,6 +70,15 @@ import type { SlowQueryLogConfigInput, SlowQueryLogEntry, SlowQueryLogFilter, Sl
 import type { ChangeStreamSyncManager, SyncConfig, SyncStats } from './sync';
 import type { Transaction, TransactionOptions, TransactionStats } from './transaction';
 
+/**
+ * Callable model accessor that preserves a descriptor's inferred document type.
+ * @since v3.3.0
+ */
+export interface ModelBindingAccessor {
+    <TDocument>(descriptor: ModelDescriptor<string, TDocument>): ModelInstance<TDocument>;
+    <TDocument = any>(modelName: string): ModelInstance<TDocument>;
+}
+
 /** Write path policy mode. `allow-both` preserves the existing collection and model write behavior. */
 export type WritePathPolicyMode = 'allow-both' | 'model-only';
 
@@ -283,7 +292,7 @@ export interface MonSQLizeInstance {
         db: (name?: string) => DbAccessor;
         use: (name: string) => {
             collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-            model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
         instance: MonSQLize;
     }>;
@@ -315,7 +324,7 @@ export interface MonSQLizeInstance {
      */
     use(name: string): {
         collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-        model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
     };
     /**
      * Return collection and model accessors for the named connection pool.
@@ -323,10 +332,10 @@ export interface MonSQLizeInstance {
      */
     pool(poolName: string): {
         collection: <TSchema = any>(name: string) => Collection<TSchema>;
-        model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
         use: (dbName: string) => {
             collection: <TSchema = any>(name: string) => Collection<TSchema>;
-            model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
     };
     /**
@@ -341,12 +350,16 @@ export interface MonSQLizeInstance {
      * @param name Model name.
      * @param options Optional database or pool scope options.
      */
+    /** @since v3.3.0 */
+    scopedModel<TDocument>(descriptor: ModelDescriptor<string, TDocument>, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel<TDocument = any>(name: string, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel(name: string, options?: { database?: string; pool?: string; }): ModelInstance<any>;
     /**
      * Return the registered model instance for the given model name.
      * @param name Model name used during registration.
      */
+    /** @since v3.3.0 */
+    model<TDocument>(descriptor: ModelDescriptor<string, TDocument>): ModelInstance<TDocument>;
     model<TDocument = any>(name: string): ModelInstance<TDocument>;
     model(name: string): ModelInstance<any>;
     /**
@@ -516,7 +529,7 @@ export default class MonSQLize implements MonSQLizeInstance {
         db: (name?: string) => DbAccessor;
         use: (name: string) => {
             collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-            model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
         instance: MonSQLize;
     }>;
@@ -529,20 +542,24 @@ export default class MonSQLize implements MonSQLizeInstance {
     db(name?: string): DbAccessor;
     use(name: string): {
         collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
-        model: <TDocument = any>(modelName: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
     };
     pool(poolName: string): {
         collection: <TSchema = any>(name: string) => Collection<TSchema>;
-        model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+        model: ModelBindingAccessor;
         use: (dbName: string) => {
             collection: <TSchema = any>(name: string) => Collection<TSchema>;
-            model: <TDocument = any>(name: string) => ModelInstance<TDocument>;
+            model: ModelBindingAccessor;
         };
     };
     scopedCollection<TSchema = any>(name: string, options?: { database?: string; pool?: string; }): Collection<TSchema>;
     scopedCollection(name: string, options?: { database?: string; pool?: string; }): Collection<any>;
+    /** @since v3.3.0 */
+    scopedModel<TDocument>(descriptor: ModelDescriptor<string, TDocument>, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel<TDocument = any>(name: string, options?: { database?: string; pool?: string; }): ModelInstance<TDocument>;
     scopedModel(name: string, options?: { database?: string; pool?: string; }): ModelInstance<any>;
+    /** @since v3.3.0 */
+    model<TDocument>(descriptor: ModelDescriptor<string, TDocument>): ModelInstance<TDocument>;
     model<TDocument = any>(name: string): ModelInstance<TDocument>;
     model(name: string): ModelInstance<any>;
     ensureModelIndexes(options?: ModelEnsureAllIndexesOptions): Promise<ModelIndexEnsureSummary>;
@@ -601,6 +618,8 @@ export default class MonSQLize implements MonSQLizeInstance {
     static LockTimeoutError: typeof import('./lock').LockTimeoutError;
     static DistributedCacheInvalidator: typeof DistributedCacheInvalidator;
     static ConnectionPoolManager: typeof import('./pool').ConnectionPoolManager;
+    /** @since v3.3.0 */
+    static defineModel: typeof import('./model').defineModel;
     static Model: typeof import('./runtime').Model;
     static ModelInstance: typeof import('./runtime').ModelInstance;
     static expr: typeof expr;

package/dist/types/runtime.d.mts

@@ -1,6 +1,6 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, UpdateBatchResult, UpdateResult } from './collection.mjs';
 import type { LoggerLike, ExpressionFunction, ExpressionObject } from './base.mjs';
-import type { ModelDefinition, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model.mjs';
+import type { ModelDefinition, ModelDescriptor, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model.mjs';
 import type { LockOptions, LockStats } from './lock.mjs';
 import type { ConnectionPoolManagerOptions, FallbackStrategy, PoolConfig, PoolHealthStatus, PoolRole, PoolStats, PoolStrategy } from './pool.mjs';
 import type { SagaDefinition, SagaOrchestratorOptions, SagaResult, SagaStats, SagaStep } from './saga.mjs';
@@ -289,6 +289,8 @@ export declare class FunctionCache {
 }
 
 export declare class Model {
+    /** @since v3.3.0 */
+    static define<TName extends string, TDocument>(descriptor: ModelDescriptor<TName, TDocument>): void;
     static define<TDocument = any>(name: string, definition: ModelDefinition<TDocument>): void;
     static get<TDocument = any>(name: string): RegisteredModel<TDocument> | undefined;
     static has(name: string): boolean;

package/dist/types/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, UpdateBatchResult, UpdateResult } from './collection';
 import type { LoggerLike, ExpressionFunction, ExpressionObject } from './base';
-import type { ModelDefinition, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model';
+import type { ModelDefinition, ModelDescriptor, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model';
 import type { LockOptions, LockStats } from './lock';
 import type { ConnectionPoolManagerOptions, FallbackStrategy, PoolConfig, PoolHealthStatus, PoolRole, PoolStats, PoolStrategy } from './pool';
 import type { SagaDefinition, SagaOrchestratorOptions, SagaResult, SagaStats, SagaStep } from './saga';
@@ -289,6 +289,8 @@ export declare class FunctionCache {
 }
 
 export declare class Model {
+    /** @since v3.3.0 */
+    static define<TName extends string, TDocument>(descriptor: ModelDescriptor<TName, TDocument>): void;
     static define<TDocument = any>(name: string, definition: ModelDefinition<TDocument>): void;
     static get<TDocument = any>(name: string): RegisteredModel<TDocument> | undefined;
     static has(name: string): boolean;

package/licenses/production-dependencies.json

@@ -5,7 +5,7 @@
     { "name": "cache-hub", "version": "2.2.4", "license": "Apache-2.0", "source": "package-metadata" },
     { "name": "ioredis", "version": "5.11.1", "license": "MIT", "source": "package-metadata" },
     { "name": "mongodb", "version": "6.21.0", "license": "Apache-2.0", "source": "package-metadata" },
-    { "name": "schema-dsl", "version": "3.0.0", "license": "Apache-2.0", "source": "package-metadata" },
+    { "name": "schema-dsl", "version": "3.0.4", "license": "Apache-2.0", "source": "package-metadata" },
     { "name": "ssh2", "version": "1.17.0", "license": "MIT", "source": "LICENSE:d06b5d27bbbbe22c36b1fd88406b1208876e2d37d795f5b8eaed951a459a3111" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "monsqlize",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "description": "TypeScript production data runtime layer for MongoDB today, with cache, transactions, pools, models, sync, and observability",
     "type": "commonjs",
     "main": "./dist/cjs/index.cjs",
@@ -21,6 +21,7 @@
         "./package.json": "./package.json"
     },
     "files": [
+        "changelogs/v3.3.0.md",
         "changelogs/v3.2.0.md",
         "changelogs/v3.1.14.md",
         "changelogs/v3.1.13.md",
@@ -160,7 +161,7 @@
         "cache-hub": "2.2.4",
         "ioredis": "5.11.1",
         "mongodb": "6.21.0",
-        "schema-dsl": "3.0.0",
+        "schema-dsl": "3.0.4",
         "ssh2": "1.17.0"
     },
     "overrides": {