@gravito/nebula 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -1,72 +1,147 @@
-import { PlanetCore, GravitoOrbit } from '@gravito/core';
+import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * 底層儲存介面
+ * StorageStore defines the low-level contract for storage backends.
  *
- * 所有儲存後端 (Local, S3, GCS 等) 必須實作此介面
+ * All storage drivers (Local, S3, Memory, etc.) must implement this interface.
+ * It focuses on raw I/O operations without higher-level logic like hooks.
  *
  * @public
- * @since 4.0.0
  */
 interface StorageStore {
     /**
+     * Persists data to the storage backend.
+     *
      * 儲存檔案
-     * @param key - 檔案路徑 (例如: 'avatars/user1.jpg')
-     * @param data - 檔案內容
+     * @param key - Unique identifier or path for the file
+     * @param data - Content to be stored
+     * @param options - Optional upload options (content-type, metadata, cache-control, etc.)
+     * @throws {Error} If the backend fails to write the data
      */
-    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    put(key: string, data: Blob | Buffer | string, options?: PutOptions): Promise<void>;
     /**
+     * Retrieves data from the storage backend.
+     *
      * 讀取檔案
-     * @param key - 檔案路徑
-     * @returns 檔案內容，若不存在則回傳 null
+     * @param key - Unique identifier or path for the file
+     * @returns The file content as a Blob, or null if the key does not exist
      */
     get(key: string): Promise<Blob | null>;
     /**
+     * Removes data from the storage backend.
+     *
      * 刪除檔案
-     * @param key - 檔案路徑
-     * @returns 是否成功刪除 (若檔案不存在則回傳 false)
+     * @param key - Unique identifier or path for the file
+     * @returns True if the file was successfully deleted, false if it didn't exist
      */
     delete(key: string): Promise<boolean>;
     /**
+     * Verifies the existence of a file.
+     *
      * 檢查檔案是否存在
-     * @param key - 檔案路徑
+     * @param key - Unique identifier or path for the file
+     * @returns True if the file exists, false otherwise
      */
     exists(key: string): Promise<boolean>;
     /**
+     * Duplicates a file within the same storage backend.
+     *
      * 複製檔案
-     * @param from - 來源路徑
-     * @param to - 目標路徑
+     * @param from - Source identifier
+     * @param to - Destination identifier
+     * @throws {Error} If the source file is missing or copy fails
      */
     copy(from: string, to: string): Promise<void>;
     /**
+     * Relocates or renames a file within the same storage backend.
+     *
      * 移動/重命名檔案
-     * @param from - 來源路徑
-     * @param to - 目標路徑
+     * @param from - Current identifier
+     * @param to - New identifier
+     * @throws {Error} If the source file is missing or move fails
      */
     move(from: string, to: string): Promise<void>;
     /**
+     * Enumerates files and directories.
+     *
      * 列出檔案 (可選實作，需要 RuntimeAdapter 支援)
-     * @param prefix - 路徑前綴 (例如: 'uploads/')
+     * @param prefix - Optional path prefix to filter results
+     * @returns An async iterable of storage items
      */
     list?(prefix?: string): AsyncIterable<StorageItem>;
     /**
+     * Lists files with pagination support.
+     *
+     * 分頁列舉檔案（適合大型儲存空間）
+     * Recommended for large storage backends (S3, GCS) to prevent OOM.
+     * Provides cursor-based pagination for efficient large-scale file enumeration.
+     *
+     * @param prefix - Optional path prefix to filter results
+     * @param options - Pagination and filtering options
+     * @returns Paginated list result with cursor for next page
+     */
+    listPaginated?(prefix: string, options?: ListOptions): Promise<ListResult>;
+    /**
+     * Retrieves technical information about a file.
+     *
      * 取得檔案元資料
-     * @param key - 檔案路徑
+     * @param key - Unique identifier or path for the file
+     * @returns Metadata object or null if file not found
      */
     getMetadata(key: string): Promise<StorageMetadata | null>;
     /**
+     * Updates custom metadata for a file.
+     *
+     * 更新自定義 Metadata（可選實作）
+     * Note: This method only updates custom metadata, not system metadata like size or mimeType.
+     *
+     * @param key - Unique identifier or path for the file
+     * @param metadata - Custom metadata to set (key-value pairs)
+     * @throws {Error} If the file does not exist or operation fails
+     */
+    setMetadata?(key: string, metadata: Record<string, string>): Promise<void>;
+    /**
+     * Generates a publicly accessible URL for the file.
+     *
      * 取得公開 URL
-     * @param key - 檔案路徑
+     * @param key - Unique identifier or path for the file
+     * @returns The URL string
      */
     getUrl(key: string): string;
     /**
+     * Generates a time-limited, authorized URL.
+     *
      * 取得有時效的簽名 URL (可選實作)
-     * @param key - 檔案路徑
-     * @param expiresIn - 過期時間 (秒)
+     * @param key - Unique identifier or path for the file
+     * @param expiresIn - Duration in seconds until the URL expires
+     * @returns A promise resolving to the signed URL string
      */
     getSignedUrl?(key: string, expiresIn: number): Promise<string>;
+    /**
+     * Writes data from a readable stream.
+     *
+     * 串流寫入檔案（可選實作）
+     * Useful for handling large files without loading entire content into memory.
+     *
+     * @param key - Unique identifier or path for the file
+     * @param stream - Readable stream containing the data
+     * @throws {Error} If the backend fails to write the stream
+     */
+    putStream?(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * Reads data as a readable stream.
+     *
+     * 串流讀取檔案（可選實作）
+     * Useful for handling large files without loading entire content into memory.
+     *
+     * @param key - Unique identifier or path for the file
+     * @returns A readable stream of the file content, or null if the key does not exist
+     */
+    getStream?(key: string): Promise<ReadableStream<Uint8Array> | null>;
 }
 /**
+ * StorageMetadata represents technical details of a stored file.
+ *
  * 檔案元資料
  * @public
  */
@@ -81,8 +156,28 @@ interface StorageMetadata {
     lastModified?: Date;
     /** ETag (用於快取驗證) */
     etag?: string;
+    /** 自定義 Metadata (S3 風格) */
+    customMetadata?: Record<string, string>;
 }
 /**
+ * PutOptions provides additional options for file uploads.
+ *
+ * 檔案上傳選項
+ * @public
+ */
+interface PutOptions {
+    /** Content-Type header (MIME type) */
+    contentType?: string;
+    /** 自定義 metadata (key-value pairs) */
+    metadata?: Record<string, string>;
+    /** Cache-Control header (用於 CDN) */
+    cacheControl?: string;
+    /** Content-Disposition header (下載檔名控制) */
+    contentDisposition?: string;
+}
+/**
+ * StorageItem represents an entry in a file listing.
+ *
  * 檔案清單項目
  * @public
  */
@@ -96,31 +191,81 @@ interface StorageItem {
     /** 最後修改時間 */
     lastModified?: Date;
 }
+/**
+ * ListOptions provides pagination and filtering options for file listing.
+ *
+ * 列舉選項（分頁與過濾）
+ * @public
+ */
+interface ListOptions {
+    /** 最大回傳數量（預設: 1000） */
+    maxResults?: number;
+    /** 分頁游標（繼續上次的列舉） */
+    cursor?: string;
+    /** 是否包含子目錄（預設: true） */
+    recursive?: boolean;
+}
+/**
+ * ListResult contains paginated file listing results.
+ *
+ * 分頁列舉結果
+ * @public
+ */
+interface ListResult {
+    /** 檔案清單項目 */
+    items: StorageItem[];
+    /** 下一頁游標（null 表示沒有更多結果） */
+    nextCursor: string | null;
+    /** 是否還有更多結果 */
+    hasMore: boolean;
+    /** 本次回傳的項目數量 */
+    count: number;
+}
 
 /**
+ * OrbitNebulaStoreConfig defines the configuration for a single storage disk.
+ *
+ * It supports multiple driver types, each with its own specific configuration requirements.
+ *
  * 單一磁碟配置
  * @public
  */
 type OrbitNebulaStoreConfig = {
+    /** Local filesystem driver */
     driver: 'local';
+    /** Root directory for file storage */
     root: string;
+    /** Base URL for generating public links */
     baseUrl?: string;
 } | {
+    /** Volatile in-memory driver */
     driver: 'memory';
 } | {
+    /** No-op driver for disabling storage */
     driver: 'null';
 } | {
+    /** Custom driver implementation */
     driver: 'custom';
+    /** The custom store instance */
     store: StorageStore;
 };
 /**
+ * OrbitNebulaOptions defines the global configuration for the Nebula orbit.
+ *
+ * It allows configuring multiple disks, the default disk, and how the service
+ * is exposed in the Gravito context.
+ *
  * OrbitNebula 配置選項
  * @public
  */
 interface OrbitNebulaOptions {
+    /** The name of the default disk to use when none is specified */
     default?: string;
+    /** The key used to expose the StorageManager in the context (default: 'storage') */
     exposeAs?: string;
+    /** A map of disk names to their respective configurations */
     disks?: Record<string, OrbitNebulaStoreConfig>;
+    /** Execution mode for storage hooks */
     eventsMode?: 'sync' | 'async';
     /** @deprecated 使用 disks.local 替代 */
     local?: {
@@ -131,30 +276,184 @@ interface OrbitNebulaOptions {
     provider?: StorageStore;
 }
 /**
+ * StorageHooks defines the internal interface for triggering Gravito hooks.
+ *
  * Hooks 回調介面
  * @internal
  */
 interface StorageHooks {
+    /** Applies a filter hook to a value */
     applyFilter<T>(hook: string, value: T, context?: Record<string, unknown>): Promise<T>;
+    /** Executes an action hook */
     doAction(hook: string, context?: Record<string, unknown>): Promise<void>;
 }
 
+/**
+ * StorageRepository wraps a StorageStore to provide high-level features.
+ *
+ * It implements the Repository pattern, adding cross-cutting concerns like
+ * hooks (filters and actions) to the raw store operations. This allows for
+ * global behaviors like image resizing on upload or logging on deletion.
+ *
+ * @public
+ */
 declare class StorageRepository {
     private readonly store;
     private readonly hooks?;
     constructor(store: StorageStore, hooks?: StorageHooks | undefined);
-    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    /**
+     * 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
+     */
+    put(key: string, data: Blob | Buffer | string, options?: PutOptions): Promise<void>;
+    /**
+     * 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
+     */
     get(key: string): Promise<Blob | null>;
+    /**
+     * 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
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Checks for file existence.
+     *
+     * @param key - The path to check
+     * @returns True if exists, false otherwise
+     */
     exists(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
     copy(from: string, to: string): Promise<void>;
+    /**
+     * 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
+     */
     move(from: string, to: string): Promise<void>;
+    /**
+     * Lists files using an async generator.
+     *
+     * @param prefix - Path prefix to filter by
+     * @returns Async iterable of storage items
+     * @throws {Error} If the underlying driver does not support listing
+     */
     list(prefix?: string): AsyncIterable<StorageItem>;
+    /**
+     * 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
+     */
+    listPaginated(prefix: string, options?: ListOptions): Promise<ListResult>;
+    /**
+     * Retrieves file metadata.
+     *
+     * @param key - Path of the file
+     * @returns Metadata object or null if not found
+     */
     getMetadata(key: string): Promise<StorageMetadata | null>;
+    /**
+     * 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
+     */
+    setMetadata(key: string, metadata: Record<string, string>): Promise<void>;
+    /**
+     * Generates a public URL.
+     *
+     * @param key - Path of the file
+     * @returns URL string
+     */
     getUrl(key: string): string;
+    /**
+     * 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
+     */
     getSignedUrl(key: string, expiresIn: number): Promise<string>;
+    /**
+     * 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
+     */
+    putStream(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * 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
+     */
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
 }
 
+/**
+ * StorageManager acts as the central hub for multi-disk storage management.
+ *
+ * It implements the Manager pattern to coordinate multiple storage repositories (disks).
+ * It provides a unified API that delegates to the default disk or a specifically
+ * requested disk. It also handles the lazy initialization of storage stores.
+ *
+ * @example
+ * ```typescript
+ * const manager = new StorageManager(factory, { default: 'local' });
+ * await manager.put('hello.txt', 'world'); // Uses default 'local' disk
+ * await manager.disk('s3').put('backup.zip', data); // Uses 's3' disk
+ * ```
+ *
+ * @public
+ */
 declare class StorageManager {
     private readonly storeFactory;
     private readonly options;
@@ -165,62 +464,439 @@ declare class StorageManager {
         default: string;
         prefix?: string;
     }, hooks?: StorageHooks | undefined);
+    /**
+     * 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?: string): StorageRepository;
     private resolveStore;
-    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    /**
+     * 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: string, data: Blob | Buffer | string, options?: PutOptions): Promise<void>;
+    /**
+     * 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: string): Promise<Blob | null>;
+    /**
+     * 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: string): Promise<boolean>;
+    /**
+     * 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: string): Promise<boolean>;
+    /**
+     * 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: string, to: string): Promise<void>;
+    /**
+     * 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: string, to: string): Promise<void>;
+    /**
+     * 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?: string): AsyncIterable<StorageItem>;
+    /**
+     * 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: string): Promise<StorageMetadata | null>;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string, expiresIn: number): Promise<string>;
+    /**
+     * 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: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * 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: string): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * 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: string, options?: ListOptions): Promise<ListResult>;
+    /**
+     * 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: string, metadata: Record<string, string>): Promise<void>;
 }
 
+/**
+ * LocalStore implements storage on the local filesystem.
+ *
+ * It uses the Gravito RuntimeAdapter to perform file operations, ensuring
+ * compatibility across different environments (Node.js, Bun, etc.). It includes
+ * built-in protection against path traversal attacks.
+ *
+ * @example
+ * ```typescript
+ * const store = new LocalStore('./uploads', '/public/files');
+ * await store.put('avatars/user.png', data);
+ * ```
+ *
+ * @public
+ */
 declare class LocalStore implements StorageStore {
     private readonly rootDir;
     private readonly baseUrl;
     private runtime;
     constructor(rootDir: string, baseUrl?: string);
-    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    /**
+     * 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
+     */
+    put(key: string, data: Blob | Buffer | string, options?: PutOptions): Promise<void>;
+    /**
+     * 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
+     */
     get(key: string): Promise<Blob | null>;
+    /**
+     * 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
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Checks if a file exists on the local disk.
+     *
+     * @param key - Relative path from the root directory
+     * @returns True if exists, false otherwise
+     */
     exists(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
     copy(from: string, to: string): Promise<void>;
+    /**
+     * 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
+     */
     move(from: string, to: string): Promise<void>;
-    list(prefix?: string): AsyncIterable<StorageItem>;
+    /**
+     * @internal
+     * @throws {Error} Always, as not yet implemented
+     */
+    list(_prefix?: string): AsyncIterable<StorageItem>;
+    /**
+     * Retrieves file metadata from the local filesystem.
+     *
+     * @param key - Relative path from the root directory
+     * @returns Metadata object or null if not found
+     */
     getMetadata(key: string): Promise<StorageMetadata | null>;
+    /**
+     * Generates a public URL based on the configured base URL.
+     *
+     * @param key - Relative path from the root directory
+     * @returns URL string
+     */
     getUrl(key: string): string;
+    /**
+     * 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
+     */
+    putStream(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * 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
+     */
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
     private normalizeKey;
     private resolvePath;
     private ensureDirectory;
     private guessMimeType;
 }
 
+/**
+ * MemoryStore implements a volatile, in-memory storage backend.
+ *
+ * It is primarily intended for testing, caching, or temporary data that
+ * does not need to persist across application restarts. All data is stored
+ * in a Map as Blobs.
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryStore();
+ * await store.put('test.txt', 'hello');
+ * ```
+ *
+ * @public
+ */
 declare class MemoryStore implements StorageStore {
     private files;
-    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    /**
+     * 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.)
+     */
+    put(key: string, data: Blob | Buffer | string, options?: PutOptions): Promise<void>;
+    /**
+     * Retrieves a Blob from the internal Map.
+     *
+     * @param key - Unique identifier for the file
+     * @returns The Blob content, or null if not found
+     */
     get(key: string): Promise<Blob | null>;
+    /**
+     * Removes a file from memory.
+     *
+     * @param key - Unique identifier for the file
+     * @returns True if deleted, false if not found
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Checks if a key exists in the internal Map.
+     *
+     * @param key - Unique identifier to check
+     * @returns True if exists, false otherwise
+     */
     exists(key: string): Promise<boolean>;
+    /**
+     * Copies a file within memory.
+     *
+     * @param from - Source key
+     * @param to - Destination key
+     * @throws {Error} If source file is missing
+     */
     copy(from: string, to: string): Promise<void>;
+    /**
+     * Moves a file within memory.
+     *
+     * @param from - Current key
+     * @param to - New key
+     * @throws {Error} If source file is missing
+     */
     move(from: string, to: string): Promise<void>;
+    /**
+     * Lists all files currently in memory.
+     *
+     * @param prefix - Optional key prefix to filter by
+     * @returns Async iterable of storage items
+     */
     list(prefix?: string): AsyncIterable<StorageItem>;
+    /**
+     * Retrieves metadata for an in-memory file.
+     *
+     * @param key - Unique identifier for the file
+     * @returns Metadata object or null if not found
+     */
     getMetadata(key: string): Promise<StorageMetadata | 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: string): string;
+    /**
+     * 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
+     */
+    putStream(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * 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
+     */
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * 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
+     */
+    setMetadata(key: string, metadata: Record<string, string>): Promise<void>;
+    /**
+     * 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
+     */
+    listPaginated(prefix?: string, options?: ListOptions): Promise<ListResult>;
 }
 
+/**
+ * NullStore implements the Null Object pattern for storage.
+ *
+ * It provides a no-op implementation of the StorageStore interface. All write
+ * operations succeed silently without doing anything, and all read operations
+ * return null or empty results. This is useful for disabling storage without
+ * changing application logic.
+ *
+ * @example
+ * ```typescript
+ * const store = new NullStore();
+ * await store.put('anything', 'data'); // Does nothing
+ * ```
+ *
+ * @public
+ */
 declare class NullStore implements StorageStore {
+    /**
+     * No-op: does not store any data.
+     */
     put(_key: string, _data: Blob | Buffer | string): Promise<void>;
+    /**
+     * Always returns null.
+     */
     get(_key: string): Promise<Blob | null>;
+    /**
+     * Always returns false.
+     */
     delete(_key: string): Promise<boolean>;
+    /**
+     * Always returns false.
+     */
     exists(_key: string): Promise<boolean>;
+    /**
+     * No-op: does not copy anything.
+     */
     copy(_from: string, _to: string): Promise<void>;
+    /**
+     * No-op: does not move anything.
+     */
     move(_from: string, _to: string): Promise<void>;
+    /**
+     * Always yields nothing.
+     */
     list(_prefix?: string): AsyncIterable<StorageItem>;
+    /**
+     * Always returns null.
+     */
     getMetadata(_key: string): Promise<StorageMetadata | null>;
+    /**
+     * Generates a dummy URL starting with /null/.
+     */
     getUrl(key: string): string;
 }
 
@@ -232,7 +908,9 @@ type OrbitStorageOptions = OrbitNebulaOptions;
 /**
  * OrbitNebula provides a unified file storage abstraction for Gravito.
  *
- * It supports multiple backends (local, S3, etc.) via the StorageManager.
+ * It implements the Galaxy Architecture's Orbit pattern, acting as a bridge between
+ * the PlanetCore micro-kernel and various storage backends. It manages the lifecycle
+ * of the StorageManager and integrates with the core's hook system.
  *
  * @example
  * ```typescript
@@ -246,33 +924,51 @@ type OrbitStorageOptions = OrbitNebulaOptions;
  * ```
  *
  * @public
- * @since 3.0.0 (Refactored in 4.0.0)
  */
 declare class OrbitNebula implements GravitoOrbit {
     private options?;
     private manager?;
     constructor(options?: OrbitNebulaOptions | undefined);
     /**
-     * Install storage service into PlanetCore.
+     * Bootstraps the storage service and registers it with PlanetCore.
+     *
+     * 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.
+     * @param core - The PlanetCore instance to install into
+     * @throws {Error} If configuration is missing or default disk cannot be initialized
      */
     install(core: PlanetCore): void;
     /**
-     * Get the installed StorageManager instance.
+     * Retrieves the initialized StorageManager instance.
      *
-     * @returns The StorageManager instance.
-     * @throws {Error} If not installed.
+     * 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(): StorageManager;
     private createStoreFactory;
 }
 /**
- * Functional API for installing OrbitNebula.
+ * Factory function for quick OrbitNebula installation.
+ *
+ * Provides a functional approach to adding storage capabilities to a Gravito application.
  *
- * @param core - The PlanetCore instance.
- * @param options - Storage options.
- * @returns The StorageManager instance.
+ * @param core - The PlanetCore instance
+ * @param options - Storage configuration options
+ * @returns The initialized StorageManager instance
+ *
+ * @example
+ * ```typescript
+ * const storage = orbitStorage(core, {
+ *   default: 'local',
+ *   disks: {
+ *     local: { driver: 'local', root: './uploads' }
+ *   }
+ * });
+ * ```
  */
 declare function orbitStorage(core: PlanetCore, options: OrbitNebulaOptions): StorageManager;
 /** @deprecated Use OrbitNebula instead */
@@ -284,4 +980,4 @@ declare module '@gravito/core' {
     }
 }
 
-export { LocalStore as LocalStorageProvider, LocalStore, MemoryStore, NullStore, OrbitNebula, type OrbitNebulaOptions, type OrbitNebulaStoreConfig, OrbitStorage, type OrbitStorageOptions, type StorageHooks, type StorageItem, StorageManager, type StorageMetadata, type StorageProvider, StorageRepository, type StorageStore, orbitStorage as default };
+export { type ListOptions, type ListResult, LocalStore as LocalStorageProvider, LocalStore, MemoryStore, NullStore, OrbitNebula, type OrbitNebulaOptions, type OrbitNebulaStoreConfig, OrbitStorage, type OrbitStorageOptions, type PutOptions, type StorageHooks, type StorageItem, StorageManager, type StorageMetadata, type StorageProvider, StorageRepository, type StorageStore, orbitStorage as default };