bun-gridfs-storage 1.0.0

package/dist/storage.d.ts

@@ -0,0 +1,91 @@
+/**
+ * BunGridFSStorage - Multer storage engine for GridFS
+ * Works with both Bun and Node.js
+ *
+ * @module bun-gridfs-storage/storage
+ * @author Aissam Irhir <aissamirhir@gmail.com>
+ */
+import { EventEmitter } from "events";
+import type { Request } from "express";
+import { GridFSBucket } from "mongodb";
+import type { BunGridFSStorageOptions, GridFSFile, MulterFile } from "./types";
+/**
+ * Custom Bun-compatible GridFS Storage Engine for Multer
+ *
+ * @example
+ * ```typescript
+ * import { BunGridFSStorage } from 'bun-gridfs-storage';
+ * import multer from 'multer';
+ * import mongoose from 'mongoose';
+ *
+ * const storage = new BunGridFSStorage({
+ *   db: mongoose.connection.db,
+ *   file: (req, file) => ({
+ *     filename: `${Date.now()}-${file.originalname}`,
+ *     bucketName: 'uploads',
+ *   }),
+ * });
+ *
+ * const upload = multer({ storage });
+ * ```
+ */
+export declare class BunGridFSStorage extends EventEmitter {
+    private dbPromise;
+    private db;
+    private bucket;
+    private fileConfig;
+    private connected;
+    private defaultBucketName;
+    private defaultChunkSize;
+    constructor(options: BunGridFSStorageOptions);
+    /**
+     * Initialize database connection and GridFS bucket
+     * @private
+     */
+    private initConnection;
+    /**
+     * Multer storage engine _handleFile method
+     * Called when a file needs to be stored
+     *
+     * @param req - Express request object
+     * @param file - Multer file object
+     * @param cb - Callback to invoke when done
+     */
+    _handleFile(req: Request, file: MulterFile, cb: (error?: Error | null, info?: Partial<GridFSFile>) => void): Promise<void>;
+    /**
+     * Multer storage engine _removeFile method
+     * Called when a file needs to be removed
+     *
+     * @param _req - Express request object (unused)
+     * @param file - GridFS file object to remove
+     * @param cb - Callback to invoke when done
+     */
+    _removeFile(_req: Request, file: GridFSFile, cb: (error?: Error | null) => void): Promise<void>;
+    /**
+     * Wait for the storage to be connected
+     * @private
+     * @param maxWaitMs - Maximum time to wait in milliseconds (default: 10000)
+     */
+    private waitForConnection;
+    /**
+     * Check if storage is ready
+     * @returns True if connected and bucket is initialized
+     */
+    isReady(): boolean;
+    /**
+     * Get the GridFS bucket instance
+     * @returns GridFSBucket instance or null if not initialized
+     */
+    getBucket(): GridFSBucket | null;
+    /**
+     * Set default bucket name for new instances
+     * @param name - Bucket name
+     */
+    setDefaultBucketName(name: string): void;
+    /**
+     * Set default chunk size for new instances
+     * @param size - Chunk size in bytes
+     */
+    setDefaultChunkSize(size: number): void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,YAAY,EAAY,MAAM,SAAS,CAAC;AAEjD,OAAO,KAAK,EACV,uBAAuB,EAGvB,UAAU,EACV,UAAU,EACX,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,gBAAgB,CAAsB;gBAElC,OAAO,EAAE,uBAAuB;IAsB5C;;;OAGG;YACW,cAAc;IA6B5B;;;;;;;OAOG;IACG,WAAW,CACf,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,GAC7D,OAAO,CAAC,IAAI,CAAC;IAkEhB;;;;;;;OAOG;IACG,WAAW,CACf,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GACjC,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;OAIG;YACW,iBAAiB;IAsB/B;;;OAGG;IACH,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACH,SAAS,IAAI,YAAY,GAAG,IAAI;IAIhC;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxC;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAGxC"}

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * TypeScript type definitions for bun-gridfs-storage
+ *
+ * @module bun-gridfs-storage/types
+ * @author Aissam Irhir <aissamirhir@gmail.com>
+ */
+import type { Request } from "express";
+import type { ObjectId } from "mongodb";
+/**
+ * GridFS file information returned after upload
+ */
+export interface GridFSFile {
+    /** MongoDB ObjectId of the uploaded file */
+    id: ObjectId;
+    /** Filename used in GridFS */
+    filename: string;
+    /** Original filename from the upload */
+    originalname: string;
+    /** File encoding (e.g., "7bit", "base64") */
+    encoding: string;
+    /** MIME type of the file */
+    mimetype: string;
+    /** File size in bytes */
+    size: number;
+    /** GridFS bucket name where file is stored */
+    bucketName: string;
+    /** Custom metadata stored with the file */
+    metadata?: Record<string, any>;
+    /** Content type of the file */
+    contentType?: string;
+    /** Date when the file was uploaded */
+    uploadDate?: Date;
+}
+/**
+ * Configuration for storing a file in GridFS
+ */
+export interface FileConfig {
+    /** Filename to use in GridFS */
+    filename: string;
+    /** GridFS bucket name */
+    bucketName: string;
+    /** Chunk size in bytes (default: 255KB) */
+    chunkSize?: number;
+    /** Custom metadata to store with the file */
+    metadata?: Record<string, any>;
+    /** Content type of the file */
+    contentType?: string;
+}
+/**
+ * Multer file type
+ */
+export interface MulterFile {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    stream: NodeJS.ReadableStream;
+    destination: string;
+    filename: string;
+    path: string;
+    buffer: Buffer;
+}
+/**
+ * Callback function to configure file storage
+ * Can return a promise or the configuration directly
+ */
+export type FileConfigCallback = (req: Request, file: MulterFile) => Promise<FileConfig> | FileConfig;
+/**
+ * Options for initializing BunGridFSStorage
+ */
+export interface BunGridFSStorageOptions {
+    /**
+     * MongoDB database connection
+     * Can be a Promise (for deferred connection) or direct Db instance
+     */
+    db: Promise<import("mongodb").Db> | import("mongodb").Db;
+    /**
+     * Optional callback to configure file storage
+     * If not provided, uses original filename and default bucket
+     */
+    file?: FileConfigCallback;
+}
+/**
+ * Events emitted by BunGridFSStorage
+ */
+export interface BunGridFSStorageEvents {
+    /** Emitted when database connection is established */
+    connection: (db: import("mongodb").Db) => void;
+    /** Emitted when a file is successfully stored */
+    file: (file: GridFSFile) => void;
+    /** Emitted when a stream error occurs */
+    streamError: (error: Error, fileConfig: Partial<FileConfig>) => void;
+    /** Emitted when database connection fails */
+    connectionFailed: (error: Error) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,EAAE,EAAE,QAAQ,CAAC;IAEb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IAEjB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IAEb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE/B,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,sCAAsC;IACtC,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE/B,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,UAAU,KACb,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,EAAE,EAAE,OAAO,CAAC,OAAO,SAAS,EAAE,EAAE,CAAC,GAAG,OAAO,SAAS,EAAE,EAAE,CAAC;IAEzD;;;OAGG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,UAAU,EAAE,CAAC,EAAE,EAAE,OAAO,SAAS,EAAE,EAAE,KAAK,IAAI,CAAC;IAE/C,iDAAiD;IACjD,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IAEjC,yCAAyC;IACzC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAErE,6CAA6C;IAC7C,gBAAgB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC1C"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "bun-gridfs-storage",
+  "version": "1.0.0",
+  "description": "A Multer storage engine for GridFS that works with both Bun and Node.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:cjs && bun run build:esm && bun run build:types",
+    "build:cjs": "bun build ./src/index.ts --outfile ./dist/index.js --target node --format cjs",
+    "build:esm": "bun build ./src/index.ts --outfile ./dist/index.mjs --target node --format esm",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "prepublishOnly": "bun run build",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "multer",
+    "gridfs",
+    "mongodb",
+    "storage",
+    "bun",
+    "nodejs",
+    "file-upload",
+    "mongoose"
+  ],
+  "author": "Aissam Irhir <aissamirhir@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aissamirhir/bun-gridfs-storage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aissamirhir/bun-gridfs-storage/issues"
+  },
+  "homepage": "https://github.com/aissamirhir/bun-gridfs-storage#readme",
+  "peerDependencies": {
+    "mongodb": "^6.0.0",
+    "mongoose": "^8.0.0",
+    "multer": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/multer": "^1.4.12",
+    "bun-types": "latest",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * bun-gridfs-storage - A Multer storage engine for GridFS
+ * Works with both Bun and Node.js
+ *
+ * @module bun-gridfs-storage
+ * @author Aissam Irhir <aissamirhir@gmail.com>
+ * @license MIT
+ */
+
+export { BunGridFSStorage } from "./storage";
+export type {
+  GridFSFile,
+  FileConfig,
+  FileConfigCallback,
+  BunGridFSStorageOptions,
+  BunGridFSStorageEvents,
+  MulterFile,
+} from "./types";

package/src/storage.ts

@@ -0,0 +1,270 @@
+/**
+ * BunGridFSStorage - Multer storage engine for GridFS
+ * Works with both Bun and Node.js
+ *
+ * @module bun-gridfs-storage/storage
+ * @author Aissam Irhir <aissamirhir@gmail.com>
+ */
+
+import { EventEmitter } from "events";
+import type { Request } from "express";
+import { GridFSBucket, ObjectId } from "mongodb";
+import type { Db } from "mongodb";
+import type {
+  BunGridFSStorageOptions,
+  FileConfig,
+  FileConfigCallback,
+  GridFSFile,
+  MulterFile,
+} from "./types";
+
+/**
+ * Custom Bun-compatible GridFS Storage Engine for Multer
+ *
+ * @example
+ * ```typescript
+ * import { BunGridFSStorage } from 'bun-gridfs-storage';
+ * import multer from 'multer';
+ * import mongoose from 'mongoose';
+ *
+ * const storage = new BunGridFSStorage({
+ *   db: mongoose.connection.db,
+ *   file: (req, file) => ({
+ *     filename: `${Date.now()}-${file.originalname}`,
+ *     bucketName: 'uploads',
+ *   }),
+ * });
+ *
+ * const upload = multer({ storage });
+ * ```
+ */
+export class BunGridFSStorage extends EventEmitter {
+  private dbPromise: Promise<Db>;
+  private db: Db | null = null;
+  private bucket: GridFSBucket | null = null;
+  private fileConfig: FileConfigCallback;
+  private connected: boolean = false;
+  private defaultBucketName: string = "fs";
+  private defaultChunkSize: number = 255 * 1024; // 255KB
+
+  constructor(options: BunGridFSStorageOptions) {
+    super();
+
+    // Handle db as promise or direct value
+    if (options.db instanceof Promise) {
+      this.dbPromise = options.db;
+    } else {
+      this.dbPromise = Promise.resolve(options.db);
+    }
+
+    // Default file config function
+    this.fileConfig =
+      options.file ||
+      ((_req: Request, file: MulterFile): FileConfig => ({
+        filename: file.originalname,
+        bucketName: this.defaultBucketName,
+      }));
+
+    // Initialize connection
+    this.initConnection();
+  }
+
+  /**
+   * Initialize database connection and GridFS bucket
+   * @private
+   */
+  private async initConnection(): Promise<void> {
+    try {
+      this.db = await this.dbPromise;
+
+      if (!this.db) {
+        throw new Error("Database connection is null");
+      }
+
+      // Only create bucket if db.collection method exists
+      if (typeof this.db.collection === "function") {
+        this.bucket = new GridFSBucket(this.db, {
+          bucketName: this.defaultBucketName,
+          chunkSizeBytes: this.defaultChunkSize,
+        });
+
+        this.connected = true;
+        this.emit("connection", this.db);
+      } else {
+        throw new Error("Invalid database instance: missing collection method");
+      }
+    } catch (error) {
+      this.emit("connectionFailed", error);
+      // Only log in non-test environments
+      if (process.env.NODE_ENV !== "test") {
+        console.error("GridFS storage connection failed:", error);
+      }
+    }
+  }
+
+  /**
+   * Multer storage engine _handleFile method
+   * Called when a file needs to be stored
+   *
+   * @param req - Express request object
+   * @param file - Multer file object
+   * @param cb - Callback to invoke when done
+   */
+  async _handleFile(
+    req: Request,
+    file: MulterFile,
+    cb: (error?: Error | null, info?: Partial<GridFSFile>) => void
+  ): Promise<void> {
+    try {
+      // Wait for connection if not ready
+      if (!this.connected || !this.bucket) {
+        await this.waitForConnection();
+      }
+
+      if (!this.bucket) {
+        throw new Error("GridFS bucket not initialized");
+      }
+
+      // Get file configuration
+      const fileConfig = await this.fileConfig(req, file);
+
+      // Create upload stream
+      const uploadStream = this.bucket.openUploadStream(fileConfig.filename, {
+        chunkSizeBytes: fileConfig.chunkSize || this.defaultChunkSize,
+        metadata: fileConfig.metadata,
+        contentType: fileConfig.contentType || file.mimetype,
+      });
+
+      // Track uploaded size
+      let size = 0;
+
+      // Handle stream events
+      file.stream.on("data", (chunk: Buffer) => {
+        size += chunk.length;
+      });
+
+      file.stream.on("error", (error: Error) => {
+        this.emit("streamError", error, fileConfig);
+        uploadStream.destroy(error);
+        cb(error);
+      });
+
+      uploadStream.on("error", (error: Error) => {
+        this.emit("streamError", error, fileConfig);
+        cb(error);
+      });
+
+      uploadStream.on("finish", () => {
+        const storedFile: GridFSFile = {
+          id: uploadStream.id as ObjectId,
+          filename: fileConfig.filename,
+          originalname: file.originalname,
+          encoding: file.encoding,
+          mimetype: file.mimetype,
+          size: size,
+          bucketName: fileConfig.bucketName,
+          metadata: fileConfig.metadata,
+          contentType: fileConfig.contentType || file.mimetype,
+          uploadDate: new Date(),
+        };
+
+        this.emit("file", storedFile);
+        cb(null, storedFile);
+      });
+
+      // Pipe the file stream to GridFS
+      file.stream.pipe(uploadStream);
+    } catch (error: any) {
+      this.emit("streamError", error, {});
+      cb(error);
+    }
+  }
+
+  /**
+   * Multer storage engine _removeFile method
+   * Called when a file needs to be removed
+   *
+   * @param _req - Express request object (unused)
+   * @param file - GridFS file object to remove
+   * @param cb - Callback to invoke when done
+   */
+  async _removeFile(
+    _req: Request,
+    file: GridFSFile,
+    cb: (error?: Error | null) => void
+  ): Promise<void> {
+    try {
+      if (!this.bucket) {
+        await this.waitForConnection();
+      }
+
+      if (!this.bucket) {
+        throw new Error("GridFS bucket not initialized");
+      }
+
+      await this.bucket.delete(file.id);
+      cb(null);
+    } catch (error: any) {
+      cb(error);
+    }
+  }
+
+  /**
+   * Wait for the storage to be connected
+   * @private
+   * @param maxWaitMs - Maximum time to wait in milliseconds (default: 10000)
+   */
+  private async waitForConnection(maxWaitMs: number = 10000): Promise<void> {
+    if (this.connected && this.bucket) {
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now();
+
+      const checkConnection = () => {
+        if (this.connected && this.bucket) {
+          resolve();
+        } else if (Date.now() - startTime > maxWaitMs) {
+          reject(new Error("Timeout waiting for GridFS connection"));
+        } else {
+          setTimeout(checkConnection, 100);
+        }
+      };
+
+      checkConnection();
+    });
+  }
+
+  /**
+   * Check if storage is ready
+   * @returns True if connected and bucket is initialized
+   */
+  isReady(): boolean {
+    return this.connected && this.bucket !== null;
+  }
+
+  /**
+   * Get the GridFS bucket instance
+   * @returns GridFSBucket instance or null if not initialized
+   */
+  getBucket(): GridFSBucket | null {
+    return this.bucket;
+  }
+
+  /**
+   * Set default bucket name for new instances
+   * @param name - Bucket name
+   */
+  setDefaultBucketName(name: string): void {
+    this.defaultBucketName = name;
+  }
+
+  /**
+   * Set default chunk size for new instances
+   * @param size - Chunk size in bytes
+   */
+  setDefaultChunkSize(size: number): void {
+    this.defaultChunkSize = size;
+  }
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+/**
+ * TypeScript type definitions for bun-gridfs-storage
+ *
+ * @module bun-gridfs-storage/types
+ * @author Aissam Irhir <aissamirhir@gmail.com>
+ */
+
+import type { Request } from "express";
+import type { ObjectId } from "mongodb";
+
+/**
+ * GridFS file information returned after upload
+ */
+export interface GridFSFile {
+  /** MongoDB ObjectId of the uploaded file */
+  id: ObjectId;
+
+  /** Filename used in GridFS */
+  filename: string;
+
+  /** Original filename from the upload */
+  originalname: string;
+
+  /** File encoding (e.g., "7bit", "base64") */
+  encoding: string;
+
+  /** MIME type of the file */
+  mimetype: string;
+
+  /** File size in bytes */
+  size: number;
+
+  /** GridFS bucket name where file is stored */
+  bucketName: string;
+
+  /** Custom metadata stored with the file */
+  metadata?: Record<string, any>;
+
+  /** Content type of the file */
+  contentType?: string;
+
+  /** Date when the file was uploaded */
+  uploadDate?: Date;
+}
+
+/**
+ * Configuration for storing a file in GridFS
+ */
+export interface FileConfig {
+  /** Filename to use in GridFS */
+  filename: string;
+
+  /** GridFS bucket name */
+  bucketName: string;
+
+  /** Chunk size in bytes (default: 255KB) */
+  chunkSize?: number;
+
+  /** Custom metadata to store with the file */
+  metadata?: Record<string, any>;
+
+  /** Content type of the file */
+  contentType?: string;
+}
+
+/**
+ * Multer file type
+ */
+export interface MulterFile {
+  fieldname: string;
+  originalname: string;
+  encoding: string;
+  mimetype: string;
+  size: number;
+  stream: NodeJS.ReadableStream;
+  destination: string;
+  filename: string;
+  path: string;
+  buffer: Buffer;
+}
+
+/**
+ * Callback function to configure file storage
+ * Can return a promise or the configuration directly
+ */
+export type FileConfigCallback = (
+  req: Request,
+  file: MulterFile
+) => Promise<FileConfig> | FileConfig;
+
+/**
+ * Options for initializing BunGridFSStorage
+ */
+export interface BunGridFSStorageOptions {
+  /**
+   * MongoDB database connection
+   * Can be a Promise (for deferred connection) or direct Db instance
+   */
+  db: Promise<import("mongodb").Db> | import("mongodb").Db;
+
+  /**
+   * Optional callback to configure file storage
+   * If not provided, uses original filename and default bucket
+   */
+  file?: FileConfigCallback;
+}
+
+/**
+ * Events emitted by BunGridFSStorage
+ */
+export interface BunGridFSStorageEvents {
+  /** Emitted when database connection is established */
+  connection: (db: import("mongodb").Db) => void;
+
+  /** Emitted when a file is successfully stored */
+  file: (file: GridFSFile) => void;
+
+  /** Emitted when a stream error occurs */
+  streamError: (error: Error, fileConfig: Partial<FileConfig>) => void;
+
+  /** Emitted when database connection fails */
+  connectionFailed: (error: Error) => void;
+}