@lde/search-api-graphql 0.11.0 → 0.12.0

package/README.md

@@ -59,6 +59,60 @@ const gqlSchema = buildGraphQLSchema(searchSchema(DATASET, PERSON), {
 Shared types (`LanguageString`, the facet buckets, filter inputs and reference
 types such as a common `Agent`) are created once and reused across root types.
 
+## Serving the API
+
+`createSearchGraphQLHandler` turns the schema into a **served API**: one
+framework-agnostic `(request: Request) => Promise<Response>` handler (built on
+[graphql-yoga](https://the-guild.dev/graphql/yoga-server), see
+[ADR 14](../../docs/decisions/0014-serve-the-search-graphql-api-with-graphql-yoga.md))
+covering POST execution, introspection, error shaping and per-request
+`Accept-Language` parsing:
+
+```ts
+import { createSearchGraphQLHandler } from '@lde/search-api-graphql';
+
+const handler = createSearchGraphQLHandler({
+  searchSchema: searchSchema(DATASET, PERSON),
+  engine, // e.g. createTypesenseSearchEngine(…)
+});
+
+// SvelteKit (src/routes/graphql/+server.ts):
+export const GET = ({ request }) => handler(request);
+export const POST = GET;
+
+// Plain node:http:
+import { createServerAdapter } from '@whatwg-node/server';
+createServer(createServerAdapter(handler)).listen(4000);
+```
+
+Every host that speaks `Request`/`Response` (SvelteKit, Hono, Fastify via a
+bridge, plain Node) mounts it the same way. Batteries included:
+
+- **Playground**: `GET /graphql` serves the bundled GraphiQL –
+  self-contained (no external CDN) and sent without framing headers, so a docs
+  site can `<iframe>` the deployed playground as a live client. Disable it per
+  environment (`playground: false`) or swap the renderer (`renderPlayground`).
+- **SDL**: `GET /graphql?sdl` returns the schema contract as SDL – publish it
+  or generate static docs in CI without a running introspection query.
+- **CORS** for cross-origin browser clients (configurable via `cors`).
+- **Depth and cost limits** ([graphql-armor](https://escape.tech/graphql-armor/);
+  `maxDepth`, default 15, and `maxCost`, default 5000) guard the public
+  endpoint against arbitrarily expensive queries; introspection stays exempt.
+
+To serve **custom fields next to the generated search API**, merge your own
+schema with `buildGraphQLSchema()`’s output (e.g. `@graphql-tools/schema`’s
+`mergeSchemas`) and pass the union as `schema` instead of `searchSchema`; the
+same endpoint and playground serve both:
+
+```ts
+const handler = createSearchGraphQLHandler({
+  schema: mergeSchemas({
+    schemas: [buildGraphQLSchema(searchSchema(DATASET)), myCustomSchema],
+  }),
+  engine,
+});
+```
+
 ## Serving a subset of the schema
 
 `types` never filters: every `SearchType` in the schema you pass gets a root

package/dist/handler.d.ts

@@ -0,0 +1,72 @@
+import { type GraphQLSchema } from 'graphql';
+import { type CORSOptions, type GraphiQLOptions } from 'graphql-yoga';
+import type { SearchEngine, SearchSchema } from '@lde/search';
+import { type BuildGraphQLSchemaOptions, type SearchContext } from './build-schema.js';
+/**
+ * A framework-agnostic request handler: SvelteKit, Fastify (via a
+ * `Request`/`Response` bridge), Hono and plain `node:http` (via
+ * `@whatwg-node/server`, which graphql-yoga uses internally) all mount it
+ * directly.
+ */
+export type SearchGraphQLHandler = (request: Request) => Promise<Response>;
+/**
+ * Renders the playground page served on `GET` requests to the endpoint.
+ * The default is the self-contained GraphiQL bundled with graphql-yoga
+ * (no external CDN); supply your own to swap the renderer (e.g. Altair).
+ */
+export type PlaygroundRenderer = (options?: GraphiQLOptions) => BodyInit | Promise<BodyInit>;
+export interface SearchGraphQLHandlerOptions {
+    /**
+     * The search schema to serve; the handler builds the GraphQL schema from it
+     * with {@link buildGraphQLSchema}. Provide either this or {@link schema}.
+     */
+    readonly searchSchema?: SearchSchema;
+    /**
+     * A ready {@link GraphQLSchema} to serve instead – bring your own fields by
+     * merging a custom schema with {@link buildGraphQLSchema}’s output (e.g.
+     * `@graphql-tools/schema` `mergeSchemas`) and passing the union here.
+     * Provide either this or {@link searchSchema}.
+     */
+    readonly schema?: GraphQLSchema;
+    /** The engine every request’s resolvers search with. */
+    readonly engine: SearchEngine;
+    /** Options for {@link buildGraphQLSchema} when {@link searchSchema} is given. */
+    readonly schemaOptions?: BuildGraphQLSchemaOptions;
+    /** Endpoint path the handler serves. @default '/graphql' */
+    readonly graphqlEndpoint?: string;
+    /**
+     * Serve the playground on `GET` requests to the endpoint. The page is
+     * self-contained (no external CDN) and sends no framing headers, so a docs
+     * site can `<iframe>` it as a live client. Disable per environment.
+     * @default true
+     */
+    readonly playground?: boolean;
+    /** Custom playground renderer; defaults to the bundled GraphiQL. */
+    readonly renderPlayground?: PlaygroundRenderer;
+    /**
+     * CORS headers for cross-origin browser clients. Defaults to graphql-yoga’s
+     * permissive default (reflects the request origin); pass `false` to send no
+     * CORS headers.
+     */
+    readonly cors?: CORSOptions | boolean;
+    /**
+     * Reject queries nested deeper than this – a public playground invites
+     * arbitrary queries. Introspection is exempt. @default 15
+     */
+    readonly maxDepth?: number;
+    /**
+     * Reject queries costlier than this (graphql-armor cost limit; introspection
+     * is exempt). @default 5000
+     */
+    readonly maxCost?: number;
+    /** Forwarded to {@link SearchContext.onFacetError} on every request. */
+    readonly onFacetError?: SearchContext['onFacetError'];
+}
+/**
+ * The served search API: one `fetch` handler covering POST execution, the GET
+ * playground, introspection, CORS, depth/cost limits, `Accept-Language`
+ * parsing, and the SDL (`GET <endpoint>?sdl` – the schema contract without a
+ * running introspection query).
+ */
+export declare function createSearchGraphQLHandler(options: SearchGraphQLHandlerOptions): SearchGraphQLHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,CAAC,EAAE,eAAe,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACvD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CA2CtB"}

package/dist/handler.js

@@ -0,0 +1,60 @@
+import { printSchema } from 'graphql';
+import { createYoga, } from 'graphql-yoga';
+import { renderGraphiQL } from '@graphql-yoga/render-graphiql';
+import { maxDepthPlugin } from '@escape.tech/graphql-armor-max-depth';
+import { costLimitPlugin } from '@escape.tech/graphql-armor-cost-limit';
+import Negotiator from 'negotiator';
+import { buildGraphQLSchema, } from './build-schema.js';
+/**
+ * The served search API: one `fetch` handler covering POST execution, the GET
+ * playground, introspection, CORS, depth/cost limits, `Accept-Language`
+ * parsing, and the SDL (`GET <endpoint>?sdl` – the schema contract without a
+ * running introspection query).
+ */
+export function createSearchGraphQLHandler(options) {
+    if ((options.searchSchema === undefined) === (options.schema === undefined)) {
+        throw new Error('Provide exactly one of searchSchema or schema.');
+    }
+    const schema = options.schema ??
+        buildGraphQLSchema(options.searchSchema, options.schemaOptions);
+    const graphqlEndpoint = options.graphqlEndpoint ?? '/graphql';
+    const yoga = createYoga({
+        schema,
+        graphqlEndpoint,
+        landingPage: false,
+        graphiql: options.playground !== false,
+        renderGraphiQL: options.renderPlayground ?? renderGraphiQL,
+        cors: options.cors,
+        plugins: [
+            maxDepthPlugin({ n: options.maxDepth ?? 15 }),
+            costLimitPlugin({ maxCost: options.maxCost ?? 5000 }),
+        ],
+        context: ({ request }) => ({
+            engine: options.engine,
+            acceptLanguage: parseAcceptLanguage(request.headers.get('accept-language')),
+            onFacetError: options.onFacetError,
+        }),
+    });
+    const sdl = printSchema(schema);
+    return async (request) => {
+        const url = new URL(request.url);
+        if (request.method === 'GET' &&
+            url.pathname === graphqlEndpoint &&
+            url.searchParams.has('sdl')) {
+            return new Response(sdl, {
+                headers: { 'content-type': 'application/graphql; charset=utf-8' },
+            });
+        }
+        return await yoga.fetch(request, {});
+    };
+}
+/** Ordered languages from an `Accept-Language` header (best first, by q-value). */
+function parseAcceptLanguage(header) {
+    if (header === null) {
+        return [];
+    }
+    const negotiator = new Negotiator({
+        headers: { 'accept-language': header },
+    });
+    return negotiator.languages().filter((language) => language !== '*');
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { buildGraphQLSchema, printGraphQLSchema } from './build-schema.js';
+export { createSearchGraphQLHandler } from './handler.js';
+export type { SearchGraphQLHandler, SearchGraphQLHandlerOptions, PlaygroundRenderer, } from './handler.js';
 export type { SearchContext, BuildGraphQLSchemaOptions, SearchTypeOptions, } from './build-schema.js';
 export { defaultLanguageOrder } from './language.js';
 export type { LanguageString, LanguageOrder } from './language.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EACV,oBAAoB,EACpB,2BAA2B,EAC3B,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { buildGraphQLSchema, printGraphQLSchema } from './build-schema.js';
+export { createSearchGraphQLHandler } from './handler.js';
 export { defaultLanguageOrder } from './language.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.11.0",
-  "description": "Engine- and domain-agnostic GraphQL surface for @lde/search: builds an executable GraphQLSchema from a whole SearchSchema at runtime (no codegen) — one root query field per SearchType — served by generic resolvers over any SearchEngine. You supply the schema and per-type typeNames; it names neither your domain nor your engine.",
+  "version": "0.12.0",
+  "description": "Engine- and domain-agnostic GraphQL surface for @lde/search: builds an executable GraphQLSchema from a whole SearchSchema at runtime (no codegen) – one root query field per SearchType – served by generic resolvers over any SearchEngine – and serves it as a framework-agnostic fetch handler with a self-contained playground, SDL endpoint, CORS and depth/cost limits. You supply the schema and per-type typeNames; it names neither your domain nor your engine.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/search-api-graphql"
@@ -25,9 +25,14 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
+    "@escape.tech/graphql-armor-cost-limit": "^2.4.3",
+    "@escape.tech/graphql-armor-max-depth": "^2.4.2",
+    "@graphql-yoga/render-graphiql": "^5.21.2",
     "@lde/search": "^0.12.0",
     "dataloader": "^2.2.3",
-    "graphql": "^15.8.0",
+    "graphql": "^16.0.0",
+    "graphql-yoga": "^5.21.2",
+    "negotiator": "^0.6.4",
     "tslib": "^2.3.0"
   }
 }