@vendure/dashboard 3.3.6-master-202506290242 → 3.3.6-master-202507010243

package/src/lib/framework/document-extension/extend-document.spec.ts

@@ -0,0 +1,549 @@
+import { graphql } from '@/graphql/graphql.js';
+import { print } from 'graphql';
+import { describe, expect, it } from 'vitest';
+
+import { extendDocument, gqlExtend } from './extend-document.js';
+
+/**
+ * Helper to strip indentation and normalize GraphQL SDL for comparison.
+ * Allows the expected result to be indented naturally in the code.
+ */
+function expectedSDL(str: string): string {
+    const lines = str.split('\n');
+    // Find the minimum indentation (excluding empty lines)
+    let minIndent = Infinity;
+    for (const line of lines) {
+        if (line.trim() === '') continue;
+        const indent = line.match(/^\s*/)?.[0].length || 0;
+        minIndent = Math.min(minIndent, indent);
+    }
+    // Remove the minimum indentation from all lines and normalize
+    return lines
+        .map(line => line.slice(minIndent).trim())
+        .filter(line => line.length > 0)
+        .join('\n');
+}
+
+describe('extendDocument', () => {
+    const baseDocument = graphql(`
+        query ProductVariantList($options: ProductVariantListOptions) {
+            productVariants(options: $options) {
+                items {
+                    id
+                    name
+                    sku
+                    price
+                }
+                totalItems
+            }
+        }
+    `);
+
+    it('should add new fields to existing query', () => {
+        const extended = extendDocument(
+            baseDocument,
+            `
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        reviewRating
+                        customField
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                            customField
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should merge nested selection sets', () => {
+        const extended = extendDocument(
+            baseDocument,
+            `
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        featuredAsset {
+                            id
+                            name
+                        }
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            featuredAsset {
+                                id
+                                name
+                            }
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should handle multiple operations', () => {
+        const multiOpDocument = graphql(`
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        id
+                        name
+                    }
+                    totalItems
+                }
+            }
+
+            query ProductVariantDetail($id: ID!) {
+                productVariant(id: $id) {
+                    id
+                    name
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            multiOpDocument,
+            `
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        sku
+                    }
+                }
+            }
+
+            query ProductVariantDetail($id: ID!) {
+                productVariant(id: $id) {
+                    sku
+                    price
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                        }
+                        totalItems
+                    }
+                }
+                query ProductVariantDetail($id: ID!) {
+                    productVariant(id: $id) {
+                        id
+                        name
+                        sku
+                        price
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should preserve fragments', () => {
+        const fragmentDocument = graphql(`
+            fragment ProductVariantFields on ProductVariant {
+                id
+                name
+            }
+
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        ...ProductVariantFields
+                    }
+                    totalItems
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            fragmentDocument,
+            `
+            fragment ProductVariantFields on ProductVariant {
+                sku
+            }
+
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        price
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            ...ProductVariantFields
+                            price
+                        }
+                        totalItems
+                    }
+                }
+                fragment ProductVariantFields on ProductVariant {
+                    id
+                    name
+                }
+                fragment ProductVariantFields on ProductVariant {
+                    sku
+                }
+            `),
+        );
+    });
+
+    it('should work with template string interpolation', () => {
+        const fieldName = 'reviewRating';
+        const extended = extendDocument(
+            baseDocument,
+            `
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        ${fieldName}
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should handle the gqlExtend utility function', () => {
+        const extender = gqlExtend`
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        reviewRating
+                    }
+                }
+            }
+        `;
+
+        const extended = extender(baseDocument);
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should not duplicate existing fields', () => {
+        const extended = extendDocument(
+            baseDocument,
+            `
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        id
+                        name
+                        reviewRating
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should merge nested selection sets for existing fields', () => {
+        const baseWithNested = graphql(`
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        id
+                        featuredAsset {
+                            id
+                        }
+                    }
+                    totalItems
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            baseWithNested,
+            `
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        featuredAsset {
+                            name
+                            preview
+                        }
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            featuredAsset {
+                                id
+                                name
+                                preview
+                            }
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should ignore different query names and merge by top-level field', () => {
+        const extended = extendDocument(
+            baseDocument,
+            `
+            query DifferentQueryName($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        reviewRating
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should ignore different variables and merge by top-level field', () => {
+        const extended = extendDocument(
+            baseDocument,
+            `
+            query ProductVariantList($differentOptions: ProductVariantListOptions) {
+                productVariants(options: $differentOptions) {
+                    items {
+                        reviewRating
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should throw error when top-level field differs', () => {
+        expect(() => {
+            extendDocument(
+                baseDocument,
+                `
+                query CompletelyDifferentQuery($id: ID!) {
+                    product(id: $id) {
+                        id
+                        name
+                        description
+                    }
+                }
+                `,
+            );
+        }).toThrow("The query extension must extend the 'productVariants' query. Got 'product' instead.");
+    });
+
+    it('should merge anonymous query by top-level field', () => {
+        const extended = extendDocument(
+            baseDocument,
+            `
+            {
+                productVariants {
+                    items {
+                        reviewRating
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should accept DocumentNode as extension parameter', () => {
+        const extensionDocument = graphql(`
+            query ProductVariantList($options: ProductVariantListOptions) {
+                productVariants(options: $options) {
+                    items {
+                        reviewRating
+                        customField
+                    }
+                }
+            }
+        `);
+
+        const extended = extendDocument(baseDocument, extensionDocument);
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductVariantList($options: ProductVariantListOptions) {
+                    productVariants(options: $options) {
+                        items {
+                            id
+                            name
+                            sku
+                            price
+                            reviewRating
+                            customField
+                        }
+                        totalItems
+                    }
+                }
+            `),
+        );
+    });
+});

package/src/lib/framework/document-extension/extend-document.ts

@@ -0,0 +1,159 @@
+import { Variables } from '@/graphql/api.js';
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import {
+    DefinitionNode,
+    DocumentNode,
+    FieldNode,
+    FragmentDefinitionNode,
+    Kind,
+    OperationDefinitionNode,
+    parse,
+    SelectionNode,
+    SelectionSetNode,
+} from 'graphql';
+
+/**
+ * Type-safe template string function for extending GraphQL documents
+ */
+export function extendDocument<T extends TypedDocumentNode, V extends Variables = Variables>(
+    defaultDocument: T,
+    template: TemplateStringsArray,
+    ...values: any[]
+): T;
+export function extendDocument<T extends TypedDocumentNode, V extends Variables = Variables>(
+    defaultDocument: T,
+    sdl: string | DocumentNode,
+): T;
+export function extendDocument<T extends TypedDocumentNode, V extends Variables = Variables>(
+    defaultDocument: T,
+    template: TemplateStringsArray | string | DocumentNode,
+    ...values: any[]
+): T {
+    // Handle template strings, regular strings, and DocumentNode
+    let extensionDocument: DocumentNode;
+    if (Array.isArray(template)) {
+        // Template string array
+        const sdl = (template as TemplateStringsArray).reduce((result, str, i) => {
+            return result + str + String(values[i] ?? '');
+        }, '');
+        extensionDocument = parse(sdl);
+    } else if (typeof template === 'string') {
+        // Regular string
+        extensionDocument = parse(template);
+    } else {
+        // DocumentNode
+        extensionDocument = template as DocumentNode;
+    }
+
+    // Merge the documents
+    const mergedDocument = mergeDocuments(defaultDocument, extensionDocument);
+
+    return mergedDocument as T;
+}
+
+/**
+ * Merges two GraphQL documents, adding fields from the extension to the base document
+ */
+function mergeDocuments(baseDocument: DocumentNode, extensionDocument: DocumentNode): DocumentNode {
+    const baseClone = JSON.parse(JSON.stringify(baseDocument)) as DocumentNode;
+
+    // Get all operation definitions from both documents
+    const baseOperations = baseClone.definitions.filter(isOperationDefinition);
+    const extensionOperations = extensionDocument.definitions.filter(isOperationDefinition);
+
+    // Get all fragment definitions from both documents
+    const baseFragments = baseClone.definitions.filter(isFragmentDefinition);
+    const extensionFragments = extensionDocument.definitions.filter(isFragmentDefinition);
+
+    // Merge fragments first (extensions can reference them)
+    const mergedFragments = [...baseFragments, ...extensionFragments];
+
+    // For each operation in the extension, find the corresponding base operation and merge
+    for (const extensionOp of extensionOperations) {
+        // Get the top-level field name from the extension operation
+        const extensionField = extensionOp.selectionSet.selections[0] as FieldNode;
+        if (!extensionField) {
+            throw new Error('Extension query must have at least one top-level field');
+        }
+
+        // Find a base operation that has the same top-level field
+        const baseOp = baseOperations.find(op => {
+            const baseField = op.selectionSet.selections[0] as FieldNode;
+            return baseField && baseField.name.value === extensionField.name.value;
+        });
+
+        if (!baseOp) {
+            const validQueryFields = baseOperations
+                .map(op => {
+                    const field = op.selectionSet.selections[0] as FieldNode;
+                    return field ? field.name.value : 'unknown';
+                })
+                .join(', ');
+            throw new Error(
+                `The query extension must extend the '${validQueryFields}' query. ` +
+                    `Got '${extensionField.name.value}' instead.`,
+            );
+        }
+
+        // Merge the selection sets of the matching top-level fields
+        const baseFieldNode = baseOp.selectionSet.selections[0] as FieldNode;
+        if (baseFieldNode.selectionSet && extensionField.selectionSet) {
+            mergeSelectionSets(baseFieldNode.selectionSet, extensionField.selectionSet);
+        }
+    }
+
+    // Update the document with merged definitions
+    (baseClone as any).definitions = [...baseOperations, ...mergedFragments];
+
+    return baseClone;
+}
+
+/**
+ * Merges two selection sets, adding fields from the extension to the base
+ */
+function mergeSelectionSets(
+    baseSelectionSet: SelectionSetNode,
+    extensionSelectionSet: SelectionSetNode,
+): void {
+    const baseFields = baseSelectionSet.selections.filter(isFieldNode);
+    const extensionFields = extensionSelectionSet.selections.filter(isFieldNode);
+
+    for (const extensionField of extensionFields) {
+        const existingField = baseFields.find(field => field.name.value === extensionField.name.value);
+
+        if (existingField) {
+            // Field already exists, merge their selection sets if both have them
+            if (existingField.selectionSet && extensionField.selectionSet) {
+                mergeSelectionSets(existingField.selectionSet, extensionField.selectionSet);
+            } else if (extensionField.selectionSet && !existingField.selectionSet) {
+                // Extension has a selection set but base doesn't, add it
+                (existingField as any).selectionSet = extensionField.selectionSet;
+            }
+        } else {
+            // Field doesn't exist, add it
+            (baseSelectionSet as any).selections.push(extensionField);
+        }
+    }
+}
+
+/**
+ * Type guards
+ */
+function isOperationDefinition(value: DefinitionNode): value is OperationDefinitionNode {
+    return value.kind === Kind.OPERATION_DEFINITION;
+}
+
+function isFragmentDefinition(value: DefinitionNode): value is FragmentDefinitionNode {
+    return value.kind === Kind.FRAGMENT_DEFINITION;
+}
+
+function isFieldNode(value: SelectionNode): value is FieldNode {
+    return value.kind === Kind.FIELD;
+}
+
+/**
+ * Utility function to create a template string tag for better DX
+ */
+export function gqlExtend(strings: TemplateStringsArray, ...values: any[]) {
+    return (defaultDocument: DocumentNode) => extendDocument(defaultDocument, strings, ...values);
+}