sqlite-adapter

@catmint-fs/sqlite-adapter

An SQLite-backed FsAdapter for @catmint-fs/core. Stores all filesystem state -- files, directories, symlinks, permissions -- in a single SQLite database, making it ideal for embedded, portable, or in-memory virtual filesystems.

Features

• Full FsAdapter implementation -- drop-in replacement for LocalAdapter
• Powered by better-sqlite3 -- fast, synchronous SQLite access wrapped in async API
• In-memory or on-disk -- pass ":memory:" for ephemeral filesystems, or a file path for persistence
• Import / export -- bulk-import from a real directory or export the database contents back to disk
• Symlink support -- stores symbolic links alongside regular files and directories
• Permission enforcement -- tracks mode, uid, and gid per entry

Installation

pnpm add @catmint-fs/sqlite-adapter @catmint-fs/core

Note: This package is Node.js only (depends on better-sqlite3).

Quick start

import { createLayer } from "@catmint-fs/core";
import { SqliteAdapter } from "@catmint-fs/sqlite-adapter";

// In-memory filesystem
const adapter = new SqliteAdapter({ database: ":memory:" });
const layer = await createLayer({ root: "/", adapter });

await layer.writeFile("/hello.txt", "Hello, world!\n");
const content = await layer.readFile("/hello.txt");

// Persistent filesystem
const persistent = new SqliteAdapter({ database: "./myfs.db" });
const diskLayer = await createLayer({ root: "/", adapter: persistent });

API

SqliteAdapter

import { SqliteAdapter } from "@catmint-fs/sqlite-adapter";

const adapter = new SqliteAdapter(options);

SqliteAdapterOptions

Property	Type	Default	Description
database	string	--	Path to SQLite file, or ":memory:" for in-memory
caseSensitive	boolean	true	Whether path lookups are case-sensitive

Methods

The adapter implements the full FsAdapter interface from @catmint-fs/core:

• readFile, writeFile, readdir, stat, lstat, exists
• mkdir, rm, rmdir, rename
• symlink, readlink
• chmod, chown, lchown, checkPermission
• createReadStream
• capabilities()

Additional methods:

Method	Signature	Description
importFrom	(sourcePath: string) => Promise<void>	Recursively import a real directory into the database
exportTo	(destPath: string) => Promise<void>	Export database contents to a real directory on disk
close	() => Promise<void>	Close the underlying SQLite connection
getDatabase	() => Database	Access the raw better-sqlite3 database instance

Standalone helpers

import { initializeSchema, importFrom, exportTo } from "@catmint-fs/sqlite-adapter";

// Initialize the schema on an existing better-sqlite3 database
initializeSchema(db);

// Import/export using a raw database handle
importFrom(db, "/path/to/source");
exportTo(db, "/path/to/destination");

Use with @catmint-fs/git

The SQLite adapter works as the backing store for git repositories:

import { createLayer } from "@catmint-fs/core";
import { SqliteAdapter } from "@catmint-fs/sqlite-adapter";
import { initRepository } from "@catmint-fs/git";

const adapter = new SqliteAdapter({ database: ":memory:" });
const layer = await createLayer({ root: "/", adapter });

const repo = await initRepository(layer);
await layer.writeFile("/readme.txt", "Hello\n");
await repo.add("/readme.txt");
await repo.commit({ message: "initial commit" });

License

GPL-2.0 -- see LICENSE for details.