@airdraft/db-adapter 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @airdraft/db-adapter
+
+Base package for Airdraft database adapters. Provides the abstract `BaseDatabaseAdapter` class, shared TypeScript types, and a portable contract test suite that all driver packages run against.
+
+You never install this package directly in a user project. It is a peer dependency of each driver package (`@airdraft/db-adapter-sqlite`, `@airdraft/db-adapter-postgres`, `@airdraft/db-adapter-mongodb`).
+
+---
+
+## Architecture
+
+Airdraft stores content as typed documents (entries). Each entry lives at a path `<collection>/<slug>`, carries an opaque `sha` (SHA-256 of the serialized content), and is tied to a `projectId` for multi-tenancy.
+
+`BaseDatabaseAdapter` implements the full `StorageAdapter` interface expected by the CMS engine, so the engine, plugins, and client SDKs see no difference between a file adapter and a database adapter.
+
+The engine detects a database adapter via `instanceof BaseDatabaseAdapter` and routes bulk list operations through the single-query `queryEntries()` method rather than the N+1 `list()` + `read()` loop used for file adapters.
+
+---
+
+## Abstract methods (implement in your driver)
+
+| Method | Description |
+|---|---|
+| `migrate(): Promise<void>` | Creates `airdraft_entries` and (when `history: true`) `airdraft_entry_history`. Idempotent — safe to call on every deploy. |
+| `read(path): Promise<FileResult \| null>` | Reads a single entry by path. |
+| `write(path, content, options): Promise<void>` | Creates or updates an entry. Must enforce SHA-based optimistic concurrency and throw `ConflictError` on mismatch. |
+| `delete(path, options): Promise<void>` | Deletes an entry. |
+| `queryEntries(collection, options): Promise<QueryEntriesResult>` | Bulk query: filters, sorts, and paginates in a single DB call. Called by the engine fast-path. |
+| `atomicUpdate(path, ops, sha): Promise<void>` | Applies `AtomicOp` field operations (increment / set / push / pull) atomically. |
+| `rollback(path, sha): Promise<void>` | Restore a previous revision from the history table. Only when `history: true`. |
+| `close(): Promise<void>` | Release connection pool / file handles. |
+
+---
+
+## Constructor options (`DbAdapterOptions`)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `projectId` | `string` | `'default'` | Isolates all reads/writes within a shared DB instance. Set to the Airdraft project slug for multi-tenant deployments. |
+| `history` | `boolean` | `false` | When `true`, mirrors every write to `airdraft_entry_history`. Enables `rollback()`. |
+| `cacheTtlMs` | `number` | `0` | Per-entry read cache TTL in milliseconds. `0` disables the cache. |
+| `cacheMaxSize` | `number` | `500` | Maximum entries in the LRU read cache. |
+
+---
+
+## Shared types
+
+```ts
+import type { DbAdapterOptions, QueryEntriesResult, AtomicOp } from '@airdraft/db-adapter'
+```
+
+### `QueryEntriesResult`
+
+```ts
+interface QueryEntriesResult {
+  entries: Array<{ path: string; content: string; sha: string }>
+  total: number  // total matching rows before pagination — used for meta.total
+}
+```
+
+### `AtomicOp`
+
+```ts
+type AtomicOp =
+  | { op: 'increment'; path: string; by: number }
+  | { op: 'set';       path: string; value: unknown }
+  | { op: 'push';      path: string; value: unknown }
+  | { op: 'pull';      path: string; value: unknown }
+```
+
+`path` uses dot-notation — e.g. `'stats.viewCount'` for a nested field.
+
+---
+
+## Contract test suite
+
+The `@airdraft/db-adapter/testing` export provides a shared Vitest test suite that all driver packages run against to verify full contract compliance.
+
+```ts
+// src/__tests__/contract.test.ts (inside a driver package)
+import { describe } from 'vitest'
+import { runStorageAdapterContract } from '@airdraft/db-adapter/testing'
+import { SQLiteAdapter } from '../SQLiteAdapter.js'
+
+describe('SQLiteAdapter contract', () => {
+  runStorageAdapterContract(() => new SQLiteAdapter({ filename: ':memory:', history: true }))
+})
+```
+
+The suite covers: `migrate`, `write`/`read`, `ConflictError` on SHA mismatch, `delete`, `list`, `queryEntries` (with filters, sort, pagination), `atomicUpdate`, history writes, and `rollback`.
+
+---
+
+## Writing a custom adapter
+
+Extend `BaseDatabaseAdapter` and implement all abstract methods:
+
+```ts
+import { BaseDatabaseAdapter } from '@airdraft/db-adapter'
+import type { FileResult, WriteOptions, DeleteOptions, ListOptions } from '@airdraft/core'
+import type { QueryEntriesResult, AtomicOp } from '@airdraft/db-adapter'
+
+export class MyAdapter extends BaseDatabaseAdapter {
+  async migrate() { /* CREATE TABLE IF NOT EXISTS … */ }
+  async read(path: string): Promise<FileResult | null> { /* … */ }
+  async write(path: string, content: string, options: WriteOptions): Promise<void> { /* … */ }
+  async delete(path: string, options: DeleteOptions): Promise<void> { /* … */ }
+  async queryEntries(collection: string, options: ListOptions): Promise<QueryEntriesResult> { /* … */ }
+  async atomicUpdate(path: string, ops: AtomicOp[], sha: string): Promise<void> { /* … */ }
+  async rollback(path: string, sha: string): Promise<void> { /* … */ }
+  async close(): Promise<void> { /* … */ }
+}
+```
+
+Run the shared contract suite in your tests to confirm your implementation is spec-compliant.
+
+---
+
+## License
+
+MIT

package/dist/BaseDatabaseAdapter.d.ts

@@ -0,0 +1,73 @@
+import type { StorageAdapter, FileResult, WriteOptions, DeleteOptions, FileListItem, ListOptions } from '@airdraft/core';
+import { LruCache } from '@airdraft/core';
+import type { DbAdapterOptions, QueryEntriesResult, AtomicOp } from './types.js';
+/**
+ * Abstract base class for all Airdraft database adapters.
+ *
+ * Implements the full `StorageAdapter` interface so the engine, plugins,
+ * and client code see no difference between a file adapter and a DB adapter.
+ *
+ * Concrete driver classes (PostgresAdapter, SQLiteAdapter, MongooseAdapter)
+ * extend this class and implement the abstract methods.
+ */
+export declare abstract class BaseDatabaseAdapter implements StorageAdapter {
+    protected readonly projectId: string;
+    protected readonly history: boolean;
+    protected readonly cache: LruCache<FileResult | null> | null;
+    constructor(options?: DbAdapterOptions);
+    abstract read(path: string): Promise<FileResult | null>;
+    abstract write(path: string, content: string, options: WriteOptions): Promise<void>;
+    abstract delete(path: string, options: DeleteOptions): Promise<void>;
+    /**
+     * Returns all entries for the collection identified by the first path
+     * segment of `glob`. Slug-level glob patterns are ignored.
+     *
+     * This method is never on the hot path when a DB adapter is in use —
+     * the engine calls `queryEntries()` directly for `listEntries()`.
+     * `list()` is only called by plugin infrastructure (audit log, search).
+     */
+    list(glob: string): Promise<FileListItem[]>;
+    /**
+     * Execute a native DB query for a collection.
+     * Called by the engine instead of the list+read loop when a DB adapter
+     * is detected via `instanceof BaseDatabaseAdapter`.
+     */
+    abstract queryEntries(collection: string, options: ListOptions): Promise<QueryEntriesResult>;
+    /**
+     * Create the `airdraft_entries` table / collection (and indexes, and the
+     * `airdraft_entry_history` table when `history: true`).
+     *
+     * Idempotent — safe to call on every deploy (e.g. from `instrumentation.ts`).
+     */
+    abstract migrate(): Promise<void>;
+    /**
+     * Apply one or more field-level operations atomically in a single DB op.
+     * The `sha` parameter is the current sha of the entry — throws `ConflictError`
+     * if it no longer matches (optimistic concurrency).
+     *
+     * Designed for ecommerce workloads: inventory decrement, order status, etc.
+     */
+    atomicUpdate?(path: string, ops: AtomicOp[], sha: string): Promise<FileResult>;
+    /**
+     * Restore an entry to a previous version identified by `sha`.
+     * Only available when `history: true`. Throws `AirdraftError UNSUPPORTED_OPERATION`
+     * when called with `history: false`.
+     */
+    rollback?(path: string, sha: string): Promise<FileResult>;
+    /**
+     * Tear down internally-owned connections / pools.
+     * No-op when the adapter was constructed with a pre-created client.
+     */
+    abstract close(): Promise<void>;
+    protected computeSha(data: unknown): string;
+    /**
+     * Parse a content path into its collection and slug components.
+     * "products/iphone-16.json" → { collection: "products", slug: "iphone-16", ext: ".json" }
+     */
+    protected parsePath(path: string): {
+        collection: string;
+        slug: string;
+        ext: string;
+    };
+}
+//# sourceMappingURL=BaseDatabaseAdapter.d.ts.map

package/dist/BaseDatabaseAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseDatabaseAdapter.d.ts","sourceRoot":"","sources":["../src/BaseDatabaseAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEhF;;;;;;;;GAQG;AACH,8BAAsB,mBAAoB,YAAW,cAAc;IACjE,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IACpC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACnC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,IAAI,CAAA;gBAEhD,OAAO,GAAE,gBAAqB;IAa1C,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IACvD,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IACnF,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAQjD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,CAAC;IAI9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;;;;OAMG;IACH,YAAY,CAAC,CACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,QAAQ,EAAE,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,CAAC;IAItB;;;;OAIG;IACH,QAAQ,CAAC,CACP,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,CAAC;IAItB;;;OAGG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;IAM3C;;;OAGG;IACH,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;CASrF"}

package/dist/BaseDatabaseAdapter.js

@@ -0,0 +1,60 @@
+import { LruCache } from '@airdraft/core';
+import { createHash } from 'node:crypto';
+/**
+ * Abstract base class for all Airdraft database adapters.
+ *
+ * Implements the full `StorageAdapter` interface so the engine, plugins,
+ * and client code see no difference between a file adapter and a DB adapter.
+ *
+ * Concrete driver classes (PostgresAdapter, SQLiteAdapter, MongooseAdapter)
+ * extend this class and implement the abstract methods.
+ */
+export class BaseDatabaseAdapter {
+    projectId;
+    history;
+    cache;
+    constructor(options = {}) {
+        this.projectId = options.projectId ?? 'default';
+        this.history = options.history ?? false;
+        this.cache = options.cacheTtlMs && options.cacheTtlMs > 0
+            ? new LruCache({
+                maxSize: options.cacheMaxSize ?? 500,
+                ttlMs: options.cacheTtlMs,
+            })
+            : null;
+    }
+    // ─── Concrete: list() delegates to queryEntries ───────────────────────────
+    /**
+     * Returns all entries for the collection identified by the first path
+     * segment of `glob`. Slug-level glob patterns are ignored.
+     *
+     * This method is never on the hot path when a DB adapter is in use —
+     * the engine calls `queryEntries()` directly for `listEntries()`.
+     * `list()` is only called by plugin infrastructure (audit log, search).
+     */
+    async list(glob) {
+        const collection = glob.split('/')[0];
+        const { entries } = await this.queryEntries(collection, {});
+        return entries.map(e => ({ path: e.path, sha: e.sha }));
+    }
+    // ─── Shared utilities ─────────────────────────────────────────────────────
+    computeSha(data) {
+        return createHash('sha256')
+            .update(JSON.stringify(data))
+            .digest('hex');
+    }
+    /**
+     * Parse a content path into its collection and slug components.
+     * "products/iphone-16.json" → { collection: "products", slug: "iphone-16", ext: ".json" }
+     */
+    parsePath(path) {
+        const parts = path.split('/');
+        const collection = parts[0];
+        const filename = parts.slice(1).join('/');
+        const dotIdx = filename.lastIndexOf('.');
+        const slug = dotIdx === -1 ? filename : filename.slice(0, dotIdx);
+        const ext = dotIdx === -1 ? '' : filename.slice(dotIdx);
+        return { collection, slug, ext };
+    }
+}
+//# sourceMappingURL=BaseDatabaseAdapter.js.map

package/dist/BaseDatabaseAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseDatabaseAdapter.js","sourceRoot":"","sources":["../src/BaseDatabaseAdapter.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC;;;;;;;;GAQG;AACH,MAAM,OAAgB,mBAAmB;IACpB,SAAS,CAAQ;IACjB,OAAO,CAAS;IAChB,KAAK,CAAoC;IAE5D,YAAY,UAA4B,EAAE;QACxC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,SAAS,CAAA;QAC/C,IAAI,CAAC,OAAO,GAAK,OAAO,CAAC,OAAO,IAAM,KAAK,CAAA;QAC3C,IAAI,CAAC,KAAK,GAAO,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC;YAC3D,CAAC,CAAC,IAAI,QAAQ,CAAoB;gBAC9B,OAAO,EAAE,OAAO,CAAC,YAAY,IAAI,GAAG;gBACpC,KAAK,EAAI,OAAO,CAAC,UAAU;aAC5B,CAAC;YACJ,CAAC,CAAC,IAAI,CAAA;IACV,CAAC;IAQD,6EAA6E;IAE7E;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACrC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;QAC3D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IACzD,CAAC;IA2DD,6EAA6E;IAEnE,UAAU,CAAC,IAAa;QAChC,OAAO,UAAU,CAAC,QAAQ,CAAC;aACxB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;aAC5B,MAAM,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;IAED;;;OAGG;IACO,SAAS,CAAC,IAAY;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC7B,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QACxC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;QACjE,MAAM,GAAG,GAAI,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QACxD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;IAClC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseDatabaseAdapter } from './BaseDatabaseAdapter.js';
+export type { DbAdapterOptions, AtomicOp, QueryEntriesResult, ListOptions } from './types.js';
+export { ConflictError, StorageUnavailableError, MigrationError, AirdraftError, } from '@airdraft/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7F,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,cAAc,EACd,aAAa,GACd,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { BaseDatabaseAdapter } from './BaseDatabaseAdapter.js';
+export { ConflictError, StorageUnavailableError, MigrationError, AirdraftError, } from '@airdraft/core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,cAAc,EACd,aAAa,GACd,MAAM,gBAAgB,CAAA"}

package/dist/testing/contract.d.ts

@@ -0,0 +1,11 @@
+import type { BaseDatabaseAdapter } from '../BaseDatabaseAdapter.js';
+export interface ContractTestOptions {
+    /** Called after each test to reset DB state. */
+    afterEach?: () => Promise<void>;
+    /** Skip tests that require history: true (optional). */
+    skipHistory?: boolean;
+    /** Skip tests that require atomicUpdate support (optional). */
+    skipAtomicUpdate?: boolean;
+}
+export declare function runStorageAdapterContract(adapter: BaseDatabaseAdapter, options?: ContractTestOptions): void;
+//# sourceMappingURL=contract.d.ts.map

package/dist/testing/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/testing/contract.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAGpE,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA8KN"}

package/dist/testing/contract.js

@@ -0,0 +1,163 @@
+/**
+ * Shared contract test suite for all Airdraft database adapters.
+ *
+ * Usage in each driver package:
+ * ```ts
+ * import { runStorageAdapterContract } from '@airdraft/db-adapter/testing'
+ * import { MySQLAdapter } from '../MySQLAdapter.js'
+ *
+ * const adapter = new MySQLAdapter({ ... })
+ * runStorageAdapterContract(adapter, {
+ *   afterEach: async () => { // truncate tables },
+ * })
+ * ```
+ */
+import { describe, it, expect, beforeAll, afterEach as vitestAfterEach } from 'vitest';
+import { ConflictError } from '@airdraft/core';
+export function runStorageAdapterContract(adapter, options = {}) {
+    const COLLECTION = 'test-posts';
+    const SLUG = 'hello-world';
+    const PATH = `${COLLECTION}/${SLUG}.json`;
+    const CONTENT = JSON.stringify({ title: 'Hello World', published: false, stock: 10 }, null, 2);
+    beforeAll(async () => {
+        await adapter.migrate();
+    });
+    if (options.afterEach) {
+        vitestAfterEach(options.afterEach);
+    }
+    // ─── migrate() ─────────────────────────────────────────────────────────────
+    describe('migrate()', () => {
+        it('is idempotent — calling twice does not throw', async () => {
+            await expect(adapter.migrate()).resolves.not.toThrow();
+        });
+    });
+    // ─── write() + read() ───────────────────────────────────────────────────────
+    describe('write() + read()', () => {
+        it('creates an entry and reads it back', async () => {
+            await adapter.write(PATH, CONTENT, { message: 'create test' });
+            const result = await adapter.read(PATH);
+            expect(result).not.toBeNull();
+            expect(result.path).toBe(PATH);
+            expect(result.sha).toBeTruthy();
+            // Content round-trip: re-parsed then re-serialized — may differ in whitespace
+            const parsed = JSON.parse(result.content);
+            expect(parsed.title).toBe('Hello World');
+        });
+        it('read() returns null for a missing path', async () => {
+            const result = await adapter.read('nonexistent/missing.json');
+            expect(result).toBeNull();
+        });
+        it('write() updates sha on overwrite', async () => {
+            await adapter.write(PATH, CONTENT, { message: 'create' });
+            const first = await adapter.read(PATH);
+            const updated = JSON.stringify({ title: 'Updated', published: true }, null, 2);
+            await adapter.write(PATH, updated, { message: 'update', sha: first.sha });
+            const second = await adapter.read(PATH);
+            expect(second.sha).not.toBe(first.sha);
+            expect(JSON.parse(second.content).title).toBe('Updated');
+        });
+        it('write() throws ConflictError on stale sha', async () => {
+            await adapter.write(PATH, CONTENT, { message: 'create' });
+            const stale = 'deadbeef'.repeat(8);
+            const updated = JSON.stringify({ title: 'Conflict' }, null, 2);
+            await expect(adapter.write(PATH, updated, { message: 'conflict', sha: stale })).rejects.toBeInstanceOf(ConflictError);
+        });
+    });
+    // ─── delete() ──────────────────────────────────────────────────────────────
+    describe('delete()', () => {
+        it('removes the entry — read() returns null afterwards', async () => {
+            await adapter.write(PATH, CONTENT, { message: 'create' });
+            const { sha } = (await adapter.read(PATH));
+            await adapter.delete(PATH, { message: 'delete', sha });
+            expect(await adapter.read(PATH)).toBeNull();
+        });
+    });
+    // ─── list() ────────────────────────────────────────────────────────────────
+    describe('list()', () => {
+        it('returns all entries for a collection', async () => {
+            await adapter.write(`${COLLECTION}/a.json`, JSON.stringify({ title: 'A' }), { message: 'a' });
+            await adapter.write(`${COLLECTION}/b.json`, JSON.stringify({ title: 'B' }), { message: 'b' });
+            const items = await adapter.list(`${COLLECTION}/*`);
+            expect(items.length).toBeGreaterThanOrEqual(2);
+            const paths = items.map(i => i.path);
+            expect(paths).toContain(`${COLLECTION}/a.json`);
+            expect(paths).toContain(`${COLLECTION}/b.json`);
+        });
+    });
+    // ─── queryEntries() ────────────────────────────────────────────────────────
+    describe('queryEntries()', () => {
+        it('returns entries with correct total', async () => {
+            await adapter.write(`${COLLECTION}/p1.json`, JSON.stringify({ title: 'P1', published: true }), { message: 'p1' });
+            await adapter.write(`${COLLECTION}/p2.json`, JSON.stringify({ title: 'P2', published: false }), { message: 'p2' });
+            const result = await adapter.queryEntries(COLLECTION, {});
+            expect(result.total).toBeGreaterThanOrEqual(2);
+            expect(result.entries.length).toBeGreaterThanOrEqual(2);
+            expect(result.entries[0]).toHaveProperty('path');
+            expect(result.entries[0]).toHaveProperty('content');
+            expect(result.entries[0]).toHaveProperty('sha');
+        });
+        it('respects limit and offset', async () => {
+            for (let i = 0; i < 5; i++) {
+                await adapter.write(`${COLLECTION}/item-${i}.json`, JSON.stringify({ title: `Item ${i}` }), { message: `item ${i}` });
+            }
+            const page1 = await adapter.queryEntries(COLLECTION, { limit: 2, offset: 0 });
+            const page2 = await adapter.queryEntries(COLLECTION, { limit: 2, offset: 2 });
+            expect(page1.entries.length).toBe(2);
+            expect(page2.entries.length).toBe(2);
+            expect(page1.entries[0].path).not.toBe(page2.entries[0].path);
+        });
+        it('total reflects all matching rows regardless of pagination', async () => {
+            for (let i = 0; i < 3; i++) {
+                await adapter.write(`${COLLECTION}/tot-${i}.json`, JSON.stringify({ title: `T${i}` }), { message: `t${i}` });
+            }
+            const result = await adapter.queryEntries(COLLECTION, { limit: 1, offset: 0 });
+            expect(result.total).toBeGreaterThan(1);
+            expect(result.entries.length).toBe(1);
+        });
+    });
+    // ─── Serialization round-trips ─────────────────────────────────────────────
+    describe('serialization round-trips', () => {
+        it('JSON: round-trips correctly', async () => {
+            const data = { title: 'JSON test', count: 42, tags: ['a', 'b'], active: true };
+            await adapter.write('rt/json.json', JSON.stringify(data, null, 2), { message: 'rt-json' });
+            const result = await adapter.read('rt/json.json');
+            const parsed = JSON.parse(result.content);
+            expect(parsed).toMatchObject(data);
+        });
+        it('YAML: round-trips correctly', async () => {
+            const yamlContent = 'title: YAML test\ncount: 7\npublished: true';
+            await adapter.write('rt/yaml.yaml', yamlContent, { message: 'rt-yaml' });
+            const result = await adapter.read('rt/yaml.yaml');
+            expect(result.content).toBeTruthy();
+        });
+        it('MDX: round-trips body correctly', async () => {
+            const mdxContent = '---\ntitle: MDX test\n---\n\nHello **world**.';
+            await adapter.write('rt/post.mdx', mdxContent, { message: 'rt-mdx' });
+            const result = await adapter.read('rt/post.mdx');
+            expect(result.content).toContain('Hello **world**.');
+        });
+    });
+    // ─── atomicUpdate() ────────────────────────────────────────────────────────
+    if (!options.skipAtomicUpdate && typeof adapter.atomicUpdate === 'function') {
+        describe('atomicUpdate()', () => {
+            it('increments a numeric field atomically', async () => {
+                await adapter.write(PATH, JSON.stringify({ stock: 10 }, null, 2), { message: 'create' });
+                const { sha } = (await adapter.read(PATH));
+                const updated = await adapter.atomicUpdate(PATH, [{ op: 'increment', path: 'stock', by: -3 }], sha);
+                const parsed = JSON.parse(updated.content);
+                expect(parsed.stock).toBe(7);
+            });
+            it('set changes a field value', async () => {
+                await adapter.write(PATH, JSON.stringify({ status: 'pending' }, null, 2), { message: 'create' });
+                const { sha } = (await adapter.read(PATH));
+                const updated = await adapter.atomicUpdate(PATH, [{ op: 'set', path: 'status', value: 'shipped' }], sha);
+                expect(JSON.parse(updated.content).status).toBe('shipped');
+            });
+            it('throws ConflictError on stale sha', async () => {
+                await adapter.write(PATH, JSON.stringify({ stock: 5 }, null, 2), { message: 'create' });
+                await expect(adapter.atomicUpdate(PATH, [{ op: 'increment', path: 'stock', by: 1 }], 'stale'.repeat(12))).rejects.toBeInstanceOf(ConflictError);
+            });
+        });
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/testing/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/testing/contract.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+import type { ListOptions } from '@airdraft/core';
+export interface DbAdapterOptions {
+    /**
+     * Isolates all reads/writes to this project within a shared DB instance.
+     * Defaults to `'default'` for single-project self-hosted deployments.
+     */
+    projectId?: string;
+    /**
+     * When true, every write is mirrored to `airdraft_entry_history`.
+     * Requires a migration that creates the history table.
+     * MongoDB: also requires a replica set.
+     * @default false
+     */
+    history?: boolean;
+    /**
+     * Read cache TTL in milliseconds. Set to 0 to disable.
+     * @default 0
+     */
+    cacheTtlMs?: number;
+    /**
+     * Maximum number of entries in the read cache.
+     * @default 500
+     */
+    cacheMaxSize?: number;
+}
+export interface QueryEntriesResult {
+    entries: Array<{
+        path: string;
+        content: string;
+        sha: string;
+    }>;
+    /** Total matching rows before pagination — used for meta.total */
+    total: number;
+}
+export type AtomicOp = {
+    op: 'increment';
+    path: string;
+    by: number;
+} | {
+    op: 'set';
+    path: string;
+    value: unknown;
+} | {
+    op: 'push';
+    path: string;
+    value: unknown;
+} | {
+    op: 'pull';
+    path: string;
+    value: unknown;
+};
+export type { ListOptions };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAMjD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,GAAG,EAAE,MAAM,CAAA;KACZ,CAAC,CAAA;IACF,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;CACd;AAMD,MAAM,MAAM,QAAQ,GAChB;IAAE,EAAE,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAO,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAM,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAM,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAGrD,YAAY,EAAE,WAAW,EAAE,CAAA"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// @airdraft/db-adapter — shared types
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@airdraft/db-adapter",
+  "version": "0.1.0",
+  "description": "Airdraft base database adapter — abstract class, shared types, and contract test suite",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing/contract.js",
+      "types": "./dist/testing/contract.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@airdraft/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependenciesMeta": {}
+}