@gravito/nebula 4.0.0 → 4.1.0

package/dist/index.cjs

@@ -38,13 +38,32 @@ var StorageRepository = class {
     this.store = store;
     this.hooks = hooks;
   }
-  async put(key, data) {
-    const finalData = this.hooks ? await this.hooks.applyFilter("storage:upload", data, { key }) : data;
-    await this.store.put(key, finalData);
+  /**
+   * 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 });
+      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) {
@@ -56,6 +75,14 @@ var StorageRepository = class {
     }
     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) {
@@ -63,39 +90,168 @@ var StorageRepository = class {
     }
     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 });
     }
   }
+  /**
+   * 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
+   */
   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
@@ -107,6 +263,16 @@ var StorageManager = class {
   }
   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)) {
@@ -121,36 +287,156 @@ var StorageManager = class {
     }
     return this.stores.get(name);
   }
-  put(key, data) {
-    return this.disk().put(key, data);
+  /**
+   * 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
@@ -163,11 +449,28 @@ var LocalStore = class {
     this.baseUrl = baseUrl;
   }
   runtime = (0, import_core.getRuntimeAdapter)();
-  async put(key, data) {
+  /**
+   * 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, options) {
     const path = this.resolvePath(key);
     await this.ensureDirectory(path);
     await this.runtime.writeFile(path, data);
   }
+  /**
+   * 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) {
     if (!await this.exists(key)) {
       return null;
@@ -175,6 +478,13 @@ var LocalStore = class {
     const path = this.resolvePath(key);
     return this.runtime.readFileAsBlob(path);
   }
+  /**
+   * 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) {
     if (!await this.exists(key)) {
       return false;
@@ -183,10 +493,23 @@ var LocalStore = class {
     await this.runtime.deleteFile(path);
     return true;
   }
+  /**
+   * 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) {
@@ -194,15 +517,32 @@ var LocalStore = class {
     }
     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);
   }
-  list(prefix = "") {
+  /**
+   * @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;
@@ -216,10 +556,63 @@ var LocalStore = class {
       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("[LocalStore] Invalid storage key: empty or contains null byte.");
@@ -269,34 +662,70 @@ var LocalStore = class {
 // src/stores/MemoryStore.ts
 var MemoryStore = class {
   files = /* @__PURE__ */ new Map();
-  async put(key, data) {
+  /**
+   * 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]);
+      blob = new Blob([data], { type: options?.contentType });
     } else {
-      blob = new Blob([new Uint8Array(data)]);
+      blob = new Blob([new Uint8Array(data)], { type: options?.contentType });
     }
     this.files.set(key, {
       data: blob,
+      options,
       metadata: {
         key,
         size: blob.size,
-        mimeType: blob.type || "application/octet-stream",
-        lastModified: /* @__PURE__ */ new Date()
+        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) {
@@ -307,10 +736,23 @@ var MemoryStore = class {
       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)) {
@@ -323,36 +765,182 @@ var MemoryStore = class {
       }
     }
   }
+  /**
+   * 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}`;
   }
@@ -365,9 +953,13 @@ var OrbitNebula = class {
   }
   manager;
   /**
-   * 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) {
     const config = this.options || core.config.get("storage");
@@ -380,9 +972,13 @@ var OrbitNebula = class {
     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";
+      if (config.local) {
+        defaultDisk = "local";
+      } else if (config.provider) {
+        defaultDisk = "custom";
+      } else {
+        defaultDisk = "local";
+      }
     }
     const managerOptions = {
       default: defaultDisk
@@ -403,10 +999,13 @@ var OrbitNebula = class {
     core.hooks.doAction("storage:init", { manager: this.manager });
   }
   /**
-   * Get the installed StorageManager instance.
+   * Retrieves the initialized StorageManager instance.
+   *
+   * Use this to access storage operations directly from the orbit instance
+   * after it has been installed.
    *
-   * @returns The StorageManager instance.
-   * @throws {Error} If not installed.
+   * @returns The active StorageManager instance
+   * @throws {Error} If called before the orbit is installed
    */
   getStorage() {
     if (!this.manager) {