@dudousxd/nestjs-codegen 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @dudousxd/nestjs-codegen
 
+## 0.27.0
+
+### Minor Changes
+
+- [#101](https://github.com/DavideCarvalho/nestjs-codegen/pull/101) [`eb98ec8`](https://github.com/DavideCarvalho/nestjs-codegen/commit/eb98ec87be042b56a068bff9d4d71c35b6e67283) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Several page globs and several Inertia apps (scopes).
+
+  - `pages.glob` takes one glob or an array. Each page is named relative to the static base of
+    the glob that matched it (brace globs included: the base stops at the first segment with
+    glob syntax), and two files resolving to the same page name are an error.
+  - `pages.scopes` declares more Inertia apps, one per `InertiaModule.forFeature({ scope })`:
+    `{ glob, prefix?, componentNameStrategy? }`. A scope's page names get the prefix
+    `'<scope>/'` by default (`minimal/pages/Home.tsx` → `minimal/Home`). Every page lands in
+    `InertiaPages`/`InertiaPageName`; `pages.d.ts` also exports `InertiaScopePages` and
+    `InertiaScopePageName<S>`, `components.json` records each page's `scope`, and the watcher and
+    the skip-if-unchanged hash cover every scope's pages.
+  - The top-level `scopes` option never had an effect; it is deprecated and now warns.
+
+- [#100](https://github.com/DavideCarvalho/nestjs-codegen/pull/100) [`1cc8944`](https://github.com/DavideCarvalho/nestjs-codegen/commit/1cc8944126b794cdd5748e2417f448cd1e157395) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Request handles are real Promises, and `api.ts` compiles under strict compiler flags.
+
+  - A generated leaf call (`api.users.create({ body })`) now returns a `RequestHandle<R>`: a
+    lazy, memoized `Promise<R>` that also carries `fetch()` and the extension members
+    (`queryKey`, `queryOptions`, `mutationOptions`, …). It can be returned from a TanStack
+    `mutationFn`/`queryFn`, passed to `Promise.all` or assigned to `Promise<T>` without calling
+    `.fetch()` first. Nothing is sent until it is awaited, so building `queryOptions()` or
+    reading `queryKey()` never fires a request. `.fetch()` keeps working.
+  - `api.ts` imports from `routes.ts` only the names it uses (no unused `ROUTES`/`RouteName`/…),
+    a leaf with no input to read takes no parameter, and `infiniteQueryOptions()` no longer
+    passes `getPreviousPageParam: undefined`. The output is clean under `noUnusedLocals`,
+    `noUnusedParameters`, `exactOptionalPropertyTypes`, `noImplicitOverride`,
+    `noUncheckedIndexedAccess` and `noPropertyAccessFromIndexSignature`; a fixture test compiles
+    it with all of them.
+
 ## 0.26.0
 
 ### Minor Changes

package/README.md

@@ -53,8 +53,8 @@ export class AppModule {}
 ```
 
 The generated `api.ts` exports a `createApi(fetcher)` factory — create the client once,
-injecting your fetcher. Each endpoint is a **unified awaitable handle**: `await` it to run
-the request.
+injecting your fetcher. Each endpoint is a **unified awaitable handle**: a lazy, memoized
+`Promise` — `await` it (or return it from a TanStack `mutationFn`) to run the request.
 
 ```ts title="src/lib/api.ts"
 import { createApi } from '../generated/api';

package/dist/cli/main.cjs

@@ -117,11 +117,32 @@ function validateUserConfig(userConfig) {
       "validation adapter is required \u2014 install @dudousxd/nestjs-codegen-zod and pass zodAdapter, or use @dudousxd/nestjs-codegen-valibot / -arktype"
     );
   }
-  if (userConfig.pages && typeof userConfig.pages.glob !== "string") {
+  if (userConfig.pages && !isGlobInput(userConfig.pages.glob)) {
     throw new ConfigError(
-      "Config validation failed: `pages.glob` must be a string when `pages` is set"
+      "Config validation failed: `pages.glob` must be a string or a non-empty array of strings when `pages` is set"
     );
   }
+  for (const [scope, scopeConfig] of Object.entries(userConfig.pages?.scopes ?? {})) {
+    if (scope === "default") {
+      throw new ConfigError(
+        'Config validation failed: `pages.scopes` cannot declare "default" \u2014 the default app is `pages.glob` (InertiaModule.forRoot).'
+      );
+    }
+    if (!isGlobInput(scopeConfig?.glob)) {
+      throw new ConfigError(
+        `Config validation failed: \`pages.scopes.${scope}.glob\` must be a string or a non-empty array of strings`
+      );
+    }
+  }
+  if (userConfig.scopes && Object.keys(userConfig.scopes).length > 0) {
+    console.warn(
+      "[nestjs-codegen] The top-level `scopes` option has no effect and is deprecated. For several Inertia apps use `pages.scopes` (one entry per InertiaModule.forFeature scope); for several controller sets use one `contracts.glob` (e.g. a brace glob)."
+    );
+  }
+}
+function isGlobInput(value) {
+  if (typeof value === "string") return true;
+  return Array.isArray(value) && value.length > 0 && value.every((glob) => typeof glob === "string");
 }
 function applyDefaults(userConfig, cwd) {
   validateUserConfig(userConfig);
@@ -149,7 +170,17 @@ function applyDefaults(userConfig, cwd) {
     pages: userConfig.pages ? {
       glob: userConfig.pages.glob,
       propsExport: userConfig.pages.propsExport ?? "ComponentProps",
-      componentNameStrategy: userConfig.pages.componentNameStrategy ?? "relative-no-ext"
+      componentNameStrategy: userConfig.pages.componentNameStrategy ?? "relative-no-ext",
+      scopes: Object.fromEntries(
+        Object.entries(userConfig.pages.scopes ?? {}).map(([scope, scopeConfig]) => [
+          scope,
+          {
+            glob: scopeConfig.glob,
+            prefix: scopeConfig.prefix ?? `${scope}/`,
+            componentNameStrategy: scopeConfig.componentNameStrategy ?? userConfig.pages?.componentNameStrategy ?? "relative-no-ext"
+          }
+        ])
+      )
     } : null,
     contracts: {
       glob: userConfig.contracts?.glob ?? "src/**/*.controller.ts",
@@ -226,23 +257,81 @@ var import_promises2 = require("fs/promises");
 var import_node_path2 = require("path");
 var import_fast_glob = __toESM(require("fast-glob"), 1);
 var NON_PAGE_FILE_RE = /\.(?:test|spec|stories|story)\.(?:tsx?|jsx?|vue|svelte)$/i;
+var MAGIC_SEGMENT_RE = /[*?{}[\]()!]/;
+function globStaticBase(glob) {
+  const segments = glob.split("/");
+  const staticSegments = [];
+  for (const segment of segments.slice(0, -1)) {
+    if (MAGIC_SEGMENT_RE.test(segment)) break;
+    staticSegments.push(segment);
+  }
+  return staticSegments.join("/");
+}
 async function discoverPages(opts) {
-  const allFiles = await (0, import_fast_glob.default)(opts.glob, { cwd: opts.cwd, absolute: true });
-  const files = allFiles.filter((f) => !NON_PAGE_FILE_RE.test(f));
-  files.sort();
-  const globStatic = opts.glob.split("*")[0]?.replace(/\/$/, "") ?? "";
-  const pagesBase = (0, import_node_path2.join)(opts.cwd, globStatic);
+  const globs = typeof opts.glob === "string" ? [opts.glob] : opts.glob;
+  const prefix = opts.prefix ?? "";
+  const scope = opts.scope ?? "default";
+  const seenFiles = /* @__PURE__ */ new Set();
   const out = [];
-  for (const file of files) {
-    const rel = (0, import_node_path2.relative)(opts.cwd, file);
-    const nameRel = (0, import_node_path2.relative)(pagesBase, file);
-    const name = computeName(nameRel, opts.componentNameStrategy);
-    const source = await (0, import_promises2.readFile)(file, "utf8");
-    const propsSource = extractPropsSource(source, opts.propsExport);
-    out.push({ name, absolutePath: file, relativePath: rel, propsSource });
+  for (const glob of globs) {
+    const files = (await (0, import_fast_glob.default)(glob, { cwd: opts.cwd, absolute: true })).filter((f) => !NON_PAGE_FILE_RE.test(f) && !seenFiles.has(f)).sort();
+    const pagesBase = (0, import_node_path2.join)(opts.cwd, globStaticBase(glob));
+    for (const file of files) {
+      seenFiles.add(file);
+      const rel = (0, import_node_path2.relative)(opts.cwd, file);
+      const nameRel = (0, import_node_path2.relative)(pagesBase, file).split(import_node_path2.sep).join("/");
+      const name = `${prefix}${computeName(nameRel, opts.componentNameStrategy)}`;
+      const source = await (0, import_promises2.readFile)(file, "utf8");
+      const propsSource = extractPropsSource(source, opts.propsExport);
+      out.push({ name, absolutePath: file, relativePath: rel, propsSource, scope });
+    }
+  }
+  assertUniqueNames(out);
+  return out;
+}
+async function discoverPageScopes(config) {
+  const pages = config.pages;
+  if (!pages) return [];
+  const common = { cwd: config.codegen.cwd, propsExport: pages.propsExport };
+  const out = await discoverPages({
+    ...common,
+    glob: pages.glob,
+    componentNameStrategy: pages.componentNameStrategy
+  });
+  for (const [scope, scopeConfig] of Object.entries(pages.scopes ?? {})) {
+    out.push(
+      ...await discoverPages({
+        ...common,
+        glob: scopeConfig.glob,
+        componentNameStrategy: scopeConfig.componentNameStrategy,
+        prefix: scopeConfig.prefix,
+        scope
+      })
+    );
   }
+  assertUniqueNames(out);
   return out;
 }
+function allPageGlobs(config) {
+  if (!config.pages) return [];
+  const asList = (glob) => typeof glob === "string" ? [glob] : glob;
+  return [
+    ...asList(config.pages.glob),
+    ...Object.values(config.pages.scopes ?? {}).flatMap((scope) => asList(scope.glob))
+  ];
+}
+function assertUniqueNames(pages) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const previous = byName.get(page.name);
+    if (previous) {
+      throw new Error(
+        `Two Inertia pages resolve to the component name "${page.name}": ${previous.relativePath} (scope "${previous.scope}") and ${page.relativePath} (scope "${page.scope}"). Give one of them another name, directory or scope prefix.`
+      );
+    }
+    byName.set(page.name, page);
+  }
+}
 function computeName(rel, strat) {
   if (typeof strat === "function") return strat(rel);
   const noExt = rel.replace(/\.(tsx?|vue|svelte)$/, "");
@@ -4113,28 +4202,28 @@ function renderFetcherRequest(req, binaryResponse) {
 }
 function emitReqHelper() {
   return [
-    "/** Awaitable request handle. `await api.x.y({...})` runs the fetch; extensions add query/mutation helpers. */",
-    "type __Req<R> = {",
-    "  then<T1 = R, T2 = never>(",
+    "/** An awaitable request handle: a lazy, memoized `Promise` that also carries `fetch()` and the members extensions add. */",
+    "export type RequestHandle<R, M = {}> = Promise<R> & { fetch(): Promise<R> } & M;",
+    "class __Request<R> extends Promise<R> {",
+    "  static override get [Symbol.species](): PromiseConstructor {",
+    "    return Promise;",
+    "  }",
+    "  private __run: () => Promise<R>;",
+    "  private __p: Promise<R> | undefined;",
+    "  constructor(run: () => Promise<R>) {",
+    "    super(() => {});",
+    "    this.__run = run;",
+    "  }",
+    "  override then<T1 = R, T2 = never>(",
     "    onfulfilled?: ((value: R) => T1 | PromiseLike<T1>) | null,",
     "    onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null,",
-    "  ): Promise<T1 | T2>;",
-    "  catch<T = never>(onrejected?: ((reason: unknown) => T | PromiseLike<T>) | null): Promise<R | T>;",
-    "  finally(onfinally?: (() => void) | null): Promise<R>;",
-    "  fetch(): Promise<R>;",
-    "};",
-    "function __req<R>(run: () => Promise<R>): __Req<R> {",
-    "  let __p: Promise<R> | undefined;",
-    "  const __promise = () => {",
-    "    __p ??= run();",
-    "    return __p;",
-    "  };",
-    "  return {",
-    "    then: (onfulfilled, onrejected) => __promise().then(onfulfilled, onrejected),",
-    "    catch: (onrejected) => __promise().catch(onrejected),",
-    "    finally: (onfinally) => __promise().finally(onfinally),",
-    "    fetch: run,",
-    "  };",
+    "  ): Promise<T1 | T2> {",
+    "    this.__p ??= this.__run();",
+    "    return this.__p.then(onfulfilled, onrejected);",
+    "  }",
+    "}",
+    "function __req<R, M extends object = {}>(run: () => Promise<R>, members?: M): RequestHandle<R, M> {",
+    "  return Object.assign(new __Request<R>(run), { fetch: run }, members) as RequestHandle<R, M>;",
     "}",
     ""
   ];
@@ -4152,18 +4241,26 @@ function emitFilterFieldGuard() {
   ];
 }
 function renderLeaf(pad, objKey, req, requestExpr, members, streamExpr) {
-  const lines = [`${pad}${objKey}: (input?: ${req.inputType}) => ({`];
-  lines.push(`${pad}  ...__req<${req.responseType}>(() => ${requestExpr}),`);
+  const memberLines = [];
   if (req.filterFieldsExpr) {
-    lines.push(`${pad}  filterFields: ${req.filterFieldsExpr},`);
+    memberLines.push(`${pad}    filterFields: ${req.filterFieldsExpr},`);
   }
   if (streamExpr) {
-    lines.push(`${pad}  stream: () => ${streamExpr},`);
+    memberLines.push(`${pad}    stream: () => ${streamExpr},`);
   }
   for (const [name, value] of Object.entries(members)) {
-    lines.push(`${pad}  ${name}: ${value},`);
-  }
-  lines.push(`${pad}}),`);
+    memberLines.push(`${pad}    ${name}: ${value},`);
+  }
+  const body = [requestExpr, ...memberLines].join("\n");
+  const param = /\binput\b/.test(body) ? `input?: ${req.inputType}` : "";
+  const lines = [`${pad}${objKey}: (${param}) =>`];
+  if (memberLines.length === 0) {
+    lines.push(`${pad}  __req<${req.responseType}>(() => ${requestExpr}),`);
+    return lines;
+  }
+  lines.push(`${pad}  __req(() => ${requestExpr}, {`);
+  lines.push(...memberLines);
+  lines.push(`${pad}  }),`);
   return lines;
 }
 function renderStreamExpr(req) {
@@ -4297,6 +4394,23 @@ var EMPTY_PATH_NAMESPACE = [
 function isClientCallable(route) {
   return route.method.toUpperCase() !== "ALL";
 }
+var ROUTES_IMPORT_PLACEHOLDER = "/* @@routes-import@@ */";
+var ROUTES_EXPORTS = [
+  // Called, never mentioned in prose: match the call so a comment saying "route" doesn't count.
+  { name: "route", typeOnly: false },
+  { name: "ROUTES", typeOnly: false },
+  { name: "RouteName", typeOnly: true },
+  { name: "ExtractParams", typeOnly: true },
+  { name: "RouteParams", typeOnly: true }
+];
+function finishRoutesImport(lines) {
+  const body = lines.filter((l) => l !== ROUTES_IMPORT_PLACEHOLDER).join("\n");
+  const used = ROUTES_EXPORTS.filter(
+    ({ name }) => new RegExp(name === "route" ? "\\broute\\(" : `\\b${name}\\b`).test(body)
+  ).map(({ name, typeOnly }) => typeOnly ? `type ${name}` : name);
+  const importLine = used.length ? `import { ${used.join(", ")} } from './routes.js';` : null;
+  return lines.flatMap((l) => l === ROUTES_IMPORT_PLACEHOLDER ? importLine ? [importLine] : [] : [l]).join("\n");
+}
 function buildApiFile(routes, outDir, opts = {}) {
   const fetcherImportPath = opts.fetcherImportPath;
   const serialization = opts.serialization ?? "json";
@@ -4356,9 +4470,7 @@ function buildApiFile(routes, outDir, opts = {}) {
     for (const imp of ext.apiHeader?.(ctx)?.imports ?? []) pushImport(imp);
   }
   lines.push(...extImports);
-  lines.push(
-    "import { route, ROUTES, type RouteName, type ExtractParams, type RouteParams } from './routes.js';"
-  );
+  lines.push(ROUTES_IMPORT_PLACEHOLDER);
   const runtimeImport = fetcherImportPath ?? "@dudousxd/nestjs-client";
   lines.push(`import type { Fetcher } from '${runtimeImport}';`);
   if (serialization === "json" && contracted.length > 0) {
@@ -4409,7 +4521,7 @@ function buildApiFile(routes, outDir, opts = {}) {
         lines.push(...statements, "");
       }
     }
-    return lines.join("\n");
+    return finishRoutesImport(lines);
   }
   const tree = /* @__PURE__ */ new Map();
   for (const r of contracted) {
@@ -4462,7 +4574,7 @@ function buildApiFile(routes, outDir, opts = {}) {
       lines.push(...statements, "");
     }
   }
-  return lines.join("\n");
+  return finishRoutesImport(lines);
 }
 
 // src/emit/emit-cache.ts
@@ -4475,6 +4587,7 @@ async function emitCache(pages, outDir) {
       const s = await (0, import_promises4.stat)(p.absolutePath);
       return {
         name: p.name,
+        scope: p.scope ?? "default",
         relativePath: p.relativePath,
         mtime: s.mtime.toISOString()
       };
@@ -5266,10 +5379,11 @@ async function emitPages(pages, outDir, _options = {}) {
   }).join("\n");
   const propsHelper = "\nexport type InertiaProps<K extends InertiaPageName> = import('@dudousxd/nestjs-inertia').InertiaPages[K];\n";
   const sharedPropsBlock = buildSharedPropsBlock(_options.sharedProps ?? null);
+  const scopesBlock = buildScopesBlock(pages);
   const content = `// Generated by @dudousxd/nestjs-codegen. Do not edit.
 
 export type InertiaPageName = ${pageNameUnion};
-${propsHelper}
+${propsHelper}${scopesBlock}
 declare module '@dudousxd/nestjs-inertia' {
   interface InertiaPages {
 ${augBody}
@@ -5278,6 +5392,31 @@ ${sharedPropsBlock}}
 `;
   await (0, import_promises9.writeFile)((0, import_node_path13.join)(outDir, "pages.d.ts"), content, "utf8");
 }
+function buildScopesBlock(pages) {
+  const byScope = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const scope = page.scope ?? "default";
+    const names = byScope.get(scope) ?? [];
+    names.push(JSON.stringify(page.name));
+    byScope.set(scope, names);
+  }
+  if (![...byScope.keys()].some((scope) => scope !== "default")) return "";
+  if (!byScope.has("default")) byScope.set("default", []);
+  const scopes = ["default", ...[...byScope.keys()].filter((s) => s !== "default")];
+  const body = scopes.map((scope) => {
+    const key = needsQuotes(scope) ? JSON.stringify(scope) : scope;
+    const names = byScope.get(scope) ?? [];
+    return `  ${key}: ${names.length ? names.join(" | ") : "never"};`;
+  }).join("\n");
+  return `
+/** The page names of each Inertia app: \`default\` (forRoot) and every \`pages.scopes\` entry. */
+export interface InertiaScopePages {
+${body}
+}
+
+export type InertiaScopePageName<S extends keyof InertiaScopePages> = InertiaScopePages[S];
+`;
+}
 function buildSharedPropsBlock(sharedProps) {
   if (!sharedProps) return "";
   if (sharedProps.isImportRef) {
@@ -5485,8 +5624,7 @@ function diffConfigKeyHashes(previous, current) {
   return [...keys].filter((key) => previous[key] !== current[key]).sort();
 }
 async function discoverInputFiles(config) {
-  const globs = [config.contracts.glob, config.forms.watch];
-  if (config.pages) globs.push(config.pages.glob);
+  const globs = [config.contracts.glob, config.forms.watch, ...allPageGlobs(config)];
   const cwd = config.codegen.cwd;
   const matched = await (0, import_fast_glob3.default)(globs, { cwd, absolute: true, onlyFiles: true });
   return [...new Set(matched)].sort();
@@ -5617,12 +5755,7 @@ async function generate(config, inputRoutes = [], entryPoint = "cli") {
   }
   if (config.pages) {
     const pagesConfig = config.pages;
-    const pages = await discoverPages({
-      glob: pagesConfig.glob,
-      cwd: config.codegen.cwd,
-      propsExport: pagesConfig.propsExport,
-      componentNameStrategy: pagesConfig.componentNameStrategy
-    });
+    const pages = await discoverPageScopes(config);
     const sharedProps = discoverSharedPropsFromConfig(config);
     await emitPages(pages, config.codegen.outDir, {
       propsExport: pagesConfig.propsExport,
@@ -5797,12 +5930,17 @@ async function watch(config, onChange, options = {}) {
     await runInitialPass();
   }
   let pagesDebounceTimer;
-  const pagesGlob = config.pages?.glob ?? ".nestjs-codegen-no-pages";
-  const pagesWatcher = import_chokidar.default.watch((0, import_node_path18.join)(config.codegen.cwd, pagesGlob), {
-    ignoreInitial: true,
-    persistent: true,
-    awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
-  });
+  const pageGlobs = allPageGlobs(config);
+  const pagesWatcher = import_chokidar.default.watch(
+    (pageGlobs.length ? pageGlobs : [".nestjs-codegen-no-pages"]).map(
+      (glob) => (0, import_node_path18.join)(config.codegen.cwd, glob)
+    ),
+    {
+      ignoreInitial: true,
+      persistent: true,
+      awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
+    }
+  );
   function schedulePagesRegenerate() {
     if (pagesDebounceTimer !== void 0) {
       clearTimeout(pagesDebounceTimer);
@@ -5882,7 +6020,7 @@ async function watch(config, onChange, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.26.0";
+var VERSION = "0.27.0";
 
 // src/cli/codegen.ts
 async function runCodegen(opts = {}) {