@stonecrop/graphql-client 0.20.0 → 0.21.0

package/dist/src/client.d.ts

@@ -15,8 +15,8 @@ export interface StonecropClientOptions {
 /**
  * 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.
+ * Acts as a transport layer for stonecropRecord/stonecropRecords/stonecropAction, and
+ * builds native PostGraphile queries for getNativeRecord/getNativeRecords.
  *
  * @public
  */
@@ -70,6 +70,37 @@ export declare class StonecropClient implements DataClient {
      * @param options - Query options (filters, orderBy, limit, offset)
      */
     getRecords(doctype: DoctypeRef, options?: GetRecordsOptions): Promise<GetRecordsResult>;
+    /**
+     * Get a single record by ID using PostGraphile's native query with relationship expansion.
+     *
+     * Unlike `getRecord()` which uses the `stonecropRecord` resolver returning a JSON blob,
+     * this method builds a native PostGraphile query that leverages the ORM's relationship
+     * resolution for efficient single-query fetches with JOINs.
+     *
+     * Link fields are returned as `{ id, displayText }` objects where `displayText` is
+     * resolved from the target doctype's `displayField`.
+     *
+     * @param doctype - Doctype reference (name and optional slug)
+     * @param recordId - Record ID to fetch
+     */
+    getNativeRecord(doctype: DoctypeRef, recordId: string): Promise<GetRecordResult>;
+    /**
+     * Get multiple records using PostGraphile's native query with relationship expansion.
+     *
+     * Unlike `getRecords()` which uses the `stonecropRecords` resolver returning JSON blobs,
+     * this method builds a native PostGraphile query that leverages the ORM's relationship
+     * resolution for efficient single-query fetches with JOINs.
+     *
+     * Link fields are returned as `{ id, displayText }` objects where `displayText` is
+     * resolved from the target doctype's `displayField`.
+     *
+     * @param doctype - Doctype reference (name and optional slug)
+     * @param options - Query options (limit, offset)
+     */
+    getNativeRecords(doctype: DoctypeRef, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<GetRecordsResult>;
     /**
      * 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,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAA;AAEjD;;;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;;;;;;;GAOG;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;;;;;;OAMG;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;IAoBxF;;;;;OAKG;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;IAenE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAU1C;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA4B5G;;;;;;;;OAQG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuC7F;;;;;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;IAYrE;;;;;OAKG;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,gBAAgB,EAChB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAU9C,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAA;AAEjD;;;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;;;;;;;GAOG;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;;;;;;OAMG;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;IAoBxF;;;;;OAKG;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;IAenE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAU1C;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA4B5G;;;;;;;;OAQG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuC7F;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAsBtF;;;;;;;;;;;;OAYG;IACG,gBAAgB,CACrB,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,gBAAgB,CAAC;IA8B5B;;;;;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;IAYrE;;;;;OAKG;IACH,cAAc,IAAI,IAAI;CAGtB"}

package/dist/src/client.js

@@ -1,9 +1,10 @@
 import { GET_META_QUERY, GET_ALL_META_QUERY, RUN_ACTION_MUTATION } from './queries';
+import { buildSingleRecordQuery, buildListRecordQuery, transformNativeRecord, doctypeToSingleQuery, doctypeToListQuery, } from './query-builder';
 /**
  * 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.
+ * Acts as a transport layer for stonecropRecord/stonecropRecords/stonecropAction, and
+ * builds native PostGraphile queries for getNativeRecord/getNativeRecords.
  *
  * @public
  */
@@ -147,6 +148,73 @@ export class StonecropClient {
         // through keeps "not asked for" and "asked for, and it is zero" distinguishable.
         return count == null ? { data, hasMore } : { data, hasMore, count };
     }
+    /**
+     * Get a single record by ID using PostGraphile's native query with relationship expansion.
+     *
+     * Unlike `getRecord()` which uses the `stonecropRecord` resolver returning a JSON blob,
+     * this method builds a native PostGraphile query that leverages the ORM's relationship
+     * resolution for efficient single-query fetches with JOINs.
+     *
+     * Link fields are returned as `{ id, displayText }` objects where `displayText` is
+     * resolved from the target doctype's `displayField`.
+     *
+     * @param doctype - Doctype reference (name and optional slug)
+     * @param recordId - Record ID to fetch
+     */
+    async getNativeRecord(doctype, recordId) {
+        const allMeta = await this.getAllMeta();
+        const meta = allMeta.find(m => m.name === doctype.name || m.slug === doctype.name);
+        if (!meta) {
+            return { record: null };
+        }
+        const { query, linkFields } = buildSingleRecordQuery(meta, { allMeta });
+        const queryName = doctypeToSingleQuery(meta.name);
+        const result = await this.query(query, { id: recordId });
+        const rawRecord = result[queryName];
+        if (!rawRecord) {
+            return { record: null };
+        }
+        const record = transformNativeRecord(rawRecord, linkFields, meta, allMeta);
+        return { record };
+    }
+    /**
+     * Get multiple records using PostGraphile's native query with relationship expansion.
+     *
+     * Unlike `getRecords()` which uses the `stonecropRecords` resolver returning JSON blobs,
+     * this method builds a native PostGraphile query that leverages the ORM's relationship
+     * resolution for efficient single-query fetches with JOINs.
+     *
+     * Link fields are returned as `{ id, displayText }` objects where `displayText` is
+     * resolved from the target doctype's `displayField`.
+     *
+     * @param doctype - Doctype reference (name and optional slug)
+     * @param options - Query options (limit, offset)
+     */
+    async getNativeRecords(doctype, options) {
+        const allMeta = await this.getAllMeta();
+        const meta = allMeta.find(m => m.name === doctype.name || m.slug === doctype.name);
+        if (!meta) {
+            return { data: [], hasMore: false };
+        }
+        const { query, linkFields } = buildListRecordQuery(meta, {
+            allMeta,
+            first: options?.limit,
+            offset: options?.offset,
+        });
+        const queryName = doctypeToListQuery(meta.name);
+        const variables = {};
+        if (options?.limit !== undefined)
+            variables.first = options.limit;
+        if (options?.offset !== undefined)
+            variables.offset = options.offset;
+        const result = await this.query(query, variables);
+        const nodes = result[queryName]?.nodes ?? [];
+        const data = nodes.map(node => transformNativeRecord(node, linkFields, meta, allMeta));
+        return {
+            data,
+            hasMore: nodes.length === options?.limit,
+        };
+    }
     /**
      * Execute a doctype action
      * @param doctype - Doctype reference (name and optional slug)

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
 export type { DoctypeMeta } from '@stonecrop/schema';
 export { StonecropClient, type StonecropClientOptions, type DoctypeContext } from './client';
 export type { GetRecordResult } from './types';
+export { buildSingleRecordQuery, buildListRecordQuery, transformNativeRecord, doctypeToSingleQuery, doctypeToListQuery, buildRelationshipName, doctypeToQueryName, type QueryBuilderOptions, type BuiltQuery, } from './query-builder';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAC5F,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAC5F,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,UAAU,GACf,MAAM,iBAAiB,CAAA"}

package/dist/src/index.js

@@ -1 +1,2 @@
 export { StonecropClient } from './client';
+export { buildSingleRecordQuery, buildListRecordQuery, transformNativeRecord, doctypeToSingleQuery, doctypeToListQuery, buildRelationshipName, doctypeToQueryName, } from './query-builder';

package/dist/src/queries.d.ts

@@ -9,7 +9,7 @@
  *
  * @public
  */
-export declare const GET_META_QUERY = "\n\tquery GetMeta($doctype: String!) {\n\t\tstonecropMeta(doctype: $doctype) {\n\t\t\tname\n\t\t\tslug\n\t\t\tfields {\n\t\t\t\tkind\n\t\t\t\tfieldname\n\t\t\t\tcomponent\n\t\t\t\tprimaryKey\n\t\t\t\tcomputed\n\t\t\t\tlanguage\n\t\t\t\tdoctype\n\t\t\t\tlabel\n\t\t\t\twidth\n\t\t\t\talign\n\t\t\t\tedit\n\t\t\t\tmask\n\t\t\t\tformat\n\t\t\t\tmode\n\t\t\t\toptions\n\t\t\t\trequired\n\t\t\t\treadOnly\n\t\t\t\thidden\n\t\t\t\tdefault\n\t\t\t\tvalidation\n\t\t\t\tcardinality\n\t\t\t\tsource\n\t\t\t}\n\t\t\tworkflow {\n\t\t\t\tstates\n\t\t\t\tactions {\n\t\t\t\t\tlabel\n\t\t\t\t\trequiredFields\n\t\t\t\t\tallowedStates\n\t\t\t\t\tnextState\n\t\t\t\t\tstateless\n\t\t\t\t\tselfTransition\n\t\t\t\t\tclientHandler\n\t\t\t\t}\n\t\t\t}\n\t\t\tinherits\n\t\t}\n\t}\n";
+export declare const GET_META_QUERY = "\n\tquery GetMeta($doctype: String!) {\n\t\tstonecropMeta(doctype: $doctype) {\n\t\t\tname\n\t\t\tslug\n\t\t\tdisplayField\n\t\t\tfields {\n\t\t\t\tkind\n\t\t\t\tfieldname\n\t\t\t\tcomponent\n\t\t\t\tprimaryKey\n\t\t\t\tcomputed\n\t\t\t\tlanguage\n\t\t\t\tdoctype\n\t\t\t\tlabel\n\t\t\t\twidth\n\t\t\t\talign\n\t\t\t\tedit\n\t\t\t\tmask\n\t\t\t\tformat\n\t\t\t\tmode\n\t\t\t\toptions\n\t\t\t\trequired\n\t\t\t\treadOnly\n\t\t\t\thidden\n\t\t\t\tdefault\n\t\t\t\tvalidation\n\t\t\t\tcardinality\n\t\t\t\tsource\n\t\t\t}\n\t\t\tworkflow {\n\t\t\t\tstates\n\t\t\t\tactions {\n\t\t\t\t\tlabel\n\t\t\t\t\trequiredFields\n\t\t\t\t\tallowedStates\n\t\t\t\t\tnextState\n\t\t\t\t\tstateless\n\t\t\t\t\tselfTransition\n\t\t\t\t\tclientHandler\n\t\t\t\t}\n\t\t\t}\n\t\t\tinherits\n\t\t}\n\t}\n";
 /**
  * Mutation document for dispatching a workflow action (the server-owned transition).
  * @public
@@ -19,5 +19,5 @@ export declare const RUN_ACTION_MUTATION = "\n\tmutation RunAction($doctype: Str
  * Query document for fetching all doctype metadata.
  * @public
  */
-export declare const GET_ALL_META_QUERY = "\n\tquery GetAllMeta {\n\t\tstonecropAllMeta {\n\t\t\tname\n\t\t\tslug\n\t\t\tfields {\n\t\t\t\tkind\n\t\t\t\tfieldname\n\t\t\t\tcomponent\n\t\t\t\tprimaryKey\n\t\t\t\tcomputed\n\t\t\t\tlanguage\n\t\t\t\tdoctype\n\t\t\t\tlabel\n\t\t\t\twidth\n\t\t\t\talign\n\t\t\t\tedit\n\t\t\t\tmask\n\t\t\t\tformat\n\t\t\t\tmode\n\t\t\t\toptions\n\t\t\t\trequired\n\t\t\t\treadOnly\n\t\t\t\thidden\n\t\t\t\tdefault\n\t\t\t\tvalidation\n\t\t\t\tcardinality\n\t\t\t\tsource\n\t\t\t}\n\t\t\tworkflow {\n\t\t\t\tstates\n\t\t\t\tactions {\n\t\t\t\t\tlabel\n\t\t\t\t\trequiredFields\n\t\t\t\t\tallowedStates\n\t\t\t\t\tnextState\n\t\t\t\t\tstateless\n\t\t\t\t\tselfTransition\n\t\t\t\t\tclientHandler\n\t\t\t\t}\n\t\t\t}\n\t\t\tinherits\n\t\t}\n\t}\n";
+export declare const GET_ALL_META_QUERY = "\n\tquery GetAllMeta {\n\t\tstonecropAllMeta {\n\t\t\tname\n\t\t\tslug\n\t\t\tdisplayField\n\t\t\tfields {\n\t\t\t\tkind\n\t\t\t\tfieldname\n\t\t\t\tcomponent\n\t\t\t\tprimaryKey\n\t\t\t\tcomputed\n\t\t\t\tlanguage\n\t\t\t\tdoctype\n\t\t\t\tlabel\n\t\t\t\twidth\n\t\t\t\talign\n\t\t\t\tedit\n\t\t\t\tmask\n\t\t\t\tformat\n\t\t\t\tmode\n\t\t\t\toptions\n\t\t\t\trequired\n\t\t\t\treadOnly\n\t\t\t\thidden\n\t\t\t\tdefault\n\t\t\t\tvalidation\n\t\t\t\tcardinality\n\t\t\t\tsource\n\t\t\t}\n\t\t\tworkflow {\n\t\t\t\tstates\n\t\t\t\tactions {\n\t\t\t\t\tlabel\n\t\t\t\t\trequiredFields\n\t\t\t\t\tallowedStates\n\t\t\t\t\tnextState\n\t\t\t\t\tstateless\n\t\t\t\t\tselfTransition\n\t\t\t\t\tclientHandler\n\t\t\t\t}\n\t\t\t}\n\t\t\tinherits\n\t\t}\n\t}\n";
 //# sourceMappingURL=queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,+vBA4C1B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,6MAQ/B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,+tBA4C9B,CAAA"}
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,mxBA6C1B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,6MAQ/B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mvBA6C9B,CAAA"}

package/dist/src/queries.js

@@ -14,6 +14,7 @@ export const GET_META_QUERY = `
 		stonecropMeta(doctype: $doctype) {
 			name
 			slug
+			displayField
 			fields {
 				kind
 				fieldname
@@ -76,6 +77,7 @@ export const GET_ALL_META_QUERY = `
 		stonecropAllMeta {
 			name
 			slug
+			displayField
 			fields {
 				kind
 				fieldname

package/dist/src/query-builder.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Query builder for constructing PostGraphile native queries with nested link selections.
+ *
+ * Instead of using the `stonecropRecord`/`stonecropRecords` resolvers which return JSON blobs,
+ * this module builds native PostGraphile queries that leverage the ORM's relationship resolution
+ * for efficient single-query fetches with JOINs.
+ *
+ * @example
+ * ```ts
+ * // Instead of:
+ * // stonecropRecord(doctype: "SalesOrder", id: "...") { data }
+ * // Which returns { customerId: "uuid" }
+ *
+ * // We generate:
+ * // salesOrderById(id: "...") { id, customerId, partyByCustomerId { id, partyName } }
+ * // Which returns { customerId: "uuid", partyByCustomerId: { id: "uuid", partyName: "Acme" } }
+ * ```
+ *
+ * @public
+ */
+import type { DoctypeMeta } from '@stonecrop/schema';
+/**
+ * Options for building queries
+ * @public
+ */
+export interface QueryBuilderOptions {
+    /**
+     * All available doctype metadata. Used to resolve target doctypes for link fields.
+     */
+    allMeta: DoctypeMeta[];
+    /**
+     * Maximum depth for nested link resolution. Defaults to 1 (immediate links only).
+     * Set to 0 to disable link expansion.
+     */
+    maxDepth?: number;
+}
+/**
+ * Result of building a native query
+ * @public
+ */
+export interface BuiltQuery {
+    /**
+     * The GraphQL query string
+     */
+    query: string;
+    /**
+     * Field names that are link fields with nested selections.
+     * The consumer can use this to know which fields will have relationship data.
+     */
+    linkFields: string[];
+}
+/**
+ * Convert a PascalCase doctype name to the camelCase query name PostGraphile uses.
+ *
+ * @example
+ * doctypeToQueryName('SalesOrder') // 'salesOrder'
+ * doctypeToQueryName('Party') // 'party'
+ * @public
+ */
+export declare function doctypeToQueryName(doctypeName: string): string;
+/**
+ * Convert a PascalCase doctype name to the PostGraphile single-record query name.
+ *
+ * @example
+ * doctypeToSingleQuery('SalesOrder') // 'salesOrderById'
+ * @public
+ */
+export declare function doctypeToSingleQuery(doctypeName: string): string;
+/**
+ * Convert a PascalCase doctype name to the PostGraphile list query name.
+ *
+ * @example
+ * doctypeToListQuery('SalesOrder') // 'allSalesOrders'
+ * doctypeToListQuery('Party') // 'allParties'
+ * @public
+ */
+export declare function doctypeToListQuery(doctypeName: string): string;
+/**
+ * Build the PostGraphile relationship field name for a foreign key.
+ *
+ * PostGraphile names relationships as `targetTypeByFkField` in camelCase.
+ *
+ * @example
+ * buildRelationshipName('Party', 'customerId') // 'partyByCustomerId'
+ * buildRelationshipName('Company', 'companyId') // 'companyByCompanyId'
+ * @public
+ */
+export declare function buildRelationshipName(targetDoctypeName: string, fkFieldname: string): string;
+/**
+ * Build a native PostGraphile query for fetching a single record by ID.
+ * @public
+ */
+export declare function buildSingleRecordQuery(meta: DoctypeMeta, options: QueryBuilderOptions): BuiltQuery;
+/**
+ * Build a native PostGraphile query for fetching multiple records.
+ * @public
+ */
+export declare function buildListRecordQuery(meta: DoctypeMeta, options: QueryBuilderOptions & {
+    first?: number;
+    offset?: number;
+    orderBy?: string;
+    condition?: Record<string, unknown>;
+}): BuiltQuery;
+/**
+ * Transform a record fetched via native PostGraphile query to the flat format
+ * expected by the Stonecrop client. Link fields become objects with `id` and `displayText`.
+ * @public
+ */
+export declare function transformNativeRecord(record: Record<string, unknown>, linkFields: string[], meta: DoctypeMeta, allMeta: DoctypeMeta[]): Record<string, unknown>;
+//# sourceMappingURL=query-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/query-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,mBAAmB,CAAA;AAGhE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,OAAO,EAAE,WAAW,EAAE,CAAA;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAI5F;AA4DD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB,GAAG,UAAU,CAUlG;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,mBAAmB,GAAG;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GACC,UAAU,CAiCZ;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,WAAW,EAAE,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmCzB"}

package/dist/src/query-builder.js

@@ -0,0 +1,199 @@
+/**
+ * Query builder for constructing PostGraphile native queries with nested link selections.
+ *
+ * Instead of using the `stonecropRecord`/`stonecropRecords` resolvers which return JSON blobs,
+ * this module builds native PostGraphile queries that leverage the ORM's relationship resolution
+ * for efficient single-query fetches with JOINs.
+ *
+ * @example
+ * ```ts
+ * // Instead of:
+ * // stonecropRecord(doctype: "SalesOrder", id: "...") { data }
+ * // Which returns { customerId: "uuid" }
+ *
+ * // We generate:
+ * // salesOrderById(id: "...") { id, customerId, partyByCustomerId { id, partyName } }
+ * // Which returns { customerId: "uuid", partyByCustomerId: { id: "uuid", partyName: "Acme" } }
+ * ```
+ *
+ * @public
+ */
+import { flattenFields, componentLinkExpansion } from '@stonecrop/schema';
+/**
+ * Convert a PascalCase doctype name to the camelCase query name PostGraphile uses.
+ *
+ * @example
+ * doctypeToQueryName('SalesOrder') // 'salesOrder'
+ * doctypeToQueryName('Party') // 'party'
+ * @public
+ */
+export function doctypeToQueryName(doctypeName) {
+    return doctypeName[0].toLowerCase() + doctypeName.slice(1);
+}
+/**
+ * Convert a PascalCase doctype name to the PostGraphile single-record query name.
+ *
+ * @example
+ * doctypeToSingleQuery('SalesOrder') // 'salesOrderById'
+ * @public
+ */
+export function doctypeToSingleQuery(doctypeName) {
+    return doctypeToQueryName(doctypeName) + 'ById';
+}
+/**
+ * Convert a PascalCase doctype name to the PostGraphile list query name.
+ *
+ * @example
+ * doctypeToListQuery('SalesOrder') // 'allSalesOrders'
+ * doctypeToListQuery('Party') // 'allParties'
+ * @public
+ */
+export function doctypeToListQuery(doctypeName) {
+    const name = doctypeName;
+    if (name.endsWith('y')) {
+        return 'all' + name.slice(0, -1) + 'ies';
+    }
+    return 'all' + name + 's';
+}
+/**
+ * Build the PostGraphile relationship field name for a foreign key.
+ *
+ * PostGraphile names relationships as `targetTypeByFkField` in camelCase.
+ *
+ * @example
+ * buildRelationshipName('Party', 'customerId') // 'partyByCustomerId'
+ * buildRelationshipName('Company', 'companyId') // 'companyByCompanyId'
+ * @public
+ */
+export function buildRelationshipName(targetDoctypeName, fkFieldname) {
+    const prefix = doctypeToQueryName(targetDoctypeName);
+    const suffix = fkFieldname[0].toUpperCase() + fkFieldname.slice(1);
+    return prefix + 'By' + suffix;
+}
+/**
+ * Resolve a doctype slug to its metadata.
+ */
+function resolveDoctype(slug, allMeta) {
+    return allMeta.find(m => m.slug === slug || m.name === slug);
+}
+function valueFieldNamed(fields, fieldname) {
+    for (const field of flattenFields(fields)) {
+        if (field.kind === 'field' && field.fieldname === fieldname) {
+            return field;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the field selection for a doctype, including nested selections for link fields.
+ */
+function buildFieldSelection(meta, allMeta, depth, maxDepth, linkFieldsOut) {
+    const flatFields = flattenFields(meta.fields);
+    const selections = [];
+    for (const field of flatFields) {
+        if (field.kind !== 'field')
+            continue;
+        const isLinkField = field.doctype && componentLinkExpansion(field.component) === 'inline';
+        if (isLinkField && depth < maxDepth) {
+            const targetMeta = resolveDoctype(field.doctype, allMeta);
+            if (targetMeta) {
+                const relationshipName = buildRelationshipName(targetMeta.name, field.fieldname);
+                const displayField = targetMeta.displayField;
+                if (displayField) {
+                    selections.push(field.fieldname);
+                    selections.push(`${relationshipName} { id ${displayField} }`);
+                    linkFieldsOut.push(field.fieldname);
+                }
+                else {
+                    selections.push(field.fieldname);
+                }
+            }
+            else {
+                selections.push(field.fieldname);
+            }
+        }
+        else {
+            selections.push(field.fieldname);
+        }
+    }
+    return selections.join(' ');
+}
+/**
+ * Build a native PostGraphile query for fetching a single record by ID.
+ * @public
+ */
+export function buildSingleRecordQuery(meta, options) {
+    const maxDepth = options.maxDepth ?? 1;
+    const linkFields = [];
+    const fieldSelection = buildFieldSelection(meta, options.allMeta, 0, maxDepth, linkFields);
+    const queryName = doctypeToSingleQuery(meta.name);
+    const query = `query($id: UUID!) { ${queryName}(id: $id) { ${fieldSelection} } }`;
+    return { query, linkFields };
+}
+/**
+ * Build a native PostGraphile query for fetching multiple records.
+ * @public
+ */
+export function buildListRecordQuery(meta, options) {
+    const maxDepth = options.maxDepth ?? 1;
+    const linkFields = [];
+    const fieldSelection = buildFieldSelection(meta, options.allMeta, 0, maxDepth, linkFields);
+    const queryName = doctypeToListQuery(meta.name);
+    const params = [];
+    const args = [];
+    if (options.first !== undefined) {
+        params.push('$first: Int');
+        args.push('first: $first');
+    }
+    if (options.offset !== undefined) {
+        params.push('$offset: Int');
+        args.push('offset: $offset');
+    }
+    if (options.orderBy) {
+        params.push('$orderBy: [SalesOrdersOrderBy!]');
+        args.push('orderBy: $orderBy');
+    }
+    if (options.condition) {
+        params.push('$condition: SalesOrderCondition');
+        args.push('condition: $condition');
+    }
+    const paramStr = params.length > 0 ? `(${params.join(', ')})` : '';
+    const argStr = args.length > 0 ? `(${args.join(', ')})` : '';
+    const query = `query${paramStr} { ${queryName}${argStr} { nodes { ${fieldSelection} } } }`;
+    return { query, linkFields };
+}
+/**
+ * Transform a record fetched via native PostGraphile query to the flat format
+ * expected by the Stonecrop client. Link fields become objects with `id` and `displayText`.
+ * @public
+ */
+export function transformNativeRecord(record, linkFields, meta, allMeta) {
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key.includes('By')) {
+            continue;
+        }
+        if (linkFields.includes(key)) {
+            const linkField = valueFieldNamed(meta.fields, key);
+            if (linkField?.doctype) {
+                const targetMeta = resolveDoctype(linkField.doctype, allMeta);
+                if (targetMeta?.displayField) {
+                    const relationshipName = buildRelationshipName(targetMeta.name, key);
+                    const nestedRaw = record[relationshipName];
+                    const displayText = nestedRaw !== null && nestedRaw !== undefined && typeof nestedRaw === 'object'
+                        ? Reflect.get(nestedRaw, targetMeta.displayField)
+                        : undefined;
+                    if (displayText !== undefined && displayText !== null && displayText !== '') {
+                        result[key] = {
+                            id: value,
+                            displayText,
+                        };
+                        continue;
+                    }
+                }
+            }
+        }
+        result[key] = value;
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/graphql-client",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "GraphQL client integration for Stonecrop",
   "bugs": {
     "url": "https://github.com/agritheory/stonecrop/issues"
@@ -30,7 +30,7 @@
     "src/*"
   ],
   "dependencies": {
-    "@stonecrop/schema": "0.20.0"
+    "@stonecrop/schema": "0.21.0"
   },
   "devDependencies": {
     "@microsoft/api-documenter": "^7.30.5",
@@ -48,8 +48,8 @@
     "vitest": "^4.1.5",
     "vue": "^3.5.33",
     "vue-router": "^5.0.6",
-    "stonecrop-rig": "0.7.0",
-    "@stonecrop/graphql-middleware": "0.20.0"
+    "@stonecrop/graphql-middleware": "0.21.0",
+    "stonecrop-rig": "0.7.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/client.ts

@@ -9,6 +9,13 @@ import type {
 } from '@stonecrop/schema'
 import type { GetRecordResult } from './types'
 import { GET_META_QUERY, GET_ALL_META_QUERY, RUN_ACTION_MUTATION } from './queries'
+import {
+	buildSingleRecordQuery,
+	buildListRecordQuery,
+	transformNativeRecord,
+	doctypeToSingleQuery,
+	doctypeToListQuery,
+} from './query-builder'
 
 export type { DoctypeContext, DoctypeRef }
 export type { GetRecordResult, GetRecordsResult }
@@ -27,8 +34,8 @@ export interface StonecropClientOptions {
 /**
  * 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.
+ * Acts as a transport layer for stonecropRecord/stonecropRecords/stonecropAction, and
+ * builds native PostGraphile queries for getNativeRecord/getNativeRecords.
  *
  * @public
  */
@@ -200,6 +207,87 @@ export class StonecropClient implements DataClient {
 		return count == null ? { data, hasMore } : { data, hasMore, count }
 	}
 
+	/**
+	 * Get a single record by ID using PostGraphile's native query with relationship expansion.
+	 *
+	 * Unlike `getRecord()` which uses the `stonecropRecord` resolver returning a JSON blob,
+	 * this method builds a native PostGraphile query that leverages the ORM's relationship
+	 * resolution for efficient single-query fetches with JOINs.
+	 *
+	 * Link fields are returned as `{ id, displayText }` objects where `displayText` is
+	 * resolved from the target doctype's `displayField`.
+	 *
+	 * @param doctype - Doctype reference (name and optional slug)
+	 * @param recordId - Record ID to fetch
+	 */
+	async getNativeRecord(doctype: DoctypeRef, recordId: string): Promise<GetRecordResult> {
+		const allMeta = await this.getAllMeta()
+		const meta = allMeta.find(m => m.name === doctype.name || m.slug === doctype.name)
+
+		if (!meta) {
+			return { record: null }
+		}
+
+		const { query, linkFields } = buildSingleRecordQuery(meta, { allMeta })
+		const queryName = doctypeToSingleQuery(meta.name)
+
+		const result = await this.query<Record<string, Record<string, unknown> | null>>(query, { id: recordId })
+
+		const rawRecord = result[queryName]
+		if (!rawRecord) {
+			return { record: null }
+		}
+
+		const record = transformNativeRecord(rawRecord, linkFields, meta, allMeta)
+		return { record }
+	}
+
+	/**
+	 * Get multiple records using PostGraphile's native query with relationship expansion.
+	 *
+	 * Unlike `getRecords()` which uses the `stonecropRecords` resolver returning JSON blobs,
+	 * this method builds a native PostGraphile query that leverages the ORM's relationship
+	 * resolution for efficient single-query fetches with JOINs.
+	 *
+	 * Link fields are returned as `{ id, displayText }` objects where `displayText` is
+	 * resolved from the target doctype's `displayField`.
+	 *
+	 * @param doctype - Doctype reference (name and optional slug)
+	 * @param options - Query options (limit, offset)
+	 */
+	async getNativeRecords(
+		doctype: DoctypeRef,
+		options?: { limit?: number; offset?: number }
+	): Promise<GetRecordsResult> {
+		const allMeta = await this.getAllMeta()
+		const meta = allMeta.find(m => m.name === doctype.name || m.slug === doctype.name)
+
+		if (!meta) {
+			return { data: [], hasMore: false }
+		}
+
+		const { query, linkFields } = buildListRecordQuery(meta, {
+			allMeta,
+			first: options?.limit,
+			offset: options?.offset,
+		})
+		const queryName = doctypeToListQuery(meta.name)
+
+		const variables: Record<string, unknown> = {}
+		if (options?.limit !== undefined) variables.first = options.limit
+		if (options?.offset !== undefined) variables.offset = options.offset
+
+		const result = await this.query<Record<string, { nodes: Record<string, unknown>[] }>>(query, variables)
+
+		const nodes = result[queryName]?.nodes ?? []
+		const data = nodes.map(node => transformNativeRecord(node, linkFields, meta, allMeta))
+
+		return {
+			data,
+			hasMore: nodes.length === options?.limit,
+		}
+	}
+
 	/**
 	 * Execute a doctype action
 	 * @param doctype - Doctype reference (name and optional slug)