@stonecrop/graphql-client 0.10.16 → 0.11.1

package/README.md

@@ -1,81 +1,154 @@
-# @stonecrop/graphql-client
-
-Client-side TypeScript interface to the Stonecrop GraphQL API. `StonecropClient` wraps the `stonecrop*` operations added to a PostGraphile schema by `@stonecrop/graphql-middleware`, handling HTTP transport, response unwrapping, and metadata caching so application code works with plain TypeScript objects rather than raw GraphQL.
-
-The client is intentionally thin — it has no knowledge of doctype definitions itself and fetches metadata from the server on demand, caching it in memory for the lifetime of the instance.
-
-While designed to pair with `@stonecrop/graphql-middleware`, the client works against any GraphQL endpoint that implements the `stonecrop*` operation conventions (`stonecropMeta`, `stonecropRecord`, `stonecropRecords`, `stonecropAction`). You can use your own server implementation as long as it conforms to those operation names and the expected response shapes. The `query` and `mutate` methods are also available for interacting with any other operations your schema exposes.
-
-## Installation
-
-```bash
-pnpm add @stonecrop/graphql-client
-```
-
-## Usage
-
-```typescript
-import { StonecropClient } from '@stonecrop/graphql-client'
-
-const client = new StonecropClient({
-  endpoint: 'http://localhost:4000/graphql',
-  headers: { Authorization: `Bearer ${token}` }, // optional
-})
-```
-
-### Metadata
-
-```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()
-```
-
-### Reading records
-
-```typescript
-// Single record by ID
-const order = await client.getRecord(meta, 'uuid-here')
-// → Record<string, unknown> | null
-
-// List with optional filtering and pagination
-const orders = await client.getRecords(meta, {
-  filters: { status: 'Draft' },
-  orderBy: 'createdAt',
-  limit: 20,
-  offset: 0,
-})
-// → Record<string, unknown>[]
-```
-
-### Actions
-
-```typescript
-// Dispatch any registered action
-const result = await client.runAction(meta, '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' } } }
-)
-```
-
-## References
-
-For full method signatures and parameter details, see [API Reference](./api.md).
+# @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.
+
+## Installation
+
+```bash
+pnpm add @stonecrop/graphql-client
+```
+
+## Usage
+
+```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 || {},
+  })
+}
+
+const client = new StonecropClient({
+  endpoint: 'http://localhost:4000/graphql',
+  headers: { Authorization: `Bearer ${token}` }, // optional
+  registry: metaMap, // for nested query support
+})
+
+// Wire up the client to the Stonecrop instance
+const stonecrop = getStonecrop()
+if (stonecrop) {
+  stonecrop.setClient(client)
+}
+```
+
+### Metadata
+
+```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()
+```
+
+### Reading Records
+
+```typescript
+import { GetRecordOptions, GetRecordsOptions } from '@stonecrop/schema'
+
+// Single record by ID (flat — scalar fields only)
+const order = await client.getRecord({ name: 'SalesOrder' }, 'uuid-here')
+
+// Single record with all nested descendant links
+const recipe = await client.getRecord({ name: 'Recipe' }, 'r1', {
+  includeNested: true,
+})
+
+// Single record with specific nested links only
+const recipe = await client.getRecord({ name: 'Recipe' }, 'r1', {
+  includeNested: ['tasks'],
+})
+
+// Single record with limited nesting depth
+const recipe = 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
+    }
+  }
+}
+```
+
+The response is merged so `result.tasks` is a flat array and `result.supersededBy` is a direct object.
+
+## References
+
+For full method signatures and parameter details, see [API Reference](./api.md).

package/dist/client.js

@@ -1,3 +1,18 @@
+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
  * @public
@@ -6,12 +21,14 @@ 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
@@ -83,8 +100,6 @@ export class StonecropClient {
 						}
 					}
 					inherits
-					listDoctype
-					parentDoctype
 				}
 			}
 			`, { doctype: context.doctype });
@@ -134,8 +149,6 @@ export class StonecropClient {
 						}
 					}
 					inherits
-					listDoctype
-					parentDoctype
 				}
 			}
 			`);
@@ -145,11 +158,33 @@ export class StonecropClient {
         return result.stonecropAllMeta;
     }
     /**
-     * Get a single record by ID
+     * 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.
+     *
      * @param doctype - Doctype reference (name and optional slug)
      * @param recordId - Record ID to fetch
+     * @param options - Query options (includeNested, maxDepth)
      */
-    async getRecord(doctype, recordId) {
+    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) {
@@ -219,3 +254,49 @@ export class StonecropClient {
         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

@@ -2,6 +2,43 @@ import type { DataClient } from '@stonecrop/schema';
 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 { 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 }
 
@@ -81,6 +118,7 @@ export declare class StonecropClient implements DataClient {
     private endpoint;
     private headers;
     private metaCache;
+    private registry?;
     constructor(options: StonecropClientOptions);
     /**
      * Execute a GraphQL query
@@ -104,22 +142,22 @@ export declare class StonecropClient implements DataClient {
      */
     getAllMeta(): Promise<DoctypeMeta[]>;
     /**
-     * Get a single record by ID
+     * 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.
+     *
      * @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): Promise<Record<string, unknown> | null>;
+    getRecord(doctype: DoctypeRef, recordId: string, options?: GetRecordOptions): Promise<Record<string, unknown> | null>;
     /**
      * Get multiple records with optional filtering and pagination
      * @param doctype - Doctype reference (name and optional slug)
      * @param options - Query options (filters, orderBy, limit, offset)
      */
-    getRecords(doctype: DoctypeRef, options?: {
-        filters?: Record<string, unknown>;
-        orderBy?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<Record<string, unknown>[]>;
+    getRecords(doctype: DoctypeRef, options?: GetRecordsOptions): Promise<Record<string, unknown>[]>;
     /**
      * Execute a doctype action
      * @param doctype - Doctype reference (name and optional slug)
@@ -146,6 +184,8 @@ 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>;
 }
 
 /**