@lde/search-api-graphql 0.21.0 → 0.22.0

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

@@ -1 +1 @@
-{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../src/build-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAmBrB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAGvB,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;;;;;;OAMG;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;AA+ED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAuoBf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}
+{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../src/build-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAqBrB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAGvB,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;;;;;;OAMG;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;AAqGD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CA6uBf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}

package/dist/build-schema.js

@@ -1,5 +1,5 @@
 import { GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString, printSchema, } from 'graphql';
-import { AND_KEY, DEFAULT_LABEL_FIELD, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, isAbsoluteIri, OR_KEY, isRangeFacet, labelFieldNameOf, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+import { AND_KEY, DEFAULT_LABEL_FIELD, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, isAbsoluteIri, OR_KEY, isRangeFacet, joinGraph, labelFieldNameOf, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
 import { defaultLanguageOrder, toLanguageStrings, } from './language.js';
 import { createFacetLoader } from './facet-batch.js';
 const nonNullListOf = (type) => new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(type)));
@@ -41,18 +41,39 @@ const iriScalar = new GraphQLScalarType({
 });
 function assertIri(value) {
     if (!isAbsoluteIri(value)) {
-        throw new GraphQLError(`IRI cannot represent “${value}”: an IRI needs a scheme (for example “https:”, “urn:” or “doi:”) and no whitespace. A value like this is usually a label or a token, which selects nothing on a field that keys on identity.`);
+        throw userError(`IRI cannot represent “${value}”: an IRI needs a scheme (for example “https:”, “urn:” or “doi:”) and no whitespace. A value like this is usually a label or a token, which selects nothing on a field that keys on identity.`);
     }
     return value;
 }
 /** Outbound the fault is the index, not the caller, so the message points at
- *  the fix rather than at the query. */
+ *  the fix rather than at the query – and it carries no `BAD_USER_INPUT`,
+ *  since there is nothing the query could have done differently. */
 function assertIriOut(value) {
     if (!isAbsoluteIri(value)) {
         throw new GraphQLError(`IRI cannot serialize “${value}”: the index holds a value that is not an absolute IRI on a field that keys on identity. The projection drops such values at the source, so this document predates that rule – reindex it.`);
     }
     return value;
 }
+/**
+ * An error the CALLER can fix, marked as such: a `GraphQLError` carrying
+ * `extensions.code = 'BAD_USER_INPUT'`.
+ *
+ * Both halves matter, and both are about the consumer rather than about us. A
+ * plain `Error` thrown from a resolver is a server fault as far as the
+ * transport is concerned, so graphql-yoga masks it to `“Unexpected error.”`;
+ * the message then survives only in the API container’s log, where a
+ * presentation-layer developer building against a hosted endpoint cannot read
+ * it. Throwing a `GraphQLError` keeps the sentence that says what was wrong.
+ * The `code` says whose fault it is, so a client can distinguish “fix your
+ * query” from “retry later” without matching on prose – the convention every
+ * major GraphQL server shares. `“Unexpected error.”` is left for what the name
+ * says: faults we did not anticipate.
+ */
+function userError(message) {
+    return new GraphQLError(message, {
+        extensions: { code: 'BAD_USER_INPUT' },
+    });
+}
 /** 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();
@@ -247,6 +268,12 @@ export function buildGraphQLSchema(schema, options = {}) {
             ? DEFAULT_LABEL_FIELD
             : labelFieldNameOf(rootTypesByName.get(field.labelSource));
     }
+    // The declared joins, and the input types they make shareable. Each map is
+    // keyed by the SearchType `name`, so a type reached as a join target and the
+    // same type queried in its own right meet exactly one `‹Name›Where`.
+    const joins = joinGraph(schema);
+    const whereInputs = new Map();
+    const referenceFilters = new Map();
     /**
      * Register the GraphQL type one reference field is served as, once per
      * referenced shape. A **surfaced inline** reference is served as the nested
@@ -400,10 +427,22 @@ export function buildGraphQLSchema(schema, options = {}) {
                 };
         }
     }
+    function whereFieldType(field, owner) {
+        // A joinable reference is filterable in two ways at once – by the ids it
+        // holds, and by a condition on the referent – so it earns a richer input
+        // than the plain membership every other reference gets. Making the
+        // difference visible in the schema is the point: a consumer sees which
+        // references can be filtered through, instead of discovering it from a
+        // runtime error.
+        const target = joins.resolve(owner, [field.name]);
+        return target !== undefined
+            ? referenceFilterFor(target)
+            : plainWhereFieldType(field);
+    }
     /** The filter input one field accepts, fixed by what the field keys on: a
      *  `reference` keys on identity (its target’s filter, or `IRIFilter` when it
      *  names no target), a `keyword` on literals. */
-    function whereFieldType(field) {
+    function plainWhereFieldType(field) {
         switch (filterOperatorFor(field.kind)) {
             case 'in':
                 if (field.kind !== 'reference') {
@@ -422,58 +461,88 @@ export function buildGraphQLSchema(schema, options = {}) {
                 return GraphQLBoolean;
         }
     }
-    /** The root query field for one {@link RootType}, 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(iriScalar) },
-                };
-                for (const field of outputFields(searchType)) {
-                    fields[field.name] = outputFieldConfig(field);
-                }
-                return fields;
-            },
+    /**
+     * The filter input a joinable reference to `target` takes, created once per
+     * target type and shared by EVERY field pointing at it – `publisher` and
+     * `creator` both resolving to `Organization` take the same
+     * `OrganizationReferenceFilter`, because what it can express is a property of
+     * the referenced type, not of the referring field.
+     *
+     * `@oneOf`, so a criterion stays an atom: filter by the ids the field holds,
+     * **or** by a condition on the referent, never both in one term.
+     */
+    function referenceFilterFor(target) {
+        const existing = referenceFilters.get(target.name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = new GraphQLInputObjectType({
+            name: `${target.name}ReferenceFilter`,
+            description: `A condition on a joinable reference to ${target.name}: the ids it holds, or a condition on the referenced ${target.name} itself.`,
+            isOneOf: true,
+            // A thunk: the target’s own `where` may point back through further
+            // joinable references (the join graph is acyclic, so this terminates).
+            fields: () => ({
+                // `IRI`, exactly as `‹Target›Filter` types it: this arm asks the same
+                // question that filter asks – which of the target’s ids the field
+                // holds – so it must accept the same variable a consumer declares
+                // `[IRI!]` for. Typing it `String` here would make the join arm the
+                // one place identity is not `IRI`-keyed.
+                in: { type: new GraphQLList(new GraphQLNonNull(iriScalar)) },
+                where: { type: whereInputFor(target) },
+            }),
         });
-        // Every type is filterable on `id`, so the input always has at least one
-        // field and always exists – no type is unaddressable by IRI, whatever it
-        // declares.
-        const filterable = filterableFields(searchType);
-        /**
-         * One key per filterable field (plus the undeclared `id`), each typed by its
-         * OWN kind – so the operator a key accepts is fixed by the field it names,
-         * and a range on a keyword field cannot be written at all. This is the
-         * single vocabulary every level of `where` is built from: the same keys
-         * appear on the clause and on a criterion, so a field is never named a
-         * second way.
-         */
-        const fieldKeys = () => {
-            const fields = {
-                // Typed self-referentially – `TermWhere.id: TermFilter` – so a consumer
-                // can resolve “the collection I am browsing” to “the filter type that
-                // accepts its IRIs”, which is what makes the refined discovery strategy
-                // work without hardcoding a single domain name.
-                [ID_FIELD]: { type: targetFilter(typeName) },
-            };
-            for (const field of filterable) {
-                fields[field.name] = {
-                    type: whereFieldType(field),
-                    description: field.description,
-                };
-            }
-            return fields;
+        referenceFilters.set(target.name, created);
+        return created;
+    }
+    /**
+     * One key per filterable field (plus the undeclared `id`), each typed by its
+     * OWN kind – so the operator a key accepts is fixed by the field it names,
+     * and a range on a keyword field cannot be written at all. This is the
+     * single vocabulary every level of `where` is built from: the same keys
+     * appear on the clause and on a criterion, so a field is never named a
+     * second way.
+     */
+    function fieldKeys(searchType) {
+        const fields = {
+            // Typed self-referentially – `TermWhere.id: TermFilter` – so a consumer
+            // can resolve “the collection I am browsing” to “the filter type that
+            // accepts its IRIs”, which is what makes the refined discovery strategy
+            // work without hardcoding a single domain name.
+            [ID_FIELD]: { type: targetFilter(searchType.name) },
         };
+        for (const field of filterableFields(searchType)) {
+            fields[field.name] = {
+                type: whereFieldType(field, searchType),
+                description: field.description,
+            };
+        }
+        return fields;
+    }
+    /**
+     * The `where` input of one root type, created once and shared: it is both the
+     * argument of that type’s own query field and – through a
+     * {@link referenceFilterFor} – the shape a *joined* condition on it takes
+     * from another type. One input either way, so the vocabulary a consumer
+     * learns for `datasets(where: …)` is the same one they write inside
+     * `creativeWorks(where: { dataset: { where: … } })`.
+     */
+    function whereInputFor(searchType) {
+        const existing = whereInputs.get(searchType.name);
+        if (existing !== undefined) {
+            return existing;
+        }
         // A criterion is an ATOM: exactly one field, enforced by `@oneOf`. That is
         // what keeps `where` a flat conjunction of disjunctions – a criterion that
         // could carry two keys would be a conjunction nested inside an `or`, and
         // skip-own-filter (ADR 5) has no answer for a clause buried inside another.
+        // Created here rather than on its own, because it exists for exactly one
+        // `where` and shares its memoization.
         const criterionInput = new GraphQLInputObjectType({
-            name: `${typeName}Criterion`,
+            name: `${searchType.name}Criterion`,
             description: 'A condition on exactly one field. Used inside `or`, where the criteria are alternatives.',
             isOneOf: true,
-            fields: fieldKeys,
+            fields: () => fieldKeys(searchType),
         });
         const orKey = {
             type: new GraphQLList(new GraphQLNonNull(criterionInput)),
@@ -485,18 +554,41 @@ export function buildGraphQLSchema(schema, options = {}) {
         // `or` holds only `@oneOf` criteria. So `where` stays a flat conjunction of
         // disjunctions at any nesting depth, and a reader meets one input type
         // instead of two near-identical ones.
-        const whereInput = new GraphQLInputObjectType({
-            name: `${typeName}Where`,
+        const created = new GraphQLInputObjectType({
+            name: `${searchType.name}Where`,
             description: 'Sibling keys are combined with AND. Use `or` for a disjunction, and `and` when a query needs more than one of them.',
             fields: () => ({
-                ...fieldKeys(),
+                ...fieldKeys(searchType),
                 [OR_KEY]: orKey,
                 [AND_KEY]: {
-                    type: new GraphQLList(new GraphQLNonNull(whereInput)),
+                    type: new GraphQLList(new GraphQLNonNull(created)),
                     description: 'Further groups of conditions, all of which apply. The way to carry a second `or` disjunction alongside the first.',
                 },
             }),
         });
+        whereInputs.set(searchType.name, created);
+        return created;
+    }
+    /** The root query field for one {@link RootType}, 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(iriScalar) },
+                };
+                for (const field of outputFields(searchType)) {
+                    fields[field.name] = outputFieldConfig(field);
+                }
+                return fields;
+            },
+        });
+        // Every type is filterable on `id`, so the input always has at least one
+        // field and always exists – no type is unaddressable by IRI, whatever it
+        // declares. It may already have been created as a joined type’s filter
+        // shape; `whereInputFor` hands back the same instance either way.
+        const whereInput = whereInputFor(searchType);
         const sortValues = {
             RELEVANCE: { value: 'relevance' },
         };
@@ -545,14 +637,34 @@ export function buildGraphQLSchema(schema, options = {}) {
         return {
             type: new GraphQLNonNull(resultType),
             args: {
-                query: { type: GraphQLString },
-                where: { type: whereInput },
-                orderBy: { type: orderByInput },
-                page: { type: GraphQLInt, defaultValue: 1 },
-                perPage: { type: GraphQLInt, defaultValue: 20 },
+                query: {
+                    type: GraphQLString,
+                    description: 'Free-text query. Omit it to browse by filter alone.',
+                },
+                where: {
+                    type: whereInput,
+                    description: 'Conditions every result must satisfy.',
+                },
+                orderBy: {
+                    type: orderByInput,
+                    description: 'Sort order. Defaults to relevance for a free-text query.',
+                },
+                page: {
+                    type: GraphQLInt,
+                    defaultValue: 1,
+                    // The bound in the SDL, so the playground’s own documentation
+                    // answers “how large may a page be?” before a request has to fail
+                    // to say it.
+                    description: '1-based page number; at least 1.',
+                },
+                perPage: {
+                    type: GraphQLInt,
+                    defaultValue: 20,
+                    description: `Results per page, between 0 and ${maxPerPage}. Use 0 for a facet-only query: no results are fetched, and the facet counts still come back.`,
+                },
             },
             resolve: async (_source, args, context) => {
-                const built = argsToQuery(args, context, searchType, maxPerPage);
+                const built = argsToQuery(args, context, searchType, maxPerPage, joins);
                 const finalQuery = typeOptions?.queryDefaults
                     ? typeOptions.queryDefaults(built, context)
                     : built;
@@ -632,19 +744,19 @@ export function printGraphQLSchema(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) {
+function argsToQuery(args, context, searchType, maxPerPage, joins) {
     const perPage = args.perPage ?? 20;
     const page = args.page ?? 1;
     if (page < 1) {
-        throw new Error(`page must be at least 1; got ${page}.`);
+        throw userError(`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}.`);
+        throw userError(`perPage must be between 0 and ${maxPerPage}; got ${perPage}.`);
     }
     return {
         text: args.query,
-        where: whereToFilters(args.where, searchType),
+        where: whereToFilters(args.where, searchType, joins),
         orderBy: args.orderBy
             ? [{ field: args.orderBy.field, direction: args.orderBy.direction }]
             : [],
@@ -655,18 +767,37 @@ function argsToQuery(args, context, searchType, maxPerPage) {
         locale: context.acceptLanguage[0] ?? 'und',
     };
 }
-function whereToFilters(where, searchType) {
+/**
+ * Compile one `Where` input into the flat conjunction of disjunctions the IR
+ * holds, at `on` hops out from the searched type (`[]` at the top level).
+ *
+ * A **joined** key carrying `where` recurses with the path extended by that
+ * key, and its clauses join this list – exactly how `and` already flattens. The
+ * result is still flat: the nesting lives in each criterion’s `on` path, never
+ * in the clause structure, so skip-own-filter (ADR 5) still scans one level.
+ */
+function whereToFilters(where, searchType, joins, on = []) {
     // `== null` deliberately: an explicit `where: null` is as absent as an omitted
     // one, and reading keys off it would throw.
     if (where == null) {
         return [];
     }
-    const filters = criteriaOf(where, searchType).map(filterOn);
+    const filters = [];
     // Sibling field keys AND, so each becomes a one-criterion filter of its own,
     // while `or` becomes a SINGLE filter carrying every alternative. That is the
     // whole AND/OR mapping: which bucket a criterion lands in, never a combinator
     // inferred from how deeply it is nested.
-    const alternatives = (where[OR_KEY] ?? []).flatMap((criterion) => criteriaOf(criterion, searchType));
+    for (const entry of keyEntriesOf(where, searchType, joins)) {
+        if ('nested' in entry) {
+            filters.push(...whereToFilters(entry.nested, entry.target, joins, [
+                ...on,
+                entry.name,
+            ]));
+            continue;
+        }
+        filters.push(filterOn(withPath(entry.criterion, on)));
+    }
+    const alternatives = (where[OR_KEY] ?? []).flatMap((criterion) => criteriaOf(criterion, searchType, joins, on));
     if (alternatives.length > 0) {
         filters.push({ or: alternatives });
     }
@@ -675,47 +806,105 @@ function whereToFilters(where, searchType) {
     // result flat: nested conjunctions collapse into this one list, and an `and`
     // can never sit inside an `or` (which holds only criteria).
     for (const nested of where[AND_KEY] ?? []) {
-        filters.push(...whereToFilters(nested, searchType));
+        filters.push(...whereToFilters(nested, searchType, joins, on));
     }
     return filters;
 }
+/** A criterion with its join path attached, or unchanged at the top level –
+ *  so an ordinary query’s IR is byte-for-byte what it was. */
+function withPath(criterion, on) {
+    return on.length === 0 ? criterion : { ...criterion, on };
+}
 /**
- * The criteria a keyed object carries, in declaration order. A `Criterion` is
- * `@oneOf`, so it yields exactly one; a `Where`/`Clause` yields one per field
- * key it sets. `id` is read first: no type declares it, so the field loop below
- * never sees it.
+ * The criteria a keyed object carries, in declaration order, `on` hops out. A
+ * `Criterion` is `@oneOf`, so it yields exactly one; a `Where` yields one per
+ * field key it sets.
+ *
+ * A joined key carrying `where` is compiled through {@link whereToFilters} and
+ * must come back as exactly ONE one-criterion clause. Anything else – two field
+ * keys, an `or`, an `and` – is a conjunction, and a conjunction cannot sit
+ * inside the `or` this feeds (ADR 18’s flat IR has nowhere to put it), so it is
+ * rejected with the rewrite that expresses it instead.
  */
-function criteriaOf(keyed, searchType) {
+function criteriaOf(keyed, searchType, joins, on = []) {
     const criteria = [];
+    for (const entry of keyEntriesOf(keyed, searchType, joins)) {
+        if (!('nested' in entry)) {
+            criteria.push(withPath(entry.criterion, on));
+            continue;
+        }
+        const path = [...on, entry.name];
+        const nested = whereToFilters(entry.nested, entry.target, joins, path);
+        const [only] = nested;
+        // An `or` alternative must be exactly one criterion. Empty and
+        // more-than-one are opposite mistakes, so they are named separately rather
+        // than sharing a message that fits only one of them.
+        if (only === undefined) {
+            throw new Error(`The joined condition on “${entry.name}” states no criterion, so it constrains nothing – and an “or” alternative that constrains nothing would make the whole disjunction match everything. Give it a condition, or leave the alternative out.`);
+        }
+        if (nested.length !== 1 || only.or.length !== 1) {
+            throw new Error(`The joined condition on “${entry.name}” states more than one criterion, so it is a conjunction – which cannot sit inside an “or”. Write one “or” alternative per criterion, or move the conjunction into “and”.`);
+        }
+        criteria.push(only.or[0]);
+    }
+    return criteria;
+}
+/**
+ * The field keys a keyed input sets, in declaration order. `id` is read first:
+ * no type declares it, so the field loop never sees it.
+ *
+ * A joinable reference takes a `‹Target›ReferenceFilter` rather than a plain
+ * `StringFilter`, and its two `@oneOf` arms mean different things: `in` filters
+ * by the ids the field itself holds – no join, the same membership every other
+ * reference gets – while `where` states a condition on the referent and yields
+ * a nested entry the caller walks into.
+ */
+function keyEntriesOf(keyed, searchType, joins) {
+    const entries = [];
     const id = keyed[ID_FIELD];
     if (id !== undefined && id !== null) {
-        criteria.push({ field: ID_FIELD, in: id.in ?? [] });
+        entries.push({ criterion: { field: ID_FIELD, in: id.in ?? [] } });
     }
     for (const field of filterableFields(searchType)) {
         const value = keyed[field.name];
         if (value === undefined || value === null) {
             continue;
         }
+        const target = joins.resolve(searchType, [field.name]);
+        if (target !== undefined) {
+            const nested = value
+                .where;
+            if (nested !== undefined && nested !== null) {
+                entries.push({ name: field.name, nested, target });
+                continue;
+            }
+        }
         switch (filterOperatorFor(field.kind)) {
             case 'in':
-                criteria.push({
-                    field: field.name,
-                    in: value.in ?? [],
+                entries.push({
+                    criterion: {
+                        field: field.name,
+                        in: value.in ?? [],
+                    },
                 });
                 break;
             case 'range': {
                 const range = value;
-                criteria.push({
-                    field: field.name,
-                    range: { min: range.min, max: range.max },
+                entries.push({
+                    criterion: {
+                        field: field.name,
+                        range: { min: range.min, max: range.max },
+                    },
                 });
                 break;
             }
             default:
-                criteria.push({ field: field.name, is: value });
+                entries.push({
+                    criterion: { field: field.name, is: value },
+                });
         }
     }
-    return criteria;
+    return entries;
 }
 function rangeInput(name, bound) {
     return new GraphQLInputObjectType({

package/dist/facet-batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facet-batch.d.ts","sourceRoot":"","sources":["../src/facet-batch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EAEX,QAAQ,EACR,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACrD,WAAW,CAoCb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,WAAW,EAAE,CAoBf"}
+{"version":3,"file":"facet-batch.d.ts","sourceRoot":"","sources":["../src/facet-batch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,WAAW,EAEX,QAAQ,EACR,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACrD,WAAW,CAoCb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,WAAW,EAAE,CAoBf"}

package/dist/facet-batch.js

@@ -115,7 +115,21 @@ function ownedField(filter) {
     if (first === undefined) {
         return undefined;
     }
-    return rest.every((criterion) => criterion.field === first.field)
-        ? first.field
-        : undefined;
+    const key = axisOf(first);
+    return rest.every((criterion) => axisOf(criterion) === key) ? key : undefined;
+}
+/**
+ * The axis one criterion constrains: its field, qualified by the join path it
+ * reaches that field through. Two criteria are the same axis only when both
+ * agree – `dataset.publisher` and a local `publisher` are different questions,
+ * so a selection on one is no selection on the other.
+ *
+ * Facets are not yet offered on joined fields, so a joined clause’s key can
+ * never equal a requested facet name and such a clause simply never drops. That
+ * falls out of the key rather than being a rule of its own, and stays right if
+ * joined facets land later.
+ */
+function axisOf(criterion) {
+    const on = criterion.on ?? [];
+    return on.length === 0 ? criterion.field : [...on, criterion.field].join('.');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.21.0",
+  "version": "0.22.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",
@@ -37,7 +37,7 @@
     "@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.19.0",
+    "@lde/search": "^0.20.0",
     "commander": "^15.0.0",
     "dataloader": "^2.2.3",
     "graphql": "^16.9.0",