@arkstack/filesystem 0.12.6 → 0.12.7

package/dist/index.d.ts

@@ -81,29 +81,123 @@ declare class Storage implements DriverContract {
   services: Record<string, () => DriverContract>;
   diskName: string;
   constructor();
+  /**
+   * Static method to get a disk instance directly from the Storage class without needing to instantiate it first.
+   *
+   * @param diskName The name of the disk to use. If not provided, the default disk will be used.
+   * @returns A Storage instance
+   */
   static disk<K extends string>(diskName?: K): Storage;
+  /**
+   * 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
+   */
   static generateName: (file: {
     name?: string;
     originalname?: string;
   }) => string;
+  /**
+   * 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
+   */
   static saveFile: (file: FileLike, filePath?: string, fileName?: string) => Promise<[string, string]>;
+  /**
+   * 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
+   */
   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.
+   */
   get(key: string): Promise<string>;
+  /**
+   * 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.
+   */
   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.
+   */
   getBytes(key: string): Promise<Uint8Array>;
+  /**
+   * Return metadata of an object for the given key.
+   */
   getMetaData(key: string): Promise<ObjectMetaData>;
+  /**
+   * Return the visibility of the file
+   */
   getVisibility(key: string): Promise<ObjectVisibility>;
+  /**
+   * Return the public URL to access the file
+   */
   getUrl(key: string): Promise<string>;
+  /**
+   * Return the signed/temporary URL to access the file
+   */
   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
+   */
   setVisibility(key: string, visibility: ObjectVisibility): Promise<void>;
+  /**
+   * Write object to the destination with the provided
+   * contents.
+   */
   put(key: string, contents: string | Uint8Array | FileLike, options?: WriteOptions): Promise<void>;
+  /**
+   * Write object to the destination with the provided
+   * contents as a readable stream
+   */
   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.
+   */
   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.
+   */
   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
+   */
   delete(key: string): Promise<void>;
+  /**
+   * Delete the files and directories matching the provided prefix.
+   */
   deleteAll(prefix: string): Promise<void>;
+  /**
+   * The list all method must return an array of objects with
+   * the ability to paginate results (if supported).
+   */
   listAll(prefix: string, options?: {
     recursive?: boolean;
     paginationToken?: string;
@@ -111,7 +205,13 @@ declare class Storage implements DriverContract {
     paginationToken?: string;
     objects: Iterable<DriveFile | DriveDirectory>;
   }>;
+  /**
+   * Switch bucket at runtime if supported.
+   */
   bucket(bucket: string): DriverContract;
+  /**
+   * Create symbolic links for all configured links in the application configuration.
+   */
   static link({
     force
   }?: {
@@ -140,22 +240,92 @@ declare class FtpDriver implements DriverContract {
   };
   private init;
   private load;
+  /**
+   * 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;
@@ -164,6 +334,10 @@ declare class FtpDriver implements DriverContract {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/filesystem",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "type": "module",
   "description": "Filesystem module for Arkstack, providing shared file storage and filesystem utitlities for the framework.",
   "homepage": "https://arkstack.toneflix.net",
@@ -39,8 +39,8 @@
     "@aws-sdk/s3-request-presigner": "^3.1011.0",
     "flydrive": "^2.0.0",
     "ssh2-sftp-client": "^12.1.0",
-    "@arkstack/common": "^0.12.6",
-    "@arkstack/contract": "^0.12.6"
+    "@arkstack/common": "^0.12.7",
+    "@arkstack/contract": "^0.12.7"
   },
   "devDependencies": {
     "@types/ssh2-sftp-client": "^9.0.6"