### Run examples locally

Source: https://github.com/jiangjie/happy-opfs/blob/main/README.md

Commands to start the local development server for running examples.

```sh
pnpm run eg
# Open https://localhost:5173
```

--------------------------------

### Quick Start with happy-opfs

Source: https://github.com/jiangjie/happy-opfs/blob/main/README.md

Basic demonstration of creating a directory, writing a file, reading its content, and removing the directory.

```ts
import { mkdir, writeFile, readTextFile, remove } from 'happy-opfs';

// Write and read files
await mkdir('/data');
await writeFile('/data/hello.txt', 'Hello, OPFS!');

(await readTextFile('/data/hello.txt')).inspect((content) => {
    console.log(content); // 'Hello, OPFS!'
});

await remove('/data');
```

--------------------------------

### Install happy-opfs

Source: https://github.com/jiangjie/happy-opfs/blob/main/README.md

Commands to install the package using various package managers or JSR.

```sh
pnpm add happy-opfs
# or
npm install happy-opfs
# or
yarn add happy-opfs
# or via JSR
jsr add @happy-js/happy-opfs
```

--------------------------------

### Testing and Automation Commands

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Commands for executing tests using Vitest and Playwright, including setup and specific execution modes.

```bash
# Install Playwright browsers (first time setup)
pnpm run playwright:install

# Run all tests
pnpm test

# Run tests in watch mode
pnpm run test:watch

# Run tests with UI
pnpm run test:ui

# Run a specific test file
pnpm exec vitest run tests/core.test.ts

# Run tests matching a pattern
pnpm exec vitest run -t "readFile"
```

--------------------------------

### Project Development Commands

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Standard commands for managing dependencies, building the project, and running the development environment.

```bash
# Install dependencies
pnpm install

# Type checking
pnpm run check

# Linting
pnpm run lint

# Build (runs prebuild: check types, lint)
pnpm run build

# Generate documentation
pnpm run docs

# Run examples (opens https://localhost:5173)
pnpm run eg
```

--------------------------------

### Run Worker Benchmark

Source: https://github.com/jiangjie/happy-opfs/blob/main/benchmarks/worker.html

Initiates the Web Worker benchmark when the 'Run Benchmark' button is clicked. It sets up the worker, handles messages and errors, and displays formatted results. Ensure the worker script is correctly referenced.

```javascript
const output = document.getElementById('output');
const runBtn = document.getElementById('run');

function log(message) {
    const line = document.createElement('div');
    line.textContent = message;
    output.appendChild(line);
    console.log(message);
}

function formatResult(result) {
    log(`\n${result.name}`);
    log(` Zip size: ${(result.zipSize / 1024).toFixed(2)} KB`);
    log('');
    log(' zip:');
    log(` Async: ${result.zipAsync.toFixed(2)} ms/op`);
    log(` Sync: ${result.zipSync.toFixed(2)} ms/op`);
    log(` Ratio: ${(result.zipAsync / result.zipSync).toFixed(2)}x (${result.zipAsync < result.zipSync ? 'async faster' : 'sync faster'})
`);
    log(' unzip:');
    log(` Async: ${result.unzipAsync.toFixed(2)} ms/op`);
    log(` Sync: ${result.unzipSync.toFixed(2)} ms/op`);
    log(` Ratio: ${(result.unzipAsync / result.unzipSync).toFixed(2)}x (${result.unzipAsync < result.unzipSync ? 'async faster' : 'sync faster'})
`);
}

runBtn.addEventListener('click', () => {
    output.textContent = '';
    log('=== Worker Benchmark: async vs sync inside Worker ===');
    log('Running benchmarks in Worker thread...');
    runBtn.disabled = true;

    const worker = new Worker(new URL('./worker.ts', import.meta.url), {
        type: 'module'
    });

    worker.onmessage = (e) => {
        const results = e.data;
        for (const result of results) {
            formatResult(result);
        }
        log('\n=== Benchmark Complete ===');
        runBtn.disabled = false;
        worker.terminate();
    };

    worker.onerror = (err) => {
        log(`Error: ${err.message}`);
        runBtn.disabled = false;
        worker.terminate();
    };

    worker.postMessage('start');
});
```

--------------------------------

### Run Performance Benchmarks

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Commands to execute performance benchmarks in interactive, automated, or specific modes.

```bash
# Interactive mode (opens browser at http://localhost:5173)
pnpm run bench

# Automated mode (headless Playwright, outputs to console)
pnpm run bench:run

# Run specific benchmark
pnpm run bench:run -- zip
pnpm run bench:run -- stream

# Vitest bench mode (microbenchmarks)
pnpm run bench:vitest
```

--------------------------------

### Project Directory Structure

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Visual representation of the source code organization, separating shared utilities, async operations, and sync worker communication.

```text
src/
├── mod.ts                      # Main entry point, exports all public APIs
│
├── shared/                     # Shared utilities (thread-agnostic)
│   ├── mod.ts                 # Aggregates shared modules
│   ├── constants.ts           # Application-wide constants
│   ├── defines.ts             # Shared TypeScript type definitions
│   ├── guards.ts              # Type guard functions (isAbsolutePath, etc.)
│   ├── support.ts             # OPFS feature detection
│   ├── tmp.ts                 # Temporary path utilities (generateTempPath, isTempPath)
│   └── internal/              # Internal utilities (@internal tagged)
│       ├── mod.ts             # Aggregates internal modules
│       ├── codec.ts           # UTF-8 encoding/decoding with cached encoders
│       ├── helpers.ts         # Shared helper functions
│       └── validations.ts     # Path/URL validation
│
├── async/                      # Async OPFS operations (main thread)
│   ├── mod.ts                 # Aggregates all async modules
│   ├── core/                  # Core OPFS operations
│   │   ├── mod.ts             # Aggregates core modules
│   │   ├── create.ts          # File/directory creation
│   │   ├── read.ts            # File reading operations
│   │   ├── write.ts           # File writing operations
│   │   ├── remove.ts          # File/directory removal
│   │   └── stat.ts            # File/directory metadata
│   ├── archive/               # Archive operations
│   │   ├── mod.ts             # Aggregates archive modules
│   │   ├── helpers.ts         # Archive helper functions
│   │   ├── zip.ts             # Zip operations
│   │   ├── unzip.ts           # Unzip operations
│   │   ├── zip-stream.ts      # Streaming zip operations
│   │   └── unzip-stream.ts    # Streaming unzip operations
│   ├── transfer/              # File transfer operations
│   │   ├── mod.ts             # Aggregates transfer modules
│   │   ├── download.ts        # Download from URL
│   │   └── upload.ts          # Upload to URL
│   ├── internal/              # Internal utilities (@internal tagged)
│   │   ├── mod.ts             # Aggregates internal modules
│   │   └── helpers.ts         # Internal helpers (handle traversal, error factories)
│   ├── ext.ts                 # Extended operations (copy, move, exists, emptyDir)
│   └── tmp.ts                 # Temporary file operations
│
└── sync/                       # Sync API via Worker communication
    ├── mod.ts                 # Aggregates sync modules
    ├── ops.ts                 # Main thread sync operations (*Sync functions)
    ├── protocol.ts            # SharedArrayBuffer communication protocol
    ├── defines.ts             # Sync-specific types
    └── channel/               # SyncChannel namespace
        ├── mod.ts             # Aggregates channel modules
        ├── connect.ts         # Main thread: connect, attach, isReady
        ├── listen.ts          # Worker thread: request handler
        └── state.ts           # Shared channel state
```

--------------------------------

### Configure .npmrc for JSR

Source: https://github.com/jiangjie/happy-opfs/blob/main/README.md

Required configuration to resolve the @std/path dependency from JSR.

```text
@jsr:registry=https://npm.jsr.io
```

--------------------------------

### Organize Internal Code with #region

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Use #region and #endregion tags to group internal variables, types, and functions within source files.

```typescript
// #region Internal Variables
const SOME_CONSTANT = 'value';
// #endregion

// Public exports
export function publicApi() { ... }

// #region Internal Types
interface InternalConfig { ... }
// #endregion

// #region Internal Functions
function helperFunction() { ... }
// #endregion
```

--------------------------------

### Migrate readFile return type

Source: https://github.com/jiangjie/happy-opfs/blob/main/README.md

Updates the return type from ArrayBuffer to Uint8Array. Use the .buffer property on the result to access the underlying ArrayBuffer.

```ts
// 1.x - default returned ArrayBuffer
const result = await readFile('/path/to/file');

// 2.x - default returns Uint8Array
const result = await readFile('/path/to/file');

// Migration: use .buffer property to get ArrayBuffer if needed
const uint8Array = await readFile('/path/to/file');
const arrayBuffer = uint8Array.unwrap().buffer;
```

--------------------------------

### Replace removed stream APIs

Source: https://github.com/jiangjie/happy-opfs/blob/main/README.md

Replaces the removed readFileStream and writeFileStream methods with the new encoding option and openWritableFileStream function.

```ts
// 1.x
const stream = await readFileStream('/path/to/file');
const writable = await writeFileStream('/path/to/file');

// 2.x
const stream = await readFile('/path/to/file', { encoding: 'stream' });
const writable = await openWritableFileStream('/path/to/file');
```

--------------------------------

### Handle Async Operations with Result Type

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Use the AsyncIOResult pattern to safely handle success and error states from asynchronous file operations.

```typescript
const result = await readFile('/path/to/file');
if (result.isOk()) {
  const content = result.unwrap();
} else {
  const error = result.unwrapErr();
}
```

--------------------------------

### Perform Type Assertions for Uint8Array

Source: https://github.com/jiangjie/happy-opfs/blob/main/AGENTS.md

Explicitly cast data to Uint8Array<ArrayBuffer> when performing write operations to ensure compatibility with v2 API requirements.

```typescript
await writeFile(path, data as Uint8Array<ArrayBuffer>);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.