@dotdo/fsx

POSIX filesystem implementation in TypeScript. Pure logic. Zero dependencies. Self-hostable.


What is this?

The filesystem logic without the infrastructure. All POSIX operations, path handling, glob patterns, grep, find - implemented in pure TypeScript with no Cloudflare dependencies.

Bring your own storage backend. Run anywhere JavaScript runs.

``typescript
import { MemoryBackend, readFile, writeFile, mkdir } from '@dotdo/fsx'

const backend = new MemoryBackend()

await mkdir('/data', { backend })
await writeFile('/data/config.json', '{}', { backend })
const content = await readFile('/data/config.json', { backend })
`

Installation

`bash
npm install @dotdo/fsx
`

Architecture

`
@dotdo/fsx
├── types.ts # FileEntry, Stats, Dirent, FsCapability
├── errors.ts # ENOENT, EEXIST, EISDIR, ENOTDIR, etc.
├── constants.ts # S_IFREG, S_IFDIR, O_RDONLY, etc.
├── path.ts # normalize, join, resolve, dirname, basename
├── backend.ts # FsBackend interface + MemoryBackend
├── fs/ # POSIX operations (readFile, writeFile, stat, etc.)
├── glob/ # Pattern matching (.ts, /.json)
├── grep/ # Content search
├── find/ # File discovery
└── cas/ # Content-addressable storage
`

FsBackend Interface

Implement this interface to add your own storage:

`typescript
import type { FsBackend, Stats, Dirent } from '@dotdo/fsx'

class MyStorageBackend implements FsBackend {
async readFile(path: string): Promise { ... }
async writeFile(path: string, data: Uint8Array): Promise { ... }
async stat(path: string): Promise { ... }
async readdir(path: string): Promise { ... }
async mkdir(path: string): Promise { ... }
async unlink(path: string): Promise { ... }
async rename(old: string, new_: string): Promise { ... }
async copyFile(src: string, dest: string): Promise { ... }
// ... full interface in backend.ts
}
`

Built-in backends:
- MemoryBackend - In-memory filesystem for testing

Submodule Exports

`typescript
// Core types and errors
import { FileEntry, Stats, ENOENT, EEXIST } from '@dotdo/fsx'

// Path utilities
import { normalize, join, resolve, dirname, basename } from '@dotdo/fsx/path'

// Glob patterns
import { glob, minimatch } from '@dotdo/fsx/glob'

// Grep (content search)
import { grep, grepFile } from '@dotdo/fsx/grep'

// Find (file discovery)
import { find } from '@dotdo/fsx/find'

// Content-addressable storage
import { sha256, compress, decompress } from '@dotdo/fsx/cas'
`

POSIX Compatibility

Full POSIX semantics:

| Operation | Status |
|-----------|--------|
| readFile / writeFile | Complete |
| stat / lstat | Complete |
| readdir | Complete with Dirent |
| mkdir / rmdir | Complete with recursive |
| unlink / rename | Complete |
| chmod / chown | Complete |
| symlink / readlink | Complete |
| link (hard links) | Complete |
| utimes | Complete |
| access | Complete |

Want a managed service?

fsx.do is the managed service built on @dotdo/fsx:

- Durable Object integration
- Tiered storage (SQLite + R2)
- CLI: npx fsx.do ls /
- SDK: import { fs } from 'fsx.do'
- HTTP API
- File watching
- Content streaming

`typescript
// fsx.do re-exports everything from @dotdo/fsx
import { glob, grep, find, MemoryBackend } from 'fsx.do'
``

License

MIT

Links

- fsx.do (managed service)
- npm: @dotdo/fsx
- npm: fsx.do