lex-gql 0.1.0

package/README.md

@@ -0,0 +1,232 @@
+# lex-gql
+
+GraphQL for AT Protocol Lexicons. Generates a fully-typed GraphQL schema from AT Protocol lexicon definitions with automatic join resolution.
+
+## Installation
+
+```bash
+npm install lex-gql graphql
+```
+
+## Quick Start
+
+```javascript
+import { parseLexicon, createAdapter } from 'lex-gql'
+
+// Parse your lexicons
+const lexicons = [
+  parseLexicon(profileLexiconJson),
+  parseLexicon(postLexiconJson),
+  parseLexicon(likeLexiconJson)
+]
+
+// Create adapter with your data source
+const adapter = createAdapter(lexicons, {
+  query: async (operation) => {
+    // Implement your data fetching logic
+    // operation.type: 'findMany' | 'findOne' | 'count' | 'aggregate' | 'create' | 'update' | 'delete'
+    // operation.collection: lexicon NSID
+    // operation.where: filter conditions
+    // operation.sort: sort clauses
+    // operation.pagination: { first, after, last, before }
+    // operation.select: requested field names (for query optimization)
+    return { rows: [...], hasNext: false, hasPrev: false, totalCount: 100 }
+  }
+})
+
+// Execute GraphQL queries
+const result = await adapter.execute(`
+  query {
+    appBskyFeedPost(first: 10, where: { text: { contains: "hello" } }) {
+      edges {
+        node {
+          uri
+          text
+          appBskyActorProfileByDid {
+            displayName
+          }
+        }
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+  }
+`)
+```
+
+## Features
+
+- **Automatic schema generation** from AT Protocol lexicons
+- **Relay-style pagination** with connections, edges, and pageInfo
+- **Forward joins** via `*Resolved` fields for strongRef and at-uri references
+- **Reverse joins** via `*Via*` fields (e.g., `appBskyFeedLikeViaSubject`)
+- **DID joins** between collections via `*ByDid` fields
+- **Filtering** with field conditions (eq, in, contains, gt, gte, lt, lte)
+- **Sorting** with multi-field sort support
+- **Aggregations** with groupBy support
+- **Mutations** for create, update, delete operations
+- **Batched join resolution** to avoid N+1 queries
+
+## API
+
+### `parseLexicon(json)`
+
+Parse a raw lexicon JSON object into the internal format.
+
+```javascript
+const lexicon = parseLexicon({
+  lexicon: 1,
+  id: 'app.bsky.feed.post',
+  defs: {
+    main: {
+      type: 'record',
+      record: {
+        type: 'object',
+        required: ['text', 'createdAt'],
+        properties: {
+          text: { type: 'string' },
+          createdAt: { type: 'string', format: 'datetime' }
+        }
+      }
+    }
+  }
+})
+```
+
+### `buildSchema(lexicons)`
+
+Build a GraphQL schema from parsed lexicons (without resolvers).
+
+```javascript
+import { buildSchema } from 'lex-gql'
+import { printSchema } from 'graphql'
+
+const schema = buildSchema(lexicons)
+console.log(printSchema(schema))
+```
+
+### `createAdapter(lexicons, options)`
+
+Create a full adapter with query execution.
+
+```javascript
+const adapter = createAdapter(lexicons, {
+  query: async (operation) => {
+    // Your data source implementation
+  }
+})
+
+const { schema, execute } = adapter
+```
+
+### Utility Functions
+
+```javascript
+import {
+  nsidToTypeName,      // 'app.bsky.feed.post' -> 'AppBskyFeedPost'
+  nsidToFieldName,     // 'app.bsky.feed.post' -> 'appBskyFeedPost'
+  nsidToCollectionName, // 'app.bsky.feed.post' -> 'post'
+  parseRefUri,         // Parse ref URIs like 'app.bsky.feed.defs#postView'
+  refToTypeName,       // Convert ref URI to GraphQL type name
+  mapLexiconType       // Map lexicon types to GraphQL type names
+} from 'lex-gql'
+```
+
+## Generated Schema Structure
+
+For each record lexicon, lex-gql generates:
+
+| Type | Example | Description |
+|------|---------|-------------|
+| Record type | `AppBskyFeedPost` | The main record with system and lexicon fields |
+| Connection | `AppBskyFeedPostConnection` | Relay connection with edges and pageInfo |
+| Edge | `AppBskyFeedPostEdge` | Edge with node and cursor |
+| WhereInput | `AppBskyFeedPostWhereInput` | Filter input with field conditions |
+| SortFieldInput | `AppBskyFeedPostSortFieldInput` | Sort input with field and direction |
+| Input | `AppBskyFeedPostInput` | Mutation input type |
+| Aggregated | `AppBskyFeedPostAggregated` | Aggregation result type |
+| GroupByField | `AppBskyFeedPostGroupByField` | Enum for groupBy fields |
+| FieldCondition | `AppBskyFeedPostFieldCondition` | Per-type field condition input |
+
+### System Fields
+
+Every record type includes these system fields:
+
+- `uri: String` - Record URI
+- `cid: String` - Record CID
+- `did: String` - DID of record author
+- `collection: String` - Collection name
+- `indexedAt: String` - When record was indexed
+- `actorHandle: String` - Handle of the actor
+
+### Special Types
+
+- `Blob` - Binary blob reference with `ref`, `mimeType`, `size`
+- `ComAtprotoRepoStrongRef` - Strong reference with `cid`, `uri`
+- `Record` - Union of all record types
+
+### Nested Types
+
+AT Protocol lexicons can define helper types alongside their main type. These live in the `defs` section under names other than `main`:
+
+```json
+{
+  "id": "app.bsky.richtext.facet",
+  "defs": {
+    "main": { ... },
+    "byteSlice": {
+      "type": "object",
+      "properties": {
+        "byteStart": { "type": "integer" },
+        "byteEnd": { "type": "integer" }
+      }
+    },
+    "mention": { ... },
+    "link": { ... }
+  }
+}
+```
+
+lex-gql generates GraphQL types for these with the pattern `{LexiconName}{DefName}`:
+
+- `app.bsky.richtext.facet#byteSlice` → `AppBskyRichtextFacetByteSlice`
+- `app.bsky.richtext.facet#mention` → `AppBskyRichtextFacetMention`
+- `app.bsky.actor.defs#profileView` → `AppBskyActorDefsProfileView`
+
+These types are included in the schema so they can be referenced by other types or used in queries.
+
+## Error Handling
+
+```javascript
+import { LexGqlError, ErrorCodes } from 'lex-gql'
+
+try {
+  parseLexicon(invalidJson)
+} catch (err) {
+  if (err instanceof LexGqlError) {
+    console.log(err.code)    // 'INVALID_LEXICON'
+    console.log(err.details) // { field: 'id' }
+  }
+}
+
+// Error codes:
+// - INVALID_LEXICON
+// - UNSUPPORTED_VERSION
+// - QUERY_FAILED
+// - VALIDATION_FAILED
+```
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## License
+
+MIT

package/lex-gql.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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;
+};
+/**
+ * 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;
+/**
+ * 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 WhereClause = {
+  field: string;
+  op: string;
+  value: any;
+};
+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;
+};
+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';