@constructive-io/graphql-query 3.2.4 → 3.3.0

package/README.md

@@ -12,7 +12,7 @@
    <a href="https://www.npmjs.com/package/@constructive-io/graphql-query"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphql%2Fquery%2Fpackage.json"/></a>
 </p>
 
-> Fluent GraphQL query and mutation builder for PostGraphile-based schemas.
+> Browser-safe GraphQL query generation core for PostGraphile schemas. Build type-safe queries, mutations, and introspection pipelines — at runtime or build time.
 
 ## Installation
 
@@ -20,68 +20,71 @@
 npm install @constructive-io/graphql-query
 ```
 
-## Why Use `@constructive-io/graphql-query`?
+## Overview
 
-* ⚡ Build complex, nested GraphQL queries fluently
-* ✅ Schema-aware via introspection (PostGraphile optimized)
-* 🧠 Prevents common query syntax issues
-* 🧩 Designed for composability and clean syntax
+This package is the **canonical source** for PostGraphile query generation logic. It provides:
 
-## Usage
+- **Query generators** — `buildSelect`, `buildFindOne`, `buildCount` for read operations
+- **Mutation generators** — `buildPostGraphileCreate`, `buildPostGraphileUpdate`, `buildPostGraphileDelete`
+- **Introspection pipeline** — `inferTablesFromIntrospection` to convert a GraphQL schema into `CleanTable` metadata
+- **AST builders** — low-level `getAll`, `getMany`, `getOne`, `createOne`, `patchOne`, `deleteOne`
+- **Client utilities** — `TypedDocumentString`, `execute`, `DataError` for type-safe execution and error handling
+- **Naming helpers** — server-aware inflection functions that respect PostGraphile's schema naming
 
-```ts
-import { QueryBuilder } from '@constructive-io/graphql-query';
+All modules are **browser-safe** (no Node.js APIs). `@constructive-io/graphql-codegen` depends on this package for the core logic and adds Node.js-only features (CLI, file output, watch mode).
+
+---
+
+## Quick Start: Generate Queries from a Schema
+
+The most common workflow: introspect a GraphQL schema, then generate queries and mutations for any table.
 
-const builder = new QueryBuilder({
-  introspection: { ...queries, ...mutations } // provide your GraphQL schema metadata
+### Step 1 — Introspect
+
+```ts
+import {
+  inferTablesFromIntrospection,
+  SCHEMA_INTROSPECTION_QUERY,
+} from '@constructive-io/graphql-query';
+
+// Fetch introspection from any GraphQL endpoint
+const response = await fetch('/graphql', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query: SCHEMA_INTROSPECTION_QUERY }),
 });
+const { data } = await response.json();
 
-const result = builder
-  .query('Action')
-  .edges(true)
-  .getMany({
-    select: {
-      id: true,
-      name: true,
-      photo: true,
-      title: true,
-      actionResults: {
-        select: {
-          id: true,
-          actionId: true
-        },
-        variables: {
-          first: 10,
-          before: null,
-          filter: {
-            name: {
-              in: ['abc', 'def']
-            },
-            actionId: {
-              equalTo: 'dc310161-7a42-4b93-6a56-9fa48adcad7e'
-            }
-          }
-        }
-      }
-    }
-  })
-  .print();
+// Convert to CleanTable metadata
+const tables = inferTablesFromIntrospection(data);
+// tables = [{ name: 'User', fields: [...], relations: {...}, query: {...}, inflection: {...} }, ...]
 ```
 
-## Output
+### Step 2 — Generate a SELECT query
+
+```ts
+import { buildSelect } from '@constructive-io/graphql-query';
+
+const userTable = tables.find(t => t.name === 'User')!;
+const query = buildSelect(userTable, tables);
+
+console.log(query.toString());
+```
+
+**Generated GraphQL:**
 
 ```graphql
-query getActionsQuery(
+query getUsersQuery(
   $first: Int
   $last: Int
   $after: Cursor
   $before: Cursor
   $offset: Int
-  $condition: ActionCondition
-  $filter: ActionFilter
-  $orderBy: [ActionsOrderBy!]
+  $condition: UserCondition
+  $filter: UserFilter
+  $orderBy: [UsersOrderBy!]
 ) {
-  actions(
+  users(
     first: $first
     last: $last
     offset: $offset
@@ -98,32 +101,375 @@ query getActionsQuery(
       endCursor
       startCursor
     }
-    edges {
-      cursor
-      node {
+    nodes {
+      id
+      name
+      email
+      createdAt
+    }
+  }
+}
+```
+
+### Step 3 — Generate mutations
+
+```ts
+import {
+  buildPostGraphileCreate,
+  buildPostGraphileUpdate,
+  buildPostGraphileDelete,
+} from '@constructive-io/graphql-query';
+
+const createQuery = buildPostGraphileCreate(userTable, tables);
+const updateQuery = buildPostGraphileUpdate(userTable, tables);
+const deleteQuery = buildPostGraphileDelete(userTable, tables);
+```
+
+**Generated CREATE mutation:**
+
+```graphql
+mutation createUserMutation($input: CreateUserInput!) {
+  createUser(input: $input) {
+    user {
+      id
+      name
+      email
+      createdAt
+    }
+  }
+}
+```
+
+**Generated UPDATE mutation:**
+
+```graphql
+mutation updateUserMutation($input: UpdateUserInput!) {
+  updateUser(input: $input) {
+    user {
+      id
+      name
+      email
+      createdAt
+    }
+  }
+}
+```
+
+**Generated DELETE mutation:**
+
+```graphql
+mutation deleteUserMutation($input: DeleteUserInput!) {
+  deleteUser(input: $input) {
+    clientMutationId
+  }
+}
+```
+
+---
+
+## Nested Relations
+
+Include related tables in your query with automatic Connection wrapping for hasMany relations:
+
+```ts
+import { buildSelect } from '@constructive-io/graphql-query';
+
+const actionTable = tables.find(t => t.name === 'Action')!;
+
+const query = buildSelect(actionTable, tables, {
+  fieldSelection: {
+    select: ['id', 'name', 'photo', 'title'],
+    include: {
+      actionResults: ['id', 'actionId'],  // hasMany → wrapped in nodes { ... }
+      category: true,                      // belongsTo → direct nesting
+    },
+  },
+});
+```
+
+**Generated GraphQL:**
+
+```graphql
+query actionsQuery {
+  actions {
+    totalCount
+    nodes {
+      id
+      name
+      photo
+      title
+      actionResults(first: 20) {
+        nodes {
+          id
+          actionId
+        }
+      }
+      category {
         id
         name
-        photo
-        title
-        actionResults(
-          first: 10
-          before: null
-          filter: {
-            name: { in: ["abc", "def"] }
-            actionId: { equalTo: "dc310161-7a42-4b93-6a56-9fa48adcad7e" }
-          }
-        ) {
-          nodes {
-            id
-            actionId
-          }
-        }
       }
     }
   }
 }
 ```
 
+> **hasMany** relations are automatically wrapped in the PostGraphile Connection pattern (`nodes { ... }` with a default `first: 20` limit).
+> **belongsTo** relations are nested directly.
+
+---
+
+## FindOne Query
+
+```ts
+import { buildFindOne } from '@constructive-io/graphql-query';
+
+const findOneQuery = buildFindOne(userTable);
+console.log(findOneQuery.toString());
+```
+
+**Generated GraphQL:**
+
+```graphql
+query getUserQuery($id: UUID!) {
+  user(id: $id) {
+    id
+    name
+    email
+    createdAt
+  }
+}
+```
+
+---
+
+## Count Query
+
+```ts
+import { buildCount } from '@constructive-io/graphql-query';
+
+const countQuery = buildCount(userTable);
+console.log(countQuery.toString());
+```
+
+**Generated GraphQL:**
+
+```graphql
+query getUsersCountQuery(
+  $condition: UserCondition
+  $filter: UserFilter
+) {
+  users(condition: $condition, filter: $filter) {
+    totalCount
+  }
+}
+```
+
+---
+
+## Field Selection
+
+Control which fields and relations are included using presets or custom selection:
+
+```ts
+import { buildSelect } from '@constructive-io/graphql-query';
+
+// Preset: just id + a few display fields
+const minimal = buildSelect(userTable, tables, { fieldSelection: 'minimal' });
+
+// Preset: all scalar fields (no relations)
+const allFields = buildSelect(userTable, tables, { fieldSelection: 'all' });
+
+// Preset: everything including relations
+const full = buildSelect(userTable, tables, { fieldSelection: 'full' });
+
+// Custom: pick specific fields + exclude some + include specific relations
+const custom = buildSelect(userTable, tables, {
+  fieldSelection: {
+    select: ['id', 'name', 'email'],
+    exclude: ['internalNotes'],
+    include: { posts: ['id', 'title'] },
+  },
+});
+```
+
+---
+
+## Relation Field Mapping (Aliases)
+
+Remap relation field names when the server-side name differs from what your consumer expects:
+
+```ts
+const query = buildSelect(userTable, tables, {
+  relationFieldMap: {
+    contact: 'contactByOwnerId',   // emits: contact: contactByOwnerId { ... }
+    internalNotes: null,           // omits this relation entirely
+  },
+});
+```
+
+---
+
+## Type-Safe Execution
+
+```ts
+import { createGraphQLClient } from '@constructive-io/graphql-query';
+
+const client = createGraphQLClient({
+  url: '/graphql',
+  headers: { Authorization: `Bearer ${token}` },
+});
+
+const { data, errors } = await client.execute(query, {
+  first: 10,
+  filter: { name: { includesInsensitive: 'search' } },
+});
+```
+
+---
+
+## Error Handling
+
+```ts
+import { DataError, parseGraphQLError, DataErrorType } from '@constructive-io/graphql-query';
+
+try {
+  const result = await client.execute(createQuery, { input: { user: { name: 'Alice' } } });
+  if (result.errors) {
+    const error = parseGraphQLError(result.errors[0]);
+    if (error.type === DataErrorType.UNIQUE_VIOLATION) {
+      console.log('Duplicate entry:', error.constraintName);
+    }
+  }
+} catch (err) {
+  if (err instanceof DataError) {
+    console.log(err.type, err.message);
+  }
+}
+```
+
+---
+
+## Server-Aware Naming
+
+All generators automatically use server-inferred names from introspection when available, falling back to local inflection conventions:
+
+```ts
+import {
+  toCamelCaseSingular,
+  toCamelCasePlural,
+  toCreateMutationName,
+  toPatchFieldName,
+  toFilterTypeName,
+} from '@constructive-io/graphql-query';
+
+// Uses table.query/table.inflection if available, falls back to convention
+toCamelCaseSingular('DeliveryZone', table);   // "deliveryZone" (from table.inflection.tableFieldName)
+toCamelCasePlural('DeliveryZone', table);     // "deliveryZones" (from table.query.all)
+toCreateMutationName('User', table);          // "createUser" (from table.query.create)
+toPatchFieldName('User', table);              // "userPatch" (from table.query.patchFieldName)
+toFilterTypeName('User', table);              // "UserFilter" (from table.inflection.filterType)
+```
+
+---
+
+## Architecture
+
+```
+GraphQL Schema (introspection or _meta)
+        |
+        v
+  inferTablesFromIntrospection()
+        |
+        v
+  CleanTable[] (normalized metadata with inflection + query names)
+        |
+        v
+  buildSelect / buildFindOne / buildCount / buildPostGraphileCreate / ...
+        |
+        v
+  gql-ast (AST node factories)
+        |
+        v
+  graphql print() -> query string
+        |
+        v
+  TypedDocumentString (type-safe wrapper)
+```
+
+### Package Relationship
+
+```
+@constructive-io/graphql-query  (this package — browser-safe core)
+        |
+        v
+@constructive-io/graphql-codegen  (Node.js CLI — depends on graphql-query)
+  + CLI entry points
+  + File output (writes .ts files to disk)
+  + Watch mode
+  + Database introspection
+  + React Query hook generation
+  + Babel codegen templates
+```
+
+---
+
+## API Reference
+
+### Generators
+
+| Function | Description |
+|---|---|
+| `buildSelect(table, allTables, options?)` | Build a paginated SELECT query with filters, sorting, field selection |
+| `buildFindOne(table, pkField?)` | Build a single-row query by primary key |
+| `buildCount(table)` | Build a count query with optional condition/filter |
+| `buildPostGraphileCreate(table, allTables, options?)` | Build a CREATE mutation |
+| `buildPostGraphileUpdate(table, allTables, options?)` | Build an UPDATE mutation |
+| `buildPostGraphileDelete(table, allTables, options?)` | Build a DELETE mutation |
+
+### Introspection
+
+| Function | Description |
+|---|---|
+| `inferTablesFromIntrospection(data, options?)` | Convert GraphQL introspection to `CleanTable[]` |
+| `transformSchemaToOperations(types, queryType, mutationType)` | Extract operations from schema types |
+| `SCHEMA_INTROSPECTION_QUERY` | Full introspection query string |
+
+### Client
+
+| Export | Description |
+|---|---|
+| `TypedDocumentString` | Type-safe GraphQL document wrapper (compatible with codegen client) |
+| `createGraphQLClient(options)` | Create a typed GraphQL client |
+| `execute(url, query, variables, options?)` | Execute a GraphQL query |
+| `DataError` | Structured error class with PG SQLSTATE classification |
+| `parseGraphQLError(error)` | Parse raw GraphQL error into `DataError` |
+
+### Naming Helpers
+
+| Function | Description |
+|---|---|
+| `toCamelCaseSingular(name, table?)` | Server-aware singular name |
+| `toCamelCasePlural(name, table?)` | Server-aware plural name |
+| `toCreateMutationName(name, table?)` | Create mutation operation name |
+| `toUpdateMutationName(name, table?)` | Update mutation operation name |
+| `toDeleteMutationName(name, table?)` | Delete mutation operation name |
+| `toPatchFieldName(name, table?)` | Patch field name in update input |
+| `toFilterTypeName(name, table?)` | Filter type name |
+| `toOrderByEnumValue(fieldName)` | Convert field name to OrderBy enum value |
+| `normalizeInflectionValue(value, fallback)` | Safe inflection value lookup |
+
+### Types
+
+| Type | Description |
+|---|---|
+| `CleanTable` | Normalized table metadata with fields, relations, inflection, query names |
+| `CleanField` | Field with type info, `isNotNull`, `hasDefault` |
+| `QueryOptions` | Options for `buildSelect` (pagination, filters, field selection, relation mapping) |
+| `MutationOptions` | Options for mutation builders |
+| `FieldSelection` | Field selection presets and custom configuration |
+| `ConnectionResult<T>` | Relay-style connection result type |
+| `Filter` | PostGraphile connection filter type |
+
 ---
 
 ## Education and Tutorials

package/ast.d.ts

@@ -1,10 +1,10 @@
-import { type DocumentNode, type FieldNode } from 'graphql';
-import type { ASTFunctionParams, FieldSelection, MutationASTParams } from './types';
-export declare const getAll: ({ queryName, operationName, query: _query, selection, }: ASTFunctionParams) => DocumentNode;
+import type { DocumentNode, FieldNode } from 'graphql';
+import type { ASTFunctionParams, MutationASTParams, QueryFieldSelection } from './types';
+export declare const getAll: ({ queryName, operationName, selection, }: ASTFunctionParams) => DocumentNode;
 export declare const getCount: ({ queryName, operationName, query, }: Omit<ASTFunctionParams, "selection">) => DocumentNode;
 export declare const getMany: ({ builder, queryName, operationName, query, selection, }: ASTFunctionParams) => DocumentNode;
 export declare const getOne: ({ queryName, operationName, query, selection, }: ASTFunctionParams) => DocumentNode;
 export declare const createOne: ({ mutationName, operationName, mutation, selection, }: MutationASTParams) => DocumentNode;
 export declare const patchOne: ({ mutationName, operationName, mutation, selection, }: MutationASTParams) => DocumentNode;
 export declare const deleteOne: ({ mutationName, operationName, mutation, }: Omit<MutationASTParams, "selection">) => DocumentNode;
-export declare function getSelections(selection?: FieldSelection[]): FieldNode[];
+export declare function getSelections(selection?: QueryFieldSelection[]): FieldNode[];

package/ast.js

@@ -37,7 +37,7 @@ exports.deleteOne = exports.patchOne = exports.createOne = exports.getOne = expo
 exports.getSelections = getSelections;
 const t = __importStar(require("gql-ast"));
 const graphql_1 = require("graphql");
-const inflection_1 = require("inflection");
+const inflekt_1 = require("inflekt");
 const custom_ast_1 = require("./custom-ast");
 const NON_MUTABLE_PROPS = ['createdAt', 'createdBy', 'updatedAt', 'updatedBy'];
 const objectToArray = (obj) => Object.keys(obj).map((k) => ({
@@ -85,7 +85,7 @@ const createGqlMutation = ({ operationName, mutationName, selectArgs, selections
         ],
     });
 };
-const getAll = ({ queryName, operationName, query: _query, selection, }) => {
+const getAll = ({ queryName, operationName, selection, }) => {
     const selections = getSelections(selection);
     const opSel = [
         t.field({
@@ -209,7 +209,10 @@ const getMany = ({ builder, queryName, operationName, query, selection, }) => {
         t.argument({ name: 'offset', value: t.variable({ name: 'offset' }) }),
         t.argument({ name: 'after', value: t.variable({ name: 'after' }) }),
         t.argument({ name: 'before', value: t.variable({ name: 'before' }) }),
-        t.argument({ name: 'condition', value: t.variable({ name: 'condition' }) }),
+        t.argument({
+            name: 'condition',
+            value: t.variable({ name: 'condition' }),
+        }),
         t.argument({ name: 'filter', value: t.variable({ name: 'filter' }) }),
         t.argument({ name: 'orderBy', value: t.variable({ name: 'orderBy' }) }),
     ];
@@ -318,7 +321,7 @@ const createOne = ({ mutationName, operationName, mutation, selection, }) => {
     if (!mutation.properties?.input?.properties) {
         throw new Error(`No input field for mutation: ${mutationName}`);
     }
-    const modelName = (0, inflection_1.camelize)([(0, inflection_1.singularize)(mutation.model)].join('_'), true);
+    const modelName = (0, inflekt_1.camelize)([(0, inflekt_1.singularize)(mutation.model)].join('_'), true);
     const inputProperties = mutation.properties.input
         .properties;
     const modelProperties = inputProperties[modelName];
@@ -364,7 +367,7 @@ const patchOne = ({ mutationName, operationName, mutation, selection, }) => {
     if (!mutation.properties?.input?.properties) {
         throw new Error(`No input field for mutation: ${mutationName}`);
     }
-    const modelName = (0, inflection_1.camelize)([(0, inflection_1.singularize)(mutation.model)].join('_'), true);
+    const modelName = (0, inflekt_1.camelize)([(0, inflekt_1.singularize)(mutation.model)].join('_'), true);
     const inputProperties = mutation.properties.input
         .properties;
     const patchProperties = inputProperties['patch'];
@@ -417,7 +420,7 @@ const deleteOne = ({ mutationName, operationName, mutation, }) => {
     if (!mutation.properties?.input?.properties) {
         throw new Error(`No input field for mutation: ${mutationName}`);
     }
-    const modelName = (0, inflection_1.camelize)([(0, inflection_1.singularize)(mutation.model)].join('_'), true);
+    const modelName = (0, inflekt_1.camelize)([(0, inflekt_1.singularize)(mutation.model)].join('_'), true);
     const inputProperties = mutation.properties.input
         .properties;
     const deleteAttrs = objectToArray(inputProperties);
@@ -463,9 +466,21 @@ const deleteOne = ({ mutationName, operationName, mutation, }) => {
 exports.deleteOne = deleteOne;
 function getSelections(selection = []) {
     const selectionAst = (field) => {
-        return typeof field === 'string'
-            ? t.field({ name: field })
-            : (0, custom_ast_1.getCustomAst)(field.fieldDefn) || t.field({ name: field.name });
+        if (typeof field === 'string') {
+            return t.field({ name: field });
+        }
+        // Check if fieldDefn has MetaField shape (has type.pgType)
+        const fieldDefn = field.fieldDefn;
+        if (fieldDefn &&
+            'type' in fieldDefn &&
+            fieldDefn.type &&
+            typeof fieldDefn.type === 'object' &&
+            'pgType' in fieldDefn.type) {
+            const customAst = (0, custom_ast_1.getCustomAst)(fieldDefn);
+            if (customAst)
+                return customAst;
+        }
+        return t.field({ name: field.name });
     };
     return selection
         .map((selectionDefn) => {