@auto-engineer/file-store

Platform-agnostic file storage abstraction with in-memory and Node.js implementations.

---

Purpose

Without @auto-engineer/file-store, you would have to write platform-specific file operations, handle path normalization across operating systems, and create separate test implementations for file-dependent code.

This package provides unified interfaces for file system operations. The in-memory implementation enables testing without touching the disk, while the Node.js implementation handles real file operations with automatic directory creation.

---

Installation

``bash
pnpm add @auto-engineer/file-store
`

Quick Start

`typescript
import { InMemoryFileStore } from '@auto-engineer/file-store';

const store = new InMemoryFileStore();

await store.write('/data/file.txt', new TextEncoder().encode('content'));
const data = await store.read('/data/file.txt');

console.log(new TextDecoder().decode(data!));
// → "content"
`

---

How-to Guides

$3

`typescript
import { InMemoryFileStore } from '@auto-engineer/file-store';

const store = new InMemoryFileStore();
await store.write('/input.txt', new TextEncoder().encode('data'));

const exists = await store.exists('/input.txt');
const tree = await store.listTree('/');
`

$3

`typescript
import { NodeFileStore } from '@auto-engineer/file-store/node';

const store = new NodeFileStore();

await store.writeText('config.json', JSON.stringify({ key: 'value' }));
const text = await store.readText('config.json');
`

$3

`typescript
import { NodeFileStore } from '@auto-engineer/file-store/node';

const store = new NodeFileStore();
const tree = await store.listTree('/project', {
pruneDirRegex: /node_modules|\.git/,
includeSizes: true,
});
`

$3

`typescript
import type { IFileStore } from '@auto-engineer/file-store';

class DocumentManager {
constructor(private store: IFileStore) {}

async save(id: string, content: string): Promise {
await this.store.write(/docs/${id}.json, new TextEncoder().encode(content));
}
}
`

---

API Reference

$3

`typescript
import { InMemoryFileStore, type IFileStore, type IExtendedFileStore } from '@auto-engineer/file-store';

import { NodeFileStore } from '@auto-engineer/file-store/node';
`

$3

| Entry Point | Import Path | Description |
|-------------|-------------|-------------|
| Main | @auto-engineer/file-store | Platform-agnostic (InMemoryFileStore, types) |
| Node | @auto-engineer/file-store/node | Node.js-specific (NodeFileStore) |

$3

`typescript
interface IFileStore {
write(path: string, data: Uint8Array): Promise;
read(path: string): Promise;
exists(path: string): Promise;
listTree(root?: string, opts?: ListTreeOptions): Promise;
remove(path: string): Promise;
}
`

$3

`typescript
interface IExtendedFileStore extends IFileStore {
ensureDir(path: string): Promise;
readdir(path: string): Promise;
readText(path: string): Promise;
writeText(path: string, text: string): Promise;
join(...parts: string[]): string;
dirname(p: string): string;
fromHere(relative: string, base?: string): string;
}
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| followSymlinkDirs | boolean | true | Traverse symlinked directories |
| includeSizes | boolean | true | Include file sizes |
| pruneDirRegex | RegExp | - | Skip matching directories |

---

Architecture

`
src/
├── index.ts
├── node.ts
├── types.ts
├── path.ts
├── InMemoryFileStore.ts
└── NodeFileStore.ts
`

$3

- Binary-first API: Core operations use Uint8Array for compatibility
- Null over exceptions: Read returns null` for missing files
- POSIX normalization: All paths use forward slashes
- Auto directory creation: Write creates parent directories

$3

This package has zero external dependencies. It uses only Node.js built-in modules.