@xyd-js/gql 0.1.0-xyd.13 → 0.1.0-xyd.15

package/src/schema.ts

@@ -1,107 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+
 import {
-    GraphQLInputObjectType,
-    GraphQLObjectType,
-    GraphQLEnumType,
-    isSpecifiedScalarType,
-    isIntrospectionType
+    buildSchema,
+    DirectiveNode,
+    print,
+    visit,
+    parse,
+    ObjectTypeExtensionNode,
+    GraphQLSchema,
+    StringValueNode
 } from "graphql";
-import {OperationTypeNode} from "graphql/language/ast";
-
-import {getDocumentLoaders, loadSchema} from "@graphql-markdown/graphql";
-import {GraphQLScalarType} from "@graphql-markdown/types";
+import {mergeTypeDefs} from '@graphql-tools/merge';
 
 import type {Reference} from "@xyd-js/uniform"
-import {ReferenceType} from "@xyd-js/uniform"
-import {gqlInputToUniformRef} from "./hydration/gql-input";
-import {gqlEnumToUniformRef, gqlScalarToUniformRef} from "./hydration/gql-types";
-import {gqlObjectToUniformRef} from "./hydration/gql-object";
-import {gqlOperationsToUniformRef} from "./utils";
+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: !!! CIRCULAR_DEPENDENCY !!!
 // TODO: sort by tag??
-
 export async function gqlSchemaToReferences(
-    schemaLocation: string
+    schemaLocation: string | string[],
+    options?: GQLSchemaToReferencesOptions
 ): Promise<Reference[]> {
-    const loadersList = {
-        ["GraphQLFileLoader"]: "@graphql-tools/graphql-file-loader",
+    // 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 = {}
     }
-    const loaders = await getDocumentLoaders(loadersList);
 
-    // @ts-ignore TODO: but ts works in @graphql-markdown/core
-    const schema = await loadSchema(schemaLocation as string, loaders);
+    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];
 
-    const references: Reference[] = []
+        // 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;
 
-    const queries = schema.getRootType(OperationTypeNode.QUERY)
-    const queryFields = queries?.getFields?.()
+            // Calculate position within this group using the stack
+            const positionInGroup = calculatePositionInGroup(reference, stackIndex, sortStacks);
 
-    if (queryFields) {
-        references.push(...gqlOperationsToUniformRef(
-            ReferenceType.GRAPHQL_QUERY,
-            queryFields
-        ))
+            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;
+        }
     }
 
-    const mutations = schema.getRootType(OperationTypeNode.MUTATION)
-    const mutationFields = mutations?.getFields?.()
+    return Number.MAX_SAFE_INTEGER;
+}
 
-    if (mutationFields) {
-        references.push(...gqlOperationsToUniformRef(
-            ReferenceType.GRAPHQL_MUTATION,
-            mutationFields
-        ))
+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;
     }
 
-    const typeMap = schema.getTypeMap();
+    // 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;
+    }
 
-    for (const gqlType of Object.values(typeMap)) {
-        const builtInType = isSpecifiedScalarType(gqlType) ||
-            isIntrospectionType(gqlType) ||
-            gqlType.name === "Mutation"
+    return true;
+}
+
+function calculatePositionInGroup(reference: Reference, stackIndex: number, sortStacks: string[][]): number {
+    if (stackIndex < 0 || stackIndex >= sortStacks.length) {
+        return 0;
+    }
 
-        if (builtInType) {
-            continue;
+    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
+}
 
-        switch (gqlType.constructor.name) {
-            case 'GraphQLObjectType': {
-                const type = gqlType as GraphQLObjectType;
 
-                references.push(gqlObjectToUniformRef(type))
+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;
+    }
 
-                break
+    // 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 [];
+}
 
-            case 'GraphQLInputObjectType': {
-                const type = gqlType as GraphQLInputObjectType;
+function docDirectiveChain(
+    rawSDL: string,
+    schema: GraphQLSchema
+) {
+    const ast = parse(rawSDL);
+    const metadata: GQLSchemaMetadata = {
+        fields: new Map<string, FieldMetadata>()
+    };
 
-                references.push(gqlInputToUniformRef(type))
-                break
+    // 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);
+                    }
+                }
             }
+        }
+    });
 
-            case 'GraphQLEnumType': {
-                const type = gqlType as GraphQLEnumType;
+    // Then process type extensions and fields
+    visit(ast, {
+        ObjectTypeExtension(node: ObjectTypeExtensionNode) {
+            const validNodeTypes = ['Query', 'Mutation', 'Subscription'];
+            if (!validNodeTypes.includes(node.name.value)) return;
 
-                references.push(gqlEnumToUniformRef(type))
+            const typeLevelDoc = node.directives?.find(d => d.name.value === OPEN_DOCS_DIRECTIVE_NAME);
+            const typeLevelDocArgs = typeLevelDoc ? extractDocArgs(typeLevelDoc) : {};
 
-                break
-            }
+            for (const field of node.fields ?? []) {
+                const fieldName = field.name.value;
 
-            case 'GraphQLScalarType': {
-                const type = gqlType as GraphQLScalarType
+                const fieldDoc = field.directives?.find(d => d.name.value === OPEN_DOCS_DIRECTIVE_NAME);
+                const fieldDocArgs = fieldDoc ? extractDocArgs(fieldDoc) : {};
 
-                references.push(gqlScalarToUniformRef(type))
+                // 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;
+                }
 
-                break
-            }
+                if (!fieldDocArgs.path && path) {
+                    path += "/" + fieldName
+                }
+
+                // Merge groups: combine root groups with type/field groups
+                const groups = fieldDocArgs.groups ?? typeLevelDocArgs.groups ?? [];
 
-            default: {
-                console.debug(`Unsupported type: ${gqlType.constructor.name}`)
+                const effectiveDoc: FieldMetadata = {
+                    groups,
+                    path
+                };
+
+                metadata.fields.set(`${node.name.value}.${fieldName}`, effectiveDoc);
             }
         }
-    }
+    });
 
-    return references
+    // 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

@@ -1,100 +1,25 @@
-import {GraphQLFieldMap} from "graphql/type";
-import {
-    Reference,
-    ReferenceCategory,
-    ReferenceType,
-    ExampleGroup,
-    Definition,
-    Example,
-} from "@xyd-js/uniform";
-
-import {gqlArgToUniformDefinitionProperty} from "./hydration/gql-arg";
-import {gqlFieldToUniformDefinitionProperty} from "./hydration/gql-field";
-import {simpleGraphqlExample} from "./samples";
-
-// gqlOperationsToUniformRef is a helper function to create a list of xyd reference for a GraphQL query or mutation.
-export function gqlOperationsToUniformRef(
-    operationType: ReferenceType.GRAPHQL_MUTATION | ReferenceType.GRAPHQL_QUERY,
-    fieldsMap: GraphQLFieldMap<any, any>
-) {
-    const references: Reference[] = []
-
-    for (const [operationName, operationField] of Object.entries(fieldsMap)) {
-        const definitions: Definition[] = []
-
-        const args = gqlArgToUniformDefinitionProperty(operationField.args)
-        const returns = gqlFieldToUniformDefinitionProperty(operationName, operationField)
-        const returnProperties = returns.properties || []
-
-        definitions.push({
-            title: "Arguments",
-            properties: args,
-        })
-        definitions.push({
-            title: "Returns",
-            properties: returnProperties
-        })
-
-        const exampleQuery = simpleGraphqlExample(
-            operationType,
-            operationName,
-            args,
-            returnProperties
-        )
-        const examples: Example[] = [
-            {
-                codeblock: {
-                    tabs: [
-                        {
-                            title: "graphql",
-                            language: "graphql",
-                            code: exampleQuery,
-                        }
-                    ]
-                }
-            }
-        ]
-
-        const exampleGroup = {
-            description: "Example request",
-            examples,
-        }
-
-        let description = operationField.description || ""
-
-        references.push(graphqlReference(
-            operationType,
-            operationName,
-            operationName,
-            description,
-            [exampleGroup],
-            definitions,
-        ))
+/**
+ * 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;
     }
 
-    return references
-}
-
-// graphqlReference is a helper function to create a Reference object for a GraphQL query or mutation.
-function graphqlReference(
-    operationType: ReferenceType.GRAPHQL_QUERY | ReferenceType.GRAPHQL_MUTATION,
-    title: string,
-    canonical: string,
-    description: string,
-    examples: ExampleGroup[],
-    definitions: Definition[],
-): Reference {
-    return {
-        title,
-        canonical,
-        description,
-
-        category: ReferenceCategory.GRAPHQL,
-        type: operationType,
-
-        examples: {
-            groups: examples,
-        },
-        definitions,
+    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

@@ -13,6 +13,6 @@
     "incremental": true,
     "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
   },
-  "include": ["examples/basic-example/**/*.ts", "src/**/*.ts"],
+  "include": ["examples/basic-example/**/*.ts", "src/**/*.ts", "declarations.d.ts"],
   "exclude": ["node_modules", "dist"]
 }

package/tsup.config.ts

@@ -1,3 +1,6 @@
+import { copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+
 import {defineConfig} from 'tsup';
 
 export default defineConfig({
@@ -14,6 +17,17 @@ export default defineConfig({
     esbuildOptions: (options) => {
         options.platform = 'node'; // Ensure the platform is set to Node.js
         options.external = ['node:fs/promises']; // Mark 'node:fs/promises' as external
-        options.loader = {'.js': 'jsx'}; // Ensure proper handling of .js files
+        options.loader = {
+            '.js': 'jsx', // Ensure proper handling of .js files
+            '.graphql': 'text' // Load .graphql files as text
+        };
     },
+    onSuccess: async () => {
+        // Copy opendocs.graphql to dist
+        copyFileSync(
+            join('src', 'opendocs.graphql'),
+            join('dist', 'opendocs.graphql')
+        );
+        return Promise.resolve();
+    }
 });

package/vitest.config.ts

@@ -2,6 +2,20 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
     test: {
-        // ...
+        environment: 'node',
+        globals: true,
     },
+    plugins: [
+        {
+            name: 'graphql-raw',
+            transform(code, id) {
+                if (id.endsWith('.graphql')) {
+                    return {
+                        code: `export default ${JSON.stringify(code)};`,
+                        map: null
+                    }
+                }
+            }
+        }
+    ]
 })

package/examples/basic/index.ts

@@ -1,12 +0,0 @@
-import path from 'path';
-
-import {gqlSchemaToReferences} from "../../src";
-
-// TODO: support multi graphql files
-// TODO: !!! CIRCULAR_DEPENDENCY !!!
-// TODO: sort by tag??
-(async () => {
-    const schemaLocation = path.join(process.cwd(), "./examples/basic/todo-app.graphqls")
-
-    const references = await gqlSchemaToReferences(schemaLocation)
-})()