@lde/search-api-graphql 0.21.0 → 0.21.1

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;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;AAqGD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,aAAa,CA4pBf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAER"}

package/dist/build-schema.js

@@ -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();
@@ -545,11 +566,31 @@ 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);
@@ -636,11 +677,11 @@ function argsToQuery(args, context, searchType, maxPerPage) {
     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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "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",