@h3ravel/filesystem 0.4.18 → 1.29.0-alpha.11

package/README.md

@@ -14,7 +14,97 @@
 
 # About H3ravel/filesystem
 
-This is the filesystem manager for the [H3ravel](https://h3ravel.toneflix.net) framework.
+This is the filesystem manager for the [H3ravel](https://h3ravel.toneflix.net) framework, providing shared file storage and filesystem utitlities for the framework.
+
+## Google Cloud Storage
+
+Install and configure the filesystem package with a `gcs` disk:
+
+```ts
+export default () => ({
+  default: 'gcs',
+  disks: {
+    gcs: {
+      driver: 'gcs',
+      projectId: env('GOOGLE_CLOUD_PROJECT'),
+      keyFilename: env('GOOGLE_APPLICATION_CREDENTIALS'),
+      bucket: env('GOOGLE_CLOUD_STORAGE_BUCKET'),
+      visibility: 'private',
+      usingUniformAcl: true,
+    },
+  },
+  links: {},
+})
+```
+
+The driver also accepts an initialized `@google-cloud/storage` client through
+the `storage` option.
+
+## Custom Drivers
+
+@h3ravel/filesystem allows you to configure and use custom storage drivers.
+
+**CloudinaryFileDriver.ts**
+
+```ts
+import type { DriverContract, ObjectVisibility } from 'flydrive/types';
+import type { CustomDiskConfig } from '@h3ravel/filesystem';
+
+export class CloudinaryFileDriver implements DriverContract {
+  constructor(private config?: CustomDiskConfig) {}
+  async exists(key: string) {}
+  async get(key: string) {}
+  async getStream(key: string) {}
+  async getBytes(key: string) {}
+  async getMetaData(key: string) {}
+  async getVisibility(): Promise<ObjectVisibility> {}
+  async getUrl(key: string) {}
+  async getSignedUrl(key: string) {}
+  async getSignedUploadUrl(key: string) {}
+  async setVisibility() {}
+  async put() {}
+  async putStream() {}
+  async copy() {}
+  async move() {}
+  async delete() {}
+  async deleteAll() {}
+  async listAll() {}
+  async bucket() {}
+}
+```
+
+**src/config/filesystem.ts**
+
+```ts
+import { CloudinaryFileDriver } from '../CloudinaryFileDriver';
+export default () => {
+  return {
+    default: 'images',
+    disks: {
+      images: {
+        //...Other Disks Here
+        driver: 'cloudinary',
+      },
+    },
+    links: {},
+    custom_drivers: {
+      cloudinary: CloudinaryFileDriver,
+    },
+  };
+};
+```
+
+To improve type safety and auto complete, you may augment the `CustomDiskDriverRegistry`
+
+**env.d.ts**
+
+```ts
+declare module '@h3ravel/filesystem' {
+  interface CustomDiskDriverRegistry {
+    cloudinary: { cloud_name: string; api_key: string; api_secret: string };
+  }
+}
+```
 
 ## Contributing
 

package/dist/app.globals.d.ts

@@ -0,0 +1,9 @@
+import { IFilesystemManager } from 'h3ravel/foundation'
+
+export { }
+
+declare module '@h3ravel/contracts' {
+    interface Bindings {
+        'storage': IFilesystemManager
+    }
+}

package/dist/commands.d.ts

@@ -0,0 +1,31 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/Commands/StorageLinkCommand.d.ts
+declare class StorageLinkCommand extends Command {
+  /**
+   * The name and signature of the console command.
+   *
+   * @var string
+   */
+  protected signature: string;
+  /**
+   * The console command description.
+   *
+   * @var string
+   */
+  protected description: string;
+  /**
+   * Execute the console command.
+   */
+  handle(this: any): Promise<void>;
+  /**
+   * Create the symbolic links configured for the application.
+   */
+  link(): Promise<void>;
+  /**
+   * Delete existing symbolic links configured for the application.
+   */
+  unlink(): Promise<void>;
+}
+//#endregion
+export { StorageLinkCommand };

package/dist/{index.cjs → commands.js}

@@ -1,10 +1,8 @@
-let __h3ravel_shared = require("@h3ravel/shared");
-let fs_promises = require("fs/promises");
-let __h3ravel_musket = require("@h3ravel/musket");
-let __h3ravel_core = require("@h3ravel/core");
-
+import { FileSystem, Logger } from "@h3ravel/shared";
+import { rm, symlink, unlink } from "fs/promises";
+import { Command } from "@h3ravel/musket";
 //#region src/Commands/StorageLinkCommand.ts
-var StorageLinkCommand = class extends __h3ravel_musket.Command {
+var StorageLinkCommand = class extends Command {
 	/**
 	* The name and signature of the console command.
 	*
@@ -40,23 +38,23 @@ var StorageLinkCommand = class extends __h3ravel_musket.Command {
 			const force = this.option("force");
 			const newPath = key;
 			const existingPath = links[key];
-			if (!force && await __h3ravel_shared.FileSystem.fileExists(newPath)) {
-				__h3ravel_shared.Logger.log([
+			if (!force && await FileSystem.fileExists(newPath)) {
+				Logger.log([
 					[" ERROR ", "bgRed"],
 					["The", "white"],
 					[`[${newPath.replace(process.cwd(), "")}]`, "bold"],
 					["link already exists.\n", "white"]
 				], " ");
 				continue;
-			} else if (force) await (0, fs_promises.rm)(newPath, {
+			} else if (force) await rm(newPath, {
 				recursive: true,
 				force: true
 			});
 			/**
 			* Create the symlink
 			*/
-			await (0, fs_promises.symlink)(existingPath, newPath);
-			__h3ravel_shared.Logger.log([
+			await symlink(existingPath, newPath);
+			Logger.log([
 				[" INFO ", "bgBlue"],
 				[" The ", "white"],
 				[`[${newPath.replace(process.cwd(), "")}] `, "bold"],
@@ -71,12 +69,12 @@ var StorageLinkCommand = class extends __h3ravel_musket.Command {
 	*/
 	async unlink() {
 		const links = config("filesystem.links");
-		for (const path in links) if (await __h3ravel_shared.FileSystem.fileExists(path)) {
+		for (const path in links) if (await FileSystem.fileExists(path)) {
 			/**
 			* Remove the symlink
 			*/
-			await (0, fs_promises.unlink)(path);
-			__h3ravel_shared.Logger.log([
+			await unlink(path);
+			Logger.log([
 				[" INFO ", "bgBlue"],
 				[" The ", "white"],
 				[`[${path.replace(process.cwd(), "")}] `, "bold"],
@@ -86,20 +84,5 @@ var StorageLinkCommand = class extends __h3ravel_musket.Command {
 		}
 	}
 };
-
 //#endregion
-//#region src/Providers/FilesystemProvider.ts
-/**
-* Sets up Filesystem management and lifecycle.
-* 
-*/
-var FilesystemProvider = class extends __h3ravel_core.ServiceProvider {
-	static priority = 997;
-	register() {
-		this.registerCommands([StorageLinkCommand]);
-	}
-};
-
-//#endregion
-exports.FilesystemProvider = FilesystemProvider;
-exports.StorageLinkCommand = StorageLinkCommand;
+export { StorageLinkCommand };

package/dist/facades.d.ts

@@ -0,0 +1,6 @@
+import { IFilesystemManager } from "@h3ravel/foundation";
+
+//#region src/Facades/StorageFacade.d.ts
+declare const Storage: IFilesystemManager<keyof import("@h3ravel/foundation").KnownDisks>;
+//#endregion
+export { Storage };

package/dist/facades.js

@@ -0,0 +1,10 @@
+import { Facades } from "@h3ravel/support/facades";
+//#region src/Facades/StorageFacade.ts
+var StorageFacade = class extends Facades {
+	static getFacadeAccessor() {
+		return "storage";
+	}
+};
+const Storage = StorageFacade.createFacade();
+//#endregion
+export { Storage };

package/dist/index.d.ts

@@ -1,33 +1,390 @@
 /// <reference path="./app.globals.d.ts" />
-import { Command } from "@h3ravel/musket";
-import { ServiceProvider } from "@h3ravel/core";
+import { StorageLinkCommand } from "./commands.js";
+import { FSDriver } from "flydrive/drivers/fs";
+import { DriveDirectory, DriveFile, DriveManager } from "flydrive";
+import { CustomDiskDriverRegistry, DiskConfig, FileLike, FilesystemConfig, IFilesystemDriver, IFilesystemManager, IFtpDiskDriver, KnownDisks } from "@h3ravel/foundation";
+import { Readable } from "node:stream";
+import { GCSDriver } from "flydrive/drivers/gcs";
+import { S3Driver } from "flydrive/drivers/s3";
+import { ServiceProvider } from "@h3ravel/support";
+import { DriverContract, ObjectMetaData, ObjectVisibility, SignedURLOptions, WriteOptions } from "flydrive/types";
 
-//#region src/Commands/StorageLinkCommand.d.ts
-declare class StorageLinkCommand extends Command {
+//#region src/FtpDriver.d.ts
+declare class FtpDriver extends IFtpDiskDriver implements DriverContract {
+  private config;
+  constructor(config: string | {
+    host: string;
+    username: string;
+    password: string;
+    port?: number;
+    verbose?: boolean;
+    privateKey?: string;
+  });
+  getConfig(): {
+    host: string;
+    username: string;
+    password: string;
+    port?: number;
+    verbose?: boolean;
+    privateKey?: string;
+  };
+  private init;
+  private load;
   /**
-   * The name and signature of the console command.
+   * Return a boolean value indicating if the file exists
+   * or not.
+   */
+  exists(key: string): Promise<boolean>;
+  /**
+   * Return the file contents as a UTF-8 string. Throw an exception
+   * if the file is missing.
+   */
+  get(key: string): Promise<string>;
+  /**
+   * Return the file contents as a Readable stream. Throw an exception
+   * if the file is missing.
+   */
+  getStream(key: string): Promise<Readable>;
+  /**
+   * Return the file contents as a Uint8Array. Throw an exception
+   * if the file is missing.
+   */
+  getBytes(key: string): Promise<Uint8Array>;
+  /**
+   * Return metadata of the file. Throw an exception
+   * if the file is missing.
+   */
+  getMetaData(key: string): Promise<ObjectMetaData>;
+  /**
+   * Return visibility of the file. Infer visibility from the initial
+   * config, when the driver does not support the concept of visibility.
+   */
+  getVisibility(key: string): Promise<ObjectVisibility>;
+  /**
+   * Return the public URL of the file. Throw an exception when the driver
+   * does not support generating URLs.
+   */
+  getUrl(key: string): Promise<string>;
+  /**
+   * Return the signed URL to serve a private file. Throw exception
+   * when the driver does not support generating URLs.
+   */
+  getSignedUrl(key: string, options?: SignedURLOptions): Promise<string>;
+  /**
+   * Return the signed/temporary URL that can be used to directly upload
+   * the file contents to the storage.
+   */
+  getSignedUploadUrl(key: string, options?: SignedURLOptions): Promise<string>;
+  /**
+   * Update the visibility of the file. Result in a NOOP
+   * when the driver does not support the concept of
+   * visibility.
+   */
+  setVisibility(key: string, visibility: ObjectVisibility): Promise<void>;
+  /**
+   * Create a new file or update an existing file. The contents
+   * will be a UTF-8 string or "Uint8Array".
+   */
+  put(key: string, contents: string | Uint8Array, options?: WriteOptions): Promise<void>;
+  /**
+   * Create a new file or update an existing file. The contents
+   * will be a Readable stream.
+   */
+  putStream(key: string, contents: Readable, options?: WriteOptions): Promise<void>;
+  /**
+   * Copy the existing file to the destination. Make sure the new file
+   * has the same visibility as the existing file. It might require
+   * manually fetching the visibility of the "source" file.
+   */
+  copy(source: string, destination: string, options?: WriteOptions): Promise<void>;
+  /**
+   * Move the existing file to the destination. Make sure the new file
+   * has the same visibility as the existing file. It might require
+   * manually fetching the visibility of the "source" file.
+   */
+  move(source: string, destination: string, options?: WriteOptions): Promise<void>;
+  /**
+   * Delete an existing file. Do not throw an error if the
+   * file is already missing
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * Delete all files inside a folder. Do not throw an error
+   * if the folder does not exist or is empty.
+   */
+  deleteAll(prefix: string): Promise<void>;
+  /**
+   * Switch bucket at runtime if supported.
+   */
+  bucket(config: string | {
+    host: string;
+    username: string;
+    password: string;
+    port?: number;
+    verbose?: boolean;
+    privateKey?: string;
+  }): DriverContract;
+  /**
+   * List all files from a given folder or the root of the storage.
+   * Do not throw an error if the request folder does not exist.
+   */
+  listAll(prefix: string, options?: {
+    recursive?: boolean;
+    paginationToken?: string;
+  }): Promise<{
+    paginationToken?: string;
+    objects: Iterable<DriveFile | DriveDirectory>;
+  }>;
+}
+//#endregion
+//#region src/Driver.d.ts
+type BuiltInDriverMap = { [K in keyof Driver]: Driver[K] };
+type DriverFor<K extends string> = K extends keyof BuiltInDriverMap ? ReturnType<BuiltInDriverMap[K]> : ReturnType<BuiltInDriverMap['custom']>;
+declare class Driver extends IFilesystemDriver {
+  private config;
+  private static customDrivers;
+  constructor(config: DiskConfig);
+  static make<K extends 'local' | 'ftp' | 's3' | 'gcs' | (string & {})>(config: DiskConfig): DriverFor<K>;
+  local(): FSDriver;
+  s3(): S3Driver;
+  gcs(): GCSDriver;
+  ftp(): FtpDriver;
+  custom(name: string): DriverContract;
+  /**
+   * Register a new custom driver
    *
-   * @var string
+   * @param name
+   * @param driver
    */
-  protected signature: string;
+  static registerDriver(name: string, driver: DriverContract): void;
   /**
-   * The console command description.
+   * Unregister a new custom driver
    *
-   * @var string
+   * @param name
    */
-  protected description: string;
+  static removeDriver(name: string): void;
+}
+//#endregion
+//#region src/FilesystemManager.d.ts
+declare class FilesystemManager<D extends keyof KnownDisks | keyof CustomDiskDriverRegistry = keyof KnownDisks | keyof CustomDiskDriverRegistry> extends IFilesystemManager implements DriverContract {
+  driver: DriveManager<any>;
+  services: Record<string, () => DriverContract>;
+  diskName: D;
+  driverName: FilesystemConfig['disks'][D]['driver'];
+  constructor();
   /**
-   * Execute the console command.
+   * Select a configured disk on the filesystem manager.
+   *
+   * @param diskName  The name of the disk to use. If not provided, the default disk will be used.
+   * @returns The filesystem manager instance
    */
-  handle(this: any): Promise<void>;
+  disk<K extends keyof KnownDisks | keyof CustomDiskDriverRegistry>(diskName: K): this;
   /**
-   * Create the symbolic links configured for the application.
+   * Generate a unique name for the file based on random numbers and original extension
+   *
+   * @param file  The file object containing the original name
+   * @returns     A unique file name
    */
-  link(): Promise<void>;
+  generateName(file: {
+    name?: string;
+    originalname?: string;
+  }): string;
   /**
-   * Delete existing symbolic links configured for the application.
+   * Save the file to the storage and return the public URL and the file path
+   *
+   * @param file      The file object containing the file data
+   * @param filePath  The path where the file should be saved
+   * @param fileName  The name to save the file as (optional)
+   * @returns         A tuple containing the public URL and the file path
+   */
+  saveFile(file: FileLike, filePath?: string, fileName?: string): Promise<[string, string]>;
+  /**
+   * Return a boolean indicating if the file exists
+   *
+   * @param key
+   * @returns
+   */
+  exists(key: string): Promise<boolean>;
+  /**
+   * Return contents of a object for the given key as a UTF-8 string.
+   * Should throw "E_CANNOT_READ_FILE" error when the file
+   * does not exists.
+   *
+   * @param key
+   * @returns
+   */
+  get(key: string): Promise<string>;
+  /**
+   * Get the name of the disk currently in use.
+   *
+   * @returns
+   */
+  getDiskName(): D;
+  /**
+   * Get the name of the driver currently in use.
+   *
+   * @returns
+   */
+  getDriverName(): (KnownDisks & CustomDiskDriverRegistry)[D]["driver"];
+  /**
+   * Get the driver currently in use.
+   *
+   * @returns
+   */
+  getDriver(): DriveManager<any>;
+  /**
+   * Return contents of a object for the given key as a Readable stream.
+   * Should throw "E_CANNOT_READ_FILE" error when the file
+   * does not exists.
+   *
+   * @param key
+   * @returns
+   */
+  getStream(key: string): Promise<Readable>;
+  /**
+   * Return contents of an object for the given key as an Uint8Array.
+   * Should throw "E_CANNOT_READ_FILE" error when the file
+   * does not exists.
+   *
+   * @param key
+   * @returns
+   */
+  getBytes(key: string): Promise<Uint8Array>;
+  /**
+   * Return metadata of an object for the given key.
+   *
+   * @param key
+   * @returns
+   */
+  getMetaData(key: string): Promise<ObjectMetaData>;
+  /**
+   * Return the visibility of the file
+   *
+   * @param key
+   * @returns
+   */
+  getVisibility(key: string): Promise<ObjectVisibility>;
+  /**
+   * Return the public URL to access the file
+   *
+   * @param key
+   * @returns
+   */
+  getUrl(key: string): Promise<string>;
+  /**
+   * Return the signed/temporary URL to access the file
+   *
+   * @param key
+   * @param options
+   * @returns
+   */
+  getSignedUrl(key: string, options?: SignedURLOptions): Promise<string>;
+  /**
+   * Return the signed/temporary URL that can be used to directly upload
+   * the file contents to the storage.
+   *
+   * @param key
+   * @param options
+   * @returns
+   */
+  getSignedUploadUrl(key: string, options?: SignedURLOptions): Promise<string>;
+  /**
+   * Update the visibility of the file
+   *
+   * @param key
+   * @param visibility
+   * @returns
+   */
+  setVisibility(key: string, visibility: ObjectVisibility): Promise<void>;
+  /**
+   * Write object to the destination with the provided
+   * contents.
+   *
+   * @param key
+   * @param contents
+   * @param options
+   * @returns
+   */
+  put(key: string, contents: string | Uint8Array | FileLike, options?: WriteOptions): Promise<void>;
+  /**
+   * Write object to the destination with the provided
+   * contents as a readable stream
+   *
+   * @param key
+   * @param contents
+   * @param options
+   * @returns
+   */
+  putStream(key: string, contents: Readable, options?: WriteOptions): Promise<void>;
+  /**
+   * Copy the file from within the disk root location. Both
+   * the "source" and "destination" will be the key names
+   * and not absolute paths.
+   *
+   * @param source
+   * @param destination
+   * @param options
+   * @returns
+   */
+  copy(source: string, destination: string, options?: WriteOptions): Promise<void>;
+  /**
+   * Move the file from within the disk root location. Both
+   * the "source" and "destination" will be the key names
+   * and not absolute paths.
+   *
+   * @param source
+   * @param destination
+   * @param options
+   * @returns
+   */
+  move(source: string, destination: string, options?: WriteOptions): Promise<void>;
+  /**
+   * Delete the file for the given key. Should not throw
+   * error when file does not exist in first place
+   *
+   * @param key
+   * @returns
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * Delete the files and directories matching the provided prefix.
+   *
+   * @param prefix
+   * @returns
+   */
+  deleteAll(prefix: string): Promise<void>;
+  /**
+   * The list all method must return an array of objects with
+   * the ability to paginate results (if supported).
+   *
+   * @param prefix
+   * @param options
+   * @returns
+   */
+  listAll(prefix: string, options?: {
+    recursive?: boolean;
+    paginationToken?: string;
+  }): Promise<{
+    paginationToken?: string;
+    objects: Iterable<DriveFile | DriveDirectory>;
+  }>;
+  /**
+   * Switch bucket at runtime if supported.
+   *
+   * @param bucket
+   * @returns
+   */
+  bucket(bucket: string): DriverContract;
+  /**
+   * Create symbolic links for all configured links in the application configuration.
+   *
+   * @param param0
    */
-  unlink(): Promise<void>;
+  link({
+    force
+  }?: {
+    force?: boolean;
+  }): void;
 }
 //#endregion
 //#region src/Providers/FilesystemProvider.d.ts
@@ -40,4 +397,4 @@ declare class FilesystemProvider extends ServiceProvider {
   register(): void;
 }
 //#endregion
-export { FilesystemProvider, StorageLinkCommand };
+export { Driver, FilesystemManager, FilesystemProvider, FtpDriver, StorageLinkCommand };