lex-gql 0.1.0 → 0.2.0

package/README.md

@@ -133,6 +133,100 @@ import {
 } from 'lex-gql'
 ```
 
+## Query Port Interface
+
+lex-gql follows the hexagonal architecture pattern. Your data layer implements the **query port** interface:
+
+### Operation Types
+
+```typescript
+type Operation =
+  | { type: 'findMany'; collection: string; where: WhereClause[]; pagination: Pagination; sort?: SortClause[] }
+  | { type: 'aggregate'; collection: string; where: WhereClause[]; groupBy?: string[] }
+  | { type: 'create'; collection: string; rkey?: string; record: object }
+  | { type: 'update'; collection: string; rkey: string; record: object }
+  | { type: 'delete'; collection: string; rkey: string }
+
+// Field condition
+type FieldCondition = { field: string; op: 'eq' | 'in' | 'contains' | 'gt' | 'gte' | 'lt' | 'lte'; value: any }
+
+// Logical operators (for AND/OR queries)
+type LogicalCondition = { op: 'and' | 'or'; conditions: WhereClause[][] }
+
+type WhereClause = FieldCondition | LogicalCondition
+type SortClause = { field: string; dir: 'asc' | 'desc' }
+type Pagination = { first?: number; after?: string; last?: number; before?: string }
+```
+
+### Cross-Collection URI Resolution
+
+For batched forward join resolution, lex-gql issues `findMany` operations with `collection: '*'`. This special value means "query across all collections by URI":
+
+```typescript
+// Forward join batch request
+{
+  type: 'findMany',
+  collection: '*',  // Special: resolve by URI, ignore collection filter
+  where: [{ field: 'uri', op: 'in', value: ['at://did1/...', 'at://did2/...'] }],
+  pagination: {}
+}
+```
+
+Adapters **must** handle this case by omitting the collection filter and returning records matching the URIs. The returned records must include a `collection` field for union type resolution.
+
+### Response Format
+
+```typescript
+// For findMany
+{ rows: Record[]; hasNext: boolean; hasPrev: boolean }
+
+// For aggregate
+{ count: number; groups: { [field]: value; count: number }[] }
+
+// For mutations
+Record | { uri: string }
+```
+
+### Standard Records Schema
+
+For SQL-based adapters, we recommend this schema:
+
+```sql
+CREATE TABLE records (
+  uri TEXT PRIMARY KEY,
+  did TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  rkey TEXT NOT NULL,
+  cid TEXT,
+  record TEXT NOT NULL,  -- JSON blob
+  indexed_at TEXT NOT NULL
+);
+
+CREATE INDEX idx_records_collection ON records(collection);
+CREATE INDEX idx_records_did ON records(did);
+
+CREATE TABLE actors (
+  did TEXT PRIMARY KEY,
+  handle TEXT NOT NULL
+);
+```
+
+### Hydration Helpers
+
+Use these helpers to transform database rows into lex-gql format:
+
+```javascript
+import { hydrateBlobs, hydrateRecord } from 'lex-gql';
+
+// hydrateBlobs - inject DID into blob fields for URL resolution
+const record = JSON.parse(row.record);
+const hydrated = hydrateBlobs(record, row.did);
+
+// hydrateRecord - full transformation from standard schema
+const rows = db.query('SELECT r.*, a.handle FROM records r LEFT JOIN actors a ON r.did = a.did');
+const records = rows.map(hydrateRecord);
+```
+
 ## Generated Schema Structure
 
 For each record lexicon, lex-gql generates:

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "lex-gql",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Generate a complete GraphQL API from AT Protocol lexicons",
   "license": "MIT",
   "type": "module",
-  "main": "lex-gql.js",
-  "types": "lex-gql.d.ts",
+  "main": "src/lex-gql.js",
+  "types": "src/lex-gql.d.ts",
   "files": [
-    "lex-gql.js",
-    "lex-gql.d.ts"
+    "src/lex-gql.js",
+    "src/lex-gql.d.ts"
   ],
   "keywords": [
     "graphql",
@@ -35,8 +35,9 @@
     "vitest": "^1.0.0"
   },
   "scripts": {
+    "build": "tsc",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc"
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/lex-gql.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Convert NSID to PascalCase type name
+ * @param {string} nsid - e.g. "app.bsky.feed.post"
+ * @returns {string} - e.g. "AppBskyFeedPost"
+ */
+export function nsidToTypeName(nsid: string): string;
+/**
+ * Convert NSID to camelCase field name
+ * @param {string} nsid - e.g. "app.bsky.feed.post"
+ * @returns {string} - e.g. "appBskyFeedPost"
+ */
+export function nsidToFieldName(nsid: string): string;
+/**
+ * Extract collection name (last segment) from NSID
+ * @param {string} nsid - e.g. "app.bsky.feed.post"
+ * @returns {string} - e.g. "post"
+ */
+export function nsidToCollectionName(nsid: string): string;
+/**
+ * Map AT Protocol lexicon type to GraphQL type name
+ * @param {string} lexiconType
+ * @returns {string}
+ */
+export function mapLexiconType(lexiconType: string): string;
+/**
+ * Parse a ref URI into nsid and fragment
+ * @param {string} refUri - e.g. "xyz.statusphere.post#embed" or "#mention"
+ * @returns {{ nsid: string|null, fragment: string }}
+ */
+export function parseRefUri(refUri: string): {
+    nsid: string | null;
+    fragment: string;
+};
+/**
+ * Resolve a ref string to a full registry key
+ * @param {string} ref - The ref string (e.g., "#replyRef" or "app.bsky.embed.images")
+ * @param {string} parentLexiconId - The lexicon ID containing this ref
+ * @returns {string} Full registry key
+ */
+export function resolveRefKey(ref: string, parentLexiconId: string): string;
+/**
+ * Convert a ref URI to a GraphQL type name
+ * @param {string} refUri - e.g. "fm.teal.alpha.feed.defs#artist"
+ * @returns {string} - e.g. "FmTealAlphaFeedDefsArtist"
+ */
+export function refToTypeName(refUri: string): string;
+/**
+ * Inject DID into blob objects for URL resolution.
+ * Blobs need the parent record's DID to generate CDN URLs.
+ *
+ * @param {any} obj - Record object or value to hydrate
+ * @param {string} did - DID to inject into blob objects
+ * @returns {any} - Hydrated object with did added to blobs
+ *
+ * @example
+ * const record = JSON.parse(row.record);
+ * const hydrated = hydrateBlobs(record, row.did);
+ */
+export function hydrateBlobs(obj: any, did: string): any;
+/**
+ * @typedef {Object} DatabaseRow
+ * @property {string} uri - Record AT URI
+ * @property {string} did - Author DID
+ * @property {string} collection - Lexicon NSID
+ * @property {string} [cid] - Content ID
+ * @property {string|Object} record - JSON string or parsed object
+ * @property {string} indexed_at - ISO timestamp
+ * @property {string} [handle] - Actor handle from actors table join
+ */
+/**
+ * Transform a database row into lex-gql record format.
+ * Expects the standard records table schema.
+ *
+ * Standard schema:
+ * - uri: TEXT (record AT URI)
+ * - did: TEXT (author DID)
+ * - collection: TEXT (lexicon NSID)
+ * - cid: TEXT (optional, content ID)
+ * - record: TEXT (JSON) or Object
+ * - indexed_at: TEXT (ISO timestamp)
+ * - handle: TEXT (optional, actor handle from actors table join)
+ *
+ * @param {DatabaseRow} row - Database row
+ * @returns {Record<string, any>} - Hydrated record for lex-gql
+ *
+ * @example
+ * const rows = db.query('SELECT r.*, a.handle FROM records r LEFT JOIN actors a ON r.did = a.did');
+ * const records = rows.map(hydrateRecord);
+ */
+export function hydrateRecord(row: DatabaseRow): Record<string, any>;
+/**
+ * Parse a lexicon JSON object into structured form
+ * @param {RawLexiconJson} json - Raw lexicon JSON
+ * @returns {Lexicon}
+ */
+export function parseLexicon(json: RawLexiconJson): Lexicon;
+/**
+ * Build a GraphQL schema from parsed lexicons
+ * @param {Lexicon[]} lexicons
+ * @returns {GraphQLSchema}
+ */
+export function buildSchema(lexicons: Lexicon[]): GraphQLSchema;
+/**
+ * Create a GraphQL adapter with query resolvers
+ * @param {Lexicon[]} lexicons
+ * @param {AdapterOptions} options
+ * @returns {{
+ *   schema: GraphQLSchema,
+ *   execute: (query: string, variables?: Record<string, unknown>) => Promise<any>,
+ *   subscribe: (query: string, variables?: Record<string, unknown>) => Promise<AsyncIterable<import('graphql').ExecutionResult>>
+ * }}
+ */
+export function createAdapter(lexicons: Lexicon[], options: AdapterOptions): {
+    schema: GraphQLSchema;
+    execute: (query: string, variables?: Record<string, unknown>) => Promise<any>;
+    subscribe: (query: string, variables?: Record<string, unknown>) => Promise<AsyncIterable<import("graphql").ExecutionResult>>;
+};
+export namespace ErrorCodes {
+    let INVALID_LEXICON: string;
+    let UNSUPPORTED_VERSION: string;
+    let QUERY_FAILED: string;
+    let VALIDATION_FAILED: string;
+}
+/**
+ * Custom error class for lex-gql errors
+ */
+export class LexGqlError extends Error {
+    /**
+     * @param {string} message
+     * @param {string} code
+     * @param {Object} [details]
+     */
+    constructor(message: string, code: string, details?: Object);
+    code: string;
+    details: Object;
+}
+export type DatabaseRow = {
+    /**
+     * - Record AT URI
+     */
+    uri: string;
+    /**
+     * - Author DID
+     */
+    did: string;
+    /**
+     * - Lexicon NSID
+     */
+    collection: string;
+    /**
+     * - Content ID
+     */
+    cid?: string | undefined;
+    /**
+     * - JSON string or parsed object
+     */
+    record: string | Object;
+    /**
+     * - ISO timestamp
+     */
+    indexed_at: string;
+    /**
+     * - Actor handle from actors table join
+     */
+    handle?: string | undefined;
+};
+/**
+ * A where clause for filtering records.
+ * Can be a field condition or a logical operator (AND/OR).
+ *
+ * Field condition: { field: 'text', op: 'eq', value: 'hello' }
+ * Logical AND:     { op: 'and', conditions: WhereClause[][] }
+ * Logical OR:      { op: 'or', conditions: WhereClause[][] }
+ */
+export type WhereClause = {
+    /**
+     * - Field name (for field conditions)
+     */
+    field?: string | undefined;
+    /**
+     * - Operator: 'eq' | 'in' | 'contains' | 'gt' | 'gte' | 'lt' | 'lte' | 'and' | 'or'
+     */
+    op: string;
+    /**
+     * - Value to compare (for field conditions)
+     */
+    value?: any;
+    /**
+     * - Nested conditions (for and/or)
+     */
+    conditions?: WhereClause[][] | undefined;
+};
+export type SortClause = {
+    field: string;
+    dir: string;
+};
+export type Pagination = {
+    first?: number | undefined;
+    after?: string | undefined;
+    last?: number | undefined;
+    before?: string | undefined;
+};
+export type Aggregate = {
+    field: string;
+    fn: string;
+};
+export type Operation = {
+    type: "findMany" | "findOne" | "count" | "aggregate" | "create" | "update" | "delete";
+    collection: string;
+    where?: WhereClause[] | undefined;
+    select?: string[] | undefined;
+    sort?: SortClause[] | undefined;
+    pagination?: Pagination | undefined;
+    data?: Record<string, any> | undefined;
+    uri?: string | undefined;
+    rkey?: string | undefined;
+    groupBy?: string[] | undefined;
+    aggregates?: Aggregate[] | undefined;
+    limit?: number | undefined;
+    orderBy?: "COUNT_ASC" | "COUNT_DESC" | undefined;
+    arrayFields?: string[] | undefined;
+};
+export type AdapterOptions = {
+    query: (op: Operation) => Promise<any>;
+    subscribe?: ((op: SubscribeOperation) => AsyncIterable<any>) | undefined;
+    context?: Record<string, any> | undefined;
+    maxDepth?: number | undefined;
+};
+export type SubscriptionEvent = "created" | "updated" | "deleted";
+export type SubscribeOperation = {
+    /**
+     * - The collection NSID (e.g., 'app.bsky.feed.post')
+     */
+    collection: string;
+    /**
+     * - The event type
+     */
+    event: SubscriptionEvent;
+};
+export type Property = {
+    name: string;
+    type: string;
+    required: boolean;
+    format?: string | null | undefined;
+    ref?: string | null | undefined;
+    refs?: string[] | null | undefined;
+    items?: ArrayItems | null | undefined;
+};
+export type ArrayItems = {
+    type: string;
+    ref?: string | null | undefined;
+    refs?: string[] | null | undefined;
+};
+export type RecordDef = {
+    type: string;
+    key?: string | null | undefined;
+    properties: Property[];
+};
+export type Lexicon = {
+    id: string;
+    defs: {
+        main: RecordDef | null;
+        others: Record<string, RecordDef>;
+    };
+};
+export type RawLexiconJson = {
+    id: string;
+    lexicon?: number | undefined;
+    defs?: Record<string, any> | undefined;
+};
+import { GraphQLSchema } from 'graphql';