@gravito/nebula 3.0.1 → 4.1.0

package/dist/index.js

@@ -1,87 +1,931 @@
-// src/index.ts
-import { mkdir } from "fs/promises";
-import { isAbsolute, normalize, resolve, sep } from "path";
-import {
-  getRuntimeAdapter
-} from "@gravito/core";
-var LocalStorageProvider = class {
-  rootDir;
-  baseUrl;
-  runtime = getRuntimeAdapter();
+// src/StorageRepository.ts
+var StorageRepository = class {
+  constructor(store, hooks) {
+    this.store = store;
+    this.hooks = hooks;
+  }
+  /**
+   * Stores content and triggers upload hooks.
+   *
+   * Applies the `storage:upload` filter to the data before storage and
+   * fires the `storage:uploaded` action upon success.
+   *
+   * @param key - The destination path
+   * @param data - The content to store
+   * @param options - Optional upload options (content-type, metadata, cache-control, etc.)
+   * @throws {Error} If the underlying store fails to persist the data
+   */
+  async put(key, data, options) {
+    const finalData = this.hooks ? await this.hooks.applyFilter("storage:upload", data, { key, options }) : data;
+    await this.store.put(key, finalData, options);
+    if (this.hooks) {
+      await this.hooks.doAction("storage:uploaded", { key, options });
+    }
+  }
+  /**
+   * Retrieves content and triggers hit/miss hooks.
+   *
+   * Fires `storage:hit` if the file exists, or `storage:miss` otherwise.
+   *
+   * @param key - The path of the file to retrieve
+   * @returns The file content as a Blob, or null if not found
+   */
+  async get(key) {
+    const data = await this.store.get(key);
+    if (this.hooks) {
+      if (data) {
+        await this.hooks.doAction("storage:hit", { key });
+      } else {
+        await this.hooks.doAction("storage:miss", { key });
+      }
+    }
+    return data;
+  }
+  /**
+   * Deletes a file and triggers the deleted hook.
+   *
+   * Fires `storage:deleted` only if the file was actually removed.
+   *
+   * @param key - The path of the file to delete
+   * @returns True if deleted, false if file didn't exist
+   */
+  async delete(key) {
+    const deleted = await this.store.delete(key);
+    if (deleted && this.hooks) {
+      await this.hooks.doAction("storage:deleted", { key });
+    }
+    return deleted;
+  }
+  /**
+   * Checks for file existence.
+   *
+   * @param key - The path to check
+   * @returns True if exists, false otherwise
+   */
+  async exists(key) {
+    return this.store.exists(key);
+  }
+  /**
+   * Copies a file and triggers the copied hook.
+   *
+   * Fires `storage:copied` upon successful completion.
+   *
+   * @param from - Source path
+   * @param to - Destination path
+   * @throws {Error} If source missing or operation fails
+   */
+  async copy(from, to) {
+    await this.store.copy(from, to);
+    if (this.hooks) {
+      await this.hooks.doAction("storage:copied", { from, to });
+    }
+  }
+  /**
+   * Moves a file and triggers the moved hook.
+   *
+   * Fires `storage:moved` upon successful completion.
+   *
+   * @param from - Current path
+   * @param to - New path
+   * @throws {Error} If source missing or operation fails
+   */
+  async move(from, to) {
+    await this.store.move(from, to);
+    if (this.hooks) {
+      await this.hooks.doAction("storage:moved", { from, to });
+    }
+  }
   /**
-   * Create a new LocalStorageProvider.
+   * Lists files using an async generator.
    *
-   * @param rootDir - The absolute path to the local storage directory.
-   * @param baseUrl - The public URL path for accessing stored files (e.g., '/storage').
+   * @param prefix - Path prefix to filter by
+   * @returns Async iterable of storage items
+   * @throws {Error} If the underlying driver does not support listing
    */
+  async *list(prefix) {
+    if (!this.store.list) {
+      throw new Error("[StorageRepository] This storage driver does not support listing files.");
+    }
+    yield* this.store.list(prefix);
+  }
+  /**
+   * Lists files with pagination support.
+   *
+   * 分頁列舉檔案
+   * Recommended for large storage backends to prevent OOM.
+   * Provides cursor-based pagination for efficient enumeration.
+   *
+   * @param prefix - Path prefix to filter by
+   * @param options - Pagination and filtering options
+   * @returns Paginated list result with cursor for next page
+   * @throws {Error} If the underlying driver does not support paginated listing
+   */
+  async listPaginated(prefix, options) {
+    if (!this.store.listPaginated) {
+      throw new Error("[StorageRepository] This storage driver does not support paginated listing.");
+    }
+    return this.store.listPaginated(prefix, options);
+  }
+  /**
+   * Retrieves file metadata.
+   *
+   * @param key - Path of the file
+   * @returns Metadata object or null if not found
+   */
+  async getMetadata(key) {
+    return this.store.getMetadata(key);
+  }
+  /**
+   * Updates custom metadata for a file.
+   *
+   * 更新自定義 Metadata
+   *
+   * @param key - Path of the file
+   * @param metadata - Custom metadata to set
+   * @throws {Error} If the underlying driver does not support metadata updates
+   */
+  async setMetadata(key, metadata) {
+    if (!this.store.setMetadata) {
+      throw new Error("[StorageRepository] This storage driver does not support metadata updates.");
+    }
+    await this.store.setMetadata(key, metadata);
+  }
+  /**
+   * Generates a public URL.
+   *
+   * @param key - Path of the file
+   * @returns URL string
+   */
+  getUrl(key) {
+    return this.store.getUrl(key);
+  }
+  /**
+   * Generates a temporary signed URL.
+   *
+   * @param key - Path of the file
+   * @param expiresIn - Expiration in seconds
+   * @returns Signed URL string
+   * @throws {Error} If the underlying driver does not support signed URLs
+   */
+  async getSignedUrl(key, expiresIn) {
+    if (!this.store.getSignedUrl) {
+      throw new Error("[StorageRepository] This storage driver does not support signed URLs.");
+    }
+    return this.store.getSignedUrl(key, expiresIn);
+  }
+  /**
+   * Stores content from a readable stream and triggers upload hooks.
+   *
+   * 串流上傳並觸發 hooks
+   * Useful for handling large files without loading entire content into memory.
+   * Applies the `storage:upload` filter and fires the `storage:uploaded` action.
+   *
+   * @param key - The destination path
+   * @param stream - Readable stream containing the data
+   * @throws {Error} If the underlying driver does not support stream writing
+   */
+  async putStream(key, stream) {
+    if (!this.store.putStream) {
+      throw new Error("[StorageRepository] This storage driver does not support stream writing.");
+    }
+    await this.store.putStream(key, stream);
+    if (this.hooks) {
+      await this.hooks.doAction("storage:uploaded", { key });
+    }
+  }
+  /**
+   * Retrieves content as a readable stream and triggers hit/miss hooks.
+   *
+   * 串流讀取並觸發 hooks
+   * Useful for handling large files without loading entire content into memory.
+   * Fires `storage:hit` if the file exists, or `storage:miss` otherwise.
+   *
+   * @param key - Path of the file
+   * @returns Readable stream of file content, or null if not found
+   * @throws {Error} If the underlying driver does not support stream reading
+   */
+  async getStream(key) {
+    if (!this.store.getStream) {
+      throw new Error("[StorageRepository] This storage driver does not support stream reading.");
+    }
+    const stream = await this.store.getStream(key);
+    if (this.hooks) {
+      if (stream) {
+        await this.hooks.doAction("storage:hit", { key });
+      } else {
+        await this.hooks.doAction("storage:miss", { key });
+      }
+    }
+    return stream;
+  }
+};
+
+// src/StorageManager.ts
+var StorageManager = class {
+  constructor(storeFactory, options, hooks) {
+    this.storeFactory = storeFactory;
+    this.options = options;
+    this.hooks = hooks;
+  }
+  stores = /* @__PURE__ */ new Map();
+  repositories = /* @__PURE__ */ new Map();
+  /**
+   * Accesses a specific storage disk by name.
+   *
+   * If no name is provided, the default disk configured during initialization is returned.
+   * Repositories are lazily initialized and cached for subsequent access.
+   *
+   * @param name - The unique identifier of the disk to access
+   * @returns A repository instance for the requested disk
+   * @throws {Error} If the requested disk is not configured or factory fails
+   */
+  disk(name) {
+    const diskName = name ?? this.options.default;
+    if (!this.repositories.has(diskName)) {
+      const store = this.resolveStore(diskName);
+      this.repositories.set(diskName, new StorageRepository(store, this.hooks));
+    }
+    return this.repositories.get(diskName);
+  }
+  resolveStore(name) {
+    if (!this.stores.has(name)) {
+      this.stores.set(name, this.storeFactory(name));
+    }
+    return this.stores.get(name);
+  }
+  /**
+   * Stores content at the specified key on the default disk.
+   *
+   * @param key - The destination path/identifier
+   * @param data - The content to store
+   * @param options - Optional upload options (content-type, metadata, cache-control, etc.)
+   * @returns A promise that resolves when the operation completes
+   * @throws {Error} If the storage operation fails on the default disk
+   */
+  put(key, data, options) {
+    return this.disk().put(key, data, options);
+  }
+  /**
+   * Retrieves content from the specified key on the default disk.
+   *
+   * @param key - The path/identifier of the file to retrieve
+   * @returns The file content as a Blob, or null if not found
+   */
+  get(key) {
+    return this.disk().get(key);
+  }
+  /**
+   * Removes a file from the default disk.
+   *
+   * @param key - The path/identifier of the file to delete
+   * @returns True if the file was deleted, false if it didn't exist
+   */
+  delete(key) {
+    return this.disk().delete(key);
+  }
+  /**
+   * Checks if a file exists on the default disk.
+   *
+   * @param key - The path/identifier to check
+   * @returns True if the file exists, false otherwise
+   */
+  exists(key) {
+    return this.disk().exists(key);
+  }
+  /**
+   * Creates a copy of a file on the default disk.
+   *
+   * @param from - The source path
+   * @param to - The destination path
+   * @throws {Error} If the source file does not exist or copy fails
+   */
+  copy(from, to) {
+    return this.disk().copy(from, to);
+  }
+  /**
+   * Moves or renames a file on the default disk.
+   *
+   * @param from - The current path
+   * @param to - The new path
+   * @throws {Error} If the source file does not exist or move fails
+   */
+  move(from, to) {
+    return this.disk().move(from, to);
+  }
+  /**
+   * Lists files and directories under a given prefix on the default disk.
+   *
+   * @param prefix - The directory or path prefix to list
+   * @returns An async iterable of storage items
+   * @throws {Error} If the default disk driver does not support listing
+   */
+  list(prefix) {
+    return this.disk().list(prefix);
+  }
+  /**
+   * Retrieves metadata for a specific file on the default disk.
+   *
+   * @param key - The path/identifier of the file
+   * @returns Metadata object or null if file not found
+   */
+  getMetadata(key) {
+    return this.disk().getMetadata(key);
+  }
+  /**
+   * Generates a public URL for a file on the default disk.
+   *
+   * @param key - The path/identifier of the file
+   * @returns The absolute or relative URL string
+   */
+  getUrl(key) {
+    return this.disk().getUrl(key);
+  }
+  /**
+   * Generates a temporary, signed URL for a file on the default disk.
+   *
+   * @param key - The path/identifier of the file
+   * @param expiresIn - Expiration time in seconds
+   * @returns A promise resolving to the signed URL string
+   * @throws {Error} If the default disk driver does not support signed URLs
+   */
+  getSignedUrl(key, expiresIn) {
+    return this.disk().getSignedUrl(key, expiresIn);
+  }
+  /**
+   * Stores content from a readable stream on the default disk.
+   *
+   * 串流上傳到預設磁碟
+   * Useful for handling large files without loading entire content into memory.
+   *
+   * @param key - The destination path
+   * @param stream - Readable stream containing the data
+   * @throws {Error} If the default disk driver does not support stream writing
+   */
+  putStream(key, stream) {
+    return this.disk().putStream(key, stream);
+  }
+  /**
+   * Retrieves content as a readable stream from the default disk.
+   *
+   * 從預設磁碟串流讀取
+   * Useful for handling large files without loading entire content into memory.
+   *
+   * @param key - The path/identifier of the file
+   * @returns Readable stream of file content, or null if not found
+   * @throws {Error} If the default disk driver does not support stream reading
+   */
+  getStream(key) {
+    return this.disk().getStream(key);
+  }
+  /**
+   * Lists files with pagination support on the default disk.
+   *
+   * 在預設磁碟上分頁列舉檔案
+   * Recommended for large storage backends to prevent OOM.
+   *
+   * @param prefix - Path prefix to filter by
+   * @param options - Pagination and filtering options
+   * @returns Paginated list result with cursor for next page
+   * @throws {Error} If the default disk driver does not support paginated listing
+   */
+  listPaginated(prefix, options) {
+    return this.disk().listPaginated(prefix, options);
+  }
+  /**
+   * Updates custom metadata for a file on the default disk.
+   *
+   * 更新預設磁碟上檔案的自定義 Metadata
+   *
+   * @param key - The path/identifier of the file
+   * @param metadata - Custom metadata to set
+   * @throws {Error} If the default disk driver does not support metadata updates
+   */
+  setMetadata(key, metadata) {
+    return this.disk().setMetadata(key, metadata);
+  }
+};
+
+// src/stores/LocalStore.ts
+import { mkdir } from "fs/promises";
+import { isAbsolute, normalize, resolve, sep } from "path";
+import { getRuntimeAdapter } from "@gravito/core";
+var LocalStore = class {
   constructor(rootDir, baseUrl = "/storage") {
     this.rootDir = rootDir;
     this.baseUrl = baseUrl;
   }
+  runtime = getRuntimeAdapter();
   /**
-   * Write data to the local disk.
+   * Writes data to a file on the local disk.
+   *
+   * Automatically creates parent directories if they don't exist.
+   *
+   * @param key - Relative path from the root directory
+   * @param data - Content to write
+   * @param options - Optional upload options (note: customMetadata not persisted in LocalStore)
+   * @throws {Error} If the key is invalid or path is outside root
    */
-  async put(key, data) {
-    const path = this.resolveKeyPath(key);
-    const dir = path.substring(0, path.lastIndexOf("/"));
-    if (dir && dir !== this.rootDir) {
-      await mkdir(dir, { recursive: true });
-    }
+  async put(key, data, options) {
+    const path = this.resolvePath(key);
+    await this.ensureDirectory(path);
     await this.runtime.writeFile(path, data);
   }
   /**
-   * Read data from the local disk.
+   * Reads a file from the local disk as a Blob.
+   *
+   * @param key - Relative path from the root directory
+   * @returns File content as Blob, or null if not found
+   * @throws {Error} If the key is invalid or path is outside root
    */
   async get(key) {
-    const path = this.resolveKeyPath(key);
-    if (!await this.runtime.exists(path)) {
+    if (!await this.exists(key)) {
       return null;
     }
-    return await this.runtime.readFileAsBlob(path);
+    const path = this.resolvePath(key);
+    return this.runtime.readFileAsBlob(path);
   }
   /**
-   * Delete a file from the local disk.
+   * Deletes a file from the local disk.
+   *
+   * @param key - Relative path from the root directory
+   * @returns True if deleted, false if file didn't exist
+   * @throws {Error} If the key is invalid or path is outside root
    */
   async delete(key) {
-    await this.runtime.deleteFile(this.resolveKeyPath(key));
+    if (!await this.exists(key)) {
+      return false;
+    }
+    const path = this.resolvePath(key);
+    await this.runtime.deleteFile(path);
+    return true;
   }
   /**
-   * Resolve the public URL for a locally stored file.
+   * Checks if a file exists on the local disk.
+   *
+   * @param key - Relative path from the root directory
+   * @returns True if exists, false otherwise
+   */
+  async exists(key) {
+    const path = this.resolvePath(key);
+    return this.runtime.exists(path);
+  }
+  /**
+   * Copies a file on the local disk.
+   *
+   * @param from - Source relative path
+   * @param to - Destination relative path
+   * @throws {Error} If source missing or operation fails
+   */
+  async copy(from, to) {
+    const data = await this.get(from);
+    if (!data) {
+      throw new Error(`[LocalStore] Source file not found: ${from}`);
+    }
+    await this.put(to, data);
+  }
+  /**
+   * Moves a file on the local disk.
+   *
+   * @param from - Current relative path
+   * @param to - New relative path
+   * @throws {Error} If source missing or operation fails
+   */
+  async move(from, to) {
+    await this.copy(from, to);
+    await this.delete(from);
+  }
+  /**
+   * @internal
+   * @throws {Error} Always, as not yet implemented
+   */
+  list(_prefix = "") {
+    throw new Error(
+      "[LocalStore] list() is not yet implemented. Requires RuntimeAdapter.readDir() support in @gravito/core."
+    );
+  }
+  /**
+   * Retrieves file metadata from the local filesystem.
+   *
+   * @param key - Relative path from the root directory
+   * @returns Metadata object or null if not found
+   */
+  async getMetadata(key) {
+    if (!await this.exists(key)) {
+      return null;
+    }
+    const path = this.resolvePath(key);
+    const stat = await this.runtime.stat(path);
+    return {
+      key,
+      size: stat.size,
+      mimeType: this.guessMimeType(key),
+      lastModified: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Generates a public URL based on the configured base URL.
+   *
+   * @param key - Relative path from the root directory
+   * @returns URL string
    */
   getUrl(key) {
     const safeKey = this.normalizeKey(key);
     return `${this.baseUrl}/${safeKey}`;
   }
+  /**
+   * Writes data from a readable stream to a file on the local disk.
+   *
+   * 串流寫入檔案
+   * Automatically creates parent directories if they don't exist.
+   * Useful for handling large files without loading entire content into memory.
+   *
+   * @param key - Relative path from the root directory
+   * @param stream - Readable stream containing the data
+   * @throws {Error} If the key is invalid or path is outside root
+   */
+  async putStream(key, stream) {
+    const path = this.resolvePath(key);
+    await this.ensureDirectory(path);
+    const file = Bun.file(path);
+    const writer = file.writer();
+    const reader = stream.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        writer.write(value);
+      }
+      await writer.end();
+    } catch (error) {
+      reader.releaseLock();
+      throw new Error(`[LocalStore] Failed to write stream: ${error}`);
+    }
+  }
+  /**
+   * Reads a file from the local disk as a readable stream.
+   *
+   * 串流讀取檔案
+   * Useful for handling large files without loading entire content into memory.
+   *
+   * @param key - Relative path from the root directory
+   * @returns Readable stream of file content, or null if not found
+   * @throws {Error} If the key is invalid or path is outside root
+   */
+  async getStream(key) {
+    if (!await this.exists(key)) {
+      return null;
+    }
+    const path = this.resolvePath(key);
+    const file = Bun.file(path);
+    return file.stream();
+  }
   normalizeKey(key) {
     if (!key || key.includes("\0")) {
-      throw new Error("Invalid storage key.");
+      throw new Error("[LocalStore] Invalid storage key: empty or contains null byte.");
     }
     const normalized = normalize(key).replace(/^[/\\]+/, "");
-    if (normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`) || isAbsolute(normalized)) {
-      throw new Error("Invalid storage key.");
+    if (normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`) || normalized.startsWith(`.${sep}`) || isAbsolute(normalized)) {
+      throw new Error("[LocalStore] Invalid storage key: path traversal attempt.");
     }
     return normalized.replace(/\\/g, "/");
   }
-  resolveKeyPath(key) {
+  resolvePath(key) {
     const normalized = this.normalizeKey(key);
     const root = resolve(this.rootDir);
     const resolved = resolve(root, normalized);
     const rootPrefix = root.endsWith(sep) ? root : `${root}${sep}`;
     if (!resolved.startsWith(rootPrefix) && resolved !== root) {
-      throw new Error("Invalid storage key.");
+      throw new Error("[LocalStore] Invalid storage key: resolved path outside root.");
     }
     return resolved;
   }
+  async ensureDirectory(filePath) {
+    const dir = filePath.substring(0, filePath.lastIndexOf(sep));
+    if (dir && dir !== this.rootDir) {
+      await mkdir(dir, { recursive: true });
+    }
+  }
+  guessMimeType(key) {
+    const ext = key.split(".").pop()?.toLowerCase();
+    const mimeTypes = {
+      txt: "text/plain",
+      html: "text/html",
+      css: "text/css",
+      js: "text/javascript",
+      json: "application/json",
+      png: "image/png",
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      gif: "image/gif",
+      svg: "image/svg+xml",
+      pdf: "application/pdf",
+      zip: "application/zip"
+    };
+    return mimeTypes[ext ?? ""] ?? "application/octet-stream";
+  }
 };
+
+// src/stores/MemoryStore.ts
+var MemoryStore = class {
+  files = /* @__PURE__ */ new Map();
+  /**
+   * Stores data in the internal Map.
+   *
+   * Converts input data to a Blob before storage.
+   *
+   * @param key - Unique identifier for the file
+   * @param data - Content to store
+   * @param options - Optional upload options (content-type, metadata, etc.)
+   */
+  async put(key, data, options) {
+    let blob;
+    if (data instanceof Blob) {
+      blob = data;
+    } else if (typeof data === "string") {
+      blob = new Blob([data], { type: options?.contentType });
+    } else {
+      blob = new Blob([new Uint8Array(data)], { type: options?.contentType });
+    }
+    this.files.set(key, {
+      data: blob,
+      options,
+      metadata: {
+        key,
+        size: blob.size,
+        mimeType: options?.contentType || blob.type || "application/octet-stream",
+        lastModified: /* @__PURE__ */ new Date(),
+        customMetadata: options?.metadata
+      }
+    });
+  }
+  /**
+   * Retrieves a Blob from the internal Map.
+   *
+   * @param key - Unique identifier for the file
+   * @returns The Blob content, or null if not found
+   */
+  async get(key) {
+    return this.files.get(key)?.data ?? null;
+  }
+  /**
+   * Removes a file from memory.
+   *
+   * @param key - Unique identifier for the file
+   * @returns True if deleted, false if not found
+   */
+  async delete(key) {
+    return this.files.delete(key);
+  }
+  /**
+   * Checks if a key exists in the internal Map.
+   *
+   * @param key - Unique identifier to check
+   * @returns True if exists, false otherwise
+   */
+  async exists(key) {
+    return this.files.has(key);
+  }
+  /**
+   * Copies a file within memory.
+   *
+   * @param from - Source key
+   * @param to - Destination key
+   * @throws {Error} If source file is missing
+   */
+  async copy(from, to) {
+    const file = this.files.get(from);
+    if (!file) {
+      throw new Error(`[MemoryStore] Source file not found: ${from}`);
+    }
+    this.files.set(to, {
+      data: file.data,
+      metadata: { ...file.metadata, key: to, lastModified: /* @__PURE__ */ new Date() }
+    });
+  }
+  /**
+   * Moves a file within memory.
+   *
+   * @param from - Current key
+   * @param to - New key
+   * @throws {Error} If source file is missing
+   */
+  async move(from, to) {
+    await this.copy(from, to);
+    await this.delete(from);
+  }
+  /**
+   * Lists all files currently in memory.
+   *
+   * @param prefix - Optional key prefix to filter by
+   * @returns Async iterable of storage items
+   */
+  async *list(prefix = "") {
+    for (const [key, file] of this.files.entries()) {
+      if (key.startsWith(prefix)) {
+        yield {
+          key,
+          isDirectory: false,
+          size: file.metadata.size,
+          lastModified: file.metadata.lastModified
+        };
+      }
+    }
+  }
+  /**
+   * Retrieves metadata for an in-memory file.
+   *
+   * @param key - Unique identifier for the file
+   * @returns Metadata object or null if not found
+   */
+  async getMetadata(key) {
+    return this.files.get(key)?.metadata ?? null;
+  }
+  /**
+   * Generates a dummy URL for the in-memory file.
+   *
+   * @param key - Unique identifier for the file
+   * @returns A string starting with /memory/
+   */
+  getUrl(key) {
+    return `/memory/${key}`;
+  }
+  /**
+   * Stores data from a readable stream in memory.
+   *
+   * 串流寫入記憶體
+   * Reads the entire stream into memory before storing.
+   *
+   * @param key - Unique identifier for the file
+   * @param stream - Readable stream containing the data
+   */
+  async putStream(key, stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+      const buffer = Buffer.concat(chunks);
+      const blob = new Blob([buffer]);
+      await this.put(key, blob);
+    } catch (error) {
+      reader.releaseLock();
+      throw new Error(`[MemoryStore] Failed to write stream: ${error}`);
+    }
+  }
+  /**
+   * Reads an in-memory file as a readable stream.
+   *
+   * 串流讀取記憶體檔案
+   *
+   * @param key - Unique identifier for the file
+   * @returns Readable stream of file content, or null if not found
+   */
+  async getStream(key) {
+    const blob = await this.get(key);
+    if (!blob) {
+      return null;
+    }
+    return blob.stream();
+  }
+  /**
+   * Updates custom metadata for an in-memory file.
+   *
+   * 更新自定義 Metadata
+   *
+   * @param key - Unique identifier for the file
+   * @param metadata - Custom metadata to set
+   * @throws {Error} If file does not exist
+   */
+  async setMetadata(key, metadata) {
+    const file = this.files.get(key);
+    if (!file) {
+      throw new Error(`[MemoryStore] File not found: ${key}`);
+    }
+    file.metadata.customMetadata = {
+      ...file.metadata.customMetadata,
+      ...metadata
+    };
+    file.metadata.lastModified = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Lists files with pagination support.
+   *
+   * 分頁列舉記憶體中的檔案
+   * Provides cursor-based pagination for consistent API with other drivers.
+   *
+   * @param prefix - Key prefix to filter by
+   * @param options - Pagination and filtering options
+   * @returns Paginated list result
+   */
+  async listPaginated(prefix = "", options) {
+    const maxResults = options?.maxResults ?? 1e3;
+    const cursorKey = options?.cursor;
+    const allKeys = Array.from(this.files.keys()).filter((key) => key.startsWith(prefix)).sort();
+    let startIndex = 0;
+    if (cursorKey) {
+      startIndex = allKeys.findIndex((key) => key > cursorKey);
+      if (startIndex === -1) {
+        return {
+          items: [],
+          nextCursor: null,
+          hasMore: false,
+          count: 0
+        };
+      }
+    }
+    const endIndex = startIndex + maxResults;
+    const pageKeys = allKeys.slice(startIndex, endIndex);
+    const hasMore = endIndex < allKeys.length;
+    const items = pageKeys.map((key) => {
+      const file = this.files.get(key);
+      return {
+        key,
+        isDirectory: false,
+        size: file.metadata.size,
+        lastModified: file.metadata.lastModified
+      };
+    });
+    const nextCursor = hasMore && items.length > 0 ? items[items.length - 1].key : null;
+    return {
+      items,
+      nextCursor,
+      hasMore,
+      count: items.length
+    };
+  }
+};
+
+// src/stores/NullStore.ts
+var NullStore = class {
+  /**
+   * No-op: does not store any data.
+   */
+  async put(_key, _data) {
+  }
+  /**
+   * Always returns null.
+   */
+  async get(_key) {
+    return null;
+  }
+  /**
+   * Always returns false.
+   */
+  async delete(_key) {
+    return false;
+  }
+  /**
+   * Always returns false.
+   */
+  async exists(_key) {
+    return false;
+  }
+  /**
+   * No-op: does not copy anything.
+   */
+  async copy(_from, _to) {
+  }
+  /**
+   * No-op: does not move anything.
+   */
+  async move(_from, _to) {
+  }
+  /**
+   * Always yields nothing.
+   */
+  async *list(_prefix) {
+  }
+  /**
+   * Always returns null.
+   */
+  async getMetadata(_key) {
+    return null;
+  }
+  /**
+   * Generates a dummy URL starting with /null/.
+   */
+  getUrl(key) {
+    return `/null/${key}`;
+  }
+};
+
+// src/index.ts
 var OrbitNebula = class {
   constructor(options) {
     this.options = options;
   }
+  manager;
   /**
-   * Install storage service into PlanetCore.
+   * Bootstraps the storage service and registers it with PlanetCore.
    *
-   * @param core - The PlanetCore instance.
-   * @throws {Error} If configuration or provider is missing.
+   * This method initializes the StorageManager, configures the default disk,
+   * and registers the storage service in the IoC container and middleware.
+   *
+   * @param core - The PlanetCore instance to install into
+   * @throws {Error} If configuration is missing or default disk cannot be initialized
    */
   install(core) {
     const config = this.options || core.config.get("storage");
@@ -91,62 +935,93 @@ var OrbitNebula = class {
       );
     }
     const { exposeAs = "storage" } = config;
-    const logger = core.logger;
-    logger.info(`[OrbitNebula] Initializing Storage (Exposed as: ${exposeAs})`);
-    let provider = config.provider;
-    if (!provider && config.local) {
-      logger.info(`[OrbitNebula] Using LocalStorageProvider at ${config.local.root}`);
-      provider = new LocalStorageProvider(config.local.root, config.local.baseUrl);
-    }
-    if (!provider) {
-      throw new Error(
-        "[OrbitNebula] No provider configured. Please provide a provider instance or local configuration."
-      );
+    core.logger.info(`[OrbitNebula] Initializing Storage (Exposed as: ${exposeAs})`);
+    let defaultDisk = config.default;
+    if (!defaultDisk) {
+      if (config.local) {
+        defaultDisk = "local";
+      } else if (config.provider) {
+        defaultDisk = "custom";
+      } else {
+        defaultDisk = "local";
+      }
     }
-    const storageService = {
-      put: async (key, data) => {
-        const finalData = await core.hooks.applyFilters("storage:upload", data, { key });
-        await provider?.put(key, finalData);
-        await core.hooks.doAction("storage:uploaded", { key });
-      },
-      get: (key) => provider?.get(key),
-      delete: (key) => provider?.delete(key),
-      getUrl: (key) => provider?.getUrl(key)
+    const managerOptions = {
+      default: defaultDisk
+    };
+    const storageHooks = {
+      applyFilter: (h, v, c) => core.hooks.applyFilters(h, v, c),
+      doAction: (h, c) => core.hooks.doAction(h, c)
     };
-    core.container.instance(exposeAs, storageService);
+    const storeFactory = this.createStoreFactory(config);
+    this.manager = new StorageManager(storeFactory, managerOptions, storageHooks);
+    this.manager.disk();
+    core.container.instance(exposeAs, this.manager);
     core.adapter.use("*", async (c, next) => {
-      c.set(exposeAs, storageService);
+      c.set(exposeAs, this.manager);
       await next();
       return void 0;
     });
-    core.hooks.doAction("storage:init", storageService);
+    core.hooks.doAction("storage:init", { manager: this.manager });
+  }
+  /**
+   * Retrieves the initialized StorageManager instance.
+   *
+   * Use this to access storage operations directly from the orbit instance
+   * after it has been installed.
+   *
+   * @returns The active StorageManager instance
+   * @throws {Error} If called before the orbit is installed
+   */
+  getStorage() {
+    if (!this.manager) {
+      throw new Error("[OrbitNebula] StorageManager not initialized. Call install() first.");
+    }
+    return this.manager;
+  }
+  createStoreFactory(options) {
+    return (name) => {
+      const config = options.disks?.[name];
+      if (config) {
+        if (config.driver === "local") {
+          return new LocalStore(config.root, config.baseUrl);
+        }
+        if (config.driver === "memory") {
+          return new MemoryStore();
+        }
+        if (config.driver === "null") {
+          return new NullStore();
+        }
+        if (config.driver === "custom") {
+          return config.store;
+        }
+      }
+      if (name === "local" && options.local) {
+        return new LocalStore(options.local.root, options.local.baseUrl);
+      }
+      if (options.provider) {
+        if (name === "custom" || !options.disks && !options.local) {
+          return options.provider;
+        }
+      }
+      throw new Error(`[OrbitNebula] Driver not configured for disk: ${name}`);
+    };
   }
 };
 function orbitStorage(core, options) {
   const orbit = new OrbitNebula(options);
   orbit.install(core);
-  let provider = options.provider;
-  if (!provider && options.local) {
-    provider = new LocalStorageProvider(options.local.root, options.local.baseUrl);
-  }
-  if (!provider) {
-    throw new Error("[OrbitNebula] No provider configured.");
-  }
-  return {
-    put: async (key, data) => {
-      const finalData = await core.hooks.applyFilters("storage:upload", data, { key });
-      await provider?.put(key, finalData);
-      await core.hooks.doAction("storage:uploaded", { key });
-    },
-    get: (key) => provider?.get(key),
-    delete: (key) => provider?.delete(key),
-    getUrl: (key) => provider?.getUrl(key)
-  };
+  return orbit.getStorage();
 }
 var OrbitStorage = OrbitNebula;
 export {
-  LocalStorageProvider,
+  LocalStore as LocalStorageProvider,
+  LocalStore,
+  MemoryStore,
+  NullStore,
   OrbitNebula,
   OrbitStorage,
+  StorageManager,
+  StorageRepository,
   orbitStorage as default
 };