@quatrain/storage-supabase 1.2.2 → 1.2.4

package/dist/SupabaseStorageAdapter.d.ts

@@ -1,24 +1,115 @@
 import { AbstractStorageAdapter, FileType, FileResponseLinkType, StorageParameters, DownloadFileMetaType } from '@quatrain/storage';
 import { Readable, Stream } from 'node:stream';
 import { StorageClient } from '@supabase/storage-js';
+/**
+ * Storage adapter implementation targeting Supabase Storage.
+ * Interfaces with the `@supabase/storage-js` client to manage buckets,
+ * secure signed URLs, and file uploads.
+ */
 export declare class SupabaseStorageAdapter extends AbstractStorageAdapter {
     protected _client: StorageClient;
     constructor(params: StorageParameters);
+    /**
+     * Exposes the underlying Supabase `StorageClient` instance.
+     *
+     * @returns The storage client.
+     */
     getDriver(): StorageClient;
+    /**
+     * Retrieves file metadata. Currently acts as a passthrough for Supabase.
+     *
+     * @param file - Target file footprint.
+     * @returns The file metadata.
+     */
     getMetaData(file: FileType): Promise<FileType>;
+    /**
+     * Validates backend connectivity by listing available buckets in the Supabase project.
+     *
+     * @returns True if connected.
+     */
     test(): Promise<boolean>;
+    /**
+     * Helper converting a node stream to a Buffer, essential for Blob creation.
+     *
+     * @param stream - The input stream.
+     * @returns A promise resolving to the concatenated Buffer.
+     */
     streamToBuffer(stream: Stream): Promise<Buffer>;
+    /**
+     * Internal helper to convert a Buffer into a native ArrayBuffer.
+     *
+     * @param buffer - The raw Buffer.
+     * @returns The ArrayBuffer representation.
+     */
     toArrayBuffer(buffer: Buffer): ArrayBuffer;
+    /**
+     * Uploads a local file path or stream to the Supabase storage bucket.
+     *
+     * @param file - Target file schema.
+     * @param stream - Readable stream or string path to the file.
+     * @returns A promise resolving to the created file footprint.
+     * @throws {Error} If upload is rejected.
+     */
     create(file: FileType, stream: Readable | string): Promise<FileType>;
+    /**
+     * Copies a file to a new destination key natively on the Supabase backend.
+     *
+     * @param file - Original file.
+     * @param destFile - Target destination.
+     */
     copy(file: FileType, destFile: FileType): Promise<void>;
+    /**
+     * Moves/Renames an existing file natively within Supabase Storage.
+     *
+     * @param file - The source file.
+     * @param destFile - The target file.
+     * @returns A promise resolving to the newly placed destination file.
+     * @throws {Error} If the move operation fails.
+     */
     move(file: FileType, destFile: FileType): Promise<FileType>;
-    _getUrl(file: FileType, expiresIn?: number, action?: any, extra?: any): Promise<{
+    /**
+     * Generates a secure, temporary GET link to access the object remotely.
+     *
+     * @param file - The file footprint.
+     * @param expiresIn - URL expiration in seconds.
+     * @param action - Intended action context.
+     * @param extra - Optional parameters (e.g. cache configurations).
+     * @returns A promise resolving to the signed URL payload.
+     * @throws {Error} If signature creation fails.
+     */
+    getUrl(file: FileType, expiresIn?: number, action?: any, extra?: any): Promise<{
         url: string;
         expiresIn: number;
     }>;
+    /**
+     * Permanently removes the file from the Supabase bucket.
+     *
+     * @param file - Target file.
+     * @returns True upon success.
+     */
     delete(file: FileType): Promise<boolean>;
+    /**
+     * Downloads the file content to a temporary location and returns a Readable stream.
+     *
+     * @param file - File to read.
+     * @returns The content as a stream.
+     */
     getReadable(file: FileType): Promise<Readable>;
+    /**
+     * Fetches and pipes the file content into the given response stream.
+     *
+     * @param file - File to stream.
+     * @param res - Writable stream or HTTP response object.
+     * @returns The piped stream instance.
+     */
     stream(file: FileType, res: any): Promise<any>;
+    /**
+     * Downloads the file directly, either returning the blob content or saving it locally.
+     *
+     * @param file - File footprint.
+     * @param meta - Options dictating save path or return format.
+     * @returns A promise resolving to the blob or local file path.
+     */
     download(file: FileType, meta: DownloadFileMetaType): Promise<string | Blob>;
     /**
      * Get signed upload url for file

package/dist/SupabaseStorageAdapter.js

@@ -19,6 +19,11 @@ const storage_js_1 = require("@supabase/storage-js");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_fs_1 = __importDefault(require("node:fs"));
+/**
+ * Storage adapter implementation targeting Supabase Storage.
+ * Interfaces with the `@supabase/storage-js` client to manage buckets,
+ * secure signed URLs, and file uploads.
+ */
 class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
     constructor(params) {
         super(params);
@@ -28,12 +33,28 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
         });
         storage_1.Storage.info(`[SSA] Supabase Storage Adapter initialized`);
     }
+    /**
+     * Exposes the underlying Supabase `StorageClient` instance.
+     *
+     * @returns The storage client.
+     */
     getDriver() {
         return this._client;
     }
+    /**
+     * Retrieves file metadata. Currently acts as a passthrough for Supabase.
+     *
+     * @param file - Target file footprint.
+     * @returns The file metadata.
+     */
     getMetaData(file) {
         return new Promise(() => file);
     }
+    /**
+     * Validates backend connectivity by listing available buckets in the Supabase project.
+     *
+     * @returns True if connected.
+     */
     test() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -51,6 +72,12 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             }
         });
     }
+    /**
+     * Helper converting a node stream to a Buffer, essential for Blob creation.
+     *
+     * @param stream - The input stream.
+     * @returns A promise resolving to the concatenated Buffer.
+     */
     streamToBuffer(stream) {
         return __awaiter(this, void 0, void 0, function* () {
             return new Promise((resolve, reject) => {
@@ -61,6 +88,12 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             });
         });
     }
+    /**
+     * Internal helper to convert a Buffer into a native ArrayBuffer.
+     *
+     * @param buffer - The raw Buffer.
+     * @returns The ArrayBuffer representation.
+     */
     toArrayBuffer(buffer) {
         const arrayBuffer = new ArrayBuffer(buffer.length);
         const view = new Uint8Array(arrayBuffer);
@@ -69,6 +102,14 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
         }
         return arrayBuffer;
     }
+    /**
+     * Uploads a local file path or stream to the Supabase storage bucket.
+     *
+     * @param file - Target file schema.
+     * @param stream - Readable stream or string path to the file.
+     * @returns A promise resolving to the created file footprint.
+     * @throws {Error} If upload is rejected.
+     */
     create(file, stream) {
         return __awaiter(this, void 0, void 0, function* () {
             storage_1.Storage.info(`[SSA] Uploading ${file.ref} to ${file.bucket}`);
@@ -105,6 +146,12 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             return file;
         });
     }
+    /**
+     * Copies a file to a new destination key natively on the Supabase backend.
+     *
+     * @param file - Original file.
+     * @param destFile - Target destination.
+     */
     copy(file, destFile) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -119,6 +166,14 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             }
         });
     }
+    /**
+     * Moves/Renames an existing file natively within Supabase Storage.
+     *
+     * @param file - The source file.
+     * @param destFile - The target file.
+     * @returns A promise resolving to the newly placed destination file.
+     * @throws {Error} If the move operation fails.
+     */
     move(file, destFile) {
         return __awaiter(this, void 0, void 0, function* () {
             storage_1.Storage.info(`Moving file ${file.ref} to ${destFile.ref} in same bucket ${file.bucket}`);
@@ -132,7 +187,17 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             return destFile;
         });
     }
-    _getUrl(file_1) {
+    /**
+     * Generates a secure, temporary GET link to access the object remotely.
+     *
+     * @param file - The file footprint.
+     * @param expiresIn - URL expiration in seconds.
+     * @param action - Intended action context.
+     * @param extra - Optional parameters (e.g. cache configurations).
+     * @returns A promise resolving to the signed URL payload.
+     * @throws {Error} If signature creation fails.
+     */
+    getUrl(file_1) {
         return __awaiter(this, arguments, void 0, function* (file, expiresIn = 3600, action = 'read', extra = {}) {
             storage_1.Storage.debug(`Getting signed url for file ${file.ref} in bucket ${file.bucket}`);
             const cacheControl = extra.cacheControl || (this._params.config.publicCacheDuration ? `${this._params.config.publicCacheDuration}` : undefined);
@@ -148,6 +213,12 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             return { url: data === null || data === void 0 ? void 0 : data.signedUrl, expiresIn };
         });
     }
+    /**
+     * Permanently removes the file from the Supabase bucket.
+     *
+     * @param file - Target file.
+     * @returns True upon success.
+     */
     delete(file) {
         return __awaiter(this, void 0, void 0, function* () {
             storage_1.Storage.info(`Deleting file ${file.ref} in bucket ${file.bucket}`);
@@ -159,6 +230,12 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             return true;
         });
     }
+    /**
+     * Downloads the file content to a temporary location and returns a Readable stream.
+     *
+     * @param file - File to read.
+     * @returns The content as a stream.
+     */
     getReadable(file) {
         return __awaiter(this, void 0, void 0, function* () {
             storage_1.Storage.debug(`GET Readable : ${file.ref}`);
@@ -171,6 +248,13 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             return readable;
         });
     }
+    /**
+     * Fetches and pipes the file content into the given response stream.
+     *
+     * @param file - File to stream.
+     * @param res - Writable stream or HTTP response object.
+     * @returns The piped stream instance.
+     */
     stream(file, res) {
         return __awaiter(this, void 0, void 0, function* () {
             storage_1.Storage.debug(`GET Stream : ${file.ref}`);
@@ -183,6 +267,13 @@ class SupabaseStorageAdapter extends storage_1.AbstractStorageAdapter {
             return readable.pipe(res);
         });
     }
+    /**
+     * Downloads the file directly, either returning the blob content or saving it locally.
+     *
+     * @param file - File footprint.
+     * @param meta - Options dictating save path or return format.
+     * @returns A promise resolving to the blob or local file path.
+     */
     download(file, meta) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data, error } = yield this._client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/storage-supabase",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Storage adapter for Supabase Storage",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -31,8 +31,8 @@
     "typescript": "^5.1.5"
   },
   "dependencies": {
-    "@quatrain/core": "^1.2.5",
-    "@quatrain/storage": "^1.2.2",
+    "@quatrain/core": "^1.2.6",
+    "@quatrain/storage": "^1.2.5",
     "@supabase/storage-js": "^2.7.2",
     "@supabase/supabase-js": "^2.87.3"
   },

package/src/SupabaseStorageAdapter.ts

@@ -12,6 +12,11 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import fs from 'node:fs'
 
+/**
+ * Storage adapter implementation targeting Supabase Storage.
+ * Interfaces with the `@supabase/storage-js` client to manage buckets,
+ * secure signed URLs, and file uploads.
+ */
 export class SupabaseStorageAdapter extends AbstractStorageAdapter {
    protected _client: StorageClient
 
@@ -25,14 +30,30 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       Storage.info(`[SSA] Supabase Storage Adapter initialized`)
    }
 
+   /**
+    * Exposes the underlying Supabase `StorageClient` instance.
+    * 
+    * @returns The storage client.
+    */
    getDriver() {
       return this._client
    }
 
+   /**
+    * Retrieves file metadata. Currently acts as a passthrough for Supabase.
+    * 
+    * @param file - Target file footprint.
+    * @returns The file metadata.
+    */
    getMetaData(file: FileType): Promise<FileType> {
       return new Promise(() => file)
    }
 
+   /**
+    * Validates backend connectivity by listing available buckets in the Supabase project.
+    * 
+    * @returns True if connected.
+    */
    async test(): Promise<boolean> {
       try {
          const { data, error } = await this._client.listBuckets()
@@ -53,6 +74,12 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       }
    }
 
+   /**
+    * Helper converting a node stream to a Buffer, essential for Blob creation.
+    * 
+    * @param stream - The input stream.
+    * @returns A promise resolving to the concatenated Buffer.
+    */
    async streamToBuffer(stream: Stream): Promise<Buffer> {
       return new Promise<Buffer>((resolve, reject) => {
          const _buf: any[] = []
@@ -63,6 +90,12 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       })
    }
 
+   /**
+    * Internal helper to convert a Buffer into a native ArrayBuffer.
+    * 
+    * @param buffer - The raw Buffer.
+    * @returns The ArrayBuffer representation.
+    */
    toArrayBuffer(buffer: Buffer): ArrayBuffer {
       const arrayBuffer = new ArrayBuffer(buffer.length)
       const view = new Uint8Array(arrayBuffer)
@@ -72,6 +105,14 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return arrayBuffer
    }
 
+   /**
+    * Uploads a local file path or stream to the Supabase storage bucket.
+    * 
+    * @param file - Target file schema.
+    * @param stream - Readable stream or string path to the file.
+    * @returns A promise resolving to the created file footprint.
+    * @throws {Error} If upload is rejected.
+    */
    async create(file: FileType, stream: Readable | string): Promise<FileType> {
       Storage.info(`[SSA] Uploading ${file.ref} to ${file.bucket}`)
 
@@ -108,6 +149,12 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return file
    }
 
+   /**
+    * Copies a file to a new destination key natively on the Supabase backend.
+    * 
+    * @param file - Original file.
+    * @param destFile - Target destination.
+    */
    async copy(file: FileType, destFile: FileType) {
       try {
          const response = await this._client
@@ -120,6 +167,14 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       }
    }
 
+   /**
+    * Moves/Renames an existing file natively within Supabase Storage.
+    * 
+    * @param file - The source file.
+    * @param destFile - The target file.
+    * @returns A promise resolving to the newly placed destination file.
+    * @throws {Error} If the move operation fails.
+    */
    async move(file: FileType, destFile: FileType) {
       Storage.info(
          `Moving file ${file.ref} to ${destFile.ref} in same bucket ${file.bucket}`
@@ -138,7 +193,17 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return destFile
    }
 
-   async _getUrl(file: FileType, expiresIn = 3600, action: any = 'read', extra: any = {}) {
+   /**
+    * Generates a secure, temporary GET link to access the object remotely.
+    * 
+    * @param file - The file footprint.
+    * @param expiresIn - URL expiration in seconds.
+    * @param action - Intended action context.
+    * @param extra - Optional parameters (e.g. cache configurations).
+    * @returns A promise resolving to the signed URL payload.
+    * @throws {Error} If signature creation fails.
+    */
+   async getUrl(file: FileType, expiresIn = 3600, action: any = 'read', extra: any = {}) {
       Storage.debug(
          `Getting signed url for file ${file.ref} in bucket ${file.bucket}`
       )
@@ -160,6 +225,12 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return { url: data?.signedUrl, expiresIn }
    }
 
+   /**
+    * Permanently removes the file from the Supabase bucket.
+    * 
+    * @param file - Target file.
+    * @returns True upon success.
+    */
    async delete(file: FileType) {
       Storage.info(`Deleting file ${file.ref} in bucket ${file.bucket}`)
       const { error } = await this._client.from(file.bucket).remove([file.ref])
@@ -173,6 +244,12 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return true
    }
 
+   /**
+    * Downloads the file content to a temporary location and returns a Readable stream.
+    * 
+    * @param file - File to read.
+    * @returns The content as a stream.
+    */
    async getReadable(file: FileType): Promise<Readable> {
       Storage.debug(`GET Readable : ${file.ref}`)
 
@@ -186,6 +263,13 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return readable
    }
 
+   /**
+    * Fetches and pipes the file content into the given response stream.
+    * 
+    * @param file - File to stream.
+    * @param res - Writable stream or HTTP response object.
+    * @returns The piped stream instance.
+    */
    async stream(file: FileType, res: any) {
       Storage.debug(`GET Stream : ${file.ref}`)
 
@@ -199,6 +283,13 @@ export class SupabaseStorageAdapter extends AbstractStorageAdapter {
       return readable.pipe(res)
    }
 
+   /**
+    * Downloads the file directly, either returning the blob content or saving it locally.
+    * 
+    * @param file - File footprint.
+    * @param meta - Options dictating save path or return format.
+    * @returns A promise resolving to the blob or local file path.
+    */
    async download(
       file: FileType,
       meta: DownloadFileMetaType