sqlite-appfile

SQLite-based application file format for Node.js. Store files, metadata, and app state in one portable .appfile.

Installation

npm install sqlite-appfile

pnpm add sqlite-appfile

yarn add sqlite-appfile

Requirements

• Node.js >= 22.13.0 (uses built-in node:sqlite)

Quick Start

import { AppFile } from 'sqlite-appfile';

const app = AppFile.create('myproject.appfile');

app.writeText('/readme.txt', 'Hello sqlite-appfile');
app.writeJson('/config.json', { version: '1.0.0', theme: 'light' });

const config = app.readJson<{ version: string; theme: string }>('/config.json');
console.log(config.theme); // light

console.log(app.listFiles());
// ['/config.json', '/readme.txt']

app.close();

Why SQLite

• Reference: https://sqlite.org/appfileformat.html

SQLite works well as an application file format when you want a single file, safe atomic writes, and incremental updates instead of rewriting whole archives. It also gives you a well-documented, cross-platform format with standard tooling.

Core Features

• Single-file document model
• Binary/text/JSON read and write APIs
• Per-file metadata and app-level metadata
• Atomic transactions and schema migrations
• Tree navigation (getTree, listDir)
• Read-only open mode for safe readers
• SQLite application_id support for file-type validation

API Reference

Factory Methods

| Method | Description | |--------|-------------| | AppFile.create(path, options?) | Create a new app file | | AppFile.open(path, options?) | Open existing app file (read/write) | | AppFile.openReadOnly(path) | Open existing app file (read-only) |

File Operations

| Method | Description | |--------|-------------| | write(path, content, options?) | Write binary content | | writeText(path, text, options?) | Write UTF-8 text | | writeJson(path, data, options?) | Write JSON | | writeFrom(path, sourcePath, options?) | Import from filesystem | | read(path) | Read binary content (Uint8Array) | | readText(path) | Read UTF-8 text (string) | | readJson<T>(path) | Read and parse JSON | | readTo(path, destPath, options?) | Export to filesystem | | exists(path) | Check path existence | | delete(path) | Delete a file | | listFiles(prefix?) | List file paths | | getAllFiles() | Return full file records |

Metadata

| Method | Description | |--------|-------------| | setMeta(key, value) | Set app metadata | | getMeta(key) | Get metadata value | | getAllMeta() | Get all metadata |

Transactions and Migrations

| Method | Description | |--------|-------------| | transaction(fn) | Run operations atomically | | getVersion() | Get schema version | | migrate(migrations) | Run pending migrations |

Tree and App ID

| Method | Description | |--------|-------------| | getTree() | Build full directory tree | | listDir(path) | List direct children | | setApplicationId(id) | Set SQLite application_id | | getApplicationId() | Get SQLite application_id | | validateApplicationId(id) | Validate app ID |

Connection

| Method | Description | |--------|-------------| | close() | Close database connection |

Error Handling

All package errors extend AppFileError.

import { ValidationError, DatabaseError } from 'sqlite-appfile';

try {
  app.writeJson('/data.json', { ok: true });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error('Invalid data:', err.message);
  } else if (err instanceof DatabaseError) {
    console.error('Database error:', err.message);
  }
}

License

MIT