lines-db

日本語版 README | English README

A lightweight database implementation that treats JSONL (JSON Lines) files as tables using SQLite. Perfect for managing application seed data and testing.

Features

• 📝 Load JSONL files as database tables
• 🔄 Automatic schema inference
• 💾 In-memory or file-based SQLite storage
• 🚀 Full SQL query support
• 🔍 Simple query API
• 📦 JSON column support with automatic serialization/deserialization
• ✅ Built-in validation using StandardSchema (supports Valibot, Zod, and more)
• 🎯 Automatic type inference from table names (no type arguments needed!)
• 🔄 Bidirectional schema transformations with automatic backward conversion
• 💾 Auto-sync to JSONL files - persist database changes back to files
• 🛡️ Type-safe with TypeScript
• 🧪 Minimal dependencies (uses built-in SQLite in Node.js)

Quick Start

npm install @toiroakr/lines-db

import { LinesDB } from '@toiroakr/lines-db';

const db = LinesDB.create({ dataDir: './data' });
await db.initialize();

const users = db.find('users');
await db.close();

For full documentation, see lib/README.md

Repository Structure

This repository is organized as a monorepo:

lines-db/
├── lib/                 # Core library package (@toiroakr/lines-db)
│   ├── src/            # Source code
│   ├── dist/           # Build output (ESM)
│   ├── bin/            # CLI executable
│   └── README.md       # 📚 User documentation (published to npm)
├── tests/              # Integration tests
│   └── unit/          # Unit tests
├── examples/           # Usage examples
└── extension/          # VSCode extension

Packages

📦 Core Library: @toiroakr/lines-db

The main npm package that provides the database functionality.

→ Full documentation

Features:

• JSONL file loading and parsing
• SQLite database abstraction
• Schema inference and validation
• Type-safe query APIs
• Node.js 22.12+ support
• CLI tools for validation and type generation
• Browser UI to browse and edit tables (lines-db studio)

🔌 VSCode Extension: lines-db-vscode

VSCode extension for lines-db with real-time validation and development tools.

→ Extension documentation

Features:

• Command palette integration (validate, migrate)
• Real-time validation diagnostics
• CodeLens showing record counts
• Hover information for schema files
• JSONL syntax highlighting

Development

Prerequisites

• Node.js 22.12.0 or later
• pnpm 10.x or later

Setup

# Install dependencies
pnpm install

# Build the library
cd lib
pnpm run build

Testing

# Run unit tests
pnpm test

The studio has end-to-end tests in e2e/, run with TesterArmy e2e. CI runs the scripted ones (pnpm e2e:deterministic) on each pull request, uploads the report as studio-e2e-report.html, an artifact that opens in the browser as it is, and comments it on the pull request. pnpm e2e:report:html writes the same file locally, to e2e/.e2e/report.html. The agent tests are run locally only, as they drive the browser through a ChatGPT subscription.

# Once: install Chromium for the tests and sign in to ChatGPT
pnpm e2e:setup

# Build, then run every test, only the scripted ones, or only the agent ones
pnpm e2e
pnpm e2e:deterministic
pnpm e2e:agent

# Show the result of the latest run (screenshots and traces are in e2e/.e2e/artifacts/)
pnpm e2e:report

Other Commands

# Type checking
pnpm typecheck

# Linting
pnpm lint
pnpm lint:fix

# Formatting
pnpm format
pnpm format:check

# Run examples
pnpm example
pnpm example:validation
pnpm example:json
pnpm example:datadir

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Workflow

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Publishing

This project uses changesets for version management:

# Create a changeset
pnpm changeset

# Version packages
pnpm version

# Publish to npm
pnpm release

License

MIT

Links

• npm: @toiroakr/lines-db
• GitHub: toiroakr/lines-db
• Issues: github.com/toiroakr/lines-db/issues
• Documentation: lib/README.md
• Extension: extension/README.md