monsqlize 3.3.4 → 3.4.0

package/dist/types/base.d.mts

@@ -37,6 +37,12 @@ export declare const enum ErrorCodes {
     INVALID_PAGINATION = 'INVALID_PAGINATION',
     INVALID_OPERATION = 'INVALID_OPERATION',
     INVALID_VECTOR_SEARCH = 'INVALID_VECTOR_SEARCH',
+    INVALID_SEARCH_INDEX_DEFINITION = 'INVALID_SEARCH_INDEX_DEFINITION',
+    SEARCH_INDEX_EXISTS = 'SEARCH_INDEX_EXISTS',
+    SEARCH_INDEX_NOT_FOUND = 'SEARCH_INDEX_NOT_FOUND',
+    SEARCH_INDEX_UNSUPPORTED = 'SEARCH_INDEX_UNSUPPORTED',
+    SEARCH_INDEX_BUILD_FAILED = 'SEARCH_INDEX_BUILD_FAILED',
+    SEARCH_INDEX_WAIT_TIMEOUT = 'SEARCH_INDEX_WAIT_TIMEOUT',
     INVALID_RELATION_SELECT = 'INVALID_RELATION_SELECT',
     RELATION_IN_USE = 'RELATION_IN_USE',
     RELATION_USAGE_UNAVAILABLE = 'RELATION_USAGE_UNAVAILABLE',

package/dist/types/base.d.ts

@@ -37,6 +37,12 @@ export declare const enum ErrorCodes {
     INVALID_PAGINATION = 'INVALID_PAGINATION',
     INVALID_OPERATION = 'INVALID_OPERATION',
     INVALID_VECTOR_SEARCH = 'INVALID_VECTOR_SEARCH',
+    INVALID_SEARCH_INDEX_DEFINITION = 'INVALID_SEARCH_INDEX_DEFINITION',
+    SEARCH_INDEX_EXISTS = 'SEARCH_INDEX_EXISTS',
+    SEARCH_INDEX_NOT_FOUND = 'SEARCH_INDEX_NOT_FOUND',
+    SEARCH_INDEX_UNSUPPORTED = 'SEARCH_INDEX_UNSUPPORTED',
+    SEARCH_INDEX_BUILD_FAILED = 'SEARCH_INDEX_BUILD_FAILED',
+    SEARCH_INDEX_WAIT_TIMEOUT = 'SEARCH_INDEX_WAIT_TIMEOUT',
     INVALID_RELATION_SELECT = 'INVALID_RELATION_SELECT',
     RELATION_IN_USE = 'RELATION_IN_USE',
     RELATION_USAGE_UNAVAILABLE = 'RELATION_USAGE_UNAVAILABLE',

package/dist/types/collection.d.mts

@@ -1,4 +1,4 @@
-import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
+import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb'; import type { SearchIndexManagement } from './search-index.mjs';
 import type {
     MetaOptions,
     VectorSearchHit,
@@ -685,7 +685,7 @@ export interface AdminAccessor {
     stats(options?: { scale?: number; }): Promise<DbStatsView>;
 }
 
-export interface Collection<TSchema = any> {
+export interface Collection<TSchema = any> extends SearchIndexManagement {
     /** Returns the namespace descriptor (iid, db, collection) for this collection. */
     getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; pool?: string; };
     /** Returns the underlying native MongoDB Collection object. */

package/dist/types/collection.d.ts

@@ -1,4 +1,4 @@
-import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
+import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb'; import type { SearchIndexManagement } from './search-index';
 import type {
     MetaOptions,
     VectorSearchHit,
@@ -685,7 +685,7 @@ export interface AdminAccessor {
     stats(options?: { scale?: number; }): Promise<DbStatsView>;
 }
 
-export interface Collection<TSchema = any> {
+export interface Collection<TSchema = any> extends SearchIndexManagement {
     /** Returns the namespace descriptor (iid, db, collection) for this collection. */
     getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; pool?: string; };
     /** Returns the underlying native MongoDB Collection object. */

package/dist/types/index.d.mts

@@ -8,6 +8,7 @@ export * from './mongodb.mjs';
 export * from './pool.mjs';
 export * from './runtime.mjs';
 export * from './saga.mjs';
+export * from './search-index.mjs';
 export * from './slow-query-log.mjs';
 export * from './sync.mjs';
 export * from './transaction.mjs';

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ export * from './mongodb';
 export * from './pool';
 export * from './runtime';
 export * from './saga';
+export * from './search-index';
 export * from './slow-query-log';
 export * from './sync';
 export * from './transaction';

package/dist/types/model.d.mts

@@ -1,5 +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 { InferSchema } from 'schema-dsl'; import type { SearchIndexManagement } from './search-index.mjs';
 import type { SchemaDslRuntime } from 'schema-dsl/runtime';
 
 /**
@@ -428,7 +428,7 @@ export type ModelDocument<TDocument = any> = TDocument & Record<string, unknown>
     toJSON(): TDocument & Record<string, unknown>;
 };
 
-export interface ModelInstance<TDocument = any> {
+export interface ModelInstance<TDocument = any> extends SearchIndexManagement {
     readonly collectionName: string;
     readonly dbName: string;
     readonly poolName?: string;

package/dist/types/model.d.ts

@@ -1,5 +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 { InferSchema } from 'schema-dsl'; import type { SearchIndexManagement } from './search-index';
 import type { SchemaDslRuntime } from 'schema-dsl/runtime';
 
 /**
@@ -428,7 +428,7 @@ export type ModelDocument<TDocument = any> = TDocument & Record<string, unknown>
     toJSON(): TDocument & Record<string, unknown>;
 };
 
-export interface ModelInstance<TDocument = any> {
+export interface ModelInstance<TDocument = any> extends SearchIndexManagement {
     readonly collectionName: string;
     readonly dbName: string;
     readonly poolName?: string;

package/dist/types/runtime.d.mts

@@ -345,6 +345,13 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
     dropIndex(name: string): Promise<unknown>;
     dropIndexes(): Promise<unknown>;
+    createSearchIndex(spec: import('./search-index.mjs').SearchIndexSpec, options?: import('./search-index.mjs').CreateSearchIndexOptions): Promise<import('./search-index.mjs').CreateSearchIndexResult>;
+    createSearchIndexes(specs: import('./search-index.mjs').SearchIndexSpec[]): Promise<string[]>;
+    listSearchIndexes(options?: import('./search-index.mjs').ListSearchIndexesOptions): Promise<import('./search-index.mjs').SearchIndexInfo[]>;
+    getSearchIndex(name: string): Promise<import('./search-index.mjs').SearchIndexInfo>;
+    updateSearchIndex(name: string, definition: Record<string, unknown>): Promise<void>;
+    dropSearchIndex(name: string, options?: import('./search-index.mjs').DropSearchIndexOptions): Promise<void>;
+    waitForSearchIndex(name: string, options?: import('./search-index.mjs').WaitForSearchIndexOptions): Promise<import('./search-index.mjs').SearchIndexInfo>;
     prewarmBookmarks(keyDims?: unknown, pages?: number[]): Promise<BookmarkPrewarmResult>;
     listBookmarks(keyDims?: unknown): Promise<BookmarkListResult>;
     clearBookmarks(keyDims?: unknown): Promise<BookmarkClearResult>;

package/dist/types/runtime.d.ts

@@ -345,6 +345,13 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
     dropIndex(name: string): Promise<unknown>;
     dropIndexes(): Promise<unknown>;
+    createSearchIndex(spec: import('./search-index').SearchIndexSpec, options?: import('./search-index').CreateSearchIndexOptions): Promise<import('./search-index').CreateSearchIndexResult>;
+    createSearchIndexes(specs: import('./search-index').SearchIndexSpec[]): Promise<string[]>;
+    listSearchIndexes(options?: import('./search-index').ListSearchIndexesOptions): Promise<import('./search-index').SearchIndexInfo[]>;
+    getSearchIndex(name: string): Promise<import('./search-index').SearchIndexInfo>;
+    updateSearchIndex(name: string, definition: Record<string, unknown>): Promise<void>;
+    dropSearchIndex(name: string, options?: import('./search-index').DropSearchIndexOptions): Promise<void>;
+    waitForSearchIndex(name: string, options?: import('./search-index').WaitForSearchIndexOptions): Promise<import('./search-index').SearchIndexInfo>;
     prewarmBookmarks(keyDims?: unknown, pages?: number[]): Promise<BookmarkPrewarmResult>;
     listBookmarks(keyDims?: unknown): Promise<BookmarkListResult>;
     clearBookmarks(keyDims?: unknown): Promise<BookmarkClearResult>;

package/dist/types/search-index.d.mts

@@ -0,0 +1,107 @@
+/**
+ * Search index lifecycle types (Atlas Search / Vector Search).
+ * @since v3.4.0
+ */
+
+/** Search index kind: full-text `search` or `vectorSearch`. */
+export type SearchIndexType = 'search' | 'vectorSearch';
+
+/** Origin of `SearchIndexInfo.type`. */
+export type SearchIndexTypeSource = 'server' | 'inferred' | 'unknown';
+
+/** Server-reported Search index status (passed through unchanged). */
+export type SearchIndexStatus =
+    | 'PENDING'
+    | 'BUILDING'
+    | 'READY'
+    | 'FAILED'
+    | 'STALE'
+    | 'DELETING'
+    | 'DOES_NOT_EXIST';
+
+/** Search index definition submitted to the server. */
+export interface SearchIndexSpec {
+    /** Index name; non-empty, without leading/trailing whitespace. */
+    name: string;
+    /** Index kind; required. */
+    type: SearchIndexType;
+    /** Index definition object, passed to the server as-is after basic validation. */
+    definition: Record<string, unknown>;
+}
+
+/** Normalized Search index information. */
+export interface SearchIndexInfo {
+    name: string;
+    status: SearchIndexStatus;
+    /** Whether the index can currently serve queries; `false` when absent. */
+    queryable: boolean;
+    id?: string;
+    /** Resolved index type; omitted only when `typeSource` is `'unknown'`. */
+    type?: SearchIndexType;
+    /**
+     * Where `type` came from: reported by the server, inferred from `latestDefinition`
+     * (self-managed mongot omits the top-level type field), or not determinable.
+     */
+    typeSource: SearchIndexTypeSource;
+    latestDefinition?: Record<string, unknown>;
+    latestDefinitionVersion?: { version: number; createdAt: Date; };
+    statusDetail?: Array<Record<string, unknown>>;
+    /** Raw driver document; `{}` when status is `DOES_NOT_EXIST`. */
+    raw: Record<string, unknown>;
+}
+
+export interface CreateSearchIndexOptions {
+    /** Behavior when an index with the same name exists. Default `'error'`. */
+    ifExists?: 'error' | 'skip' | 'update';
+}
+
+export interface CreateSearchIndexResult {
+    name: string;
+    action: 'created' | 'skipped' | 'updated';
+    /** `true` only when `action === 'created'`. */
+    created: boolean;
+}
+
+export interface ListSearchIndexesOptions {
+    /** Client-side filter on the resolved type; entries with `typeSource: 'unknown'` never match. */
+    type?: SearchIndexType;
+}
+
+export interface DropSearchIndexOptions {
+    /** Do not throw when the index does not exist. Default `false`. */
+    ignoreMissing?: boolean;
+}
+
+export interface WaitForSearchIndexOptions {
+    /** Target condition. Default `'queryable'`. */
+    until?: 'queryable' | 'ready' | 'dropped';
+    /** Overall timeout in ms (positive integer). Default `300000`. */
+    timeoutMs?: number;
+    /** Poll interval in ms (integer >= 100). Default `2000`. */
+    intervalMs?: number;
+    /** Abort signal; aborting rejects with `signal.reason`. */
+    signal?: AbortSignal;
+}
+
+/**
+ * Search index lifecycle methods, available on collection accessors and Models.
+ * Write methods are governed by `writePathPolicy` under the `management` category.
+ * Requires MongoDB Atlas, Community/Enterprise 8.2+ with mongot, or `mongodb/mongodb-atlas-local`.
+ * @since v3.4.0
+ */
+export interface SearchIndexManagement {
+    /** Creates one Search index. Default `ifExists: 'error'` throws `SEARCH_INDEX_EXISTS`. */
+    createSearchIndex(spec: SearchIndexSpec, options?: CreateSearchIndexOptions): Promise<CreateSearchIndexResult>;
+    /** Creates several Search indexes in one command (no `ifExists`). */
+    createSearchIndexes(specs: SearchIndexSpec[]): Promise<string[]>;
+    /** Lists Search indexes on the collection. */
+    listSearchIndexes(options?: ListSearchIndexesOptions): Promise<SearchIndexInfo[]>;
+    /** Returns one Search index; a missing index yields `status: 'DOES_NOT_EXIST'` instead of throwing. */
+    getSearchIndex(name: string): Promise<SearchIndexInfo>;
+    /** Replaces the index definition; the server rebuilds asynchronously. */
+    updateSearchIndex(name: string, definition: Record<string, unknown>): Promise<void>;
+    /** Drops a Search index; throws `SEARCH_INDEX_NOT_FOUND` unless `ignoreMissing`. */
+    dropSearchIndex(name: string, options?: DropSearchIndexOptions): Promise<void>;
+    /** Polls until the index is queryable, READY, or dropped. */
+    waitForSearchIndex(name: string, options?: WaitForSearchIndexOptions): Promise<SearchIndexInfo>;
+}

package/dist/types/search-index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Search index lifecycle types (Atlas Search / Vector Search).
+ * @since v3.4.0
+ */
+
+/** Search index kind: full-text `search` or `vectorSearch`. */
+export type SearchIndexType = 'search' | 'vectorSearch';
+
+/** Origin of `SearchIndexInfo.type`. */
+export type SearchIndexTypeSource = 'server' | 'inferred' | 'unknown';
+
+/** Server-reported Search index status (passed through unchanged). */
+export type SearchIndexStatus =
+    | 'PENDING'
+    | 'BUILDING'
+    | 'READY'
+    | 'FAILED'
+    | 'STALE'
+    | 'DELETING'
+    | 'DOES_NOT_EXIST';
+
+/** Search index definition submitted to the server. */
+export interface SearchIndexSpec {
+    /** Index name; non-empty, without leading/trailing whitespace. */
+    name: string;
+    /** Index kind; required. */
+    type: SearchIndexType;
+    /** Index definition object, passed to the server as-is after basic validation. */
+    definition: Record<string, unknown>;
+}
+
+/** Normalized Search index information. */
+export interface SearchIndexInfo {
+    name: string;
+    status: SearchIndexStatus;
+    /** Whether the index can currently serve queries; `false` when absent. */
+    queryable: boolean;
+    id?: string;
+    /** Resolved index type; omitted only when `typeSource` is `'unknown'`. */
+    type?: SearchIndexType;
+    /**
+     * Where `type` came from: reported by the server, inferred from `latestDefinition`
+     * (self-managed mongot omits the top-level type field), or not determinable.
+     */
+    typeSource: SearchIndexTypeSource;
+    latestDefinition?: Record<string, unknown>;
+    latestDefinitionVersion?: { version: number; createdAt: Date; };
+    statusDetail?: Array<Record<string, unknown>>;
+    /** Raw driver document; `{}` when status is `DOES_NOT_EXIST`. */
+    raw: Record<string, unknown>;
+}
+
+export interface CreateSearchIndexOptions {
+    /** Behavior when an index with the same name exists. Default `'error'`. */
+    ifExists?: 'error' | 'skip' | 'update';
+}
+
+export interface CreateSearchIndexResult {
+    name: string;
+    action: 'created' | 'skipped' | 'updated';
+    /** `true` only when `action === 'created'`. */
+    created: boolean;
+}
+
+export interface ListSearchIndexesOptions {
+    /** Client-side filter on the resolved type; entries with `typeSource: 'unknown'` never match. */
+    type?: SearchIndexType;
+}
+
+export interface DropSearchIndexOptions {
+    /** Do not throw when the index does not exist. Default `false`. */
+    ignoreMissing?: boolean;
+}
+
+export interface WaitForSearchIndexOptions {
+    /** Target condition. Default `'queryable'`. */
+    until?: 'queryable' | 'ready' | 'dropped';
+    /** Overall timeout in ms (positive integer). Default `300000`. */
+    timeoutMs?: number;
+    /** Poll interval in ms (integer >= 100). Default `2000`. */
+    intervalMs?: number;
+    /** Abort signal; aborting rejects with `signal.reason`. */
+    signal?: AbortSignal;
+}
+
+/**
+ * Search index lifecycle methods, available on collection accessors and Models.
+ * Write methods are governed by `writePathPolicy` under the `management` category.
+ * Requires MongoDB Atlas, Community/Enterprise 8.2+ with mongot, or `mongodb/mongodb-atlas-local`.
+ * @since v3.4.0
+ */
+export interface SearchIndexManagement {
+    /** Creates one Search index. Default `ifExists: 'error'` throws `SEARCH_INDEX_EXISTS`. */
+    createSearchIndex(spec: SearchIndexSpec, options?: CreateSearchIndexOptions): Promise<CreateSearchIndexResult>;
+    /** Creates several Search indexes in one command (no `ifExists`). */
+    createSearchIndexes(specs: SearchIndexSpec[]): Promise<string[]>;
+    /** Lists Search indexes on the collection. */
+    listSearchIndexes(options?: ListSearchIndexesOptions): Promise<SearchIndexInfo[]>;
+    /** Returns one Search index; a missing index yields `status: 'DOES_NOT_EXIST'` instead of throwing. */
+    getSearchIndex(name: string): Promise<SearchIndexInfo>;
+    /** Replaces the index definition; the server rebuilds asynchronously. */
+    updateSearchIndex(name: string, definition: Record<string, unknown>): Promise<void>;
+    /** Drops a Search index; throws `SEARCH_INDEX_NOT_FOUND` unless `ignoreMissing`. */
+    dropSearchIndex(name: string, options?: DropSearchIndexOptions): Promise<void>;
+    /** Polls until the index is queryable, READY, or dropped. */
+    waitForSearchIndex(name: string, options?: WaitForSearchIndexOptions): Promise<SearchIndexInfo>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "monsqlize",
-    "version": "3.3.4",
+    "version": "3.4.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.4.0.md",
         "changelogs/v3.3.3.md",
         "changelogs/v3.3.4.md",
         "changelogs/v3.3.2.md",
@@ -121,6 +122,7 @@
         "test:compatibility": "npm run build && npm run build:tests && node --test .generated/test-dist/test/compatibility/exports/exports.test.js .generated/test-dist/test/compatibility/matrix.test.js",
         "probe:server-matrix": "node scripts/validation/probe-memory-server-matrix.cjs",
         "test:server-matrix": "node scripts/validation/run-memory-server-matrix.cjs",
+        "test:search-index:real": "npm run build && node scripts/validation/run-search-index-real-env.cjs",
         "test:real-env:private": "node scripts/validation/run-private-real-env-checks.cjs",
         "test:examples": "npm run build && tsc -p tsconfig.examples.json && node scripts/run-examples.cjs",
         "test:performance": "npm run build && npm run build:tests && node .generated/test-dist/test/performance/baselines/function-cache.benchmark.js",
@@ -134,7 +136,7 @@
         "test:coverage": "node scripts/run-coverage.cjs",
         "test:audit": "npm audit --omit=dev --registry=https://registry.npmjs.org/",
         "test": "npm run build && npm run build:tests && node test/run-tests.cjs",
-        "type-check": "npm run build && tsc -p tsconfig.json --noEmit && tsd --files test/types/root-import.test-d.ts --files test/types/cache-usage.test-d.ts --files test/types/model-usage.test-d.ts --files test/types/pool-usage.test-d.ts --files test/types/sync-usage.test-d.ts --files test/types/slow-query-log-usage.test-d.ts --files test/types/saga-usage.test-d.ts --files test/types/data-tasks-usage.test-d.ts",
+        "type-check": "npm run build && tsc -p tsconfig.json --noEmit && tsd --files test/types/root-import.test-d.ts --files test/types/cache-usage.test-d.ts --files test/types/model-usage.test-d.ts --files test/types/pool-usage.test-d.ts --files test/types/sync-usage.test-d.ts --files test/types/slow-query-log-usage.test-d.ts --files test/types/saga-usage.test-d.ts --files test/types/data-tasks-usage.test-d.ts --files test/types/search-index-usage.test-d.ts",
         "check:test-language": "node scripts/check-test-language.cjs",
         "check:docs-examples": "node scripts/validation/check-doc-example-matrix.cjs",
         "check:release-candidate": "node scripts/check-release-candidate.cjs",