@stonecrop/graphql-client 0.11.0 → 0.11.2

package/README.md

@@ -1,154 +1,59 @@
 # @stonecrop/graphql-client
 
-Client-side TypeScript implementation of the `DataClient` interface for Stonecrop's PostGraphile-based GraphQL API. `StonecropClient` handles HTTP transport, response unwrapping, query building, and metadata caching so application code works with plain TypeScript objects.
+Transport layer for Stonecrop GraphQL APIs. Handles HTTP communication, response parsing, and metadata caching.
 
-## Installation
+## Responsibilities
 
-```bash
-pnpm add @stonecrop/graphql-client
-```
+**Transport** — The client sends requests and parses responses. It doesn't construct queries.
 
-## Usage
+**Caching** — Metadata is cached in memory after first fetch.
 
-```typescript
-import { StonecropClient } from '@stonecrop/graphql-client'
-import { Registry, getStonecrop } from '@stonecrop/stonecrop'
-import type { DoctypeMeta } from '@stonecrop/schema'
-
-const registry = new Registry()
-// ... register doctypes ...
-
-// Build a DoctypeMeta map — StonecropClient expects DoctypeMeta, not Doctype instances
-const metaMap = new Map<string, DoctypeMeta>()
-for (const [slug, doctype] of Object.entries(registry.registry)) {
-  metaMap.set(slug, {
-    name: doctype.doctype,
-    slug,
-    tableName: slug.replace(/-/g, '_'),
-    fields: doctype.getSchemaArray(),
-    links: doctype.links || {},
-  })
-}
+**Contract** — The client expects the server to expose these operations:
 
-const client = new StonecropClient({
-  endpoint: 'http://localhost:4000/graphql',
-  headers: { Authorization: `Bearer ${token}` }, // optional
-  registry: metaMap, // for nested query support
-})
+| Operation | Arguments | Returns |
+|-----------|-----------|---------|
+| `stonecropRecord` | `doctype`, `id`, `options?` | `{ record, unknownLinks? }` |
+| `stonecropRecords` | `doctype`, `filters?`, `orderBy?`, `limit?`, `offset?` | `{ data[], count }` |
+| `stonecropMeta` | `doctype` | `DoctypeMeta` |
+| `stonecropAllMeta` | — | `DoctypeMeta[]` |
+| `stonecropAction` | `doctype`, `action`, `args?` | `{ success, data, error }` |
 
-// Wire up the client to the Stonecrop instance
-const stonecrop = getStonecrop()
-if (stonecrop) {
-  stonecrop.setClient(client)
-}
-```
+The client has no opinions about how the server implements these — naming conventions, query construction, nested data merging are all the server's concern.
 
-### Metadata
+## Assumptions
 
-```typescript
-// Fetch DoctypeMeta for a single doctype (cached after first call)
-const meta = await client.getMeta({ doctype: 'SalesOrder' })
-
-// Fetch all registered doctypes
-const allMeta = await client.getAllMeta()
-
-// Bust the in-memory cache
-client.clearMetaCache()
-```
+- All record operations accept a `doctype` string argument
+- `stonecropRecord` accepts `options: { includeNested?, maxDepth? }`
+- The server handles query building and field naming
 
-### Reading Records
+## Usage
 
 ```typescript
-import { GetRecordOptions, GetRecordsOptions } from '@stonecrop/schema'
-
-// Single record by ID (flat — scalar fields only)
-const order = await client.getRecord({ name: 'SalesOrder' }, 'uuid-here')
+import { StonecropClient } from '@stonecrop/graphql-client'
 
-// Single record with all nested descendant links
-const recipe = await client.getRecord({ name: 'Recipe' }, 'r1', {
-  includeNested: true,
+const client = new StonecropClient({
+  endpoint: 'http://localhost:4000/graphql',
+  headers: { Authorization: `Bearer ${token}` }, // optional
 })
 
-// Single record with specific nested links only
-const recipe = await client.getRecord({ name: 'Recipe' }, 'r1', {
-  includeNested: ['tasks'],
-})
+// Fetch a record
+const result = await client.getRecord({ name: 'Recipe' }, 'r1')
+result.record  // plain object with the record fields
+result.unknownLinks  // links requested but not found in schema
 
-// Single record with limited nesting depth
-const recipe = await client.getRecord({ name: 'Recipe' }, 'r1', {
+// Fetch with nested links
+const withNested = await client.getRecord({ name: 'Recipe' }, 'r1', {
   includeNested: true,
-  maxDepth: 2,
 })
 
-// List with optional filtering and pagination
-const orders = await client.getRecords(
-  { name: 'SalesOrder' },
-  {
-    filters: { status: 'Draft' },
-    orderBy: 'createdAt',
-    limit: 20,
-    offset: 0,
-  }
-)
-```
-
-### Actions
-
-```typescript
-// Dispatch any registered action
-const result = await client.runAction({ name: 'SalesOrder' }, 'submit', ['uuid-here'])
-// → { success: boolean; data: unknown; error: string | null }
-```
-
-### Raw GraphQL
-
-For queries or mutations not covered by the helpers:
-
-```typescript
-const data = await client.query<{ myTable: unknown[] }>(`query { myTable { id name } }`)
-
-const result = await client.mutate<{ createFoo: unknown }>(
-  `mutation CreateFoo($input: CreateFooInput!) { createFoo(input: $input) { foo { id } } }`,
-  { input: { foo: { name: 'bar' } } }
-)
-```
-
-### How Nested Queries Work
-
-When `includeNested` is set on `getRecord`:
-
-1. The client fetches doctype metadata (including `links`)
-2. Builds a GraphQL query with sub-selections for descendant links
-3. Connection fields (`noneOrMany`/`atLeastOne`) emit `{ nodes { ... } }` sub-selections
-4. Direct fields (`one`/`atMostOne`) emit object sub-selections
-5. Results with connection fields are merged to flat arrays
-
-Example query generated for a Recipe with `tasks` (noneOrMany) and `supersededBy` (atMostOne):
-
-```graphql
-query GetRecord($id: UUID!) {
-  recipeById(id: $id) {
-    id
-    name
-    status
-    RecipeTasksByRecipeId {
-      nodes {
-        id
-        name
-        description
-      }
-    }
-    supersededBy {
-      id
-      name
-      status
-    }
-  }
-}
+// Custom queries
+const custom = await client.query<{ myData: unknown[] }>(`query { myData { id } }`)
 ```
 
-The response is merged so `result.tasks` is a flat array and `result.supersededBy` is a direct object.
+## Data Shapes
 
-## References
+- `getRecord` returns `{ record: Record<string, unknown> | null, unknownLinks?: string[] }`. The `record` field contains the record's fields. Nested links are merged into the same object when `includeNested` is used.
+- `getRecords` returns `Record<string, unknown>[]` — an array of flat objects. Pagination metadata (`count`) is available in the server response but not currently exposed by the client.
+- `unknownLinks` will contain link names you requested that don't exist in the doctype schema — useful for catching typos.
 
-For full method signatures and parameter details, see [API Reference](./api.md).
+See [API Reference](./api.md) for full method signatures.

package/dist/client.js

@@ -1,39 +1,28 @@
-import { snakeToCamel, toPascalCase } from '@stonecrop/schema';
-import pluralize from 'pluralize';
-import { buildRecordQuery } from './query';
 /**
- * Default inflection functions for PostGraphile Amber preset conventions.
- * These match the middleware's default inflection so the client builds
- * queries the server can execute.
- * @internal
- */
-const defaultRecordFieldName = (tableName) => {
-    const singularName = pluralize.singular(tableName);
-    return `${snakeToCamel(singularName)}ById`;
-};
-const defaultRecordArgName = (_tableName) => 'id';
-const defaultRecordArgType = (_tableName) => 'UUID!';
-/**
- * Client for interacting with Stonecrop GraphQL API
+ * Client for interacting with Stonecrop GraphQL API.
+ *
+ * Acts as a transport layer — it passes requests to the middleware and returns
+ * merged results. Does not construct queries itself.
+ *
  * @public
  */
 export class StonecropClient {
     endpoint;
     headers;
     metaCache = new Map();
-    registry;
     constructor(options) {
         this.endpoint = options.endpoint;
         this.headers = {
             'Content-Type': 'application/json',
             ...options.headers,
         };
-        this.registry = options.registry;
     }
     /**
-     * Execute a GraphQL query
+     * Execute a GraphQL query against the configured endpoint.
+     *
      * @param query - GraphQL query string
      * @param variables - Query variables
+     * @throws Error if the GraphQL response contains errors
      */
     async query(query, variables) {
         const response = await fetch(this.endpoint, {
@@ -48,7 +37,8 @@ export class StonecropClient {
         return json.data;
     }
     /**
-     * Execute a GraphQL mutation
+     * Execute a GraphQL mutation. Delegates to query() since both use POST.
+     *
      * @param mutation - GraphQL mutation string
      * @param variables - Mutation variables
      */
@@ -160,42 +150,40 @@ export class StonecropClient {
     /**
      * Get a single record by ID.
      *
-     * When `includeNested` is set, builds a query with sub-selections for descendant
-     * links and returns ancestor + merged descendants. When omitted, returns flat scalar data.
+     * Routes through the stonecropRecord resolver which handles nested data
+     * fetching based on the includeNested option.
      *
      * @param doctype - Doctype reference (name and optional slug)
      * @param recordId - Record ID to fetch
      * @param options - Query options (includeNested, maxDepth)
      */
     async getRecord(doctype, recordId, options) {
-        // Nested path: build query with sub-selections
-        if (options?.includeNested) {
-            const meta = await this.getMeta({ doctype: doctype.name });
-            if (!meta)
-                return null;
-            const query = buildRecordQuery(meta, defaultRecordFieldName, defaultRecordArgName, defaultRecordArgType, this.registry, options);
-            const result = await this.query(query, { id: recordId });
-            const queryName = defaultRecordFieldName(meta.tableName || doctype.name);
-            const record = result[queryName];
-            if (!record)
-                return null;
-            if (meta.links && this.registry) {
-                return mergeNestedResults(record, meta, this.registry);
-            }
-            return record;
-        }
-        // Flat path: original query
-        const result = await this.query(`
-			query GetRecord($doctype: String!, $id: String!) {
-				stonecropRecord(doctype: $doctype, id: $id) {
+        const result = await this.query(`query GetRecord($doctype: String!, $id: String!, $options: JSON) {
+				stonecropRecord(doctype: $doctype, id: $id, options: $options) {
 					data
+					unknownLinks
 				}
-			}
-			`, { doctype: doctype.name, id: recordId });
-        return result.stonecropRecord.data;
+			}`, {
+            doctype: doctype.name,
+            id: recordId,
+            options: options?.includeNested
+                ? {
+                    includeNested: options.includeNested,
+                    maxDepth: options.maxDepth,
+                }
+                : undefined,
+        });
+        return {
+            record: result.stonecropRecord?.data ?? null,
+            unknownLinks: result.stonecropRecord?.unknownLinks,
+        };
     }
     /**
-     * Get multiple records with optional filtering and pagination
+     * Get multiple records with optional filtering and pagination.
+     *
+     * Returns flat arrays — the middleware merges connection format (\{ nodes: [...] \})
+     * into plain arrays before returning.
+     *
      * @param doctype - Doctype reference (name and optional slug)
      * @param options - Query options (filters, orderBy, limit, offset)
      */
@@ -248,55 +236,12 @@ export class StonecropClient {
         return result.stonecropAction;
     }
     /**
-     * Clear the cached doctype metadata
+     * Clear the cached doctype metadata.
+     *
+     * Call this if the server-side doctype schema has changed and you need
+     * to fetch fresh metadata (e.g., after adding a new field).
      */
     clearMetaCache() {
         this.metaCache.clear();
     }
 }
-/**
- * Merge nested connection results into flat arrays.
- *
- * For `noneOrMany`/`atLeastOne` links, the query returns `{ nodes: [...] }`.
- * This flattens them to just `[]` for easier consumption.
- *
- * For `one`/`atMostOne` links, the result is already flat.
- *
- * @internal
- */
-function mergeNestedResults(record, meta, registry) {
-    if (!meta.links)
-        return record;
-    const merged = { ...record };
-    for (const [fieldname, link] of Object.entries(meta.links)) {
-        const isMany = link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne';
-        if (isMany) {
-            // Connection result: { nodes: [...] } → flatten to []
-            const targetMeta = registry.get(link.target);
-            if (!targetMeta)
-                continue;
-            const connectionField = getConnectionFieldFromTarget(targetMeta, meta.tableName || '');
-            const connectionResult = merged[connectionField];
-            if (connectionResult?.nodes) {
-                merged[fieldname] = connectionResult.nodes;
-                delete merged[connectionField];
-            }
-            else {
-                merged[fieldname] = [];
-                delete merged[connectionField];
-            }
-        }
-        // 'one'/'atMostOne' links are already at the right fieldname
-    }
-    return merged;
-}
-/**
- * Derive the connection field name matching the query builder's convention.
- * @internal
- */
-function getConnectionFieldFromTarget(targetMeta, parentTableName) {
-    const targetPlural = pluralize.plural(targetMeta.tableName || '');
-    const targetPascal = toPascalCase(targetPlural);
-    const fkPascal = toPascalCase(parentTableName) + 'Id';
-    return `${targetPascal}By${fkPascal}`;
-}

package/dist/graphql-client.d.ts

@@ -3,131 +3,46 @@ import type { DoctypeContext } from '@stonecrop/schema';
 import { DoctypeMeta } from '@stonecrop/schema';
 import type { DoctypeRef } from '@stonecrop/schema';
 import type { GetRecordOptions } from '@stonecrop/schema';
+import type { GetRecordResult as GetRecordResult_2 } from '@stonecrop/schema';
 import type { GetRecordsOptions } from '@stonecrop/schema';
 
-/**
- * Build a GraphQL connection query to fetch a list of records.
- *
- * Only declares variables ($limit, $offset, $orderBy) that are actually used,
- * avoiding GraphQL spec violations from unused variable declarations.
- *
- * @param meta - Doctype metadata
- * @param connectionFieldName - Function to derive the connection field name from a table name
- * @param orderByTypeName - Function to derive the order-by type name from a table name
- * @param options - Query options (limit, offset, orderBy)
- * @returns GraphQL query string
- *
- * @public
- */
-export declare function buildListQuery(meta: DoctypeMeta, connectionFieldName: (t: string) => string, orderByTypeName: (t: string) => string, options?: GetRecordsOptions): string;
-
-/**
- * Build a GraphQL query string from doctype metadata.
- *
- * Generates scalar field selections. When `includeNested` is set,
- * recursively includes descendant link sub-selections derived from
- * the doctype's `links` object.
- *
- * @param meta - Doctype metadata to build the query from
- * @param recordFieldName - Function to derive the query field name from a table name
- * @param recordArgName - Function to derive the argument name from a table name
- * @param recordArgType - Function to derive the argument type from a table name
- * @param registry - Doctype registry for resolving link targets. Required when includeNested is set.
- * @param options - Query options (includeNested, maxDepth)
- * @returns GraphQL query string
- *
- * @public
- */
-export declare function buildRecordQuery(meta: DoctypeMeta, recordFieldName: (t: string) => string, recordArgName: (t: string) => string, recordArgType: (t: string) => string, registry?: Map<string, DoctypeMeta>, options?: GetRecordOptions): string;
-
 export { DoctypeContext }
 
 export { DoctypeMeta }
 
 /**
- * @file This file contains all the types that are used in the application.
- * @public
- */
-/**
- * The type of the response from the `getMeta` query.
+ * Result from getRecord - includes the record data and any unknown links requested
  * @public
  */
-export declare type Meta = {
-    variables: {
-        doctype: string;
-    };
-    response: {
-        getMeta: MetaResponse;
-    };
-};
-
-/**
- * The type of the response from the `getMeta` query.
- * @public
- */
-export declare type MetaParser = {
-    data: Meta['response'];
-};
-
-/**
- * The type of the response from the `getRecords` query.
- * @public
- */
-export declare type MetaResponse = {
-    id: string;
-    name: string;
-    workflow: {
-        id: string;
-        name: string;
-        machineId?: string;
-    };
-    schema: {
-        id: string;
-        label: string;
-    }[];
-    actions: {
-        id: string;
-        eventName: string;
-    }[];
-};
-
-/**
- * Get meta information for a doctype
- * @param doctype - The doctype to get meta information for
- * @param url - The URL to send the request to
- * @returns The meta information for the doctype
- * @public
- */
-export declare const methods: {
-    getMeta: (doctype: string, url?: string) => Promise<MetaResponse>;
-};
-
-/**
- * Queries for the GraphQL API.
- * @public
- */
-export declare const queries: {
-    getMeta: string;
-};
+export declare interface GetRecordResult extends GetRecordResult_2 {
+    /** Link names that were requested but don't exist in the doctype schema */
+    unknownLinks?: string[];
+}
 
 /**
- * Client for interacting with Stonecrop GraphQL API
+ * Client for interacting with Stonecrop GraphQL API.
+ *
+ * Acts as a transport layer — it passes requests to the middleware and returns
+ * merged results. Does not construct queries itself.
+ *
  * @public
  */
 export declare class StonecropClient implements DataClient {
     private endpoint;
     private headers;
     private metaCache;
-    private registry?;
     constructor(options: StonecropClientOptions);
     /**
-     * Execute a GraphQL query
+     * Execute a GraphQL query against the configured endpoint.
+     *
      * @param query - GraphQL query string
      * @param variables - Query variables
+     * @throws Error if the GraphQL response contains errors
      */
     query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
     /**
-     * Execute a GraphQL mutation
+     * Execute a GraphQL mutation. Delegates to query() since both use POST.
+     *
      * @param mutation - GraphQL mutation string
      * @param variables - Mutation variables
      */
@@ -144,16 +59,20 @@ export declare class StonecropClient implements DataClient {
     /**
      * Get a single record by ID.
      *
-     * When `includeNested` is set, builds a query with sub-selections for descendant
-     * links and returns ancestor + merged descendants. When omitted, returns flat scalar data.
+     * Routes through the stonecropRecord resolver which handles nested data
+     * fetching based on the includeNested option.
      *
      * @param doctype - Doctype reference (name and optional slug)
      * @param recordId - Record ID to fetch
      * @param options - Query options (includeNested, maxDepth)
      */
-    getRecord(doctype: DoctypeRef, recordId: string, options?: GetRecordOptions): Promise<Record<string, unknown> | null>;
+    getRecord(doctype: DoctypeRef, recordId: string, options?: GetRecordOptions): Promise<GetRecordResult>;
     /**
-     * Get multiple records with optional filtering and pagination
+     * Get multiple records with optional filtering and pagination.
+     *
+     * Returns flat arrays — the middleware merges connection format (\{ nodes: [...] \})
+     * into plain arrays before returning.
+     *
      * @param doctype - Doctype reference (name and optional slug)
      * @param options - Query options (filters, orderBy, limit, offset)
      */
@@ -170,7 +89,10 @@ export declare class StonecropClient implements DataClient {
         error: string | null;
     }>;
     /**
-     * Clear the cached doctype metadata
+     * Clear the cached doctype metadata.
+     *
+     * Call this if the server-side doctype schema has changed and you need
+     * to fetch fresh metadata (e.g., after adding a new field).
      */
     clearMetaCache(): void;
 }
@@ -184,14 +106,6 @@ export declare interface StonecropClientOptions {
     endpoint: string;
     /** Additional HTTP headers to include in requests */
     headers?: Record<string, string>;
-    /** Doctype registry for nested query building */
-    registry?: Map<string, DoctypeMeta>;
 }
 
-/**
- * This is the schema for the GraphQL API.
- * @public
- */
-export declare const typeDefs: string;
-
 export { }