Support custom scalars

Author: lo1tuma

eslint.config.js

@@ -49,7 +49,7 @@ export default [
         }
     },
     {
-        files: ['source/zod-graphql-query-builder/builder.ts'],
+        files: ['source/zod-graphql-query-builder/builder.ts', 'source/zod-graphql-query-builder/query-schema.ts'],
         // those rules crash for some reason, we should re-enable them as soon as they are not crashing anymore
         rules: {
             '@typescript-eslint/no-unnecessary-type-assertion': 'off',

source/zod-graphql-client/entry-point.ts

@@ -14,7 +14,12 @@ export function createGraphqlClient(clientOptions: GraphqlClientOptions): Graphq
 }
 
 export type { QuerySchema } from '../zod-graphql-query-builder/entry-point.js';
-export { enumValue, graphqlFieldOptions, variablePlaceholder } from '../zod-graphql-query-builder/entry-point.js';
+export {
+    customScalar,
+    enumValue,
+    graphqlFieldOptions,
+    variablePlaceholder
+} from '../zod-graphql-query-builder/entry-point.js';
 export type { GraphqlClient, GraphqlOverHttpOperationRequestPayload } from './client.js';
 export type { OperationErrorDetails } from './operation-error.js';
 export { GraphqlOperationError } from './operation-error.js';

source/zod-graphql-client/readme.md

@@ -191,6 +191,7 @@ Some functions from `@schema-hub/zod-graphql-query-builder` are re-exported for
 - `graphqlFieldOptions()`
 - `enumValue()`
 - `variablePlaceholder()`
+- `customScalar()`
 
 For more details, see the [`@schema-hub/zod-graphql-query-builder` documentation](../zod-graphql-query-builder/readme.md).
 

source/zod-graphql-query-builder/builder.test.ts

@@ -3,6 +3,7 @@ import { oneLine } from 'common-tags';
 import assert from 'node:assert';
 import { z } from 'zod';
 import { createQueryBuilder, type OperationOptions, type QueryBuilder } from './builder.js';
+import { createCustomScalarSchema } from './custom-scalar.js';
 import type { QuerySchema } from './query-schema.js';
 import { variablePlaceholder } from './values/variable-placeholder.js';
 
@@ -634,4 +635,31 @@ function checkQuery(testCase: QueryTestCase): TestFn {
             expectedQuery: `${operationType} { foo, bar }`
         })
     );
+
+    test(
+        `builds a ${operationType} with a custom scalar`,
+        checkQuery({
+            type: operationType,
+            buildSchema() {
+                return z
+                    .object({
+                        foo: createCustomScalarSchema(z.object({ bar: z.record(z.string()) }).strip())
+                    })
+                    .strict();
+            },
+            expectedQuery: `${operationType} { foo }`
+        })
+    );
+});
+
+test('a schema with custom scalar validates correctly', () => {
+    const schema = z
+        .object({
+            foo: createCustomScalarSchema(z.object({ bar: z.record(z.string()) }).strip())
+        })
+        .strict();
+
+    const result = schema.safeParse({ foo: { bar: 'bar' } });
+
+    assert.strictEqual(result.error?.issues[0]?.message, 'Expected object, received string');
 });

source/zod-graphql-query-builder/builder.ts

@@ -1,4 +1,5 @@
 import { z, ZodArray, ZodDiscriminatedUnion, type ZodLazy, type ZodTuple, ZodUndefined } from 'zod';
+import { isCustomScalarSchema } from './custom-scalar.js';
 import {
     type FieldSchema,
     type FieldShape,
@@ -178,12 +179,17 @@ export function createQueryBuilder(): QueryBuilder {
         };
     }
 
-    // eslint-disable-next-line max-statements -- no good idea how to refactor at the moment
+    // eslint-disable-next-line max-statements, complexity -- no good idea how to refactor at the moment
     function serializeFieldSchema(
         fieldName: string,
         fieldSchema: FieldSchema
     ): NormalizedGraphqlValue {
         const fieldSelector = serializedFieldSelector(fieldName, fieldSchema);
+
+        if (isCustomScalarSchema(fieldSchema)) {
+            return fieldSelector;
+        }
+
         const unwrappedSchema = unwrapFieldSchema(fieldSchema);
 
         if (unwrappedSchema instanceof ZodUndefined) {

source/zod-graphql-query-builder/custom-scalar.ts

@@ -0,0 +1,23 @@
+import { z, type ZodLazy, type ZodTypeAny } from 'zod';
+
+const customScalarSymbol: unique symbol = Symbol('custom-scalar');
+
+export type CustomScalarSchema<Schema extends ZodTypeAny> = ZodLazy<Schema> & {
+    [customScalarSymbol]: true;
+};
+
+export function isCustomScalarSchema(schema: ZodTypeAny): schema is CustomScalarSchema<ZodTypeAny> {
+    return Object.hasOwn(schema, customScalarSymbol);
+}
+
+export function createCustomScalarSchema<Schema extends ZodTypeAny>(
+    schema: Schema
+): CustomScalarSchema<Schema> {
+    const wrappedSchema = z.lazy(() => {
+        return schema;
+    }) as CustomScalarSchema<Schema>;
+
+    wrappedSchema[customScalarSymbol] = true;
+
+    return wrappedSchema;
+}

source/zod-graphql-query-builder/entry-point.ts

@@ -6,6 +6,7 @@ export const graphqlFieldOptions = builder.registerFieldOptions;
 export const buildGraphqlQuery = builder.buildQuery;
 export const buildGraphqlMutation = builder.buildMutation;
 
+export { createCustomScalarSchema as customScalar } from './custom-scalar.js';
 export { enumValue } from './values/enum.js';
 export { variablePlaceholder } from './values/variable-placeholder.js';
 

source/zod-graphql-query-builder/query-schema.ts

@@ -17,6 +17,7 @@ import {
     type ZodUndefined,
     type ZodUnion
 } from 'zod';
+import { type CustomScalarSchema, isCustomScalarSchema } from './custom-scalar.js';
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions,@typescript-eslint/no-empty-object-type -- generic type alias can’t be circular
 export interface StrictObjectSchema<Shape extends ZodRawShape>
@@ -44,6 +45,7 @@ export declare type FragmentUnionOptionSchema = ZodObject<
 // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style -- see https://github.com/microsoft/TypeScript/pull/57293
 export type FieldShape = { readonly [FieldName: string]: FieldSchema; };
 export type NonWrappedFieldSchema =
+    | CustomScalarSchema<ZodTypeAny>
     | PrimitiveSchema
     | StrictObjectSchema<FieldShape>
     | ZodArray<FieldSchema>
@@ -58,6 +60,10 @@ export type WrappedFieldSchema =
 export type FieldSchema = NonWrappedFieldSchema | WrappedFieldSchema;
 
 function isWrappedFieldSchema(schema: FieldSchema): schema is WrappedFieldSchema {
+    if (isCustomScalarSchema(schema)) {
+        return false;
+    }
+
     return schema instanceof ZodLazy || schema instanceof ZodEffects || schema instanceof ZodNullable;
 }
 

source/zod-graphql-query-builder/readme.md

@@ -129,6 +129,34 @@ const query = buildGraphqlQuery(mySchema);
 query { foo { ... on A { __typename, valueA }, ... on B { __typename, valueB } } }
 ```
 
+### Working with custom scalars
+
+**Input:**
+
+```typescript
+import { buildGraphqlQuery, customScalar } from '@schema-hub/zod-graphql-query-builder';
+import { z } from 'zod';
+
+const mySchema = z
+    .object({
+        foo: customScalar(
+            z
+                .object({
+                    bar: z.record(z.string())
+                })
+                .strip()
+        )
+    })
+    .strict();
+const query = buildGraphqlQuery(mySchema);
+```
+
+**Built query:**
+
+```graphql
+query { foo }
+```
+
 ## Mutations
 
 ### Basic Mutation