@lde/search-api-graphql 0.20.0 → 0.20.2

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

package/dist/build-schema.js

@@ -179,7 +179,13 @@ export function buildGraphQLSchema(schema, options = {}) {
             registerReferenceType(field, searchType);
         }
     }
+    /** A field's config, plus the declared {@link SearchFieldBase.description}
+     *  wherever the field surfaces – so one sentence written on the declaration
+     *  reaches the playground, introspection and an editor alike. */
     function outputFieldConfig(field) {
+        return { ...outputFieldType(field), description: field.description };
+    }
+    function outputFieldType(field) {
         switch (field.kind) {
             case 'text':
                 return labelList((source) => source[field.name]);
@@ -271,7 +277,10 @@ export function buildGraphQLSchema(schema, options = {}) {
                 [ID_FIELD]: { type: stringFilter },
             };
             for (const field of filterable) {
-                fields[field.name] = { type: whereFieldType(field) };
+                fields[field.name] = {
+                    type: whereFieldType(field),
+                    description: field.description,
+                };
             }
             return fields;
         };

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.0",
+  "version": "0.20.2",
   "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.0",
+    "@lde/search": "^0.18.2",
+    "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
+    }
   }
 }