@flightdev/graphql 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @flight-framework/graphql
+
+GraphQL adapter for Flight Framework. Optional, non-imposing - use it only if you need GraphQL.
+
+## Installation
+
+```bash
+npm install @flight-framework/graphql graphql graphql-yoga
+```
+
+## Quick Start
+
+Create a GraphQL endpoint in your Flight app:
+
+```typescript
+// src/routes/api/graphql.ts
+import { createGraphQLHandler } from '@flight-framework/graphql';
+import { yogaAdapter } from '@flight-framework/graphql/yoga';
+import { schema } from '../../graphql/schema';
+
+const handler = createGraphQLHandler({
+  adapter: yogaAdapter(),
+  schema,
+});
+
+export const GET = handler;
+export const POST = handler;
+```
+
+## Creating a Schema
+
+### Code-First (Recommended)
+
+```typescript
+// src/graphql/schema.ts
+import { createSchema } from 'graphql-yoga';
+
+export const schema = createSchema({
+  typeDefs: /* GraphQL */ `
+    type Query {
+      hello(name: String): String!
+      users: [User!]!
+    }
+    
+    type User {
+      id: ID!
+      name: String!
+      email: String!
+    }
+  `,
+  resolvers: {
+    Query: {
+      hello: (_, { name }) => `Hello ${name || 'World'}`,
+      users: () => db.users.findMany(),
+    },
+  },
+});
+```
+
+### Schema-First
+
+```typescript
+import { buildSchema } from 'graphql';
+import { createGraphQLHandler } from '@flight-framework/graphql';
+import { yogaAdapter } from '@flight-framework/graphql/yoga';
+
+const schema = buildSchema(/* GraphQL */ `
+  type Query {
+    hello: String
+  }
+`);
+
+const rootValue = {
+  hello: () => 'Hello World',
+};
+
+export const POST = createGraphQLHandler({
+  adapter: yogaAdapter({ rootValue }),
+  schema,
+});
+```
+
+## Context
+
+Pass request context to resolvers:
+
+```typescript
+const handler = createGraphQLHandler({
+  adapter: yogaAdapter(),
+  schema,
+  context: async (req) => {
+    const token = req.headers.get('Authorization');
+    const user = token ? await verifyToken(token) : null;
+    return { user, db };
+  },
+});
+```
+
+Access in resolvers:
+
+```typescript
+const resolvers = {
+  Query: {
+    me: (_, __, ctx) => ctx.user,
+    posts: (_, __, ctx) => ctx.db.posts.findMany(),
+  },
+};
+```
+
+## GraphiQL
+
+GraphiQL is enabled by default in development. Access it at your endpoint URL.
+
+To disable:
+
+```typescript
+const handler = createGraphQLHandler({
+  adapter: yogaAdapter({ graphiql: false }),
+  schema,
+});
+```
+
+## Adapters
+
+### GraphQL Yoga (Default)
+
+```typescript
+import { yogaAdapter } from '@flight-framework/graphql/yoga';
+```
+
+Yoga is the recommended adapter - modern, lightweight, full fetch API support.
+
+### Apollo (Coming Soon)
+
+```typescript
+import { apolloAdapter } from '@flight-framework/graphql/apollo';
+```
+
+## TypeScript
+
+Full TypeScript support with type inference:
+
+```typescript
+import type { GraphQLContext, GraphQLAdapter } from '@flight-framework/graphql';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { GraphQLSchema } from 'graphql';
+export { ExecutionResult, GraphQLSchema } from 'graphql';
+
+/**
+ * @flightdev/graphql
+ *
+ * GraphQL adapter for Flight Framework.
+ * Optional, non-imposing - use it only if you need GraphQL.
+ */
+
+/**
+ * Context factory function type
+ */
+type ContextFactory<TContext = Record<string, unknown>> = (request: Request) => TContext | Promise<TContext>;
+/**
+ * Configuration for GraphQL adapters
+ */
+interface GraphQLAdapterConfig<TContext = Record<string, unknown>> {
+    /** GraphQL schema */
+    schema: GraphQLSchema;
+    /** Context factory for resolvers */
+    context?: ContextFactory<TContext>;
+    /** Root value for schema-first approach */
+    rootValue?: unknown;
+}
+/**
+ * GraphQL handler function type
+ *
+ * Uses rest parameters with `any[]` to accommodate different GraphQL server
+ * implementations with varying signatures:
+ * - GraphQL Yoga: `fetch(request, serverContext?)` with overloaded variants
+ * - Apollo: `executeHTTPGraphQLRequest(request)`
+ * - Other implementations may differ
+ *
+ * This is an intentional TypeScript escape hatch - the adapter pattern provides
+ * type safety at the public API boundaries (createGraphQLHandler), while allowing
+ * internal flexibility for wrapping third-party libraries.
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any
+ */
+type GraphQLHandler = (request: Request, ...serverContext: any[]) => Response | Promise<Response>;
+/**
+ * GraphQL adapter interface
+ *
+ * Implement this interface to add support for different GraphQL servers.
+ */
+interface GraphQLAdapter {
+    /** Adapter name for debugging */
+    readonly name: string;
+    /**
+     * Create a request handler from the adapter config
+     */
+    createHandler<TContext = Record<string, unknown>>(config: GraphQLAdapterConfig<TContext>): GraphQLHandler;
+}
+/**
+ * Options for createGraphQLHandler
+ */
+interface CreateGraphQLHandlerOptions<TContext = Record<string, unknown>> {
+    /** The GraphQL adapter to use */
+    adapter: GraphQLAdapter;
+    /** GraphQL schema */
+    schema: GraphQLSchema;
+    /** Context factory for resolvers */
+    context?: ContextFactory<TContext>;
+    /** Root value for schema-first approach */
+    rootValue?: unknown;
+}
+/**
+ * Create a GraphQL request handler
+ *
+ * @example
+ * ```typescript
+ * import { createGraphQLHandler } from '@flightdev/graphql';
+ * import { yogaAdapter } from '@flightdev/graphql/yoga';
+ * import { schema } from './schema';
+ *
+ * const handler = createGraphQLHandler({
+ *   adapter: yogaAdapter(),
+ *   schema,
+ *   context: (req) => ({ user: getUser(req) }),
+ * });
+ *
+ * export const GET = handler;
+ * export const POST = handler;
+ * ```
+ */
+declare function createGraphQLHandler<TContext = Record<string, unknown>>(options: CreateGraphQLHandlerOptions<TContext>): GraphQLHandler;
+/**
+ * Type helper for GraphQL context
+ */
+type GraphQLContext<T = Record<string, unknown>> = T;
+
+export { type ContextFactory, type CreateGraphQLHandlerOptions, type GraphQLAdapter, type GraphQLAdapterConfig, type GraphQLContext, type GraphQLHandler, createGraphQLHandler };

package/dist/index.js

@@ -0,0 +1,11 @@
+// src/index.ts
+function createGraphQLHandler(options) {
+  const { adapter, schema, context, rootValue } = options;
+  return adapter.createHandler({
+    schema,
+    context,
+    rootValue
+  });
+}
+
+export { createGraphQLHandler };

package/dist/yoga.d.ts

@@ -0,0 +1,66 @@
+import { YogaServerOptions } from 'graphql-yoga';
+export { createSchema } from 'graphql-yoga';
+import { GraphQLAdapter } from './index.js';
+import 'graphql';
+
+/**
+ * GraphQL Yoga Adapter for Flight Framework
+ *
+ * @example
+ * ```typescript
+ * import { createGraphQLHandler } from '@flightdev/graphql';
+ * import { yogaAdapter } from '@flightdev/graphql/yoga';
+ *
+ * const handler = createGraphQLHandler({
+ *   adapter: yogaAdapter(),
+ *   schema,
+ * });
+ * ```
+ */
+
+/**
+ * Options specific to the Yoga adapter
+ */
+interface YogaAdapterOptions {
+    /** Enable/disable GraphiQL interface (default: true in development) */
+    graphiql?: boolean | {
+        title?: string;
+        defaultQuery?: string;
+    };
+    /** CORS configuration (passed directly to Yoga) */
+    cors?: boolean | Record<string, unknown>;
+    /** Enable/disable logging */
+    logging?: boolean;
+    /** Mask errors in production */
+    maskedErrors?: boolean;
+    /** Custom plugins */
+    plugins?: YogaServerOptions<Record<string, unknown>, Record<string, unknown>>['plugins'];
+}
+/**
+ * Create a GraphQL Yoga adapter
+ *
+ * Yoga is the recommended GraphQL server for Flight:
+ * - Modern, lightweight, full fetch API support
+ * - Built-in GraphiQL, CORS, file uploads
+ * - Excellent TypeScript support
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * yogaAdapter()
+ *
+ * // With options
+ * yogaAdapter({
+ *   graphiql: { title: 'My API' },
+ *   cors: { origin: 'https://myapp.com' },
+ * })
+ *
+ * // Disable GraphiQL in production
+ * yogaAdapter({
+ *   graphiql: process.env.NODE_ENV !== 'production',
+ * })
+ * ```
+ */
+declare function yogaAdapter(options?: YogaAdapterOptions): GraphQLAdapter;
+
+export { type YogaAdapterOptions, yogaAdapter };

package/dist/yoga.js

@@ -0,0 +1,39 @@
+import { createYoga } from 'graphql-yoga';
+export { createSchema } from 'graphql-yoga';
+
+// src/yoga.ts
+function yogaAdapter(options = {}) {
+  const {
+    graphiql = true,
+    cors,
+    logging = false,
+    maskedErrors = true,
+    plugins = []
+  } = options;
+  return {
+    name: "graphql-yoga",
+    createHandler(config) {
+      const yoga = createYoga({
+        schema: config.schema,
+        // Context factory
+        context: config.context ? async ({ request }) => {
+          const ctx = await config.context(request);
+          return ctx;
+        } : void 0,
+        // GraphiQL configuration
+        graphiql: graphiql === true ? { title: "Flight GraphQL" } : graphiql === false ? false : graphiql,
+        // CORS - use simple default
+        cors: cors ?? true,
+        // Logging
+        logging,
+        // Error masking
+        maskedErrors,
+        // Plugins
+        plugins
+      });
+      return yoga.fetch.bind(yoga);
+    }
+  };
+}
+
+export { yogaAdapter };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@flightdev/graphql",
+  "version": "0.1.0",
+  "description": "GraphQL adapter for Flight Framework - optional, non-imposing",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./yoga": {
+      "types": "./dist/yoga.d.ts",
+      "import": "./dist/yoga.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "graphql": "^16.0.0",
+    "graphql-yoga": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "graphql-yoga": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "graphql": "^16.9.0",
+    "graphql-yoga": "^5.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "flight",
+    "graphql",
+    "yoga",
+    "adapter"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}