@lde/search-api-graphql 0.1.0 → 0.2.0

package/README.md

@@ -84,10 +84,16 @@ const gqlSchema = buildGraphQLSchema(searchSchema(DATASET, PERSON));
   `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).
+- **Facets**: a keyed object with one field per `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). Selecting facet fields IS
+  the request: each selected facet is computed with its own `where`-filter
+  removed (skip-own-filter), and the whole selection is **batched per
+  request** – facets whose field carries no active filter share one query
+  (the unfiltered browse collapses to a single query) and everything is
+  dispatched as one `engine.searchFacets` call, so a typical page costs the
+  listing search plus one batched facet round-trip.
 
 ## Guarding the contract
 

package/dist/build-schema.d.ts

@@ -10,9 +10,11 @@ export interface SearchContext {
     /** 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.
+     * Called once per affected facet field when its computation fails – for a
+     * failed facet query only that query's fields, for a failed batch dispatch
+     * every selected field. The affected facets degrade to empty lists (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;
 }

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,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"}
+{"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;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,CAwWf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}

package/dist/build-schema.js

@@ -1,6 +1,7 @@
 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';
+import { createFacetLoader } from './facet-batch.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`. */
@@ -222,16 +223,14 @@ export function buildGraphQLSchema(schema, options = {}) {
             },
         });
         // 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.
+        // (range fields → [RangeBucket!], 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.
         // 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 facetsType = facetable.length === 0 ? undefined : facetsTypeFor(typeName, facetable);
         const resultType = new GraphQLObjectType({
             name: `${typeName}SearchResult`,
             fields: {
@@ -240,7 +239,7 @@ export function buildGraphQLSchema(schema, options = {}) {
                 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.
+                // (which carries the per-request facet loader) is the facets source.
                 ...(facetsType && {
                     facets: {
                         type: new GraphQLNonNull(facetsType),
@@ -273,14 +272,14 @@ export function buildGraphQLSchema(schema, options = {}) {
                     total: result.total,
                     page: pageForOffset(finalQuery.offset, finalQuery.limit),
                     perPage: finalQuery.limit,
-                    // Carried for the facets resolver (skip-own-filter per key).
-                    query: finalQuery,
+                    // Carried for the facet field resolvers (see facet-batch.ts).
+                    loadFacet: createFacetLoader(context.engine, searchType, finalQuery, context.onFacetError),
                 };
             },
         };
     }
     /** The keyed facets object for one type (only called with ≥ 1 facetable field). */
-    function facetsTypeFor(searchType, typeName, facetable) {
+    function facetsTypeFor(typeName, facetable) {
         return new GraphQLObjectType({
             name: `${typeName}Facets`,
             fields: () => {
@@ -288,30 +287,10 @@ export function buildGraphQLSchema(schema, options = {}) {
                 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 [];
-                            }
-                        },
+                        // 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).
+                        resolve: (source) => source.loadFacet(field.name),
                     };
                 }
                 return fields;

package/dist/facet-batch.d.ts

@@ -0,0 +1,33 @@
+import type { FacetBucket, SearchEngine, SearchQuery, SearchType } from '@lde/search';
+/** Resolves one selected facet field to its buckets; see {@link createFacetLoader}. */
+export type FacetLoader = (field: string) => Promise<readonly FacetBucket[]>;
+/**
+ * A per-request batcher behind the keyed facets object. Each selected facet
+ * field’s resolver calls the loader; GraphQL resolves the sibling facet
+ * fields synchronously, so the loads land in the same tick, where the
+ * DataLoader collects them into one batch, which is grouped into the fewest
+ * equivalent queries ({@link groupFacetQueries}) and dispatched as ONE
+ * `engine.searchFacets` call – one engine round-trip for the whole sidebar
+ * instead of one search per facet.
+ *
+ * A facet is supplementary: a failed facet query degrades exactly its own
+ * facets to empty lists – reported per field via `onFacetError` – while its
+ * siblings keep their buckets; only a batch-level failure (the dispatch
+ * itself rejecting) degrades every facet. Neither fails the whole GraphQL
+ * query, which would null the non-null result and discard the items.
+ */
+export declare function createFacetLoader(engine: SearchEngine, searchType: SearchType, query: SearchQuery, onFacetError?: (field: string, error: unknown) => void): FacetLoader;
+/**
+ * Group the selected facet fields into the fewest facet-only queries with
+ * unchanged skip-own-filter semantics. Each facet counts with its OWN
+ * `where`-filter removed, so removal only matters for a facet whose field is
+ * actively filtered: every facet whose field carries no filter shares the
+ * untouched `where` – one query faceting all of them (the unfiltered browse
+ * collapses to a single query) – while each own-filtered facet gets its own
+ * query with its own effective `where`. (Dropping a facet’s filter also drops
+ * 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`.
+ */
+export declare function groupFacetQueries(query: SearchQuery, fields: readonly string[]): SearchQuery[];
+//# sourceMappingURL=facet-batch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"facet-batch.d.ts","sourceRoot":"","sources":["../src/facet-batch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACX,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,UAAU,EACtB,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"}

package/dist/facet-batch.js

@@ -0,0 +1,80 @@
+import DataLoader from 'dataloader';
+/**
+ * A per-request batcher behind the keyed facets object. Each selected facet
+ * field’s resolver calls the loader; GraphQL resolves the sibling facet
+ * fields synchronously, so the loads land in the same tick, where the
+ * DataLoader collects them into one batch, which is grouped into the fewest
+ * equivalent queries ({@link groupFacetQueries}) and dispatched as ONE
+ * `engine.searchFacets` call – one engine round-trip for the whole sidebar
+ * instead of one search per facet.
+ *
+ * A facet is supplementary: a failed facet query degrades exactly its own
+ * facets to empty lists – reported per field via `onFacetError` – while its
+ * siblings keep their buckets; only a batch-level failure (the dispatch
+ * itself rejecting) degrades every facet. Neither fails the whole GraphQL
+ * query, which would null the non-null result and discard the items.
+ */
+export function createFacetLoader(engine, searchType, query, onFacetError) {
+    const loader = new DataLoader(async (fields) => {
+        const queries = groupFacetQueries(query, fields);
+        const buckets = new Map();
+        try {
+            const outcomes = await engine.searchFacets(searchType, queries);
+            queries.forEach((facetQuery, index) => {
+                const outcome = outcomes[index];
+                if (outcome !== undefined && !('error' in outcome)) {
+                    for (const field of facetQuery.facets) {
+                        buckets.set(field, outcome.facets[field] ?? []);
+                    }
+                    return;
+                }
+                // A failed (or missing – a port-contract breach) outcome degrades
+                // exactly this query's facets; its siblings keep theirs.
+                const error = outcome === undefined
+                    ? new Error('The engine returned no outcome for this query.')
+                    : outcome.error;
+                for (const field of facetQuery.facets) {
+                    onFacetError?.(field, error);
+                }
+            });
+        }
+        catch (error) {
+            // A batch-level failure leaves `buckets` empty: every facet in the
+            // batch degrades to [].
+            for (const field of fields) {
+                onFacetError?.(field, error);
+            }
+        }
+        return fields.map((field) => buckets.get(field) ?? []);
+    });
+    return (field) => loader.load(field);
+}
+/**
+ * Group the selected facet fields into the fewest facet-only queries with
+ * unchanged skip-own-filter semantics. Each facet counts with its OWN
+ * `where`-filter removed, so removal only matters for a facet whose field is
+ * actively filtered: every facet whose field carries no filter shares the
+ * untouched `where` – one query faceting all of them (the unfiltered browse
+ * collapses to a single query) – while each own-filtered facet gets its own
+ * query with its own effective `where`. (Dropping a facet’s filter also drops
+ * 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`.
+ */
+export function groupFacetQueries(query, fields) {
+    const filteredFields = new Set(query.where.map((filter) => filter.field));
+    const facetOnly = { ...query, orderBy: [], limit: 0, offset: 0 };
+    const sharedFields = fields.filter((field) => !filteredFields.has(field));
+    const queries = [];
+    if (sharedFields.length > 0) {
+        queries.push({ ...facetOnly, facets: sharedFields });
+    }
+    for (const field of fields.filter((field) => filteredFields.has(field))) {
+        queries.push({
+            ...facetOnly,
+            where: query.where.filter((filter) => filter.field !== field),
+            facets: [field],
+        });
+    }
+    return queries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -25,7 +25,8 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.2.0",
+    "@lde/search": "^0.3.0",
+    "dataloader": "^2.2.3",
     "graphql": "^15.8.0",
     "tslib": "^2.3.0"
   }