@effect-gql/core 0.1.0

package/src/server/config.ts

@@ -0,0 +1,174 @@
+import { Config, Option } from "effect"
+import type { ComplexityConfig } from "./complexity"
+import type { CacheControlConfig } from "./cache-control"
+
+/**
+ * Configuration for the GraphiQL UI
+ */
+export interface GraphiQLConfig {
+  /** Path where GraphiQL UI is served (default: "/graphiql") */
+  readonly path: string
+  /** URL where GraphiQL sends requests (default: same as graphql path) */
+  readonly endpoint: string
+}
+
+/**
+ * Configuration for the GraphQL router
+ */
+export interface GraphQLRouterConfig {
+  /** Path for GraphQL endpoint (default: "/graphql") */
+  readonly path: string
+  /** GraphiQL configuration, or false to disable */
+  readonly graphiql: false | GraphiQLConfig
+  /** Query complexity limiting configuration */
+  readonly complexity?: ComplexityConfig
+  /** Enable introspection queries (default: true). Set to false in production. */
+  readonly introspection: boolean
+  /** Cache control configuration for HTTP Cache-Control headers */
+  readonly cacheControl?: CacheControlConfig
+}
+
+/**
+ * Default configuration values
+ */
+export const defaultConfig: GraphQLRouterConfig = {
+  path: "/graphql",
+  graphiql: false,
+  complexity: undefined,
+  introspection: true,
+  cacheControl: undefined,
+}
+
+/**
+ * Normalize user-provided config (which may use boolean shorthand for graphiql)
+ * into the full GraphQLRouterConfig format
+ */
+export interface GraphQLRouterConfigInput {
+  readonly path?: string
+  readonly graphiql?: boolean | Partial<GraphiQLConfig>
+  /** Query complexity limiting configuration */
+  readonly complexity?: ComplexityConfig
+  /** Enable introspection queries (default: true). Set to false in production. */
+  readonly introspection?: boolean
+  /** Cache control configuration for HTTP Cache-Control headers */
+  readonly cacheControl?: CacheControlConfig
+}
+
+export const normalizeConfig = (input: GraphQLRouterConfigInput = {}): GraphQLRouterConfig => {
+  const path = input.path ?? defaultConfig.path
+
+  let graphiql: false | GraphiQLConfig = false
+  if (input.graphiql === true) {
+    graphiql = { path: "/graphiql", endpoint: path }
+  } else if (input.graphiql && typeof input.graphiql === "object") {
+    graphiql = {
+      path: input.graphiql.path ?? "/graphiql",
+      endpoint: input.graphiql.endpoint ?? path,
+    }
+  }
+
+  return {
+    path,
+    graphiql,
+    complexity: input.complexity,
+    introspection: input.introspection ?? true,
+    cacheControl: input.cacheControl,
+  }
+}
+
+/**
+ * Effect Config for loading GraphQL router configuration from environment variables.
+ *
+ * Environment variables:
+ * - GRAPHQL_PATH: Path for GraphQL endpoint (default: "/graphql")
+ * - GRAPHQL_INTROSPECTION: Enable introspection queries (default: true)
+ * - GRAPHIQL_ENABLED: Enable GraphiQL UI (default: false)
+ * - GRAPHIQL_PATH: Path for GraphiQL UI (default: "/graphiql")
+ * - GRAPHIQL_ENDPOINT: URL where GraphiQL sends requests (default: same as GRAPHQL_PATH)
+ * - GRAPHQL_MAX_DEPTH: Maximum query depth (optional)
+ * - GRAPHQL_MAX_COMPLEXITY: Maximum complexity score (optional)
+ * - GRAPHQL_MAX_ALIASES: Maximum number of aliases (optional)
+ * - GRAPHQL_MAX_FIELDS: Maximum number of fields (optional)
+ * - GRAPHQL_DEFAULT_FIELD_COMPLEXITY: Default field complexity (default: 1)
+ * - GRAPHQL_CACHE_CONTROL_ENABLED: Enable cache control headers (default: false)
+ * - 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)
+ */
+export const GraphQLRouterConfigFromEnv: Config.Config<GraphQLRouterConfig> = Config.all({
+  path: Config.string("GRAPHQL_PATH").pipe(Config.withDefault("/graphql")),
+  introspection: Config.boolean("GRAPHQL_INTROSPECTION").pipe(Config.withDefault(true)),
+  graphiqlEnabled: Config.boolean("GRAPHIQL_ENABLED").pipe(Config.withDefault(false)),
+  graphiqlPath: Config.string("GRAPHIQL_PATH").pipe(Config.withDefault("/graphiql")),
+  graphiqlEndpoint: Config.string("GRAPHIQL_ENDPOINT").pipe(Config.option),
+  maxDepth: Config.number("GRAPHQL_MAX_DEPTH").pipe(Config.option),
+  maxComplexity: Config.number("GRAPHQL_MAX_COMPLEXITY").pipe(Config.option),
+  maxAliases: Config.number("GRAPHQL_MAX_ALIASES").pipe(Config.option),
+  maxFields: Config.number("GRAPHQL_MAX_FIELDS").pipe(Config.option),
+  defaultFieldComplexity: Config.number("GRAPHQL_DEFAULT_FIELD_COMPLEXITY").pipe(
+    Config.withDefault(1)
+  ),
+  cacheControlEnabled: Config.boolean("GRAPHQL_CACHE_CONTROL_ENABLED").pipe(
+    Config.withDefault(false)
+  ),
+  cacheControlDefaultMaxAge: Config.number("GRAPHQL_CACHE_CONTROL_DEFAULT_MAX_AGE").pipe(
+    Config.withDefault(0)
+  ),
+  cacheControlDefaultScope: Config.string("GRAPHQL_CACHE_CONTROL_DEFAULT_SCOPE").pipe(
+    Config.withDefault("PUBLIC")
+  ),
+}).pipe(
+  Config.map(
+    ({
+      path,
+      introspection,
+      graphiqlEnabled,
+      graphiqlPath,
+      graphiqlEndpoint,
+      maxDepth,
+      maxComplexity,
+      maxAliases,
+      maxFields,
+      defaultFieldComplexity,
+      cacheControlEnabled,
+      cacheControlDefaultMaxAge,
+      cacheControlDefaultScope,
+    }) => {
+      // Check if any complexity option is set
+      const hasComplexity =
+        Option.isSome(maxDepth) ||
+        Option.isSome(maxComplexity) ||
+        Option.isSome(maxAliases) ||
+        Option.isSome(maxFields)
+
+      return {
+        path,
+        introspection,
+        graphiql: graphiqlEnabled
+          ? {
+              path: graphiqlPath,
+              endpoint: Option.isSome(graphiqlEndpoint) ? graphiqlEndpoint.value : path,
+            }
+          : (false as const),
+        complexity: hasComplexity
+          ? {
+              maxDepth: Option.getOrUndefined(maxDepth),
+              maxComplexity: Option.getOrUndefined(maxComplexity),
+              maxAliases: Option.getOrUndefined(maxAliases),
+              maxFields: Option.getOrUndefined(maxFields),
+              defaultFieldComplexity,
+            }
+          : undefined,
+        cacheControl: cacheControlEnabled
+          ? {
+              enabled: true,
+              defaultMaxAge: cacheControlDefaultMaxAge,
+              defaultScope: (cacheControlDefaultScope === "PRIVATE"
+                ? "PRIVATE"
+                : "PUBLIC") as import("../builder/types").CacheControlScope,
+              calculateHttpHeaders: true,
+            }
+          : undefined,
+      }
+    }
+  )
+)

package/src/server/graphiql.ts

@@ -0,0 +1,38 @@
+/**
+ * Generate HTML for GraphiQL IDE, loading dependencies from CDN
+ */
+export const graphiqlHtml = (endpoint: string): string => `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>GraphiQL</title>
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/graphiql@3/graphiql.min.css"
+    />
+  </head>
+  <body style="margin: 0; overflow: hidden;">
+    <div id="graphiql" style="height: 100vh;"></div>
+    <script
+      crossorigin
+      src="https://unpkg.com/react@18/umd/react.production.min.js"
+    ></script>
+    <script
+      crossorigin
+      src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
+    ></script>
+    <script
+      crossorigin
+      src="https://unpkg.com/graphiql@3/graphiql.min.js"
+    ></script>
+    <script>
+      const fetcher = GraphiQL.createFetcher({
+        url: ${JSON.stringify(endpoint)},
+      });
+      ReactDOM.createRoot(document.getElementById('graphiql')).render(
+        React.createElement(GraphiQL, { fetcher })
+      );
+    </script>
+  </body>
+</html>`

package/src/server/index.ts

@@ -0,0 +1,96 @@
+// Configuration types and utilities
+export type { GraphiQLConfig, GraphQLRouterConfig, GraphQLRouterConfigInput } from "./config"
+
+export { defaultConfig, normalizeConfig, GraphQLRouterConfigFromEnv } from "./config"
+
+// GraphiQL HTML generator
+export { graphiqlHtml } from "./graphiql"
+
+// Router factory
+export {
+  makeGraphQLRouter,
+  defaultErrorHandler,
+  type MakeGraphQLRouterOptions,
+  type ErrorHandler,
+} from "./router"
+
+// Schema builder extension
+export { toRouter } from "./schema-builder-extensions"
+
+// Complexity limiting
+export type {
+  ComplexityConfig,
+  ComplexityResult,
+  ComplexityAnalysisInfo,
+  ComplexityExceededInfo,
+  ComplexityCalculator,
+  FieldComplexity,
+  FieldComplexityMap,
+} from "./complexity"
+
+export {
+  ComplexityLimitExceededError,
+  ComplexityAnalysisError,
+  validateComplexity,
+  defaultComplexityCalculator,
+  depthOnlyCalculator,
+  combineCalculators,
+  ComplexityConfigFromEnv,
+} from "./complexity"
+
+// Cache control
+export type {
+  CacheHintMap,
+  CachePolicy,
+  CacheControlConfig,
+  CachePolicyAnalysisInfo,
+} from "./cache-control"
+
+export {
+  computeCachePolicy,
+  computeCachePolicyFromQuery,
+  toCacheControlHeader,
+  CacheControlConfigFromEnv,
+} from "./cache-control"
+
+// WebSocket subscription support
+export type {
+  EffectWebSocket,
+  CloseEvent,
+  ConnectionContext,
+  GraphQLWSOptions,
+  GraphQLWSConfig,
+  SubscribeMessage,
+  CompleteMessage,
+} from "./ws-types"
+
+export { WebSocketError } from "./ws-types"
+
+export { makeGraphQLWSHandler } from "./ws-adapter"
+
+// WebSocket utilities for 'ws' library integration
+export type { WsWebSocket } from "./ws-utils"
+export { toEffectWebSocketFromWs, WS_CLOSED } from "./ws-utils"
+
+// SSE (Server-Sent Events) subscription support
+export type {
+  EffectSSE,
+  SSEEvent,
+  SSEEventType,
+  SSESubscriptionRequest,
+  SSEConnectionContext,
+  GraphQLSSEOptions,
+  GraphQLSSEConfig,
+  SSESubscriptionResult,
+} from "./sse-types"
+
+export {
+  SSEError,
+  SSE_HEADERS,
+  formatNextEvent,
+  formatErrorEvent,
+  formatCompleteEvent,
+  formatSSEMessage,
+} from "./sse-types"
+
+export { makeSSESubscriptionStream, makeGraphQLSSEHandler } from "./sse-adapter"