@ubean/routing 0.1.2 → 0.1.4

package/dist/generator/index.d.ts

@@ -0,0 +1,89 @@
+import { ScanResult, ScannedLayout, ScannedPageRoute } from "../types.js";
+//#region src/generator/index.d.ts
+/**
+ * Options for the physical route file generator.
+ *
+ * The generator produces 3 files under `outDir`:
+ *  - `routes.ts`         — flat route records (`RouteRecord[]`) with name/path/component/layout/meta
+ *  - `imports.ts`        — lazy `views` and `layouts` records (for `import.meta.glob`-free consumption)
+ *  - `typed-router.d.ts` — type definitions:
+ *     - `@ubean/routing` 模块增强:`RouteKey`、`RoutePath`、`RouteLayoutKey`、`ReuseRouteKey`、`RoutePathMap`
+ *     - `vue-router/auto-routes` 模块增强:`RouteNamedMap`(name → `RouteRecordInfo<Name, Path, ParamsRaw, Params>`)
+ *     - `vue-router` 模块增强:`TypesConfig.RouteNamedMap` 引用上面的 `RouteNamedMap`
+ *
+ * `RouteNamedMap` 让 `vue-router` 的 `useRoute<Name>(name)` 能根据路由名推断
+ * `route.params` 的类型(动态路由 `:id` / `:id?` 自动类型化),无需用户手动断言。
+ * 这与 elegant-router 的 `typed-router.d.ts` 行为对齐。
+ */
+interface GeneratorOptions {
+  /** Project root directory (absolute). */
+  cwd: string;
+  /** Output directory for `routes.ts` / `imports.ts` (absolute or relative to `cwd`). */
+  outDir: string;
+  /** Path for `typed-router.d.ts` (absolute or relative to `cwd`). Default: `<outDir>/typed-router.d.ts`. */
+  dtsPath?: string;
+  /** Whether to generate `routes.ts`. Default: `true`. */
+  generateRoutes?: boolean;
+  /** Whether to generate `imports.ts`. Default: `true`. */
+  generateImports?: boolean;
+  /** Whether to generate `typed-router.d.ts`. Default: `true`. */
+  generateDts?: boolean;
+  /** Use lazy `() => import(...)` for views. Default: `true`. */
+  routeLazy?: boolean | ((page: ScannedPageRoute) => boolean);
+  /** Use lazy `() => import(...)` for layouts. Default: `true`. */
+  layoutLazy?: boolean | ((layout: ScannedLayout) => boolean);
+  /**
+   * Compute extra `meta` for a route. The returned object is merged
+   * on top of the page's existing `pageMeta.meta` (from `definePage` / frontmatter).
+   * Return `null` to skip. Existing keys are NOT overwritten.
+   */
+  getRouteMeta?: (page: ScannedPageRoute) => Record<string, unknown> | null;
+  /**
+   * Compute the import specifier for a page file. Receives the absolute
+   * `fullPath` of the page; should return a module specifier usable from
+   * `imports.ts`. Defaults to a project-relative path prefixed with `@/`.
+   */
+  getImportPath?: (page: ScannedPageRoute) => string;
+  /** Same as `getImportPath` but for layouts. */
+  getLayoutImportPath?: (layout: ScannedLayout) => string;
+  /**
+   * Header comment prepended to every generated file. Default: a
+   * `// @generated by ubean-routing — do not edit` notice with a timestamp.
+   */
+  headerComment?: string;
+}
+interface GeneratorResult {
+  routesPath?: string;
+  importsPath?: string;
+  dtsPath?: string;
+  routeCount: number;
+  layoutCount: number;
+}
+declare const DEFAULT_HEADER_COMMENT: string;
+declare function generateRouteFiles(scanResult: ScanResult, options: GeneratorOptions): Promise<GeneratorResult>;
+declare class RouteFileGenerator {
+  private readonly opts;
+  constructor(options: GeneratorOptions);
+  generate(scanResult: ScanResult): Promise<GeneratorResult>;
+  renderRoutesFile(scanResult: ScanResult): string;
+  private renderRouteRecord;
+  private computeMeta;
+  renderImportsFile(scanResult: ScanResult): string;
+  private renderLayoutImport;
+  private renderViewImport;
+  renderDtsFile(scanResult: ScanResult): string;
+  /**
+   * 渲染单条路由的 `RouteRecordInfo<Name, Path, ParamsRaw, Params>`。
+   *
+   * 参数类型映射:
+   * - 必需参数(`/users/:id`)    → `{ id: ParamValue<true> }` / `{ id: ParamValue<false> }`
+   * - 可选参数(`/users/:id?`)   → `{ id?: ParamValueZeroOrOne<true> }` / `{ id?: ParamValueZeroOrOne<false> }`
+   * - 无参数(`/about`)          → `Record<never, never>`
+   *
+   * `ParamValue<true>` 表示原始输入类型(必需为 string),`ParamValue<false>` 表示
+   * 解析后类型(已编码/解码,可能为 `string | undefined`)。这是 vue-router 的约定。
+   */
+  private renderRouteRecordInfo;
+}
+//#endregion
+export { DEFAULT_HEADER_COMMENT, GeneratorOptions, GeneratorResult, RouteFileGenerator, generateRouteFiles };

package/dist/generator/index.js

@@ -0,0 +1,300 @@
+//#region src/generator/index.ts
+const DEFAULT_HEADER_COMMENT = "// @generated by @ubean/routing/generator — do not edit manually.\n// This file is regenerated on every dev start / build.";
+async function generateRouteFiles(scanResult, options) {
+	return new RouteFileGenerator(options).generate(scanResult);
+}
+var RouteFileGenerator = class {
+	opts;
+	constructor(options) {
+		const dtsPath = options.dtsPath ?? joinPosix(options.outDir, "typed-router.d.ts");
+		this.opts = {
+			cwd: options.cwd,
+			outDir: options.outDir,
+			dtsPath,
+			generateRoutes: options.generateRoutes ?? true,
+			generateImports: options.generateImports ?? true,
+			generateDts: options.generateDts ?? true,
+			routeLazy: options.routeLazy ?? true,
+			layoutLazy: options.layoutLazy ?? true,
+			headerComment: options.headerComment ?? "// @generated by @ubean/routing/generator — do not edit manually.\n// This file is regenerated on every dev start / build.",
+			getRouteMeta: options.getRouteMeta,
+			getImportPath: options.getImportPath,
+			getLayoutImportPath: options.getLayoutImportPath
+		};
+	}
+	async generate(scanResult) {
+		const { cwd, outDir, dtsPath, generateRoutes, generateImports, generateDts } = this.opts;
+		const routesPath = generateRoutes ? joinPosix(outDir, "routes.ts") : void 0;
+		const importsPath = generateImports ? joinPosix(outDir, "imports.ts") : void 0;
+		const finalDtsPath = generateDts ? dtsPath : void 0;
+		await Promise.all([
+			routesPath ? writeFile(resolvePath(cwd, routesPath), this.renderRoutesFile(scanResult)) : null,
+			importsPath ? writeFile(resolvePath(cwd, importsPath), this.renderImportsFile(scanResult)) : null,
+			finalDtsPath ? writeFile(resolvePath(cwd, finalDtsPath), this.renderDtsFile(scanResult)) : null
+		]);
+		return {
+			routesPath,
+			importsPath,
+			dtsPath: finalDtsPath,
+			routeCount: scanResult.pages.length,
+			layoutCount: scanResult.layouts.length
+		};
+	}
+	renderRoutesFile(scanResult) {
+		return `${this.opts.headerComment}
+
+import type { RouteRecord } from './imports';
+
+export const routes: RouteRecord[] = [
+${scanResult.pages.map((p) => this.renderRouteRecord(p)).join(",\n")}
+];
+`;
+	}
+	renderRouteRecord(page) {
+		const parts = [];
+		parts.push(`  name: ${JSON.stringify(page.name)}`);
+		parts.push(`  path: ${JSON.stringify(page.route)}`);
+		const component = this.opts.getImportPath?.(page) ?? defaultPageImportPath(page, this.opts.cwd);
+		parts.push(`  component: ${JSON.stringify(component)}`);
+		if (page.layout !== void 0) {
+			const layoutVal = page.layout === false ? "false" : JSON.stringify(page.layout);
+			parts.push(`  layout: ${layoutVal}`);
+		}
+		if (page.isReuse) parts.push(`  reuse: true`);
+		const meta = this.computeMeta(page);
+		if (meta && Object.keys(meta).length > 0) parts.push(`  meta: ${JSON.stringify(meta)}`);
+		if (page.pageMeta?.cache === true) parts.push(`  cache: true`);
+		if (page.pageMeta?.requiresAuth === true) parts.push(`  requiresAuth: true`);
+		if (page.pageMeta?.middleware) {
+			const mw = page.pageMeta.middleware;
+			const mwVal = Array.isArray(mw) ? JSON.stringify(mw) : JSON.stringify(mw);
+			parts.push(`  middleware: ${mwVal}`);
+		}
+		return `  {\n${parts.join(",\n")}\n  }`;
+	}
+	computeMeta(page) {
+		const base = page.pageMeta?.meta ?? {};
+		const merged = {
+			...this.opts.getRouteMeta?.(page) ?? {},
+			...base
+		};
+		return Object.keys(merged).length > 0 ? merged : null;
+	}
+	renderImportsFile(scanResult) {
+		const header = this.opts.headerComment;
+		const layouts = scanResult.layouts.map((l) => this.renderLayoutImport(l)).join(",\n");
+		const views = scanResult.pages.filter((p) => !p.isReuse).map((p) => this.renderViewImport(p)).join(",\n");
+		return `${header}
+
+export type LayoutKey = ${scanResult.layouts.length > 0 ? `'${scanResult.layouts.map((l) => l.name).join("' | '")}'` : "string"};
+export type RouteKey = ${scanResult.pages.length > 0 ? `'${scanResult.pages.map((p) => p.name).join("' | '")}'` : "string"};
+
+export type Lazy<T> = () => Promise<T>;
+export type RawRouteComponent = import('vue').Component | Lazy<import('vue').Component>;
+
+export interface RouteRecord {
+  name: RouteKey;
+  path: string;
+  component: string;
+  layout?: LayoutKey | false;
+  reuse?: boolean;
+  meta?: Record<string, unknown>;
+  cache?: boolean;
+  requiresAuth?: boolean;
+  middleware?: string | string[];
+}
+
+export const layouts: Record<LayoutKey, RawRouteComponent> = {
+${layouts}
+};
+
+export const views: Record<RouteKey, RawRouteComponent> = {
+${views}
+};
+`;
+	}
+	renderLayoutImport(layout) {
+		const importPath = this.opts.getLayoutImportPath?.(layout) ?? defaultLayoutImportPath(layout, this.opts.cwd);
+		if (typeof this.opts.layoutLazy === "function" ? this.opts.layoutLazy(layout) : this.opts.layoutLazy) return `  ${layout.name}: () => import(${JSON.stringify(importPath)})`;
+		const importName = `__layout_${layout.name}`;
+		return `  ${layout.name}: ${importName}, // import ${importName} from ${JSON.stringify(importPath)}`;
+	}
+	renderViewImport(page) {
+		const importPath = this.opts.getImportPath?.(page) ?? defaultPageImportPath(page, this.opts.cwd);
+		if (typeof this.opts.routeLazy === "function" ? this.opts.routeLazy(page) : this.opts.routeLazy) return `  ${page.name}: () => import(${JSON.stringify(importPath)})`;
+		return `  ${page.name}: ${page.name}, // import ${page.name} from ${JSON.stringify(importPath)}`;
+	}
+	renderDtsFile(scanResult) {
+		const header = this.opts.headerComment;
+		const pathMapEntries = scanResult.pages.length > 0 ? scanResult.pages.map((p) => `    "${p.name}": "${p.route}";`).join("\n") : "    // (no pages scanned)";
+		const reuseRoutes = scanResult.pages.filter((p) => p.isReuse);
+		const reuseKeys = reuseRoutes.length > 0 ? reuseRoutes.map((p) => `"${p.name}"`).join(" | ") : "never";
+		return `${header}
+
+declare module '@ubean/routing' {
+  /**
+   * Route layout keys scanned from \`src/layouts/\`.
+   */
+  export type RouteLayoutKey = ${scanResult.layouts.length > 0 ? scanResult.layouts.map((l) => `"${l.name}"`).join(" | ") : "never"};
+
+  /**
+   * Map of route name → route path, scanned from \`src/pages/\`.
+   */
+  export interface RoutePathMap {
+${pathMapEntries}
+  }
+
+  /**
+   * Route names (keys of {@link RoutePathMap}).
+   */
+  export type RouteKey = keyof RoutePathMap;
+
+  /**
+   * Route paths (values of {@link RoutePathMap}).
+   */
+  export type RoutePath = RoutePathMap[RouteKey];
+
+  /**
+   * Reuse route keys (pages using \`.reuse.vue\` suffix).
+   */
+  export type ReuseRouteKey = ${reuseKeys};
+}
+
+declare module 'vue-router/auto-routes' {
+  import type { RouteRecordInfo, ParamValue, ParamValueZeroOrOne } from 'vue-router';
+
+  /**
+   * Route named map — enables typed \`useRoute<Name>(name)\` via vue-router's
+   * \`TypesConfig\` augmentation below.
+   *
+   * Each entry describes a route's name, path, and the types of its path
+   * params (raw input vs. resolved value). For routes without params,
+   * \`Record<never, never>\` is used.
+   *
+   * @see https://router.vuejs.org/api/interfaces/RouteRecordInfo.html
+   */
+  export interface RouteNamedMap {
+${scanResult.pages.length > 0 ? scanResult.pages.map((p) => `    "${p.name}": ${this.renderRouteRecordInfo(p)};`).join("\n") : "    // (no pages scanned)"}
+  }
+}
+
+declare module 'vue-router' {
+  export interface TypesConfig {
+    RouteNamedMap: import('vue-router/auto-routes').RouteNamedMap;
+  }
+}
+
+export type { RouteLayoutKey, RoutePathMap, RouteKey, RoutePath, ReuseRouteKey } from '@ubean/routing';
+`;
+	}
+	/**
+	* 渲染单条路由的 `RouteRecordInfo<Name, Path, ParamsRaw, Params>`。
+	*
+	* 参数类型映射:
+	* - 必需参数(`/users/:id`)    → `{ id: ParamValue<true> }` / `{ id: ParamValue<false> }`
+	* - 可选参数(`/users/:id?`)   → `{ id?: ParamValueZeroOrOne<true> }` / `{ id?: ParamValueZeroOrOne<false> }`
+	* - 无参数(`/about`)          → `Record<never, never>`
+	*
+	* `ParamValue<true>` 表示原始输入类型(必需为 string),`ParamValue<false>` 表示
+	* 解析后类型(已编码/解码,可能为 `string | undefined`)。这是 vue-router 的约定。
+	*/
+	renderRouteRecordInfo(page) {
+		const params = extractRouteParams(page.route);
+		const paramsRaw = renderParamsType(params, true);
+		const paramsResolved = renderParamsType(params, false);
+		return `RouteRecordInfo<${JSON.stringify(page.name)}, ${JSON.stringify(page.route)}, ${paramsRaw}, ${paramsResolved}>`;
+	}
+};
+function defaultPageImportPath(page, cwd) {
+	return `@/${relativePosix(cwd, page.fullPath).replace(/\.(vue|tsx?|jsx?|mdx?)$/, "")}`;
+}
+function defaultLayoutImportPath(layout, cwd) {
+	return `@/${relativePosix(cwd, layout.fullPath).replace(/\.(vue|tsx?|jsx?)$/, "")}`;
+}
+/**
+* 从 vue-router 风格路径中提取参数信息。
+*
+* 支持的语法:
+* - `:name`     — 必需参数(如 `/users/:id`)
+* - `:name?`    — 可选参数(如 `/users/:id?`)
+* - `:name*`    — 重复参数(零或多个,如 `/files/:path*`)— 当前当作可选处理
+* - `:name+`    — 重复参数(一个或多个,如 `/files/:path+`)— 当前当作必需处理
+* - `:name(...)` — 带自定义正则的参数(如 `:id(\\d+)`)— 提取 `name`,忽略正则
+*
+* 不识别 `:pathMatch(.*)*`(catch-all),由 vue-router 内部处理,在
+* `RouteRecordInfo` 中视为无参数(`Record<never, never>`)。
+*
+* @returns 参数数组,顺序与 path 中出现顺序一致
+*/
+function extractRouteParams(path) {
+	const params = [];
+	const paramRegex = /:([A-Za-z_][A-Za-z0-9_]*)(?:\([^)]*\))?([?*+]?)/g;
+	let match;
+	while ((match = paramRegex.exec(path)) !== null) {
+		const name = match[1];
+		const modifier = match[2];
+		const optional = modifier === "?" || modifier === "*";
+		if (!params.some((p) => p.name === name)) params.push({
+			name,
+			optional
+		});
+	}
+	return params;
+}
+/**
+* 渲染参数类型字面量,用于 `RouteRecordInfo` 的 `ParamsRaw` / `Params` 类型参数位置。
+*
+* @param params   `extractRouteParams` 返回的参数数组
+* @param isRaw    `true` 渲染原始输入类型(`ParamValue<true>` / `ParamValueZeroOrOne<true>`),
+*                 `false` 渲染解析后类型(`ParamValue<false>` / `ParamValueZeroOrOne<false>`)
+* @returns 类型字面量字符串,如 `{ id: ParamValue<true> }` 或 `Record<never, never>`
+*/
+function renderParamsType(params, isRaw) {
+	if (params.length === 0) return "Record<never, never>";
+	return `{\n${params.map((p) => {
+		const optionalMarker = p.optional ? "?" : "";
+		const type = p.optional ? `ParamValueZeroOrOne<${isRaw ? "true" : "false"}>` : `ParamValue<${isRaw ? "true" : "false"}>`;
+		return `    ${p.name}${optionalMarker}: ${type}`;
+	}).join(",\n")}\n  }`;
+}
+function joinPosix(...parts) {
+	return parts.map((p) => p.replace(/\\/g, "/")).join("/").replace(/\/+/g, "/");
+}
+/**
+* 将 `cwd` 与 `target` 合并为最终写入路径。
+*
+* 与 `joinPosix` 不同,此函数会识别 `target` 是否为绝对路径:
+* - 如果 `target` 以 `/` 开头(POSIX 绝对路径)或盘符开头(Windows,如 `C:`),
+*   直接使用 `target`,忽略 `cwd`
+* - 否则,使用 `joinPosix(cwd, target)` 拼接
+*
+* 这是为了支持消费方(`@ubean/build`)传入 `path.resolve()` 计算出的绝对路径,
+* 避免出现 `<cwd>/<absolute-target>` 这种重复前缀的错误路径(参见
+* `maybeGenerateRouteFiles` 中 `resolve(config.rootDir, ...)` 的调用)。
+*/
+function resolvePath(cwd, target) {
+	const normalized = target.replace(/\\/g, "/");
+	if (normalized.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(normalized)) return normalized;
+	return joinPosix(cwd, normalized);
+}
+function relativePosix(from, to) {
+	const fromParts = resolvePosix(from).split("/").filter(Boolean);
+	const toParts = resolvePosix(to).split("/").filter(Boolean);
+	let i = 0;
+	while (i < fromParts.length && i < toParts.length && fromParts[i] === toParts[i]) i++;
+	const up = fromParts.slice(i).map(() => "..");
+	const down = toParts.slice(i);
+	return [...up, ...down].join("/") || ".";
+}
+function resolvePosix(p) {
+	if (p.startsWith("/")) return p.replace(/\\/g, "/");
+	return p.replace(/\\/g, "/");
+}
+async function writeFile(path, content) {
+	const { mkdir, writeFile: fsWriteFile } = await import("node:fs/promises");
+	const { dirname } = await import("node:path");
+	await mkdir(dirname(path), { recursive: true });
+	await fsWriteFile(path, content, "utf-8");
+}
+//#endregion
+export { DEFAULT_HEADER_COMMENT, RouteFileGenerator, generateRouteFiles };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { AppEntry, DefineMetaResult, HttpMethod, PageMeta, RouteMeta, ScanOptions, ScanResult, ScannedApiRoute, ScannedAppEntry, ScannedCronTask, ScannedFile, ScannedLayout, ScannedLocale, ScannedMiddleware, ScannedPageRoute, ScannedPlugin, ScannedQueue, ScannedServerEntry } from "./types.js";
+import { filePathToRoute, stripRouteGroups } from "@ubean/utils";
+//#region src/scan.d.ts
+declare function scanProject(options: ScanOptions): Promise<ScanResult>;
+//#endregion
+//#region src/detect-exports.d.ts
+interface DetectExportsResult {
+  exports: string[];
+  httpMethods: Lowercase<HttpMethod>[];
+  hasMeta: boolean;
+  fileMeta?: RouteMeta;
+}
+declare function detectHttpExports(filePath: string): Promise<DetectExportsResult>;
+declare function detectHttpExportsFromCode(code: string): DetectExportsResult;
+//#endregion
+//#region src/route-name.d.ts
+declare function generateRouteName(routePath: string): string;
+declare function generateLayoutName(layoutPath: string): string;
+declare function generateApiRouteId(method: string, routePath: string): string;
+//#endregion
+//#region src/define-page.d.ts
+declare function extractDefinePageFromCode(code: string): PageMeta | null;
+declare function extractDefineMetaFromCode(code: string): DefineMetaResult | null;
+declare function extractDefinePage(filePath: string): Promise<PageMeta | null>;
+declare function extractDefineMeta(filePath: string): Promise<DefineMetaResult | null>;
+//#endregion
+//#region src/router.d.ts
+interface CompiledRoute {
+  method: string;
+  path: string;
+  id: string;
+  filePath: string;
+  meta?: Record<string, unknown>;
+}
+interface CompiledMiddleware {
+  path: string;
+  filePath: string;
+  order: number;
+  global: boolean;
+}
+interface CompiledPage {
+  name: string;
+  path: string;
+  filePath: string;
+  layout?: string | false;
+  reuseTarget?: string;
+}
+interface CompiledLayout {
+  name: string;
+  filePath: string;
+  isDefault: boolean;
+}
+declare class UbeanRouter {
+  private apiContext;
+  private middlewares;
+  private pages;
+  private layouts;
+  constructor();
+  addApiRoute(route: ScannedApiRoute): void;
+  addMiddleware(mw: ScannedMiddleware): void;
+  addPage(page: ScannedPageRoute): void;
+  addLayout(layout: ScannedLayout): void;
+  matchApi(method: string, path: string): CompiledRoute | undefined;
+  getMiddlewares(): CompiledMiddleware[];
+  getPages(): CompiledPage[];
+  getPage(name: string): CompiledPage | undefined;
+  getLayout(name: string): CompiledLayout | undefined;
+  getDefaultLayout(): CompiledLayout | undefined;
+  getLayouts(): CompiledLayout[];
+  getPageRouteNames(): string[];
+}
+declare function useRouter(): UbeanRouter;
+declare function createUbeanRouter(): UbeanRouter;
+//#endregion
+export { type AppEntry, type CompiledLayout, type CompiledMiddleware, type CompiledPage, type CompiledRoute, type DefineMetaResult, type HttpMethod, type PageMeta, type ScanOptions, type ScanResult, type ScannedApiRoute, type ScannedAppEntry, type ScannedCronTask, type ScannedFile, type ScannedLayout, type ScannedLocale, type ScannedMiddleware, type ScannedPageRoute, type ScannedPlugin, type ScannedQueue, type ScannedServerEntry, UbeanRouter, createUbeanRouter, detectHttpExports, detectHttpExportsFromCode, extractDefineMeta, extractDefineMetaFromCode, extractDefinePage, extractDefinePageFromCode, filePathToRoute, generateApiRouteId, generateLayoutName, generateRouteName, scanProject, stripRouteGroups, useRouter };