monsqlize 3.3.4 → 3.5.0

package/dist/types/base.d.mts

@@ -37,6 +37,18 @@ 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',
+    GRIDFS_FILE_NOT_FOUND = 'GRIDFS_FILE_NOT_FOUND',
+    GRIDFS_FILE_EXISTS = 'GRIDFS_FILE_EXISTS',
+    GRIDFS_INTEGRITY_MISMATCH = 'GRIDFS_INTEGRITY_MISMATCH',
+    GRIDFS_UPLOAD_INCOMPLETE = 'GRIDFS_UPLOAD_INCOMPLETE',
+    GRIDFS_RESUME_MISMATCH = 'GRIDFS_RESUME_MISMATCH',
+    GRIDFS_RANGE_INVALID = 'GRIDFS_RANGE_INVALID',
     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,18 @@ 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',
+    GRIDFS_FILE_NOT_FOUND = 'GRIDFS_FILE_NOT_FOUND',
+    GRIDFS_FILE_EXISTS = 'GRIDFS_FILE_EXISTS',
+    GRIDFS_INTEGRITY_MISMATCH = 'GRIDFS_INTEGRITY_MISMATCH',
+    GRIDFS_UPLOAD_INCOMPLETE = 'GRIDFS_UPLOAD_INCOMPLETE',
+    GRIDFS_RESUME_MISMATCH = 'GRIDFS_RESUME_MISMATCH',
+    GRIDFS_RANGE_INVALID = 'GRIDFS_RANGE_INVALID',
     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/gridfs.d.mts

@@ -0,0 +1,146 @@
+/**
+ * GridFS bucket types.
+ * @since v3.5.0
+ */
+
+import type { ObjectId } from 'mongodb';
+import type { Readable, Writable } from 'node:stream';
+
+/** Normalized GridFS file metadata. Driver-private state is omitted. */
+export interface GridFSFileInfo {
+    /** `files._id`. */
+    id: ObjectId;
+    filename: string;
+    /** Byte length. Always >= 0. */
+    length: number;
+    /** Chunk size in bytes. Always > 0. */
+    chunkSize: number;
+    uploadDate: Date;
+    /** Present when the file was stored with a content type. */
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+}
+
+/** Options for `msq.gridfs()`. `db` and `pool` select the native database. */
+export interface GridFSBucketOpenOptions {
+    /** Defaults to the runtime database. */
+    db?: string;
+    /** Defaults to the runtime connection. A named pool uses that pool's client. */
+    pool?: string;
+    /** Defaults to 261120 (255 KiB). Must be a positive integer. */
+    chunkSizeBytes?: number;
+}
+
+/** Options for `model.gridfs()`. Pool and database come from the Model. */
+export interface GridFSModelBucketOpenOptions {
+    /** Defaults to 261120 (255 KiB). Must be a positive integer. */
+    chunkSizeBytes?: number;
+}
+
+/** What to do when uploaded content matches an existing visible file. Default `error`. */
+export type GridFSIfExists = 'error' | 'skip' | 'duplicate';
+
+export interface GridFSUploadOptions {
+    /** Custom `files._id`. An existing id rejects with `GRIDFS_FILE_EXISTS`. */
+    id?: ObjectId;
+    metadata?: Record<string, unknown>;
+    contentType?: string;
+    /**
+     * Lowercase 64-character sha256 hex. Stored as `metadata.sha256` and used as the idempotency key.
+     * When the bytes do not match, upload rejects with `GRIDFS_INTEGRITY_MISMATCH` before the file is visible.
+     */
+    sha256?: string;
+    /** Default `error`. */
+    ifExists?: GridFSIfExists;
+    /** Overrides the bucket chunk size for this file only. */
+    chunkSizeBytes?: number;
+}
+
+/** `uploadStream` writes `sha256` into metadata and does not support `ifExists`. */
+export interface GridFSUploadStreamOptions extends Omit<GridFSUploadOptions, 'ifExists'> {}
+
+/**
+ * Download target. `revision` follows the driver: `0` is the oldest file with that name,
+ * `-1` (default) is the newest.
+ */
+export type GridFSIdOrName = ObjectId | { filename: string; revision?: number };
+
+/**
+ * Inclusive `start` and exclusive `end`, matching `GridFSBucketReadStreamOptions`.
+ * Omitted `start` means 0. Omitted `end` means the file length.
+ */
+export interface GridFSDownloadRange {
+    start?: number;
+    end?: number;
+}
+
+export interface GridFSFindFilesFilter {
+    filename?: string;
+    [key: string]: unknown;
+}
+
+export interface GridFSFindFilesOptions {
+    /** Positive integer. Omit for no limit. */
+    limit?: number;
+    /** Non-negative integer. Default 0. */
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+}
+
+export interface GridFSDeleteOptions {
+    /** Default false. When true, a missing file resolves instead of `GRIDFS_FILE_NOT_FOUND`. */
+    ignoreMissing?: boolean;
+}
+
+export interface BeginResumableUploadOptions {
+    /** Final byte length. Positive integer. */
+    length: number;
+    /** Final lowercase sha256 hex. Checked by `finalizeResumableUpload`. */
+    sha256: string;
+    chunkSizeBytes?: number;
+    metadata?: Record<string, unknown>;
+    contentType?: string;
+    /** Also the id returned as `uploadId` and the final `files._id`. */
+    id?: ObjectId;
+}
+
+export interface BeginResumableUploadResult {
+    uploadId: ObjectId;
+    /** Next chunk index to write. A new session returns 0. */
+    nextChunk: number;
+    chunkSizeBytes: number;
+}
+
+export interface AppendChunksResult {
+    nextChunk: number;
+    bytesAccepted: number;
+}
+
+/**
+ * Bucket returned by `msq.gridfs()` and `model.gridfs()`.
+ * Reads do not consult `writePathPolicy`. Writes use category `gridfs`.
+ * `drop` uses category `management`.
+ */
+export interface MonSQLizeGridFSBucket {
+    readonly bucketName: string;
+    readonly dbName: string;
+    readonly chunkSizeBytes: number;
+    upload(filename: string, data: Buffer | Uint8Array | Readable, opts?: GridFSUploadOptions): Promise<GridFSFileInfo>;
+    uploadStream(filename: string, opts?: GridFSUploadStreamOptions): Writable & { id: ObjectId; done: Promise<GridFSFileInfo> };
+    download(idOrName: GridFSIdOrName): Promise<Buffer>;
+    downloadStream(idOrName: GridFSIdOrName, range?: GridFSDownloadRange): Readable;
+    /** Returns null when the id is absent. */
+    getFile(id: ObjectId): Promise<GridFSFileInfo | null>;
+    findFiles(filter?: GridFSFindFilesFilter, opts?: GridFSFindFilesOptions): Promise<GridFSFileInfo[]>;
+    delete(id: ObjectId, opts?: GridFSDeleteOptions): Promise<void>;
+    rename(id: ObjectId, filename: string): Promise<void>;
+    /** Drops `<bucket>.files`, `<bucket>.chunks`, and `<bucket>.uploads` when present. */
+    drop(): Promise<void>;
+    beginResumableUpload(filename: string, opts: BeginResumableUploadOptions): Promise<BeginResumableUploadResult>;
+    appendChunks(uploadId: ObjectId, fromChunk: number, data: Buffer | Uint8Array | Readable): Promise<AppendChunksResult>;
+    finalizeResumableUpload(uploadId: ObjectId): Promise<GridFSFileInfo>;
+    /** Deletes the session and any chunks. A missing or already aborted session resolves. */
+    abortResumableUpload(uploadId: ObjectId): Promise<void>;
+    /** Creates the standard files/chunks indexes, `metadata.sha256`, and the uploads TTL index. */
+    ensureIndexes(): Promise<void>;
+}

package/dist/types/gridfs.d.ts

@@ -0,0 +1,146 @@
+/**
+ * GridFS bucket types.
+ * @since v3.5.0
+ */
+
+import type { ObjectId } from 'mongodb';
+import type { Readable, Writable } from 'node:stream';
+
+/** Normalized GridFS file metadata. Driver-private state is omitted. */
+export interface GridFSFileInfo {
+    /** `files._id`. */
+    id: ObjectId;
+    filename: string;
+    /** Byte length. Always >= 0. */
+    length: number;
+    /** Chunk size in bytes. Always > 0. */
+    chunkSize: number;
+    uploadDate: Date;
+    /** Present when the file was stored with a content type. */
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+}
+
+/** Options for `msq.gridfs()`. `db` and `pool` select the native database. */
+export interface GridFSBucketOpenOptions {
+    /** Defaults to the runtime database. */
+    db?: string;
+    /** Defaults to the runtime connection. A named pool uses that pool's client. */
+    pool?: string;
+    /** Defaults to 261120 (255 KiB). Must be a positive integer. */
+    chunkSizeBytes?: number;
+}
+
+/** Options for `model.gridfs()`. Pool and database come from the Model. */
+export interface GridFSModelBucketOpenOptions {
+    /** Defaults to 261120 (255 KiB). Must be a positive integer. */
+    chunkSizeBytes?: number;
+}
+
+/** What to do when uploaded content matches an existing visible file. Default `error`. */
+export type GridFSIfExists = 'error' | 'skip' | 'duplicate';
+
+export interface GridFSUploadOptions {
+    /** Custom `files._id`. An existing id rejects with `GRIDFS_FILE_EXISTS`. */
+    id?: ObjectId;
+    metadata?: Record<string, unknown>;
+    contentType?: string;
+    /**
+     * Lowercase 64-character sha256 hex. Stored as `metadata.sha256` and used as the idempotency key.
+     * When the bytes do not match, upload rejects with `GRIDFS_INTEGRITY_MISMATCH` before the file is visible.
+     */
+    sha256?: string;
+    /** Default `error`. */
+    ifExists?: GridFSIfExists;
+    /** Overrides the bucket chunk size for this file only. */
+    chunkSizeBytes?: number;
+}
+
+/** `uploadStream` writes `sha256` into metadata and does not support `ifExists`. */
+export interface GridFSUploadStreamOptions extends Omit<GridFSUploadOptions, 'ifExists'> {}
+
+/**
+ * Download target. `revision` follows the driver: `0` is the oldest file with that name,
+ * `-1` (default) is the newest.
+ */
+export type GridFSIdOrName = ObjectId | { filename: string; revision?: number };
+
+/**
+ * Inclusive `start` and exclusive `end`, matching `GridFSBucketReadStreamOptions`.
+ * Omitted `start` means 0. Omitted `end` means the file length.
+ */
+export interface GridFSDownloadRange {
+    start?: number;
+    end?: number;
+}
+
+export interface GridFSFindFilesFilter {
+    filename?: string;
+    [key: string]: unknown;
+}
+
+export interface GridFSFindFilesOptions {
+    /** Positive integer. Omit for no limit. */
+    limit?: number;
+    /** Non-negative integer. Default 0. */
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+}
+
+export interface GridFSDeleteOptions {
+    /** Default false. When true, a missing file resolves instead of `GRIDFS_FILE_NOT_FOUND`. */
+    ignoreMissing?: boolean;
+}
+
+export interface BeginResumableUploadOptions {
+    /** Final byte length. Positive integer. */
+    length: number;
+    /** Final lowercase sha256 hex. Checked by `finalizeResumableUpload`. */
+    sha256: string;
+    chunkSizeBytes?: number;
+    metadata?: Record<string, unknown>;
+    contentType?: string;
+    /** Also the id returned as `uploadId` and the final `files._id`. */
+    id?: ObjectId;
+}
+
+export interface BeginResumableUploadResult {
+    uploadId: ObjectId;
+    /** Next chunk index to write. A new session returns 0. */
+    nextChunk: number;
+    chunkSizeBytes: number;
+}
+
+export interface AppendChunksResult {
+    nextChunk: number;
+    bytesAccepted: number;
+}
+
+/**
+ * Bucket returned by `msq.gridfs()` and `model.gridfs()`.
+ * Reads do not consult `writePathPolicy`. Writes use category `gridfs`.
+ * `drop` uses category `management`.
+ */
+export interface MonSQLizeGridFSBucket {
+    readonly bucketName: string;
+    readonly dbName: string;
+    readonly chunkSizeBytes: number;
+    upload(filename: string, data: Buffer | Uint8Array | Readable, opts?: GridFSUploadOptions): Promise<GridFSFileInfo>;
+    uploadStream(filename: string, opts?: GridFSUploadStreamOptions): Writable & { id: ObjectId; done: Promise<GridFSFileInfo> };
+    download(idOrName: GridFSIdOrName): Promise<Buffer>;
+    downloadStream(idOrName: GridFSIdOrName, range?: GridFSDownloadRange): Readable;
+    /** Returns null when the id is absent. */
+    getFile(id: ObjectId): Promise<GridFSFileInfo | null>;
+    findFiles(filter?: GridFSFindFilesFilter, opts?: GridFSFindFilesOptions): Promise<GridFSFileInfo[]>;
+    delete(id: ObjectId, opts?: GridFSDeleteOptions): Promise<void>;
+    rename(id: ObjectId, filename: string): Promise<void>;
+    /** Drops `<bucket>.files`, `<bucket>.chunks`, and `<bucket>.uploads` when present. */
+    drop(): Promise<void>;
+    beginResumableUpload(filename: string, opts: BeginResumableUploadOptions): Promise<BeginResumableUploadResult>;
+    appendChunks(uploadId: ObjectId, fromChunk: number, data: Buffer | Uint8Array | Readable): Promise<AppendChunksResult>;
+    finalizeResumableUpload(uploadId: ObjectId): Promise<GridFSFileInfo>;
+    /** Deletes the session and any chunks. A missing or already aborted session resolves. */
+    abortResumableUpload(uploadId: ObjectId): Promise<void>;
+    /** Creates the standard files/chunks indexes, `metadata.sha256`, and the uploads TTL index. */
+    ensureIndexes(): Promise<void>;
+}

package/dist/types/index.d.mts

@@ -2,12 +2,14 @@ export * from './base.mjs';
 export * from './collection.mjs';
 export * from './data-tasks.mjs';
 export * from './expression.mjs';
+export * from './gridfs.mjs';
 export * from './lock.mjs';
 export * from './model.mjs';
 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

@@ -2,12 +2,14 @@ export * from './base';
 export * from './collection';
 export * from './data-tasks';
 export * from './expression';
+export * from './gridfs';
 export * from './lock';
 export * from './model';
 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;
@@ -706,6 +706,8 @@ export interface ModelInstance<TDocument = any> {
      * Does not drop, rename, or rebuild conflicting indexes.
      */
     ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
+    /** Opens a GridFS bucket bound to this Model's pool and database. Default bucket name is `fs`. @since v3.5.0 */
+    gridfs(bucketName?: string, opts?: import('./gridfs.mjs').GridFSModelBucketOpenOptions): import('./gridfs.mjs').MonSQLizeGridFSBucket;
     /**
      * Drops the specified index by name.
      * @param name Index name.

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;
@@ -706,6 +706,8 @@ export interface ModelInstance<TDocument = any> {
      * Does not drop, rename, or rebuild conflicting indexes.
      */
     ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
+    /** Opens a GridFS bucket bound to this Model's pool and database. Default bucket name is `fs`. @since v3.5.0 */
+    gridfs(bucketName?: string, opts?: import('./gridfs').GridFSModelBucketOpenOptions): import('./gridfs').MonSQLizeGridFSBucket;
     /**
      * Drops the specified index by name.
      * @param name Index name.

package/dist/types/monsqlize.d.mts

@@ -37,6 +37,7 @@ export interface SSHConfig {
 }
 
 import type { Collection, CursorValueNormalizer, CursorValueType, DbAccessor, HealthView } from './collection.mjs';
+import type { GridFSBucketOpenOptions, MonSQLizeGridFSBucket } from './gridfs.mjs';
 import type { DataTaskJobError } from './data-tasks.mjs';
 import type { Lock, LockOptions, LockStats } from './lock.mjs';
 import type { ModelAutoIndexOptions, ModelDescriptor, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model.mjs';
@@ -92,6 +93,12 @@ export type WritePathPolicyRawMode = 'inherit' | 'allow' | 'block';
 /** Controls whether collection/database management writes are available under a write path policy. */
 export type WritePathPolicyManagementMode = 'inherit' | 'allow' | 'block';
 
+/**
+ * Controls GridFS writes. `inherit` follows `mode`, except `model-only` still blocks
+ * GridFS writes from every source until the rule is `allow`.
+ */
+export type WritePathPolicyGridfsMode = 'inherit' | 'allow' | 'block';
+
 /** Controls violation handling; `warn` logs and allows for migration observation. */
 export type WritePathPolicyViolationAction = 'throw' | 'warn';
 
@@ -103,6 +110,11 @@ export interface WritePathPolicyRule {
     raw?: WritePathPolicyRawMode;
     /** Management write policy. `inherit` allows model management and blocks external management in `model-only`. */
     management?: WritePathPolicyManagementMode;
+    /**
+     * GridFS write policy. Default: `inherit`.
+     * `inherit` allows GridFS writes in `allow-both` and blocks them in `model-only` even when `source` is `model`.
+     */
+    gridfs?: WritePathPolicyGridfsMode;
     /** Violation action. Default: `throw`. */
     onViolation?: WritePathPolicyViolationAction;
 }
@@ -324,6 +336,12 @@ export interface MonSQLizeInstance {
      * @param name Target database name; omit to use the default database.
      */
     db(name?: string): DbAccessor;
+    /**
+     * Open a GridFS bucket. The default bucket name is `fs`.
+     * Call after `connect()`; otherwise this throws `NOT_CONNECTED`.
+     * @since v3.5.0
+     */
+    gridfs(bucketName?: string, opts?: GridFSBucketOpenOptions): MonSQLizeGridFSBucket;
     /**
      * Switch to the given database and return its `collection` and `model` accessors.
      * @param name Target database name.
@@ -546,6 +564,8 @@ export default class MonSQLize implements MonSQLizeInstance {
     collection<TSchema = any>(name: string): Collection<TSchema>;
     collection(name: string): Collection<any>;
     db(name?: string): DbAccessor;
+    /** @since v3.5.0 */
+    gridfs(bucketName?: string, opts?: GridFSBucketOpenOptions): MonSQLizeGridFSBucket;
     use(name: string): {
         collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
         model: ModelBindingAccessor;

package/dist/types/monsqlize.d.ts

@@ -37,6 +37,7 @@ export interface SSHConfig {
 }
 
 import type { Collection, CursorValueNormalizer, CursorValueType, DbAccessor, HealthView } from './collection';
+import type { GridFSBucketOpenOptions, MonSQLizeGridFSBucket } from './gridfs';
 import type { DataTaskJobError } from './data-tasks';
 import type { Lock, LockOptions, LockStats } from './lock';
 import type { ModelAutoIndexOptions, ModelDescriptor, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model';
@@ -92,6 +93,12 @@ export type WritePathPolicyRawMode = 'inherit' | 'allow' | 'block';
 /** Controls whether collection/database management writes are available under a write path policy. */
 export type WritePathPolicyManagementMode = 'inherit' | 'allow' | 'block';
 
+/**
+ * Controls GridFS writes. `inherit` follows `mode`, except `model-only` still blocks
+ * GridFS writes from every source until the rule is `allow`.
+ */
+export type WritePathPolicyGridfsMode = 'inherit' | 'allow' | 'block';
+
 /** Controls violation handling; `warn` logs and allows for migration observation. */
 export type WritePathPolicyViolationAction = 'throw' | 'warn';
 
@@ -103,6 +110,11 @@ export interface WritePathPolicyRule {
     raw?: WritePathPolicyRawMode;
     /** Management write policy. `inherit` allows model management and blocks external management in `model-only`. */
     management?: WritePathPolicyManagementMode;
+    /**
+     * GridFS write policy. Default: `inherit`.
+     * `inherit` allows GridFS writes in `allow-both` and blocks them in `model-only` even when `source` is `model`.
+     */
+    gridfs?: WritePathPolicyGridfsMode;
     /** Violation action. Default: `throw`. */
     onViolation?: WritePathPolicyViolationAction;
 }
@@ -324,6 +336,12 @@ export interface MonSQLizeInstance {
      * @param name Target database name; omit to use the default database.
      */
     db(name?: string): DbAccessor;
+    /**
+     * Open a GridFS bucket. The default bucket name is `fs`.
+     * Call after `connect()`; otherwise this throws `NOT_CONNECTED`.
+     * @since v3.5.0
+     */
+    gridfs(bucketName?: string, opts?: GridFSBucketOpenOptions): MonSQLizeGridFSBucket;
     /**
      * Switch to the given database and return its `collection` and `model` accessors.
      * @param name Target database name.
@@ -546,6 +564,8 @@ export default class MonSQLize implements MonSQLizeInstance {
     collection<TSchema = any>(name: string): Collection<TSchema>;
     collection(name: string): Collection<any>;
     db(name?: string): DbAccessor;
+    /** @since v3.5.0 */
+    gridfs(bucketName?: string, opts?: GridFSBucketOpenOptions): MonSQLizeGridFSBucket;
     use(name: string): {
         collection: <TSchema = any>(collectionName: string) => Collection<TSchema>;
         model: ModelBindingAccessor;

package/dist/types/runtime.d.mts

@@ -343,8 +343,17 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
     listIndexes(): Promise<Record<string, unknown>[]>;
     ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
+    /** @since v3.5.0 */
+    gridfs(bucketName?: string, opts?: import('./gridfs.mjs').GridFSModelBucketOpenOptions): import('./gridfs.mjs').MonSQLizeGridFSBucket;
     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

@@ -343,8 +343,17 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
     listIndexes(): Promise<Record<string, unknown>[]>;
     ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
+    /** @since v3.5.0 */
+    gridfs(bucketName?: string, opts?: import('./gridfs').GridFSModelBucketOpenOptions): import('./gridfs').MonSQLizeGridFSBucket;
     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>;