Localdrive

Localdrive exposes a local directory through an API that closely matches Hyperdrive. It is the simplest way to mirror between on-disk files and distributed drives with Mirrordrive. For upstream implementation details, see the Localdrive repository.

Install

npm i localdrive

Quickstart

import Localdrive from 'localdrive'

const drive = new Localdrive('./site')

await drive.put('/index.html', Buffer.from('<h1>Hello</h1>'))
const html = await drive.get('/index.html')

console.log(html?.toString())
console.log(await drive.entry('/index.html'))

API Reference

Constructor and lifecycle

new Localdrive(root, [options])

src

Creates a drive based on a root directory. root can be relative or absolute.

await drive.ready()

src

Resolves immediately. It exists for compatibility with drive-like APIs such as Hyperdrive.

• Returns: Promise<void> — Resolves immediately.

await drive.ready()

await drive.close()

src

Resolves immediately. Localdrive does not keep a background storage process open.

• Returns: Promise<void> — Resolves immediately.

await drive.close()

await drive.flush()

src

Resolves immediately. It exists so code written for batched drive APIs can treat Localdrive as a drop-in target.

• Returns: Promise<void> — Resolves immediately.

await drive.flush()

Drive properties

drive.root

src

String with the resolved (absolute) drive path.

• Returns: string

drive.supportsMetadata

src

Boolean that indicates if the drive handles or not metadata. Default false.

• Returns: boolean

Compatibility helpers

drive.batch()

src

Returns the same Localdrive instance. This lets batch-oriented code reuse a Localdrive target without branching.

• Returns: Localdrive — This drive instance.

const batch = drive.batch()
await batch.put('/file.txt', Buffer.from('hello'))
// on Localdrive, batch === drive

drive.checkout()

src

Returns the same Localdrive instance. Unlike Hyperdrive, Localdrive does not expose historical versions.

• Returns: Localdrive — This drive instance.

const snapshot = drive.checkout()
// on Localdrive, snapshot === drive

drive.toPath(key)

src

Resolves a drive path such as '/images/logo.png' to its local filesystem path under drive.root.

• Returns: string — Absolute filesystem path for the given key.

const drive = new Localdrive('/srv/data')
drive.toPath('/images/logo.png') // => '/srv/data/images/logo.png'

Reading and writing entries

await drive.entry(name, [options])

src

Resolves with the entry stored at key, or null if no entry exists.

• Returns: Promise<object\|null> — the entry at name path in the drive.

await drive.get(key, [options])

src

Reads the file at key and resolves with its contents as a Buffer, or null if no file exists (also null for symbolic links).

• Returns: Promise<Buffer\|null> — the blob at key path in the drive.

const buffer = await drive.get('/blob.txt')
console.log(buffer.toString()) // => 'example'

await drive.put(key, buffer, [options])

src

Creates a file at key path in the drive. options are the same as in createWriteStream.

• Returns: Promise<void> — Resolves when the file has been fully written and closed.

await drive.put('/blob.txt', Buffer.from('example'))
await drive.put('/images/logo.png', Buffer.from('..'), { executable: false })

await drive.del(key)

src

Deletes the file at key path from the drive.

• Returns: Promise<void> — Resolves when the file and any empty parent directories have been removed.

await drive.del('/images/old-logo.png')

await drive.symlink(key, linkname)

src

Creates an entry in drive at key path that points to the entry at linkname.

• Returns: Promise<void> — Resolves when the symlink entry has been created.

await drive.symlink('/images/logo.shortcut', '/images/logo.png')

await drive.exists(name)

src

Resolves to true when drive.entry(key) resolves to a non-null entry, otherwise false.

• Returns: Promise<boolean> — Whether an entry exists at the given path.

const found = await drive.exists('/blob.txt')
console.log(found) // => true or false

drive.compare(entryA, entryB)

src

Compares two drive entries by modification time.

• Returns: number — 1 if entryA is newer, -1 if entryB is newer, and 0 if they are equal.

const entryA = await drive.entry('/file-a.txt')
const entryB = await drive.entry('/file-b.txt')
const result = drive.compare(entryA, entryB)
// result: 0 (same), 1 (a is newer), or -1 (b is newer)

Listing and mirroring

await drive.list([folder], [options])

src

Returns a stream of entries for files under folder (defaults to the whole drive).

• Returns: AsyncIterable<object> — a stream of all entries in the drive inside of specified folder.

await drive.readdir([folder])

src

Returns an async iterator that yields the immediate child names (not full paths) under folder. Only non-empty sub-directories and files with a valid entry are included.

• Returns: AsyncIterable<string> — a stream of all subpaths of entries in drive stored at paths prefixed by folder.

for await (const name of drive.readdir('/images')) {
  console.log(name) // => 'logo.png', 'banner.jpg', ...
}

drive.mirror(out, [options])

src

Efficiently mirror this drive into another. Returns a MirrorDrive instance constructed with options.

• Returns: MirrorDrive — A MirrorDrive instance that runs the mirror operation.

const src = new Localdrive('./source')
const dst = new Localdrive('./destination')
const mirror = src.mirror(dst)
await mirror.done()

Stream APIs

drive.createReadStream(key, [options])

src

Returns a readable stream of the file stored at key.

• Returns: FileReadStream — a stream to read out the blob stored in the drive at key path.

drive.createWriteStream(key, [options])

src

Stream a blob into the drive at key path.

• Returns: FileWriteStream — Writable stream targeting the given key.

Types

LocaldriveOptions

Options for creating a Localdrive instance.

EntryOptions

Options for drive.entry().

GetOptions

Options for drive.get().

WriteStreamOptions

Options for drive.put() and drive.createWriteStream().

ListOptions

Options for drive.list().

ReadStreamOptions

Options for drive.createReadStream().

MirrorOptions

Options for drive.mirror().

See also

• Create a full peer-to-peer filesystem with Hyperdrive—shows Localdrive mirroring in a full writer/reader flow.
• Hyperdrive—the distributed filesystem API Localdrive is designed to interoperate with.
• Mirrordrive—the sync engine that copies between Localdrive and Hyperdrive.
• Drives—CLI tool that mirrors between local directories and Hyperdrives using the same drive-like interface.
• Upstream Localdrive repository—source, releases, and implementation details.