lex-gql-sqlite 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- `createWriter(db)` helper with prepared statements for efficient writes
+  - `insertRecord({ uri, did, collection, rkey, cid?, record, indexedAt? })`
+  - `deleteRecord(uri)`
+  - `upsertActor(did, handle)`
+- `totalCount` field in findMany query results
+
+### Changed
+
+- AND/OR conditions format: `{ op: 'and', conditions: [...] }` instead of `{ field: 'AND', op: 'and', value: [...] }`
+
+## [0.1.0] - 2026-01-15
+
+### Added
+
+- Initial release
+- `createSqliteAdapter(db)` - create query function from better-sqlite3 database
+- `setupSchema(db)` - create required tables and indexes
+- Full WHERE support with AND/OR nesting
+- All filter operators: eq, in, contains, gt, gte, lt, lte
+- Multi-field sorting
+- Bidirectional cursor pagination (first/after, last/before)
+- Aggregate queries with groupBy
+- Actor handle joins

package/README.md

@@ -0,0 +1,104 @@
+# lex-gql-sqlite
+
+SQLite adapter for [lex-gql](https://github.com/your-repo/lex-gql).
+
+## Installation
+
+```bash
+npm install lex-gql-sqlite lex-gql better-sqlite3
+```
+
+## Usage
+
+```javascript
+import Database from 'better-sqlite3';
+import { createAdapter, parseLexicon } from 'lex-gql';
+import { createSqliteAdapter, createWriter, setupSchema } from 'lex-gql-sqlite';
+
+const db = new Database('./data.db');
+setupSchema(db);
+
+const query = createSqliteAdapter(db);
+const adapter = createAdapter(lexicons, { query });
+
+const result = await adapter.execute(`
+  query {
+    appBskyFeedPost(first: 10) {
+      edges { node { text } }
+    }
+  }
+`);
+```
+
+## API
+
+### `setupSchema(db)`
+
+Creates the required database tables and indexes.
+
+### `createSqliteAdapter(db)`
+
+Returns a query function compatible with lex-gql's adapter interface.
+
+### `buildWhere(where)`
+
+Builds SQL WHERE clause from lex-gql where conditions. Supports:
+- All comparison operators: `eq`, `gt`, `gte`, `lt`, `lte`
+- Array operators: `in`
+- Text operators: `contains`
+- Logical operators: nested `AND`/`OR`
+
+### `buildOrderBy(sort)`
+
+Builds SQL ORDER BY clause from lex-gql sort conditions.
+
+### `createWriter(db)`
+
+Creates a writer with prepared statements for efficient writes.
+
+```javascript
+const writer = createWriter(db);
+
+// Insert or replace a record
+writer.insertRecord({
+  uri: 'at://did:plc:alice/app.bsky.feed.post/1',
+  did: 'did:plc:alice',
+  collection: 'app.bsky.feed.post',
+  rkey: '1',
+  cid: 'bafycid123',          // optional
+  record: { text: 'Hello!' }, // object or JSON string
+  indexedAt: '2024-01-15T12:00:00Z', // optional, defaults to now
+});
+
+// Delete a record
+writer.deleteRecord('at://did:plc:alice/app.bsky.feed.post/1');
+
+// Insert or update an actor
+writer.upsertActor('did:plc:alice', 'alice.bsky.social');
+```
+
+## Schema
+
+The adapter expects this schema (created by `setupSchema`):
+
+```sql
+CREATE TABLE records (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  uri TEXT UNIQUE NOT NULL,
+  did TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  rkey TEXT NOT NULL,
+  cid TEXT,
+  record TEXT NOT NULL,
+  indexed_at TEXT NOT NULL
+);
+
+CREATE TABLE actors (
+  did TEXT PRIMARY KEY,
+  handle TEXT NOT NULL
+);
+```
+
+## License
+
+MIT

package/lex-gql-sqlite.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Set up the required database schema for lex-gql-sqlite
+ * @param {import('better-sqlite3').Database} db
+ */
+export function setupSchema(db: import("better-sqlite3").Database): void;
+/**
+ * @typedef {Object} RecordInput
+ * @property {string} uri - Record URI (at://did/collection/rkey)
+ * @property {string} did - DID of record author
+ * @property {string} collection - Collection NSID
+ * @property {string} rkey - Record key
+ * @property {string} [cid] - Record CID
+ * @property {object} record - Record data (will be JSON stringified)
+ * @property {string} [indexedAt] - Timestamp (defaults to now)
+ */
+/**
+ * @typedef {Object} Writer
+ * @property {(record: RecordInput) => void} insertRecord - Insert or replace a record
+ * @property {(uri: string) => void} deleteRecord - Delete a record by URI
+ * @property {(did: string, handle: string) => void} upsertActor - Insert or replace an actor
+ */
+/**
+ * Create a writer with prepared statements for efficient writes
+ * @param {import('better-sqlite3').Database} db
+ * @returns {Writer}
+ */
+export function createWriter(db: import("better-sqlite3").Database): Writer;
+/**
+ * Build SQL WHERE clause from lex-gql where conditions
+ * @param {import('lex-gql').WhereClause[]} where
+ * @returns {{ sql: string, params: any[] }}
+ */
+export function buildWhere(where: import("lex-gql").WhereClause[]): {
+    sql: string;
+    params: any[];
+};
+/**
+ * Build SQL ORDER BY clause from lex-gql sort conditions
+ * @param {Array<{field: string, dir?: string}>} sort
+ * @returns {string}
+ */
+export function buildOrderBy(sort: Array<{
+    field: string;
+    dir?: string;
+}>): string;
+/**
+ * Create a SQLite query adapter for lex-gql
+ * @param {import('better-sqlite3').Database} db - better-sqlite3 database instance
+ * @returns {(op: import('lex-gql').Operation) => Promise<any>}
+ */
+export function createSqliteAdapter(db: import("better-sqlite3").Database): (op: import("lex-gql").Operation) => Promise<any>;
+/**
+ * SQL schema for lex-gql records
+ */
+export const SCHEMA_SQL: "\n  CREATE TABLE IF NOT EXISTS records (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    uri TEXT UNIQUE NOT NULL,\n    did TEXT NOT NULL,\n    collection TEXT NOT NULL,\n    rkey TEXT NOT NULL,\n    cid TEXT,\n    record TEXT NOT NULL,\n    indexed_at TEXT NOT NULL\n  );\n\n  CREATE INDEX IF NOT EXISTS idx_records_collection ON records(collection);\n  CREATE INDEX IF NOT EXISTS idx_records_did ON records(did);\n  CREATE INDEX IF NOT EXISTS idx_records_uri ON records(uri);\n\n  CREATE TABLE IF NOT EXISTS actors (\n    did TEXT PRIMARY KEY,\n    handle TEXT NOT NULL\n  );\n";
+export type RecordInput = {
+    /**
+     * - Record URI (at://did/collection/rkey)
+     */
+    uri: string;
+    /**
+     * - DID of record author
+     */
+    did: string;
+    /**
+     * - Collection NSID
+     */
+    collection: string;
+    /**
+     * - Record key
+     */
+    rkey: string;
+    /**
+     * - Record CID
+     */
+    cid?: string | undefined;
+    /**
+     * - Record data (will be JSON stringified)
+     */
+    record: object;
+    /**
+     * - Timestamp (defaults to now)
+     */
+    indexedAt?: string | undefined;
+};
+export type Writer = {
+    /**
+     * - Insert or replace a record
+     */
+    insertRecord: (record: RecordInput) => void;
+    /**
+     * - Delete a record by URI
+     */
+    deleteRecord: (uri: string) => void;
+    /**
+     * - Insert or replace an actor
+     */
+    upsertActor: (did: string, handle: string) => void;
+};

package/lex-gql-sqlite.js

@@ -0,0 +1,356 @@
+/**
+ * SQLite adapter for lex-gql
+ */
+
+import { hydrateRecord } from 'lex-gql';
+
+/**
+ * SQL schema for lex-gql records
+ */
+export const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS records (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    uri TEXT UNIQUE NOT NULL,
+    did TEXT NOT NULL,
+    collection TEXT NOT NULL,
+    rkey TEXT NOT NULL,
+    cid TEXT,
+    record TEXT NOT NULL,
+    indexed_at TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_records_collection ON records(collection);
+  CREATE INDEX IF NOT EXISTS idx_records_did ON records(did);
+  CREATE INDEX IF NOT EXISTS idx_records_uri ON records(uri);
+
+  CREATE TABLE IF NOT EXISTS actors (
+    did TEXT PRIMARY KEY,
+    handle TEXT NOT NULL
+  );
+`;
+
+/**
+ * Set up the required database schema for lex-gql-sqlite
+ * @param {import('better-sqlite3').Database} db
+ */
+export function setupSchema(db) {
+  db.exec(SCHEMA_SQL);
+}
+
+/**
+ * @typedef {Object} RecordInput
+ * @property {string} uri - Record URI (at://did/collection/rkey)
+ * @property {string} did - DID of record author
+ * @property {string} collection - Collection NSID
+ * @property {string} rkey - Record key
+ * @property {string} [cid] - Record CID
+ * @property {object} record - Record data (will be JSON stringified)
+ * @property {string} [indexedAt] - Timestamp (defaults to now)
+ */
+
+/**
+ * @typedef {Object} Writer
+ * @property {(record: RecordInput) => void} insertRecord - Insert or replace a record
+ * @property {(uri: string) => void} deleteRecord - Delete a record by URI
+ * @property {(did: string, handle: string) => void} upsertActor - Insert or replace an actor
+ */
+
+/**
+ * Create a writer with prepared statements for efficient writes
+ * @param {import('better-sqlite3').Database} db
+ * @returns {Writer}
+ */
+export function createWriter(db) {
+  const insertRecordStmt = db.prepare(`
+    INSERT OR REPLACE INTO records (uri, did, collection, rkey, cid, record, indexed_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const deleteRecordStmt = db.prepare(`
+    DELETE FROM records WHERE uri = ?
+  `);
+
+  const upsertActorStmt = db.prepare(`
+    INSERT OR REPLACE INTO actors (did, handle) VALUES (?, ?)
+  `);
+
+  return {
+    insertRecord: ({ uri, did, collection, rkey, cid, record, indexedAt }) => {
+      const recordJson = typeof record === 'string' ? record : JSON.stringify(record);
+      const timestamp = indexedAt || new Date().toISOString();
+      insertRecordStmt.run(uri, did, collection, rkey, cid || null, recordJson, timestamp);
+    },
+    deleteRecord: (uri) => {
+      deleteRecordStmt.run(uri);
+    },
+    upsertActor: (did, handle) => {
+      upsertActorStmt.run(did, handle);
+    },
+  };
+}
+
+/** @type {Record<string, string>} */
+const SYSTEM_FIELDS = {
+  did: 'r.did',
+  uri: 'r.uri',
+  collection: 'r.collection',
+  cid: 'r.cid',
+  indexedAt: 'r.indexed_at',
+};
+
+/**
+ * Build SQL WHERE clause from lex-gql where conditions
+ * @param {import('lex-gql').WhereClause[]} where
+ * @returns {{ sql: string, params: any[] }}
+ */
+export function buildWhere(where) {
+  if (!where || where.length === 0) {
+    return { sql: '1=1', params: [] };
+  }
+
+  const parts = [];
+  const params = [];
+
+  for (const clause of where) {
+    const { field, op, value, conditions } = clause;
+
+    // Handle AND/OR logical operators
+    if (op === 'and' && conditions) {
+      /** @type {Array<{sql: string, params: any[]}>} */
+      const subClauses = conditions.map((/** @type {any} */ sub) => buildWhere(sub));
+      const subSql = subClauses.map((s) => s.sql).join(' AND ');
+      parts.push(`(${subSql})`);
+      for (const s of subClauses) {
+        params.push(...s.params);
+      }
+      continue;
+    }
+
+    if (op === 'or' && conditions) {
+      /** @type {Array<{sql: string, params: any[]}>} */
+      const subClauses = conditions.map((/** @type {any} */ sub) => buildWhere(sub));
+      const subSql = subClauses.map((s) => s.sql).join(' OR ');
+      parts.push(`(${subSql})`);
+      for (const s of subClauses) {
+        params.push(...s.params);
+      }
+      continue;
+    }
+
+    // Field conditions require a field name
+    if (!field) continue;
+
+    const fieldPath = SYSTEM_FIELDS[field] || `json_extract(r.record, '$.${field}')`;
+
+    switch (op) {
+      case 'eq':
+        parts.push(`${fieldPath} = ?`);
+        params.push(value);
+        break;
+      case 'in':
+        if (Array.isArray(value) && value.length > 0) {
+          const placeholders = value.map(() => '?').join(', ');
+          parts.push(`${fieldPath} IN (${placeholders})`);
+          params.push(...value);
+        }
+        break;
+      case 'contains':
+        parts.push(`${fieldPath} LIKE ?`);
+        params.push(`%${value}%`);
+        break;
+      case 'gt':
+        parts.push(`${fieldPath} > ?`);
+        params.push(value);
+        break;
+      case 'gte':
+        parts.push(`${fieldPath} >= ?`);
+        params.push(value);
+        break;
+      case 'lt':
+        parts.push(`${fieldPath} < ?`);
+        params.push(value);
+        break;
+      case 'lte':
+        parts.push(`${fieldPath} <= ?`);
+        params.push(value);
+        break;
+    }
+  }
+
+  return {
+    sql: parts.length > 0 ? parts.join(' AND ') : '1=1',
+    params,
+  };
+}
+
+/**
+ * Build SQL ORDER BY clause from lex-gql sort conditions
+ * @param {Array<{field: string, dir?: string}>} sort
+ * @returns {string}
+ */
+export function buildOrderBy(sort) {
+  if (!sort || sort.length === 0) {
+    return 'r.id DESC';
+  }
+
+  return sort
+    .map(({ field, dir = 'asc' }) => {
+      const fieldPath = SYSTEM_FIELDS[field] || `json_extract(r.record, '$.${field}')`;
+      return `${fieldPath} ${dir.toUpperCase()}`;
+    })
+    .join(', ');
+}
+
+/**
+ * Create a SQLite query adapter for lex-gql
+ * @param {import('better-sqlite3').Database} db - better-sqlite3 database instance
+ * @returns {(op: import('lex-gql').Operation) => Promise<any>}
+ */
+export function createSqliteAdapter(db) {
+  return async function query(op) {
+    if (op.type === 'findMany') {
+      return findMany(db, op);
+    }
+    if (op.type === 'aggregate') {
+      return aggregate(db, op);
+    }
+    throw new Error(`Not implemented: ${op.type}`);
+  };
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {any} op
+ */
+function findMany(db, op) {
+  const { collection, where = [], sort = [], pagination = {} } = op;
+  const { first = 20, after, last, before } = pagination;
+
+  // Build WHERE clause
+  const { sql: whereSql, params: whereParams } = buildWhere([
+    { field: 'collection', op: 'eq', value: collection },
+    ...where,
+  ]);
+
+  // Handle cursor pagination
+  const cursorConditions = [];
+  const cursorParams = [];
+
+  if (after) {
+    try {
+      const cursor = JSON.parse(Buffer.from(after, 'base64').toString());
+      if (cursor.id) {
+        cursorConditions.push('r.id < ?');
+        cursorParams.push(cursor.id);
+      }
+    } catch {}
+  }
+
+  if (before) {
+    try {
+      const cursor = JSON.parse(Buffer.from(before, 'base64').toString());
+      if (cursor.id) {
+        cursorConditions.push('r.id > ?');
+        cursorParams.push(cursor.id);
+      }
+    } catch {}
+  }
+
+  const fullWhere =
+    cursorConditions.length > 0 ? `${whereSql} AND ${cursorConditions.join(' AND ')}` : whereSql;
+
+  const allParams = [...whereParams, ...cursorParams];
+
+  // Build ORDER BY
+  const orderBy = buildOrderBy(sort);
+
+  // Build query
+  const limit = (first || last || 20) + 1;
+  const sql = `
+    SELECT r.id, r.uri, r.did, r.collection, r.rkey, r.cid, r.record, r.indexed_at, a.handle
+    FROM records r
+    LEFT JOIN actors a ON r.did = a.did
+    WHERE ${fullWhere}
+    ORDER BY ${orderBy}
+    LIMIT ?
+  `;
+  allParams.push(limit);
+
+  const rawRows = db.prepare(sql).all(...allParams);
+  const hasMore = rawRows.length > (first || last || 20);
+  const rows = hasMore ? rawRows.slice(0, -1) : rawRows;
+
+  // Transform rows
+  const transformed = rows.map((/** @type {any} */ row) => ({
+    ...hydrateRecord({
+      uri: row.uri,
+      did: row.did,
+      collection: row.collection,
+      cid: row.cid,
+      record: row.record,
+      indexed_at: row.indexed_at,
+      handle: row.handle,
+    }),
+    _id: row.id,
+  }));
+
+  // Get total count (without pagination)
+  const countSql = `SELECT COUNT(*) as count FROM records r WHERE ${whereSql}`;
+  /** @type {{count: number}} */
+  const countResult = /** @type {any} */ (db.prepare(countSql).get(...whereParams));
+
+  return {
+    rows: transformed,
+    hasNext: first ? hasMore : !!before,
+    hasPrev: !!after || (last ? hasMore : false),
+    totalCount: countResult.count,
+  };
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {any} op
+ */
+function aggregate(db, op) {
+  const { collection, where = [], groupBy = [] } = op;
+
+  const { sql: whereSql, params } = buildWhere([
+    { field: 'collection', op: 'eq', value: collection },
+    ...where,
+  ]);
+
+  if (groupBy.length === 0) {
+    const sql = `SELECT COUNT(*) as count FROM records r WHERE ${whereSql}`;
+    /** @type {{count: number}} */
+    const result = /** @type {any} */ (db.prepare(sql).get(...params));
+    return { count: result.count, groups: [] };
+  }
+
+  const groupFields = groupBy
+    .map((/** @type {string} */ f) => {
+      const fieldPath = SYSTEM_FIELDS[f] || `json_extract(r.record, '$.${f}')`;
+      return `${fieldPath} as ${f}`;
+    })
+    .join(', ');
+
+  const groupByClause = groupBy
+    .map((/** @type {string} */ f) => {
+      return SYSTEM_FIELDS[f] || `json_extract(r.record, '$.${f}')`;
+    })
+    .join(', ');
+
+  const sql = `
+    SELECT ${groupFields}, COUNT(*) as count
+    FROM records r
+    WHERE ${whereSql}
+    GROUP BY ${groupByClause}
+    ORDER BY count DESC
+    LIMIT 100
+  `;
+
+  /** @type {Array<{count: number, [key: string]: any}>} */
+  const groups = /** @type {any} */ (db.prepare(sql).all(...params));
+  const count = groups.reduce((sum, g) => sum + g.count, 0);
+
+  return { count, groups };
+}

package/lex-gql-sqlite.test.js

@@ -0,0 +1,575 @@
+import Database from 'better-sqlite3';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  buildOrderBy,
+  buildWhere,
+  createSqliteAdapter,
+  createWriter,
+  setupSchema,
+} from './lex-gql-sqlite.js';
+
+describe('setupSchema', () => {
+  let db;
+
+  beforeEach(() => {
+    db = new Database(':memory:');
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it('creates records table', () => {
+    setupSchema(db);
+    const tables = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='records'")
+      .all();
+    expect(tables).toHaveLength(1);
+  });
+
+  it('creates actors table', () => {
+    setupSchema(db);
+    const tables = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='actors'")
+      .all();
+    expect(tables).toHaveLength(1);
+  });
+
+  it('creates indexes', () => {
+    setupSchema(db);
+    const indexes = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'idx_%'")
+      .all();
+    expect(indexes.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('is idempotent (can run multiple times)', () => {
+    setupSchema(db);
+    setupSchema(db);
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all();
+    expect(tables.filter((t) => t.name === 'records')).toHaveLength(1);
+  });
+});
+
+describe('createWriter', () => {
+  let db;
+  let writer;
+
+  beforeEach(() => {
+    db = new Database(':memory:');
+    setupSchema(db);
+    writer = createWriter(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it('inserts a record', () => {
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/app.bsky.feed.post/1',
+      did: 'did:plc:alice',
+      collection: 'app.bsky.feed.post',
+      rkey: '1',
+      cid: 'bafycid123',
+      record: { text: 'Hello world' },
+    });
+
+    const row = db
+      .prepare('SELECT * FROM records WHERE uri = ?')
+      .get('at://did:plc:alice/app.bsky.feed.post/1');
+    expect(row.did).toBe('did:plc:alice');
+    expect(row.collection).toBe('app.bsky.feed.post');
+    expect(JSON.parse(row.record)).toEqual({ text: 'Hello world' });
+  });
+
+  it('replaces existing record on conflict', () => {
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/app.bsky.feed.post/1',
+      did: 'did:plc:alice',
+      collection: 'app.bsky.feed.post',
+      rkey: '1',
+      record: { text: 'First version' },
+    });
+
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/app.bsky.feed.post/1',
+      did: 'did:plc:alice',
+      collection: 'app.bsky.feed.post',
+      rkey: '1',
+      record: { text: 'Updated version' },
+    });
+
+    const rows = db.prepare('SELECT * FROM records').all();
+    expect(rows).toHaveLength(1);
+    expect(JSON.parse(rows[0].record)).toEqual({ text: 'Updated version' });
+  });
+
+  it('deletes a record', () => {
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/app.bsky.feed.post/1',
+      did: 'did:plc:alice',
+      collection: 'app.bsky.feed.post',
+      rkey: '1',
+      record: { text: 'Hello' },
+    });
+
+    writer.deleteRecord('at://did:plc:alice/app.bsky.feed.post/1');
+
+    const rows = db.prepare('SELECT * FROM records').all();
+    expect(rows).toHaveLength(0);
+  });
+
+  it('upserts an actor', () => {
+    writer.upsertActor('did:plc:alice', 'alice.bsky.social');
+
+    const row = db.prepare('SELECT * FROM actors WHERE did = ?').get('did:plc:alice');
+    expect(row.handle).toBe('alice.bsky.social');
+  });
+
+  it('updates actor handle on conflict', () => {
+    writer.upsertActor('did:plc:alice', 'alice.bsky.social');
+    writer.upsertActor('did:plc:alice', 'alice.example.com');
+
+    const rows = db.prepare('SELECT * FROM actors').all();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].handle).toBe('alice.example.com');
+  });
+});
+
+describe('buildWhere', () => {
+  it('handles empty where', () => {
+    const { sql, params } = buildWhere([]);
+    expect(sql).toBe('1=1');
+    expect(params).toEqual([]);
+  });
+
+  it('handles simple eq condition', () => {
+    const { sql, params } = buildWhere([{ field: 'status', op: 'eq', value: 'active' }]);
+    expect(sql).toBe("json_extract(r.record, '$.status') = ?");
+    expect(params).toEqual(['active']);
+  });
+
+  it('handles system field (did)', () => {
+    const { sql, params } = buildWhere([{ field: 'did', op: 'eq', value: 'did:plc:abc' }]);
+    expect(sql).toBe('r.did = ?');
+    expect(params).toEqual(['did:plc:abc']);
+  });
+
+  it('handles in operator', () => {
+    const { sql, params } = buildWhere([{ field: 'status', op: 'in', value: ['a', 'b', 'c'] }]);
+    expect(sql).toBe("json_extract(r.record, '$.status') IN (?, ?, ?)");
+    expect(params).toEqual(['a', 'b', 'c']);
+  });
+
+  it('handles contains operator', () => {
+    const { sql, params } = buildWhere([{ field: 'text', op: 'contains', value: 'hello' }]);
+    expect(sql).toBe("json_extract(r.record, '$.text') LIKE ?");
+    expect(params).toEqual(['%hello%']);
+  });
+
+  it('handles comparison operators', () => {
+    const { sql, params } = buildWhere([
+      { field: 'count', op: 'gt', value: 10 },
+      { field: 'count', op: 'lte', value: 100 },
+    ]);
+    expect(sql).toBe(
+      "json_extract(r.record, '$.count') > ? AND json_extract(r.record, '$.count') <= ?",
+    );
+    expect(params).toEqual([10, 100]);
+  });
+
+  it('handles AND conditions', () => {
+    const { sql, params } = buildWhere([
+      {
+        op: 'and',
+        conditions: [
+          [{ field: 'a', op: 'eq', value: '1' }],
+          [{ field: 'b', op: 'eq', value: '2' }],
+        ],
+      },
+    ]);
+    expect(sql).toBe("(json_extract(r.record, '$.a') = ? AND json_extract(r.record, '$.b') = ?)");
+    expect(params).toEqual(['1', '2']);
+  });
+
+  it('handles OR conditions', () => {
+    const { sql, params } = buildWhere([
+      {
+        op: 'or',
+        conditions: [
+          [{ field: 'a', op: 'eq', value: '1' }],
+          [{ field: 'b', op: 'eq', value: '2' }],
+        ],
+      },
+    ]);
+    expect(sql).toBe("(json_extract(r.record, '$.a') = ? OR json_extract(r.record, '$.b') = ?)");
+    expect(params).toEqual(['1', '2']);
+  });
+
+  it('handles nested AND/OR', () => {
+    const { sql, params } = buildWhere([
+      { field: 'status', op: 'eq', value: 'active' },
+      {
+        op: 'or',
+        conditions: [
+          [{ field: 'author', op: 'eq', value: 'alice' }],
+          [{ field: 'author', op: 'eq', value: 'bob' }],
+        ],
+      },
+    ]);
+    expect(sql).toBe(
+      "json_extract(r.record, '$.status') = ? AND (json_extract(r.record, '$.author') = ? OR json_extract(r.record, '$.author') = ?)",
+    );
+    expect(params).toEqual(['active', 'alice', 'bob']);
+  });
+});
+
+describe('buildOrderBy', () => {
+  it('returns default order when no sort', () => {
+    const sql = buildOrderBy([]);
+    expect(sql).toBe('r.id DESC');
+  });
+
+  it('handles single sort field', () => {
+    const sql = buildOrderBy([{ field: 'createdAt', dir: 'asc' }]);
+    expect(sql).toBe("json_extract(r.record, '$.createdAt') ASC");
+  });
+
+  it('handles system field sort', () => {
+    const sql = buildOrderBy([{ field: 'indexedAt', dir: 'desc' }]);
+    expect(sql).toBe('r.indexed_at DESC');
+  });
+
+  it('handles multi-field sort', () => {
+    const sql = buildOrderBy([
+      { field: 'status', dir: 'asc' },
+      { field: 'createdAt', dir: 'desc' },
+    ]);
+    expect(sql).toBe(
+      "json_extract(r.record, '$.status') ASC, json_extract(r.record, '$.createdAt') DESC",
+    );
+  });
+
+  it('defaults to asc when dir not specified', () => {
+    const sql = buildOrderBy([{ field: 'name' }]);
+    expect(sql).toBe("json_extract(r.record, '$.name') ASC");
+  });
+});
+
+describe('findMany', () => {
+  let db;
+  let query;
+
+  beforeEach(() => {
+    db = new Database(':memory:');
+    setupSchema(db);
+    query = createSqliteAdapter(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it('returns empty result for empty table', async () => {
+    const result = await query({
+      type: 'findMany',
+      collection: 'app.bsky.feed.post',
+      where: [],
+      pagination: { first: 10 },
+    });
+    expect(result.rows).toEqual([]);
+    expect(result.hasNext).toBe(false);
+    expect(result.hasPrev).toBe(false);
+  });
+
+  it('returns records for collection', async () => {
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/app.bsky.feed.post/123',
+      'did:plc:abc',
+      'app.bsky.feed.post',
+      '123',
+      JSON.stringify({ text: 'hello' }),
+      '2024-01-01T00:00:00Z',
+    );
+
+    const result = await query({
+      type: 'findMany',
+      collection: 'app.bsky.feed.post',
+      where: [],
+      pagination: { first: 10 },
+    });
+
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].text).toBe('hello');
+    expect(result.rows[0].uri).toBe('at://did:plc:abc/app.bsky.feed.post/123');
+  });
+
+  it('respects first limit', async () => {
+    for (let i = 0; i < 5; i++) {
+      db.prepare(
+        `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+      ).run(
+        `at://did:plc:abc/col/${i}`,
+        'did:plc:abc',
+        'col',
+        `${i}`,
+        '{}',
+        '2024-01-01T00:00:00Z',
+      );
+    }
+
+    const result = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [],
+      pagination: { first: 3 },
+    });
+
+    expect(result.rows).toHaveLength(3);
+    expect(result.hasNext).toBe(true);
+  });
+
+  it('handles cursor pagination with after', async () => {
+    for (let i = 0; i < 5; i++) {
+      db.prepare(
+        `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+      ).run(
+        `at://did:plc:abc/col/${i}`,
+        'did:plc:abc',
+        'col',
+        `${i}`,
+        '{}',
+        '2024-01-01T00:00:00Z',
+      );
+    }
+
+    const first = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [],
+      pagination: { first: 2 },
+    });
+
+    const cursor = Buffer.from(JSON.stringify({ id: first.rows[1]._id })).toString('base64');
+
+    const second = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [],
+      pagination: { first: 2, after: cursor },
+    });
+
+    expect(second.rows).toHaveLength(2);
+    expect(second.hasPrev).toBe(true);
+  });
+
+  it('filters with where clause', async () => {
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/1',
+      'did:plc:abc',
+      'col',
+      '1',
+      JSON.stringify({ status: 'active' }),
+      '2024-01-01T00:00:00Z',
+    );
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/2',
+      'did:plc:abc',
+      'col',
+      '2',
+      JSON.stringify({ status: 'inactive' }),
+      '2024-01-01T00:00:00Z',
+    );
+
+    const result = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [{ field: 'status', op: 'eq', value: 'active' }],
+      pagination: { first: 10 },
+    });
+
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].status).toBe('active');
+  });
+
+  it('sorts results', async () => {
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/1',
+      'did:plc:abc',
+      'col',
+      '1',
+      JSON.stringify({ name: 'banana' }),
+      '2024-01-01T00:00:00Z',
+    );
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/2',
+      'did:plc:abc',
+      'col',
+      '2',
+      JSON.stringify({ name: 'apple' }),
+      '2024-01-01T00:00:00Z',
+    );
+
+    const result = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [],
+      sort: [{ field: 'name', dir: 'asc' }],
+      pagination: { first: 10 },
+    });
+
+    expect(result.rows[0].name).toBe('apple');
+    expect(result.rows[1].name).toBe('banana');
+  });
+
+  it('joins actor handle', async () => {
+    db.prepare(`INSERT INTO actors (did, handle) VALUES (?, ?)`).run('did:plc:abc', 'alice.test');
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run('at://did:plc:abc/col/1', 'did:plc:abc', 'col', '1', '{}', '2024-01-01T00:00:00Z');
+
+    const result = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [],
+      pagination: { first: 10 },
+    });
+
+    expect(result.rows[0].actorHandle).toBe('alice.test');
+  });
+});
+
+describe('aggregate', () => {
+  let db;
+  let query;
+
+  beforeEach(() => {
+    db = new Database(':memory:');
+    setupSchema(db);
+    query = createSqliteAdapter(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it('returns count for empty table', async () => {
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+    });
+    expect(result.count).toBe(0);
+    expect(result.groups).toEqual([]);
+  });
+
+  it('returns count for collection', async () => {
+    for (let i = 0; i < 5; i++) {
+      db.prepare(
+        `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+      ).run(
+        `at://did:plc:abc/col/${i}`,
+        'did:plc:abc',
+        'col',
+        `${i}`,
+        '{}',
+        '2024-01-01T00:00:00Z',
+      );
+    }
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+    });
+
+    expect(result.count).toBe(5);
+  });
+
+  it('respects where clause', async () => {
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/1',
+      'did:plc:abc',
+      'col',
+      '1',
+      JSON.stringify({ status: 'active' }),
+      '2024-01-01T00:00:00Z',
+    );
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/2',
+      'did:plc:abc',
+      'col',
+      '2',
+      JSON.stringify({ status: 'inactive' }),
+      '2024-01-01T00:00:00Z',
+    );
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [{ field: 'status', op: 'eq', value: 'active' }],
+    });
+
+    expect(result.count).toBe(1);
+  });
+
+  it('groups by field', async () => {
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/1',
+      'did:plc:abc',
+      'col',
+      '1',
+      JSON.stringify({ status: 'active' }),
+      '2024-01-01T00:00:00Z',
+    );
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/2',
+      'did:plc:abc',
+      'col',
+      '2',
+      JSON.stringify({ status: 'active' }),
+      '2024-01-01T00:00:00Z',
+    );
+    db.prepare(
+      `INSERT INTO records (uri, did, collection, rkey, record, indexed_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'at://did:plc:abc/col/3',
+      'did:plc:abc',
+      'col',
+      '3',
+      JSON.stringify({ status: 'inactive' }),
+      '2024-01-01T00:00:00Z',
+    );
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+      groupBy: ['status'],
+    });
+
+    expect(result.count).toBe(3);
+    expect(result.groups).toHaveLength(2);
+    expect(result.groups.find((g) => g.status === 'active').count).toBe(2);
+    expect(result.groups.find((g) => g.status === 'inactive').count).toBe(1);
+  });
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "lex-gql-sqlite",
+  "version": "0.1.0",
+  "description": "SQLite adapter for lex-gql",
+  "type": "module",
+  "main": "lex-gql-sqlite.js",
+  "types": "lex-gql-sqlite.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lex-gql-sqlite.d.ts",
+      "default": "./lex-gql-sqlite.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc"
+  },
+  "keywords": [
+    "graphql",
+    "atproto",
+    "lexicon",
+    "sqlite",
+    "adapter"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "better-sqlite3": ">=11.0.0",
+    "lex-gql": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "better-sqlite3": "^12.6.0",
+    "lex-gql": "workspace:*",
+    "typescript": "^5.7.2",
+    "vitest": "^1.6.1"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "types": ["node"]
+  },
+  "include": ["lex-gql-sqlite.js"],
+  "exclude": ["node_modules"]
+}