fs-blob-storage

fs-blob-storage

Blob storage on a filesystem, with streams and promises API.

Features:

• Simple API
• Read and write file streams
• Partial files
• Safe, atomic operations
• Works with any POSIX or NTFS filesystem
• NFS friendly locking

Requirements

This module requires Node >= 16.

Installation

npm install fs-blob-storage

Additionally for Typescript:

npm install -D @types/node

Usage

import FsBlobStorage, {DEFAULT_EXT, DEFAULT_PART} from "fs-blob-storage"

DEFAULT_EXT

The default ext option is ''

DEFAULT_PART

The default part option is '.part'

constructor

const storage = new FsBlobStorage(options)

Options:

• ext is a default ext argument for methods (optional, default: DEFAULT_EXT)
• part is a default part argument for methods (optional, default: DEFAULT_PART)
• exclusive if is true then can't create new object if already exists with the same key (optional, default: false)
• fs is a File System module (optional, default: require('fs'))
• path is a directory path of the storage (optional, default: '.')

Example:

const storage = new FsBlobStorage({
  part: ".lock",
  path: "/var/spool/mail",
  exclusive: true,
})

createWriteStream

const writable = await storage.createWriteStream(key, options)

Options:

• ext is a default extension added to the file name for the object (optional, default: this.ext)
• part is an extension added to the file name which can be later committed (optional, default: this.part)
• encoding is an encoding for a created file (optional, default: null)

Creates a writable stream for a new object in the storage. An object is stored with the file name based on key, ext and part. Throws an error if has occurred and if the file already exists for exclusive mode.

createReadStream

const readable = await storage.createWriteStream(key, options)

Options:

• ext is a default extension added to the file name for the object (optional, default: '')
• encoding is an encoding for a created file (optional, default: 'utf8')

Creates a readable stream for an existing object in the storage. Throws an error if has occurred or if the object doesn't exist or its size is zero.

commit

await storage.commit(key, options)

Options:

• ext is a default extension added to the file name for the object (optional, default: this.ext)
• part is an extension added to the file name which can be later committed (optional, default: this.part)

Commits the object in the storage. It means that the file name for the object is renamed and the additional extension for partial objects is removed. Throws an error if has occurred or the object doesn't exist.

remove

await storage.remove(key, options)

Options:

• ext is a default extension added to the file name for the object (optional, default: this.ext)

Removes the object from the storage. Throws an error if has occurred or the object doesn't exist.

Bugs

This storage doesn't work correctly on the NTFS filesystem mounted in Linux in VirtualBox. In this case, no partial files should be used.

License

Copyright (c) 2018-2024 Piotr Roszatycki [e-mail]

MIT

Changelog

v4.1.0 2024-06-24

• Refactoring: uses fs.promises API.