lex-gql-duckdb 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0
+
+### Minor Changes
+
+- 349ddb3: Add aggregate enhancements, actorHandle filtering, and DuckDB adapter
+
+### Patch Changes
+
+- Updated dependencies [349ddb3]
+  - lex-gql@0.2.0

package/README.md

@@ -0,0 +1,106 @@
+# lex-gql-duckdb
+
+DuckDB adapter for [lex-gql](../lex-gql) - optimized for analytics-heavy workloads.
+
+## Why DuckDB?
+
+DuckDB is a columnar database designed for analytical queries. Compared to SQLite:
+
+- **~17x faster aggregates** on large datasets (tested with 660K+ records)
+- Better suited for GROUP BY, COUNT, and time-series queries
+- Same embeddable, serverless model as SQLite
+
+Use this adapter when your workload involves heavy aggregate queries (top tracks, leaderboards, time-based analytics).
+
+## Installation
+
+```bash
+npm install lex-gql-duckdb duckdb
+```
+
+## Usage
+
+```javascript
+import { createAdapter, parseLexicon } from 'lex-gql';
+import { createDuckDB, setupSchema, createWriter, createDuckDBAdapter } from 'lex-gql-duckdb';
+
+// 1. Create DuckDB connection
+const db = await createDuckDB('./data/records.duckdb');
+await setupSchema(db);
+
+// 2. Create writer for inserting records
+const writer = createWriter(db);
+
+await writer.insertRecord({
+  uri: 'at://did:plc:xyz/app.example.post/abc',
+  cid: 'bafyrei...',
+  record: { text: 'Hello world', createdAt: new Date().toISOString() }
+});
+
+await writer.upsertActor('did:plc:xyz', 'alice.bsky.social');
+
+// 3. Create lex-gql adapter
+const query = createDuckDBAdapter(db);
+const adapter = createAdapter(lexicons, { query });
+
+// 4. Use adapter.schema with your GraphQL server
+```
+
+## API
+
+### `createDuckDB(dbPath)`
+
+Creates a promisified DuckDB connection.
+
+- `dbPath` - Path to database file, or `':memory:'` for in-memory database
+- Returns `Promise<DuckDBConnection>`
+
+### `setupSchema(conn)`
+
+Creates the required tables and indexes.
+
+### `createWriter(conn)`
+
+Returns an object with:
+
+- `insertRecord({ uri, cid, record, indexedAt? })` - Insert or update a record
+- `deleteRecord(uri)` - Delete a record by URI
+- `upsertActor(did, handle)` - Insert or update an actor
+
+### `createDuckDBAdapter(conn)`
+
+Creates a query adapter compatible with lex-gql's `createAdapter()`.
+
+Supports:
+- `findMany` - Paginated queries with filtering and sorting
+- `aggregate` - GROUP BY queries with COUNT
+
+## Date Handling
+
+The adapter handles both ISO strings and Unix timestamps (seconds or milliseconds) for date fields. Date interval suffixes work automatically:
+
+```graphql
+query {
+  myRecordAggregate(groupBy: [createdAt_day]) {
+    groups {
+      createdAt_day  # Returns "2025-01-15"
+      count
+    }
+  }
+}
+```
+
+Supported suffixes: `_day`, `_week`, `_month`
+
+## Comparison with lex-gql-sqlite
+
+| Feature | lex-gql-sqlite | lex-gql-duckdb |
+|---------|----------------|----------------|
+| Best for | Simple apps, small datasets | Analytics, large datasets |
+| Aggregate speed | ~1500ms (660K rows) | ~85ms (660K rows) |
+| Write speed | Fast | Fast (batch inserts) |
+| Maturity | Battle-tested | Newer, but solid |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "lex-gql-duckdb",
+  "version": "0.2.0",
+  "description": "DuckDB adapter for lex-gql - optimized for analytics queries",
+  "type": "module",
+  "main": "src/lex-gql-duckdb.js",
+  "types": "src/lex-gql-duckdb.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/lex-gql-duckdb.d.ts",
+      "default": "./src/lex-gql-duckdb.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "graphql",
+    "atproto",
+    "lexicon",
+    "duckdb",
+    "analytics",
+    "adapter"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "duckdb": ">=1.0.0",
+    "lex-gql": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "duckdb": "^1.4.3",
+    "lex-gql": "workspace:*",
+    "typescript": "^5.7.2",
+    "vitest": "^1.6.1"
+  }
+}

package/src/lex-gql-duckdb.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @typedef {Object} DuckDBConnection
+ * @property {duckdb.Database} db - The DuckDB database instance
+ * @property {duckdb.Connection} conn - The connection instance
+ * @property {(sql: string, ...params: any[]) => Promise<void>} run - Execute a statement
+ * @property {(sql: string, ...params: any[]) => Promise<any[]>} all - Query all rows
+ * @property {(sql: string, ...params: any[]) => Promise<any>} get - Query single row
+ */
+/**
+ * Create a promisified DuckDB connection
+ * @param {string} dbPath - Path to database file (use ':memory:' for in-memory)
+ * @returns {Promise<DuckDBConnection>}
+ */
+export function createDuckDB(dbPath: string): Promise<DuckDBConnection>;
+/**
+ * Set up the required database schema for lex-gql-duckdb
+ * @param {DuckDBConnection} conn
+ */
+export function setupSchema(conn: DuckDBConnection): Promise<void>;
+/**
+ * @typedef {Object} RecordInput
+ * @property {string} uri - Record URI (at://did/collection/rkey)
+ * @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) => Promise<void>} insertRecord - Insert or replace a record
+ * @property {(uri: string) => Promise<void>} deleteRecord - Delete a record by URI
+ * @property {(did: string, handle: string) => Promise<void>} upsertActor - Insert or replace an actor
+ */
+/**
+ * Create a writer with methods for efficient writes
+ * @param {DuckDBConnection} conn
+ * @returns {Writer}
+ */
+export function createWriter(conn: DuckDBConnection): 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 DuckDB query adapter for lex-gql
+ * @param {DuckDBConnection} conn - DuckDB connection from createDuckDB()
+ * @returns {(op: import('lex-gql').Operation) => Promise<any>}
+ */
+export function createDuckDBAdapter(conn: DuckDBConnection): (op: import("lex-gql").Operation) => Promise<any>;
+/**
+ * SQL schema for lex-gql records
+ */
+export const SCHEMA_SQL: "\n  CREATE SEQUENCE IF NOT EXISTS records_id_seq;\n\n  CREATE TABLE IF NOT EXISTS records (\n    id INTEGER DEFAULT nextval('records_id_seq'),\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 JSON NOT NULL,\n    indexed_at TIMESTAMP 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\n  CREATE TABLE IF NOT EXISTS actors (\n    did TEXT PRIMARY KEY,\n    handle TEXT NOT NULL\n  );\n";
+export type DuckDBConnection = {
+    /**
+     * - The DuckDB database instance
+     */
+    db: duckdb.Database;
+    /**
+     * - The connection instance
+     */
+    conn: duckdb.Connection;
+    /**
+     * - Execute a statement
+     */
+    run: (sql: string, ...params: any[]) => Promise<void>;
+    /**
+     * - Query all rows
+     */
+    all: (sql: string, ...params: any[]) => Promise<any[]>;
+    /**
+     * - Query single row
+     */
+    get: (sql: string, ...params: any[]) => Promise<any>;
+};
+export type RecordInput = {
+    /**
+     * - Record URI (at://did/collection/rkey)
+     */
+    uri: 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) => Promise<void>;
+    /**
+     * - Delete a record by URI
+     */
+    deleteRecord: (uri: string) => Promise<void>;
+    /**
+     * - Insert or replace an actor
+     */
+    upsertActor: (did: string, handle: string) => Promise<void>;
+};
+import duckdb from 'duckdb';