@xyd-js/gql 0.0.0-build

package/src/opendocs.ts

@@ -0,0 +1,253 @@
+import {
+    GraphQLSchema,
+    GraphQLArgument,
+    GraphQLEnumType,
+    GraphQLEnumValue,
+    GraphQLField,
+    GraphQLInputObjectType,
+    GraphQLInterfaceType,
+    GraphQLObjectType,
+    GraphQLScalarType,
+    GraphQLUnionType,
+    ConstValueNode,
+    StringValueNode,
+} from "graphql";
+
+import {GQLOperation, GQLSchemaToReferencesOptions, SortItem} from "./types";
+import {GraphqlUniformReferenceType} from "./gql-core";
+import {Context} from "./context";
+
+export const OPEN_DOCS_SCHEMA_DIRECTIVE_NAME = "docs";
+export const OPEN_DOCS_DIRECTIVE_NAME = "doc";
+
+export function openDocsExtensionsToOptions(
+    schema: GraphQLSchema,
+) {
+    const options: GQLSchemaToReferencesOptions = {}
+
+    // Check for @docs directive in schema extensions
+    for (const extension of schema.extensionASTNodes || []) {
+        if (extension.kind === 'SchemaExtension') {
+            for (const directive of extension.directives || []) {
+                if (directive.name.value === OPEN_DOCS_SCHEMA_DIRECTIVE_NAME) {
+                    for (const arg of directive.arguments || []) {
+                        if (arg.name.value === 'flattenTypes' && arg.value.kind === 'BooleanValue') {
+                            if (arg.value.value === true) {
+                                options.flat = true
+                            } else if (arg.value.value === false) {
+                                options.flat = false
+                            }
+                        } else if (arg.name.value === 'sort' && arg.value.kind === 'ListValue') {
+                            const sortItems: SortItem[] = [];
+                            for (const item of arg.value.values) {
+                                if (item.kind === 'ObjectValue') {
+                                    const sortItem: SortItem = {};
+                                    for (const field of item.fields) {
+                                        if (field.name.value === 'node' && field.value.kind === 'StringValue') {
+                                            sortItem.node = field.value.value;
+                                        } else if (field.name.value === 'group' && field.value.kind === 'ListValue') {
+                                            sortItem.group = field.value.values
+                                                .filter((v): v is StringValueNode => v.kind === 'StringValue')
+                                                .map(v => v.value);
+                                        } else if (field.name.value === 'stack' && field.value.kind === 'IntValue') {
+                                            sortItem.stack = parseInt(field.value.value);
+                                        }
+                                    }
+                                    sortItems.push(sortItem);
+                                }
+                            }
+                            if (!options.sort) {
+                                options.sort = {};
+                            }
+                            options.sort.sort = sortItems;
+                        } else if (arg.name.value === 'sortStack' && arg.value.kind === 'ListValue') {
+                            const sortStacks: string[][] = [];
+                            for (const item of arg.value.values) {
+                                if (item.kind === 'ListValue') {
+                                    const stack = item.values
+                                        .filter((v): v is StringValueNode => v.kind === 'StringValue')
+                                        .map(v => v.value);
+                                    sortStacks.push(stack);
+                                }
+                            }
+                            if (!options.sort) {
+                                options.sort = {};
+                            }
+                            options.sort.sortStack = sortStacks;
+                        } else if (arg.name.value === 'route' && arg.value.kind === 'StringValue') {
+                            options.route = arg.value.value;
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return options;
+}
+
+type OpenDocsGQLNode =
+    | GQLOperation
+    | GraphQLScalarType
+    | GraphQLObjectType
+    | GraphQLField<any, any>
+    | GraphQLArgument
+    | GraphQLInterfaceType
+    | GraphQLUnionType
+    | GraphQLEnumType
+    | GraphQLEnumValue
+    | GraphQLInputObjectType
+
+export function openDocsToGroup(
+    ctx: Context | undefined,
+    odGqlNode: OpenDocsGQLNode,
+): string[] {
+    let groups: string[] = []
+
+    const metadata = (ctx?.schema as any).__metadata;
+
+    if (metadata?.rootGroups) {
+        groups = [...metadata.rootGroups];
+    }
+
+    let directiveGroups = false
+
+    // Check schema metadata for field-specific groups (for operations)
+    if (ctx?.schema && 'name' in odGqlNode) {
+        const metadata = (ctx.schema as any).__metadata;
+        if (metadata?.fields) {
+            if ("_operationType" in odGqlNode) {
+                let fieldKey = ""
+
+                switch (odGqlNode._operationType) {
+                    case "query": {
+                        fieldKey = `Query.${odGqlNode.name}`;
+                        break;
+                    }
+                    case "mutation": {
+                        fieldKey = `Mutation.${odGqlNode.name}`;
+                        break;
+                    }
+                    case "subscription": {
+                        fieldKey = `Subscription.${odGqlNode.name}`;
+                        break;
+                    }
+                }
+
+                const fieldMetadata = metadata.fields.get(fieldKey);
+                if (fieldMetadata?.groups) {
+                    directiveGroups = true
+                    groups.push(...fieldMetadata.groups);
+                }
+            }
+        }
+    }
+
+    // If no groups from metadata, try getting groups from the node itself
+    if (!directiveGroups && odGqlNode.astNode?.directives) {
+        for (const directive of odGqlNode.astNode.directives) {
+            switch (directive.name.value) {
+                case OPEN_DOCS_DIRECTIVE_NAME: {
+                    const groupArg = directive.arguments?.find((arg: {
+                        name: { value: string }
+                    }) => arg.name.value === 'group')
+                    if (groupArg?.value.kind === 'ListValue') {
+                        directiveGroups = true
+                        groups.push(...groupArg.value.values
+                            .filter((v: ConstValueNode): v is StringValueNode => v.kind === 'StringValue')
+                            .map(v => v.value)
+                        )
+                    }
+                    break
+                }
+            }
+        }
+    }
+
+    // If still no groups, use default based on type
+    if (!directiveGroups) {
+        if (odGqlNode instanceof GraphQLObjectType) {
+            groups.push("Objects")
+        } else if (odGqlNode instanceof GraphQLInterfaceType) {
+            groups.push("Interfaces")
+        } else if (odGqlNode instanceof GraphQLUnionType) {
+            groups.push("Unions")
+        } else if (odGqlNode instanceof GraphQLEnumType) {
+            groups.push("Enums")
+        } else if (odGqlNode instanceof GraphQLInputObjectType) {
+            groups.push("Inputs")
+        } else if (odGqlNode instanceof GraphQLScalarType) {
+            groups.push("Scalars")
+        } else if (odGqlNode instanceof GQLOperation) {
+            switch (odGqlNode._operationType) {
+                case "query": {
+                    groups.push("Queries")
+                    break;
+                }
+                case "mutation": {
+                    groups.push("Mutations")
+                    break;
+                }
+                case "subscription": {
+                    groups.push("Subscriptions")
+                    break;
+                }
+            }
+        }
+    }
+
+    return groups
+}
+
+export function openDocsCanonical(
+    ctx: Context,
+    gqlType: GraphqlUniformReferenceType,
+) {
+    let path = ""
+
+    // Get parent path if this is a field
+    if ('astNode' in gqlType && gqlType.astNode?.kind === 'FieldDefinition' && ctx?.schema) {
+        // Check schema metadata for field-specific path
+        const metadata = (ctx.schema as any).__metadata;
+        if (metadata?.fields && 'name' in gqlType) {
+            if ("_operationType" in gqlType) {
+                let fieldKey = ""
+
+                switch (gqlType._operationType) {
+                    case "query": {
+                        fieldKey = `Query.${gqlType.name}`;
+                        break;
+                    }
+                    case "mutation": {
+                        fieldKey = `Mutation.${gqlType.name}`;
+                        break;
+                    }
+                    case "subscription": {
+                        fieldKey = `Subscription.${gqlType.name}`;
+                        break;
+                    }
+                }
+                const fieldMetadata = metadata.fields.get(fieldKey);
+
+
+                if (fieldMetadata?.path) {
+                    path = fieldMetadata.path;
+                }
+            }
+        }
+    }
+
+    // Extract path from @doc directive if present
+    if (!path && gqlType.astNode?.directives) {
+        for (const directive of gqlType.astNode.directives) {
+            if (directive.name.value === OPEN_DOCS_DIRECTIVE_NAME) {
+                const pathArg = directive.arguments?.find(arg => arg.name.value === 'path')
+                if (pathArg?.value.kind === 'StringValue') {
+                    path = pathArg.value.value
+                }
+            }
+        }
+    }
+
+    return path
+}

package/src/schema.ts

@@ -0,0 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+
+import {
+    buildSchema,
+    DirectiveNode,
+    print,
+    visit,
+    parse,
+    ObjectTypeExtensionNode,
+    GraphQLSchema,
+    StringValueNode
+} from "graphql";
+import {mergeTypeDefs} from '@graphql-tools/merge';
+
+import type {Reference} from "@xyd-js/uniform"
+import {ReferenceType} from "@xyd-js/uniform";
+
+import type {
+    GQLSchemaToReferencesOptions,
+    OpenDocsSortConfig,
+    FieldMetadata,
+    GQLSchemaMetadata,
+    SortItem
+} from "./types";
+import {DEFAULT_SORT_ORDER} from "./types";
+import {graphqlTypesToUniformReferences} from "./converters/gql-types";
+import {graphqlQueriesToUniformReferences} from "./converters/gql-query";
+import {graphqlMutationsToUniformReferences} from "./converters/gql-mutation";
+import {graphqlSubscriptionsToUniformReferences} from "./converters/gql-subscription";
+import {OPEN_DOCS_DIRECTIVE_NAME, OPEN_DOCS_SCHEMA_DIRECTIVE_NAME, openDocsExtensionsToOptions} from "./opendocs";
+import openDocsSchemaRaw from './opendocs.graphql'
+
+// TODO: support multi graphql files
+// TODO: sort by tag??
+export async function gqlSchemaToReferences(
+    schemaLocation: string | string[],
+    options?: GQLSchemaToReferencesOptions
+): Promise<Reference[]> {
+    // 1. Convert schemaLocation to array
+    const schemaLocations = Array.isArray(schemaLocation) ? schemaLocation : [schemaLocation];
+
+    // Add opendocs.graphql to schema locations (first)
+    schemaLocations.unshift(openDocsSchemaRaw);
+
+    // 2. Read all schema contents
+    const schemaContents = await Promise.all(schemaLocations.map(async location => {
+        if (location.startsWith('http://') || location.startsWith('https://')) {
+            const response = await fetch(location);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch schema from URL: ${location}`);
+            }
+            return response.text();
+        }
+        if (fs.existsSync(location)) {
+            return fs.readFileSync(location, 'utf-8');
+        }
+        return location;
+    }));
+
+    // 3. Merge all schema contents
+    const mergedTypeDefs = mergeTypeDefs(schemaContents);
+    const schemaString = print(mergedTypeDefs);
+
+    // 4. Build the schema
+    const schema = buildSchema(schemaString, {
+        assumeValid: true
+    });
+    if (schemaContents.length > 2) {
+        console.warn(`Warning: More than 2 schema files provided - no all featues will be supported!`);
+    }
+    
+    docDirectiveChain(schemaContents[1], schema);
+    // TODO: fix schemaContents[1]
+
+    if (!options) {
+        options = {}
+    }
+
+    if (!options.hasOwnProperty('flat')) {
+        options.flat = true; // Default flat is true
+    }
+    options = {
+        ...options,
+        ...openDocsExtensionsToOptions(schema)
+    }
+
+    // 5. Generate uniform references from the schema
+    const references = [
+        // types
+        ...graphqlTypesToUniformReferences(schema, options),
+
+        // queries
+        ...graphqlQueriesToUniformReferences(schema, options),
+
+        // mutations
+        ...graphqlMutationsToUniformReferences(schema, options),
+
+        // subscriptions
+        ...graphqlSubscriptionsToUniformReferences(schema, options),
+    ]
+
+    // Sort references using provided sort config or defaults
+    const sortConfig = options.sort ?? {sort: DEFAULT_SORT_ORDER};
+    references.sort((a, b) => {
+        const aOrder = getSortOrder(a, sortConfig);
+        const bOrder = getSortOrder(b, sortConfig);
+        return aOrder - bOrder;
+    });
+
+    if (options.route) {
+        // TODO: types or better solution!!!
+        // @ts-ignore
+        references.__UNSAFE_route = () => options.route
+    }
+    return references
+}
+
+function getSortOrder(reference: Reference, sortConfig: OpenDocsSortConfig): number {
+    const sortItems = sortConfig.sort ?? DEFAULT_SORT_ORDER;
+    const sortStacks = sortConfig.sortStack ?? [];
+    const referenceGroups = getReferenceGroups(reference);
+
+    // First, find which primary group this reference belongs to
+    for (let groupIndex = 0; groupIndex < sortItems.length; groupIndex++) {
+        const sortItem = sortItems[groupIndex];
+
+        // Check if this reference matches the primary group
+        if (matchesPrimaryGroup(reference, sortItem)) {
+            // Determine which stack to use (default to 0 if not specified)
+            const stackIndex = sortItem.stack !== undefined ? sortItem.stack : 0;
+
+            // Calculate position within this group using the stack
+            const positionInGroup = calculatePositionInGroup(reference, stackIndex, sortStacks);
+
+            const result = (groupIndex * 1000) + positionInGroup;
+            
+            // Return order: groupIndex * 1000 + positionInGroup
+            // This ensures all items in group 0 come before all items in group 1, etc.
+            return result;
+        }
+    }
+
+    return Number.MAX_SAFE_INTEGER;
+}
+
+function matchesPrimaryGroup(reference: Reference, sortItem: SortItem): boolean {
+    // Check node match first
+    if (sortItem.node) {
+        const context = reference.context as any;
+        if (context?.graphqlTypeShort === sortItem.node) {
+            return true;
+        }
+        // If node is specified but doesn't match, return false (don't fall through)
+        return false;
+    }
+
+    // Check group match
+    if (sortItem.group && sortItem.group.length > 0) {
+        const referenceGroups = getReferenceGroups(reference);
+        const match = sortItem.group.some(group => referenceGroups.includes(group));
+        return match;
+    }
+
+    return true;
+}
+
+function calculatePositionInGroup(reference: Reference, stackIndex: number, sortStacks: string[][]): number {
+    if (stackIndex < 0 || stackIndex >= sortStacks.length) {
+        return 0;
+    }
+
+    const stackGroups = sortStacks[stackIndex];
+    const referenceGroups = getReferenceGroups(reference);
+
+    // Find the position of the reference's type in the stack
+    for (let i = 0; i < stackGroups.length; i++) {
+        const stackGroup = stackGroups[i];
+        if (referenceGroups.includes(stackGroup)) {
+            return i;
+        }
+    }
+
+    return 999; // If not found in stack, put at the end of the group
+}
+
+
+function getReferenceGroups(reference: Reference): string[] {
+    // Extract groups from reference context
+    const context = reference.context as any;
+    if (context?.group && Array.isArray(context.group)) {
+        return context.group;
+    }
+
+    // Fallback: try to get groups from metadata if available
+    if (reference.__UNSAFE_selector) {
+        try {
+            const selector = reference.__UNSAFE_selector;
+            const metadata = selector("[metadata]");
+            if (metadata?.groups) {
+                return metadata.groups;
+            }
+        } catch (e) {
+            // Ignore errors from selector
+        }
+    }
+
+    return [];
+}
+
+function docDirectiveChain(
+    rawSDL: string,
+    schema: GraphQLSchema
+) {
+    const ast = parse(rawSDL);
+    const metadata: GQLSchemaMetadata = {
+        fields: new Map<string, FieldMetadata>()
+    };
+
+    // First, find root groups from @docs directive
+    visit(ast, {
+        SchemaExtension(node) {
+            for (const directive of node.directives || []) {
+                if (directive.name.value === OPEN_DOCS_SCHEMA_DIRECTIVE_NAME) {
+                    const groupArg = directive.arguments?.find(arg => arg.name.value === 'group');
+                    if (groupArg?.value.kind === 'ListValue') {
+                        metadata.rootGroups = groupArg.value.values
+                            .filter((v): v is StringValueNode => v.kind === 'StringValue')
+                            .map(v => v.value);
+                    }
+                }
+            }
+        }
+    });
+
+    // Then process type extensions and fields
+    visit(ast, {
+        ObjectTypeExtension(node: ObjectTypeExtensionNode) {
+            const validNodeTypes = ['Query', 'Mutation', 'Subscription'];
+            if (!validNodeTypes.includes(node.name.value)) return;
+
+            const typeLevelDoc = node.directives?.find(d => d.name.value === OPEN_DOCS_DIRECTIVE_NAME);
+            const typeLevelDocArgs = typeLevelDoc ? extractDocArgs(typeLevelDoc) : {};
+
+            for (const field of node.fields ?? []) {
+                const fieldName = field.name.value;
+
+                const fieldDoc = field.directives?.find(d => d.name.value === OPEN_DOCS_DIRECTIVE_NAME);
+                const fieldDocArgs = fieldDoc ? extractDocArgs(fieldDoc) : {};
+
+                // Merge paths: if both type and field have paths, join them
+                let path = fieldDocArgs.path;
+                if (typeLevelDocArgs.path && fieldDocArgs.path) {
+                    path = `${typeLevelDocArgs.path}/${fieldDocArgs.path}`;
+                } else if (typeLevelDocArgs.path) {
+                    path = typeLevelDocArgs.path;
+                }
+
+                if (!fieldDocArgs.path && path) {
+                    path += "/" + fieldName
+                }
+
+                // Merge groups: combine root groups with type/field groups
+                const groups = fieldDocArgs.groups ?? typeLevelDocArgs.groups ?? [];
+
+                const effectiveDoc: FieldMetadata = {
+                    groups,
+                    path
+                };
+
+                metadata.fields.set(`${node.name.value}.${fieldName}`, effectiveDoc);
+            }
+        }
+    });
+
+    // Attach metadata to schema
+    (schema as any).__metadata = metadata;
+}
+
+function extractDocArgs(directive: DirectiveNode): FieldMetadata {
+    const info: FieldMetadata = {};
+    for (const arg of directive.arguments ?? []) {
+        if (arg.name.value === 'group' && arg.value.kind === 'ListValue') {
+            info.groups = arg.value.values
+                .filter((v): v is StringValueNode => v.kind === 'StringValue')
+                .map(v => v.value);
+        } else if (arg.name.value === 'path' && arg.value.kind === 'StringValue') {
+            info.path = arg.value.value;
+        }
+    }
+    return info;
+}

package/src/types.ts

@@ -0,0 +1,103 @@
+import type {GraphQLInputObjectType, GraphQLInterfaceType, GraphQLNamedType, GraphQLObjectType} from "graphql";
+import {GraphQLField, OperationTypeNode} from "graphql";
+
+import type {DefinitionProperty} from "@xyd-js/uniform";
+
+// New sorting types based on the documentation
+export interface SortItem {
+    node?: string;
+    group?: string[];
+    stack?: number;
+}
+
+export interface SortStack {
+    sortStack?: string[][];
+    sort?: SortItem[];
+}
+
+export interface OpenDocsSortConfig {
+    sortStack?: string[][];
+    sort?: SortItem[];
+}
+
+export const DEFAULT_SORT_ORDER: SortItem[] = [
+    { node: "query" },
+    { node: "mutation" },
+    { node: "subscription" },
+    { node: "object" },
+    { node: "interface" },
+    { node: "union" },
+    { node: "input" },
+    { node: "enum" },
+    { node: "scalar" },
+];
+
+export interface GQLSchemaToReferencesOptions {
+    // TODO: support line ranged in the future?
+    regions?: string[] // TODO: BETTER API - UNIFY FOR REST API / GRAPHQL ETC
+
+    flat?: boolean;
+    sort?: OpenDocsSortConfig;
+    route?: string
+}
+
+export type NestedGraphqlType = {
+    __definitionProperties?: DefinitionProperty[];
+} & (GraphQLObjectType | GraphQLInputObjectType | GraphQLInterfaceType)
+
+// needed cuz GraphQLField does not have operation info?
+export class GQLOperation implements GraphQLField<any, any> {
+    public _operationType!: OperationTypeNode
+    field: GraphQLField<any, any>;
+
+    constructor(field: GraphQLField<any, any>) {
+        this.field = field;
+    }
+
+    get name() {
+        return this.field.name;
+    }
+
+    get description() {
+        return this.field.description;
+    }
+
+    get type() {
+        return this.field.type;
+    }
+
+    get args() {
+        return this.field.args;
+    }
+
+    get deprecationReason() {
+        return this.field.deprecationReason;
+    }
+
+    get extensions() {
+        return this.field.extensions;
+    }
+
+    get astNode() {
+        return this.field.astNode;
+    }
+
+    set __operationType(operationType: OperationTypeNode) {
+        this._operationType = operationType;
+    }
+}
+
+export interface GQLTypeInfo {
+    typeFlat?: GraphQLNamedType
+}
+
+export interface FieldMetadata {
+    path?: string;
+    groups?: string[];
+}
+
+export interface GQLSchemaMetadata {
+    fields: Map<string, FieldMetadata>;
+    rootGroups?: string[];
+}
+

package/src/utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Helper function to filter fields based on region patterns
+ * @param fields - The fields to filter
+ * @param prefix - The prefix for the region key (e.g., "Query" or "Mutation")
+ * @param regions - The regions to filter by
+ * @returns Filtered fields object
+ */
+export function filterFieldsByRegions<T>(
+    fields: Record<string, T>,
+    prefix: string,
+    regions?: string[]
+): Record<string, T> {
+    if (!regions || regions.length === 0) {
+        return fields;
+    }
+
+    const filteredFields: Record<string, T> = {};
+    for (const [fieldName, field] of Object.entries(fields)) {
+        const regionKey = `${prefix}.${fieldName}`;
+        if (regions.some(region => region === regionKey)) {
+            filteredFields[fieldName] = field;
+        }
+    }
+    return filteredFields;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["examples/basic-example/**/*.ts", "src/**/*.ts", "declarations.d.ts"],
+  "exclude": ["node_modules", "dist"]
+}