@gravito/nebula 3.0.0 → 3.0.1

package/dist/index.cjs

@@ -36,18 +36,15 @@ var LocalStorageProvider = class {
   /**
    * Create a new LocalStorageProvider.
    *
-   * @param rootDir - The root directory for storage.
-   * @param baseUrl - The base URL for accessing stored files.
+   * @param rootDir - The absolute path to the local storage directory.
+   * @param baseUrl - The public URL path for accessing stored files (e.g., '/storage').
    */
   constructor(rootDir, baseUrl = "/storage") {
     this.rootDir = rootDir;
     this.baseUrl = baseUrl;
   }
   /**
-   * Store data in a file.
-   *
-   * @param key - The storage key (path).
-   * @param data - The data to store.
+   * Write data to the local disk.
    */
   async put(key, data) {
     const path = this.resolveKeyPath(key);
@@ -58,10 +55,7 @@ var LocalStorageProvider = class {
     await this.runtime.writeFile(path, data);
   }
   /**
-   * Retrieve a file.
-   *
-   * @param key - The storage key.
-   * @returns A promise resolving to the file Blob or null if not found.
+   * Read data from the local disk.
    */
   async get(key) {
     const path = this.resolveKeyPath(key);
@@ -71,18 +65,13 @@ var LocalStorageProvider = class {
     return await this.runtime.readFileAsBlob(path);
   }
   /**
-   * Delete a file.
-   *
-   * @param key - The storage key.
+   * Delete a file from the local disk.
    */
   async delete(key) {
     await this.runtime.deleteFile(this.resolveKeyPath(key));
   }
   /**
-   * Get the public URL for a file.
-   *
-   * @param key - The storage key.
-   * @returns The public URL string.
+   * Resolve the public URL for a locally stored file.
    */
   getUrl(key) {
     const safeKey = this.normalizeKey(key);
@@ -149,6 +138,7 @@ var OrbitNebula = class {
       delete: (key) => provider?.delete(key),
       getUrl: (key) => provider?.getUrl(key)
     };
+    core.container.instance(exposeAs, storageService);
     core.adapter.use("*", async (c, next) => {
       c.set(exposeAs, storageService);
       await next();

package/dist/index.d.cts

@@ -1,13 +1,64 @@
 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.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface StorageProvider {
+    /**
+     * 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.
+     */
     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.
+     */
     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.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * 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.
+     */
     getUrl(key: string): string;
 }
 /**
- * Local storage provider implementation.
+ * 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;
@@ -16,54 +67,77 @@ declare class LocalStorageProvider implements StorageProvider {
     /**
      * Create a new LocalStorageProvider.
      *
-     * @param rootDir - The root directory for storage.
-     * @param baseUrl - The base URL for accessing stored files.
+     * @param rootDir - The absolute path to the local storage directory.
+     * @param baseUrl - The public URL path for accessing stored files (e.g., '/storage').
      */
     constructor(rootDir: string, baseUrl?: string);
     /**
-     * Store data in a file.
-     *
-     * @param key - The storage key (path).
-     * @param data - The data to store.
+     * Write data to the local disk.
      */
     put(key: string, data: Blob | Buffer | string): Promise<void>;
     /**
-     * Retrieve a file.
-     *
-     * @param key - The storage key.
-     * @returns A promise resolving to the file Blob or null if not found.
+     * Read data from the local disk.
      */
     get(key: string): Promise<Blob | null>;
     /**
-     * Delete a file.
-     *
-     * @param key - The storage key.
+     * Delete a file from the local disk.
      */
     delete(key: string): Promise<void>;
     /**
-     * Get the public URL for a file.
-     *
-     * @param key - The storage key.
-     * @returns The public URL string.
+     * Resolve the public URL for a locally stored file.
      */
     getUrl(key: string): string;
     private normalizeKey;
     private resolveKeyPath;
 }
+/**
+ * Configuration options for the Nebula Storage Orbit.
+ *
+ * @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'
+     */
     exposeAs?: string;
+    /** Configuration for the default LocalStorageProvider. */
     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 Use OrbitNebulaOptions instead */
 type OrbitStorageOptions = OrbitNebulaOptions;
 /**
- * OrbitNebula - Storage Orbit
+ * OrbitNebula provides a unified file storage abstraction for Gravito.
  *
- * Provides file storage functionality for Gravito applications.
+ * 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`).
+ *
+ * @example
+ * ```typescript
+ * const nebula = new OrbitNebula({
+ *   local: { root: './storage', baseUrl: '/public' }
+ * });
+ * core.addOrbit(nebula);
+ *
+ * // Usage in controller
+ * const storage = c.get('storage');
+ * await storage.put('example.txt', 'Content');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class OrbitNebula implements GravitoOrbit {
     private options?;
@@ -92,5 +166,11 @@ declare function orbitStorage(core: PlanetCore, options: OrbitNebulaOptions): {
 };
 /** @deprecated Use OrbitNebula instead */
 declare const OrbitStorage: typeof OrbitNebula;
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** File storage service */
+        storage: StorageProvider;
+    }
+}
 
 export { LocalStorageProvider, OrbitNebula, type OrbitNebulaOptions, OrbitStorage, type OrbitStorageOptions, type StorageProvider, orbitStorage as default };

package/dist/index.d.ts

@@ -1,13 +1,64 @@
 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.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface StorageProvider {
+    /**
+     * 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.
+     */
     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.
+     */
     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.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * 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.
+     */
     getUrl(key: string): string;
 }
 /**
- * Local storage provider implementation.
+ * 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;
@@ -16,54 +67,77 @@ declare class LocalStorageProvider implements StorageProvider {
     /**
      * Create a new LocalStorageProvider.
      *
-     * @param rootDir - The root directory for storage.
-     * @param baseUrl - The base URL for accessing stored files.
+     * @param rootDir - The absolute path to the local storage directory.
+     * @param baseUrl - The public URL path for accessing stored files (e.g., '/storage').
      */
     constructor(rootDir: string, baseUrl?: string);
     /**
-     * Store data in a file.
-     *
-     * @param key - The storage key (path).
-     * @param data - The data to store.
+     * Write data to the local disk.
      */
     put(key: string, data: Blob | Buffer | string): Promise<void>;
     /**
-     * Retrieve a file.
-     *
-     * @param key - The storage key.
-     * @returns A promise resolving to the file Blob or null if not found.
+     * Read data from the local disk.
      */
     get(key: string): Promise<Blob | null>;
     /**
-     * Delete a file.
-     *
-     * @param key - The storage key.
+     * Delete a file from the local disk.
      */
     delete(key: string): Promise<void>;
     /**
-     * Get the public URL for a file.
-     *
-     * @param key - The storage key.
-     * @returns The public URL string.
+     * Resolve the public URL for a locally stored file.
      */
     getUrl(key: string): string;
     private normalizeKey;
     private resolveKeyPath;
 }
+/**
+ * Configuration options for the Nebula Storage Orbit.
+ *
+ * @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'
+     */
     exposeAs?: string;
+    /** Configuration for the default LocalStorageProvider. */
     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 Use OrbitNebulaOptions instead */
 type OrbitStorageOptions = OrbitNebulaOptions;
 /**
- * OrbitNebula - Storage Orbit
+ * OrbitNebula provides a unified file storage abstraction for Gravito.
  *
- * Provides file storage functionality for Gravito applications.
+ * 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`).
+ *
+ * @example
+ * ```typescript
+ * const nebula = new OrbitNebula({
+ *   local: { root: './storage', baseUrl: '/public' }
+ * });
+ * core.addOrbit(nebula);
+ *
+ * // Usage in controller
+ * const storage = c.get('storage');
+ * await storage.put('example.txt', 'Content');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class OrbitNebula implements GravitoOrbit {
     private options?;
@@ -92,5 +166,11 @@ declare function orbitStorage(core: PlanetCore, options: OrbitNebulaOptions): {
 };
 /** @deprecated Use OrbitNebula instead */
 declare const OrbitStorage: typeof OrbitNebula;
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** File storage service */
+        storage: StorageProvider;
+    }
+}
 
 export { LocalStorageProvider, OrbitNebula, type OrbitNebulaOptions, OrbitStorage, type OrbitStorageOptions, type StorageProvider, orbitStorage as default };

package/dist/index.js

@@ -11,18 +11,15 @@ var LocalStorageProvider = class {
   /**
    * Create a new LocalStorageProvider.
    *
-   * @param rootDir - The root directory for storage.
-   * @param baseUrl - The base URL for accessing stored files.
+   * @param rootDir - The absolute path to the local storage directory.
+   * @param baseUrl - The public URL path for accessing stored files (e.g., '/storage').
    */
   constructor(rootDir, baseUrl = "/storage") {
     this.rootDir = rootDir;
     this.baseUrl = baseUrl;
   }
   /**
-   * Store data in a file.
-   *
-   * @param key - The storage key (path).
-   * @param data - The data to store.
+   * Write data to the local disk.
    */
   async put(key, data) {
     const path = this.resolveKeyPath(key);
@@ -33,10 +30,7 @@ var LocalStorageProvider = class {
     await this.runtime.writeFile(path, data);
   }
   /**
-   * Retrieve a file.
-   *
-   * @param key - The storage key.
-   * @returns A promise resolving to the file Blob or null if not found.
+   * Read data from the local disk.
    */
   async get(key) {
     const path = this.resolveKeyPath(key);
@@ -46,18 +40,13 @@ var LocalStorageProvider = class {
     return await this.runtime.readFileAsBlob(path);
   }
   /**
-   * Delete a file.
-   *
-   * @param key - The storage key.
+   * Delete a file from the local disk.
    */
   async delete(key) {
     await this.runtime.deleteFile(this.resolveKeyPath(key));
   }
   /**
-   * Get the public URL for a file.
-   *
-   * @param key - The storage key.
-   * @returns The public URL string.
+   * Resolve the public URL for a locally stored file.
    */
   getUrl(key) {
     const safeKey = this.normalizeKey(key);
@@ -124,6 +113,7 @@ var OrbitNebula = class {
       delete: (key) => provider?.delete(key),
       getUrl: (key) => provider?.getUrl(key)
     };
+    core.container.instance(exposeAs, storageService);
     core.adapter.use("*", async (c, next) => {
       c.set(exposeAs, storageService);
       await next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/nebula",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "publishConfig": {
     "access": "public"
   },