@atlex/storage

@atlex/storage

Filesystem abstraction for local, S3, and Cloudflare R2 storage.

Installation

npm install @atlex/storage
# or
yarn add @atlex/storage

Quick Start

import { StorageManager } from '@atlex/storage'
import { LocalDriver } from '@atlex/storage'

const manager = new StorageManager()
manager.disk('local', new LocalDriver({ root: './storage' }))

const disk = manager.disk('local')

// Write file
await disk.put('users/avatar.jpg', fileContent)

// Read file
const content = await disk.get('users/avatar.jpg')

// Check existence
const exists = await disk.exists('users/avatar.jpg')

// Delete file
await disk.delete('users/avatar.jpg')

// Get file URL
const url = disk.url('users/avatar.jpg')

Features

• Multi-Driver Support: Local, S3, Cloudflare R2
• Unified API: Same interface across all storage drivers
• File Operations: Read, write, delete, copy, move files
• Directory Management: Create and delete directories
• Metadata: Get file size, MIME type, visibility, last modified time
• Presigned URLs: Generate temporary signed URLs via getPresignedUrl() (S3 and R2)
• File Uploads: Seamless handling of multipart file uploads
• Visibility Control: Set public/private file visibility
• Content Streaming: Stream file content for large files

Basic File Operations

Reading Files

import { StorageManager } from '@atlex/storage'
import { LocalDriver } from '@atlex/storage'

const manager = new StorageManager()
const disk = manager.disk('local', new LocalDriver({ root: './storage' }))

// Read entire file as string
const content = await disk.get('path/to/file.txt')

// Read file as bytes/buffer
const buffer = await disk.getBytes('path/to/file.jpg')

// Check if file exists
const exists = await disk.exists('path/to/file.txt')
const missing = await disk.missing('path/to/file.txt')

Writing Files

const disk = manager.disk('local')

// Write string content
await disk.put('path/to/file.txt', 'Hello, World!')

// Write buffer content
const buffer = Buffer.from('binary data')
await disk.put('path/to/file.bin', buffer)

// Append to file
await disk.append('logs/app.log', 'Log message\n')

// Write with visibility
await disk.put('public/image.jpg', buffer, { visibility: 'public' })

File Management

const disk = manager.disk('local')

// Copy file
await disk.copy('original.txt', 'backup.txt')

// Move file
await disk.move('old/location.txt', 'new/location.txt')

// Delete file
await disk.delete('path/to/file.txt')

// Delete directory (recursively)
await disk.deleteDirectory('path/to/directory')

// Create directory
await disk.makeDirectory('new/directory/path')

File Metadata

const disk = manager.disk('local')

// Get file size in bytes
const size = await disk.size('file.txt')

// Get MIME type
const mimeType = await disk.mimeType('image.jpg')

// Get last modification time
const modified = await disk.lastModified('file.txt')

// Get file visibility
const visibility = await disk.getVisibility('file.txt')

// Set file visibility
await disk.setVisibility('file.txt', 'public')

Working with URLs

const disk = manager.disk('local')

// Get public URL (if accessible)
const url = disk.url('public/image.jpg')
// Returns: /storage/public/image.jpg

// Generate temporary signed URL (S3/GCS)
const tempUrl = disk.temporaryUrl('private/document.pdf', {
  expiresIn: 3600, // 1 hour
})

Directory Operations

const disk = manager.disk('local')

// List directory contents
const files = await disk.listContents('uploads')
// Returns: [
//   { path: 'uploads/file1.txt', type: 'file', size: 1024 },
//   { path: 'uploads/subdir', type: 'dir' }
// ]

// List recursively
const allFiles = await disk.listContents('uploads', { recursive: true })

// Create nested directories
await disk.makeDirectory('uploads/users/profiles')

Local Driver

import { LocalDriver } from '@atlex/storage'
import path from 'path'

const driver = new LocalDriver({
  root: path.join(__dirname, '../storage'),
  public: path.join(__dirname, '../public/storage'),
})

const manager = new StorageManager()
manager.disk('local', driver)

S3 Driver

import { S3Driver } from '@atlex/storage'

const driver = new S3Driver({
  key: process.env.AWS_ACCESS_KEY_ID,
  secret: process.env.AWS_SECRET_ACCESS_KEY,
  bucket: process.env.AWS_BUCKET,
  region: process.env.AWS_REGION,
  endpoint: 'https://s3.amazonaws.com',
})

const manager = new StorageManager()
manager.disk('s3', driver)

const disk = manager.disk('s3')
await disk.put('uploads/file.txt', 'content')

const url = disk.url('uploads/file.txt')
const tempUrl = disk.temporaryUrl('uploads/file.txt', { expiresIn: 3600 })

Cloudflare R2 Driver

@atlex/storage v0.1.7 adds R2Driver — a Cloudflare R2 driver that extends S3Driver with automatic endpoint derivation. R2 is S3-compatible, but credentials come from Cloudflare R2 API tokens (not AWS IAM), and the endpoint is always https://{accountId}.r2.cloudflarestorage.com.

Install the AWS SDK peer dependencies if not already present:

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Configuration via StorageManager

import { StorageManager } from '@atlex/storage'

const manager = StorageManager.fromConfig(
  {
    default: 'r2',
    disks: {
      r2: {
        driver: 'r2',
        bucket: process.env.R2_BUCKET!,
        url: process.env.R2_PUBLIC_URL ?? '', // optional CDN URL
        accountId: process.env.R2_ACCOUNT_ID!,
        accessKeyId: process.env.R2_ACCESS_KEY_ID!,
        secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
      },
    },
  },
  app.basePath,
)

const disk = manager.disk('r2')

Usage

// Upload a file
await disk.put('voice/familyId/messageId.m4a', buffer)

// Generate a presigned GET URL (expires in 1 hour)
const url = await disk.getPresignedUrl('voice/familyId/messageId.m4a', { expiresIn: 3600 })

// Delete a file
await disk.delete('voice/familyId/messageId.m4a')

// Check existence, copy, move — all S3Driver operations are inherited
const exists = await disk.exists('voice/familyId/messageId.m4a')

Direct Driver Instantiation

import { R2Driver } from '@atlex/storage'

const driver = new R2Driver({
  accountId: process.env.R2_ACCOUNT_ID!,
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  bucket: process.env.R2_BUCKET!,
  url: process.env.R2_PUBLIC_URL ?? '',
})
// Endpoint is auto-derived: https://{accountId}.r2.cloudflarestorage.com

Presigned URLs on S3

The same getPresignedUrl convenience method is available on any disk backed by S3Driver:

const s3Disk = manager.disk('s3')
const signedUrl = await s3Disk.getPresignedUrl('uploads/report.pdf', { expiresIn: 900 })

Memory Driver

import { MemoryDriver } from '@atlex/storage'

const driver = new MemoryDriver()

const manager = new StorageManager()
manager.disk('memory', driver)

const disk = manager.disk('memory')
await disk.put('temp/data.json', JSON.stringify({ test: true }))

Handling File Uploads

UploadedFile API

import { UploadedFile } from '@atlex/storage'

class UserController {
  async uploadAvatar(file: UploadedFile) {
    // Get file info
    const originalName = file.originalName
    const extension = file.extension
    const mimeType = file.mimeType
    const size = file.size

    // Get file stream
    const stream = file.stream()

    // Get file buffer
    const buffer = await file.buffer()

    // Store file
    const path = `avatars/${Date.now()}.${extension}`
    await file.store(path, 'local')

    return { path, originalName }
  }
}

Parsing Multipart Uploads

import { parseUploads } from '@atlex/storage'
import { Request } from '@atlex/http'

async function handleUpload(req: Request) {
  const uploads = await parseUploads(req)

  const avatar = uploads.file('avatar')
  if (avatar) {
    const path = await avatar.store('avatars', 'local')
    console.log('Saved to:', path)
  }

  const documents = uploads.files('documents')
  for (const doc of documents) {
    await doc.store('documents', 's3')
  }
}

StorageManager Configuration

import { StorageManager } from '@atlex/storage'
import { LocalDriver, S3Driver } from '@atlex/storage'
import { FilesystemsConfig } from '@atlex/storage'

const config: FilesystemsConfig = {
  default: 'local',
  disks: {
    local: {
      driver: 'local',
      root: './storage',
    },
    public: {
      driver: 'local',
      root: './public/storage',
      url: '/storage',
    },
    s3: {
      driver: 's3',
      key: process.env.AWS_ACCESS_KEY_ID,
      secret: process.env.AWS_SECRET_ACCESS_KEY,
      region: process.env.AWS_REGION,
      bucket: process.env.AWS_BUCKET,
    },
  },
}

const manager = StorageManager.fromConfig(config)

// Use default disk
const disk = manager.disk()

// Switch disks at runtime
const publicDisk = manager.disk('public')
const s3Disk = manager.disk('s3')

// Replace disk driver
manager.replaceDisk('local', new LocalDriver({ root: './new-storage' }))

Complete Example

import { StorageManager } from '@atlex/storage'
import { LocalDriver, S3Driver } from '@atlex/storage'
import path from 'path'

class FileService {
  private storage: StorageManager

  constructor() {
    this.storage = new StorageManager()
    this.setupDisks()
  }

  private setupDisks() {
    const env = process.env.NODE_ENV || 'development'

    // Local storage for development
    this.storage.disk(
      'local',
      new LocalDriver({
        root: path.join(__dirname, '../storage'),
        public: path.join(__dirname, '../public/storage'),
      }),
    )

    // S3 for production
    if (env === 'production') {
      this.storage.disk(
        's3',
        new S3Driver({
          key: process.env.AWS_ACCESS_KEY_ID!,
          secret: process.env.AWS_SECRET_ACCESS_KEY!,
          bucket: process.env.AWS_BUCKET!,
          region: process.env.AWS_REGION!,
        }),
      )
    }
  }

  async uploadUserAvatar(userId: string, file: UploadedFile) {
    const disk = this.storage.disk()

    // Validate file
    if (!['image/jpeg', 'image/png'].includes(file.mimeType)) {
      throw new Error('Only JPEG and PNG images are allowed')
    }

    if (file.size > 5 * 1024 * 1024) {
      throw new Error('File must be less than 5MB')
    }

    // Generate filename
    const filename = `${userId}-${Date.now()}.${file.extension}`
    const path = `avatars/${filename}`

    // Store file
    await disk.put(path, await file.buffer(), {
      visibility: 'public',
    })

    return {
      path,
      url: disk.url(path),
      mimeType: file.mimeType,
      size: file.size,
    }
  }

  async deleteOldFiles(directory: string, days: number = 30) {
    const disk = this.storage.disk()
    const cutoffTime = Date.now() - days * 24 * 60 * 60 * 1000

    const files = await disk.listContents(directory, { recursive: true })

    for (const file of files) {
      if (file.type === 'file') {
        const lastModified = await disk.lastModified(file.path)
        if (lastModified.getTime() < cutoffTime) {
          await disk.delete(file.path)
          console.log(`Deleted: ${file.path}`)
        }
      }
    }
  }

  async getTemporaryAccessUrl(filePath: string, expiresIn: number = 3600) {
    const disk = this.storage.disk()
    return disk.temporaryUrl(filePath, { expiresIn })
  }
}

export default new FileService()

API Overview

StorageManager

Method	Description
disk(name?)	Get or set a storage disk
fromConfig(config)	Create manager from configuration
replaceDisk(name, driver)	Replace a disk driver

Disk

Method	Description
exists(path)	Check if file exists
missing(path)	Check if file is missing
get(path)	Read file as string
getBytes(path)	Read file as buffer
put(path, content, options?)	Write file
putFile(path, file)	Write from file
delete(path)	Delete file
deleteDirectory(path)	Delete directory recursively
makeDirectory(path)	Create directory
append(path, content)	Append to file
copy(from, to)	Copy file
move(from, to)	Move file
getVisibility(path)	Get file visibility
setVisibility(path, visibility)	Set file visibility
url(path)	Get public URL
temporaryUrl(path, expiresInSeconds)	Get temporary signed URL (low-level)
getPresignedUrl(key, { expiresIn })	Get presigned GET URL (convenience wrapper)
lastModified(path)	Get last modification time
size(path)	Get file size
mimeType(path)	Get MIME type
listContents(path, options?)	List directory contents

Drivers

Driver	Description
LocalDriver	File system storage
S3Driver	Amazon S3 storage (with presigned URLs)
R2Driver	Cloudflare R2 storage (extends S3Driver)
MemoryDriver	In-memory storage (testing)

Documentation

For complete documentation, visit https://atlex.dev/guide/storage

License

MIT

Part of Atlex — A modern framework for Node.js.