@lde/search-api-graphql 0.17.0 → 0.19.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,EASL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAIL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAarB,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;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAoaf;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,EASL,aAAa,EAQd,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAgBrB,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;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAkef;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, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, printSchema, } from 'graphql';
-import { facetableFields, filterableFields, filterOperatorFor, ID_FIELD, isRangeFacet, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+import { AND_KEY, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, OR_KEY, isRangeFacet, 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)));
@@ -63,6 +63,20 @@ export function buildGraphQLSchema(schema, options = {}) {
             count: { type: new GraphQLNonNull(GraphQLInt) },
         },
     });
+    // A boolean-facet bucket: the value as a real boolean, so the bucket a client
+    // selects round-trips straight into the `is` filter that selects it. No label
+    // – a boolean has no data label to resolve, and the sensible rendering (“with
+    // an image” / “without one”) is knowable only by the consumer.
+    const booleanBucket = new GraphQLObjectType({
+        name: 'BooleanBucket',
+        fields: {
+            value: {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                resolve: (bucket) => bucket.is,
+            },
+            count: { type: new GraphQLNonNull(GraphQLInt) },
+        },
+    });
     // The pagination actually applied (after queryDefaults), shared across every
     // ‹Type›SearchResult so one client pager fragment serves all root types.
     const paginationType = new GraphQLObjectType({
@@ -241,17 +255,54 @@ export function buildGraphQLSchema(schema, options = {}) {
         // 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 = {
+                [ID_FIELD]: { type: stringFilter },
+            };
+            for (const field of filterable) {
+                fields[field.name] = { type: whereFieldType(field) };
+            }
+            return fields;
+        };
+        // 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.
+        const criterionInput = new GraphQLInputObjectType({
+            name: `${typeName}Criterion`,
+            description: 'A condition on exactly one field. Used inside `or`, where the criteria are alternatives.',
+            isOneOf: true,
+            fields: fieldKeys,
+        });
+        const orKey = {
+            type: new GraphQLList(new GraphQLNonNull(criterionInput)),
+            description: 'A disjunction: a document matches when ANY of these criteria holds. Combined with the sibling keys by AND, so it widens across fields without widening the query as a whole.',
+        };
+        // `and` carries further `Where`s rather than a separate clause type. Safe to
+        // be recursive: a conjunction inside a conjunction FLATTENS, and the one
+        // shape that would not – an `and` inside an `or` – is unreachable, because
+        // `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`,
-            fields: () => {
-                const fields = {
-                    [ID_FIELD]: { type: stringFilter },
-                };
-                for (const field of filterable) {
-                    fields[field.name] = { type: whereFieldType(field) };
-                }
-                return fields;
-            },
+            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(),
+                [OR_KEY]: orKey,
+                [AND_KEY]: {
+                    type: new GraphQLList(new GraphQLNonNull(whereInput)),
+                    description: 'Further groups of conditions, all of which apply. The way to carry a second `or` disjunction alongside the first.',
+                },
+            }),
         });
         const sortValues = {
             RELEVANCE: { value: 'relevance' },
@@ -274,7 +325,8 @@ export function buildGraphQLSchema(schema, options = {}) {
             },
         });
         // Keyed facets object: one field per facetable field, typed by its kind
-        // (range fields → [RangeBucket!], else [ValueBucket!]). Only the selected
+        // (range fields → [RangeBucket!], boolean fields → [BooleanBucket!], else
+        // [ValueBucket!]). Only the selected
         // fields are resolved (GraphQL prunes the rest), so the selection IS the
         // request; how they are computed – skip-own-filter, batched into one
         // engine dispatch – lives in facet-batch.ts.
@@ -329,6 +381,13 @@ export function buildGraphQLSchema(schema, options = {}) {
             },
         };
     }
+    /** The bucket type a facet’s kind earns: bins for a range facet, a real
+     *  boolean for a boolean one, a keyed value otherwise. */
+    function bucketTypeFor(field) {
+        if (isRangeFacet(field))
+            return rangeBucket;
+        return field.kind === 'boolean' ? booleanBucket : valueBucket;
+    }
     /** The keyed facets object for one type (only called with ≥ 1 facetable field). */
     function facetsTypeFor(typeName, facetable) {
         return new GraphQLObjectType({
@@ -337,7 +396,7 @@ export function buildGraphQLSchema(schema, options = {}) {
                 const fields = {};
                 for (const field of facetable) {
                     fields[field.name] = {
-                        type: nonNullListOf(isRangeFacet(field) ? rangeBucket : valueBucket),
+                        type: nonNullListOf(bucketTypeFor(field)),
                         // The skip-own-filter query building, the batching into one
                         // engine dispatch and the degrade-to-[] error handling all live
                         // in the loader (facet-batch.ts).
@@ -399,40 +458,66 @@ function argsToQuery(args, context, searchType, maxPerPage) {
     };
 }
 function whereToFilters(where, searchType) {
-    if (where === undefined) {
+    // `== 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 = [];
-    // `id` first: it is declared by no type, so the field loop below never sees it.
-    const id = where[ID_FIELD];
+    const filters = criteriaOf(where, searchType).map(filterOn);
+    // 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));
+    if (alternatives.length > 0) {
+        filters.push({ or: alternatives });
+    }
+    // `and` carries further groups, each contributing its own filters – which is
+    // how a query states a second `or` alongside the first. Recursing keeps the
+    // 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));
+    }
+    return filters;
+}
+/**
+ * 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.
+ */
+function criteriaOf(keyed, searchType) {
+    const criteria = [];
+    const id = keyed[ID_FIELD];
     if (id !== undefined && id !== null) {
-        filters.push({ field: ID_FIELD, in: id.in ?? [] });
+        criteria.push({ field: ID_FIELD, in: id.in ?? [] });
     }
     for (const field of filterableFields(searchType)) {
-        const value = where[field.name];
+        const value = keyed[field.name];
         if (value === undefined || value === null) {
             continue;
         }
         switch (filterOperatorFor(field.kind)) {
             case 'in':
-                filters.push({
+                criteria.push({
                     field: field.name,
                     in: value.in ?? [],
                 });
                 break;
             case 'range': {
                 const range = value;
-                filters.push({
+                criteria.push({
                     field: field.name,
                     range: { min: range.min, max: range.max },
                 });
                 break;
             }
             default:
-                filters.push({ field: field.name, is: value });
+                criteria.push({ field: field.name, is: value });
         }
     }
-    return filters;
+    return criteria;
 }
 function rangeInput(name, bound) {
     return new GraphQLInputObjectType({

package/dist/facet-batch.d.ts

@@ -28,6 +28,17 @@ export declare function createFacetLoader(engine: SearchEngine, searchType: Root
  * a policy default on that field, e.g. valid-only `status`, so the facet
  * counts across every value.) The queries are facet-only: no hits (`limit:
  * 0`) and, with no hits to order, no `orderBy`.
+ *
+ * A clause is a facet’s **own** only when it carries exactly one criterion, on
+ * that field ({@link ownsFacet}). A disjunction (`or`) is nobody’s own and
+ * always stays: the user constrained the document as a whole, never that one
+ * axis, so there is no selection on it to widen. Keeping it is what leaves each facet
+ * *complete on its own field* – every value it offers is one the user can pick,
+ * with the count they will actually get. Dropping the clause’s own disjunct
+ * instead would hide values that do return hits (on an entity page: the very
+ * entity the page is about, absent from a sidebar beside results full of it),
+ * and dropping it whole would count a corpus the sibling facets do not.
+ * It also keeps a multi-field clause from ever splitting the batch.
  */
 export declare function groupFacetQueries(query: SearchQuery, fields: readonly string[]): SearchQuery[];
 //# sourceMappingURL=facet-batch.d.ts.map

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,EACX,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;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,WAAW,EAAE,CAgBf"}
+{"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"}

package/dist/facet-batch.js

@@ -60,9 +60,22 @@ export function createFacetLoader(engine, searchType, query, onFacetError) {
  * a policy default on that field, e.g. valid-only `status`, so the facet
  * counts across every value.) The queries are facet-only: no hits (`limit:
  * 0`) and, with no hits to order, no `orderBy`.
+ *
+ * A clause is a facet’s **own** only when it carries exactly one criterion, on
+ * that field ({@link ownsFacet}). A disjunction (`or`) is nobody’s own and
+ * always stays: the user constrained the document as a whole, never that one
+ * axis, so there is no selection on it to widen. Keeping it is what leaves each facet
+ * *complete on its own field* – every value it offers is one the user can pick,
+ * with the count they will actually get. Dropping the clause’s own disjunct
+ * instead would hide values that do return hits (on an entity page: the very
+ * entity the page is about, absent from a sidebar beside results full of it),
+ * and dropping it whole would count a corpus the sibling facets do not.
+ * It also keeps a multi-field clause from ever splitting the batch.
  */
 export function groupFacetQueries(query, fields) {
-    const filteredFields = new Set(query.where.map((filter) => filter.field));
+    const filteredFields = new Set(query.where
+        .map(ownedField)
+        .filter((field) => field !== undefined));
     const facetOnly = { ...query, orderBy: [], limit: 0, offset: 0 };
     const sharedFields = fields.filter((field) => !filteredFields.has(field));
     const queries = [];
@@ -72,9 +85,37 @@ export function groupFacetQueries(query, fields) {
     for (const field of fields.filter((field) => filteredFields.has(field))) {
         queries.push({
             ...facetOnly,
-            where: query.where.filter((filter) => filter.field !== field),
+            where: query.where.filter((filter) => !ownsFacet(filter, field)),
             facets: [field],
         });
     }
     return queries;
 }
+/** Whether a clause is `field`’s own – it constrains that field and nothing
+ *  else, so skip-own-filter removes it when counting that facet. */
+function ownsFacet(filter, field) {
+    return ownedField(filter) === field;
+}
+/**
+ * The field a clause belongs to, or `undefined` when it belongs to none.
+ *
+ * A clause owns a field when **every** criterion names it – which covers the
+ * ordinary one-criterion filter and equally a same-field disjunction
+ * (`or: [{ created: { max: … } }, { created: { min: … } }]`, or a multi-select
+ * spelled as alternatives). Those ARE a selection on one axis, so skip-own-filter
+ * must drop them; leaving them in would compute the facet with the user’s own
+ * selection applied, offering back only what they already picked.
+ *
+ * A clause spanning several fields is nobody’s own: the user constrained the
+ * document as a whole, never one axis, so there is nothing on any single facet
+ * to widen.
+ */
+function ownedField(filter) {
+    const [first, ...rest] = filter.or;
+    if (first === undefined) {
+        return undefined;
+    }
+    return rest.every((criterion) => criterion.field === first.field)
+        ? first.field
+        : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.17.0",
+  "version": "0.19.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",
@@ -28,9 +28,9 @@
     "@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.16.0",
+    "@lde/search": "^0.18.0",
     "dataloader": "^2.2.3",
-    "graphql": "^16.0.0",
+    "graphql": "^16.9.0",
     "graphql-yoga": "^5.21.2",
     "negotiator": "^1.0.0",
     "tslib": "^2.3.0"