Node File System

This project was inspired on the great PHP package Flysystem, and tries to be API compatible when possible. It's a work in progress. Pull requests are welcome.

Like Flysystem, is a filesystem abstraction which allows you to easily swap out a local filesystem for a remote one.

It's made with Typescript. All methods are async.

Goals

- Have a generic API for handling common tasks across multiple file storage engines.
- Have consistent output which you can rely on.
- Emulate directories in systems that support none, like AwsS3.

Installation

Using YARN:

``
yarn add node-filesystem
`

Using NPM:

`
npm add node-filesystem --save
`

Core concepts

See Flysysytem docs

The API

$3

`typescript
await filesystem.write('path/to/file.txt', 'contents');
`

$3

`typescript
await filesystem.update('path/to/file.txt', 'new contents');
`

$3

`typescript
await filesystem.put('path/to/file.txt', 'contents');
`

$3

`typescript
const contents = await filesystem.read('path/to/file.txt');
`

$3

`typescript
const exists = await filesystem.has('path/to/file.txt');
`

NOTE: This only has consistent behaviour for files, not directories. Directories are less important, they’re created implicitly and often ignored because not every adapter (filesystem type) supports directories.

$3

`typescript
await filesystem.delete('path/to/file.txt');
`

$3

`typescript
await filesystem.rename('filename.txt', 'newname.txt');
`

$3

`typescript
await filesystem.copy('filename.txt', 'duplicate.txt');
`

$3

`typescript
const mimetype = await filesystem.getMimetype('path/to/file.txt');
`

$3

`typescript
const timestamp = await filesystem.getTimestamp('path/to/file.txt');
`

$3

`typescript
const size = await filesystem.getSize('path/to/file.txt');
`

$3

`typescript
await filesystem.createDir('path/to/nested/directory');
`

$3

`typescript
await filesystem.write('path/to/file.txt', 'contents');
`

$3

`typescript
await filesystem.deleteDir('path/to/directory');
`

The above method will delete directories recursively

NOTE: All paths used are relative to the adapter root directory.

$3

Visibility is the abstraction of file permissions across multiple platforms. Visibility can be either public or private.

`typescript
await filesystem.write('db.backup', backup, {
visibility: 'private',
});
`

You can also change and check visibility of existing files

`typescript
if ((await filesystem.getVisibility('secret.txt')) === 'private') {
await filesystem.setVisibility('secret.txt', 'public');
}
`

$3

`typescript
const contents = await filesystem.listContents();
`

The result of a contents listing is a collection of arrays containing all the metadata the file manager knows at that time. By default you’ll receive path info and file type. Additional info could be supplied by default depending on the adapter used.

Example:

`typescript
for (const object of contents) {
console.log(
object.basename,
' is located at ',
object.path,
' and is a ',
object.type,
);
}
`

By default it lists the top directory non-recursively. You can supply a directory name and recursive boolean to get more precise results

`typescript
const contents = filesystem.listContents('some/dir', true);
`

Adapters

$3

`typescript
import { LocalAdapter } from 'node-filesystem';

new LocalAdapter('my-root-folder', 'my-subfolder');
`

$3

You need install the official AWS SDK v3:

`
yarn add @aws-sdk/client-s3
`

`typescript
import { S3Client } from '@aws-sdk/client-s3';
import { S3Adapter } from 'node-filesystem';

const s3Client = new S3Client({
credentials: {
accessKeyId: 'my-aws-access-key',
secretAccessKey: 'my-aws-secret-key',
},
region: 'my-aws-region',
});

new S3Adapter(s3Client, 'my-bucket', 'my-subfolder');
`

$3

If you're using Bun runtime (>= 1.1.30), you can use the native Bun S3 adapter which has better performance:

No additional dependencies needed - Bun has built-in S3 support!

`typescript
import { BunAdapter } from 'node-filesystem';

const adapter = new BunAdapter(
{
accessKeyId: 'my-aws-access-key',
secretAccessKey: 'my-aws-secret-key',
region: 'my-aws-region',
bucket: 'my-bucket',
endpoint: 'https://s3.amazonaws.com', // optional, for S3-compatible services
},
'my-subfolder', // optional prefix
);
`

Benefits of BunAdapter:

- No external dependencies required
- Better performance with Bun's native implementation
- Smaller bundle size
- Native stream support
- Compatible with S3 and S3-compatible services (DigitalOcean Spaces, Cloudflare R2, etc.)

Note: This adapter requires Bun runtime and won't work in Node.js.

$3

`typescript
import * as Storage from '@google-cloud/storage';
import { GoogleStorage } from 'node-filesystem';

const googleStorageClient = new Storage({
projectId: '',
});

process.env.GOOGLE_APPLICATION_CREDENTIALS =
__dirname + '/../gcp-credentials.json';

new GoogleStorage(googleStorageClient, 'my-bucket', 'my-subfolder');
``

$3

You can use the AWS S3 Adapter