---
title: "@unikvs/fs.node"
description: "Node.js のローカルファイルシステムにバイト列を保存する @unikvs/fs.node の使い方を説明します。"
---

## 概要 [#overview]

`@unikvs/fs.node` はローカルファイルシステムにバイト列を保存するストレージプラグインです。Node.js 専用 単一ノードでの永続化や、開発時の簡易な保存先として使います。

- `name` は `"NodeFs"` で、`isOpen` で開閉状態を確認します。
- `open()` でルートディレクトリーを作成して開きます。`close()` はありません。
- キーはファイル名としてそのまま保存します。書き込みは一時ファイルへの書き出しと完了時のリネームで原子的に行います。

インストールは次のコマンドで行います。

```package-install
npm install @unikvs/fs.node
```

## 使い方 [#usage]

NodeFs は IStorage を実装しています。UniKvs には persist() で渡します。

```ts
import { NodeFs } from "@unikvs/fs.node";
```

### NodeFs [#nodefs]

ローカルファイルシステムに保存するストレージです。利用者は `open()` で開いてから使います。

コンストラクターの引数は次のとおりです。

| Prop | Type | Default | Description |
| - | - | - | - |
| `root?` | `[#nodefs-root] string` | - | データを保存するルートディレクトリーです。既定値は `".unikvs"` で、`open()` 時に絶対パスへ解決します。 |
| `options?` | `[#nodefs-options] NodeFsOptions` | - | 将来の拡張用のオプションです。現在は空のオブジェクトです。 |

### NodeFsOptions [#nodefsoptions]

将来の拡張用のオプション型です。現在は空のオブジェクトで、指定できる項目はありません。

以下は、値を保存して読み戻す例です。

```ts
import { NodeFs } from "@unikvs/fs.node";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new NodeFs("./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`                         | `Uint8Array<ArrayBuffer>` |
| `getWritable`・`getReadable` のチャンク | `Uint8Array<ArrayBuffer>` |

- `write`・`read` にはバイト列 (`Uint8Array<ArrayBuffer>`) を使います。
- キーはファイル名として検証され、パス区切りなどを含むキーは拒否されます。
- ストリームの読み書きに対応し、チャンクは `Uint8Array<ArrayBuffer>` です。
- 書き込みは一時ファイルへの書き出しと完了時のリネームで原子的に行われ、並行書き込みでも一時ファイルが衝突しません。

## エラー [#errors]

このパッケージ固有のエラーはありません。存在しないキーを読み取ったり削除したりすると、`ENOENT` のシステムエラーで失敗します。