@unikvs/fs.bun

How to use @unikvs/fs.bun, which stores byte sequences in the Bun local file system.

Overview

@unikvs/fs.bun is a storage plugin that stores byte sequences in the local file system. Bun only Use it for persistence on a single node or as a simple store during development.

• name is "BunFs", and isOpen reports whether it is open.
• open() creates the root directory and opens it. There is no close().
• Keys are stored as-is as file names. Writes go to a temporary file first and are atomically renamed on completion.

Install it with the following command:

npm install @unikvs/fs.bun

pnpm add @unikvs/fs.bun

yarn add @unikvs/fs.bun

bun add @unikvs/fs.bun

nub add @unikvs/fs.bun

aube add @unikvs/fs.bun

Usage

BunFs implements IStorage. Pass it to UniKvs via persist().

import { BunFs } from "@unikvs/fs.bun";

BunFs

Storage that saves to the local file system. Callers open it with open() before use.

The constructor arguments are as follows:

BunFsOptions

An option type reserved for future use. Currently an empty object with no settable fields.

The following example saves a value and reads it back:

import { BunFs } from "@unikvs/fs.bun";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new BunFs("./data"))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

const data = await kvs.get("file");
console.log(data); // Uint8Array(3) [0, 1, 2]

Data types

• write / read use byte sequences (Uint8Array<ArrayBuffer>).
• Keys are validated as file names; keys containing path separators and similar are rejected.
• Supports streamed reading and writing with Uint8Array<ArrayBuffer> chunks.
• Writes go to a temporary file first and are atomically renamed on completion, so concurrent writes never collide on temporary files.

Errors

This package has no package-specific errors. Opening it on a runtime other than Bun throws the shared @unikvs/core error UnsupportedRuntimeError. Reading or deleting a missing key fails with the ENOENT system error.