Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Slynova-Org/flydrive

☁️ Flexible and Fluent framework-agnostic driver based system to manage storage in Node.js
https://github.com/Slynova-Org/flydrive

digital-ocean-spaces driver filesystem framework-agnostic google-cloud-storage nodejs s3 storage

Last synced: 7 days ago
JSON representation

☁️ Flexible and Fluent framework-agnostic driver based system to manage storage in Node.js

Awesome Lists containing this project

README 

        


  flydrive






  Download

  Version

  License




`flydrive` is a framework-agnostic package which provides a powerful wrapper to manage file Storage in [Node.js](https://nodejs.org).



There are currently 3 drivers available:



- `'local'`: Stores files on the local file system.

- `'s3'`: Amazon S3 and other compatible services

  - You need to install the `@slynova/flydrive-s3` package to be able to use this driver.

  - This driver is compatible with DigitalOcean Spaces and Scaleway Object Storage.

- `'gcs'`: Google Cloud Storage

  - You need to install the `@slynova/flydrive-gcs` package to be able to use this driver.



---



## Getting Started



This package is available in the npm registry.

It can easily be installed with `npm` or `yarn`.



```bash

$ npm i @slynova/flydrive

# or

$ yarn add @slynova/flydrive

```



When you require the package in your file, it will give you access to the `StorageManager` class.

This class is a facade for the package and should be instantiated with a [configuration object](https://github.com/Slynova-Org/flydrive/blob/develop/examples/config.ts).



```javascript

const { StorageManager } = require('@slynova/flydrive');

const storage = new StorageManager(...);

```



Once you instantiated the manager, you can use the `StorageManager#disk()` method to retrieve a disk an use it.



```javascript

storage.disk(); // Returns the default disk (specified in the config)

storage.disk('awsCloud'); // Returns the driver for the disk "s3"

storage.disk('awsCloud', customConfig); // Overwrite the default configuration of the disk

```



## Registering External Driver



After installing any external driver, like `@slynova/flydrive-gcs`, you need to register it inside our manager to be able to use it.



The following is done by using the method `storage.registerDriver(name: string, Driver)`.



```ts

const { GoogleCloudStorage } = require('@slynova/flydrive-gcs');

const { StorageManager } = require('@slynova/flydrive');

const storage = new StorageManager(...);



storage.registerDriver('gcs', GoogleCloudStorage);

```



## Driver's API



Each driver extends the abstract class [`Storage`](https://github.com/Slynova-Org/flydrive/blob/develop/packages/flydrive/src/Storage.ts). This class will throw an exception for each methods by default. The driver needs to overwrite the methods it supports.



The following method doesn't exist on the `LocalFileSystemStorage` driver, therefore, it will throw an exception.



```javascript

// throws "E_METHOD_NOT_SUPPORTED: Method getSignedUrl is not supported for the driver LocalFileSystemStorage"

storage.disk('local').getSignedUrl();

```



Since we are using TypeScript, you can make use of casting to get the real interface:



```typescript

import { LocalFileSystemStorage } from '@slynova/flydrive';



storage.disk('local');

```



### Response interface



Asynchronous methods will always return a Promise which resolves with a `Response`

object. The response object may contain relevant data in its properties (for

example, the `ExistsResponse` object for the `exists` method contains a boolean

`exists` property).



All responses additionally have a `raw` property which is driver-specific and

contains the result from the original call made by the driver.



### Exceptions



In case of runtime errors, `flydrive` will try to throw driver-agnostic exceptions.

Exceptions also have a `raw` property which contains the original error.



### Methods



append(location: string, content: Buffer | Stream | string, options: object): Promise<Response>



This method will append the content to the file at the location.

If the file doesn't exist yet, it will be created.



```javascript

// Supported drivers: "local"



await storage.disk('local').append('foo.txt', 'bar');

// foo.txt now has the content `${initialContent}bar`

```



copy(src: string, dest: string, options: object): Promise<Response>



This method will copy a file to another location.



```javascript

// Supported drivers: "local", "s3", "gcs"



await storage.disk('local').copy('foo.txt', 'bar.txt');

// foo.txt was copied to bar.txt

```



delete(location: string): Promise<DeleteResponse>



This method will delete the file at the given location.



```javascript

// Supported drivers: "local", "s3", "gcs"



const { wasDeleted } = await storage.disk('local').delete('foo.txt');

// If a file named foo.txt has been deleted, wasDeleted is true.

```



The value returned by this method will have a `wasDeleted` property that

can be either a boolean (`true` if a file was deleted, `false` if there was

no file to delete) or `null` (if no information about the file is available).



driver()



This method returns the driver used if you need to do anything specific not supported by default.



```javascript

storage.disk('local').driver(); // Returns the "fs-extra" module.

storage.disk('awsCloud').driver(); // Returns an instance of the AWS S3 client.

storage.disk('googleCloud').driver(); // Returns an instance of the the Google Cloud Storage client.

// ....

```



exists(location: string): Promise<ExistsResponse>



This method will determine if a file exists at the given location.



```javascript

// Supported drivers: "local", "s3", "gcs"



const { exists } = await storage.disk('local').exists('foo.txt');

// exists is true or false

```



get(location: string, encoding: string = 'utf-8'): Promise<ContentResponse<string>>



This method will return the file's content as a string for the given location.



```javascript

// Supported drivers: "local", "s3", "gcs"



const { content } = await storage.disk('local').get('foo.txt');

```



getBuffer(location: string): Promise<ContentResponse<Buffer>>



This method will return the file's content as a Buffer for the given location.



```javascript

// Supported drivers: "local", "s3", "gcs"



const buffer = await storage.disk('local').getBuffer('foo.txt');

```



getSignedUrl(location: string, options: SignedUrlOptions = { expiry: 900 }): Promise<SignedUrlResponse>



This method will return the signed url for an existing file.



```javascript

// Supported drivers: "s3", "gcs"



const { signedUrl } = await storage.disk('awsCloud').getSignedUrl('foo.txt');

```



getStat(location: string): Promise<StatResponse>



This method will return the file's size (in bytes) and last modification date.



```javascript

// Supported drivers: "local", "s3", "gcs"



const { size, modified } = await storage.disk('local').getStat('foo.txt');

```



getStream(location: string, options: object | string): Stream



This method will return a Node.js readable stream for the given file.



```javascript

// Supported drivers: "local", "s3", "gcs"



const stream = storage.disk('local').getStream('foo.txt');

```



getUrl(location: string): string



This method will return a public URL for a given file.



```javascript

// Supported drivers: "s3", "gcs"



const uri = storage.disk('awsCloud').getUrl('foo.txt');

```



move(src: string, dest: string): Promise<Response>



This method will move the file to a new location.



```javascript

// Supported drivers: "local", "s3", "gcs"



await storage.disk('local').move('foo.txt', 'newFolder/foo.txt');

```



put(location: string, content: Buffer | Stream | string, options: object): Promise<Response>



This method will create a new file with the provided content.



```javascript

// Supported drivers: "local", "s3", "gcs"



await storage.disk('local').put('bar.txt', 'Foobar');

```



prepend(location: string, content: Buffer | string, options: object): Promise<Response>



This method will prepend content to a file.



```javascript

// Supported drivers: "local"



await storage.disk('local').prepend('foo.txt', 'bar');

// foo.txt now has the content `bar${initialContent}`

```



flatList(prefix?: string): AsyncIterable<FileListResponse>



This method will return an async iterator over all file names that start with `prefix` (recursive).



```javascript

// Supported drivers: "local", "s3", "gcs"



const disk = storage.disk('local');

for await (const file of disk.flatList('a/b')) {

  console.log(file.path);

}

```



## Contribution Guidelines



Any pull requests or discussions are welcome.

Note that every pull request providing new feature or correcting a bug should be created with appropriate unit tests.