@unikvs/fs.bun

Bun のローカルファイルシステムにバイト列を保存するストレージプラグインの使い方を説明します。

概要

@unikvs/fs.bun は、Bun のローカルファイルシステムに保存するストレージプラグインです。指定したルートディレクトリー配下にキーをファイル名として保存します。Bun 専用

扱うデータはバイト列専用です。write は Uint8Array<ArrayBuffer> を受け付け、read は Uint8Array<ArrayBuffer> を返します。ファイルの読み書きには Bun.file の bytes()・write()・writer() を使い、ディレクトリー操作とリネームには node:fs/promises、パス操作には node:path を動的インポートして使います。一時ファイル名の生成には Bun.randomUUIDv7() を使います。

インストールは次のように行います。

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

依存関係として @unikvs/core と @unikvs/utils を使用します。

使い方

中心は BunFs クラスです。

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

public constructor(root: string = ".unikvs", options: BunFsOptions = {})

root は保存先のルートディレクトリーです。相対パスは open() 実行時にカレントディレクトリー基準で解決します。既定値は ".unikvs" です。

options.allowRepair は書き戻しによる書き込みを許可するかどうかです。既定値は false です。false を指定すると、書き戻し（vars["unikvs:repair"] が true）の write・getWritable は RepairNotAllowedError で失敗します。

主なメンバーは次のとおりです。

• name は "BunFs" です。
• allowRepair は書き戻しによる書き込みを許可するかどうかを示します。
• isOpen はオープン済みかどうかを示します。
• open() はルートディレクトリーを再帰的に作り、読み書き可能にします。
• write・read・exists・delete・clear で読み書きします。

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

const storage = new BunFs("./.tmp/unikvs-fs-bun");
await storage.open();

await storage.write({
  key: "hello.bin",
  data: new TextEncoder().encode("hello"),
});

const data = await storage.read({ key: "hello.bin" });
console.log(new TextDecoder().decode(data));

ファイル配置

キーからファイルパスへの対応は次のとおりです。ルート直下にキーがそのまま並び、サブディレクトリーは作りません。

ファイル名の検証には @unikvs/utils の assertValidFilename を使います。無効なキーでは InvalidFilenameError を投げます。

ストリーム

読み書きどちらのストリームにも対応しています。

注意点

• Bun 専用です。Bun グローバルが無いランタイムでは open() が UnsupportedRuntimeError で失敗します。
• open() 前に操作しないでください。isOpen で確認できます。
• 存在しないファイルの読み取りや削除はエラーになります。

エラー

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

const storage = new BunFs();

try {
  await storage.open();
} catch (error) {
  if (error instanceof UnsupportedRuntimeError) {
    console.error("Bun ランタイムで実行してください");
  } else {
    throw error;
  }
}

使用例

.tmp/ 配下に保存する最小完動例です。

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

const storage = new BunFs("./.tmp/unikvs-fs-bun-example");
await storage.open();

const key = "greeting.bin";
await storage.write({
  key,
  data: new TextEncoder().encode("hello, BunFs"),
});

if (await storage.exists({ key })) {
  const data = await storage.read({ key });
  console.log(new TextDecoder().decode(data));
}

await storage.delete({ key });
await storage.clear();