@stonecrop/graphql-client 0.10.16 → 0.11.1

package/dist/index.js

@@ -59,3 +59,4 @@ const methods = {
 };
 export { queries, typeDefs, methods };
 export { StonecropClient } from './client';
+export { buildRecordQuery, buildListQuery } from './query';

package/dist/query.js

@@ -0,0 +1,231 @@
+import { toPascalCase } from '@stonecrop/schema';
+import pluralize from 'pluralize';
+/**
+ * Default sync limit for many-cardinality links
+ */
+const DEFAULT_SYNC_LIMIT = 50;
+/**
+ * Field types that are not scalar queryable fields.
+ * Link fields are handled separately via sub-selections; relationship fields live in `links`.
+ */
+const RELATION_FIELDTYPES = new Set(['Link']);
+/**
+ * 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 function buildListQuery(meta, connectionFieldName, orderByTypeName, options) {
+    const fieldNames = queryableFieldNames(meta);
+    const connectionName = connectionFieldName(meta.tableName);
+    const orderByType = orderByTypeName(meta.tableName);
+    const varDecls = [];
+    const queryArgs = [];
+    if (options?.limit) {
+        varDecls.push('$limit: Int');
+        queryArgs.push(`first: $limit`);
+    }
+    if (options?.offset) {
+        varDecls.push('$offset: Int');
+        queryArgs.push(`offset: $offset`);
+    }
+    if (options?.orderBy) {
+        varDecls.push(`$orderBy: [${orderByType}!]`);
+        queryArgs.push(`orderBy: $orderBy`);
+    }
+    const varStr = varDecls.length > 0 ? `(${varDecls.join(', ')})` : '';
+    const argsStr = queryArgs.length > 0 ? `(${queryArgs.join(', ')})` : '';
+    return `
+		query GetRecords${varStr} {
+			${connectionName}${argsStr} {
+				nodes {
+				${fieldNames}
+				}
+			}
+		}
+	`;
+}
+/**
+ * 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 function buildRecordQuery(meta, recordFieldName, recordArgName, recordArgType, registry, options) {
+    const queryName = recordFieldName(meta.tableName);
+    const argName = recordArgName(meta.tableName);
+    const argType = recordArgType(meta.tableName);
+    const seen = new Set([meta.slug || meta.name]);
+    let selection = queryableFieldNames(meta);
+    if (options?.includeNested && meta.links && registry) {
+        const includeSet = Array.isArray(options.includeNested) ? new Set(options.includeNested) : null;
+        const nestedSelections = buildNestedSelections(meta.links, meta.tableName, includeSet, registry, seen, 0, options.maxDepth);
+        if (nestedSelections) {
+            selection += '\n      ' + nestedSelections;
+        }
+    }
+    return `
+		query GetRecord($${argName}: ${argType}) {
+			${queryName}(${argName}: $${argName}) {
+				${selection}
+			}
+		}
+	`;
+}
+/**
+ * Build nested sub-selections for descendant links
+ * @internal
+ */
+function buildNestedSelections(links, parentTableName, includeSet, registry, seen, depth, maxDepth) {
+    if (maxDepth !== undefined && depth >= maxDepth)
+        return '';
+    const selections = [];
+    for (const [fieldname, link] of Object.entries(links)) {
+        if (maxDepth !== undefined && depth >= maxDepth)
+            break;
+        // Check blockWorkflows first - if true, it overrides the includeSet filter
+        const effectiveBlockWorkflows = getEffectiveBlockWorkflows(link);
+        const linkBlockWorkflowsExplicitTrue = link.blockWorkflows === true;
+        // Check includeSet filter - but blockWorkflows: true bypasses this filter
+        if (includeSet && !includeSet.has(fieldname) && !linkBlockWorkflowsExplicitTrue) {
+            continue;
+        }
+        // Check fetch strategy - skip if not sync (unless blockWorkflows overrides)
+        const effectiveFetch = getEffectiveFetchStrategy(link);
+        const shouldSkip = effectiveBlockWorkflows === false || (effectiveFetch.method !== 'sync' && !linkBlockWorkflowsExplicitTrue);
+        if (shouldSkip) {
+            continue;
+        }
+        // TODO: When blockWorkflows is true with custom fetch, this currently forces the link into
+        // GraphQL queries, bypassing the custom handler. This is a workaround — custom handlers
+        // should be able to satisfy blockWorkflows on their own schedule. Future enhancement:
+        // - Option: Add SchemaValidator error for custom + blockWorkflows (blocking is impossible)
+        // - Option: Track pending custom fetches and only unblock when all custom handlers complete
+        // See: relationships.md Phase 6 "Open Question: blockWorkflows + custom fetch"
+        const targetMeta = registry.get(link.target);
+        if (!targetMeta)
+            continue;
+        const alreadySeen = seen.has(link.target);
+        if (alreadySeen) {
+            // Self-referential: include scalar fields only, don't modify seen
+        }
+        else {
+            seen.add(link.target);
+        }
+        const scalarFields = queryableFieldNames(targetMeta);
+        let nestedLinks = '';
+        if (!alreadySeen && targetMeta.links && targetMeta.tableName && (maxDepth === undefined || depth + 1 < maxDepth)) {
+            const innerSelections = buildNestedSelections(targetMeta.links, targetMeta.tableName, null, registry, seen, depth + 1, maxDepth);
+            if (innerSelections) {
+                nestedLinks = '\n          ' + innerSelections;
+            }
+            seen.delete(link.target);
+        }
+        const fullSelection = scalarFields + nestedLinks;
+        if (isManyCardinality(link.cardinality)) {
+            const connectionField = getConnectionFieldName(targetMeta, parentTableName);
+            const limitArg = effectiveFetch.method === 'sync' && effectiveFetch.limit !== undefined
+                ? `first: ${effectiveFetch.limit}`
+                : effectiveFetch.method === 'sync'
+                    ? `first: ${DEFAULT_SYNC_LIMIT}`
+                    : '';
+            selections.push(`
+			${connectionField}${limitArg ? `(${limitArg})` : ''} {
+				nodes {
+					${fullSelection}
+				}
+			}`);
+        }
+        else {
+            selections.push(`
+			${fieldname} {
+				${fullSelection}
+			}`);
+        }
+    }
+    return selections.join('');
+}
+/**
+ * Get the effective fetch strategy for a link, applying cardinality-based defaults.
+ *
+ * - `fetch` explicitly set → use it
+ * - `fetch` absent → apply defaults:
+ *   - `noneOrMany`/`atLeastOne` → `{ method: 'sync', limit: 50 }`
+ *   - `one`/`atMostOne` → `{ method: 'lazy' }`
+ *
+ * @internal
+ */
+function getEffectiveFetchStrategy(link) {
+    if (link.fetch !== undefined) {
+        return link.fetch;
+    }
+    // Apply cardinality-based defaults
+    if (isManyCardinality(link.cardinality)) {
+        return { method: 'sync', limit: DEFAULT_SYNC_LIMIT };
+    }
+    else {
+        return { method: 'lazy' };
+    }
+}
+/**
+ * Get the effective blockWorkflows value for a link.
+ * Returns true if blockWorkflows is explicitly true, or if it's absent and fetch method is 'sync'.
+ * @internal
+ */
+function getEffectiveBlockWorkflows(link) {
+    if (link.blockWorkflows !== undefined) {
+        return link.blockWorkflows;
+    }
+    const effectiveFetch = getEffectiveFetchStrategy(link);
+    return effectiveFetch.method === 'sync';
+}
+/**
+ * Get scalar field names for a doctype, excluding Link and Doctype fields
+ * @internal
+ */
+function queryableFieldNames(meta) {
+    return meta.fields
+        .filter(f => !RELATION_FIELDTYPES.has(f.fieldtype))
+        .map(f => f.fieldname)
+        .join('\n      ');
+}
+/**
+ * Check if a cardinality value represents a 1:many relationship
+ * @internal
+ */
+function isManyCardinality(cardinality) {
+    return cardinality === 'noneOrMany' || cardinality === 'atLeastOne';
+}
+/**
+ * Derive a PostGraphile connection field name from a target doctype and parent table name.
+ *
+ * PostGraphile convention: `{targetPlural}By{ParentTablePascal}Id`
+ * Example: recipe_task with parent recipe → `recipeTasksByRecipeId`
+ *
+ * @internal
+ */
+function getConnectionFieldName(targetMeta, parentTableName) {
+    const targetPlural = pluralize.plural(targetMeta.tableName);
+    const targetPascal = toPascalCase(targetPlural);
+    const fkPascal = toPascalCase(parentTableName) + 'Id';
+    return `${targetPascal}By${fkPascal}`;
+}

package/dist/src/client.d.ts

@@ -1,4 +1,4 @@
-import type { DataClient, DoctypeMeta, DoctypeContext, DoctypeRef } from '@stonecrop/schema';
+import type { DataClient, DoctypeMeta, DoctypeContext, DoctypeRef, GetRecordOptions, GetRecordsOptions } from '@stonecrop/schema';
 export type { DoctypeContext, DoctypeRef };
 /**
  * Options for creating a Stonecrop client
@@ -9,6 +9,8 @@ export 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>;
 }
 /**
  * Client for interacting with Stonecrop GraphQL API
@@ -18,6 +20,7 @@ export declare class StonecropClient implements DataClient {
     private endpoint;
     private headers;
     private metaCache;
+    private registry?;
     constructor(options: StonecropClientOptions);
     /**
      * Execute a GraphQL query
@@ -41,22 +44,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)

package/dist/src/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE5F,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;AAE1C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAsC;gBAE3C,OAAO,EAAE,sBAAsB;IAQ3C;;;;OAIG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBxF;;;;OAIG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5F;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAyDnE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAqD1C;;;;OAIG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAiB/F;;;;OAIG;IACG,UAAU,CACf,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,MAAM,CAAC,EAAE,MAAM,CAAA;KACf,GACC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAiCrC;;;;;OAKG;IACG,SAAS,CACd,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EAAE,GACd,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAuBrE;;OAEG;IACH,cAAc,IAAI,IAAI;CAGtB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,mBAAmB,CAAA;AAM1B,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;AAe1C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CACnC;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,QAAQ,CAAC,CAA0B;gBAE/B,OAAO,EAAE,sBAAsB;IAS3C;;;;OAIG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBxF;;;;OAIG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5F;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAuDnE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAmD1C;;;;;;;;;OASG;IACG,SAAS,CACd,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IA8C1C;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAiCtG;;;;;OAKG;IACG,SAAS,CACd,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EAAE,GACd,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAuBrE;;OAEG;IACH,cAAc,IAAI,IAAI;CAGtB"}

package/dist/src/index.d.ts

@@ -13,6 +13,7 @@ declare const methods: {
 };
 export { queries, typeDefs, methods };
 export { StonecropClient } from './client';
+export { buildRecordQuery, buildListQuery } from './query';
 export type { StonecropClientOptions, DoctypeContext } from './client';
 export type { Meta, MetaParser, MetaResponse } from './types';
 export type { DoctypeMeta } from '@stonecrop/schema';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,QAAQ,MAAM,cAAc,CAAA;AACnC,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,SAAS,CAAA;AAkC7D;;;;;;GAMG;AACH,QAAA,MAAM,OAAO;uBACa,MAAM,QAAQ,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC;CAgBrE,CAAA;AAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACtE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,QAAQ,MAAM,cAAc,CAAA;AACnC,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,SAAS,CAAA;AAkC7D;;;;;;GAMG;AACH,QAAA,MAAM,OAAO;uBACa,MAAM,QAAQ,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC;CAgBrE,CAAA;AAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC1D,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACtE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/src/query.d.ts

@@ -0,0 +1,35 @@
+import type { DoctypeMeta, GetRecordOptions, 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;
+//# sourceMappingURL=query.d.ts.map

package/dist/src/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EAIjB,MAAM,mBAAmB,CAAA;AAe1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,WAAW,EACjB,mBAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC1C,eAAe,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EACtC,OAAO,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAgCR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,WAAW,EACjB,eAAe,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EACtC,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EACpC,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EACpC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EACnC,OAAO,CAAC,EAAE,gBAAgB,GACxB,MAAM,CAkCR"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/graphql-client",
-  "version": "0.10.16",
+  "version": "0.11.1",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -33,14 +33,17 @@
     "decimal.js": "^10.6.0",
     "graphql": "^16.12.0",
     "graphql-request": "^7.4.0",
-    "@stonecrop/schema": "0.10.16",
-    "@stonecrop/stonecrop": "0.10.16"
+    "pluralize": "^8.0.0",
+    "@stonecrop/schema": "0.11.1",
+    "@stonecrop/stonecrop": "0.11.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@microsoft/api-documenter": "^7.28.2",
     "@miragejs/graphql": "^0.1.13",
     "@rushstack/heft": "^1.2.0",
+    "@types/node": "^22.19.5",
+    "@types/pluralize": "^0.0.33",
     "@vitejs/plugin-vue": "^6.0.3",
     "@vitest/coverage-istanbul": "^4.0.18",
     "eslint": "^9.39.2",

package/src/client.ts

@@ -1,7 +1,31 @@
-import type { DataClient, DoctypeMeta, DoctypeContext, DoctypeRef } from '@stonecrop/schema'
+import type {
+	DataClient,
+	DoctypeMeta,
+	DoctypeContext,
+	DoctypeRef,
+	GetRecordOptions,
+	GetRecordsOptions,
+} from '@stonecrop/schema'
+import { snakeToCamel, toPascalCase } from '@stonecrop/schema'
+import pluralize from 'pluralize'
+
+import { buildRecordQuery } from './query'
 
 export type { DoctypeContext, DoctypeRef }
 
+/**
+ * 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: string): string => {
+	const singularName = pluralize.singular(tableName)
+	return `${snakeToCamel(singularName)}ById`
+}
+const defaultRecordArgName = (_tableName: string): string => 'id'
+const defaultRecordArgType = (_tableName: string): string => 'UUID!'
+
 /**
  * Options for creating a Stonecrop client
  * @public
@@ -11,6 +35,8 @@ export 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>
 }
 
 /**
@@ -21,6 +47,7 @@ export class StonecropClient implements DataClient {
 	private endpoint: string
 	private headers: Record<string, string>
 	private metaCache: Map<string, DoctypeMeta> = new Map()
+	private registry?: Map<string, DoctypeMeta>
 
 	constructor(options: StonecropClientOptions) {
 		this.endpoint = options.endpoint
@@ -28,6 +55,7 @@ export class StonecropClient implements DataClient {
 			'Content-Type': 'application/json',
 			...options.headers,
 		}
+		this.registry = options.registry
 	}
 
 	/**
@@ -109,8 +137,6 @@ export class StonecropClient implements DataClient {
 						}
 					}
 					inherits
-					listDoctype
-					parentDoctype
 				}
 			}
 			`,
@@ -166,8 +192,6 @@ export class StonecropClient implements DataClient {
 						}
 					}
 					inherits
-					listDoctype
-					parentDoctype
 				}
 			}
 			`
@@ -181,11 +205,49 @@ export class StonecropClient implements DataClient {
 	}
 
 	/**
-	 * 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: DoctypeRef, recordId: string): Promise<Record<string, unknown> | null> {
+	async getRecord(
+		doctype: DoctypeRef,
+		recordId: string,
+		options?: GetRecordOptions
+	): Promise<Record<string, unknown> | null> {
+		// 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<Record<string, unknown>>(query, { id: recordId })
+
+			const queryName = defaultRecordFieldName(meta.tableName || doctype.name)
+			const record = result[queryName] as Record<string, unknown> | undefined
+
+			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<{
 			stonecropRecord: { data: Record<string, unknown> | null }
 		}>(
@@ -207,15 +269,7 @@ export class StonecropClient implements DataClient {
 	 * @param doctype - Doctype reference (name and optional slug)
 	 * @param options - Query options (filters, orderBy, limit, offset)
 	 */
-	async getRecords(
-		doctype: DoctypeRef,
-		options?: {
-			filters?: Record<string, unknown>
-			orderBy?: string
-			limit?: number
-			offset?: number
-		}
-	): Promise<Record<string, unknown>[]> {
+	async getRecords(doctype: DoctypeRef, options?: GetRecordsOptions): Promise<Record<string, unknown>[]> {
 		const result = await this.query<{
 			stonecropRecords: { data: Record<string, unknown>[] }
 		}>(
@@ -288,3 +342,57 @@ export class StonecropClient implements DataClient {
 		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: Record<string, unknown>,
+	meta: DoctypeMeta,
+	registry: Map<string, DoctypeMeta>
+): Record<string, unknown> {
+	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] as { nodes?: unknown[] } | undefined
+			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: DoctypeMeta, parentTableName: string): string {
+	const targetPlural = pluralize.plural(targetMeta.tableName || '')
+	const targetPascal = toPascalCase(targetPlural)
+	const fkPascal = toPascalCase(parentTableName) + 'Id'
+	return `${targetPascal}By${fkPascal}`
+}

package/src/index.ts

@@ -65,6 +65,7 @@ const methods = {
 
 export { queries, typeDefs, methods }
 export { StonecropClient } from './client'
+export { buildRecordQuery, buildListQuery } from './query'
 export type { StonecropClientOptions, DoctypeContext } from './client'
 export type { Meta, MetaParser, MetaResponse } from './types'
 export type { DoctypeMeta } from '@stonecrop/schema'