@lde/search-api-graphql 0.23.1 → 0.24.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;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;AA4GD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAsxBf;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,EAGjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAmBrB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAIvB,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;AA4GD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CA0xBf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}

package/dist/build-schema.js

@@ -1,7 +1,8 @@
 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, joinGraph, labelFieldNameOf, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+import { AND_KEY, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, isAbsoluteIri, OR_KEY, isRangeFacet, joinGraph, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
 import { defaultLanguageOrder, toLanguageStrings, } from './language.js';
 import { createFacetLoader } from './facet-batch.js';
+import { projectionFor } from './projection.js';
 const nonNullListOf = (type) => new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(type)));
 const scalarOutput = (scalar, field) => field.required === true ? new GraphQLNonNull(scalar) : scalar;
 /**
@@ -283,25 +284,19 @@ export function buildGraphQLSchema(schema, options = {}) {
         floatRange.name,
         dateRange.name,
     ]);
-    /** The label key each id-plus-label reference type was registered with; no
-     *  entry for a surfaced inline one, which carries fields instead of a label. */
-    const labelKeys = new Map();
-    /** The key a reference serves its resolved label under: the name its label
-     *  source declares that label field with, so the reference and the type it
-     *  resolves against agree on the word. An id-only reference resolves no
-     *  label, so it keeps the default. `searchSchema` guarantees the source is a
-     *  declared Root Type. */
-    function labelKeyOf(field) {
-        return field.labelSource === undefined
-            ? 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();
+    /** The name a reference’s emitted type is keyed under: a `lookup`’s target,
+     *  an `inline`’s reference type, an `idOnly`’s declared name (which names a
+     *  filter’s target, never an object type – an `idOnly` surfaces as its bare
+     *  IRI). */
+    function referencedTypeName(ref) {
+        return ref.strategy === 'lookup' ? ref.target : ref.typeName;
+    }
     /**
      * Register the GraphQL type one reference field is served as, once per
      * referenced shape. A **surfaced inline** reference is served as the nested
@@ -318,20 +313,18 @@ export function buildGraphQLSchema(schema, options = {}) {
             // as the IRI itself rather than as an object – there is no type to
             // register, and no name needed to register one under.
             field.ref.strategy === 'idOnly' ||
-            field.ref.typeName === undefined) {
+            referencedTypeName(field.ref) === undefined) {
             return;
         }
-        if (referenceTypes.has(field.ref.typeName)) {
-            // Fields sharing a `ref.typeName` share one emitted type, so they must
-            // agree on the word it serves its label under – otherwise which one wins
-            // would come down to declaration order.
-            const registered = labelKeys.get(field.ref.typeName);
-            if (registered !== undefined && registered !== labelKeyOf(field)) {
-                throw new Error(`Reference “${owner.name}.${field.name}” serves its label as “${labelKeyOf(field)}”, but “${field.ref.typeName}” is already served with “${registered}”; fields sharing a reference type must resolve labels from sources that agree on their labelField.`);
-            }
+        // Guaranteed by the guard above: idOnly is out, and the other two strategies
+        // each name their referent.
+        const typeName = referencedTypeName(field.ref);
+        if (referenceTypes.has(typeName)) {
+            // Fields sharing a referent share one emitted type, and cannot disagree
+            // about it: a lookup's fields come from the target that names the type,
+            // an inline reference's from the Reference Type that does.
             return;
         }
-        const { typeName } = field.ref;
         const graphQLName = rootTypeNames.has(typeName)
             ? `${typeName}Reference`
             : typeName;
@@ -339,35 +332,34 @@ export function buildGraphQLSchema(schema, options = {}) {
             throw new Error(`Reference type “${typeName}” (field “${field.name}” of “${owner.name}”) would be served as “${graphQLName}”, which collides with another type name; rename one.`);
         }
         takenTypeNames.add(graphQLName);
-        const nested = nestedReferenceType(schema, field);
-        if (nested === undefined) {
-            labelKeys.set(typeName, labelKeyOf(field));
-        }
+        // What the emitted type carries, by one rule read off two declarations: a
+        // surfaced inline reference nests its declared Reference Type, a lookup
+        // carries its target root type's own output fields. Always resolvable –
+        // searchSchema rejects a lookup whose target it cannot find, and an inline
+        // reference that resolves to no Reference Type.
+        const nested = (field.ref.strategy === 'lookup'
+            ? rootTypesByName.get(field.ref.target)
+            : nestedReferenceType(schema, field));
         referenceTypes.set(typeName, new GraphQLObjectType({
             name: graphQLName,
             // A thunk, so a Reference Type nesting another one resolves whatever
             // the registration order is (the graph is acyclic by searchSchema).
-            fields: () => nested === undefined
-                ? {
-                    id: { type: new GraphQLNonNull(iriScalar) },
-                    // The same word the label source declares its label field
-                    // under (`label` by default): one resolved label, one name for
-                    // it wherever it surfaces.
-                    [labelKeyOf(field)]: labelList((source) => source.label),
-                }
-                : {
-                    // Nullable, and load-bearing: a referent needs no identity, so
-                    // a blank-node one nests exactly like a named one, minus this.
-                    id: { type: iriScalar },
-                    ...Object.fromEntries(outputFields(nested).map((nestedField) => [
-                        nestedField.name,
-                        outputFieldConfig(nestedField),
-                    ])),
+            fields: () => ({
+                // A lookup resolves a document by IRI, so its `id` is always there.
+                // An inline referent’s is nullable, and load-bearing: a referent
+                // needs no identity, so a blank-node one nests exactly like a named
+                // one, minus this.
+                id: {
+                    type: field.ref?.strategy === 'lookup'
+                        ? new GraphQLNonNull(iriScalar)
+                        : iriScalar,
                 },
+                ...Object.fromEntries(outputFields(nested).map((nestedField) => [
+                    nestedField.name,
+                    outputFieldConfig(nestedField),
+                ])),
+            }),
         }));
-        if (nested === undefined) {
-            return;
-        }
         // A nested reference type’s own surfaced references are types too; register
         // them now, so every type exists before the thunks above are called.
         for (const nestedField of outputFields(nested)) {
@@ -421,7 +413,9 @@ export function buildGraphQLSchema(schema, options = {}) {
                             resolve: (source) => iriOf(source[field.name]) ?? null,
                         };
                 }
-                const referenceType = referenceTypes.get(field.ref?.typeName ?? '');
+                const referenceType = referenceTypes.get((field.ref === undefined
+                    ? undefined
+                    : referencedTypeName(field.ref)) ?? '');
                 return field.array === true
                     ? {
                         type: nonNullListOf(referenceType),
@@ -472,13 +466,15 @@ export function buildGraphQLSchema(schema, options = {}) {
      *  names no target), a `keyword` on literals. */
     function plainWhereFieldType(field) {
         switch (filterOperatorFor(field.kind)) {
-            case 'in':
+            case 'in': {
                 if (field.kind !== 'reference') {
                     return keywordFilter;
                 }
-                return field.ref?.typeName === undefined
-                    ? iriFilter
-                    : targetFilter(field.ref.typeName);
+                // A lookup keys on its `target`, an idOnly/inline on its `typeName`:
+                // one reading, so a filter is typed by whatever names the referent.
+                const target = field.ref === undefined ? undefined : referencedTypeName(field.ref);
+                return target === undefined ? iriFilter : targetFilter(target);
+            }
             case 'range':
                 return field.kind === 'integer'
                     ? intRange
@@ -691,14 +687,20 @@ export function buildGraphQLSchema(schema, options = {}) {
                     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) => {
+            resolve: async (_source, args, context, info) => {
                 const built = argsToQuery(args, context, searchType, maxPerPage, joins);
+                // What the client selected decides what each lookup fetches, so the
+                // engine carries the referent fields this query asked for and no more.
+                const resolve = projectionFor(info, searchType, (target) => rootTypesByName.get(target));
                 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,
+                    // A `queryDefaults` policy may add its own projection; the selection
+                    // set is what the caller actually asked for, so it wins.
+                    resolve: resolve ?? finalQuery.resolve,
                     facets: [],
                 });
                 return {

package/dist/handler.d.ts

@@ -6,7 +6,9 @@ import { type BuildGraphQLSchemaOptions, type SearchContext } from './build-sche
  * A framework-agnostic request handler: SvelteKit, Fastify (via a
  * `Request`/`Response` bridge), Hono and plain `node:http` (via
  * `@whatwg-node/server`, which graphql-yoga uses internally) all mount it
- * directly.
+ * directly. On a runtime that has its own Fetch classes, the returned
+ * `Response` is an instance of that runtime’s global, so a host that checks
+ * `instanceof Response` accepts it as is.
  */
 export type SearchGraphQLHandler = (request: Request) => Promise<Response>;
 /**

package/dist/handler.d.ts.map

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

package/dist/handler.js

@@ -21,6 +21,17 @@ export function createSearchGraphQLHandler(options) {
     const yoga = createYoga({
         schema,
         graphqlEndpoint,
+        // Build responses with the runtime’s own Fetch classes, so the handler’s
+        // `Response` is the class a host framework checks against. graphql-yoga
+        // otherwise uses `@whatwg-node/fetch`, a ponyfill: spec-conformant, but a
+        // different class, which every host that checks `instanceof Response`
+        // nominally – SvelteKit, Hono, Next – rejects. yoga ignores the keys a
+        // runtime leaves `undefined`, so one without them keeps the ponyfill.
+        fetchAPI: {
+            Request: globalThis.Request,
+            Response: globalThis.Response,
+            ReadableStream: globalThis.ReadableStream,
+        },
         landingPage: false,
         graphiql: options.playground !== false,
         renderGraphiQL: options.renderPlayground ?? renderGraphiQL,

package/dist/projection.d.ts

@@ -0,0 +1,24 @@
+import { type GraphQLResolveInfo } from 'graphql';
+import { type ReferenceProjection, type SearchType } from '@lde/search';
+/** How a `lookup` field’s `target` resolves to the Root Type it reads from –
+ *  supplied by the caller, which holds the schema. */
+export type TargetResolver = (target: string) => SearchType | undefined;
+/**
+ * Build the {@link ReferenceProjection} a query’s **selection set** asks for, so
+ * the engine fetches each referent’s fields at the depth the client selected and
+ * no further. Without it a lookup would either fetch every field of every target
+ * at every depth – unbounded, since targets reference one another – or serve
+ * fields nothing filled.
+ *
+ * Only `lookup` references appear: an `idOnly` reference surfaces as its bare
+ * IRI, and an `inline` one is already carried by the hit. A selection naming
+ * nothing but `id` asks for no `fields`; the id is on the referring document
+ * already, so it costs no round-trip.
+ *
+ * Fragments are followed; `@skip`/`@include` are deliberately **not** evaluated,
+ * so a conditionally-skipped selection is fetched and discarded rather than
+ * omitted and then missing. Over-fetching a field is recoverable; a null where
+ * the client asked for a value is not.
+ */
+export declare function projectionFor(info: Pick<GraphQLResolveInfo, 'fieldNodes' | 'fragments'>, searchType: SearchType, targetOf: TargetResolver): ReferenceProjection | undefined;
+//# sourceMappingURL=projection.d.ts.map

package/dist/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGxE;sDACsD;AACtD,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;AAIxE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,YAAY,GAAG,WAAW,CAAC,EAC1D,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,cAAc,GACvB,mBAAmB,GAAG,SAAS,CAajC"}

package/dist/projection.js

@@ -0,0 +1,119 @@
+import { Kind, } from 'graphql';
+import { fieldNamed } from '@lde/search/adapter';
+/**
+ * Build the {@link ReferenceProjection} a query’s **selection set** asks for, so
+ * the engine fetches each referent’s fields at the depth the client selected and
+ * no further. Without it a lookup would either fetch every field of every target
+ * at every depth – unbounded, since targets reference one another – or serve
+ * fields nothing filled.
+ *
+ * Only `lookup` references appear: an `idOnly` reference surfaces as its bare
+ * IRI, and an `inline` one is already carried by the hit. A selection naming
+ * nothing but `id` asks for no `fields`; the id is on the referring document
+ * already, so it costs no round-trip.
+ *
+ * Fragments are followed; `@skip`/`@include` are deliberately **not** evaluated,
+ * so a conditionally-skipped selection is fetched and discarded rather than
+ * omitted and then missing. Over-fetching a field is recoverable; a null where
+ * the client asked for a value is not.
+ */
+export function projectionFor(info, searchType, targetOf) {
+    // `items` carries the hits; the root field’s other selections (pagination,
+    // facets) are served without touching a referent.
+    const items = info.fieldNodes.flatMap((node) => selectionsNamed(node.selectionSet, 'items', info.fragments));
+    const projection = fromSelections(items, searchType, info.fragments, targetOf);
+    return Object.keys(projection).length === 0 ? undefined : projection;
+}
+/** The selection sets of every field named `name`, fragments followed. */
+function selectionsNamed(selectionSet, name, fragments) {
+    const found = [];
+    for (const field of fieldsOf(selectionSet, fragments)) {
+        if (field.name.value === name && field.selectionSet !== undefined) {
+            found.push(field.selectionSet);
+        }
+    }
+    return found;
+}
+/** Every field selection in a set, with fragment spreads flattened in place. */
+function fieldsOf(selectionSet, fragments) {
+    if (selectionSet === undefined) {
+        return [];
+    }
+    return selectionSet.selections.flatMap((selection) => {
+        switch (selection.kind) {
+            case Kind.FIELD:
+                return [selection];
+            case Kind.INLINE_FRAGMENT:
+                return fieldsOf(selection.selectionSet, fragments);
+            case Kind.FRAGMENT_SPREAD: {
+                const fragment = fragments[selection.name.value];
+                return fragment === undefined
+                    ? []
+                    : fieldsOf(fragment.selectionSet, fragments);
+            }
+        }
+    });
+}
+/** Whether a type serves this field name – what a projection may ask for. */
+function servesField(searchType, name) {
+    return fieldNamed(searchType, name)?.output === true;
+}
+/** Union two projections level by level, so neither loses what it asked for. */
+function mergeProjections(left, right) {
+    if (left === undefined) {
+        return right;
+    }
+    const merged = { ...left };
+    for (const [name, level] of Object.entries(right)) {
+        const existing = merged[name];
+        merged[name] =
+            existing === undefined
+                ? level
+                : {
+                    fields: [
+                        ...new Set([...(existing.fields ?? []), ...(level.fields ?? [])]),
+                    ],
+                    resolve: level.resolve === undefined
+                        ? existing.resolve
+                        : mergeProjections(existing.resolve, level.resolve),
+                };
+    }
+    return merged;
+}
+/** One level: which lookups were selected, and what each asked for. */
+function fromSelections(selectionSets, searchType, fragments, targetOf) {
+    const projection = {};
+    for (const selectionSet of selectionSets) {
+        for (const selected of fieldsOf(selectionSet, fragments)) {
+            const field = fieldNamed(searchType, selected.name.value);
+            if (field === undefined ||
+                field.kind !== 'reference' ||
+                field.ref?.strategy !== 'lookup') {
+                continue;
+            }
+            // The target's own declaration decides what its selections mean, so the
+            // level below is read against it rather than against this type.
+            const target = targetOf(field.ref.target);
+            // Only what the target actually serves. A selection carries more than
+            // that: `id` is on the referring document already, and every GraphQL
+            // client worth the name injects `__typename` into every selection set –
+            // asking the engine for either would fail the query at the port's guard.
+            const wanted = fieldsOf(selected.selectionSet, fragments)
+                .map((node) => node.name.value)
+                .filter((name) => target === undefined ? false : servesField(target, name));
+            const entry = (projection[selected.name.value] ??= {});
+            entry.fields = [...new Set([...(entry.fields ?? []), ...wanted])];
+            if (target !== undefined && selected.selectionSet !== undefined) {
+                const below = fromSelections([selected.selectionSet], target, fragments, targetOf);
+                if (Object.keys(below).length > 0) {
+                    // Merged level by level, not key by key: one lookup selected twice –
+                    // two fragments each spreading it – must union what each asked for,
+                    // or the second selection silently replaces the first and a field
+                    // the client asked for is never fetched.
+                    entry.resolve = mergeProjections(entry.resolve, below);
+                }
+            }
+        }
+    }
+    return projection;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.23.1",
+  "version": "0.24.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.21.1",
+    "@lde/search": "^0.22.0",
     "commander": "^15.0.0",
     "dataloader": "^2.2.3",
     "graphql": "^16.9.0",