@lde/search-api-graphql 0.20.3 → 0.21.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,EAKL,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAkBrB,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,CA6gBf;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;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"}

package/dist/build-schema.js

@@ -1,9 +1,58 @@
-import { GraphQLBoolean, GraphQLEnumType, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, printSchema, } from 'graphql';
-import { AND_KEY, DEFAULT_LABEL_FIELD, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, OR_KEY, isRangeFacet, labelFieldNameOf, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+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 { 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;
+/**
+ * The IRI scalar: an absolute IRI, serialized as a string.
+ *
+ * Its job is to make a filter’s **element type** tell a consumer what the filter
+ * keys on, so “which of this type’s fields accept an IRI” is answerable by
+ * introspection instead of by a hardcoded, per-deployment list of predicates
+ * that drifts whenever a field is added. Wire-compatible with `String` – but
+ * deliberately NOT the same type, since the whole point is that the two are
+ * distinguishable. Consequence for consumers: a variable must be declared
+ * `[IRI!]`, not `[String!]`, because GraphQL checks variable usage nominally.
+ *
+ * **Input coercion validates; output serialization does not.** Rejecting a bare
+ * token on the way in is what turns `where: { material: { in: ["boerenbont"] } }`
+ * from a silent empty result into an error saying why – the same job
+ * `argsToQuery` already does for an out-of-range `perPage`.
+ *
+ * It validates on the way **out** too, and deliberately: a type that is enforced
+ * in one direction only is not a type a consumer can rely on, and the coarse
+ * discovery strategy reads `IRI` as the promise that a value is a selection key.
+ * Serving a non-IRI under it would make the promise false exactly where a
+ * consumer acts on it. The projection applies the same rule at the source, so
+ * the only way to reach this error is an index written before it existed – which
+ * a reindex fixes, and which failing names instead of hiding.
+ *
+ * What counts as an IRI is {@link isAbsoluteIri} – shared with the projection,
+ * so the surface cannot promise something the index contradicts.
+ */
+const iriScalar = new GraphQLScalarType({
+    name: 'IRI',
+    description: 'An absolute IRI (RFC 3987), serialized as a string. Any scheme – `https:`, `urn:`, `doi:`, `ark:` – not only HTTP. A field or filter typed `IRI` keys on identity, never on a literal.',
+    specifiedByURL: 'https://www.rfc-editor.org/rfc/rfc3987',
+    serialize: (value) => assertIriOut(GraphQLString.serialize(value)),
+    parseValue: (value) => assertIri(GraphQLString.parseValue(value)),
+    parseLiteral: (node, variables) => assertIri(GraphQLString.parseLiteral(node, variables)),
+});
+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.`);
+    }
+    return value;
+}
+/** Outbound the fault is the index, not the caller, so the message points at
+ *  the fix rather than at the query. */
+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;
+}
 /** 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();
@@ -35,25 +84,37 @@ export function buildGraphQLSchema(schema, options = {}) {
             value: { type: new GraphQLNonNull(GraphQLString) },
         },
     });
-    // A plain value facet bucket: a selection key, its count, and (for reference
-    // facets) the engine-resolved data label; null for token/free-string facets
-    // whose display the consumer owns.
-    const valueBucket = new GraphQLObjectType({
-        name: 'ValueBucket',
-        fields: {
-            value: { type: new GraphQLNonNull(GraphQLString) },
-            count: { type: new GraphQLNonNull(GraphQLInt) },
-            label: {
-                type: new GraphQLList(new GraphQLNonNull(languageString)),
-                resolve: (bucket, _args, context) => {
-                    const label = bucket.label;
-                    return label
-                        ? toLanguageStrings(label, context.acceptLanguage, languageOrder)
-                        : null;
-                },
+    // A value facet bucket: a selection key, its count, and (for reference facets)
+    // the engine-resolved data label; null for token/free-string facets whose
+    // display the consumer owns. Only the key’s type varies between the two – a
+    // facet keys on whatever its field keys on – so both are built from here and
+    // cannot drift apart.
+    const valueBucketFields = (keyType) => ({
+        value: { type: new GraphQLNonNull(keyType) },
+        count: { type: new GraphQLNonNull(GraphQLInt) },
+        label: {
+            type: new GraphQLList(new GraphQLNonNull(languageString)),
+            resolve: (bucket, _args, context) => {
+                const label = bucket.label;
+                return label
+                    ? toLanguageStrings(label, context.acceptLanguage, languageOrder)
+                    : null;
             },
         },
     });
+    const valueBucket = new GraphQLObjectType({
+        name: 'ValueBucket',
+        fields: valueBucketFields(GraphQLString),
+    });
+    // A reference facet’s bucket, whose `value` is an `IRI` because the field it
+    // buckets keys on identity. This is what makes the round trip typed end to
+    // end: the bucket a consumer selects feeds straight into the ‹Target›Filter
+    // that selects it, with no `String`-to-`IRI` boundary in between – the
+    // contract BooleanBucket already keeps for `is`.
+    const iriBucket = new GraphQLObjectType({
+        name: 'IriBucket',
+        fields: valueBucketFields(iriScalar),
+    });
     // A numeric range-facet bin: half-open `[min, max)` bounds (max null on an
     // open-ended top bin) and the count of documents in it.
     const rangeBucket = new GraphQLObjectType({
@@ -92,12 +153,63 @@ export function buildGraphQLSchema(schema, options = {}) {
         name: 'SortDirection',
         values: { ASC: { value: 'asc' }, DESC: { value: 'desc' } },
     });
-    const stringFilter = new GraphQLInputObjectType({
-        name: 'StringFilter',
+    // Membership filters, split by what the field keys on. A `keyword` field
+    // holds literals (an accession number, an ISO 8601 string, a token); a
+    // `reference` holds identity. One shared `StringFilter` said neither, which
+    // left `where: { material: { in: ["boerenbont"] } }` valid, silent and empty.
+    const keywordFilter = new GraphQLInputObjectType({
+        name: 'KeywordFilter',
+        description: 'Matches a field holding literal values.',
         fields: {
             in: { type: new GraphQLList(new GraphQLNonNull(GraphQLString)) },
         },
     });
+    // The fallback for a reference whose referent is nameable as no type: a
+    // canonical vocabulary URI, a licence, a content URL. Its `in` element type is
+    // what the COARSE discovery strategy matches on – select every criterion field
+    // whose filter takes IRIs, and you have the complete reference-field set with
+    // no origin collection at all.
+    const iriFilter = new GraphQLInputObjectType({
+        name: 'IRIFilter',
+        description: 'Matches a field holding IRIs that belong to no collection this API serves.',
+        fields: { in: { type: new GraphQLList(new GraphQLNonNull(iriScalar)) } },
+    });
+    /**
+     * The filter input for IRIs of one named target, `‹TypeName›Filter` – created
+     * once per target and shared by every field pointing at it, INCLUDING the
+     * target’s own `id`. That sharing is the whole mechanism: a consumer resolves
+     * the collection it is browsing to its filter type through `‹Type›Where.id`,
+     * then selects the criterion fields of every other type whose filter is that
+     * same type. The name is COMPARED, never parsed – a generic consumer needs no
+     * more knowledge of `TermFilter` than it already needs of `terms`.
+     */
+    const targetFilters = new Map();
+    function targetFilter(typeName) {
+        const existing = targetFilters.get(typeName);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const name = `${typeName}Filter`;
+        // graphql-js would reject the duplicate too, but only once the whole schema
+        // is assembled and without saying which declaration caused it. Checked
+        // against every name already claimed – the built-in filters, the `IRI`
+        // scalar, and every root/reference type – since a declaration is free to
+        // name a type `TermFilter` beside a root type `Term`.
+        if (name === keywordFilter.name ||
+            name === iriFilter.name ||
+            name === iriScalar.name ||
+            takenTypeNames.has(name)) {
+            throw new Error(`Type “${typeName}” would be filtered through “${name}”, which is already the name of another type; rename one of them.`);
+        }
+        takenTypeNames.add(name);
+        const filter = new GraphQLInputObjectType({
+            name,
+            description: `Matches a field holding IRIs of ${typeName}.`,
+            fields: { in: { type: new GraphQLList(new GraphQLNonNull(iriScalar)) } },
+        });
+        targetFilters.set(typeName, filter);
+        return filter;
+    }
     const intRange = rangeInput('IntRange', GraphQLInt);
     const floatRange = rangeInput('FloatRange', GraphQLFloat);
     const dateRange = rangeInput('DateRange', GraphQLString);
@@ -145,7 +257,13 @@ export function buildGraphQLSchema(schema, options = {}) {
      * stays the id-plus-label pair its strategy carries.
      */
     function registerReferenceType(field, owner) {
-        if (field.kind !== 'reference' || field.ref === undefined) {
+        if (field.kind !== 'reference' ||
+            field.ref === undefined ||
+            // An `idOnly` reference carries the IRI and nothing else, so it surfaces
+            // 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) {
             return;
         }
         if (referenceTypes.has(field.ref.typeName)) {
@@ -176,14 +294,16 @@ export function buildGraphQLSchema(schema, options = {}) {
             // 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.
-                    id: { type: new GraphQLNonNull(GraphQLString) },
                     [labelKeyOf(field)]: labelList((source) => source.label),
                 }
                 : {
-                    id: { type: GraphQLString },
+                    // 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),
@@ -222,6 +342,30 @@ export function buildGraphQLSchema(schema, options = {}) {
                     }
                     : { type: scalarOutput(GraphQLString, field) };
             case 'reference': {
+                // `idOnly`: the IRI itself, not an object wrapping it – so a field whose
+                // referent this deployment does not describe (a vocabulary URI, a
+                // licence, a content URL) reads as the flat list of IRIs it is, while
+                // still declaring what it holds.
+                //
+                // The IR still carries a `Reference` here, as it does for every
+                // non-inline reference (see `SearchValue`): the strategy is a statement
+                // about the SURFACE, not about the port, so the flattening belongs on
+                // this side rather than in each adapter’s result reconstruction. A
+                // referent carrying no IRI drops out instead of nulling the field.
+                if (field.ref?.strategy === 'idOnly') {
+                    const iriOf = (value) => value?.id;
+                    return field.array === true
+                        ? {
+                            type: nonNullListOf(iriScalar),
+                            resolve: (source) => (source[field.name] ?? [])
+                                .map(iriOf)
+                                .filter((iri) => iri !== undefined),
+                        }
+                        : {
+                            type: scalarOutput(iriScalar, field),
+                            resolve: (source) => iriOf(source[field.name]) ?? null,
+                        };
+                }
                 const referenceType = referenceTypes.get(field.ref?.typeName ?? '');
                 return field.array === true
                     ? {
@@ -256,10 +400,18 @@ export function buildGraphQLSchema(schema, options = {}) {
                 };
         }
     }
+    /** 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) {
         switch (filterOperatorFor(field.kind)) {
             case 'in':
-                return stringFilter;
+                if (field.kind !== 'reference') {
+                    return keywordFilter;
+                }
+                return field.ref?.typeName === undefined
+                    ? iriFilter
+                    : targetFilter(field.ref.typeName);
             case 'range':
                 return field.kind === 'integer'
                     ? intRange
@@ -277,7 +429,7 @@ export function buildGraphQLSchema(schema, options = {}) {
             name: typeName,
             fields: () => {
                 const fields = {
-                    id: { type: new GraphQLNonNull(GraphQLString) },
+                    id: { type: new GraphQLNonNull(iriScalar) },
                 };
                 for (const field of outputFields(searchType)) {
                     fields[field.name] = outputFieldConfig(field);
@@ -299,7 +451,11 @@ export function buildGraphQLSchema(schema, options = {}) {
          */
         const fieldKeys = () => {
             const fields = {
-                [ID_FIELD]: { type: stringFilter },
+                // 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] = {
@@ -362,8 +518,8 @@ export function buildGraphQLSchema(schema, options = {}) {
             },
         });
         // Keyed facets object: one field per facetable field, typed by its kind
-        // (range fields → [RangeBucket!], boolean fields → [BooleanBucket!], else
-        // [ValueBucket!]). Only the selected
+        // (range fields → [RangeBucket!], boolean fields → [BooleanBucket!],
+        // reference fields → [IriBucket!], 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.
@@ -419,11 +575,16 @@ 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. */
+     *  boolean for a boolean one, an `IRI` key for a reference, a literal key
+     *  otherwise. The reference test is the one {@link whereFieldType} applies, so
+     *  a bucket and the filter it feeds cannot disagree about what the field keys
+     *  on. */
     function bucketTypeFor(field) {
         if (isRangeFacet(field))
             return rangeBucket;
-        return field.kind === 'boolean' ? booleanBucket : valueBucket;
+        if (field.kind === 'boolean')
+            return booleanBucket;
+        return field.kind === 'reference' ? iriBucket : valueBucket;
     }
     /** The keyed facets object for one type (only called with ≥ 1 facetable field). */
     function facetsTypeFor(typeName, facetable) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.20.3",
+  "version": "0.21.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.18.3",
+    "@lde/search": "^0.19.0",
     "commander": "^15.0.0",
     "dataloader": "^2.2.3",
     "graphql": "^16.9.0",