@effect-gql/core 0.1.0

package/dist/server/cache-control.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheControlConfigFromEnv = exports.toCacheControlHeader = exports.computeCachePolicyFromQuery = exports.computeCachePolicy = void 0;
+const effect_1 = require("effect");
+const graphql_1 = require("graphql");
+// ============================================================================
+// Cache Policy Computation
+// ============================================================================
+/**
+ * Compute the cache policy for a GraphQL response based on the fields resolved.
+ *
+ * The policy is computed by walking the selection set and aggregating hints:
+ * - maxAge: Use the minimum maxAge of all resolved fields
+ * - scope: If any field is PRIVATE, the entire response is PRIVATE
+ *
+ * Default behaviors (matching Apollo):
+ * - Root fields default to maxAge: 0 (unless configured otherwise)
+ * - Object-returning fields default to maxAge: 0
+ * - Scalar fields inherit their parent's maxAge
+ * - Fields with inheritMaxAge: true inherit from parent
+ */
+const computeCachePolicy = (info) => effect_1.Effect.sync(() => {
+    const fragments = new Map();
+    // Collect fragment definitions
+    for (const definition of info.document.definitions) {
+        if (definition.kind === graphql_1.Kind.FRAGMENT_DEFINITION) {
+            fragments.set(definition.name.value, definition);
+        }
+    }
+    // Get the root type for the operation
+    const rootType = getRootType(info.schema, info.operation.operation);
+    if (!rootType) {
+        // No root type - return no-cache
+        return { maxAge: 0, scope: "PUBLIC" };
+    }
+    const defaultMaxAge = info.config.defaultMaxAge ?? 0;
+    const defaultScope = info.config.defaultScope ?? "PUBLIC";
+    // Analyze the selection set
+    const result = analyzeSelectionSet(info.operation.selectionSet, rootType, info.schema, fragments, info.cacheHints, defaultMaxAge, defaultScope, undefined, // No parent maxAge for root
+    new Set());
+    return result;
+});
+exports.computeCachePolicy = computeCachePolicy;
+/**
+ * Compute cache policy from a query string
+ */
+const computeCachePolicyFromQuery = (query, operationName, schema, cacheHints, config = {}) => effect_1.Effect.gen(function* () {
+    // Parse the query
+    const document = yield* effect_1.Effect.try({
+        try: () => (0, graphql_1.parse)(query),
+        catch: (error) => new Error(`Failed to parse query: ${error}`),
+    });
+    // Find the operation
+    const operation = yield* effect_1.Effect.try({
+        try: () => {
+            const operations = document.definitions.filter((d) => d.kind === graphql_1.Kind.OPERATION_DEFINITION);
+            if (operations.length === 0) {
+                throw new Error("No operation found in query");
+            }
+            if (operationName) {
+                const op = operations.find((o) => o.name?.value === operationName);
+                if (!op) {
+                    throw new Error(`Operation "${operationName}" not found`);
+                }
+                return op;
+            }
+            if (operations.length > 1) {
+                throw new Error("Multiple operations found - operationName required");
+            }
+            return operations[0];
+        },
+        catch: (error) => error,
+    });
+    return yield* (0, exports.computeCachePolicy)({
+        document,
+        operation,
+        schema,
+        cacheHints,
+        config,
+    });
+});
+exports.computeCachePolicyFromQuery = computeCachePolicyFromQuery;
+/**
+ * Convert a cache policy to an HTTP Cache-Control header value
+ */
+const toCacheControlHeader = (policy) => {
+    if (policy.maxAge === 0) {
+        return "no-store";
+    }
+    const directives = [];
+    directives.push(policy.scope === "PRIVATE" ? "private" : "public");
+    directives.push(`max-age=${policy.maxAge}`);
+    return directives.join(", ");
+};
+exports.toCacheControlHeader = toCacheControlHeader;
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Get the root type for an operation
+ */
+function getRootType(schema, operation) {
+    switch (operation) {
+        case "query":
+            return schema.getQueryType() ?? null;
+        case "mutation":
+            return schema.getMutationType() ?? null;
+        case "subscription":
+            return schema.getSubscriptionType() ?? null;
+    }
+}
+/**
+ * Get the named type from a potentially wrapped type
+ */
+function getNamedType(type) {
+    if (type instanceof graphql_1.GraphQLNonNull || type instanceof graphql_1.GraphQLList) {
+        return getNamedType(type.ofType);
+    }
+    if (type instanceof graphql_1.GraphQLObjectType ||
+        type instanceof graphql_1.GraphQLScalarType ||
+        type instanceof graphql_1.GraphQLEnumType) {
+        return type;
+    }
+    return null;
+}
+/**
+ * Check if a type is a scalar or enum (leaf type)
+ */
+function isLeafType(type) {
+    const namedType = getNamedType(type);
+    return namedType instanceof graphql_1.GraphQLScalarType || namedType instanceof graphql_1.GraphQLEnumType;
+}
+/**
+ * Aggregate a field policy into the accumulator
+ */
+function aggregatePolicy(acc, policy) {
+    if (acc.minMaxAge === undefined) {
+        acc.minMaxAge = policy.maxAge;
+    }
+    else {
+        acc.minMaxAge = Math.min(acc.minMaxAge, policy.maxAge);
+    }
+    if (policy.scope === "PRIVATE") {
+        acc.hasPrivate = true;
+    }
+}
+/**
+ * Analyze a fragment spread and return its cache policy
+ */
+function analyzeFragmentSpread(fragmentName, ctx, parentMaxAge, visitedFragments) {
+    // Prevent infinite loops with fragment cycles
+    if (visitedFragments.has(fragmentName)) {
+        return undefined;
+    }
+    const fragment = ctx.fragments.get(fragmentName);
+    if (!fragment) {
+        return undefined;
+    }
+    const fragmentType = ctx.schema.getType(fragment.typeCondition.name.value);
+    if (!(fragmentType instanceof graphql_1.GraphQLObjectType)) {
+        return undefined;
+    }
+    const newVisited = new Set(visitedFragments);
+    newVisited.add(fragmentName);
+    return analyzeSelectionSet(fragment.selectionSet, fragmentType, ctx, parentMaxAge, newVisited);
+}
+/**
+ * Analyze an inline fragment and return its cache policy
+ */
+function analyzeInlineFragment(selection, parentType, ctx, parentMaxAge, visitedFragments) {
+    let targetType = parentType;
+    if (selection.typeCondition) {
+        const conditionType = ctx.schema.getType(selection.typeCondition.name.value);
+        if (conditionType instanceof graphql_1.GraphQLObjectType) {
+            targetType = conditionType;
+        }
+    }
+    return analyzeSelectionSet(selection.selectionSet, targetType, ctx, parentMaxAge, visitedFragments);
+}
+/**
+ * Look up the effective cache hint for a field (field-level > type-level > undefined)
+ */
+function lookupEffectiveCacheHint(parentTypeName, fieldName, returnType, cacheHints) {
+    // Priority: field-level hint > type-level hint
+    const fieldKey = `${parentTypeName}.${fieldName}`;
+    const fieldHint = cacheHints.get(fieldKey);
+    if (fieldHint)
+        return fieldHint;
+    // Check type-level hint on return type
+    const namedType = getNamedType(returnType);
+    return namedType ? cacheHints.get(namedType.name) : undefined;
+}
+/**
+ * Compute the maxAge for a field based on hint, inheritance, and field type
+ */
+function computeFieldMaxAge(hint, fieldType, parentMaxAge, defaultMaxAge) {
+    if (hint) {
+        // Use explicit hint
+        if (hint.inheritMaxAge && parentMaxAge !== undefined) {
+            return parentMaxAge;
+        }
+        if (hint.maxAge !== undefined) {
+            return hint.maxAge;
+        }
+        // Fall through to default logic
+    }
+    // Scalar/enum fields inherit parent maxAge by default
+    if (isLeafType(fieldType) && parentMaxAge !== undefined) {
+        return parentMaxAge;
+    }
+    // Root and object fields default to defaultMaxAge (typically 0)
+    return defaultMaxAge;
+}
+function analyzeSelectionSet(selectionSet, parentType, schemaOrCtx, fragmentsOrParentMaxAge, cacheHintsOrVisited, defaultMaxAge, defaultScope, parentMaxAge, visitedFragments) {
+    // Normalize arguments - support both old and new signatures
+    let ctx;
+    let actualParentMaxAge;
+    let actualVisitedFragments;
+    if (schemaOrCtx instanceof graphql_1.GraphQLSchema) {
+        // Old signature
+        ctx = {
+            schema: schemaOrCtx,
+            fragments: fragmentsOrParentMaxAge,
+            cacheHints: cacheHintsOrVisited,
+            defaultMaxAge: defaultMaxAge,
+            defaultScope: defaultScope,
+        };
+        actualParentMaxAge = parentMaxAge;
+        actualVisitedFragments = visitedFragments;
+    }
+    else {
+        // New signature with AnalysisContext
+        ctx = schemaOrCtx;
+        actualParentMaxAge = fragmentsOrParentMaxAge;
+        actualVisitedFragments = cacheHintsOrVisited;
+    }
+    const acc = { minMaxAge: undefined, hasPrivate: false };
+    for (const selection of selectionSet.selections) {
+        let fieldPolicy;
+        switch (selection.kind) {
+            case graphql_1.Kind.FIELD:
+                fieldPolicy = analyzeField(selection, parentType, ctx, actualParentMaxAge, actualVisitedFragments);
+                break;
+            case graphql_1.Kind.FRAGMENT_SPREAD:
+                fieldPolicy = analyzeFragmentSpread(selection.name.value, ctx, actualParentMaxAge, actualVisitedFragments);
+                break;
+            case graphql_1.Kind.INLINE_FRAGMENT:
+                fieldPolicy = analyzeInlineFragment(selection, parentType, ctx, actualParentMaxAge, actualVisitedFragments);
+                break;
+        }
+        if (fieldPolicy) {
+            aggregatePolicy(acc, fieldPolicy);
+        }
+    }
+    return {
+        maxAge: acc.minMaxAge ?? ctx.defaultMaxAge,
+        scope: acc.hasPrivate ? "PRIVATE" : ctx.defaultScope,
+    };
+}
+/**
+ * Analyze a field node and return its cache policy
+ */
+function analyzeField(field, parentType, ctx, parentMaxAge, visitedFragments) {
+    const fieldName = field.name.value;
+    // Introspection fields - don't affect caching
+    if (fieldName.startsWith("__")) {
+        return { maxAge: Infinity, scope: "PUBLIC" };
+    }
+    // Get the field from the schema
+    const schemaField = parentType.getFields()[fieldName];
+    if (!schemaField) {
+        return { maxAge: ctx.defaultMaxAge, scope: ctx.defaultScope };
+    }
+    // Look up effective cache hint
+    const effectiveHint = lookupEffectiveCacheHint(parentType.name, fieldName, schemaField.type, ctx.cacheHints);
+    // Compute field maxAge
+    const fieldMaxAge = computeFieldMaxAge(effectiveHint, schemaField.type, parentMaxAge, ctx.defaultMaxAge);
+    const fieldScope = effectiveHint?.scope ?? ctx.defaultScope;
+    // If the field has a selection set, analyze it
+    const namedType = getNamedType(schemaField.type);
+    if (field.selectionSet && namedType instanceof graphql_1.GraphQLObjectType) {
+        const nestedPolicy = analyzeSelectionSet(field.selectionSet, namedType, ctx, fieldMaxAge, visitedFragments);
+        return {
+            maxAge: Math.min(fieldMaxAge, nestedPolicy.maxAge),
+            scope: fieldScope === "PRIVATE" || nestedPolicy.scope === "PRIVATE" ? "PRIVATE" : "PUBLIC",
+        };
+    }
+    return { maxAge: fieldMaxAge, scope: fieldScope };
+}
+// ============================================================================
+// Environment Configuration
+// ============================================================================
+/**
+ * Effect Config for loading cache control configuration from environment variables.
+ *
+ * Environment variables:
+ * - GRAPHQL_CACHE_CONTROL_ENABLED: Enable cache control (default: true)
+ * - GRAPHQL_CACHE_CONTROL_DEFAULT_MAX_AGE: Default maxAge for root fields (default: 0)
+ * - GRAPHQL_CACHE_CONTROL_DEFAULT_SCOPE: Default scope (PUBLIC or PRIVATE, default: PUBLIC)
+ * - GRAPHQL_CACHE_CONTROL_HTTP_HEADERS: Set HTTP headers (default: true)
+ */
+exports.CacheControlConfigFromEnv = effect_1.Config.all({
+    enabled: effect_1.Config.boolean("GRAPHQL_CACHE_CONTROL_ENABLED").pipe(effect_1.Config.withDefault(true)),
+    defaultMaxAge: effect_1.Config.number("GRAPHQL_CACHE_CONTROL_DEFAULT_MAX_AGE").pipe(effect_1.Config.withDefault(0)),
+    defaultScope: effect_1.Config.string("GRAPHQL_CACHE_CONTROL_DEFAULT_SCOPE").pipe(effect_1.Config.withDefault("PUBLIC"), effect_1.Config.map((s) => (s === "PRIVATE" ? "PRIVATE" : "PUBLIC"))),
+    calculateHttpHeaders: effect_1.Config.boolean("GRAPHQL_CACHE_CONTROL_HTTP_HEADERS").pipe(effect_1.Config.withDefault(true)),
+});
+//# sourceMappingURL=cache-control.js.map

package/dist/server/cache-control.js.map

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

package/dist/server/complexity.d.ts

@@ -0,0 +1,165 @@
+import { Effect, Config } from "effect";
+import { DocumentNode, OperationDefinitionNode, GraphQLSchema } from "graphql";
+declare const ComplexityLimitExceededError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ComplexityLimitExceededError";
+} & Readonly<A>;
+/**
+ * Error thrown when query complexity exceeds configured limits
+ */
+export declare class ComplexityLimitExceededError extends ComplexityLimitExceededError_base<{
+    readonly message: string;
+    readonly limit: number;
+    readonly actual: number;
+    readonly limitType: "depth" | "complexity" | "aliases" | "fields";
+}> {
+}
+declare const ComplexityAnalysisError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ComplexityAnalysisError";
+} & Readonly<A>;
+/**
+ * Error thrown when complexity analysis fails
+ */
+export declare class ComplexityAnalysisError extends ComplexityAnalysisError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * Result of complexity analysis for a GraphQL operation
+ */
+export interface ComplexityResult {
+    /** Maximum depth of the query */
+    readonly depth: number;
+    /** Total complexity score */
+    readonly complexity: number;
+    /** Number of field selections (including nested) */
+    readonly fieldCount: number;
+    /** Number of aliased fields */
+    readonly aliasCount: number;
+}
+/**
+ * Information provided to complexity calculators
+ */
+export interface ComplexityAnalysisInfo {
+    /** Parsed GraphQL document */
+    readonly document: DocumentNode;
+    /** The operation being executed */
+    readonly operation: OperationDefinitionNode;
+    /** Variables provided with the query */
+    readonly variables?: Record<string, unknown>;
+    /** The GraphQL schema */
+    readonly schema: GraphQLSchema;
+    /** Field complexity definitions from the builder */
+    readonly fieldComplexities: FieldComplexityMap;
+}
+/**
+ * Information provided when complexity limit is exceeded
+ */
+export interface ComplexityExceededInfo {
+    /** The computed complexity result */
+    readonly result: ComplexityResult;
+    /** Which limit was exceeded */
+    readonly exceededLimit: "depth" | "complexity" | "aliases" | "fields";
+    /** The limit value */
+    readonly limit: number;
+    /** The actual value */
+    readonly actual: number;
+    /** The query that exceeded limits */
+    readonly query: string;
+    /** Operation name if provided */
+    readonly operationName?: string;
+}
+/**
+ * Complexity value for a field - can be static or dynamic based on arguments
+ */
+export type FieldComplexity = number | ((args: Record<string, unknown>) => number);
+/**
+ * Map of type.field -> complexity
+ */
+export type FieldComplexityMap = Map<string, FieldComplexity>;
+/**
+ * Custom complexity calculator function.
+ * Must be self-contained (no service requirements).
+ */
+export type ComplexityCalculator = (info: ComplexityAnalysisInfo) => Effect.Effect<ComplexityResult, ComplexityAnalysisError, never>;
+/**
+ * Configuration for query complexity limiting
+ */
+export interface ComplexityConfig {
+    /**
+     * Maximum allowed query depth.
+     * Depth is the deepest nesting level in the query.
+     * @example
+     * // Depth 3:
+     * // { user { posts { comments { text } } } }
+     */
+    readonly maxDepth?: number;
+    /**
+     * Maximum allowed total complexity score.
+     * Complexity is calculated by summing field costs.
+     */
+    readonly maxComplexity?: number;
+    /**
+     * Maximum number of field aliases allowed.
+     * Prevents response explosion attacks via aliases.
+     */
+    readonly maxAliases?: number;
+    /**
+     * Maximum total number of fields in the query.
+     * Includes all nested field selections.
+     */
+    readonly maxFields?: number;
+    /**
+     * Default complexity cost for fields without explicit costs.
+     * @default 1
+     */
+    readonly defaultFieldComplexity?: number;
+    /**
+     * Custom complexity calculator.
+     * If provided, this is used instead of the default calculator.
+     * Can be used to implement custom cost algorithms.
+     */
+    readonly calculator?: ComplexityCalculator;
+    /**
+     * Hook called when a limit is exceeded.
+     * Useful for logging, metrics, or custom handling.
+     * This is called BEFORE the error is thrown.
+     * Must be self-contained (no service requirements).
+     */
+    readonly onExceeded?: (info: ComplexityExceededInfo) => Effect.Effect<void, never, never>;
+}
+/**
+ * Default complexity calculator that walks the AST and computes:
+ * - depth: Maximum nesting level
+ * - complexity: Sum of field costs
+ * - fieldCount: Total number of field selections
+ * - aliasCount: Number of aliased fields
+ */
+export declare const defaultComplexityCalculator: (defaultCost?: number) => ComplexityCalculator;
+/**
+ * Validate query complexity against configured limits.
+ * Returns the complexity result if within limits, or fails with ComplexityLimitExceededError.
+ */
+export declare const validateComplexity: (query: string, operationName: string | undefined, variables: Record<string, unknown> | undefined, schema: GraphQLSchema, fieldComplexities: FieldComplexityMap, config: ComplexityConfig) => Effect.Effect<ComplexityResult, ComplexityLimitExceededError | ComplexityAnalysisError, never>;
+/**
+ * Effect Config for loading complexity configuration from environment variables.
+ *
+ * Environment variables:
+ * - GRAPHQL_MAX_DEPTH: Maximum query depth
+ * - GRAPHQL_MAX_COMPLEXITY: Maximum complexity score
+ * - GRAPHQL_MAX_ALIASES: Maximum number of aliases
+ * - GRAPHQL_MAX_FIELDS: Maximum number of fields
+ * - GRAPHQL_DEFAULT_FIELD_COMPLEXITY: Default field complexity (default: 1)
+ */
+export declare const ComplexityConfigFromEnv: Config.Config<ComplexityConfig>;
+/**
+ * A simple depth-only calculator that only tracks query depth.
+ * Use this when you only care about depth limiting and want fast validation.
+ */
+export declare const depthOnlyCalculator: ComplexityCalculator;
+/**
+ * Combine multiple calculators - returns the maximum values from all calculators.
+ */
+export declare const combineCalculators: (...calculators: ComplexityCalculator[]) => ComplexityCalculator;
+export {};
+//# sourceMappingURL=complexity.d.ts.map

package/dist/server/complexity.d.ts.map

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