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

const drive = new Localdrive(root, [options])

API definition on GitHub

• Signature: const drive = new Localdrive(root, [options]) (GitHub)
• Parameters: root is the local directory to expose. options.followLinks follows symlinks during entry resolution, options.followExternalLinks permits following symlinks that leave root, options.metadata can be either a { get, put, del } hook object or a Map, and options.atomic writes through temporary files before renaming into place. (GitHub)
• Returns: A Localdrive instance rooted at the resolved absolute path. (GitHub)
• Example:

const metadata = new Map()

const drive = new Localdrive('./assets', {
  atomic: true,
  metadata
})

await drive.ready()

API definition on GitHub

• Signature: await drive.ready() (GitHub)
• Parameters: None. (GitHub)
• Returns: A promise that resolves immediately. It exists for compatibility with drive-like APIs such as Hyperdrive. (GitHub)
• Example:

await drive.ready()

await drive.close()

API definition on GitHub

• Signature: await drive.close() (GitHub)
• Parameters: None. (GitHub)
• Returns: A promise that resolves immediately. Localdrive does not keep a background storage process open. (GitHub)
• Example:

await drive.close()

await drive.flush()

API definition on GitHub

• Signature: await drive.flush() (GitHub)
• Parameters: None. (GitHub)
• Returns: A promise that resolves immediately. It exists so code written for batched drive APIs can treat Localdrive as a drop-in target. (GitHub)
• Example:

await drive.flush()

Drive properties

drive.root

API definition on GitHub

• Returns: The resolved absolute filesystem path backing the drive. (GitHub)

drive.supportsMetadata

API definition on GitHub

• Returns: true when metadata hooks were configured, otherwise false. (GitHub)

Compatibility helpers

const batch = drive.batch()

API definition on GitHub

• Signature: const batch = drive.batch() (GitHub)
• Parameters: None. (GitHub)
• Returns: The same Localdrive instance. This lets batch-oriented code reuse a Localdrive target without branching. (GitHub)
• Example:

const batch = drive.batch()
await batch.put('/a.txt', Buffer.from('a'))
await batch.flush()

const snapshot = drive.checkout()

API definition on GitHub

• Signature: const snapshot = drive.checkout() (GitHub)
• Parameters: None. (GitHub)
• Returns: The same Localdrive instance. Unlike Hyperdrive, Localdrive does not expose historical versions. (GitHub)
• Example:

const snapshot = drive.checkout()
console.log(snapshot === drive)

const filename = drive.toPath(key)

API definition on GitHub

• Signature: const filename = drive.toPath(key) (GitHub)
• Parameters: key is a drive path such as '/images/logo.png'. (GitHub)
• Returns: The resolved local filesystem path for that key under drive.root. (GitHub)
• Example:

console.log(drive.toPath('/images/logo.png'))

Reading and writing entries

const entry = await drive.entry(key, [options])

API definition on GitHub

• Signature: const entry = await drive.entry(key, [options]) (GitHub)
• Parameters: key is the drive path to inspect. options.follow follows symlink chains up to 16 hops before throwing a recursive-link error. (GitHub)
• Returns: An entry object with key, mtime, and value fields (executable, linkname, blob, metadata), or null when the path is missing or resolves to a directory. (GitHub)
• Example:

const entry = await drive.entry('/index.html')
console.log(entry?.value.blob?.byteLength)

const buffer = await drive.get(key, [options])

API definition on GitHub

• Signature: const buffer = await drive.get(key, [options]) (GitHub)
• Parameters: key is the path to read. options are forwarded to drive.entry(...), including follow for symlink-aware lookups. (GitHub)
• Returns: A Buffer containing the file contents, or null if the path is missing or points at a symlink rather than file data. (GitHub)
• Example:

const buffer = await drive.get('/index.html')
console.log(buffer?.toString())

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

API definition on GitHub

• Signature: await drive.put(key, buffer, [options]) (GitHub)
• Parameters: key is the destination path. buffer is the file content to write. options.executable sets executable mode bits and options.metadata stores metadata through the configured metadata hooks. (GitHub)
• Returns: A promise that resolves once the write stream closes and the file is fully persisted. (GitHub)
• Example:

await drive.put('/bin/run.sh', Buffer.from('#!/usr/bin/env sh\necho hi\n'), {
  executable: true,
  metadata: { type: 'shell' }
})

await drive.del(key)

API definition on GitHub

• Signature: await drive.del(key) (GitHub)
• Parameters: key is the path to remove. (GitHub)
• Returns: A promise that resolves after the file is deleted. Missing files are ignored. (GitHub)
• Example:

await drive.del('/old/index.html')

await drive.symlink(key, linkname)

API definition on GitHub

• Signature: await drive.symlink(key, linkname) (GitHub)
• Parameters: key is the symlink entry to create. linkname is the target path, either inside the drive or a relative path. (GitHub)
• Returns: A promise that resolves after the symlink is created. (GitHub)
• Example:

await drive.symlink('/current', '/releases/v2')

const exists = await drive.exists(key)

API definition on GitHub

• Signature: const exists = await drive.exists(key) (GitHub)
• Parameters: key is the path to check. (GitHub)
• Returns: true when drive.entry(key) resolves to a non-null entry, otherwise false. (GitHub)
• Example:

const exists = await drive.exists('/index.html')

const comparison = drive.compare(entryA, entryB)

API definition on GitHub

• Signature: const comparison = drive.compare(entryA, entryB) (GitHub)
• Parameters: entryA and entryB are entry objects returned by drive.entry(...) or yielded by drive.list(...). (GitHub)
• Returns: 1 when entryA is newer, -1 when entryB is newer, or 0 when their modification times match. (GitHub)
• Example:

const previous = await drive.entry('/v1.txt')
const current = await drive.entry('/v2.txt')

console.log(drive.compare(previous, current))

Listing and mirroring

const iterator = drive.list([folder], [options])

API definition on GitHub

• Signature: const iterator = drive.list([folder], [options]) (GitHub)
• Parameters: folder optionally scopes the walk to one subtree. options.ignore can be a function, string, or array of paths to skip. (GitHub)
• Returns: An async iterator of full entry objects for every non-directory entry under the requested subtree. (GitHub)
• Example:

for await (const entry of drive.list('/images', { ignore: '/images/tmp' })) {
  console.log(entry.key)
}

const iterator = drive.readdir([folder])

API definition on GitHub

• Signature: const iterator = drive.readdir([folder]) (GitHub)
• Parameters: folder optionally scopes the listing to one directory prefix. (GitHub)
• Returns: An async iterator of child path names under that folder. (GitHub)
• Example:

for await (const name of drive.readdir('/images')) {
  console.log(name)
}

const mirror = drive.mirror(out, [options])

API definition on GitHub

• Signature: const mirror = drive.mirror(out, [options]) (GitHub)
• Parameters: out is another drive-like destination such as Hyperdrive or another Localdrive. options are passed to Mirrordrive. (GitHub)
• Returns: A MirrorDrive instance. Call await mirror.done() or iterate over it to watch diffs as they apply. (GitHub)
• Example:

const mirror = drive.mirror(otherDrive, { prune: true })
await mirror.done()

Stream APIs

const rs = drive.createReadStream(key, [options])

API definition on GitHub

• Signature: const rs = drive.createReadStream(key, [options]) (GitHub)
• Parameters: key is the file path to stream. options.start, options.end, and options.length select the byte range to read. (GitHub)
• Returns: A readable stream for the target file. (GitHub)
• Example:

for await (const chunk of drive.createReadStream('/index.html')) {
  console.log(chunk)
}

const ws = drive.createWriteStream(key, [options])

API definition on GitHub

• Signature: const ws = drive.createWriteStream(key, [options]) (GitHub)
• Parameters: key is the file path to write. options.executable controls the output mode bits and options.metadata updates the metadata hooks when the stream finishes. (GitHub)
• Returns: A writable stream that writes into the drive and, when atomic mode is enabled, renames a temporary file into place on close. (GitHub)
• Example:

const ws = drive.createWriteStream('/notes.txt', {
  metadata: { section: 'docs' }
})

ws.end('hello from a stream')

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.