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

Write Files

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

Update Files

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

Write or Update Files

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

Read Files

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

Check if a file exists

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.

Delete Files

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

Rename Files

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

Copy Files

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

Get Mimetypes

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

Get Timestamps

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

Get File Sizes

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

Create Directories

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

Directories are also made implicitly when writing to a deeper path

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

Delete Directories

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

The above method will delete directories recursively

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

Manage Visibility

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

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

You can also change and check visibility of existing files

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

List Contents

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:

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

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

Adapters

Local

import { LocalAdapter } from 'node-filesystem';

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

Aws S3

You need install the official AWS SDK v3:

yarn add @aws-sdk/client-s3

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');

Bun S3 (Native)

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!

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.

Google Cloud Storage

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');

DigitalOcean Spaces

You can use the AWS S3 Adapter