litestar-vite-plugin 0.24.1 → 0.26.0

package/dist/js/shared/bridge-schema.js

@@ -29,6 +29,9 @@ const allowedLogLevels = /* @__PURE__ */ new Set(["quiet", "normal", "verbose"])
 function fail(message) {
   throw new Error(`litestar-vite-plugin: invalid .litestar.json - ${message}`);
 }
+function warn(message) {
+  console.warn(`litestar-vite-plugin: invalid .litestar.json - ${message}`);
+}
 function assertObject(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     fail(`${label} must be an object`);
@@ -122,6 +125,8 @@ function parseTypesConfig(value) {
   const generatePageProps = assertBoolean(obj, "generatePageProps");
   const generateSchemas = assertOptionalBoolean(obj, "generateSchemas", true);
   const globalRoute = assertBoolean(obj, "globalRoute");
+  const rawFailOnError = obj.failOnError;
+  const failOnError = rawFailOnError === void 0 || rawFailOnError === null ? void 0 : assertBoolean(obj, "failOnError");
   return {
     enabled,
     output,
@@ -135,7 +140,8 @@ function parseTypesConfig(value) {
     generateRoutes,
     generatePageProps,
     generateSchemas,
-    globalRoute
+    globalRoute,
+    failOnError
   };
 }
 function parseLogging(value) {
@@ -162,7 +168,7 @@ function parseBridgeSchema(value) {
   const obj = assertObject(value, "root");
   for (const key of Object.keys(obj)) {
     if (!allowedTopLevelKeys.has(key)) {
-      fail(`unknown top-level key "${key}"`);
+      warn(`unknown top-level key "${key}" ignored`);
     }
   }
   const assetUrl = assertString(obj, "assetUrl");
@@ -211,16 +217,42 @@ function parseBridgeSchema(value) {
 function readBridgeConfig(explicitPath) {
   const envPath = explicitPath ?? process.env.LITESTAR_VITE_CONFIG_PATH;
   if (envPath) {
-    if (!fs.existsSync(envPath)) {
-      return null;
-    }
-    return readBridgeConfigFile(envPath);
+    return readBridgeConfigFileCached(envPath);
   }
   const defaultPath = path.join(process.cwd(), ".litestar.json");
-  if (fs.existsSync(defaultPath)) {
-    return readBridgeConfigFile(defaultPath);
+  return readBridgeConfigFileCached(defaultPath);
+}
+const bridgeConfigCache = /* @__PURE__ */ new Map();
+function readBridgeConfigFileCached(filePath) {
+  const resolvedPath = path.resolve(filePath);
+  if (!fs.existsSync(resolvedPath)) {
+    return null;
+  }
+  let mtimeMs = null;
+  try {
+    mtimeMs = fs.statSync(resolvedPath).mtimeMs;
+  } catch {
+    mtimeMs = null;
+  }
+  if (mtimeMs !== null) {
+    const cached = bridgeConfigCache.get(resolvedPath);
+    if (cached?.mtimeMs === mtimeMs) {
+      return cached.config;
+    }
+  }
+  try {
+    const config = readBridgeConfigFile(resolvedPath);
+    if (mtimeMs !== null) {
+      bridgeConfigCache.set(resolvedPath, { mtimeMs, config });
+    }
+    return config;
+  } catch (error) {
+    warn(error instanceof Error ? error.message : String(error));
+    if (mtimeMs !== null) {
+      bridgeConfigCache.set(resolvedPath, { mtimeMs, config: null });
+    }
+    return null;
   }
-  return null;
 }
 function readBridgeConfigFile(filePath) {
   let raw;

package/dist/js/shared/constants.d.ts

@@ -11,23 +11,9 @@
  */
 export declare const DEBOUNCE_MS = 300;
 /**
- * Timeout in milliseconds for backend health checks.
+ * Pinned fallback package spec for @hey-api/openapi-ts.
  *
- * Used when checking if the Litestar backend is available
- * before attempting to fetch OpenAPI schema.
+ * Keep this in sync with CURRENT_NPM_VERSION_RANGES in the Python scaffold
+ * registry and the optional peer dependency range in package.json.
  */
-export declare const BACKEND_CHECK_TIMEOUT_MS = 2000;
-/**
- * Default asset URL path.
- *
- * Used as fallback when no explicit assetUrl is configured.
- * Should match the default in Python ViteConfig.
- */
-export declare const DEFAULT_ASSET_URL = "/static/";
-/**
- * Default output directory for generated TypeScript types.
- *
- * Used by framework integrations as fallback when no output
- * is specified in Python bridge config or plugin options.
- */
-export declare const DEFAULT_TYPES_OUTPUT = "src/generated";
+export declare const HEY_API_PINNED_SPEC = "@hey-api/openapi-ts@0.98.2";

package/dist/js/shared/constants.js

@@ -1,10 +1,6 @@
 const DEBOUNCE_MS = 300;
-const BACKEND_CHECK_TIMEOUT_MS = 2e3;
-const DEFAULT_ASSET_URL = "/static/";
-const DEFAULT_TYPES_OUTPUT = "src/generated";
+const HEY_API_PINNED_SPEC = "@hey-api/openapi-ts@0.98.2";
 export {
-  BACKEND_CHECK_TIMEOUT_MS,
   DEBOUNCE_MS,
-  DEFAULT_ASSET_URL,
-  DEFAULT_TYPES_OUTPUT
+  HEY_API_PINNED_SPEC
 };

package/dist/js/shared/emit-page-props-types.d.ts

@@ -3,4 +3,4 @@
  *
  * @returns true if file was changed, false if unchanged
  */
-export declare function emitPagePropsTypes(pagesPath: string, outputDir: string): Promise<boolean>;
+export declare function emitPagePropsTypes(pagesPath: string, outputDir: string, projectRoot?: string): Promise<boolean>;

package/dist/js/shared/emit-page-props-types.js

@@ -1,10 +1,44 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeIfChanged } from "./write-if-changed.js";
-async function emitPagePropsTypes(pagesPath, outputDir) {
+const semanticAliases = {
+  UUID: { description: "UUID v4 string", base: "string" },
+  DateTime: { description: "RFC 3339 date-time string", base: "string" },
+  DateOnly: { description: "ISO 8601 date string (YYYY-MM-DD)", base: "string" },
+  TimeOnly: { description: "ISO 8601 time string", base: "string" },
+  Duration: { description: "ISO 8601 duration string", base: "string" },
+  Email: { description: "Email address string", base: "string" },
+  URI: { description: "URI/URL string", base: "string" },
+  IPv4: { description: "IPv4 address string", base: "string" },
+  IPv6: { description: "IPv6 address string", base: "string" }
+};
+function collectSemanticAliases(typeExpr) {
+  const aliases = /* @__PURE__ */ new Set();
+  for (const match of typeExpr.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*\b/g)) {
+    const name = match[0];
+    if (name in semanticAliases) {
+      aliases.add(name);
+    }
+  }
+  return [...aliases].toSorted();
+}
+function renderSemanticAliases(aliases) {
+  if (aliases.size === 0) {
+    return "";
+  }
+  const lines = ["/** Semantic string aliases derived from OpenAPI `format`. */"];
+  for (const alias of [...aliases].toSorted()) {
+    const { description, base } = semanticAliases[alias];
+    lines.push(`/** ${description} */`, `export type ${alias} = ${base}`, "");
+  }
+  return `${lines.join("\n").trimEnd()}
+
+`;
+}
+async function emitPagePropsTypes(pagesPath, outputDir, projectRoot = process.cwd()) {
   const contents = await fs.promises.readFile(pagesPath, "utf-8");
   const json = JSON.parse(contents);
-  const outDir = path.resolve(process.cwd(), outputDir);
+  const outDir = path.resolve(projectRoot, outputDir);
   await fs.promises.mkdir(outDir, { recursive: true });
   const outFile = path.join(outDir, "page-props.ts");
   const { includeDefaultAuth, includeDefaultFlash } = json.typeGenConfig;
@@ -84,8 +118,15 @@ export interface FlashMessages {}
     return `  ${safeKey}${optional}: ${def.type}`;
   });
   const allCustomTypes = /* @__PURE__ */ new Set();
+  const usedSemanticAliases = /* @__PURE__ */ new Set();
   for (const data of Object.values(json.pages)) {
-    if (data.tsType) {
+    const typeExpr = data.tsType ?? data.propsType;
+    if (typeExpr) {
+      for (const alias of collectSemanticAliases(typeExpr)) {
+        usedSemanticAliases.add(alias);
+      }
+    }
+    if (data.tsType && /^[A-Za-z_][A-Za-z0-9_]*$/.test(data.tsType)) {
       allCustomTypes.add(data.tsType);
     }
     for (const t of data.customTypes ?? []) {
@@ -131,9 +172,13 @@ export interface FlashMessages {}
     "RegExp",
     "User",
     "AuthData",
-    "FlashMessages"
+    "FlashMessages",
+    ...Object.keys(semanticAliases)
   ]);
   for (const def of Object.values(generatedSharedProps)) {
+    for (const alias of collectSemanticAliases(def.type)) {
+      usedSemanticAliases.add(alias);
+    }
     for (const match of def.type.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*\b/g)) {
       const name = match[0];
       if (!builtinTypes.has(name)) {
@@ -190,6 +235,7 @@ export interface FlashMessages {}
   if (importStatement) {
     importStatement += "\n";
   }
+  const semanticAliasTypes = renderSemanticAliases(usedSemanticAliases);
   const pageEntries = [];
   for (const [component, data] of Object.entries(json.pages)) {
     const rawType = data.tsType || data.propsType || defaultFallback;
@@ -206,7 +252,7 @@ export interface FlashMessages {}
 // Import user-defined type extensions (edit page-props.user.ts to customize)
 import type { UserExtensions, SharedPropsExtensions } from "./page-props.user"
 
-${importStatement}${userTypes}${authTypes}${flashTypes}/**
+${importStatement}${semanticAliasTypes}${userTypes}${authTypes}${flashTypes}/**
  * Generated shared props (always present).
  * Includes built-in props + static config props.
  */

package/dist/js/shared/emit-schemas-types.d.ts

@@ -5,4 +5,4 @@
  * @param outputDir - Output directory (contains api/types.gen.ts)
  * @returns true if file was changed, false if unchanged
  */
-export declare function emitSchemasTypes(routesJsonPath: string, outputDir: string, schemasOutputPath?: string): Promise<boolean>;
+export declare function emitSchemasTypes(routesJsonPath: string, outputDir: string, schemasOutputPath?: string, projectRoot?: string): Promise<boolean>;

package/dist/js/shared/emit-schemas-types.js

@@ -10,21 +10,12 @@ function toImportPath(fromDir, targetFile) {
   return `./${withoutExtension}`;
 }
 function parseHeyApiTypes(content) {
-  const dataTypes = /* @__PURE__ */ new Map();
   const responsesTypes = /* @__PURE__ */ new Set();
   const errorsTypes = /* @__PURE__ */ new Set();
   const urlToDataType = /* @__PURE__ */ new Map();
-  const typeBlockRegex = /export\s+type\s+(\w+Data)\s*=\s*\{([^}]*(?:\{[^}]*\}[^}]*)*)\}/gs;
-  for (const match of content.matchAll(typeBlockRegex)) {
-    const typeName = match[1];
-    const typeBody = match[2];
-    const urlMatch = typeBody.match(/url:\s*['"]([^'"]+)['"]/);
+  for (const { typeName, body } of findExportedDataTypeBlocks(content)) {
+    const urlMatch = body.match(/url:\s*['"]([^'"]+)['"]/);
     const url = urlMatch ? urlMatch[1] : null;
-    const hasBody = /\bbody\s*:/.test(typeBody) && !/\bbody\s*\?\s*:\s*never/.test(typeBody);
-    const hasPath = /\bpath\s*:/.test(typeBody) && !/\bpath\s*\?\s*:\s*never/.test(typeBody);
-    const hasQuery = /\bquery\s*:/.test(typeBody) && !/\bquery\s*\?\s*:\s*never/.test(typeBody);
-    const info = { typeName, url, hasBody, hasPath, hasQuery };
-    dataTypes.set(typeName, info);
     if (url) {
       urlToDataType.set(url, typeName);
     }
@@ -37,7 +28,87 @@ function parseHeyApiTypes(content) {
   for (const match of content.matchAll(errorsRegex)) {
     errorsTypes.add(match[1]);
   }
-  return { dataTypes, responsesTypes, errorsTypes, urlToDataType };
+  return { responsesTypes, errorsTypes, urlToDataType };
+}
+function findExportedDataTypeBlocks(content) {
+  const blocks = [];
+  const declarationRegex = /export\s+type\s+(\w+Data)\s*=\s*/g;
+  for (const match of content.matchAll(declarationRegex)) {
+    const typeName = match[1];
+    const bodyStart = match.index + match[0].length;
+    const openIndex = content.indexOf("{", bodyStart);
+    const nextToken = content.slice(bodyStart, openIndex === -1 ? content.length : openIndex).trim();
+    if (openIndex === -1 || nextToken.length > 0) {
+      console.warn(`litestar-vite: Unable to parse hey-api Data type ${typeName}; expected object type`);
+      continue;
+    }
+    const closeIndex = findMatchingBrace(content, openIndex);
+    if (closeIndex === -1) {
+      console.warn(`litestar-vite: Unable to parse hey-api Data type ${typeName}; unbalanced braces`);
+      continue;
+    }
+    blocks.push({ typeName, body: content.slice(openIndex + 1, closeIndex) });
+  }
+  return blocks;
+}
+function findMatchingBrace(content, openIndex) {
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (let i = openIndex; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+    if (lineComment) {
+      if (char === "\n") {
+        lineComment = false;
+      }
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i += 1;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
 }
 function normalizePath(routePath) {
   return routePath.replace(/\{([^:}]+):[^}]+\}/g, "{$1}");
@@ -312,9 +383,9 @@ export type HasPathParams<T extends OperationName> = PathParams<T> extends never
 export type HasQueryParams<T extends OperationName> = QueryParams<T> extends never ? false : true
 `;
 }
-async function emitSchemasTypes(routesJsonPath, outputDir, schemasOutputPath) {
-  const outDir = path.resolve(process.cwd(), outputDir);
-  const outFile = schemasOutputPath ? path.resolve(process.cwd(), schemasOutputPath) : path.join(outDir, "schemas.ts");
+async function emitSchemasTypes(routesJsonPath, outputDir, schemasOutputPath, projectRoot = process.cwd()) {
+  const outDir = path.resolve(projectRoot, outputDir);
+  const outFile = schemasOutputPath ? path.resolve(projectRoot, schemasOutputPath) : path.join(outDir, "schemas.ts");
   const schemasDir = path.dirname(outFile);
   const apiTypesPath = path.join(outDir, "api", "types.gen.ts");
   const apiTypesImportPath = toImportPath(schemasDir, apiTypesPath);

package/dist/js/shared/emit-static-props-types.d.ts

@@ -8,4 +8,4 @@
  *
  * @returns true if file was changed, false if unchanged
  */
-export declare function emitStaticPropsTypes(outputDir: string): Promise<boolean>;
+export declare function emitStaticPropsTypes(outputDir: string, projectRoot?: string): Promise<boolean>;

package/dist/js/shared/emit-static-props-types.js

@@ -53,10 +53,10 @@ function toInterfaceName(key) {
   const pascal = key.replace(/[^a-zA-Z0-9_$]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").replace(/(^|_)([a-z])/g, (_, __, c) => c.toUpperCase());
   return pascal || "StaticProp";
 }
-async function emitStaticPropsTypes(outputDir) {
+async function emitStaticPropsTypes(outputDir, projectRoot = process.cwd()) {
   const bridgeConfig = readBridgeConfig();
   const staticProps = bridgeConfig?.staticProps ?? {};
-  const outDir = path.resolve(process.cwd(), outputDir);
+  const outDir = path.resolve(projectRoot, outputDir);
   await fs.promises.mkdir(outDir, { recursive: true });
   const outFile = path.join(outDir, "static-props.ts");
   if (Object.keys(staticProps).length === 0) {

package/dist/js/shared/typegen-cache.d.ts

@@ -1,3 +1,9 @@
+interface OpenApiTsCacheOptions {
+    generateSdk: boolean;
+    generateZod: boolean;
+    plugins: string[];
+    outputPaths?: string[];
+}
 /**
  * Check if openapi-ts should run based on input cache.
  *
@@ -6,11 +12,7 @@
  * @param options - Generator options
  * @returns true if generation should run, false if cached
  */
-export declare function shouldRunOpenApiTs(openapiPath: string, configPath: string | null, options: {
-    generateSdk: boolean;
-    generateZod: boolean;
-    plugins: string[];
-}): Promise<boolean>;
+export declare function shouldRunOpenApiTs(openapiPath: string, configPath: string | null, options: OpenApiTsCacheOptions): Promise<boolean>;
 /**
  * Update cache after successful openapi-ts run.
  *
@@ -18,11 +20,7 @@ export declare function shouldRunOpenApiTs(openapiPath: string, configPath: stri
  * @param configPath - Path to config file (or null)
  * @param options - Generator options
  */
-export declare function updateOpenApiTsCache(openapiPath: string, configPath: string | null, options: {
-    generateSdk: boolean;
-    generateZod: boolean;
-    plugins: string[];
-}): Promise<void>;
+export declare function updateOpenApiTsCache(openapiPath: string, configPath: string | null, options: OpenApiTsCacheOptions): Promise<void>;
 /**
  * Compute input hash for page props generation.
  *
@@ -36,10 +34,11 @@ export declare function computePagePropsHash(pagePropsPath: string): Promise<str
  * @param pagePropsPath - Path to inertia-pages.json
  * @returns true if generation should run, false if cached
  */
-export declare function shouldRegeneratePageProps(pagePropsPath: string): Promise<boolean>;
+export declare function shouldRegeneratePageProps(pagePropsPath: string, outputPath?: string): Promise<boolean>;
 /**
  * Update cache after successful page props generation.
  *
  * @param pagePropsPath - Path to inertia-pages.json
  */
 export declare function updatePagePropsCache(pagePropsPath: string): Promise<void>;
+export {};

package/dist/js/shared/typegen-cache.js

@@ -45,11 +45,17 @@ function isOptionalMetadataMatch(a, b) {
   }
   return isMetadataMatch(a, b);
 }
+function areExpectedOutputsPresent(outputPaths) {
+  return !outputPaths?.some((outputPath) => !fs.existsSync(outputPath));
+}
 function hashObject(obj) {
   const sorted = JSON.stringify(obj, Object.keys(obj).toSorted());
   return crypto.createHash("sha256").update(sorted).digest("hex");
 }
 async function shouldRunOpenApiTs(openapiPath, configPath, options) {
+  if (!areExpectedOutputsPresent(options.outputPaths)) {
+    return true;
+  }
   const cache = await loadCache();
   const optionsHash = hashObject(options);
   const cacheKey = "openapi-ts";
@@ -81,7 +87,10 @@ async function updateOpenApiTsCache(openapiPath, configPath, options) {
 async function computePagePropsHash(pagePropsPath) {
   return hashFile(pagePropsPath);
 }
-async function shouldRegeneratePageProps(pagePropsPath) {
+async function shouldRegeneratePageProps(pagePropsPath, outputPath) {
+  if (outputPath && !fs.existsSync(outputPath)) {
+    return true;
+  }
   const cache = await loadCache();
   const currentMetadata = await readFileMetadata(pagePropsPath);
   const cacheKey = "page-props";

package/dist/js/shared/typegen-core.d.ts

@@ -53,12 +53,30 @@ export interface TypeGenLogger {
     warn(message: string): void;
     error(message: string): void;
 }
+export interface TypeGenCacheHooks {
+    shouldRunOpenApiTs(openapiPath: string, configPath: string | null, options: {
+        generateSdk: boolean;
+        generateZod: boolean;
+        plugins: string[];
+        outputPaths?: string[];
+    }): Promise<boolean>;
+    updateOpenApiTsCache(openapiPath: string, configPath: string | null, options: {
+        generateSdk: boolean;
+        generateZod: boolean;
+        plugins: string[];
+        outputPaths?: string[];
+    }): Promise<void>;
+    shouldRegeneratePageProps(pagePropsPath: string, outputPath?: string): Promise<boolean>;
+    updatePagePropsCache(pagePropsPath: string): Promise<void>;
+}
 /**
  * Options for running type generation.
  */
 export interface RunTypeGenOptions {
     /** Logger for output (optional - silent if not provided) */
     logger?: TypeGenLogger;
+    /** Optional cache hooks for Vite dev/build contexts */
+    cache?: TypeGenCacheHooks;
 }
 /**
  * Resolve the default hey-api client plugin for the current project mode.
@@ -79,6 +97,12 @@ export declare function buildHeyApiPlugins(config: {
     generateZod: boolean;
     sdkClientPlugin: string;
 }): string[];
+/**
+ * Resolve the locally installed @hey-api/openapi-ts executable.
+ */
+export declare function resolveHeyApiBin(projectRoot: string): {
+    binPath: string;
+} | null;
 /**
  * Run @hey-api/openapi-ts to generate TypeScript types from OpenAPI spec.
  *