@wundergraph/protographic 0.15.6 → 0.16.0

package/dist/src/proto-utils.js

@@ -0,0 +1,286 @@
+import { isListType, isNonNullType, isScalarType, isEnumType, getNamedType, } from 'graphql';
+import { isUnionMessageDefinition, SCALAR_TYPE_MAP, SCALAR_WRAPPER_TYPE_MAP, } from './types.js';
+import { unwrapNonNullType, isNestedListType, calculateNestingLevel } from './operations/list-type-utils.js';
+import { graphqlFieldToProtoField } from './naming-conventions.js';
+const SPACE_INDENT = '  '; // 2 spaces
+const LINE_COMMENT_PREFIX = '// ';
+const BLOCK_COMMENT_START = '/*';
+const BLOCK_COMMENT_END = '*/';
+/**
+ * Builds a message definition from a ProtoMessage object
+ * @param message - The ProtoMessage object
+ * @returns The message definition
+ */
+export function buildProtoMessage(includeComments, message) {
+    return buildProtoMessageWithIndent(includeComments, message, 0, new Set());
+}
+/**
+ * Builds a message definition from a ProtoMessage object with an indent level
+ * @param includeComments - Whether to include comments
+ * @param message - The ProtoMessage object
+ * @param indent - The indent level
+ * @returns The message lines
+ */
+function buildProtoMessageWithIndent(includeComments, message, indent, seenTypes) {
+    const messageLines = formatComment(includeComments, message.description, indent);
+    if (seenTypes.has(message.messageName)) {
+        throw new Error(`Duplicate nested message name: ${message.messageName}`);
+    }
+    seenTypes.add(message.messageName);
+    messageLines.push(indentContent(indent, `message ${message.messageName} {`));
+    // Build nested messages first - use a new Set for this level since
+    // protobuf allows the same message name at different nesting levels
+    if (message.nestedMessages && message.nestedMessages.length > 0) {
+        const nestedSeenTypes = new Set();
+        for (const nestedMessage of message.nestedMessages) {
+            messageLines.push(...buildProtoMessageWithIndent(includeComments, nestedMessage, indent + 1, nestedSeenTypes));
+        }
+    }
+    if (message.reservedNumbers && message.reservedNumbers.length > 0) {
+        messageLines.push(indentContent(indent + 1, `reserved ${message.reservedNumbers};`));
+    }
+    const compositeTypeFields = message.fields.filter((f) => f.compositeType);
+    for (const compositeTypeField of compositeTypeFields) {
+        messageLines.push(...buildCompositeTypeMessage(includeComments, compositeTypeField.compositeType, indent + 1, seenTypes));
+    }
+    for (const field of message.fields) {
+        if (field.description) {
+            messageLines.push(...formatComment(includeComments, field.description, indent + 1));
+        }
+        const repeated = field.isRepeated ? 'repeated ' : '';
+        messageLines.push(indentContent(indent + 1, `${repeated}${field.typeName} ${field.fieldName} = ${field.fieldNumber};`));
+    }
+    messageLines.push(indentContent(indent, '}'), '');
+    return messageLines;
+}
+/**
+ * Builds a composite type message
+ * @param includeComments - Whether to include comments
+ * @param compositeType - The composite type definition
+ * @param indent - The indent level
+ * @returns The message lines
+ * @example
+ * ```proto
+ * // A union type uses `value`
+ * message Animal {
+ *   oneof value {
+ *     Cat cat = 1;
+ *     Dog dog = 2;
+ *   }
+ * }
+ *
+ * // An interface type uses `instance`
+ * message Animal {
+ *   oneof instance {
+ *     Cat cat = 1;
+ *     Dog dog = 2;
+ *   }
+ * }
+ * ```
+ */
+function buildCompositeTypeMessage(includeComments, compositeType, indent, seenTypes) {
+    if (seenTypes.has(compositeType.typeName)) {
+        return [];
+    }
+    seenTypes.add(compositeType.typeName);
+    const lines = [];
+    if (includeComments && compositeType.description) {
+        lines.push(...formatComment(includeComments, compositeType.description, indent));
+    }
+    let oneOfName = '';
+    let compositeTypes = [];
+    if (isUnionMessageDefinition(compositeType)) {
+        oneOfName = 'value';
+        compositeTypes = compositeType.memberTypes;
+    }
+    else {
+        oneOfName = 'instance';
+        compositeTypes = compositeType.implementingTypes;
+    }
+    // Create a sorted copy to ensure deterministic field numbers without mutating the input.
+    compositeTypes = [...compositeTypes].sort((a, b) => a.localeCompare(b));
+    lines.push(indentContent(indent, `message ${compositeType.typeName} {`), indentContent(indent + 1, `oneof ${oneOfName} {`));
+    for (const [index, compositeType] of compositeTypes.entries()) {
+        lines.push(indentContent(indent + 2, `${compositeType} ${graphqlFieldToProtoField(compositeType)} = ${index + 1};`));
+    }
+    lines.push(indentContent(indent + 1, '}'));
+    lines.push(indentContent(indent, '}'));
+    return lines;
+}
+/**
+ * Convert a GraphQL description to Protocol Buffer comment
+ * @param description - The GraphQL description text
+ * @param indentLevel - The level of indentation for the comment (in number of 2-space blocks)
+ * @returns Array of comment lines with proper indentation
+ */
+export function formatComment(includeComments, description, indentLevel = 0) {
+    if (!includeComments || !description) {
+        return [];
+    }
+    // Sanitize description to prevent breaking block comments.
+    // Replace "/*" and "*/" with safe alternatives so they don't interfere
+    // with the BLOCK_COMMENT_START/BLOCK_COMMENT_END markers.
+    const sanitized = description.replace(/\/\*/g, '/ *').replace(/\*\//g, '* /');
+    // Use 2-space indentation consistently
+    const indent = SPACE_INDENT.repeat(indentLevel);
+    const lines = sanitized.trim().split('\n');
+    return lines.length === 1
+        ? [`${indent}${LINE_COMMENT_PREFIX}${lines[0]}`]
+        : [
+            `${indent}${BLOCK_COMMENT_START}`,
+            ...lines.map((line) => `${indent} * ${line}`),
+            `${indent} ${BLOCK_COMMENT_END}`,
+        ];
+}
+export function renderRPCMethod(includeComments, rpcMethod) {
+    const lines = [];
+    if (includeComments && rpcMethod.description) {
+        lines.push(...formatComment(includeComments, rpcMethod.description, 1));
+    }
+    lines.push(indentContent(1, `rpc ${rpcMethod.name}(${rpcMethod.request}) returns (${rpcMethod.response}) {}`));
+    return lines;
+}
+/**
+ * Map GraphQL type to Protocol Buffer type
+ *
+ * Determines the appropriate Protocol Buffer type for a given GraphQL type,
+ * including the use of wrapper types for nullable scalar fields to distinguish
+ * between unset fields and zero values.
+ *
+ * @param graphqlType - The GraphQL type to convert
+ * @param ignoreWrapperTypes - If true, do not use wrapper types for nullable scalar fields
+ * @returns The corresponding Protocol Buffer type name
+ */
+export function getProtoTypeFromGraphQL(includeComments, graphqlType, ignoreWrapperTypes = false) {
+    // Nullable lists need to be handled first, otherwise they will be treated as scalar types
+    if (isListType(graphqlType) || (isNonNullType(graphqlType) && isListType(graphqlType.ofType))) {
+        return handleListType(includeComments, graphqlType);
+    }
+    // For nullable scalar types, use wrapper types
+    if (isScalarType(graphqlType)) {
+        if (ignoreWrapperTypes) {
+            return { typeName: SCALAR_TYPE_MAP[graphqlType.name] || 'string', isRepeated: false, isWrapper: false };
+        }
+        return {
+            typeName: SCALAR_WRAPPER_TYPE_MAP[graphqlType.name] || 'google.protobuf.StringValue',
+            isRepeated: false,
+            isWrapper: true,
+        };
+    }
+    if (isEnumType(graphqlType)) {
+        return { typeName: graphqlType.name, isRepeated: false, isWrapper: false };
+    }
+    if (isNonNullType(graphqlType)) {
+        // For non-null scalar types, use the base type
+        if (isScalarType(graphqlType.ofType)) {
+            return { typeName: SCALAR_TYPE_MAP[graphqlType.ofType.name] || 'string', isRepeated: false, isWrapper: false };
+        }
+        return getProtoTypeFromGraphQL(includeComments, graphqlType.ofType);
+    }
+    // Named types (object, interface, union, input)
+    const namedType = graphqlType;
+    if (namedType && typeof namedType.name === 'string') {
+        return { typeName: namedType.name, isRepeated: false, isWrapper: false };
+    }
+    return { typeName: 'string', isRepeated: false, isWrapper: false }; // Default fallback
+}
+/**
+ * Converts GraphQL list types to appropriate Protocol Buffer representations.
+ *
+ * For non-nullable, single-level lists (e.g., [String!]!), generates simple repeated fields.
+ * For nullable lists (e.g., [String]) or nested lists (e.g., [[String]]), creates wrapper
+ * messages to properly handle nullability in proto3.
+ *
+ * Examples:
+ * - [String!]! → repeated string field_name = 1;
+ * - [String] → ListOfString field_name = 1; (with wrapper message)
+ * - [[String!]!]! → ListOfListOfString field_name = 1; (with nested wrapper messages)
+ * - [[String]] → ListOfListOfString field_name = 1; (with nested wrapper messages)
+ *
+ * @param graphqlType - The GraphQL list type to convert
+ * @returns ProtoType object containing the type name and whether it should be repeated
+ */
+export function handleListType(includeComments, graphqlType) {
+    const listType = unwrapNonNullType(graphqlType);
+    const isNullableList = !isNonNullType(graphqlType);
+    const isNested = isNestedListType(listType);
+    // Simple non-nullable lists can use repeated fields directly
+    if (!isNullableList && !isNested) {
+        return { ...getProtoTypeFromGraphQL(includeComments, getNamedType(listType), true), isRepeated: true };
+    }
+    // Nullable or nested lists need wrapper messages
+    const baseType = getNamedType(listType);
+    const nestingLevel = calculateNestingLevel(listType);
+    // For nested lists, always use full nesting level to preserve inner list nullability
+    // For single-level nullable lists, use nesting level 1
+    const wrapperNestingLevel = isNested ? nestingLevel : 1;
+    // Generate all required wrapper messages
+    const wrapperName = listNameByNestingLevel(wrapperNestingLevel, baseType);
+    // For nested lists, never use repeated at field level to preserve nullability
+    return {
+        typeName: wrapperName,
+        isWrapper: false,
+        isRepeated: false,
+        listWrapper: { baseType, nestingLevel: wrapperNestingLevel },
+    };
+}
+export function listNameByNestingLevel(nestingLevel, baseType) {
+    return `${'ListOf'.repeat(nestingLevel)}${baseType.name}`;
+}
+/**
+ * Creates wrapper messages for nullable or nested GraphQL lists.
+ *
+ * Generates Protocol Buffer message definitions to handle list nullability and nesting.
+ * The wrapper messages are stored and later included in the final proto output.
+ *
+ * For level 1: Creates simple wrapper like:
+ *   message ListOfString {
+ *     repeated string items = 1;
+ *   }
+ *
+ * For level > 1: Creates nested wrapper structures like:
+ *   message ListOfListOfString {
+ *     message List {
+ *       repeated ListOfString items = 1;
+ *     }
+ *     List list = 1;
+ *   }
+ *
+ * @param includeComments - Whether to include descriptive comments in the output
+ * @param level - The nesting level (1 for simple wrapper, >1 for nested structures)
+ * @param baseType - The GraphQL base type being wrapped (e.g., String, User, etc.)
+ * @returns The generated wrapper message definition as a proto message string.
+ *          Constructs a `wrapperName` (e.g., "ListOfString", "ListOfListOfUser") and
+ *          uses `buildWrapperMessage(includeComments, wrapperName, level, baseType)`
+ *          to render the full message text.
+ */
+export function createNestedListWrapper(includeComments, level, baseType) {
+    const wrapperName = `${'ListOf'.repeat(level)}${baseType.name}`;
+    return buildWrapperMessage(includeComments, wrapperName, level, baseType).join('\n');
+}
+/**
+ * Builds the message lines for a wrapper message
+ */
+function buildWrapperMessage(includeComments, wrapperName, level, baseType) {
+    const lines = [];
+    // Add comment if enabled
+    if (includeComments) {
+        lines.push(...formatComment(includeComments, `Wrapper message for a list of ${baseType.name}.`, 0));
+    }
+    lines.push(`message ${wrapperName} {`);
+    let innerWrapperName = '';
+    innerWrapperName =
+        level > 1
+            ? `${'ListOf'.repeat(level - 1)}${baseType.name}`
+            : getProtoTypeFromGraphQL(includeComments, baseType, true).typeName;
+    lines.push(indentContent(1, `message List {`), indentContent(2, `repeated ${innerWrapperName} items = 1;`), indentContent(1, `}`), indentContent(1, `List list = 1;`), `}`);
+    return lines;
+}
+/**
+ * Indents the content by the given indent level
+ * @param indentLevel - The indent level
+ * @param content - The content to indent
+ * @returns The indented content
+ */
+const indentContent = (indentLevel, content) => SPACE_INDENT.repeat(indentLevel) + content;
+//# sourceMappingURL=proto-utils.js.map

package/dist/src/proto-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proto-utils.js","sourceRoot":"","sources":["../../src/proto-utils.ts"],"names":[],"mappings":"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"}

package/dist/src/required-fields-visitor.d.ts

@@ -0,0 +1,230 @@
+import { GraphQLField, GraphQLObjectType, GraphQLSchema } from 'graphql';
+import { FieldMapping } from '@wundergraph/cosmo-connect/dist/node/v1/node_pb';
+import { ProtoMessage, RPCMethod } from './types.js';
+/**
+ * A record mapping key directive strings to their corresponding RequiredFieldMapping.
+ * Each entity can have multiple @key directives, and each key needs its own RPC mapping.
+ */
+type RequiredFieldMappings = Record<string, RequiredFieldMapping>;
+/**
+ * Represents the mapping configuration for a single @requires field.
+ * This mapping is keyed by the @key directive fields string.
+ */
+export type RequiredFieldMapping = {
+    /** The RPC method configuration for resolving this required field */
+    rpc?: RPCMethod;
+    /** The field mapping between GraphQL and proto field names */
+    requiredFieldMapping?: FieldMapping;
+};
+/**
+ * Generates protobuf messages and RPC methods for @requires directive field sets.
+ *
+ * This visitor processes the field set defined in a @requires directive and generates:
+ * - RPC method definitions for fetching required fields
+ * - Request/response message definitions
+ * - Field mappings between GraphQL and protobuf
+ *
+ * The visitor handles each @key directive on the entity separately, creating
+ * distinct RPC methods for each key since required fields may need to be
+ * fetched using different entity keys.
+ *
+ * @example
+ * ```typescript
+ * const visitor = new RequiredFieldsVisitor(
+ *   schema,
+ *   ProductType,
+ *   weightField,
+ *   'dimensions { width height }'
+ * );
+ * visitor.visit();
+ *
+ * const messages = visitor.getMessageDefinitions();
+ * const rpcs = visitor.getRPCMethods();
+ * const mappings = visitor.getMapping();
+ * ```
+ */
+export declare class RequiredFieldsVisitor {
+    private readonly schema;
+    private readonly objectType;
+    private readonly requiredField;
+    private readonly visitor;
+    private readonly fieldSetDoc;
+    private ancestors;
+    private currentType;
+    private keyDirectives;
+    private currentKeyFieldsString;
+    /** Collected RPC methods for the required fields */
+    private rpcMethods;
+    /** All generated protobuf message definitions */
+    private messageDefinitions;
+    /** The current required field message being built */
+    private requiredFieldMessage;
+    /** The current message context during traversal */
+    private current;
+    /** Stack for tracking nested message contexts */
+    private stack;
+    private currentInlineFragment?;
+    private inlineFragmentStack;
+    /** Mappings keyed by @key directive fields string */
+    private mapping;
+    /**
+     * Creates a new RequiredFieldsVisitor.
+     *
+     * @param schema - The GraphQL schema containing type definitions
+     * @param objectType - The entity type that has the @requires directive
+     * @param requiredField - The field with the @requires directive
+     * @param fieldSet - The field set string from the @requires directive (e.g., "dimensions { width height }")
+     * @param options - Optional configuration options
+     * @throws Error if the object type is not an entity (has no @key directive)
+     */
+    constructor(schema: GraphQLSchema, objectType: GraphQLObjectType, requiredField: GraphQLField<any, any, any>, fieldSet: string);
+    /**
+     * Executes the visitor, processing the field set for each @key directive.
+     * Creates separate RPC methods and mappings for each entity key.
+     */
+    visit(): void;
+    /**
+     * Normalizes the parsed field set operation by rewriting abstract selections.
+     * This ensures consistent handling of interface and union type selections.
+     */
+    private normalizeSelectionSet;
+    /**
+     * Returns all generated protobuf message definitions.
+     *
+     * @returns Array of ProtoMessage definitions for request, response, and nested messages
+     */
+    getMessageDefinitions(): ProtoMessage[];
+    /**
+     * Returns the generated RPC method definitions.
+     *
+     * @returns Array of RPCMethod definitions for fetching required fields
+     */
+    getRPCMethods(): RPCMethod[];
+    /**
+     * Returns the field mappings keyed by @key directive fields string.
+     *
+     * @returns Record mapping key strings to their RequiredFieldMapping configurations
+     */
+    getMapping(): RequiredFieldMappings;
+    /**
+     * Resolves all @key directives from the object type.
+     * Each key directive will result in a separate RPC method.
+     *
+     * @throws Error if the object type has no @key directives
+     */
+    private resolveKeyDirectives;
+    /**
+     * Creates the AST visitor configuration for traversing the field set document.
+     *
+     * @returns An ASTVisitor with handlers for Document, Field, InlineFragment, and SelectionSet nodes
+     */
+    private createASTVisitor;
+    /**
+     * Handles leaving the document node.
+     * Finalizes the required field message and generates type field mappings.
+     */
+    private onLeaveDocument;
+    /**
+     * Handles entering the document node.
+     * Creates the RPC method definition and all request/response message structures
+     * for fetching the required fields.
+     *
+     * @param node - The document node being entered
+     */
+    private onEnterDocument;
+    /**
+     * Handles entering a field node during traversal.
+     * Adds the field to the current proto message with appropriate type mapping.
+     *
+     * @param ctx - The visit context containing the field node and its ancestors
+     * @throws Error if the field definition is not found on the current type
+     */
+    private onEnterField;
+    /**
+     * Handles entering an inline fragment node.
+     * Pushes the current inline fragment onto the stack for nested fragment handling.
+     *
+     * @param ctx - The visit context containing the inline fragment node
+     */
+    private onEnterInlineFragment;
+    /**
+     * Handles leaving an inline fragment node.
+     * Records union member types when processing union type fragments.
+     *
+     * @param ctx - The visit context containing the inline fragment node
+     */
+    private onLeaveInlineFragment;
+    /**
+     * Handles entering a selection set node.
+     * Creates a new nested proto message for object type selections and updates
+     * the current type context for proper field resolution.
+     *
+     * @param ctx - The visit context containing the selection set node and its parent
+     */
+    private onEnterSelectionSet;
+    /**
+     * Handles leaving a selection set node.
+     * Restores the previous type and message context when ascending the tree,
+     * but only if onEnterSelectionSet actually pushed state.
+     *
+     * @param ctx - The visit context containing the selection set node
+     */
+    private onLeaveSelectionSet;
+    /**
+     * Handles composite types (interfaces and unions) by setting up the
+     * appropriate composite type metadata on the current message.
+     *
+     * @param fieldDefinition - The field definition with a composite type
+     */
+    private handleCompositeType;
+    /**
+     * Type guard to check if a node is a FieldNode.
+     *
+     * @param node - The AST node or array of nodes to check
+     * @returns True if the node is a FieldNode
+     */
+    private isFieldNode;
+    /**
+     * Type guard to check if a node is an InlineFragmentNode.
+     *
+     * @param node - The AST node or array of nodes to check
+     * @returns True if the node is an InlineFragmentNode
+     */
+    private isInlineFragmentNode;
+    /**
+     * Finds the GraphQL object type for a field by looking up the field's return type.
+     *
+     * @param fieldName - The name of the field to look up
+     * @returns The GraphQL object type if the field returns an object type, undefined otherwise
+     */
+    private findObjectTypeForField;
+    /**
+     * Retrieves the field definition for a field name from the current type.
+     *
+     * @param fieldName - The name of the field to look up
+     * @returns The GraphQL field definition, or undefined if not found
+     */
+    private fieldDefinition;
+    /**
+     * Finds a GraphQL object type by name from the schema's type map.
+     *
+     * @param typeName - The name of the type to find
+     * @returns The GraphQL object type if found and is an object type, undefined otherwise
+     */
+    private findObjectType;
+    /**
+     * Extracts the fields string from a @key directive's fields argument.
+     *
+     * @param directive - The @key directive node
+     * @returns The fields string value, or empty string if not found
+     */
+    private getKeyFieldsString;
+    /**
+     * Checks if a GraphQL type is a composite type (interface or union).
+     *
+     * @param type - The GraphQL type to check
+     * @returns True if the type is an interface or union type
+     */
+    private isCompositeType;
+}
+export {};