@lde/search-api-graphql 0.20.1 → 0.20.3

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;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,CAiff;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;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"}

package/dist/build-schema.js

@@ -1,5 +1,5 @@
 import { GraphQLBoolean, GraphQLEnumType, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, printSchema, } from 'graphql';
-import { AND_KEY, facetableFields, filterableFields, filterOn, filterOperatorFor, ID_FIELD, OR_KEY, isRangeFacet, nestedReferenceType, outputFields, pageForOffset, sortableFields, unixSecondsToIso, } from '@lde/search/adapter';
+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 { defaultLanguageOrder, toLanguageStrings, } from './language.js';
 import { createFacetLoader } from './facet-batch.js';
 const nonNullListOf = (type) => new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(type)));
@@ -21,7 +21,8 @@ function screamingSnake(name) {
 export function buildGraphQLSchema(schema, options = {}) {
     const languageOrder = options.languageOrder ?? defaultLanguageOrder;
     const maxPerPage = options.maxPerPage ?? 100;
-    const rootTypeNames = new Set([...schema.values()].map((searchType) => searchType.name));
+    const rootTypesByName = new Map([...schema.values()].map((searchType) => [searchType.name, searchType]));
+    const rootTypeNames = new Set(rootTypesByName.keys());
     for (const name of Object.keys(options.types ?? {})) {
         if (!rootTypeNames.has(name)) {
             throw new Error(`Options given for type “${name}”, which is not in the search schema.`);
@@ -121,6 +122,19 @@ export function buildGraphQLSchema(schema, options = {}) {
     // and rejects duplicate names schema-wide.
     const referenceTypes = new Map();
     const takenTypeNames = new Set(rootTypeNames);
+    /** 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));
+    }
     /**
      * Register the GraphQL type one reference field is served as, once per
      * referenced shape. A **surfaced inline** reference is served as the nested
@@ -131,9 +145,17 @@ 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 ||
-            referenceTypes.has(field.ref.typeName)) {
+        if (field.kind !== 'reference' || 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.`);
+            }
             return;
         }
         const { typeName } = field.ref;
@@ -145,17 +167,20 @@ export function buildGraphQLSchema(schema, options = {}) {
         }
         takenTypeNames.add(graphQLName);
         const nested = nestedReferenceType(schema, field);
+        if (nested === undefined) {
+            labelKeys.set(typeName, labelKeyOf(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
                 ? {
+                    // 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) },
-                    // `label`, the same word the label source declares and a
-                    // reference facet’s bucket carries: one resolved label, one
-                    // name for it wherever it surfaces.
-                    label: labelList((source) => source.label),
+                    [labelKeyOf(field)]: labelList((source) => source.label),
                 }
                 : {
                     id: { type: GraphQLString },

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { printSchemaModuleSdl } from './print-sdl.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const program = new Command()
+    .name('search-print-sdl')
+    .description('Print the GraphQL contract of a mounted @lde/search schema-declaration module: the published surface consumers meet. Commit the output so every pull request that moves the surface shows the move.')
+    .version(version)
+    .requiredOption('--module <path>', 'path to the schema-declaration module, the same file the indexer and the served API mount')
+    .option('--out <path>', 'file to write the SDL to (default: standard output)')
+    .option('--no-format', 'write the SDL as GraphQL prints it, instead of formatting it with the Prettier configuration that applies to the output file');
+program.parse();
+const options = program.opts();
+try {
+    const sdl = await printSchemaModuleSdl({
+        modulePath: options.module,
+        outputPath: options.out,
+        format: options.format,
+    });
+    if (options.out === undefined) {
+        process.stdout.write(sdl);
+    }
+    else {
+        console.info(`Wrote ${options.out}`);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+}

package/dist/print-sdl.d.ts

@@ -0,0 +1,28 @@
+/** What {@link printSchemaModuleSdl} needs to know. */
+export interface PrintSchemaModuleSdlOptions {
+    /** Path to the mounted schema-declaration module – the same file the
+     *  indexer and the served API mount, so the printed contract cannot describe
+     *  a different API from the one served. Its optional `schemaOptions` export
+     *  is forwarded to {@link printGraphQLSchema}. */
+    readonly modulePath: string;
+    /** Where to write the SDL. Omit to only return it. */
+    readonly outputPath?: string;
+    /** Format the SDL with Prettier, resolving the config that applies to
+     *  {@link outputPath} (default `true`). Keeps the file byte-identical to what
+     *  a repo’s own formatter would produce, so a formatting pre-commit hook and
+     *  this writer cannot spell the same schema differently and overwrite each
+     *  other in turn. Requires `prettier` to be installed alongside this package.
+     */
+    readonly format?: boolean;
+}
+/**
+ * Print the GraphQL contract of a mounted schema-declaration module, and
+ * optionally write it to a file – the published surface consumers meet, which
+ * a repository commits so every pull request that moves it shows the move.
+ *
+ * Returns the SDL. Throws with the module path in the message for every
+ * failure mode of the module itself (unreadable, wrong export shape, invalid
+ * declaration), so a broken contract build names the file to fix.
+ */
+export declare function printSchemaModuleSdl({ modulePath, outputPath, format, }: PrintSchemaModuleSdlOptions): Promise<string>;
+//# sourceMappingURL=print-sdl.d.ts.map

package/dist/print-sdl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"print-sdl.d.ts","sourceRoot":"","sources":["../src/print-sdl.ts"],"names":[],"mappings":"AAMA,uDAAuD;AACvD,MAAM,WAAW,2BAA2B;IAC1C;;;sDAGkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,UAAU,EACV,UAAU,EACV,MAAa,GACd,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB/C"}

package/dist/print-sdl.js

@@ -0,0 +1,48 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadSchemaModule, optionalObjectExport } from '@lde/search/module';
+import { printGraphQLSchema } from './build-schema.js';
+/**
+ * Print the GraphQL contract of a mounted schema-declaration module, and
+ * optionally write it to a file – the published surface consumers meet, which
+ * a repository commits so every pull request that moves it shows the move.
+ *
+ * Returns the SDL. Throws with the module path in the message for every
+ * failure mode of the module itself (unreadable, wrong export shape, invalid
+ * declaration), so a broken contract build names the file to fix.
+ */
+export async function printSchemaModuleSdl({ modulePath, outputPath, format = true, }) {
+    const { schema, moduleExports } = await loadSchemaModule(modulePath);
+    const sdl = printGraphQLSchema(schema, optionalObjectExport(moduleExports, 'schemaOptions', modulePath));
+    // Prettier resolves its config from the file it is about to format, so a
+    // stdout run still has to name the path the SDL would live at.
+    const filepath = resolve(outputPath ?? 'schema.graphql');
+    const output = format ? await formatWithPrettier(sdl, filepath) : sdl;
+    if (outputPath !== undefined) {
+        await writeFile(filepath, output, 'utf8');
+    }
+    return output;
+}
+/** Prettier is an optional peer: the consumer’s own version formats the file,
+ *  because matching the consumer’s repository is the whole point. */
+async function formatWithPrettier(sdl, filepath) {
+    let prettier;
+    try {
+        prettier = await import('prettier');
+    }
+    catch (cause) {
+        // Reports what went wrong rather than assuming it is missing: a broken
+        // install and a plugin that throws at module scope both land here, and
+        // “install prettier” is unhelpful advice for either.
+        throw new Error(`Formatting the SDL requires “prettier”, an optional peer dependency of @lde/search-api-graphql, which could not be loaded: ${String(cause)}. Install it, or turn formatting off.`, { cause });
+    }
+    return prettier.format(sdl, {
+        // The CLI reads `.editorconfig` by default and the Node API does not, so
+        // leaving it off would have `prettier --write` reformat what we just wrote.
+        ...(await prettier.resolveConfig(filepath, { editorconfig: true })),
+        filepath,
+        // Named outright, so an output path Prettier cannot map to a parser (say
+        // `.sdl`) formats instead of failing on an inferred-parser error.
+        parser: 'graphql',
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-api-graphql",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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",
@@ -15,11 +15,20 @@
       "import": "./dist/index.js",
       "development": "./src/index.ts",
       "default": "./dist/index.js"
+    },
+    "./print-sdl": {
+      "types": "./dist/print-sdl.d.ts",
+      "import": "./dist/print-sdl.js",
+      "development": "./src/print-sdl.ts",
+      "default": "./dist/print-sdl.js"
     }
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "search-print-sdl": "dist/cli.js"
+  },
   "files": [
     "dist",
     "!**/*.tsbuildinfo"
@@ -28,11 +37,20 @@
     "@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.1",
+    "@lde/search": "^0.18.3",
+    "commander": "^15.0.0",
     "dataloader": "^2.2.3",
     "graphql": "^16.9.0",
     "graphql-yoga": "^5.21.2",
     "negotiator": "^1.0.0",
     "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "prettier": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "prettier": {
+      "optional": true
+    }
   }
 }