README.md

Storage 🗃️

The Athenna filesystem provider.

Links

For project documentation click here. If something is not clear in the documentation please open an issue in the documentation repository

Usage

import { Storage } from '@athenna/storage'

await Storage.put('avatars/user.png', buffer, { contentType: 'image/png' })
await Storage.disk('s3').putStream('videos/movie.mp4', stream, { onProgress: p => console.log(p.loaded) })
await Storage.putFromUrl('avatars/user.png', 'https://example.com/user.png')

const text = await Storage.get('notes.txt')
const buffer = await Storage.getBuffer('avatars/user.png', { range: { start: 0, end: 11 } })
const stream = await Storage.getStream('videos/movie.mp4')
const { size, contentType, lastModified, etag, metadata } = await Storage.stat('avatars/user.png')
const { files, nextCursor } = await Storage.list('avatars/', { limit: 100 })

await Storage.copy('a.png', 'b.png')
await Storage.disk('s3_private').move('videos/1.mp4', 'videos/1.mp4', { toDisk: 's3' })
await Storage.delete('b.png')
await Storage.deleteAll('tmp/')

Storage.disk('s3').url('avatars/user.png')       // https://cdn.example.com/avatars/user.png
Storage.disk('s3').parseUrl(url)                 // 'avatars/user.png' or null
await Storage.disk('s3').getSignedUrl('uploads/user.png', { method: 'put', expiresIn: 300 })

Configuration

disks: {
  fs: { driver: 'fs', root: Path.storage(), url: Env('STORAGE_FS_URL') },
  s3: {
    driver: 's3',
    bucket: Env('AWS_S3_BUCKET_NAME', ''),
    region: Env('AWS_REGION', ''),
    credentials: {
      accessKeyId: Env('AWS_ACCESS_KEY_ID', ''),
      secretAccessKey: Env('AWS_SECRET_ACCESS_KEY', '')
    },
    url: Env('AWS_S3_PUBLIC_URL')
  }
}

Declare one disk per bucket (s3, s3_private, ...). The optional url is the public base URL returned by url() (a CDN or custom domain). The legacy key/secret options are still accepted and mapped to credentials.

Testing

STORAGE_DISK=fake

The fake driver is a real in-memory disk: put/get/exists/stat/list work on the static FakeDriver.files map. Inspect it in your assertions, call FakeDriver.clear() between tests and stub what you need with Mock.when(FakeDriver, 'getSignedUrl'), the same pattern used by the fake drivers of @athenna/database, @athenna/mail and @athenna/queue.

Contributing

If you want to contribute to this project, first read the CONTRIBUTING.MD file. It will be a pleasure to receive your help.

---

With 💜 by Athenna community