@easbot/database 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 houjallen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,261 @@
+[English](./README.en.md) | [中文](./README.md)
+
+# @easbot/database
+
+EASBot's database abstraction layer: hides backend differences behind a single `DatabaseInterface`, ships SQLite (with three swappable backends: `better-sqlite3` / `node:sqlite` / `@tursodatabase/database`) and PostgreSQL implementations, and provides first-class nested transactions (SAVEPOINT), parameter placeholder translation, and a coherent error taxonomy.
+
+Application code should reach the database through `DatabaseFactory` and build domain DAOs (Agent / Task / Memory persistence) on top — those concerns do not belong to this package.
+
+## Features
+
+- **Single interface**: `DatabaseInterface` covers `query / queryOne / execute / exec / execBatch / begin / withTransaction`; dialect specifics stay hidden.
+- **Pluggable backends**: SQLite auto-detects one of three backends and falls through gracefully; PostgreSQL uses a `pg` pool.
+- **Unified `?` placeholder**: `translatePlaceholders(sql, 'numbered')` rewrites to `$1, $2 …` so callers don't care about dialect.
+- **Nested transactions**: re-entrant `withTransaction` calls on the same connection use `SAVEPOINT sp_<N>`; outermost owns `BEGIN/COMMIT/ROLLBACK`; inner handles only carry state.
+- **Auto rollback**: `withTransaction(fn)` rolls back on callback throw; double-commit / double-rollback on the same handle is idempotent; readonly mode rejects `begin()`.
+- **Error taxonomy**: `DatabaseError` root + `ConnectionError / QueryError / TransactionError` subclasses with preserved `cause` chains.
+
+## Install
+
+```bash
+pnpm add @easbot/database
+```
+
+Or as a workspace dependency:
+
+```json
+{
+  "dependencies": {
+    "@easbot/database": "workspace:*"
+  }
+}
+```
+
+Note: `better-sqlite3` is the default backend, declared as an `optional peerDependency`. If your runtime only has `node:sqlite` (Node 22.5+ builtin), leave `better-sqlite3` out and the resolver falls back automatically.
+
+## Usage
+
+### 1. SQLite via `DatabaseFactory`
+
+```typescript
+import { DatabaseFactory } from '@easbot/database';
+
+// backend: 'auto' | 'better-sqlite3' | 'node:sqlite' | '@tursodatabase/database'
+const db = DatabaseFactory.create({
+  flavor: 'sqlite',
+  sqlite: {
+    path: 'app.db',
+    backend: 'auto',
+    walMode: true,
+    foreignKeys: true,
+  },
+});
+await db.initialize();
+
+// Always use `?` placeholders
+const users = await db.query<{ id: string; name: string }>(
+  'SELECT id, name FROM users WHERE status = ? ORDER BY name',
+  ['active'],
+);
+```
+
+### 2. Nested transactions + auto rollback
+
+```typescript
+await db.withTransaction(async (tx) => {
+  await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 'alice']);
+  await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 'bob']);
+
+  // Nested: SAVEPOINT sp_2; failure only rolls back the inner scope
+  try {
+    await db.withTransaction(async (inner) => {
+      await inner.execute('INSERT INTO audit_log (...) VALUES (...)', [...]);
+      throw new Error('rollback me');
+    });
+  } catch {
+    /* ignore — outer tx still alive */
+  }
+
+  // Explicit SAVEPOINT for finer-grained control
+  await tx.savepoint('checkpoint_1');
+  /* … */
+  await tx.rollbackTo('checkpoint_1');
+  await tx.release('checkpoint_1');
+});
+// Exiting the outermost withTransaction auto-commits; throwing auto-rolls-back
+```
+
+### 3. Switch to PostgreSQL
+
+```typescript
+import { DatabaseFactory } from '@easbot/database';
+
+const pg = DatabaseFactory.create({
+  flavor: 'postgresql',
+  host: '127.0.0.1',
+  port: 5432,
+  database: 'app',
+  username: 'app',
+  password: '***',
+  ssl: false,
+  poolSize: 10,
+});
+await pg.initialize();
+
+// Always `?` at the application layer; the backend rewrites it
+await pg.query('SELECT * FROM users WHERE id = ?', [42]);
+```
+
+### 4. Build domain DAOs on top
+
+The abstraction exposes only "database capabilities". Domain entities (Agent / Task / Memory schemas, JSON serialisation) are an application concern:
+
+```typescript
+import type { DatabaseInterface } from '@easbot/database';
+
+interface Widget {
+  id: string;
+  name: string;
+  color: string;
+}
+
+class WidgetDao {
+  constructor(private readonly db: DatabaseInterface) {}
+
+  async create(w: Widget) {
+    await this.db.execute('INSERT INTO widgets (id, name, color) VALUES (?, ?, ?)', [
+      w.id,
+      w.name,
+      w.color,
+    ]);
+  }
+
+  async findById(id: string): Promise<Widget | null> {
+    const rows = await this.db.query<{ id: string; name: string; color: string }>(
+      'SELECT id, name, color FROM widgets WHERE id = ?',
+      [id],
+    );
+    return rows[0] ?? null;
+  }
+}
+```
+
+## Backend selection strategy
+
+| backend | Performance | When to use |
+|---|---|---|
+| `better-sqlite3` | Best (validated by the sqg.dev benchmark) | Default; requires a `node-gyp` build. |
+| `node:sqlite` | 10–20 % slower than better-sqlite3 | Node 22.5+ builtin; zero native dependency; ideal when cross-platform builds fail. |
+| `@tursodatabase/database` | Mid (Turso historically lags) | Embedded / long-term fallback; optional dependency. |
+
+`DatabaseFactory.create({ flavor: 'sqlite', sqlite: { backend: 'auto' } })` runs the resolver in the order above; passing an explicit `backend` skips detection.
+
+## Error codes
+
+| code | class | meaning |
+|---|---|---|
+| `CONNECTION` | `ConnectionError` | backend create / init failure (WAL failure, missing native binding, etc.) |
+| `QUERY` | `QueryError` | SQL execution failure (syntax, missing column, type mismatch) |
+| `TX` | `TransactionError` | transaction state-machine error (double-finalise, readonly begin failure, SAVEPOINT failure) |
+
+Error instances carry the original driver exception via the `cause` chain, suitable for upstream aggregation.
+
+## Out of scope
+
+- Domain entity persistence (Agent / Task / Memory / Knowledge Graph) — owned by each domain package.
+- MCP / Skill exposure — owned by `@easbot/mcp`, `@easbot/skills`, and the `easbot` main CLI.
+- Vector DB interfaces — placeholder stubs; tracked for future implementation.
+
+## CLI
+
+This package exposes no standalone CLI; integrate via the public API instead.
+
+## Performance optimizations
+
+### 1. Prepared statement LRU (SQLite)
+
+`SqliteDatabase` maintains a 256-capacity LRU cache that skips tokenize + parse for repeated SQL:
+
+- Hot path: every repeated SQL is 0-cost;
+- Capacity full: evict the least-recently-used entry;
+- Invalidation: only DDL (`CREATE/DROP/ALTER/TRUNCATE/REPLACE`) clears the cache; regular DML and `PRAGMA` keep it intact.
+
+### 2. Placeholder translation cache (PostgreSQL)
+
+`PostgresDatabase` caches `translatePlaceholders` results in a 256-capacity LRU keyed by SQL string, avoiding `String.replace + closure` on every query:
+
+- Placeholder-less SQL short-circuits (returns original SQL, passes `undefined` to pg to suppress noisy warnings);
+- Placeholder-bearing SQL hits the cache and skips the scan.
+
+### 3. `execBatch` single round-trip (PostgreSQL)
+
+`execBatch` joins multiple statements with `;` and sends them in a single `client.query()` call, saving N-1 network round-trips vs. looping. SQLite stays on per-statement `backend.exec()` since its driver is synchronous and has no network gain.
+
+## Nested transaction semantics (SQLite ⇄ PostgreSQL)
+
+Both backends are observationally identical to the application layer:
+
+| Depth | SQLite | PostgreSQL |
+|---|---|---|
+| `begin()` depth=1 | `BEGIN` | `BEGIN` (dedicated client) |
+| `begin()` depth>1 | `SAVEPOINT sp_<N>` | `SAVEPOINT sp_<N>` (reuses outer client) |
+| Inner `commit()` | state cleanup only | `RELEASE SAVEPOINT sp_<N>` |
+| Inner `rollback()` | `ROLLBACK TO SAVEPOINT sp_<N>` | `ROLLBACK TO SAVEPOINT sp_<N>` |
+| Outer `commit()` | `COMMIT` | `COMMIT` + release client |
+| Outer `rollback()` | `ROLLBACK` | `ROLLBACK` + release client |
+| After inner failure | inner SQL undone, outer unaffected | same |
+
+The application never sees the dialect.
+
+## Edge cases & error handling
+
+- **Call before `initialize()`**: `query / execute / exec / begin` all throw `ConnectionError`.
+- **Call after `close()`**: same; internal state is reset.
+- **readonly SQLite**: `begin()` throws `TransactionError` immediately (clearer than the raw SQLite message).
+- **PG `pool.connect()` failure**: `begin()` throws `TransactionError` AND rolls `lastTxDepth` back, so the next `begin()` starts at depth=1.
+- **Double commit/rollback on same handle**: idempotent guard via `finished` flag, no extra SQL.
+- **Query/savepoint after finalize**: throws `TransactionError`.
+- **Unsafe SAVEPOINT / table names** (non-ASCII, injection payloads): `isSafeIdent` rejects, `TransactionError` blocks the concatenation.
+
+## Test matrix
+
+| Suite | Coverage | File |
+|---|---|---|
+| `sqlite-database.test.ts` | backend probe / query / execute / connection / LRU / DDL invalidation | `tests/__tests__/` |
+| `transaction.test.ts` | basic / idempotent / nested SAVEPOINT / explicit savepoint / readonly | `tests/__tests__/` |
+| `utils.test.ts` | `isSafeIdent` / `translatePlaceholders` / `DatabaseError` taxonomy | `tests/__tests__/` |
+| `postgresql.test.ts` | placeholder cache / nested SAVEPOINT / handle idempotency / error taxonomy / connect-fail rollback (mocked `pg`) | `tests/__tests__/` |
+| `sqlite-cache.test.ts` | LRU capacity eviction / precise cache invalidation / readonly boundary | `tests/__tests__/` |
+| `backends.test.ts` | backend probe / explicit selection / application-layer DAO pattern | `tests/__tests__/` |
+| `examples/test-database.ts` | end-to-end smoke (35 assertions) | `examples/` |
+| `examples/test-pgsql.ts` | PG end-to-end (19 assertions, including nested SAVEPOINT) | `examples/` |
+
+Run:
+
+```bash
+pnpm test:run                              # 66 vitest tests
+node --import tsx examples/test-database.ts # SQLite 35/35
+node --import tsx examples/test-pgsql.ts   # PG 19/19 (requires docker compose up -d pg)
+```
+
+## Changelog
+
+### 0.4.x (current)
+
+Fixes:
+
+- **PG nested SAVEPOINT semantics**: inner `begin()` now actually issues `SAVEPOINT sp_<N>`; inner commit issues `RELEASE SAVEPOINT sp_<N>`; rollback issues `ROLLBACK TO SAVEPOINT sp_<N>`. Fully aligned with SQLite (previous behavior was broken — inner begin/commit were no-ops, breaking isolation).
+- **PG `pool.connect()` failure rolls `lastTxDepth` back**: previously, a failed begin left the depth counter dirty, corrupting the next transaction.
+- **PG `client.release(destroy=true)` on BEGIN failure**: damaged clients are removed from the pool instead of being returned.
+- **PG `close()` propagates errors**: previously swallowed `pool.end()` errors; now throws `ConnectionError`.
+- **PG `translatePlaceholders` LRU cache**: avoids re-scanning SQL on every query; placeholder-less SQL passes `undefined` to pg.
+- **PG `execBatch` single round-trip**: semicolon-joined statements sent in one `client.query()`.
+- **SQLite `exec()` precise cache invalidation**: changed from "clear on every exec" to "clear only on DDL" (`PRAGMA` / DML leave the cache intact).
+- **`examples/` refactor**: replaced the bespoke `expect` mock with standard `assertEq / assertTrue / expectThrows / expectInstanceOf`; PG example now exercises nested SAVEPOINT and is type-tolerant (number/string).
+- **Test coverage**: new `utils.test.ts` (isSafeIdent / translatePlaceholders / error taxonomy), `postgresql.test.ts` (9 mocked PG tests for nested + rollback), `sqlite-cache.test.ts` (LRU capacity + precise invalidation).
+- **`tsup.config.ts` cleanup**: removed 60+ lines of debug `console.log`, removed manual `node:*` externalization (tsup auto-externalizes under `platform: 'node'`), removed `any` return type.
+- **`vitest.config.ts` fixes**: `coverage.include` changed from nonexistent `src/tool/**` to `src/**`; `setupFiles` moved from `tests/setup.ts` (not under include) to `tests/__tests__/global.setup.ts`.
+
+## License
+
+MIT © houjallen / EASBot

package/README.md

@@ -0,0 +1,313 @@
+[English](./README.en.md) | 中文
+
+# @easbot/database
+
+EASBot 数据库抽象层：在统一 `DatabaseInterface` 之后屏蔽后端差异，提供 SQLite（better-sqlite3 / node:sqlite / @tursodatabase/database 三选一）与 PostgreSQL 双方言实现，并内置嵌套事务（SAVEPOINT）、参数占位符翻译、错误码体系。
+
+> 详细架构 / 后端选择策略 / 错误码 / 性能预算 / 单测基线见项目发布文档 [`docs/components/database.md`](https://github.com/houjallen/easbot/blob/main/docs/components/database.md)。包内 `docs/EAS_DATABASE_DESIGN.md` 为历史私有副本，新信息请以上述链接为准。
+
+应用层应当通过 `DatabaseFactory` 获取连接，再基于 `DatabaseInterface` 自建业务 DAO（Agent / Task / Memory 等实体的持久化不归本包）。
+
+## 特性
+
+- **统一接口**：`DatabaseInterface` 覆盖 `query / queryOne / execute / exec / execBatch / begin / withTransaction`，底层方言差异被屏蔽
+- **同步 facade**：`SyncSqliteConnection` 暴露 `better-sqlite3` 形态的同步 API（`exec / prepare / pragma / transaction / getJournalMode / ...`），给同步热路径使用（Tree-sitter / 本地 embedding / 主线程 SQLite 调用）
+- **后端可插拔**：SQLite 三大 backend 自动探测（`better-sqlite3` → `node:sqlite` → `@tursodatabase/database`），并支持显式指定；PostgreSQL 通过 `pg` 池化连接
+- **占位符统一为 `?`**：内置 `translatePlaceholders(sql, 'numbered')` 把 `?` 翻译为 `$1, $2 ...`，兼容 pg 等 numbered 占位符方言
+- **嵌套事务**：同一连接上 `withTransaction` 嵌套调用走 `SAVEPOINT sp_<N>`；最外层负责 `BEGIN/COMMIT/ROLLBACK`，内层句柄仅做状态机
+- **自动兜底**：`withTransaction(fn)` 在 callback 抛错时自动 rollback；同一 handle 二次 commit / rollback 幂等；readonly 数据库拒绝 begin
+- **错误体系**：`DatabaseError` 根类 + `ConnectionError / QueryError / TransactionError` 子类，cause 链保留驱动层原始异常
+
+## 两种接入模式
+
+### 模式 A：异步 facade（`DatabaseFactory` / `DatabaseInterface`）
+
+适用于异步调用栈——MCP server / 跨网络 / web handler：
+
+```typescript
+import { DatabaseFactory } from '@easbot/database';
+
+const db = DatabaseFactory.create({
+  flavor: 'sqlite',
+  sqlite: { path: 'app.db', backend: 'auto', walMode: true },
+});
+await db.initialize();
+const rows = await db.query<{ id: string }>('SELECT id FROM users WHERE status = ?', ['active']);
+```
+
+### 模式 B：同步 facade（`SyncSqliteConnection`）—— **新**
+
+适用于同步热路径——Tree-sitter WASM 解析 / 本地 embedding 推理 / 主线程 SQLite 调用：
+
+```typescript
+import { createSyncSqliteConnection } from '@easbot/database';
+
+const conn = createSyncSqliteConnection({
+  path: 'app.db',
+  backend: 'better-sqlite3',  // 或 'node-sqlite' / '@tursodatabase/database'
+  walMode: true,
+});
+conn.initialize();
+
+// 完全同步 API，对标 better-sqlite3 / codegraph SqliteDatabase
+const stmt = conn.prepare('SELECT id FROM users WHERE status = ?');
+const rows = stmt.all('active');
+conn.close();
+```
+
+**典型应用**：`packages/codebase` 的 `DatabaseManager` 60+ 同步 DB 调用点通过 `SyncSqliteConnection` 接入 `@easbot/database`，API 形态完全兼容 `better-sqlite3` 同步 binding，**零改动**。详见决策 [`0036-storage-backend.md`](file:///e:/work/apps/eas/easbot/docs/decisions/0036-storage-backend.md)。
+
+## backend 与 facade 选择
+
+| 场景 | 推荐 facade | 推荐 backend |
+|---|---|---|
+| 同步热路径（Tree-sitter / 本地推理 / 主线程 SQLite） | `SyncSqliteConnection` | `better-sqlite3` |
+| MCP server / 异步 CLI | `DatabaseInterface`（async） | `better-sqlite3` |
+| cross-platform 构建失败回退 | 任意 | `node:sqlite`（Node 22.5+ 内置） |
+| 嵌入式 / 远期 Turso 兼容 | 任意 | `@tursodatabase/database` |
+| PostgreSQL 切换 | `DatabaseInterface`（async） | `pg` |
+
+## 安装
+
+```bash
+pnpm add @easbot/database
+```
+
+或作为 monorepo 工作区依赖：
+
+```json
+{
+  "dependencies": {
+    "@easbot/database": "workspace:*"
+  }
+}
+```
+
+注意：`better-sqlite3` 是默认 backend，作为 `optional peerDependency`。如果运行环境只能使用 `node:sqlite`（Node 22.5+ 内置），可让 `better-sqlite3` 不安装；resolver 会自动降级。
+
+## 使用方式
+
+### 1. 通过 `DatabaseFactory` 创建 SQLite 实例
+
+```typescript
+import { DatabaseFactory } from '@easbot/database';
+
+// backend: 'auto' | 'better-sqlite3' | 'node:sqlite' | '@tursodatabase/database'
+const db = DatabaseFactory.create({
+  flavor: 'sqlite',
+  sqlite: {
+    path: 'app.db',
+    backend: 'auto',
+    walMode: true,
+    foreignKeys: true,
+  },
+});
+await db.initialize();
+
+// 统一 ? 占位符（SQLite / PostgreSQL 通用）
+const users = await db.query<{ id: string; name: string }>(
+  'SELECT id, name FROM users WHERE status = ? ORDER BY name',
+  ['active'],
+);
+```
+
+### 2. 嵌套事务 + 自动回滚
+
+```typescript
+await db.withTransaction(async (tx) => {
+  await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 'alice']);
+  await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 'bob']);
+
+  // 嵌套：SAVEPOINT sp_2；失败仅回滚内层
+  try {
+    await db.withTransaction(async (inner) => {
+      await inner.execute('INSERT INTO audit_log (...) VALUES (...)', [...]);
+      throw new Error('rollback me');
+    });
+  } catch {
+    /* ignore — outer tx still alive */
+  }
+
+  // 显式 SAVEPOINT（控制粒度更细）
+  await tx.savepoint('checkpoint_1');
+  /* ... */
+  await tx.rollbackTo('checkpoint_1');
+  await tx.release('checkpoint_1');
+});
+// 退出最外层 withTransaction 自动 commit；中途抛错自动 rollback
+```
+
+### 3. 切换 PostgreSQL
+
+```typescript
+import { DatabaseFactory, translatePlaceholders } from '@easbot/database';
+
+const pg = DatabaseFactory.create({
+  flavor: 'postgresql',
+  host: '127.0.0.1',
+  port: 5432,
+  database: 'app',
+  username: 'app',
+  password: '***',
+  ssl: false,
+  poolSize: 10,
+});
+await pg.initialize();
+
+// 应用层始终使用 `?`；后端自动翻译为 `$1, $2 ...`
+await pg.query('SELECT * FROM users WHERE id = ?', [42]);
+```
+
+### 4. 应用层自建业务 DAO（不属于本包）
+
+数据库抽象只暴露"数据库能力"。业务实体（如 Agent / Task / Memory）的 schema、字段映射、JSON 序列化策略属于上层职责——应用层应自己基于 `DatabaseInterface` 写 DAO，例如：
+
+```typescript
+import type { DatabaseInterface } from '@easbot/database';
+
+interface Widget {
+  id: string;
+  name: string;
+  color: string;
+}
+
+class WidgetDao {
+  constructor(private readonly db: DatabaseInterface) {}
+
+  async create(w: Widget) {
+    await this.db.execute('INSERT INTO widgets (id, name, color) VALUES (?, ?, ?)', [
+      w.id,
+      w.name,
+      w.color,
+    ]);
+  }
+
+  async findById(id: string): Promise<Widget | null> {
+    const rows = await this.db.query<{ id: string; name: string; color: string }>(
+      'SELECT id, name, color FROM widgets WHERE id = ?',
+      [id],
+    );
+    return rows[0] ?? null;
+  }
+}
+```
+
+## 后端 backend 选择策略
+
+| backend | 性能 | 何时适用 |
+|---|---|---|
+| `better-sqlite3` | ✅ 最佳（sqg.dev 基准验证） | 默认；要求 `node-gyp` 构建 |
+| `node:sqlite` | 次之（比 better-sqlite3 慢 10–20%） | Node 22.5+ 内置；零原生依赖；适合 cross-platform 构建失败场景 |
+| `@tursodatabase/database` | 中（Turso 历史性能较差） | 嵌入式 / 远期兜底；可选依赖 |
+
+`DatabaseFactory.create({ flavor: 'sqlite', sqlite: { backend: 'auto' } })` 时，resolver 按上表顺序探测；显式指定 backend 跳过探测。
+
+## 错误码
+
+| code | 类 | 含义 |
+|---|---|---|
+| `CONNECTION` | `ConnectionError` | backend 创建 / 初始化失败（WAL 失败、native binding 缺失等） |
+| `QUERY` | `QueryError` | SQL 执行失败（语法错、列不存在、类型不匹配） |
+| `TX` | `TransactionError` | 事务状态机错误（二次操作、readonly begin 失败、SAVEPOINT 抛错） |
+
+错误实例保留 `cause` 链，可向上层聚合时透出原始驱动抛错。
+
+## 不在范围内
+
+- 业务实体持久化（Agent / Task / Memory / Knowledge Graph 等）—— 由各自领域包提供
+- MCP / Skill 暴露—— 由 `@easbot/mcp`、`@easbot/skills`、`easbot` 主 CLI 承载
+- 向量数据库接口—— 占位 stub 未实装，留作将来
+
+## CLI
+
+本包不暴露独立 CLI；调用方通过 `DatabaseFactory` / `DatabaseInterface` API 集成。
+
+## 性能优化
+
+### 1. prepared statement LRU（SQLite）
+
+`SqliteDatabase` 内部维护一个容量 256 的 LRU 缓存，命中已 prepare 过的 SQL 跳过 tokenize + parse 阶段：
+
+- 热路径：所有重复 SQL 0-cost 命中；
+- 容量满：按 LRU 淘汰最久未访问；
+- 失效策略：仅在检测到 DDL（`CREATE/DROP/ALTER/TRUNCATE/REPLACE`）时清空，普通 DML 与 `PRAGMA` 不影响 cache。
+
+### 2. 占位符翻译缓存（PostgreSQL）
+
+`PostgresDatabase` 对 `translatePlaceholders` 结果按 SQL 字符串做 256 容量 LRU 缓存，避免每次 query 都扫描 SQL 替换 `?`：
+
+- 无占位符 SQL 一次性 short-circuit（直接返回原 SQL，params 传 `undefined` 避免 pg 警告噪音）；
+- 有占位符 SQL：命中即跳过 `String.replace + closure` 计数。
+
+### 3. `execBatch` 单 round-trip（PostgreSQL）
+
+PG 上 `execBatch` 用 `;` 分号拼接多条 statement 一次性发送，由 PG 自身批量执行；相比逐条 `client.query()` 节省 N-1 次网络往返。SQLite 仍走逐条 `backend.exec()`，因底层是同步 API 不存在网络收益。
+
+## 嵌套事务语义对齐（SQLite ⇄ PostgreSQL）
+
+两条路径在事务行为上完全一致：
+
+| 深度 | SQLite | PostgreSQL |
+|---|---|---|
+| `begin()` depth=1 | `BEGIN` | `BEGIN`（独占 client） |
+| `begin()` depth>1 | `SAVEPOINT sp_<N>` | `SAVEPOINT sp_<N>`（复用最外层 client） |
+| 内层 `commit()` | 仅清理状态 | `RELEASE SAVEPOINT sp_<N>` |
+| 内层 `rollback()` | `ROLLBACK TO SAVEPOINT sp_<N>` | `ROLLBACK TO SAVEPOINT sp_<N>` |
+| 外层 `commit()` | `COMMIT` | `COMMIT` + 释放 client |
+| 外层 `rollback()` | `ROLLBACK` | `ROLLBACK` + 释放 client |
+| 嵌套失败后 | 内层 SQL 撤回，外层不受影响 | 同左 |
+
+应用层无需关心方言；`db.withTransaction` 嵌套调用行为完全一致。
+
+## 边界与错误处理
+
+- **未 `initialize()` 调用**：`query / execute / exec / begin` 全部抛 `ConnectionError`；
+- **`close()` 后再调用**：同上抛 `ConnectionError`，内部状态全部重置；
+- **readonly SQLite**：`begin()` 立即抛 `TransactionError`，避免 SQLite 原生报错信息含糊；
+- **PG `pool.connect()` 失败**：`begin()` 抛 `TransactionError`，且 `lastTxDepth` 归位，下次 `begin()` 从 depth=1 重新开始（不污染计数）；
+- **同一 handle 二次 commit / rollback**：幂等守门（`finished` 标记），不重复发 SQL；
+- **finalize 后再 query / savepoint**：抛 `TransactionError`，提示事务已终结；
+- **SAVEPOINT / 表名包含非 ASCII / 注入字符**：`isSafeIdent` 拒绝，抛 `TransactionError` 阻断拼接。
+
+## 测试矩阵
+
+| 测试套件 | 覆盖 | 文件 |
+|---|---|---|
+| `sqlite-database.test.ts` | backend 探测 / query / execute / 连接管理 / LRU cache / DDL 失效 | `tests/__tests__/` |
+| `transaction.test.ts` | basic / 幂等 / 嵌套 SAVEPOINT / 显式 savepoint / readonly 守卫 | `tests/__tests__/` |
+| `utils.test.ts` | `isSafeIdent` / `translatePlaceholders` / `DatabaseError` 体系 | `tests/__tests__/` |
+| `postgresql.test.ts` | 占位符翻译缓存 / 嵌套 SAVEPOINT / 句柄幂等 / 错误分类 / connect 失败归位（用 `pg` 模块桩） | `tests/__tests__/` |
+| `sqlite-cache.test.ts` | LRU 容量上限淘汰 / exec 精确清 cache / readonly 边界 | `tests/__tests__/` |
+| `backends.test.ts` | backend 探测 / 显式选择 / 应用层 DAO 模式 | `tests/__tests__/` |
+| `examples/test-database.ts` | 端到端冒烟（35 assertions） | `examples/` |
+| `examples/test-pgsql.ts` | PG 端到端（19 assertions，含嵌套 SAVEPOINT） | `examples/` |
+
+运行：
+
+```bash
+pnpm test:run              # 66 vitest tests
+node --import tsx examples/test-database.ts   # SQLite 35/35
+node --import tsx examples/test-pgsql.ts     # PG 19/19 (需 docker compose up -d pg)
+```
+
+## 版本变更
+
+### 0.4.x（本版本）
+
+修复：
+
+- **PG 嵌套事务 SAVEPOINT 语义**：内层 `begin()` 现在真发 `SAVEPOINT sp_<N>`；内层 commit 发 `RELEASE SAVEPOINT sp_<N>`；rollback 发 `ROLLBACK TO SAVEPOINT sp_<N>`。与 SQLite 路径行为完全对齐（之前实现只发 `BEGIN/COMMIT`，嵌套语义错乱）。
+- **PG `pool.connect()` 失败归位 `lastTxDepth`**：begin 失败时正确归位计数，避免下次 begin 从脏 depth 开始。
+- **PG `client.release(destroy=true)`**：BEGIN 失败时销毁损坏 client，避免脏连接回流 pool。
+- **PG `close()` 错误传播**：之前 `pool.end()` 抛错被 silently swallow，现在抛 `ConnectionError`。
+- **PG `translatePlaceholders` LRU 缓存**：避免每次 query 重扫 SQL；无占位符 SQL 传 `undefined` 避免 pg 噪音警告。
+- **PG `execBatch` 单 round-trip**：分号拼接多 statement 一次发送，节省网络往返。
+- **SQLite `exec()` 精确清 cache**：从"任何 exec 都清"改为"DDL 才清"（`PRAGMA` / DML 不影响 schema），热路径 stmt cache 保留。
+- **`examples/` 重构**：移除自造 expect mock，引入 `assertEq / assertTrue / expectThrows / expectInstanceOf` 标准断言；PG 示例补嵌套 SAVEPOINT 测试与 PG 类型（number/string）兼容。
+- **测试覆盖**：新增 `utils.test.ts`（isSafeIdent / translatePlaceholders / 错误体系）、`postgresql.test.ts`（9 个 PG mock 测试覆盖嵌套 + 归位）、`sqlite-cache.test.ts`（LRU 容量上限 + 精确清 cache）。
+- **`tsup.config.ts` 清理**：移除 60+ 行冗余 console.log、移除 `node:*` 内置模块手工 external（tsup 在 platform=node 下自动 external）、删除 `any` 返回类型。
+- **`vitest.config.ts` 修正**：`coverage.include` 路径从 `src/tool/**`（不存在）改为 `src/**`；`setupFiles` 路径从 `tests/setup.ts`（不被 include）改为 `tests/__tests__/global.setup.ts`（避开 test include）。
+
+## 许可
+
+MIT © houjallen / EASBot

package/dist/index.cjs

@@ -0,0 +1,7 @@
+'use strict';Object.defineProperty(exports,'__esModule',{value:true});var module$1=require('module'),m=require('fs'),h=require('path'),pg=require('pg');function _interopNamespace(e){if(e&&e.__esModule)return e;var n=Object.create(null);if(e){Object.keys(e).forEach(function(k){if(k!=='default'){var d=Object.getOwnPropertyDescriptor(e,k);Object.defineProperty(n,k,d.get?d:{enumerable:true,get:function(){return e[k]}});}})}n.default=e;return Object.freeze(n)}var m__namespace=/*#__PURE__*/_interopNamespace(m);var h__namespace=/*#__PURE__*/_interopNamespace(h);var V=Object.defineProperty;var j=(n,e,t)=>e in n?V(n,e,{enumerable:true,configurable:true,writable:true,value:t}):n[e]=t;var i=(n,e,t)=>j(n,typeof e!="symbol"?e+"":e,t);var U=()=>typeof document>"u"?new URL(`file:${__filename}`).href:document.currentScript&&document.currentScript.tagName.toUpperCase()==="SCRIPT"?document.currentScript.src:new URL("main.js",document.baseURI).href,c=U();var S=class extends Error{constructor(t,r,a){super(r);i(this,"code");i(this,"cause");this.name="DatabaseError",this.code=t,this.cause=a;}},o=class extends S{constructor(e,t){super("CONNECTION",e,t),this.name="ConnectionError";}},d=class extends S{constructor(e,t){super("QUERY",e,t),this.name="QueryError";}},l=class extends S{constructor(e,t){super("TX",e,t),this.name="TransactionError";}},T=(n,e)=>{if(e==="qmark")return n;let t=0;return n.replace(/\?/g,()=>`$${++t}`)},x=n=>/^[A-Za-z_][A-Za-z0-9_]*$/.test(n);var J=module$1.createRequire(c),B=(n,e)=>{try{let t=J(n);return e(t)}catch{return  false}},f=()=>{if(B("better-sqlite3",n=>typeof n.default=="function"))return "better-sqlite3";if(B("node:sqlite",n=>typeof n.DatabaseSync=="function"))return "node:sqlite";if(B("@tursodatabase/database",n=>typeof(n.default??n)=="function"))return "@tursodatabase/database";throw new o(`No SQLite backend available. Please install one of:
+  - better-sqlite3 (recommended; highest perf)
+  - node:sqlite (built-in since Node.js 22.5+)
+  - @tursodatabase/database`)};var y=class{constructor(e){i(this,"stmt",e);}run(...e){return this.stmt.run(...e)}get(...e){return this.stmt.get(...e)}all(...e){return this.stmt.all(...e)}iterate(...e){return this.stmt.iterate(...e)}};var X=module$1.createRequire(c),F=n=>typeof n=="function"&&n.prototype!==void 0,w=class{constructor(e,t={}){i(this,"backend","better-sqlite3");i(this,"db");let r=X("better-sqlite3"),a=F(r)?r:r.default;if(!F(a))throw new TypeError(`better-sqlite3 import did not expose a constructor (got ${typeof r})`);this.db=new a(e,t);}exec(e){this.db.exec(e);}prepare(e){return new y(this.db.prepare(e))}pragma(e,t){return this.db.pragma(e,t)}transaction(e){return this.db.transaction(e)}close(){this.db.open&&this.db.close();}get open(){return this.db.open}};var te=module$1.createRequire(c),b=class{constructor(e){i(this,"backend","node:sqlite");i(this,"db");let t=te("node:sqlite");this.db=new t.DatabaseSync(e);}exec(e){this.db.exec(e);}prepare(e){return new y(this.db.prepare(e))}pragma(e,t){return this.db.exec(`PRAGMA ${e}`),t?.simple!==true?void 0:this.db.prepare("SELECT pragma_value AS v FROM pragma_value(?)").get(e)}transaction(e){return((...r)=>{this.db.exec("BEGIN");let a;try{a=e(...r);}catch(s){try{this.db.exec("ROLLBACK");}catch{}throw s}return this.db.exec("COMMIT"),a})}close(){this.db.isOpen&&this.db.close();}get open(){return this.db.isOpen}};var re=module$1.createRequire(c),M=n=>typeof n=="function"&&n.prototype!==void 0,k=class{constructor(e){i(this,"backend","@tursodatabase/database");i(this,"db",null);let t=re("@tursodatabase/database"),r=M(t)?t:t.default;if(!M(r))throw new TypeError(`@tursodatabase/database import did not expose a constructor (got ${typeof t})`);this.db=new r(e);}requireDb(){if(!this.db)throw new Error(`Turso backend not initialized (db=${String(this.db)})`);return this.db}exec(e){this.requireDb().exec(e);}prepare(e){return new y(this.requireDb().prepare(e))}pragma(e){this.requireDb().exec(`PRAGMA ${e}`);}transaction(e){return((...r)=>{let a=this.requireDb();a.exec("BEGIN");let s;try{s=e(...r);}catch(u){try{a.exec("ROLLBACK");}catch{}throw u}return a.exec("COMMIT"),s})}close(){if(this.db)try{this.db.close();}finally{this.db=null;}}get open(){return this.db!==null}};var ae=256,O=class{constructor(e){i(this,"backend",e);i(this,"cache",new Map);}get(e){let t=this.cache.get(e);if(t)return this.cache.delete(e),this.cache.set(e,t),t;let r=this.backend.prepare(e);if(this.cache.size>=ae){let a=this.cache.keys().next().value;a!==void 0&&this.cache.delete(a);}return this.cache.set(e,r),r}clear(){this.cache.clear();}},Q=n=>n==null?{}:typeof n!="object"?{}:{...n},ie=n=>n.map(Q);function E(n){if(!x(n))throw new l(`Unsafe SQL identifier: ${JSON.stringify(n)}`);return `"${n}"`}function se(n){let e=n.trimStart();if(e.length===0)return  false;let a=((e.split(`
+`,1)[0]??"").trimStart().split(/\s+/,1)[0]??"").toUpperCase();return a==="CREATE"||a==="DROP"||a==="ALTER"||a==="TRUNCATE"||a==="REPLACE"}var L=class{constructor(e,t){i(this,"db",e);i(this,"depth");i(this,"finished",false);this.depth=t;}isFinished(){return this.finished}async query(e,t){return this.assertOpen(),this.db.query(e,t)}async queryOne(e,t){return this.assertOpen(),this.db.queryOne(e,t)}async execute(e,t){return this.assertOpen(),this.db.execute(e,t)}async exec(e){this.assertOpen(),await this.db.exec(e);}async commit(){this.finished||(this.finished=true,this.depth===1&&this.db.commitRoot(),this.db.popTxDepth());}async rollback(){if(!this.finished){this.finished=true;try{this.depth===1?this.db.rollbackRoot():this.db.rollbackToSavepoint(`sp_${this.depth}`);}catch{}this.db.popTxDepth();}}async savepoint(e){this.assertOpen(),this.db.execSavepoint(E(e));}async release(e){this.assertOpen(),this.db.execRelease(E(e));}async rollbackTo(e){this.assertOpen(),this.db.execRollbackTo(E(e));}assertOpen(){if(this.finished)throw new l(`Transaction already finalized (depth=${this.depth})`)}},R=class{constructor(e){i(this,"config",e);i(this,"flavor","sqlite");i(this,"sqliteBackend");i(this,"backend",null);i(this,"stmtCache",null);i(this,"inTxDepth",0);i(this,"readOnlyFlag",false);i(this,"initialized",false);i(this,"walShmSymlink",null);i(this,"effectiveDbPath",null);let t=e.sqlite??{};this.sqliteBackend=t.backend===void 0||t.backend==="auto"?f():t.backend;}async initialize(){if(this.initialized)return;let e=this.config.sqlite??{},t=e.path??":memory:",r=e.walMode!==false,a=e.foreignKeys!==false,s=e.readonly===true,u=e.busyTimeoutMs??5e3,q=e.walShmPath,_=this.resolveOpenPath(t,q);try{this.backend=this.createBackend(_,{readonly:s});}catch(D){throw this.cleanupWalShmSymlink(),new o(`Failed to create SQLite backend (${this.sqliteBackend}) at "${_}"`,D)}this.readOnlyFlag=s,this.stmtCache=new O(this.backend);try{!s&&t!==":memory:"&&r&&this.backend.exec("PRAGMA journal_mode = WAL"),!s&&a&&this.backend.exec("PRAGMA foreign_keys = ON"),this.backend.exec(`PRAGMA busy_timeout = ${u}`);}catch(D){throw this.backend=null,this.stmtCache=null,this.cleanupWalShmSymlink(),new o("Failed to apply SQLite pragmas",D)}this.initialized=true;}resolveOpenPath(e,t){if(e===":memory:"||t===void 0||t===""||this.sqliteBackend!=="better-sqlite3")return e;let r=h__namespace.dirname(e);if(h__namespace.resolve(r)===h__namespace.resolve(t))return e;let a=h__namespace.basename(e),s=h__namespace.join(t,a);try{try{let u=m__namespace.lstatSync(s);(u.isSymbolicLink()||u.isFile())&&m__namespace.unlinkSync(s);}catch{}return m__namespace.symlinkSync(h__namespace.resolve(e),s),this.walShmSymlink=s,this.effectiveDbPath=s,s}catch(u){throw new o(`Failed to create symlink for WAL at "${t}" \u2192 "${e}". Check directory existence & write permission.`,u)}}cleanupWalShmSymlink(){if(this.walShmSymlink){try{m__namespace.unlinkSync(this.walShmSymlink);}catch{}this.walShmSymlink=null,this.effectiveDbPath=null;}}createBackend(e,t){switch(this.sqliteBackend){case "better-sqlite3":return new w(e,{readonly:t.readonly});case "node:sqlite":return new b(e);case "@tursodatabase/database":return new k(e);default:throw new o(`Unsupported SQLite backend: ${String(this.sqliteBackend)}`)}}async close(){if(!this.backend){this.stmtCache?.clear(),this.stmtCache=null,this.initialized=false,this.cleanupWalShmSymlink();return}try{this.backend.close();}finally{this.backend=null,this.stmtCache?.clear(),this.stmtCache=null,this.inTxDepth=0,this.initialized=false,this.cleanupWalShmSymlink();}}isConnected(){return this.backend?.open===true}isReadOnly(){return this.readOnlyFlag}requireBackend(){if(!this.backend)throw new o("SQLite database not initialized. Call initialize() first.");return this.backend}requireCache(){if(!this.stmtCache)throw new o("SQLite database not initialized. Call initialize() first.");return this.stmtCache}async query(e,t){let r=this.prepareOrThrow(e);try{return ie(r.all(...t??[]))}catch(a){throw new d(`SQLite query failed: ${this.errorMessage(a)}`,a)}}async queryOne(e,t){let r=this.prepareOrThrow(e);try{let a=r.get(...t??[]);return a==null?null:Q(a)}catch(a){throw new d(`SQLite queryOne failed: ${this.errorMessage(a)}`,a)}}async execute(e,t){let r=this.prepareOrThrow(e);try{return r.run(...t??[])}catch(a){throw new d(`SQLite execute failed: ${this.errorMessage(a)}`,a)}}prepareOrThrow(e){try{return this.requireCache().get(e)}catch(t){throw t instanceof o?t:new d(`SQLite prepare failed: ${this.errorMessage(t)}`,t)}}async exec(e){let t=this.requireBackend();try{t.exec(e),se(e)&&this.stmtCache?.clear();}catch(r){throw new d(`SQLite exec failed: ${this.errorMessage(r)}`,r)}}async execBatch(e){for(let t of e)await this.exec(t);}async begin(){let e=this.requireBackend();if(this.readOnlyFlag)throw new l("Cannot begin transaction on read-only SQLite database");let t=this.pushTxDepth();try{t===1?e.exec("BEGIN"):e.exec(`SAVEPOINT sp_${t}`);}catch(r){this.popTxDepth();let a=t===1?"BEGIN":`SAVEPOINT sp_${t}`;throw new l(`${a} failed`,r)}return new L(this,t)}async withTransaction(e){let t=await this.begin();try{let r=await e(t);return await t.commit(),r}catch(r){try{await t.rollback();}catch{}throw r}}getTransactionDepth(){return this.inTxDepth}commitRoot(){this.requireBackend().exec("COMMIT");}rollbackRoot(){this.requireBackend().exec("ROLLBACK");}rollbackToSavepoint(e){this.requireBackend().exec(`ROLLBACK TO SAVEPOINT ${e}`);}execSavepoint(e){this.requireBackend().exec(`SAVEPOINT ${e}`);}execRelease(e){this.requireBackend().exec(`RELEASE SAVEPOINT ${e}`);}execRollbackTo(e){this.requireBackend().exec(`ROLLBACK TO SAVEPOINT ${e}`);}pushTxDepth(){return this.inTxDepth+=1}popTxDepth(){this.inTxDepth>0&&(this.inTxDepth-=1);}errorMessage(e){return e instanceof Error?e.message:String(e)}};var le=256,$=class{constructor(){i(this,"cache",new Map);}get(e){let t=this.cache.get(e);if(t)return this.cache.delete(e),this.cache.set(e,t),t;let r=T(e,"numbered");if(this.cache.size>=le){let a=this.cache.keys().next().value;a!==void 0&&this.cache.delete(a);}return this.cache.set(e,r),r}clear(){this.cache.clear();}},ce=n=>n==null?{}:{...n},de=n=>n.map(e=>ce(e)),I=n=>{if(!x(n))throw new l(`Unsafe SQL identifier: ${JSON.stringify(n)}`);return `"${n}"`};function K(n,e){return n.includes("?")?{sql:T(n,"numbered"),params:e?[...e]:[]}:{sql:n,params:void 0}}var C=class{constructor(e,t){i(this,"db",e);i(this,"depth");i(this,"finished",false);this.depth=t;}get client(){return this.db.getClient(this.depth)}isFinished(){return this.finished}assertOpen(){if(this.finished)throw new l("Transaction already finalized")}async query(e,t){return this.assertOpen(),await W(this.client,e,t)}async queryOne(e,t){let r=await this.query(e,t);return r.length>0?r[0]??null:null}async execute(e,t){return this.assertOpen(),await G(this.client,e,t)}async exec(e){this.assertOpen(),await z(this.client,e);}async commit(){if(!this.finished)if(this.finished=true,this.depth===1)try{await this.client.query("COMMIT");}finally{this.db.releaseTxClient(false),this.db.clearTxCtx();}else await this.client.query(`RELEASE SAVEPOINT sp_${this.depth}`);}async rollback(){if(!this.finished)if(this.finished=true,this.depth===1)try{await this.client.query("ROLLBACK");}catch{}finally{this.db.releaseTxClient(false),this.db.clearTxCtx();}else try{await this.client.query(`ROLLBACK TO SAVEPOINT sp_${this.depth}`);}catch{}}async savepoint(e){this.assertOpen(),await this.client.query(`SAVEPOINT ${I(e)}`);}async release(e){this.assertOpen(),await this.client.query(`RELEASE SAVEPOINT ${I(e)}`);}async rollbackTo(e){this.assertOpen(),await this.client.query(`ROLLBACK TO SAVEPOINT ${I(e)}`);}};async function W(n,e,t){let{sql:r,params:a}=K(e,t);try{let s=await n.query(r,a);return de(s.rows)}catch(s){throw new d(`PostgreSQL query failed: ${s instanceof Error?s.message:String(s)}`,s)}}async function G(n,e,t){let{sql:r,params:a}=K(e,t);try{return {changes:(await n.query(r,a)).rowCount??0}}catch(s){throw new d(`PostgreSQL execute failed: ${s instanceof Error?s.message:String(s)}`,s)}}async function z(n,e){try{await n.query(e);}catch(t){throw new d(`PostgreSQL exec failed: ${t instanceof Error?t.message:String(t)}`,t)}}async function ue(n,e){if(e.length===0)return;let t=e.join(`;
+`)+";";await z(n,t);}var v=class{constructor(e){i(this,"config",e);i(this,"flavor","postgresql");i(this,"sqliteBackend");i(this,"pool",null);i(this,"translatedSqlCache",new $);i(this,"txCtx",null);i(this,"lastTxDepth",0);}async initialize(){if(!this.pool)try{this.pool=new pg.Pool({host:this.config.host??"localhost",port:this.config.port??5432,user:this.config.username??"postgres",password:this.config.password??"",database:this.config.database??"eas_database",ssl:this.config.ssl??!1,max:this.config.poolSize??10}),(await this.pool.connect()).release();}catch(e){throw this.pool=null,new o("Failed to connect to PostgreSQL",e)}}async close(){if(!this.pool)return;let e=this.pool;this.pool=null;try{await e.end();}catch(t){throw new o("Failed to close PostgreSQL pool",t)}finally{this.translatedSqlCache.clear(),this.txCtx=null,this.lastTxDepth=0;}}isConnected(){return this.pool===null?false:!this.pool.ended&&!this.pool.closing}requirePool(){if(!this.pool)throw new o("PostgreSQL database not initialized. Call initialize() first.");return this.pool}async query(e,t){let r=await this.requirePool().connect();try{return await W(r,e,t)}finally{r.release();}}async queryOne(e,t){let r=await this.query(e,t);return r.length>0?r[0]??null:null}async execute(e,t){let r=await this.requirePool().connect();try{return await G(r,e,t)}finally{r.release();}}async exec(e){let t=await this.requirePool().connect();try{await z(t,e);}finally{t.release();}}async execBatch(e){if(e.length===0)return;let t=await this.requirePool().connect();try{await ue(t,e);}finally{t.release();}}async begin(){let e=this.requirePool(),t=this.pushTxDepth();if(t>1){let a=this.requireCtx(t);try{await a.client.query(`SAVEPOINT sp_${t}`);}catch(s){throw this.popTxDepth(),new l(`SAVEPOINT sp_${t} failed`,s)}return new C(this,t)}let r;try{r=await e.connect();}catch(a){throw this.popTxDepth(),new l("BEGIN failed: cannot acquire client",a)}try{await r.query("BEGIN");}catch(a){throw r.release(true),this.popTxDepth(),new l("BEGIN failed",a)}return this.txCtx={client:r,depth:t},new C(this,t)}requireCtx(e){if(!this.txCtx)throw new l(`No active transaction (depth=${e})`);return this.txCtx}getClient(e){return this.requireCtx(e).client}clearTxCtx(){this.txCtx=null,this.lastTxDepth=0,this.translatedSqlCache.clear();}releaseTxClient(e){let t=this.txCtx;if(t)try{t.client.release(e);}catch{}}async withTransaction(e){let t=await this.begin();try{let r=await e(t);return await t.commit(),r}catch(r){try{await t.rollback();}catch{}throw r}}pushTxDepth(){return this.lastTxDepth+=1}popTxDepth(){this.lastTxDepth>0&&(this.lastTxDepth-=1);}getTransactionDepth(){return this.lastTxDepth}};var P=class{static create(e){switch(e.flavor){case "sqlite":return new R(e);case "postgresql":return new v(e);default:{let t=e.flavor;throw new o(`Unsupported database flavor: ${String(t)}`)}}}};var he=256,A=class{constructor(e){i(this,"flavor","sqlite");i(this,"sqliteBackend");i(this,"backend",null);i(this,"stmtCache",null);i(this,"readOnlyFlag",false);i(this,"initialized",false);i(this,"walShmSymlink",null);i(this,"effectiveDbPath",null);i(this,"dbPath");this.sqliteBackend=e.backend===void 0||e.backend==="auto"?f():e.backend,this.dbPath=e.path??":memory:";}resolveBackendPath(e){return e===":memory:"?"":e}initialize(){if(this.initialized)return;let e=this.walModeDefault(),t=this.foreignKeysDefault(),r=this.readonlyDefault(),a=this.busyTimeoutDefault(),s=this.resolveOpenPath(this.dbPath,e?this.walShmPathDefault():void 0),u=s===":memory:"?"":s;try{this.backend=this.createBackend(u,{readonly:r});}catch(q){throw this.cleanupWalShmSymlink(),new o(`Failed to create SQLite backend (${this.sqliteBackend}) at "${s}"`,q)}this.readOnlyFlag=r,this.stmtCache=new N(this.backend);try{!r&&this.dbPath!==":memory:"&&e&&this.backend.exec("PRAGMA journal_mode = WAL"),!r&&t&&this.backend.exec("PRAGMA foreign_keys = ON"),this.backend.exec(`PRAGMA busy_timeout = ${a}`);}catch(q){throw this.backend=null,this.stmtCache=null,this.cleanupWalShmSymlink(),new o("Failed to apply SQLite pragmas",q)}this.initialized=true;}close(){if(!this.backend){this.stmtCache?.clear(),this.stmtCache=null,this.initialized=false,this.cleanupWalShmSymlink();return}try{this.backend.close();}finally{this.backend=null,this.stmtCache?.clear(),this.stmtCache=null,this.readOnlyFlag=false,this.initialized=false,this.cleanupWalShmSymlink();}}isOpen(){return this.backend?.open===true}isReadOnly(){return this.readOnlyFlag}getDbPath(){return this.dbPath}getBackend(){return this.sqliteBackend}getJournalMode(){this.assertInitialized();let e=this.requireBackend().pragma("journal_mode"),t=Array.isArray(e)?e[0]:e;if(t==null)return "";if(typeof t=="object"){let r=t.journal_mode;return typeof r=="string"?r.toLowerCase():String(r??"").toLowerCase()}return String(t).toLowerCase()}prepare(e){this.assertInitialized();try{return this.requireCache().get(e)}catch(t){throw t instanceof o?t:new d(`SQLite prepare failed: ${H(t)}`,t)}}exec(e){this.assertInitialized();let t=this.requireBackend();try{t.exec(e),pe(e)&&this.stmtCache?.clear();}catch(r){throw new d(`SQLite exec failed: ${H(r)}`,r)}}pragma(e,t){return this.assertInitialized(),this.requireBackend().pragma(e,t)}transaction(e){if(this.assertInitialized(),this.readOnlyFlag)throw new l("Cannot begin transaction on read-only SQLite database");return this.requireBackend().transaction(e)}execBatch(e){if(e.length!==0)for(let t of e)this.exec(t);}resolveOpenPath(e,t){if(e===":memory:"||t===void 0||t===""||this.sqliteBackend!=="better-sqlite3")return e;let r=h__namespace.dirname(e);if(h__namespace.resolve(r)===h__namespace.resolve(t))return e;let a=h__namespace.basename(e),s=h__namespace.join(t,a);try{try{let u=m__namespace.lstatSync(s);(u.isSymbolicLink()||u.isFile())&&m__namespace.unlinkSync(s);}catch{}return m__namespace.symlinkSync(h__namespace.resolve(e),s),this.walShmSymlink=s,this.effectiveDbPath=s,s}catch(u){throw new o(`Failed to create symlink for WAL at "${t}" \u2192 "${e}". Check directory existence & write permission.`,u)}}cleanupWalShmSymlink(){if(this.walShmSymlink){try{m__namespace.unlinkSync(this.walShmSymlink);}catch{}this.walShmSymlink=null,this.effectiveDbPath=null;}}createBackend(e,t){switch(this.sqliteBackend){case "better-sqlite3":return new w(e,{readonly:t.readonly});case "node:sqlite":return new b(e);case "@tursodatabase/database":return new k(e);default:throw new o(`Unsupported SQLite backend: ${String(this.sqliteBackend)}`)}}requireBackend(){if(!this.backend)throw new o("SQLite database not initialized. Call initialize() first.");return this.backend}requireCache(){if(!this.stmtCache)throw new o("SQLite database not initialized. Call initialize() first.");return this.stmtCache}assertInitialized(){if(!this.initialized)throw new o("SyncSqliteConnection not initialized. Call initialize() first.")}walModeDefault(){return  true}foreignKeysDefault(){return  true}readonlyDefault(){return  false}busyTimeoutDefault(){return 5e3}walShmPathDefault(){}syncStmtCacheAccessor(){return this.requireCache()}},N=class{constructor(e){i(this,"backend",e);i(this,"cache",new Map);}get(e){let t=this.cache.get(e);if(t)return this.cache.delete(e),this.cache.set(e,t),t;let r=this.backend.prepare(e);if(this.cache.size>=he){let a=this.cache.keys().next().value;a!==void 0&&this.cache.delete(a);}return this.cache.set(e,r),r}clear(){this.cache.clear();}};function pe(n){let e=n.trimStart();if(e.length===0)return  false;let a=((e.split(`
+`,1)[0]??"").trimStart().split(/\s+/,1)[0]??"").toUpperCase();return a==="CREATE"||a==="DROP"||a==="ALTER"||a==="TRUNCATE"||a==="REPLACE"}function H(n){return n instanceof Error?n.message:String(n)}function me(n={}){let e=n.backend===void 0||n.backend==="auto"?f():n.backend,t=new A({...n,backend:e}),r=n.path??":memory:";if(r!==":memory:"){let a=h__namespace.dirname(r);try{m__namespace.mkdirSync(a,{recursive:!0});}catch(s){throw new o(`Failed to ensure directory for SQLite database at "${r}"`,s)}}return t}exports.ConnectionError=o;exports.DatabaseError=S;exports.DatabaseFactory=P;exports.PostgresDatabase=v;exports.QueryError=d;exports.SqliteDatabase=R;exports.SyncSqliteConnection=A;exports.TransactionError=l;exports.createSyncSqliteConnection=me;exports.default=P;exports.isSafeIdent=x;exports.resolveDefaultSqliteBackend=f;exports.translatePlaceholders=T;

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+import { PoolClient } from 'pg';
+
+type DatabaseFlavor = 'sqlite' | 'postgresql';
+type SqliteBackendKind = 'better-sqlite3' | 'node:sqlite' | '@tursodatabase/database';
+interface SqliteDatabaseConfig {
+    backend?: SqliteBackendKind | 'auto';
+    path?: string;
+    walMode?: boolean;
+    walShmPath?: string;
+    foreignKeys?: boolean;
+    readonly?: boolean;
+    busyTimeoutMs?: number;
+}
+interface DatabaseConfig {
+    flavor: DatabaseFlavor;
+    sqlite?: SqliteDatabaseConfig;
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    database?: string;
+    ssl?: boolean;
+    poolSize?: number;
+}
+type Row = Record<string, unknown>;
+interface ExecuteResult {
+    changes: number;
+    lastInsertRowid?: number | bigint;
+}
+interface TransactionHandle {
+    readonly depth: number;
+    isFinished(): boolean;
+    query<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_[]>;
+    queryOne<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_ | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    exec(sql: string): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    savepoint(name: string): Promise<void>;
+    release(name: string): Promise<void>;
+    rollbackTo(name: string): Promise<void>;
+}
+interface DatabaseInterface {
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    readonly flavor: DatabaseFlavor;
+    readonly sqliteBackend?: SqliteBackendKind;
+    query<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_[]>;
+    queryOne<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_ | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    exec(sql: string): Promise<void>;
+    begin(): Promise<TransactionHandle>;
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    execBatch(sql: ReadonlyArray<string>): Promise<void>;
+}
+declare class DatabaseError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+declare class ConnectionError extends DatabaseError {
+    constructor(message: string, cause?: unknown);
+}
+declare class QueryError extends DatabaseError {
+    constructor(message: string, cause?: unknown);
+}
+declare class TransactionError extends DatabaseError {
+    constructor(message: string, cause?: unknown);
+}
+declare const translatePlaceholders: (sql: string, style: "qmark" | "numbered") => string;
+declare const isSafeIdent: (name: string) => boolean;
+
+interface SqliteStatementAdapter {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+}
+interface SqliteBackendAdapter {
+    readonly backend: SqliteBackendKind;
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatementAdapter;
+    pragma(name: string, opts?: {
+        simple?: boolean;
+    }): unknown;
+    transaction<T extends (...args: never[]) => unknown>(fn: T): T;
+    close(): void;
+    readonly open: boolean;
+}
+
+declare const resolveDefaultSqliteBackend: () => SqliteBackendKind;
+
+declare class SqliteDatabase implements DatabaseInterface {
+    readonly config: DatabaseConfig;
+    readonly flavor: "sqlite";
+    readonly sqliteBackend: SqliteBackendKind;
+    private backend;
+    private stmtCache;
+    private inTxDepth;
+    private readOnlyFlag;
+    private initialized;
+    private walShmSymlink;
+    private effectiveDbPath;
+    constructor(config: DatabaseConfig);
+    initialize(): Promise<void>;
+    private resolveOpenPath;
+    private cleanupWalShmSymlink;
+    private createBackend;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    isReadOnly(): boolean;
+    private requireBackend;
+    private requireCache;
+    query<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R[]>;
+    queryOne<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    private prepareOrThrow;
+    exec(sql: string): Promise<void>;
+    execBatch(statements: ReadonlyArray<string>): Promise<void>;
+    begin(): Promise<TransactionHandle>;
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    getTransactionDepth(): number;
+    commitRoot(): void;
+    rollbackRoot(): void;
+    rollbackToSavepoint(name: string): void;
+    execSavepoint(name: string): void;
+    execRelease(name: string): void;
+    execRollbackTo(name: string): void;
+    pushTxDepth(): number;
+    popTxDepth(): void;
+    private errorMessage;
+}
+
+declare class PostgresDatabase implements DatabaseInterface {
+    readonly config: DatabaseConfig;
+    readonly flavor: "postgresql";
+    readonly sqliteBackend: undefined;
+    private pool;
+    private readonly translatedSqlCache;
+    private txCtx;
+    private lastTxDepth;
+    constructor(config: DatabaseConfig);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    private requirePool;
+    query<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R[]>;
+    queryOne<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    exec(sql: string): Promise<void>;
+    execBatch(statements: ReadonlyArray<string>): Promise<void>;
+    begin(): Promise<TransactionHandle>;
+    private requireCtx;
+    getClient(depth: number): PoolClient;
+    clearTxCtx(): void;
+    releaseTxClient(destroy: boolean): void;
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    pushTxDepth(): number;
+    popTxDepth(): void;
+    getTransactionDepth(): number;
+}
+
+declare class DatabaseFactory {
+    static create(config: DatabaseConfig): DatabaseInterface;
+}
+
+interface SyncSqliteConnectionConfig {
+    backend?: SqliteBackendKind | 'auto';
+    path?: string;
+    walMode?: boolean;
+    walShmPath?: string;
+    foreignKeys?: boolean;
+    readonly?: boolean;
+    busyTimeoutMs?: number;
+}
+declare class SyncSqliteConnection {
+    readonly flavor: "sqlite";
+    readonly sqliteBackend: SqliteBackendKind;
+    private backend;
+    private stmtCache;
+    private readOnlyFlag;
+    private initialized;
+    private walShmSymlink;
+    private effectiveDbPath;
+    private readonly dbPath;
+    constructor(config: SyncSqliteConnectionConfig);
+    private resolveBackendPath;
+    initialize(): void;
+    close(): void;
+    isOpen(): boolean;
+    isReadOnly(): boolean;
+    getDbPath(): string;
+    getBackend(): SqliteBackendKind;
+    getJournalMode(): string;
+    prepare(sql: string): SqliteStatementAdapter;
+    exec(sql: string): void;
+    pragma(name: string, opts?: {
+        simple?: boolean;
+    }): unknown;
+    transaction<T extends (...args: never[]) => unknown>(fn: T): T;
+    execBatch(statements: ReadonlyArray<string>): void;
+    private resolveOpenPath;
+    private cleanupWalShmSymlink;
+    private createBackend;
+    private requireBackend;
+    private requireCache;
+    private assertInitialized;
+    private walModeDefault;
+    private foreignKeysDefault;
+    private readonlyDefault;
+    private busyTimeoutDefault;
+    private walShmPathDefault;
+    private syncStmtCacheAccessor;
+}
+declare function createSyncSqliteConnection(config?: SyncSqliteConnectionConfig): SyncSqliteConnection;
+
+export { ConnectionError, type DatabaseConfig, DatabaseError, DatabaseFactory, type DatabaseFlavor, type DatabaseInterface, type ExecuteResult, PostgresDatabase, QueryError, type Row, type SqliteBackendAdapter, type SqliteBackendKind, SqliteDatabase, type SqliteDatabaseConfig, type SqliteStatementAdapter, SyncSqliteConnection, type SyncSqliteConnectionConfig, TransactionError, type TransactionHandle, createSyncSqliteConnection, DatabaseFactory as default, isSafeIdent, resolveDefaultSqliteBackend, translatePlaceholders };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import { PoolClient } from 'pg';
+
+type DatabaseFlavor = 'sqlite' | 'postgresql';
+type SqliteBackendKind = 'better-sqlite3' | 'node:sqlite' | '@tursodatabase/database';
+interface SqliteDatabaseConfig {
+    backend?: SqliteBackendKind | 'auto';
+    path?: string;
+    walMode?: boolean;
+    walShmPath?: string;
+    foreignKeys?: boolean;
+    readonly?: boolean;
+    busyTimeoutMs?: number;
+}
+interface DatabaseConfig {
+    flavor: DatabaseFlavor;
+    sqlite?: SqliteDatabaseConfig;
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    database?: string;
+    ssl?: boolean;
+    poolSize?: number;
+}
+type Row = Record<string, unknown>;
+interface ExecuteResult {
+    changes: number;
+    lastInsertRowid?: number | bigint;
+}
+interface TransactionHandle {
+    readonly depth: number;
+    isFinished(): boolean;
+    query<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_[]>;
+    queryOne<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_ | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    exec(sql: string): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    savepoint(name: string): Promise<void>;
+    release(name: string): Promise<void>;
+    rollbackTo(name: string): Promise<void>;
+}
+interface DatabaseInterface {
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    readonly flavor: DatabaseFlavor;
+    readonly sqliteBackend?: SqliteBackendKind;
+    query<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_[]>;
+    queryOne<Row_ extends Record<string, unknown> = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<Row_ | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    exec(sql: string): Promise<void>;
+    begin(): Promise<TransactionHandle>;
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    execBatch(sql: ReadonlyArray<string>): Promise<void>;
+}
+declare class DatabaseError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+declare class ConnectionError extends DatabaseError {
+    constructor(message: string, cause?: unknown);
+}
+declare class QueryError extends DatabaseError {
+    constructor(message: string, cause?: unknown);
+}
+declare class TransactionError extends DatabaseError {
+    constructor(message: string, cause?: unknown);
+}
+declare const translatePlaceholders: (sql: string, style: "qmark" | "numbered") => string;
+declare const isSafeIdent: (name: string) => boolean;
+
+interface SqliteStatementAdapter {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+}
+interface SqliteBackendAdapter {
+    readonly backend: SqliteBackendKind;
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatementAdapter;
+    pragma(name: string, opts?: {
+        simple?: boolean;
+    }): unknown;
+    transaction<T extends (...args: never[]) => unknown>(fn: T): T;
+    close(): void;
+    readonly open: boolean;
+}
+
+declare const resolveDefaultSqliteBackend: () => SqliteBackendKind;
+
+declare class SqliteDatabase implements DatabaseInterface {
+    readonly config: DatabaseConfig;
+    readonly flavor: "sqlite";
+    readonly sqliteBackend: SqliteBackendKind;
+    private backend;
+    private stmtCache;
+    private inTxDepth;
+    private readOnlyFlag;
+    private initialized;
+    private walShmSymlink;
+    private effectiveDbPath;
+    constructor(config: DatabaseConfig);
+    initialize(): Promise<void>;
+    private resolveOpenPath;
+    private cleanupWalShmSymlink;
+    private createBackend;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    isReadOnly(): boolean;
+    private requireBackend;
+    private requireCache;
+    query<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R[]>;
+    queryOne<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    private prepareOrThrow;
+    exec(sql: string): Promise<void>;
+    execBatch(statements: ReadonlyArray<string>): Promise<void>;
+    begin(): Promise<TransactionHandle>;
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    getTransactionDepth(): number;
+    commitRoot(): void;
+    rollbackRoot(): void;
+    rollbackToSavepoint(name: string): void;
+    execSavepoint(name: string): void;
+    execRelease(name: string): void;
+    execRollbackTo(name: string): void;
+    pushTxDepth(): number;
+    popTxDepth(): void;
+    private errorMessage;
+}
+
+declare class PostgresDatabase implements DatabaseInterface {
+    readonly config: DatabaseConfig;
+    readonly flavor: "postgresql";
+    readonly sqliteBackend: undefined;
+    private pool;
+    private readonly translatedSqlCache;
+    private txCtx;
+    private lastTxDepth;
+    constructor(config: DatabaseConfig);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    private requirePool;
+    query<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R[]>;
+    queryOne<R extends Row = Row>(sql: string, params?: ReadonlyArray<unknown>): Promise<R | null>;
+    execute(sql: string, params?: ReadonlyArray<unknown>): Promise<ExecuteResult>;
+    exec(sql: string): Promise<void>;
+    execBatch(statements: ReadonlyArray<string>): Promise<void>;
+    begin(): Promise<TransactionHandle>;
+    private requireCtx;
+    getClient(depth: number): PoolClient;
+    clearTxCtx(): void;
+    releaseTxClient(destroy: boolean): void;
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    pushTxDepth(): number;
+    popTxDepth(): void;
+    getTransactionDepth(): number;
+}
+
+declare class DatabaseFactory {
+    static create(config: DatabaseConfig): DatabaseInterface;
+}
+
+interface SyncSqliteConnectionConfig {
+    backend?: SqliteBackendKind | 'auto';
+    path?: string;
+    walMode?: boolean;
+    walShmPath?: string;
+    foreignKeys?: boolean;
+    readonly?: boolean;
+    busyTimeoutMs?: number;
+}
+declare class SyncSqliteConnection {
+    readonly flavor: "sqlite";
+    readonly sqliteBackend: SqliteBackendKind;
+    private backend;
+    private stmtCache;
+    private readOnlyFlag;
+    private initialized;
+    private walShmSymlink;
+    private effectiveDbPath;
+    private readonly dbPath;
+    constructor(config: SyncSqliteConnectionConfig);
+    private resolveBackendPath;
+    initialize(): void;
+    close(): void;
+    isOpen(): boolean;
+    isReadOnly(): boolean;
+    getDbPath(): string;
+    getBackend(): SqliteBackendKind;
+    getJournalMode(): string;
+    prepare(sql: string): SqliteStatementAdapter;
+    exec(sql: string): void;
+    pragma(name: string, opts?: {
+        simple?: boolean;
+    }): unknown;
+    transaction<T extends (...args: never[]) => unknown>(fn: T): T;
+    execBatch(statements: ReadonlyArray<string>): void;
+    private resolveOpenPath;
+    private cleanupWalShmSymlink;
+    private createBackend;
+    private requireBackend;
+    private requireCache;
+    private assertInitialized;
+    private walModeDefault;
+    private foreignKeysDefault;
+    private readonlyDefault;
+    private busyTimeoutDefault;
+    private walShmPathDefault;
+    private syncStmtCacheAccessor;
+}
+declare function createSyncSqliteConnection(config?: SyncSqliteConnectionConfig): SyncSqliteConnection;
+
+export { ConnectionError, type DatabaseConfig, DatabaseError, DatabaseFactory, type DatabaseFlavor, type DatabaseInterface, type ExecuteResult, PostgresDatabase, QueryError, type Row, type SqliteBackendAdapter, type SqliteBackendKind, SqliteDatabase, type SqliteDatabaseConfig, type SqliteStatementAdapter, SyncSqliteConnection, type SyncSqliteConnectionConfig, TransactionError, type TransactionHandle, createSyncSqliteConnection, DatabaseFactory as default, isSafeIdent, resolveDefaultSqliteBackend, translatePlaceholders };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+import {createRequire}from'module';import*as y from'fs';import*as p from'path';import {Pool}from'pg';var j=Object.defineProperty;var U=(n,e,t)=>e in n?j(n,e,{enumerable:true,configurable:true,writable:true,value:t}):n[e]=t;var i=(n,e,t)=>U(n,typeof e!="symbol"?e+"":e,t);var x=class extends Error{constructor(t,r,a){super(r);i(this,"code");i(this,"cause");this.name="DatabaseError",this.code=t,this.cause=a;}},o=class extends x{constructor(e,t){super("CONNECTION",e,t),this.name="ConnectionError";}},c=class extends x{constructor(e,t){super("QUERY",e,t),this.name="QueryError";}},l=class extends x{constructor(e,t){super("TX",e,t),this.name="TransactionError";}},C=(n,e)=>{if(e==="qmark")return n;let t=0;return n.replace(/\?/g,()=>`$${++t}`)},q=n=>/^[A-Za-z_][A-Za-z0-9_]*$/.test(n);var J=createRequire(import.meta.url),E=(n,e)=>{try{let t=J(n);return e(t)}catch{return  false}},w=()=>{if(E("better-sqlite3",n=>typeof n.default=="function"))return "better-sqlite3";if(E("node:sqlite",n=>typeof n.DatabaseSync=="function"))return "node:sqlite";if(E("@tursodatabase/database",n=>typeof(n.default??n)=="function"))return "@tursodatabase/database";throw new o(`No SQLite backend available. Please install one of:
+  - better-sqlite3 (recommended; highest perf)
+  - node:sqlite (built-in since Node.js 22.5+)
+  - @tursodatabase/database`)};var f=class{constructor(e){i(this,"stmt",e);}run(...e){return this.stmt.run(...e)}get(...e){return this.stmt.get(...e)}all(...e){return this.stmt.all(...e)}iterate(...e){return this.stmt.iterate(...e)}};var X=createRequire(import.meta.url),_=n=>typeof n=="function"&&n.prototype!==void 0,b=class{constructor(e,t={}){i(this,"backend","better-sqlite3");i(this,"db");let r=X("better-sqlite3"),a=_(r)?r:r.default;if(!_(a))throw new TypeError(`better-sqlite3 import did not expose a constructor (got ${typeof r})`);this.db=new a(e,t);}exec(e){this.db.exec(e);}prepare(e){return new f(this.db.prepare(e))}pragma(e,t){return this.db.pragma(e,t)}transaction(e){return this.db.transaction(e)}close(){this.db.open&&this.db.close();}get open(){return this.db.open}};var te=createRequire(import.meta.url),k=class{constructor(e){i(this,"backend","node:sqlite");i(this,"db");let t=te("node:sqlite");this.db=new t.DatabaseSync(e);}exec(e){this.db.exec(e);}prepare(e){return new f(this.db.prepare(e))}pragma(e,t){return this.db.exec(`PRAGMA ${e}`),t?.simple!==true?void 0:this.db.prepare("SELECT pragma_value AS v FROM pragma_value(?)").get(e)}transaction(e){return((...r)=>{this.db.exec("BEGIN");let a;try{a=e(...r);}catch(s){try{this.db.exec("ROLLBACK");}catch{}throw s}return this.db.exec("COMMIT"),a})}close(){this.db.isOpen&&this.db.close();}get open(){return this.db.isOpen}};var re=createRequire(import.meta.url),Q=n=>typeof n=="function"&&n.prototype!==void 0,g=class{constructor(e){i(this,"backend","@tursodatabase/database");i(this,"db",null);let t=re("@tursodatabase/database"),r=Q(t)?t:t.default;if(!Q(r))throw new TypeError(`@tursodatabase/database import did not expose a constructor (got ${typeof t})`);this.db=new r(e);}requireDb(){if(!this.db)throw new Error(`Turso backend not initialized (db=${String(this.db)})`);return this.db}exec(e){this.requireDb().exec(e);}prepare(e){return new f(this.requireDb().prepare(e))}pragma(e){this.requireDb().exec(`PRAGMA ${e}`);}transaction(e){return((...r)=>{let a=this.requireDb();a.exec("BEGIN");let s;try{s=e(...r);}catch(d){try{a.exec("ROLLBACK");}catch{}throw d}return a.exec("COMMIT"),s})}close(){if(this.db)try{this.db.close();}finally{this.db=null;}}get open(){return this.db!==null}};var ae=256,L=class{constructor(e){i(this,"backend",e);i(this,"cache",new Map);}get(e){let t=this.cache.get(e);if(t)return this.cache.delete(e),this.cache.set(e,t),t;let r=this.backend.prepare(e);if(this.cache.size>=ae){let a=this.cache.keys().next().value;a!==void 0&&this.cache.delete(a);}return this.cache.set(e,r),r}clear(){this.cache.clear();}},K=n=>n==null?{}:typeof n!="object"?{}:{...n},ie=n=>n.map(K);function O(n){if(!q(n))throw new l(`Unsafe SQL identifier: ${JSON.stringify(n)}`);return `"${n}"`}function se(n){let e=n.trimStart();if(e.length===0)return  false;let a=((e.split(`
+`,1)[0]??"").trimStart().split(/\s+/,1)[0]??"").toUpperCase();return a==="CREATE"||a==="DROP"||a==="ALTER"||a==="TRUNCATE"||a==="REPLACE"}var I=class{constructor(e,t){i(this,"db",e);i(this,"depth");i(this,"finished",false);this.depth=t;}isFinished(){return this.finished}async query(e,t){return this.assertOpen(),this.db.query(e,t)}async queryOne(e,t){return this.assertOpen(),this.db.queryOne(e,t)}async execute(e,t){return this.assertOpen(),this.db.execute(e,t)}async exec(e){this.assertOpen(),await this.db.exec(e);}async commit(){this.finished||(this.finished=true,this.depth===1&&this.db.commitRoot(),this.db.popTxDepth());}async rollback(){if(!this.finished){this.finished=true;try{this.depth===1?this.db.rollbackRoot():this.db.rollbackToSavepoint(`sp_${this.depth}`);}catch{}this.db.popTxDepth();}}async savepoint(e){this.assertOpen(),this.db.execSavepoint(O(e));}async release(e){this.assertOpen(),this.db.execRelease(O(e));}async rollbackTo(e){this.assertOpen(),this.db.execRollbackTo(O(e));}assertOpen(){if(this.finished)throw new l(`Transaction already finalized (depth=${this.depth})`)}},v=class{constructor(e){i(this,"config",e);i(this,"flavor","sqlite");i(this,"sqliteBackend");i(this,"backend",null);i(this,"stmtCache",null);i(this,"inTxDepth",0);i(this,"readOnlyFlag",false);i(this,"initialized",false);i(this,"walShmSymlink",null);i(this,"effectiveDbPath",null);let t=e.sqlite??{};this.sqliteBackend=t.backend===void 0||t.backend==="auto"?w():t.backend;}async initialize(){if(this.initialized)return;let e=this.config.sqlite??{},t=e.path??":memory:",r=e.walMode!==false,a=e.foreignKeys!==false,s=e.readonly===true,d=e.busyTimeoutMs??5e3,R=e.walShmPath,F=this.resolveOpenPath(t,R);try{this.backend=this.createBackend(F,{readonly:s});}catch(B){throw this.cleanupWalShmSymlink(),new o(`Failed to create SQLite backend (${this.sqliteBackend}) at "${F}"`,B)}this.readOnlyFlag=s,this.stmtCache=new L(this.backend);try{!s&&t!==":memory:"&&r&&this.backend.exec("PRAGMA journal_mode = WAL"),!s&&a&&this.backend.exec("PRAGMA foreign_keys = ON"),this.backend.exec(`PRAGMA busy_timeout = ${d}`);}catch(B){throw this.backend=null,this.stmtCache=null,this.cleanupWalShmSymlink(),new o("Failed to apply SQLite pragmas",B)}this.initialized=true;}resolveOpenPath(e,t){if(e===":memory:"||t===void 0||t===""||this.sqliteBackend!=="better-sqlite3")return e;let r=p.dirname(e);if(p.resolve(r)===p.resolve(t))return e;let a=p.basename(e),s=p.join(t,a);try{try{let d=y.lstatSync(s);(d.isSymbolicLink()||d.isFile())&&y.unlinkSync(s);}catch{}return y.symlinkSync(p.resolve(e),s),this.walShmSymlink=s,this.effectiveDbPath=s,s}catch(d){throw new o(`Failed to create symlink for WAL at "${t}" \u2192 "${e}". Check directory existence & write permission.`,d)}}cleanupWalShmSymlink(){if(this.walShmSymlink){try{y.unlinkSync(this.walShmSymlink);}catch{}this.walShmSymlink=null,this.effectiveDbPath=null;}}createBackend(e,t){switch(this.sqliteBackend){case "better-sqlite3":return new b(e,{readonly:t.readonly});case "node:sqlite":return new k(e);case "@tursodatabase/database":return new g(e);default:throw new o(`Unsupported SQLite backend: ${String(this.sqliteBackend)}`)}}async close(){if(!this.backend){this.stmtCache?.clear(),this.stmtCache=null,this.initialized=false,this.cleanupWalShmSymlink();return}try{this.backend.close();}finally{this.backend=null,this.stmtCache?.clear(),this.stmtCache=null,this.inTxDepth=0,this.initialized=false,this.cleanupWalShmSymlink();}}isConnected(){return this.backend?.open===true}isReadOnly(){return this.readOnlyFlag}requireBackend(){if(!this.backend)throw new o("SQLite database not initialized. Call initialize() first.");return this.backend}requireCache(){if(!this.stmtCache)throw new o("SQLite database not initialized. Call initialize() first.");return this.stmtCache}async query(e,t){let r=this.prepareOrThrow(e);try{return ie(r.all(...t??[]))}catch(a){throw new c(`SQLite query failed: ${this.errorMessage(a)}`,a)}}async queryOne(e,t){let r=this.prepareOrThrow(e);try{let a=r.get(...t??[]);return a==null?null:K(a)}catch(a){throw new c(`SQLite queryOne failed: ${this.errorMessage(a)}`,a)}}async execute(e,t){let r=this.prepareOrThrow(e);try{return r.run(...t??[])}catch(a){throw new c(`SQLite execute failed: ${this.errorMessage(a)}`,a)}}prepareOrThrow(e){try{return this.requireCache().get(e)}catch(t){throw t instanceof o?t:new c(`SQLite prepare failed: ${this.errorMessage(t)}`,t)}}async exec(e){let t=this.requireBackend();try{t.exec(e),se(e)&&this.stmtCache?.clear();}catch(r){throw new c(`SQLite exec failed: ${this.errorMessage(r)}`,r)}}async execBatch(e){for(let t of e)await this.exec(t);}async begin(){let e=this.requireBackend();if(this.readOnlyFlag)throw new l("Cannot begin transaction on read-only SQLite database");let t=this.pushTxDepth();try{t===1?e.exec("BEGIN"):e.exec(`SAVEPOINT sp_${t}`);}catch(r){this.popTxDepth();let a=t===1?"BEGIN":`SAVEPOINT sp_${t}`;throw new l(`${a} failed`,r)}return new I(this,t)}async withTransaction(e){let t=await this.begin();try{let r=await e(t);return await t.commit(),r}catch(r){try{await t.rollback();}catch{}throw r}}getTransactionDepth(){return this.inTxDepth}commitRoot(){this.requireBackend().exec("COMMIT");}rollbackRoot(){this.requireBackend().exec("ROLLBACK");}rollbackToSavepoint(e){this.requireBackend().exec(`ROLLBACK TO SAVEPOINT ${e}`);}execSavepoint(e){this.requireBackend().exec(`SAVEPOINT ${e}`);}execRelease(e){this.requireBackend().exec(`RELEASE SAVEPOINT ${e}`);}execRollbackTo(e){this.requireBackend().exec(`ROLLBACK TO SAVEPOINT ${e}`);}pushTxDepth(){return this.inTxDepth+=1}popTxDepth(){this.inTxDepth>0&&(this.inTxDepth-=1);}errorMessage(e){return e instanceof Error?e.message:String(e)}};var le=256,z=class{constructor(){i(this,"cache",new Map);}get(e){let t=this.cache.get(e);if(t)return this.cache.delete(e),this.cache.set(e,t),t;let r=C(e,"numbered");if(this.cache.size>=le){let a=this.cache.keys().next().value;a!==void 0&&this.cache.delete(a);}return this.cache.set(e,r),r}clear(){this.cache.clear();}},ce=n=>n==null?{}:{...n},de=n=>n.map(e=>ce(e)),$=n=>{if(!q(n))throw new l(`Unsafe SQL identifier: ${JSON.stringify(n)}`);return `"${n}"`};function W(n,e){return n.includes("?")?{sql:C(n,"numbered"),params:e?[...e]:[]}:{sql:n,params:void 0}}var P=class{constructor(e,t){i(this,"db",e);i(this,"depth");i(this,"finished",false);this.depth=t;}get client(){return this.db.getClient(this.depth)}isFinished(){return this.finished}assertOpen(){if(this.finished)throw new l("Transaction already finalized")}async query(e,t){return this.assertOpen(),await G(this.client,e,t)}async queryOne(e,t){let r=await this.query(e,t);return r.length>0?r[0]??null:null}async execute(e,t){return this.assertOpen(),await H(this.client,e,t)}async exec(e){this.assertOpen(),await M(this.client,e);}async commit(){if(!this.finished)if(this.finished=true,this.depth===1)try{await this.client.query("COMMIT");}finally{this.db.releaseTxClient(false),this.db.clearTxCtx();}else await this.client.query(`RELEASE SAVEPOINT sp_${this.depth}`);}async rollback(){if(!this.finished)if(this.finished=true,this.depth===1)try{await this.client.query("ROLLBACK");}catch{}finally{this.db.releaseTxClient(false),this.db.clearTxCtx();}else try{await this.client.query(`ROLLBACK TO SAVEPOINT sp_${this.depth}`);}catch{}}async savepoint(e){this.assertOpen(),await this.client.query(`SAVEPOINT ${$(e)}`);}async release(e){this.assertOpen(),await this.client.query(`RELEASE SAVEPOINT ${$(e)}`);}async rollbackTo(e){this.assertOpen(),await this.client.query(`ROLLBACK TO SAVEPOINT ${$(e)}`);}};async function G(n,e,t){let{sql:r,params:a}=W(e,t);try{let s=await n.query(r,a);return de(s.rows)}catch(s){throw new c(`PostgreSQL query failed: ${s instanceof Error?s.message:String(s)}`,s)}}async function H(n,e,t){let{sql:r,params:a}=W(e,t);try{return {changes:(await n.query(r,a)).rowCount??0}}catch(s){throw new c(`PostgreSQL execute failed: ${s instanceof Error?s.message:String(s)}`,s)}}async function M(n,e){try{await n.query(e);}catch(t){throw new c(`PostgreSQL exec failed: ${t instanceof Error?t.message:String(t)}`,t)}}async function ue(n,e){if(e.length===0)return;let t=e.join(`;
+`)+";";await M(n,t);}var T=class{constructor(e){i(this,"config",e);i(this,"flavor","postgresql");i(this,"sqliteBackend");i(this,"pool",null);i(this,"translatedSqlCache",new z);i(this,"txCtx",null);i(this,"lastTxDepth",0);}async initialize(){if(!this.pool)try{this.pool=new Pool({host:this.config.host??"localhost",port:this.config.port??5432,user:this.config.username??"postgres",password:this.config.password??"",database:this.config.database??"eas_database",ssl:this.config.ssl??!1,max:this.config.poolSize??10}),(await this.pool.connect()).release();}catch(e){throw this.pool=null,new o("Failed to connect to PostgreSQL",e)}}async close(){if(!this.pool)return;let e=this.pool;this.pool=null;try{await e.end();}catch(t){throw new o("Failed to close PostgreSQL pool",t)}finally{this.translatedSqlCache.clear(),this.txCtx=null,this.lastTxDepth=0;}}isConnected(){return this.pool===null?false:!this.pool.ended&&!this.pool.closing}requirePool(){if(!this.pool)throw new o("PostgreSQL database not initialized. Call initialize() first.");return this.pool}async query(e,t){let r=await this.requirePool().connect();try{return await G(r,e,t)}finally{r.release();}}async queryOne(e,t){let r=await this.query(e,t);return r.length>0?r[0]??null:null}async execute(e,t){let r=await this.requirePool().connect();try{return await H(r,e,t)}finally{r.release();}}async exec(e){let t=await this.requirePool().connect();try{await M(t,e);}finally{t.release();}}async execBatch(e){if(e.length===0)return;let t=await this.requirePool().connect();try{await ue(t,e);}finally{t.release();}}async begin(){let e=this.requirePool(),t=this.pushTxDepth();if(t>1){let a=this.requireCtx(t);try{await a.client.query(`SAVEPOINT sp_${t}`);}catch(s){throw this.popTxDepth(),new l(`SAVEPOINT sp_${t} failed`,s)}return new P(this,t)}let r;try{r=await e.connect();}catch(a){throw this.popTxDepth(),new l("BEGIN failed: cannot acquire client",a)}try{await r.query("BEGIN");}catch(a){throw r.release(true),this.popTxDepth(),new l("BEGIN failed",a)}return this.txCtx={client:r,depth:t},new P(this,t)}requireCtx(e){if(!this.txCtx)throw new l(`No active transaction (depth=${e})`);return this.txCtx}getClient(e){return this.requireCtx(e).client}clearTxCtx(){this.txCtx=null,this.lastTxDepth=0,this.translatedSqlCache.clear();}releaseTxClient(e){let t=this.txCtx;if(t)try{t.client.release(e);}catch{}}async withTransaction(e){let t=await this.begin();try{let r=await e(t);return await t.commit(),r}catch(r){try{await t.rollback();}catch{}throw r}}pushTxDepth(){return this.lastTxDepth+=1}popTxDepth(){this.lastTxDepth>0&&(this.lastTxDepth-=1);}getTransactionDepth(){return this.lastTxDepth}};var A=class{static create(e){switch(e.flavor){case "sqlite":return new v(e);case "postgresql":return new T(e);default:{let t=e.flavor;throw new o(`Unsupported database flavor: ${String(t)}`)}}}};var he=256,D=class{constructor(e){i(this,"flavor","sqlite");i(this,"sqliteBackend");i(this,"backend",null);i(this,"stmtCache",null);i(this,"readOnlyFlag",false);i(this,"initialized",false);i(this,"walShmSymlink",null);i(this,"effectiveDbPath",null);i(this,"dbPath");this.sqliteBackend=e.backend===void 0||e.backend==="auto"?w():e.backend,this.dbPath=e.path??":memory:";}resolveBackendPath(e){return e===":memory:"?"":e}initialize(){if(this.initialized)return;let e=this.walModeDefault(),t=this.foreignKeysDefault(),r=this.readonlyDefault(),a=this.busyTimeoutDefault(),s=this.resolveOpenPath(this.dbPath,e?this.walShmPathDefault():void 0),d=s===":memory:"?"":s;try{this.backend=this.createBackend(d,{readonly:r});}catch(R){throw this.cleanupWalShmSymlink(),new o(`Failed to create SQLite backend (${this.sqliteBackend}) at "${s}"`,R)}this.readOnlyFlag=r,this.stmtCache=new N(this.backend);try{!r&&this.dbPath!==":memory:"&&e&&this.backend.exec("PRAGMA journal_mode = WAL"),!r&&t&&this.backend.exec("PRAGMA foreign_keys = ON"),this.backend.exec(`PRAGMA busy_timeout = ${a}`);}catch(R){throw this.backend=null,this.stmtCache=null,this.cleanupWalShmSymlink(),new o("Failed to apply SQLite pragmas",R)}this.initialized=true;}close(){if(!this.backend){this.stmtCache?.clear(),this.stmtCache=null,this.initialized=false,this.cleanupWalShmSymlink();return}try{this.backend.close();}finally{this.backend=null,this.stmtCache?.clear(),this.stmtCache=null,this.readOnlyFlag=false,this.initialized=false,this.cleanupWalShmSymlink();}}isOpen(){return this.backend?.open===true}isReadOnly(){return this.readOnlyFlag}getDbPath(){return this.dbPath}getBackend(){return this.sqliteBackend}getJournalMode(){this.assertInitialized();let e=this.requireBackend().pragma("journal_mode"),t=Array.isArray(e)?e[0]:e;if(t==null)return "";if(typeof t=="object"){let r=t.journal_mode;return typeof r=="string"?r.toLowerCase():String(r??"").toLowerCase()}return String(t).toLowerCase()}prepare(e){this.assertInitialized();try{return this.requireCache().get(e)}catch(t){throw t instanceof o?t:new c(`SQLite prepare failed: ${V(t)}`,t)}}exec(e){this.assertInitialized();let t=this.requireBackend();try{t.exec(e),pe(e)&&this.stmtCache?.clear();}catch(r){throw new c(`SQLite exec failed: ${V(r)}`,r)}}pragma(e,t){return this.assertInitialized(),this.requireBackend().pragma(e,t)}transaction(e){if(this.assertInitialized(),this.readOnlyFlag)throw new l("Cannot begin transaction on read-only SQLite database");return this.requireBackend().transaction(e)}execBatch(e){if(e.length!==0)for(let t of e)this.exec(t);}resolveOpenPath(e,t){if(e===":memory:"||t===void 0||t===""||this.sqliteBackend!=="better-sqlite3")return e;let r=p.dirname(e);if(p.resolve(r)===p.resolve(t))return e;let a=p.basename(e),s=p.join(t,a);try{try{let d=y.lstatSync(s);(d.isSymbolicLink()||d.isFile())&&y.unlinkSync(s);}catch{}return y.symlinkSync(p.resolve(e),s),this.walShmSymlink=s,this.effectiveDbPath=s,s}catch(d){throw new o(`Failed to create symlink for WAL at "${t}" \u2192 "${e}". Check directory existence & write permission.`,d)}}cleanupWalShmSymlink(){if(this.walShmSymlink){try{y.unlinkSync(this.walShmSymlink);}catch{}this.walShmSymlink=null,this.effectiveDbPath=null;}}createBackend(e,t){switch(this.sqliteBackend){case "better-sqlite3":return new b(e,{readonly:t.readonly});case "node:sqlite":return new k(e);case "@tursodatabase/database":return new g(e);default:throw new o(`Unsupported SQLite backend: ${String(this.sqliteBackend)}`)}}requireBackend(){if(!this.backend)throw new o("SQLite database not initialized. Call initialize() first.");return this.backend}requireCache(){if(!this.stmtCache)throw new o("SQLite database not initialized. Call initialize() first.");return this.stmtCache}assertInitialized(){if(!this.initialized)throw new o("SyncSqliteConnection not initialized. Call initialize() first.")}walModeDefault(){return  true}foreignKeysDefault(){return  true}readonlyDefault(){return  false}busyTimeoutDefault(){return 5e3}walShmPathDefault(){}syncStmtCacheAccessor(){return this.requireCache()}},N=class{constructor(e){i(this,"backend",e);i(this,"cache",new Map);}get(e){let t=this.cache.get(e);if(t)return this.cache.delete(e),this.cache.set(e,t),t;let r=this.backend.prepare(e);if(this.cache.size>=he){let a=this.cache.keys().next().value;a!==void 0&&this.cache.delete(a);}return this.cache.set(e,r),r}clear(){this.cache.clear();}};function pe(n){let e=n.trimStart();if(e.length===0)return  false;let a=((e.split(`
+`,1)[0]??"").trimStart().split(/\s+/,1)[0]??"").toUpperCase();return a==="CREATE"||a==="DROP"||a==="ALTER"||a==="TRUNCATE"||a==="REPLACE"}function V(n){return n instanceof Error?n.message:String(n)}function me(n={}){let e=n.backend===void 0||n.backend==="auto"?w():n.backend,t=new D({...n,backend:e}),r=n.path??":memory:";if(r!==":memory:"){let a=p.dirname(r);try{y.mkdirSync(a,{recursive:!0});}catch(s){throw new o(`Failed to ensure directory for SQLite database at "${r}"`,s)}}return t}export{o as ConnectionError,x as DatabaseError,A as DatabaseFactory,T as PostgresDatabase,c as QueryError,v as SqliteDatabase,D as SyncSqliteConnection,l as TransactionError,me as createSyncSqliteConnection,A as default,q as isSafeIdent,w as resolveDefaultSqliteBackend,C as translatePlaceholders};

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@easbot/database",
+  "version": "0.3.3",
+  "description": "Unified database abstraction for EASBot — SQLite (better-sqlite3 / node:sqlite / @tursodatabase/database) with first-class transactions (begin/commit/rollback + nested SAVEPOINT) and PostgreSQL behind a single DatabaseInterface.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "easbot",
+    "database",
+    "sqlite",
+    "postgresql",
+    "turso",
+    "mcp",
+    "ai",
+    "agent",
+    "storage",
+    "transaction",
+    "savepoint"
+  ],
+  "author": "houjallen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/houjallen/easbot.git",
+    "directory": "packages/database"
+  },
+  "homepage": "https://github.com/houjallen/easbot/tree/main/packages/database",
+  "bugs": {
+    "url": "https://github.com/houjallen/easbot/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "pg": "^8.20.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "better-sqlite3": "^12.9.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@tursodatabase/database": "^0.5.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.6.2",
+    "@types/pg": "^8.20.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "better-sqlite3": "^12.9.0",
+    "dotenv": "^17.4.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsup --watch --env.NODE_ENV development",
+    "build": "tsup --env.NODE_ENV production",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "lint:report": "biome check --reporter=summary .",
+    "format": "biome format .",
+    "format:fix": "biome format --write .",
+    "clean": "npx rimraf dist node_modules",
+    "publish:npm": "bash scripts/publish.sh",
+    "publish:npm:win": "powershell -ExecutionPolicy Bypass -File scripts/publish.ps1"
+  }
+}