@brighter/storage

@brighter/storage is a JavaScript object storage library that:

• enables local development,
• has a simple, concise API,
• is well documented and tested against real infrastructure.

Why is local development important? Most of today's software talks directly to the cloud, even in local environments. This extends the feedback loop and creates a storage provider dependency.

This library offers a different approach. It introduces a unified storage interface that enables seamless switching between providers and a local implementation that shortens the feedback loop during development.

A list of supported object storage providers:

• local and
• any s3 compatible provider (AWS S3, Cloudflare R2, ...).

For more information:

• see the examples,
• track changes in the changelog or
• dive straight into the documentation.

Quick Start

Installation, using npm:

npm i @brighter/storage

Usage:

const { Storage } = require('@brighter/storage')

const storage = Storage({
  type: 'local',
  path: '/tmp/storage'
})

const main = async () => {
  await storage.write('msg', 'hi')
  const msg = await storage.read('msg')
  console.log(msg)
}

main().catch(console.error)

API overview

The aim of the API is to be simple and concise so that's easy to use and remember.

Reading:

let data
data = await storage.read('file')
data = await storage.read('file', { encoding: 'ascii' })
data = await storage.read('file.bin', { encoding: 'binary' })

See ReadFunction for more information.

Writing:

await storage.write('file', 'hi')
await storage.write('file', 'hi', { encoding: 'utf8' })
await storage.write('file', Buffer.alloc(2), { encoding: 'binary' })

See WriteFunction for more information.

Removing:

await storage.remove('file')
await storage.remove('dir/', { recursive: true })
await storage.remove('dir/', { recursive: true, concurrency: 10 })

See RemoveFunction for more information.

Copying:

await storage.copy('file', 'file_copy')
await storage.copy('file', 'dir/')
await storage.copy('dir/', 'dir_copy/')
await storage.copy('dir/', 'dir_copy/', { concurrency: 10 })

See CopyFunction for more information.

Listing:

let data
data = await storage.list('/')
data = await storage.list('/', { recursive: true })
data = await storage.list('/', { recursive: true, absolute: true })
data = await storage.list('/', { recursive: true, absolute: true, concurrency: 10 })

See ListFunction for more information.

Existence:

let data
data = await storage.exists('file')
data = await storage.exists('dir/')

See ExistsFunction for more information.

File Information:

let data
data = await storage.stat('file')

See StatFunction for more information.

Roadmap

• v1.2.0 Azure Blob Storage implementation
• v1.3.0 Google Storage implementation

Testing

npm run test                      # run tests
npm run test -- --provider=local  # run tests for a specific provider

Releasing

npm run release             # set version by bumping the patch number, tag the commit
npm run release -- 1.0.0    # set specific version, tag the commit