ponder-enrich-gql-docs-middleware/lib/src/base-definitions.js

A middleware for Ponder that allows devs to enrich their GraphQL docs with docstrings

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.baseDefinitions = void 0;
exports.generateFilterDocs = generateFilterDocs;
exports.generatePageDocs = generatePageDocs;
exports.generateQueryDocs = generateQueryDocs;
exports.generateTypeDocSet = generateTypeDocSet;
exports.extendWithBaseDefinitions = extendWithBaseDefinitions;
// src/base-definitions.ts
exports.baseDefinitions = {
    // Standard scalar types
    scalars: {
        JSON: "The `JSON` scalar type represents JSON values as specified by ECMA-404",
        BigInt: "Arbitrary precision integer, useful for representing large numbers",
        Boolean: "True or false value",
        String: "UTF-8 character sequence used for text data",
        Int: "32-bit integer between -(2^31) and 2^31 - 1",
    },
    // Common page info and pagination
    pagination: {
        PageInfo: "Information about pagination in a connection",
        "PageInfo.hasNextPage": "Whether there are more records after the current page",
        "PageInfo.hasPreviousPage": "Whether there are more records before the current page",
        "PageInfo.startCursor": "Cursor pointing to the first record in the current page",
        "PageInfo.endCursor": "Cursor pointing to the last record in the current page",
        totalCount: "Total number of records matching the query",
        items: "List of items in the current page",
    },
    // Query arguments
    queryArgs: {
        where: "Filter conditions to apply",
        orderBy: "Field to order results by",
        orderDirection: "Direction to order results (asc/desc)",
        before: "Fetch records before this cursor",
        after: "Fetch records after this cursor",
        limit: "Maximum number of records to return",
    },
    // Filter operators
    filterOperators: {
        AND: "Combine multiple conditions with AND",
        OR: "Combine multiple conditions with OR",
        equals: "Exact match",
        not: "Negates the condition",
        in: "Match any value in the provided list",
        not_in: "Match none of the values in the provided list",
        gt: "Greater than",
        gte: "Greater than or equal",
        lt: "Less than",
        lte: "Less than or equal",
        contains: "String contains the value",
        not_contains: "String does not contain the value",
        starts_with: "String starts with the value",
        ends_with: "String ends with the value",
        not_starts_with: "String does not start with the value",
        not_ends_with: "String does not end with the value",
    },
};
// Helper function to generate filter field docs
function generateFilterDocs(fieldName, baseDesc = "") {
    const prefix = fieldName ? `${fieldName}_` : "";
    return {
        [`${fieldName}`]: `${baseDesc} (exact match)`,
        [`${prefix}not`]: `${baseDesc} (exclude match)`,
        [`${prefix}in`]: `${baseDesc} (match any in list)`,
        [`${prefix}not_in`]: `${baseDesc} (match none in list)`,
        [`${prefix}gt`]: `${baseDesc} (greater than)`,
        [`${prefix}gte`]: `${baseDesc} (greater than or equal)`,
        [`${prefix}lt`]: `${baseDesc} (less than)`,
        [`${prefix}lte`]: `${baseDesc} (less than or equal)`,
        [`${prefix}contains`]: `${baseDesc} (contains substring)`,
        [`${prefix}not_contains`]: `${baseDesc} (does not contain substring)`,
        [`${prefix}starts_with`]: `${baseDesc} (starts with)`,
        [`${prefix}ends_with`]: `${baseDesc} (ends with)`,
        [`${prefix}not_starts_with`]: `${baseDesc} (does not start with)`,
        [`${prefix}not_ends_with`]: `${baseDesc} (does not end with)`,
    };
}
// Helper to generate page type docs
function generatePageDocs(typeName, description = "") {
    return {
        [`${typeName}Page`]: `Paginated list of ${description || typeName} records`,
        [`${typeName}Page.items`]: `List of ${description || typeName} records`,
        [`${typeName}Page.pageInfo`]: exports.baseDefinitions.pagination.PageInfo,
        [`${typeName}Page.totalCount`]: exports.baseDefinitions.pagination.totalCount,
    };
}
/**
 * Generate documentation for a query field based on its type name
 */
function generateQueryDocs(typeName, description = "") {
    const baseDesc = description || `${typeName} record`;
    const pluralName = `${typeName}s`;
    return {
        // Single record query
        [typeName]: `Get a single ${baseDesc} by address`,
        // List query with filters and pagination
        [pluralName]: `Get a list of ${baseDesc}s with optional filtering and pagination`,
        [`${pluralName}.where`]: `Filter conditions for ${baseDesc}s`,
        [`${pluralName}.orderBy`]: `Field to order ${baseDesc}s by`,
        [`${pluralName}.orderDirection`]: `Direction to order ${baseDesc}s (asc/desc)`,
        [`${pluralName}.before`]: "Fetch records before this cursor",
        [`${pluralName}.after`]: "Fetch records after this cursor",
        [`${pluralName}.limit`]: "Maximum number of records to return",
    };
}
function generateTypeDocSet(typeName, description, fields = {}) {
    return Object.assign(Object.assign(Object.assign(Object.assign({ 
        // Attach doc to the actual type name, i.e. "User"
        [typeName]: description }, fields), Object.entries(fields).reduce((acc, [fieldName, fieldDesc]) => {
        return Object.assign(acc, generateFilterDocs(fieldName, fieldDesc));
    }, {})), generatePageDocs(typeName, description)), generateQueryDocs(typeName, description));
}
function extendWithBaseDefinitions(userDocs) {
    return Object.assign(Object.assign(Object.assign({}, exports.baseDefinitions.scalars), exports.baseDefinitions.pagination), userDocs);
}