@lde/search-api-graphql 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @lde/search-api-graphql
+
+The GraphQL surface for the [`@lde/search`](../search) core. **Both engine- and
+domain-agnostic:** it builds an executable
+[graphql-js](https://graphql.org/graphql-js/) `GraphQLSchema` from your whole
+[`SearchSchema`](../search/README.md#terminology) at runtime — one root query
+field per `SearchType`, each searchable in its own way. All root fields are
+served by the same resolver implementation (no per-type code, no codegen);
+each root field gets its own instance of it, bound to that field’s
+`SearchType`, over any `SearchEngine`. It names neither your **domain** (each type’s GraphQL name
+is the `SearchType`’s own logical `name` — `Dataset`, `Person`, `CreativeWork`,
+…) nor your **engine** (the resolver calls the schema-bound `context.engine`, be it
+[`@lde/search-typesense`](../search-typesense) or another adapter).
+
+## Runtime configuration, not codegen
+
+`buildGraphQLSchema(schema)` constructs the GraphQL schema once at startup from
+the field model — no SDL artifact, no generated resolver stubs. For you that
+means: no codegen step in the build, no generated files to commit and review,
+and no stale artifact that can drift from the declaration — change the
+`SearchType`, restart, and the API is current. (The flip side, no artifact
+showing contract changes as diffs, is restored by the
+[snapshot guard](#guarding-the-contract).) The field model
+is the single source; the GraphQL contract is derived from it. Type names
+come from each `SearchType`’s `name`; output types, the `where`/`orderBy`/facet
+inputs, reference types and nullability are all derived from each field’s
+`kind` and capability flags. The common case needs no options at all:
+
+```ts
+import { searchSchema } from '@lde/search';
+import { buildGraphQLSchema } from '@lde/search-api-graphql';
+
+const gqlSchema = buildGraphQLSchema(searchSchema(DATASET, PERSON));
+
+// The API now serves `datasets(…)` and `persons(…)` root fields.
+// Hand `gqlSchema` to any graphql-js server; populate the per-request context:
+//   { engine: SearchEngine, acceptLanguage: string[] }
+```
+
+Per-type options are pure fine-tuning, only for the types that need it: a
+`queryField` when the default root field (the lowercased plural of the type’s
+`name`) is wrong, and a `queryDefaults` policy applied to every query of that
+type:
+
+```ts
+const gqlSchema = buildGraphQLSchema(searchSchema(DATASET, PERSON), {
+  types: {
+    Dataset: {
+      queryDefaults: (query) => ({
+        ...query,
+        where: [...query.where, { field: 'status', in: ['valid'] }],
+      }),
+    },
+    Person: { queryField: 'people' },
+  },
+});
+```
+
+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 a subset of the schema
+
+`types` never filters: every `SearchType` in the schema you pass gets a root
+field (options for a type not in the schema are a build-time error). To expose
+only part of what you index, narrow the **schema argument**
+(`searchSchema(…)` is a cheap constructor):
+
+```ts
+// Index all three types…
+projectGraph(quads, searchSchema(DATASET, PERSON, INTERNAL));
+
+// …but serve only two.
+const gqlSchema = buildGraphQLSchema(searchSchema(DATASET, PERSON));
+```
+
+## What it builds (per root type)
+
+- **Output type** (the `SearchType`’s `name`): localized text → best-first `[LanguageString!]!`
+  (`[0].language` is the language actually served); references → named per-shape
+  types (`Organization`, `Term`) with a `name`; scalars/booleans per kind; `date`
+  → ISO 8601 string; nullability from `required` / `array` / `kind`.
+- **`where`** one input per `filterable` field (`StringFilter`, `IntRange` /
+  `FloatRange` / `DateRange`, or `Boolean`); omitted entirely for a type with no
+  filterable fields.
+- **`orderBy`**: `RELEVANCE` plus every `sortable` field, as an enum.
+- **Facets**: an enum of every `facetable` field; a bucket carries `value` +
+  `count` + a nullable `label` — the resolved data label for **reference** facets,
+  `null` for token/free-string facets whose display the consumer owns (its own
+  i18n, or the value itself).
+
+## Guarding the contract
+
+Why the API, the index and a future REST surface cannot drift apart is the
+search family’s overall approach — one field model, one query IR — described
+in [`@lde/search`](../search/README.md). Specific to this surface: the GraphQL
+contract is **frozen** (breaking to change), yet generated rather than
+handwritten, so nothing in the repo shows a contract change as a reviewable
+diff. A _consumer_ restores that with one snapshot test over its **own**
+search schema:
+
+```ts
+import { printGraphQLSchema } from '@lde/search-api-graphql';
+
+it('keeps the public GraphQL contract stable', () => {
+  expect(printGraphQLSchema(searchSchema(DATASET, PERSON))).toMatchSnapshot();
+});
+```
+
+The first run writes the emitted SDL to a committed snapshot file; every later
+run re-emits and diffs against it. Any contract change — your own schema edit,
+or a new version of this library emitting different GraphQL for the same
+declaration — fails the test and shows the SDL diff, until you consciously
+accept it (`vitest -u`) and the reviewer sees the contract change spelled out
+in the PR.

package/dist/build-schema.d.ts

@@ -0,0 +1,59 @@
+import { GraphQLSchema } from 'graphql';
+import { type SearchEngine, type SearchQuery, type SearchSchema } from '@lde/search';
+import { type LanguageOrder } from './language.js';
+/** Populated per request by the transport; no framework type appears here. */
+export interface SearchContext {
+    /** The deployment’s engine, bound to the whole {@link SearchSchema} at
+     *  construction; the resolvers pass each root field’s search type per call
+     *  and the engine routes it to its collection. */
+    readonly engine: SearchEngine;
+    /** Parsed, ordered `Accept-Language`; drives locale selection and output order. */
+    readonly acceptLanguage: readonly string[];
+    /**
+     * Called when a single facet's computation fails. The facet degrades to an
+     * empty list (a supplementary facet must not fail the whole query); supply
+     * this to log the cause. Optional — omit to swallow silently.
+     */
+    readonly onFacetError?: (field: string, error: unknown) => void;
+}
+/** Per-root-type fine-tuning. The type’s name comes from the {@link SearchType}
+ *  itself (`name`); options exist only for what has a sensible default. */
+export interface SearchTypeOptions {
+    /** Root query field; defaults to the lowercased plural of the type’s `name`
+     *  (e.g. `Dataset` → `datasets`). */
+    readonly queryField?: string;
+    /** Consumer policy applied to every query of this type (default status, sort,
+     *  tie-breaks). */
+    readonly queryDefaults?: (query: SearchQuery, context: SearchContext) => SearchQuery;
+}
+export interface BuildGraphQLSchemaOptions {
+    /** Optional fine-tuning per root type, keyed by the {@link SearchType}
+     *  `name` (the logical API name, e.g. `Dataset`) — the key a consumer knows
+     *  the type by. A type without an entry gets the defaults. */
+    readonly types?: Readonly<Record<string, SearchTypeOptions>>;
+    /** Output-language ordering; defaults to Accept-Language-first, `und` last. */
+    readonly languageOrder?: LanguageOrder;
+    /** Upper bound for the `perPage` argument (default 100). A request outside
+     *  `1 ≤ perPage ≤ maxPerPage` or with `page < 1` is rejected with a clear
+     *  error instead of reaching the engine. */
+    readonly maxPerPage?: number;
+}
+/**
+ * Construct an executable GraphQL schema from the whole {@link SearchSchema} at
+ * runtime — no codegen, no SDL artifact. One root query field per
+ * {@link SearchType} (e.g. `datasets`, `people`), each searchable in its own
+ * way through its own output/`where`/`orderBy`/facet types, while the shared
+ * types (`LanguageString`, buckets, filter inputs, reference types) are created
+ * once. One generic resolver per root field maps the arguments to a
+ * {@link SearchQuery}, calls `context.engine`, and maps the result back; the
+ * field model only parameterises data.
+ */
+export declare function buildGraphQLSchema(schema: SearchSchema, options?: BuildGraphQLSchemaOptions): GraphQLSchema;
+/**
+ * The SDL of the built schema. Not a shipped artifact — a consumer uses it for an
+ * optional CI snapshot test over its own schema, catching accidental breaking
+ * changes to its frozen contract (including a `buildGraphQLSchema` change in a
+ * future version of this library silently altering it).
+ */
+export declare function printGraphQLSchema(schema: SearchSchema, options?: BuildGraphQLSchemaOptions): string;
+//# sourceMappingURL=build-schema.d.ts.map

package/dist/build-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../src/build-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAWrB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAEvB,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACjE;AAED;2EAC2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC;yCACqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;uBACmB;IACnB,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,KACnB,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC;;kEAE8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;gDAE4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAiYf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}

package/dist/build-schema.js

@@ -0,0 +1,407 @@
+import { GraphQLBoolean, GraphQLEnumType, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, printSchema, } from 'graphql';
+import { facetableFields, filterableFields, filterOperatorFor, isRangeFacet, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+import { defaultLanguageOrder, toLanguageStrings, } from './language.js';
+const nonNullListOf = (type) => new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(type)));
+const scalarOutput = (scalar, field) => field.required === true ? new GraphQLNonNull(scalar) : scalar;
+/** SCREAMING_SNAKE_CASE for an enum value name, e.g. `datePosted` → `DATE_POSTED`. */
+function screamingSnake(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+}
+/**
+ * Construct an executable GraphQL schema from the whole {@link SearchSchema} at
+ * runtime — no codegen, no SDL artifact. One root query field per
+ * {@link SearchType} (e.g. `datasets`, `people`), each searchable in its own
+ * way through its own output/`where`/`orderBy`/facet types, while the shared
+ * types (`LanguageString`, buckets, filter inputs, reference types) are created
+ * once. One generic resolver per root field maps the arguments to a
+ * {@link SearchQuery}, calls `context.engine`, and maps the result back; the
+ * field model only parameterises data.
+ */
+export function buildGraphQLSchema(schema, options = {}) {
+    const languageOrder = options.languageOrder ?? defaultLanguageOrder;
+    const maxPerPage = options.maxPerPage ?? 100;
+    const rootTypeNames = new Set([...schema.values()].map((searchType) => searchType.name));
+    for (const name of Object.keys(options.types ?? {})) {
+        if (!rootTypeNames.has(name)) {
+            throw new Error(`Options given for type “${name}”, which is not in the search schema.`);
+        }
+    }
+    const languageString = new GraphQLObjectType({
+        name: 'LanguageString',
+        fields: {
+            language: { type: GraphQLString },
+            value: { type: new GraphQLNonNull(GraphQLString) },
+        },
+    });
+    // A plain value facet bucket: a selection key, its count, and (for reference
+    // facets) the engine-resolved data label; null for token/free-string facets
+    // whose display the consumer owns.
+    const valueBucket = new GraphQLObjectType({
+        name: 'ValueBucket',
+        fields: {
+            value: { type: new GraphQLNonNull(GraphQLString) },
+            count: { type: new GraphQLNonNull(GraphQLInt) },
+            label: {
+                type: new GraphQLList(new GraphQLNonNull(languageString)),
+                resolve: (bucket, _args, context) => {
+                    const label = bucket.label;
+                    return label
+                        ? toLanguageStrings(label, context.acceptLanguage, languageOrder)
+                        : null;
+                },
+            },
+        },
+    });
+    // A numeric range-facet bin: half-open `[min, max)` bounds (max null on an
+    // open-ended top bin) and the count of documents in it.
+    const rangeBucket = new GraphQLObjectType({
+        name: 'RangeBucket',
+        fields: {
+            min: { type: GraphQLFloat },
+            max: { type: GraphQLFloat },
+            count: { type: new GraphQLNonNull(GraphQLInt) },
+        },
+    });
+    const sortDirection = new GraphQLEnumType({
+        name: 'SortDirection',
+        values: { ASC: { value: 'asc' }, DESC: { value: 'desc' } },
+    });
+    const stringFilter = new GraphQLInputObjectType({
+        name: 'StringFilter',
+        fields: {
+            in: { type: new GraphQLList(new GraphQLNonNull(GraphQLString)) },
+        },
+    });
+    const intRange = rangeInput('IntRange', GraphQLInt);
+    const floatRange = rangeInput('FloatRange', GraphQLFloat);
+    const dateRange = rangeInput('DateRange', GraphQLString);
+    const labelList = (resolveLabel) => ({
+        type: nonNullListOf(languageString),
+        resolve: (source, _args, context) => {
+            const value = resolveLabel(source);
+            return value
+                ? toLanguageStrings(value, context.acceptLanguage, languageOrder)
+                : [];
+        },
+    });
+    // Duplicate root type names cannot occur: SearchSchema is branded, so
+    // searchSchema() — which rejects duplicates — is the only constructor.
+    // One reference type per referenced shape, shared across every root type and
+    // reused by every field (Person and CreativeWork both referencing Agent yield
+    // one Agent type).
+    const referenceTypes = new Map();
+    for (const searchType of schema.values()) {
+        for (const field of outputFields(searchType)) {
+            if (field.kind !== 'reference' || field.ref === undefined) {
+                continue;
+            }
+            const { typeName } = field.ref;
+            if (rootTypeNames.has(typeName)) {
+                throw new Error(`Reference type name “${typeName}” (field “${field.name}” of “${searchType.name}”) collides with a root type of the same name; rename one — a reference does not resolve to a root type.`);
+            }
+            if (!referenceTypes.has(typeName)) {
+                referenceTypes.set(typeName, new GraphQLObjectType({
+                    name: typeName,
+                    fields: {
+                        id: { type: new GraphQLNonNull(GraphQLString) },
+                        name: labelList((source) => source.label),
+                    },
+                }));
+            }
+        }
+    }
+    function outputFieldConfig(field) {
+        switch (field.kind) {
+            case 'text':
+                return labelList((source) => source[field.name]);
+            case 'keyword':
+                return field.array === true
+                    ? {
+                        type: nonNullListOf(GraphQLString),
+                        resolve: (s) => s[field.name] ?? [],
+                    }
+                    : { type: scalarOutput(GraphQLString, field) };
+            case 'reference': {
+                const referenceType = referenceTypes.get(field.ref?.typeName ?? '');
+                return field.array === true
+                    ? {
+                        type: nonNullListOf(referenceType),
+                        resolve: (s) => s[field.name] ?? [],
+                    }
+                    : {
+                        type: field.required === true
+                            ? new GraphQLNonNull(referenceType)
+                            : referenceType,
+                    };
+            }
+            case 'integer':
+                return { type: scalarOutput(GraphQLInt, field) };
+            case 'number':
+                return { type: scalarOutput(GraphQLFloat, field) };
+            case 'date':
+                // Stored as Unix seconds (int64); the surface serves ISO 8601 (ADR 4).
+                return {
+                    type: scalarOutput(GraphQLString, field),
+                    resolve: (source) => {
+                        const value = source[field.name];
+                        return typeof value === 'number'
+                            ? unixSecondsToIso(value)
+                            : (value ?? null);
+                    },
+                };
+            case 'boolean':
+                return {
+                    type: new GraphQLNonNull(GraphQLBoolean),
+                    resolve: (source) => source[field.name] === true,
+                };
+        }
+    }
+    function whereFieldType(field) {
+        switch (filterOperatorFor(field.kind)) {
+            case 'in':
+                return stringFilter;
+            case 'range':
+                return field.kind === 'integer'
+                    ? intRange
+                    : field.kind === 'number'
+                        ? floatRange
+                        : dateRange;
+            default:
+                return GraphQLBoolean;
+        }
+    }
+    /** The root query field for one {@link SearchType}, with its derived types. */
+    function rootField(searchType, typeOptions) {
+        const typeName = searchType.name;
+        const outputType = new GraphQLObjectType({
+            name: typeName,
+            fields: () => {
+                const fields = {
+                    id: { type: new GraphQLNonNull(GraphQLString) },
+                };
+                for (const field of outputFields(searchType)) {
+                    fields[field.name] = outputFieldConfig(field);
+                }
+                return fields;
+            },
+        });
+        // A GraphQL input object must have at least one field, so a type with no
+        // filterable fields gets no `where` arg at all rather than an invalid
+        // empty input.
+        const filterable = filterableFields(searchType);
+        const whereInput = filterable.length === 0
+            ? undefined
+            : new GraphQLInputObjectType({
+                name: `${typeName}Where`,
+                fields: () => {
+                    const fields = {};
+                    for (const field of filterable) {
+                        fields[field.name] = { type: whereFieldType(field) };
+                    }
+                    return fields;
+                },
+            });
+        const sortValues = {
+            RELEVANCE: { value: 'relevance' },
+        };
+        for (const field of sortableFields(searchType)) {
+            sortValues[screamingSnake(field.name)] = { value: field.name };
+        }
+        const sortField = new GraphQLEnumType({
+            name: `${typeName}SortField`,
+            values: sortValues,
+        });
+        const orderByInput = new GraphQLInputObjectType({
+            name: `${typeName}OrderBy`,
+            fields: {
+                field: { type: new GraphQLNonNull(sortField) },
+                direction: {
+                    type: new GraphQLNonNull(sortDirection),
+                    defaultValue: 'desc',
+                },
+            },
+        });
+        // Keyed facets object: one field per facetable field, typed by its kind
+        // (range fields → [RangeBucket!], else [ValueBucket!]). Each field's resolver
+        // computes that facet with its OWN where-filter removed (skip-own-filter), so a
+        // multi-select facet still lists its other options; only the selected fields
+        // are resolved (GraphQL prunes the rest), so the selection IS the request.
+        // Like `where`, omitted entirely for a type with no facetable fields (a
+        // GraphQL object type must have at least one field).
+        const facetable = facetableFields(searchType);
+        const facetsType = facetable.length === 0
+            ? undefined
+            : facetsTypeFor(searchType, typeName, facetable);
+        const resultType = new GraphQLObjectType({
+            name: `${typeName}SearchResult`,
+            fields: {
+                items: { type: nonNullListOf(outputType) },
+                total: { type: new GraphQLNonNull(GraphQLInt) },
+                page: { type: new GraphQLNonNull(GraphQLInt) },
+                perPage: { type: new GraphQLNonNull(GraphQLInt) },
+                // Resolved lazily, per selected key (skip-own-filter); the result object
+                // (which carries the resolved `query`) is the facets source.
+                ...(facetsType && {
+                    facets: {
+                        type: new GraphQLNonNull(facetsType),
+                        resolve: (source) => source,
+                    },
+                }),
+            },
+        });
+        return {
+            type: new GraphQLNonNull(resultType),
+            args: {
+                query: { type: GraphQLString },
+                ...(whereInput && { where: { type: whereInput } }),
+                orderBy: { type: orderByInput },
+                page: { type: GraphQLInt, defaultValue: 1 },
+                perPage: { type: GraphQLInt, defaultValue: 20 },
+            },
+            resolve: async (_source, args, context) => {
+                const built = argsToQuery(args, context, searchType, maxPerPage);
+                const finalQuery = typeOptions?.queryDefaults
+                    ? typeOptions.queryDefaults(built, context)
+                    : built;
+                // Items + total only; facets are resolved lazily per selected key.
+                const result = await context.engine.search(searchType, {
+                    ...finalQuery,
+                    facets: [],
+                });
+                return {
+                    items: result.hits.map((hit) => ({ id: hit.id, ...hit.document })),
+                    total: result.total,
+                    page: pageForOffset(finalQuery.offset, finalQuery.limit),
+                    perPage: finalQuery.limit,
+                    // Carried for the facets resolver (skip-own-filter per key).
+                    query: finalQuery,
+                };
+            },
+        };
+    }
+    /** The keyed facets object for one type (only called with ≥ 1 facetable field). */
+    function facetsTypeFor(searchType, typeName, facetable) {
+        return new GraphQLObjectType({
+            name: `${typeName}Facets`,
+            fields: () => {
+                const fields = {};
+                for (const field of facetable) {
+                    fields[field.name] = {
+                        type: nonNullListOf(isRangeFacet(field) ? rangeBucket : valueBucket),
+                        resolve: async (source, _args, context) => {
+                            const query = source.query;
+                            // Drop this facet's own filter so its other options still count
+                            // (a removed `status` filter also drops the valid-only default, so
+                            // the status facet counts across every status).
+                            const facetQuery = {
+                                ...query,
+                                where: query.where.filter((filter) => filter.field !== field.name),
+                                facets: [field.name],
+                                limit: 0,
+                                offset: 0,
+                            };
+                            // A facet is supplementary: degrade a failed facet to an empty list
+                            // rather than failing the whole query (which would null the non-null
+                            // result and discard the items + every other facet).
+                            try {
+                                const result = await context.engine.search(searchType, facetQuery);
+                                return result.facets[field.name] ?? [];
+                            }
+                            catch (error) {
+                                context.onFacetError?.(field.name, error);
+                                return [];
+                            }
+                        },
+                    };
+                }
+                return fields;
+            },
+        });
+    }
+    const queryFields = {};
+    for (const searchType of schema.values()) {
+        const typeOptions = options.types?.[searchType.name];
+        const typeName = searchType.name;
+        const queryField = typeOptions?.queryField ??
+            `${typeName.charAt(0).toLowerCase()}${typeName.slice(1)}s`;
+        if (queryField in queryFields) {
+            throw new Error(`Duplicate root query field “${queryField}”; set queryField to disambiguate.`);
+        }
+        queryFields[queryField] = rootField(searchType, typeOptions);
+    }
+    return new GraphQLSchema({
+        query: new GraphQLObjectType({ name: 'Query', fields: queryFields }),
+    });
+}
+/**
+ * The SDL of the built schema. Not a shipped artifact — a consumer uses it for an
+ * optional CI snapshot test over its own schema, catching accidental breaking
+ * changes to its frozen contract (including a `buildGraphQLSchema` change in a
+ * future version of this library silently altering it).
+ */
+export function printGraphQLSchema(schema, options = {}) {
+    return printSchema(buildGraphQLSchema(schema, options));
+}
+/** Pure args → {@link SearchQuery} mapping. Rejects out-of-bounds paging
+ *  (`page < 1`, `perPage` outside `1..maxPerPage`) with a clear error — a
+ *  negative offset or an unbounded page size must not reach the engine. */
+function argsToQuery(args, context, searchType, maxPerPage) {
+    const perPage = args.perPage ?? 20;
+    const page = args.page ?? 1;
+    if (page < 1) {
+        throw new Error(`page must be at least 1; got ${page}.`);
+    }
+    // perPage: 0 is a legitimate facet-only query (no hits, page pins to 1).
+    if (perPage < 0 || perPage > maxPerPage) {
+        throw new Error(`perPage must be between 0 and ${maxPerPage}; got ${perPage}.`);
+    }
+    return {
+        text: args.query,
+        where: whereToFilters(args.where, searchType),
+        orderBy: args.orderBy
+            ? [{ field: args.orderBy.field, direction: args.orderBy.direction }]
+            : [],
+        limit: perPage,
+        offset: (page - 1) * perPage,
+        // Facets are requested per-key by the facets resolver, not via an arg.
+        facets: [],
+        locale: context.acceptLanguage[0] ?? 'und',
+    };
+}
+function whereToFilters(where, searchType) {
+    if (where === undefined) {
+        return [];
+    }
+    const filters = [];
+    for (const field of filterableFields(searchType)) {
+        const value = where[field.name];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        switch (filterOperatorFor(field.kind)) {
+            case 'in':
+                filters.push({
+                    field: field.name,
+                    in: value.in ?? [],
+                });
+                break;
+            case 'range': {
+                const range = value;
+                filters.push({
+                    field: field.name,
+                    range: { min: range.min, max: range.max },
+                });
+                break;
+            }
+            default:
+                filters.push({ field: field.name, is: value });
+        }
+    }
+    return filters;
+}
+function rangeInput(name, bound) {
+    return new GraphQLInputObjectType({
+        name,
+        fields: { min: { type: bound }, max: { type: bound } },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { buildGraphQLSchema, printGraphQLSchema } from './build-schema.js';
+export type { SearchContext, BuildGraphQLSchemaOptions, SearchTypeOptions, } from './build-schema.js';
+export { defaultLanguageOrder } from './language.js';
+export type { LanguageString, LanguageOrder } from './language.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

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

package/dist/language.d.ts

@@ -0,0 +1,19 @@
+import type { LocalizedValue } from '@lde/search';
+/** One entry of the surface’s best-first `[LanguageString!]!`. `language` is null
+ *  for untagged (`und`) values; `[0]` is the value to display and `[0].language`
+ *  is the language actually served (the per-field `Content-Language`). */
+export interface LanguageString {
+    readonly language: string | null;
+    readonly value: string;
+}
+/** Orders a localized value’s available languages against the request. */
+export type LanguageOrder = (available: readonly string[], accept: readonly string[]) => readonly string[];
+/**
+ * Default ordering: requested languages first (in request order), then the
+ * remaining tagged languages, then untagged (`und`) last — so `[0]` is always the
+ * best available value.
+ */
+export declare const defaultLanguageOrder: LanguageOrder;
+/** Flatten a language map into a best-first `LanguageString` list. */
+export declare function toLanguageStrings(value: LocalizedValue, accept: readonly string[], order: LanguageOrder): LanguageString[];
+//# sourceMappingURL=language.d.ts.map

package/dist/language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../src/language.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;0EAE0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,CAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,MAAM,EAAE,SAAS,MAAM,EAAE,KACtB,SAAS,MAAM,EAAE,CAAC;AAEvB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAOlC,CAAC;AAEF,sEAAsE;AACtE,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,aAAa,GACnB,cAAc,EAAE,CAWlB"}

package/dist/language.js

@@ -0,0 +1,24 @@
+/**
+ * Default ordering: requested languages first (in request order), then the
+ * remaining tagged languages, then untagged (`und`) last — so `[0]` is always the
+ * best available value.
+ */
+export const defaultLanguageOrder = (available, accept) => {
+    const requested = accept.filter((language) => available.includes(language));
+    const rest = available.filter((language) => language !== 'und' && !requested.includes(language));
+    const untagged = available.includes('und') ? ['und'] : [];
+    return [...requested, ...rest, ...untagged];
+};
+/** Flatten a language map into a best-first `LanguageString` list. */
+export function toLanguageStrings(value, accept, order) {
+    const result = [];
+    for (const language of order(Object.keys(value), accept)) {
+        for (const text of value[language] ?? []) {
+            result.push({
+                language: language === 'und' ? null : language,
+                value: text,
+            });
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@lde/search-api-graphql",
+  "version": "0.1.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.",
+  "repository": {
+    "url": "git+https://github.com/ldelements/lde.git",
+    "directory": "packages/search-api-graphql"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@lde/search": "^0.2.0",
+    "graphql": "^15.8.0",
+    "tslib": "^2.3.0"
+  }
+}