fix(filesystem): improve type safety and provide methods to access current disk and driver.

Author: exronnin

packages/filesystem/src/Storage.ts

@@ -1,5 +1,5 @@
+import { CustomDiskDriverRegistry, DriverConfig, FileLike, FilesystemConfig, KnownDisks } from './types'
 import { DriveDirectory, DriveFile, DriveManager } from 'flydrive'
-import { DriverConfig, FileLike } from './types'
 import { DriverContract, ObjectMetaData, ObjectVisibility, SignedURLOptions, WriteOptions } from 'flydrive/types'
 import { rmSync, symlinkSync } from 'node:fs'
 
@@ -10,10 +10,13 @@ import { Readable } from 'node:stream'
 import { config } from '@arkstack/common'
 import path from 'node:path'
 
-export class Storage implements DriverContract {
+export class Storage<
+    D extends keyof KnownDisks | keyof CustomDiskDriverRegistry = keyof KnownDisks | keyof CustomDiskDriverRegistry
+> implements DriverContract {
     driver: DriveManager<any>
     services: Record<string, () => DriverContract> = {}
-    diskName: string
+    diskName: D
+    driverName: FilesystemConfig['disks'][D]['driver']
 
     constructor() {
         const disks = Object.entries(config('filesystem.disks', {})) as Array<[string, DriverConfig]>
@@ -28,6 +31,7 @@ export class Storage implements DriverContract {
         }
 
         this.diskName = config('filesystem.default')
+        this.driverName = config(`filesystem.disks.${this.diskName}.driver`) as never
         this.driver = new DriveManager({
             default: config('filesystem.default'),
             services: this.services
@@ -40,18 +44,21 @@ export class Storage implements DriverContract {
      * @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 {
+    static disk<K extends keyof KnownDisks | keyof CustomDiskDriverRegistry> (
+        diskName?: K
+    ): Storage<K> {
         const storage = new Storage()
 
         if (diskName) {
             storage.diskName = diskName
+            storage.driverName = config(`filesystem.disks.${diskName}.driver`)
             storage.driver = new DriveManager({
                 default: diskName,
                 services: storage.services
             })
         }
 
-        return storage
+        return storage as never
     }
 
     /**
@@ -111,81 +118,156 @@ export class Storage implements DriverContract {
         await drive.put(path.join(filePath, name), file.buffer)
 
         const url = await drive.getUrl(path.join(filePath, name))
-        const pth = this.diskName === 'local' ? path.join(filePath, name) : url
+        const pth = this.driverName === 'local' ? path.join(filePath, name) : url
 
         return [url, pth]
     }
 
     /**
      * Return a boolean indicating if the file exists
+     * 
+     * @param key 
+     * @returns 
      */
     exists (key: string): Promise<boolean> {
         return this.driver.use().exists(key)
     }
+
     /**
      * 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> {
         return this.driver.use().get(key)
     }
+
+    /**
+     * Get the name of the disk currently in use.
+     * 
+     * @returns 
+     */
+    getDiskName (): D {
+        return this.diskName
+    }
+
+    /**
+     * Get the name of the driver currently in use.
+     * 
+     * @returns 
+     */
+    getDriverName () {
+        return this.driverName
+    }
+
+    /**
+     * Get the driver currently in use.
+     * 
+     * @returns 
+     */
+    getDriver (): DriveManager<any> {
+        return this.driver
+    }
+
     /**
      * 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 this.driver.use().getStream(key)
     }
+
     /**
      * 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 this.driver.use().getBytes(key)
     }
+
     /**
      * Return metadata of an object for the given key.
+     * 
+     * @param key 
+     * @returns 
      */
     getMetaData (key: string): Promise<ObjectMetaData> {
         return this.driver.use().getMetaData(key)
     }
+
     /**
      * Return the visibility of the file
+     * 
+     * @param key 
+     * @returns 
      */
     getVisibility (key: string): Promise<ObjectVisibility> {
         return this.driver.use().getVisibility(key)
     }
+
     /**
      * Return the public URL to access the file
+     * 
+     * @param key 
+     * @returns 
      */
     getUrl (key: string): Promise<string> {
         return this.driver.use().getUrl(key)
     }
+
     /**
      * Return the signed/temporary URL to access the file
+     * 
+     * @param key 
+     * @param options 
+     * @returns 
      */
     getSignedUrl (key: string, options?: SignedURLOptions): Promise<string> {
         return this.driver.use().getSignedUrl(key, options)
     }
+
     /**
      * 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> {
         return this.driver.use().getSignedUploadUrl(key, options)
     }
+
     /**
      * Update the visibility of the file
+     * 
+     * @param key 
+     * @param visibility 
+     * @returns 
      */
     setVisibility (key: string, visibility: ObjectVisibility): Promise<void> {
         return this.driver.use().setVisibility(key, visibility)
     }
+
     /**
      * 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> {
         if (!(contents instanceof Uint8Array) && typeof contents !== 'string') {
@@ -194,46 +276,78 @@ export class Storage implements DriverContract {
 
         return this.driver.use().put(key, contents, options)
     }
+
     /**
      * 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> {
         return this.driver.use().putStream(key, contents, options)
     }
+
     /**
      * 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> {
         return this.driver.use().copy(source, destination, options)
     }
+
     /**
      * 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> {
         return this.driver.use().move(source, destination, options)
     }
+
     /**
      * 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> {
         return this.driver.use().delete(key)
     }
+
     /**
      * Delete the files and directories matching the provided prefix.
+     * 
+     * @param prefix 
+     * @returns 
      */
     deleteAll (prefix: string): Promise<void> {
         return this.driver.use().deleteAll(prefix)
     }
+
     /**
      * 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;
@@ -243,15 +357,21 @@ export class Storage implements DriverContract {
     }> {
         return this.driver.use().listAll(prefix, options)
     }
+
     /**
      * Switch bucket at runtime if supported.
+     * 
+     * @param bucket 
+     * @returns 
      */
     bucket (bucket: string): DriverContract {
         return (this.driver.use() as any).bucket(bucket)
     }
 
     /**
      * Create symbolic links for all configured links in the application configuration.
+     * 
+     * @param param0 
      */
     static link ({ force = false }: { force?: boolean } = {}): void {
         for (const link in config('filesystem.links')) {

packages/filesystem/tests/ftp.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+
+import { FtpDriver } from '../src/FtpDriver'
+
+const ftpDriver = new FtpDriver(process.env.FTP_CONNECTION || 'sftp://a.b.c.d:22')
+const testPath = process.env.FTP_TEST_PATH || '/'
+
+describe('Filesystem FTP Driver', () => {
+    it('should be configurable with an object', async () => {
+        const config = {
+            host: 'ftp.example.com',
+            username: 'username',
+            password: 'password',
+            port: 22,
+            verbose: false,
+        }
+        const ftpDriver = new FtpDriver(config)
+
+        expect(ftpDriver.getConfig()).toEqual(config)
+    })
+
+    it('should be configurable with a string', async () => {
+        const config = 'ftp://username:password@ftp.example.com'
+        const ftpDriver = new FtpDriver(config)
+
+        expect(ftpDriver.getConfig()).toEqual({
+            host: 'ftp.example.com',
+            username: 'username',
+            password: 'password',
+            port: 22,
+            verbose: false,
+        })
+    })
+
+    it.skip('should list files in a directory', async () => {
+        console.log(testPath, await ftpDriver.listAll(testPath))
+    })
+
+    it.skip('should exist', async () => {
+        expect(await ftpDriver.exists(testPath + '/test.txt')).toBe(true)
+    })
+
+    it.skip('should get stream from FTP server', async () => {
+        const stream = await ftpDriver.getStream(testPath + '/test.txt')
+        const chunks: Uint8Array[] = []
+        for await (const chunk of stream) {
+            chunks.push(chunk)
+        }
+        const content = Buffer.concat(chunks).toString('utf-8')
+        expect(content).toBe('Hello World\n')
+    })
+
+    it.skip('should get file from FTP server', async () => {
+        const content = await ftpDriver.get(testPath + '/test.txt')
+        expect(content).toBe('Hello World\n')
+    })
+
+    it.skip('should get bytes from FTP server', async () => {
+        const content = await ftpDriver.getBytes(testPath + '/test.txt')
+        expect(Buffer.from(content).toString('utf-8')).toBe('Hello World\n')
+    })
+}, 10000 /* increase timeout for FTP operations */)