lex-gql-sqlite 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,26 +1,28 @@
 # Changelog
 
-## [Unreleased]
+## 0.2.0
 
-### Added
+### Minor Changes
 
-- `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
+- 349ddb3: Add aggregate enhancements, actorHandle filtering, and DuckDB adapter
 
-### Changed
+### Patch Changes
 
-- AND/OR conditions format: `{ op: 'and', conditions: [...] }` instead of `{ field: 'AND', op: 'and', value: [...] }`
+- Updated dependencies [349ddb3]
+  - lex-gql@0.2.0
 
-## [0.1.0] - 2026-01-15
+## 0.1.0 - 2026-01-16
 
 ### Added
 
 - Initial release
 - `createSqliteAdapter(db)` - create query function from better-sqlite3 database
 - `setupSchema(db)` - create required tables and indexes
+- `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
 - Full WHERE support with AND/OR nesting
 - All filter operators: eq, in, contains, gt, gte, lt, lte
 - Multi-field sorting

package/README.md

@@ -38,7 +38,7 @@ Creates the required database tables and indexes.
 
 ### `createSqliteAdapter(db)`
 
-Returns a query function compatible with lex-gql's adapter interface.
+Returns a query function compatible with lex-gql's adapter interface. Supports cross-collection URI resolution (`collection: '*'`) for forward join batching.
 
 ### `buildWhere(where)`
 

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "lex-gql-sqlite",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SQLite adapter for lex-gql",
   "type": "module",
-  "main": "lex-gql-sqlite.js",
-  "types": "lex-gql-sqlite.d.ts",
+  "main": "src/lex-gql-sqlite.js",
+  "types": "src/lex-gql-sqlite.d.ts",
   "exports": {
     ".": {
-      "types": "./lex-gql-sqlite.d.ts",
-      "default": "./lex-gql-sqlite.js"
+      "types": "./src/lex-gql-sqlite.d.ts",
+      "default": "./src/lex-gql-sqlite.js"
     }
   },
   "scripts": {
+    "build": "tsc",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc"
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "graphql",
@@ -26,7 +27,7 @@
   "license": "MIT",
   "peerDependencies": {
     "better-sqlite3": ">=11.0.0",
-    "lex-gql": ">=0.1.0"
+    "lex-gql": ">=0.2.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",

package/{lex-gql-sqlite.d.ts → src/lex-gql-sqlite.d.ts}

@@ -6,9 +6,6 @@ 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)
@@ -58,18 +55,6 @@ 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
      */

package/{lex-gql-sqlite.js → src/lex-gql-sqlite.js}

@@ -37,12 +37,22 @@ export function setupSchema(db) {
   db.exec(SCHEMA_SQL);
 }
 
+/**
+ * Parse an AT URI into its components
+ * @param {string} uri - AT URI (at://did/collection/rkey)
+ * @returns {{ did: string, collection: string, rkey: string }}
+ */
+function parseAtUri(uri) {
+  const match = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+  if (!match) {
+    throw new Error(`Invalid AT URI: ${uri}`);
+  }
+  return { did: match[1], collection: match[2], rkey: match[3] };
+}
+
 /**
  * @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)
@@ -75,7 +85,8 @@ export function createWriter(db) {
   `);
 
   return {
-    insertRecord: ({ uri, did, collection, rkey, cid, record, indexedAt }) => {
+    insertRecord: ({ uri, cid, record, indexedAt }) => {
+      const { did, collection, rkey } = parseAtUri(uri);
       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);
@@ -96,6 +107,7 @@ const SYSTEM_FIELDS = {
   collection: 'r.collection',
   cid: 'r.cid',
   indexedAt: 'r.indexed_at',
+  actorHandle: 'a.handle',
 };
 
 /**
@@ -155,8 +167,10 @@ export function buildWhere(where) {
         }
         break;
       case 'contains':
-        parts.push(`${fieldPath} LIKE ?`);
-        params.push(`%${value}%`);
+        parts.push(`${fieldPath} LIKE ? ESCAPE '\\'`);
+        // Escape LIKE wildcards (% and _) in the search value
+        const escapedValue = String(value).replace(/[%_\\]/g, '\\$&');
+        params.push(`%${escapedValue}%`);
         break;
       case 'gt':
         parts.push(`${fieldPath} > ?`);
@@ -227,10 +241,10 @@ function findMany(db, op) {
   const { first = 20, after, last, before } = pagination;
 
   // Build WHERE clause
-  const { sql: whereSql, params: whereParams } = buildWhere([
-    { field: 'collection', op: 'eq', value: collection },
-    ...where,
-  ]);
+  // Special case: collection '*' means query across all collections (for URI resolution)
+  const collectionFilter =
+    collection === '*' ? [] : [{ field: 'collection', op: 'eq', value: collection }];
+  const { sql: whereSql, params: whereParams } = buildWhere([...collectionFilter, ...where]);
 
   // Handle cursor pagination
   const cursorConditions = [];
@@ -243,7 +257,9 @@ function findMany(db, op) {
         cursorConditions.push('r.id < ?');
         cursorParams.push(cursor.id);
       }
-    } catch {}
+    } catch (err) {
+      console.warn('lex-gql-sqlite: Malformed cursor (after), ignoring:', /** @type {Error} */ (err).message);
+    }
   }
 
   if (before) {
@@ -253,7 +269,9 @@ function findMany(db, op) {
         cursorConditions.push('r.id > ?');
         cursorParams.push(cursor.id);
       }
-    } catch {}
+    } catch (err) {
+      console.warn('lex-gql-sqlite: Malformed cursor (before), ignoring:', /** @type {Error} */ (err).message);
+    }
   }
 
   const fullWhere =
@@ -295,7 +313,7 @@ function findMany(db, op) {
   }));
 
   // Get total count (without pagination)
-  const countSql = `SELECT COUNT(*) as count FROM records r WHERE ${whereSql}`;
+  const countSql = `SELECT COUNT(*) as count FROM records r LEFT JOIN actors a ON r.did = a.did WHERE ${whereSql}`;
   /** @type {{count: number}} */
   const countResult = /** @type {any} */ (db.prepare(countSql).get(...whereParams));
 
@@ -307,12 +325,55 @@ function findMany(db, op) {
   };
 }
 
+/**
+ * Get the SQL expression for a field
+ * @param {string} field
+ * @returns {string}
+ */
+function getFieldExpression(field) {
+  return SYSTEM_FIELDS[field] || `json_extract(r.record, '$.${field}')`;
+}
+
+/**
+ * Get SQL expression for a groupBy field, handling date interval suffixes
+ * @param {string} field
+ * @returns {{ expr: string, alias: string }}
+ */
+function getGroupByExpression(field) {
+  const dayMatch = field.match(/^(.+)_day$/);
+  const weekMatch = field.match(/^(.+)_week$/);
+  const monthMatch = field.match(/^(.+)_month$/);
+
+  if (dayMatch) {
+    const base = dayMatch[1];
+    const path = getFieldExpression(base);
+    return { expr: `date(${path})`, alias: field };
+  }
+  if (weekMatch) {
+    const base = weekMatch[1];
+    const path = getFieldExpression(base);
+    return { expr: `strftime('%Y-%W', ${path})`, alias: field };
+  }
+  if (monthMatch) {
+    const base = monthMatch[1];
+    const path = getFieldExpression(base);
+    return { expr: `strftime('%Y-%m', ${path})`, alias: field };
+  }
+
+  const expr = getFieldExpression(field);
+  return { expr, alias: field };
+}
+
 /**
  * @param {import('better-sqlite3').Database} db
  * @param {any} op
  */
 function aggregate(db, op) {
-  const { collection, where = [], groupBy = [] } = op;
+  const { collection, where = [], groupBy = [], limit = 50, orderBy = 'COUNT_DESC', arrayFields = [] } = op;
+
+  // Cap limit at 1000
+  const effectiveLimit = Math.min(limit, 1000);
+  const orderDirection = orderBy === 'COUNT_ASC' ? 'ASC' : 'DESC';
 
   const { sql: whereSql, params } = buildWhere([
     { field: 'collection', op: 'eq', value: collection },
@@ -320,36 +381,59 @@ function aggregate(db, op) {
   ]);
 
   if (groupBy.length === 0) {
-    const sql = `SELECT COUNT(*) as count FROM records r WHERE ${whereSql}`;
+    const sql = `SELECT COUNT(*) as count FROM records r LEFT JOIN actors a ON r.did = a.did 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}`;
-    })
+  const groupExpressions = groupBy.map((/** @type {string} */ f) => getGroupByExpression(f));
+
+  const groupFields = groupExpressions
+    .map((/** @type {{ expr: string, alias: string }} */ { expr, alias }) => `${expr} as ${alias}`)
     .join(', ');
 
-  const groupByClause = groupBy
-    .map((/** @type {string} */ f) => {
-      return SYSTEM_FIELDS[f] || `json_extract(r.record, '$.${f}')`;
-    })
+  const groupByClause = groupExpressions
+    .map((/** @type {{ expr: string }} */ { expr }) => expr)
     .join(', ');
 
+  // Build array field selections using MAX to get a sample value from each group
+  const arrayFieldSelects = arrayFields
+    .map((/** @type {string} */ f) => `MAX(json_extract(r.record, '$.${f}')) as ${f}`)
+    .join(', ');
+
+  const selectClause = arrayFieldSelects
+    ? `${groupFields}, ${arrayFieldSelects}, COUNT(*) as count`
+    : `${groupFields}, COUNT(*) as count`;
+
   const sql = `
-    SELECT ${groupFields}, COUNT(*) as count
+    SELECT ${selectClause}
     FROM records r
+    LEFT JOIN actors a ON r.did = a.did
     WHERE ${whereSql}
     GROUP BY ${groupByClause}
-    ORDER BY count DESC
-    LIMIT 100
+    ORDER BY count ${orderDirection}
+    LIMIT ?
   `;
 
   /** @type {Array<{count: number, [key: string]: any}>} */
-  const groups = /** @type {any} */ (db.prepare(sql).all(...params));
+  const rawGroups = /** @type {any} */ (db.prepare(sql).all(...params, effectiveLimit));
+
+  // Parse JSON array fields back into actual arrays
+  const groups = rawGroups.map((group) => {
+    const parsed = { ...group };
+    for (const field of arrayFields) {
+      if (parsed[field] && typeof parsed[field] === 'string') {
+        try {
+          parsed[field] = JSON.parse(parsed[field]);
+        } catch {
+          // Keep as-is if not valid JSON
+        }
+      }
+    }
+    return parsed;
+  });
+
   const count = groups.reduce((sum, g) => sum + g.count, 0);
 
   return { count, groups };

package/{lex-gql-sqlite.test.js → test/lex-gql-sqlite.test.js}

@@ -6,7 +6,7 @@ import {
   createSqliteAdapter,
   createWriter,
   setupSchema,
-} from './lex-gql-sqlite.js';
+} from '../src/lex-gql-sqlite.js';
 
 describe('setupSchema', () => {
   let db;
@@ -68,9 +68,6 @@ describe('createWriter', () => {
   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' },
     });
@@ -86,17 +83,11 @@ describe('createWriter', () => {
   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' },
     });
 
@@ -108,9 +99,6 @@ describe('createWriter', () => {
   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' },
     });
 
@@ -164,10 +152,16 @@ describe('buildWhere', () => {
 
   it('handles contains operator', () => {
     const { sql, params } = buildWhere([{ field: 'text', op: 'contains', value: 'hello' }]);
-    expect(sql).toBe("json_extract(r.record, '$.text') LIKE ?");
+    expect(sql).toBe("json_extract(r.record, '$.text') LIKE ? ESCAPE '\\'");
     expect(params).toEqual(['%hello%']);
   });
 
+  it('escapes LIKE wildcards in contains operator', () => {
+    const { sql, params } = buildWhere([{ field: 'text', op: 'contains', value: '50%' }]);
+    expect(sql).toBe("json_extract(r.record, '$.text') LIKE ? ESCAPE '\\'");
+    expect(params).toEqual(['%50\\%%']);
+  });
+
   it('handles comparison operators', () => {
     const { sql, params } = buildWhere([
       { field: 'count', op: 'gt', value: 10 },
@@ -260,11 +254,13 @@ describe('buildOrderBy', () => {
 describe('findMany', () => {
   let db;
   let query;
+  let writer;
 
   beforeEach(() => {
     db = new Database(':memory:');
     setupSchema(db);
     query = createSqliteAdapter(db);
+    writer = createWriter(db);
   });
 
   afterEach(() => {
@@ -284,16 +280,11 @@ describe('findMany', () => {
   });
 
   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',
-    );
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/app.bsky.feed.post/123',
+      record: { text: 'hello' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
 
     const result = await query({
       type: 'findMany',
@@ -309,16 +300,11 @@ describe('findMany', () => {
 
   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',
-      );
+      writer.insertRecord({
+        uri: `at://did:plc:abc/col/${i}`,
+        record: {},
+        indexedAt: '2024-01-01T00:00:00Z',
+      });
     }
 
     const result = await query({
@@ -334,16 +320,11 @@ describe('findMany', () => {
 
   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',
-      );
+      writer.insertRecord({
+        uri: `at://did:plc:abc/col/${i}`,
+        record: {},
+        indexedAt: '2024-01-01T00:00:00Z',
+      });
     }
 
     const first = await query({
@@ -367,26 +348,16 @@ describe('findMany', () => {
   });
 
   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',
-    );
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/1',
+      record: { status: 'active' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/2',
+      record: { status: 'inactive' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
 
     const result = await query({
       type: 'findMany',
@@ -400,26 +371,16 @@ describe('findMany', () => {
   });
 
   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',
-    );
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/1',
+      record: { name: 'banana' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/2',
+      record: { name: 'apple' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
 
     const result = await query({
       type: 'findMany',
@@ -434,10 +395,12 @@ describe('findMany', () => {
   });
 
   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');
+    writer.upsertActor('did:plc:abc', 'alice.test');
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/1',
+      record: {},
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
 
     const result = await query({
       type: 'findMany',
@@ -448,16 +411,44 @@ describe('findMany', () => {
 
     expect(result.rows[0].actorHandle).toBe('alice.test');
   });
+
+  it('filters by actorHandle', async () => {
+    writer.upsertActor('did:plc:alice', 'alice.test');
+    writer.upsertActor('did:plc:bob', 'bob.test');
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/1',
+      record: { text: 'from alice' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:bob/col/2',
+      record: { text: 'from bob' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+
+    const result = await query({
+      type: 'findMany',
+      collection: 'col',
+      where: [{ field: 'actorHandle', op: 'eq', value: 'alice.test' }],
+      pagination: { first: 10 },
+    });
+
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].actorHandle).toBe('alice.test');
+    expect(result.rows[0].text).toBe('from alice');
+  });
 });
 
 describe('aggregate', () => {
   let db;
   let query;
+  let writer;
 
   beforeEach(() => {
     db = new Database(':memory:');
     setupSchema(db);
     query = createSqliteAdapter(db);
+    writer = createWriter(db);
   });
 
   afterEach(() => {
@@ -476,16 +467,11 @@ describe('aggregate', () => {
 
   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',
-      );
+      writer.insertRecord({
+        uri: `at://did:plc:abc/col/${i}`,
+        record: {},
+        indexedAt: '2024-01-01T00:00:00Z',
+      });
     }
 
     const result = await query({
@@ -498,26 +484,16 @@ describe('aggregate', () => {
   });
 
   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',
-    );
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/1',
+      record: { status: 'active' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/2',
+      record: { status: 'inactive' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
 
     const result = await query({
       type: 'aggregate',
@@ -529,36 +505,21 @@ describe('aggregate', () => {
   });
 
   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',
-    );
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/1',
+      record: { status: 'active' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/2',
+      record: { status: 'active' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:abc/col/3',
+      record: { status: 'inactive' },
+      indexedAt: '2024-01-01T00:00:00Z',
+    });
 
     const result = await query({
       type: 'aggregate',
@@ -572,4 +533,121 @@ describe('aggregate', () => {
     expect(result.groups.find((g) => g.status === 'active').count).toBe(2);
     expect(result.groups.find((g) => g.status === 'inactive').count).toBe(1);
   });
+
+  it('groups by day interval', async () => {
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/1',
+      record: { playedTime: '2024-01-15T10:00:00Z' },
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/2',
+      record: { playedTime: '2024-01-15T22:00:00Z' },
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/3',
+      record: { playedTime: '2024-01-16T08:00:00Z' },
+    });
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+      groupBy: ['playedTime_day'],
+    });
+
+    expect(result.count).toBe(3);
+    expect(result.groups).toHaveLength(2);
+    expect(result.groups.find((g) => g.playedTime_day === '2024-01-15').count).toBe(2);
+    expect(result.groups.find((g) => g.playedTime_day === '2024-01-16').count).toBe(1);
+  });
+
+  it('groups by week interval', async () => {
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/1',
+      record: { playedTime: '2024-01-01T10:00:00Z' }, // Week 01
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/2',
+      record: { playedTime: '2024-01-03T10:00:00Z' }, // Week 01
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/3',
+      record: { playedTime: '2024-01-08T10:00:00Z' }, // Week 02
+    });
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+      groupBy: ['playedTime_week'],
+    });
+
+    expect(result.count).toBe(3);
+    expect(result.groups).toHaveLength(2);
+  });
+
+  it('groups by month interval', async () => {
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/1',
+      record: { playedTime: '2024-01-15T10:00:00Z' },
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/2',
+      record: { playedTime: '2024-01-20T10:00:00Z' },
+    });
+    writer.insertRecord({
+      uri: 'at://did:plc:alice/col/3',
+      record: { playedTime: '2024-02-05T10:00:00Z' },
+    });
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+      groupBy: ['playedTime_month'],
+    });
+
+    expect(result.count).toBe(3);
+    expect(result.groups).toHaveLength(2);
+    expect(result.groups.find((g) => g.playedTime_month === '2024-01').count).toBe(2);
+    expect(result.groups.find((g) => g.playedTime_month === '2024-02').count).toBe(1);
+  });
+
+  it('respects custom limit', async () => {
+    // Create 5 distinct groups
+    for (let i = 0; i < 5; i++) {
+      writer.insertRecord({
+        uri: `at://did:plc:alice/col/${i}`,
+        record: { category: `cat${i}` },
+      });
+    }
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+      groupBy: ['category'],
+      limit: 3,
+    });
+
+    expect(result.groups).toHaveLength(3);
+  });
+
+  it('supports ascending count order', async () => {
+    writer.insertRecord({ uri: 'at://did:plc:alice/col/1', record: { cat: 'a' } });
+    writer.insertRecord({ uri: 'at://did:plc:alice/col/2', record: { cat: 'a' } });
+    writer.insertRecord({ uri: 'at://did:plc:alice/col/3', record: { cat: 'a' } });
+    writer.insertRecord({ uri: 'at://did:plc:alice/col/4', record: { cat: 'b' } });
+
+    const result = await query({
+      type: 'aggregate',
+      collection: 'col',
+      where: [],
+      groupBy: ['cat'],
+      orderBy: 'COUNT_ASC',
+    });
+
+    expect(result.groups[0].cat).toBe('b'); // count 1 first
+    expect(result.groups[1].cat).toBe('a'); // count 3 second
+  });
 });

package/tsconfig.json

@@ -7,6 +7,6 @@
     "emitDeclarationOnly": true,
     "types": ["node"]
   },
-  "include": ["lex-gql-sqlite.js"],
-  "exclude": ["node_modules"]
+  "include": ["src/lex-gql-sqlite.js"],
+  "exclude": ["node_modules", "test"]
 }