Generic database abstraction layer for Atscript. Provides unified CRUD, relations, views, aggregations, and schema sync — all driven by @db.* annotations in your .as models. Pluggable adapters connect any database engine (SQLite, PostgreSQL, MongoDB, MySQL).

Installation

pnpm add @atscript/db

Quick Start

@db.table "users"
interface User {
  @meta.id
  @db.default.increment
  id: number

  @db.index.unique "email_idx"
  email: string

  name: string
}

import { DbSpace } from "@atscript/db";
import { createAdapter } from "@atscript/db-sqlite";

const db = createAdapter("./myapp.db");
const users = db.getTable(User);

await users.insertOne({ name: "John", email: "[email protected]" });
const all = await users.findMany({ filter: { name: { $eq: "John" } } });

Sub-entries

| Entry | Purpose | | --------------------- | -------------------------------------------------------- | | @atscript/db/plugin | dbPlugin() — registers all @db.* annotations | | @atscript/db/rel | Relation loading and nested writes | | @atscript/db/agg | Aggregation query validation | | @atscript/db/sync | Schema sync with drift detection and distributed locking | | @atscript/db/shared | Annotation helpers for adapter plugins |

Features

• Annotation-driven schema: table names, indexes, column mappings, defaults, primary keys
• Pluggable adapters via BaseDbAdapter — same code works with any database
• Automatic write pipeline: defaults, validation, ID preparation, column mapping
• Embedded object flattening (__-separated columns) and @db.json storage
• Relations: @db.rel.to, @db.rel.from, @db.rel.via with nested writes
• Views: @db.view with joins, filters, materialized views, aggregation
• Schema sync: FNV-1a hash drift detection, distributed locking, column/table renames
• Array patch operations: $insert, $upsert, $update, $remove, $replace
• Type-safe queries with FlatOf<T> for autocomplete on filters and projections

Documentation

• Database Guide
• API & Annotations
• Full Documentation

License

MIT