@stonecrop/graphql-client 0.10.16 → 0.11.0

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/dist/src/stonecrop-client.d.ts

@@ -0,0 +1,87 @@
+import type { DoctypeMeta as DoctypeMetaType } from '@stonecrop/schema';
+/**
+ * Route context for identifying what doctype/record we're working with
+ * @public
+ */
+export interface RouteContext {
+    /** Doctype name (e.g., 'Task', 'Customer') */
+    doctype: string;
+    /** Optional record ID for viewing/editing a specific record */
+    recordId?: string;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for creating a Stonecrop client
+ * @public
+ */
+export interface StonecropClientOptions {
+    /** GraphQL endpoint URL */
+    endpoint: string;
+    /** Additional HTTP headers to include in requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Client for interacting with Stonecrop GraphQL API
+ * @public
+ */
+export declare class StonecropClient {
+    private endpoint;
+    private headers;
+    private metaCache;
+    constructor(options: StonecropClientOptions);
+    /**
+     * Execute a GraphQL query
+     * @param query - GraphQL query string
+     * @param variables - Query variables
+     */
+    query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Execute a GraphQL mutation
+     * @param mutation - GraphQL mutation string
+     * @param variables - Mutation variables
+     */
+    mutate<T = unknown>(mutation: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get doctype metadata
+     * @param context - Route context containing doctype name
+     */
+    getMeta(context: RouteContext): Promise<DoctypeMetaType | null>;
+    /**
+     * Get all doctype metadata
+     */
+    getAllMeta(): Promise<DoctypeMetaType[]>;
+    /**
+     * Get a single record by ID
+     * @param doctype - Doctype metadata
+     * @param recordId - Record ID to fetch
+     */
+    getRecord(doctype: DoctypeMetaType, recordId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Get multiple records with optional filtering and pagination
+     * @param doctype - Doctype metadata
+     * @param options - Query options (filters, orderBy, limit, offset)
+     */
+    getRecords(doctype: DoctypeMetaType, options?: {
+        filters?: Record<string, unknown>;
+        orderBy?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a doctype action
+     * @param doctype - Doctype metadata
+     * @param action - Action name to execute
+     * @param args - Action arguments
+     */
+    runAction(doctype: DoctypeMetaType, action: string, args?: unknown[]): Promise<{
+        success: boolean;
+        data: unknown;
+        error: string | null;
+    }>;
+    /**
+     * Clear the cached doctype metadata
+     */
+    clearMetaCache(): void;
+}
+//# sourceMappingURL=stonecrop-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stonecrop-client.d.ts","sourceRoot":"","sources":["../../src/stonecrop-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEvE;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oCAAoC;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED;;;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,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAA0C;gBAE/C,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,YAAY,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IA0CrE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAsC9C;;;;OAIG;IACG,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAiBpG;;;;OAIG;IACG,UAAU,CACf,OAAO,EAAE,eAAe,EACxB,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,eAAe,EACxB,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/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.0"
+    }
+  ]
+}

package/dist/src/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * @file This file contains all the types that are used in the application.
+ * @public
+ */

package/dist/stonecrop-client.js

@@ -0,0 +1,191 @@
+/**
+ * Client for interacting with Stonecrop GraphQL API
+ * @public
+ */
+export class StonecropClient {
+    endpoint;
+    headers;
+    metaCache = new Map();
+    constructor(options) {
+        this.endpoint = options.endpoint;
+        this.headers = {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        };
+    }
+    /**
+     * Execute a GraphQL query
+     * @param query - GraphQL query string
+     * @param variables - Query variables
+     */
+    async query(query, variables) {
+        const response = await fetch(this.endpoint, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ query, variables }),
+        });
+        const json = (await response.json());
+        if (json.errors?.length) {
+            throw new Error(json.errors[0].message);
+        }
+        return json.data;
+    }
+    /**
+     * Execute a GraphQL mutation
+     * @param mutation - GraphQL mutation string
+     * @param variables - Mutation variables
+     */
+    async mutate(mutation, variables) {
+        return this.query(mutation, variables);
+    }
+    /**
+     * Get doctype metadata
+     * @param context - Route context containing doctype name
+     */
+    async getMeta(context) {
+        const cached = this.metaCache.get(context.doctype);
+        if (cached)
+            return cached;
+        const result = await this.query(`
+			query GetMeta($doctype: String!) {
+				stonecropMeta(doctype: $doctype) {
+					name
+					slug
+					tableName
+					fields {
+						fieldname
+						fieldtype
+						component
+						label
+						required
+						readOnly
+						options
+						precision
+						scale
+					}
+					workflow {
+						states
+						actions
+					}
+					inherits
+					listDoctype
+					parentDoctype
+				}
+			}
+			`, { doctype: context.doctype });
+        if (result.stonecropMeta) {
+            this.metaCache.set(context.doctype, result.stonecropMeta);
+        }
+        return result.stonecropMeta;
+    }
+    /**
+     * Get all doctype metadata
+     */
+    async getAllMeta() {
+        const result = await this.query(`
+			query GetAllMeta {
+				stonecropAllMeta {
+					name
+					slug
+					tableName
+					fields {
+						fieldname
+						fieldtype
+						component
+						label
+						required
+						readOnly
+						options
+						precision
+						scale
+					}
+					workflow {
+						states
+						actions
+					}
+					inherits
+					listDoctype
+					parentDoctype
+				}
+			}
+			`);
+        for (const meta of result.stonecropAllMeta) {
+            this.metaCache.set(meta.name, meta);
+        }
+        return result.stonecropAllMeta;
+    }
+    /**
+     * Get a single record by ID
+     * @param doctype - Doctype metadata
+     * @param recordId - Record ID to fetch
+     */
+    async getRecord(doctype, recordId) {
+        const result = await this.query(`
+			query GetRecord($doctype: String!, $id: String!) {
+				stonecropRecord(doctype: $doctype, id: $id) {
+					data
+				}
+			}
+			`, { doctype: doctype.name, id: recordId });
+        return result.stonecropRecord.data;
+    }
+    /**
+     * Get multiple records with optional filtering and pagination
+     * @param doctype - Doctype metadata
+     * @param options - Query options (filters, orderBy, limit, offset)
+     */
+    async getRecords(doctype, options) {
+        const result = await this.query(`
+			query GetRecords(
+				$doctype: String!
+				$filters: JSON
+				$orderBy: String
+				$limit: Int
+				$offset: Int
+			) {
+				stonecropRecords(
+					doctype: $doctype
+					filters: $filters
+					orderBy: $orderBy
+					limit: $limit
+					offset: $offset
+				) {
+					data
+					count
+				}
+			}
+			`, {
+            doctype: doctype.name,
+            ...options,
+        });
+        return result.stonecropRecords.data;
+    }
+    /**
+     * Execute a doctype action
+     * @param doctype - Doctype metadata
+     * @param action - Action name to execute
+     * @param args - Action arguments
+     */
+    async runAction(doctype, action, args) {
+        const result = await this.query(`
+			mutation RunAction($doctype: String!, $action: String!, $args: JSON) {
+				stonecropAction(doctype: $doctype, action: $action, args: $args) {
+					success
+					data
+					error
+				}
+			}
+			`, {
+            doctype: doctype.name,
+            action,
+            args,
+        });
+        return result.stonecropAction;
+    }
+    /**
+     * Clear the cached doctype metadata
+     */
+    clearMetaCache() {
+        this.metaCache.clear();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/graphql-client",
-  "version": "0.10.16",
+  "version": "0.11.0",
   "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.0",
+    "@stonecrop/stonecrop": "0.11.0"
   },
   "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'