@gravito/nebula 3.0.1 → 4.0.0

package/dist/index.d.ts

@@ -1,176 +1,287 @@
 import { PlanetCore, GravitoOrbit } from '@gravito/core';
 
 /**
- * Interface for a file storage provider.
+ * 底層儲存介面
  *
- * All storage backends (Local, S3, Cloudinary, etc.) must implement this interface.
- * It provides a consistent API for file operations across different runtimes
- * and cloud providers.
+ * 所有儲存後端 (Local, S3, GCS 等) 必須實作此介面
  *
  * @public
- * @since 3.0.0
+ * @since 4.0.0
  */
-interface StorageProvider {
+interface StorageStore {
     /**
-     * Save data to the storage backend.
-     *
-     * @param key - Unique identifier or path for the file (e.g., 'avatars/user1.jpg').
-     * @param data - The file content as a Blob, Buffer, or string.
-     * @returns A promise that resolves when the file is successfully saved.
+     * 儲存檔案
+     * @param key - 檔案路徑 (例如: 'avatars/user1.jpg')
+     * @param data - 檔案內容
      */
     put(key: string, data: Blob | Buffer | string): Promise<void>;
     /**
-     * Retrieve a file from the storage backend.
-     *
-     * @param key - The file identifier or path.
-     * @returns The file as a Blob, or null if the file does not exist.
+     * 讀取檔案
+     * @param key - 檔案路徑
+     * @returns 檔案內容，若不存在則回傳 null
      */
     get(key: string): Promise<Blob | null>;
     /**
-     * Remove a file from the storage backend.
-     *
-     * @param key - The file identifier or path to delete.
-     * @returns A promise that resolves when the file is deleted.
+     * 刪除檔案
+     * @param key - 檔案路徑
+     * @returns 是否成功刪除 (若檔案不存在則回傳 false)
      */
-    delete(key: string): Promise<void>;
+    delete(key: string): Promise<boolean>;
     /**
-     * Get a publicly accessible URL for the given file key.
-     *
-     * Note: This may return a relative URL for local storage or a full URL
-     * for cloud storage providers.
-     *
-     * @param key - The file identifier or path.
-     * @returns The public URL string.
+     * 檢查檔案是否存在
+     * @param key - 檔案路徑
      */
-    getUrl(key: string): string;
-}
-/**
- * Local file system storage provider.
- *
- * Stores files on the local disk using the configured root directory and
- * resolves URLs using a provided base URL prefix.
- *
- * @example
- * ```typescript
- * const local = new LocalStorageProvider('./storage', '/files');
- * await local.put('hello.txt', 'Hello World');
- * console.log(local.getUrl('hello.txt')); // "/files/hello.txt"
- * ```
- *
- * @public
- * @since 3.0.0
- */
-declare class LocalStorageProvider implements StorageProvider {
-    private rootDir;
-    private baseUrl;
-    private runtime;
+    exists(key: string): Promise<boolean>;
     /**
-     * Create a new LocalStorageProvider.
-     *
-     * @param rootDir - The absolute path to the local storage directory.
-     * @param baseUrl - The public URL path for accessing stored files (e.g., '/storage').
+     * 複製檔案
+     * @param from - 來源路徑
+     * @param to - 目標路徑
      */
-    constructor(rootDir: string, baseUrl?: string);
+    copy(from: string, to: string): Promise<void>;
     /**
-     * Write data to the local disk.
+     * 移動/重命名檔案
+     * @param from - 來源路徑
+     * @param to - 目標路徑
      */
-    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
     /**
-     * Read data from the local disk.
+     * 列出檔案 (可選實作，需要 RuntimeAdapter 支援)
+     * @param prefix - 路徑前綴 (例如: 'uploads/')
      */
-    get(key: string): Promise<Blob | null>;
+    list?(prefix?: string): AsyncIterable<StorageItem>;
     /**
-     * Delete a file from the local disk.
+     * 取得檔案元資料
+     * @param key - 檔案路徑
      */
-    delete(key: string): Promise<void>;
+    getMetadata(key: string): Promise<StorageMetadata | null>;
     /**
-     * Resolve the public URL for a locally stored file.
+     * 取得公開 URL
+     * @param key - 檔案路徑
      */
     getUrl(key: string): string;
-    private normalizeKey;
-    private resolveKeyPath;
+    /**
+     * 取得有時效的簽名 URL (可選實作)
+     * @param key - 檔案路徑
+     * @param expiresIn - 過期時間 (秒)
+     */
+    getSignedUrl?(key: string, expiresIn: number): Promise<string>;
 }
 /**
- * Configuration options for the Nebula Storage Orbit.
- *
+ * 檔案元資料
+ * @public
+ */
+interface StorageMetadata {
+    /** 檔案路徑 */
+    key: string;
+    /** 檔案大小 (bytes) */
+    size: number;
+    /** MIME 類型 */
+    mimeType?: string;
+    /** 最後修改時間 */
+    lastModified?: Date;
+    /** ETag (用於快取驗證) */
+    etag?: string;
+}
+/**
+ * 檔案清單項目
+ * @public
+ */
+interface StorageItem {
+    /** 檔案路徑 */
+    key: string;
+    /** 是否為目錄 */
+    isDirectory: boolean;
+    /** 檔案大小 (目錄為 undefined) */
+    size?: number;
+    /** 最後修改時間 */
+    lastModified?: Date;
+}
+
+/**
+ * 單一磁碟配置
+ * @public
+ */
+type OrbitNebulaStoreConfig = {
+    driver: 'local';
+    root: string;
+    baseUrl?: string;
+} | {
+    driver: 'memory';
+} | {
+    driver: 'null';
+} | {
+    driver: 'custom';
+    store: StorageStore;
+};
+/**
+ * OrbitNebula 配置選項
  * @public
- * @since 3.0.0
  */
 interface OrbitNebulaOptions {
-    /**
-     * Custom storage provider instance (e.g., S3Provider).
-     * If not provided, a LocalStorageProvider will be created if `local` options are set.
-     */
-    provider?: StorageProvider;
-    /**
-     * The key used to expose the storage service in the request context.
-     * @default 'storage'
-     */
+    default?: string;
     exposeAs?: string;
-    /** Configuration for the default LocalStorageProvider. */
+    disks?: Record<string, OrbitNebulaStoreConfig>;
+    eventsMode?: 'sync' | 'async';
+    /** @deprecated 使用 disks.local 替代 */
     local?: {
-        /** Absolute or relative path to the root directory on disk. */
         root: string;
-        /** Base URL prefix for serving files (e.g., '/public/storage'). @default '/storage' */
         baseUrl?: string;
     };
+    /** @deprecated 使用 disks[name] = { driver: 'custom', store } 替代 */
+    provider?: StorageStore;
+}
+/**
+ * Hooks 回調介面
+ * @internal
+ */
+interface StorageHooks {
+    applyFilter<T>(hook: string, value: T, context?: Record<string, unknown>): Promise<T>;
+    doAction(hook: string, context?: Record<string, unknown>): Promise<void>;
+}
+
+declare class StorageRepository {
+    private readonly store;
+    private readonly hooks?;
+    constructor(store: StorageStore, hooks?: StorageHooks | undefined);
+    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    get(key: string): Promise<Blob | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    list(prefix?: string): AsyncIterable<StorageItem>;
+    getMetadata(key: string): Promise<StorageMetadata | null>;
+    getUrl(key: string): string;
+    getSignedUrl(key: string, expiresIn: number): Promise<string>;
+}
+
+declare class StorageManager {
+    private readonly storeFactory;
+    private readonly options;
+    private readonly hooks?;
+    private stores;
+    private repositories;
+    constructor(storeFactory: (name: string) => StorageStore, options: {
+        default: string;
+        prefix?: string;
+    }, hooks?: StorageHooks | undefined);
+    disk(name?: string): StorageRepository;
+    private resolveStore;
+    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    get(key: string): Promise<Blob | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    list(prefix?: string): AsyncIterable<StorageItem>;
+    getMetadata(key: string): Promise<StorageMetadata | null>;
+    getUrl(key: string): string;
+    getSignedUrl(key: string, expiresIn: number): Promise<string>;
 }
+
+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>;
+    get(key: string): Promise<Blob | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    list(prefix?: string): AsyncIterable<StorageItem>;
+    getMetadata(key: string): Promise<StorageMetadata | null>;
+    getUrl(key: string): string;
+    private normalizeKey;
+    private resolvePath;
+    private ensureDirectory;
+    private guessMimeType;
+}
+
+declare class MemoryStore implements StorageStore {
+    private files;
+    put(key: string, data: Blob | Buffer | string): Promise<void>;
+    get(key: string): Promise<Blob | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    list(prefix?: string): AsyncIterable<StorageItem>;
+    getMetadata(key: string): Promise<StorageMetadata | null>;
+    getUrl(key: string): string;
+}
+
+declare class NullStore implements StorageStore {
+    put(_key: string, _data: Blob | Buffer | string): Promise<void>;
+    get(_key: string): Promise<Blob | null>;
+    delete(_key: string): Promise<boolean>;
+    exists(_key: string): Promise<boolean>;
+    copy(_from: string, _to: string): Promise<void>;
+    move(_from: string, _to: string): Promise<void>;
+    list(_prefix?: string): AsyncIterable<StorageItem>;
+    getMetadata(_key: string): Promise<StorageMetadata | null>;
+    getUrl(key: string): string;
+}
+
+/** @deprecated Use StorageStore instead */
+type StorageProvider = StorageStore;
+
 /** @deprecated Use OrbitNebulaOptions instead */
 type OrbitStorageOptions = OrbitNebulaOptions;
 /**
  * OrbitNebula provides a unified file storage abstraction for Gravito.
  *
- * It supports multiple backends (local, S3, etc.) and provides a consistent API
- * for file operations. It also integrates with Gravito's hook system for
- * filtering uploads (`storage:upload`) and reacting to events (`storage:uploaded`).
+ * It supports multiple backends (local, S3, etc.) via the StorageManager.
  *
  * @example
  * ```typescript
  * const nebula = new OrbitNebula({
- *   local: { root: './storage', baseUrl: '/public' }
+ *   default: 'local',
+ *   disks: {
+ *     local: { driver: 'local', root: './uploads' }
+ *   }
  * });
  * core.addOrbit(nebula);
- *
- * // Usage in controller
- * const storage = c.get('storage');
- * await storage.put('example.txt', 'Content');
  * ```
  *
  * @public
- * @since 3.0.0
+ * @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.
      *
      * @param core - The PlanetCore instance.
-     * @throws {Error} If configuration or provider is missing.
      */
     install(core: PlanetCore): void;
+    /**
+     * Get the installed StorageManager instance.
+     *
+     * @returns The StorageManager instance.
+     * @throws {Error} If not installed.
+     */
+    getStorage(): StorageManager;
+    private createStoreFactory;
 }
 /**
  * Functional API for installing OrbitNebula.
  *
  * @param core - The PlanetCore instance.
  * @param options - Storage options.
- * @returns The configured storage provider wrapper.
- * @throws {Error} If provider is not configured.
+ * @returns The StorageManager instance.
  */
-declare function orbitStorage(core: PlanetCore, options: OrbitNebulaOptions): {
-    put: (key: string, data: Blob | Buffer | string) => Promise<void>;
-    get: (key: string) => Promise<Blob | null>;
-    delete: (key: string) => Promise<void>;
-    getUrl: (key: string) => string;
-};
+declare function orbitStorage(core: PlanetCore, options: OrbitNebulaOptions): StorageManager;
 /** @deprecated Use OrbitNebula instead */
 declare const OrbitStorage: typeof OrbitNebula;
 declare module '@gravito/core' {
     interface GravitoVariables {
         /** File storage service */
-        storage: StorageProvider;
+        storage: StorageManager;
     }
 }
 
-export { LocalStorageProvider, OrbitNebula, type OrbitNebulaOptions, OrbitStorage, type OrbitStorageOptions, type StorageProvider, orbitStorage as default };
+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 };