@uni-helper/vite-plugin-uni-pages 0.4.9 → 0.5.0

package/dist/index.d.cts

@@ -1,569 +0,0 @@
-import { Logger, Plugin, ViteDevServer } from "vite";
-import { LoadConfigSource } from "unconfig";
-import { DefinePage, ExcludeIndexSignature, MaybeCallable, MaybePromise, MaybePromiseCallable, PageMetaDatum, SubPageMetaDatum, UserPageMeta, UserPagesConfig, UserTabBarItem, definePage } from "@uni-helper/uni-pages-types";
-import { FSWatcher } from "chokidar";
-import { SFCDescriptor, SFCParseOptions } from "@vue/compiler-sfc";
-import * as t from "@babel/types";
-import babelGenerator from "@babel/generator";
-import Debug from "debug";
-import fs from "node:fs";
-export * from "@uni-helper/uni-pages-types";
-
-//#region \0rolldown/runtime.js
-declare namespace index_d_exports$1 {
-  export { defineUniPages };
-}
-import * as import__uni_helper_uni_pages_types from "@uni-helper/uni-pages-types";
-/**
- * Define uni-pages configuration
- * Used in pages.config.ts configuration file to provide type hints and validation
- *
- * @param config - Page configuration object
- * @returns Configuration object
- */
-declare function defineUniPages(config: UserPagesConfig): UserPagesConfig;
-//#endregion
-//#region src/page.d.ts
-/**
- * Page class representing a Vue page file
- *
- * Responsibilities:
- * 1. Read page file content
- * 2. Parse page metadata defined by definePage macro
- * 3. Provide tabBar configuration information
- * 4. Track page file change status
- */
-declare class Page {
-  /** Page context instance */
-  ctx: PageContext;
-  /** Page path information containing relative and absolute paths */
-  path: PagePath;
-  /** Page URI used for pages.json path field */
-  uri: string;
-  /** Whether the page has changed, used for incremental update judgment */
-  changed: boolean;
-  /** Raw JSON string of page metadata for change detection */
-  private raw;
-  /** Parsed page metadata */
-  private meta;
-  /**
-   * Create a page instance
-   * @param ctx - Page context instance
-   * @param path - Page path information
-   */
-  constructor(ctx: PageContext, path: PagePath);
-  /**
-   * Get page metadata
-   * Parse configuration defined by definePage macro and return metadata for pages.json
-   *
-   * @param forceUpdate - Whether to force update, ignoring cache
-   * @returns Page metadata object
-   */
-  getPageMeta(forceUpdate?: boolean): Promise<PageMetaDatum>;
-  /**
-   * Get page tabBar configuration
-   * Extract tabBar related configuration from definePage macro
-   *
-   * @param forceUpdate - Whether to force update, ignoring cache
-   * @returns tabBar configuration object, or undefined if page doesn't define tabBar
-   */
-  getTabBar(forceUpdate?: boolean): Promise<index_d_exports$1.TabBarItem & {
-    index: number;
-  } | undefined>;
-  /**
-   * Check if the page has changed
-   * @returns Whether the page has changed
-   */
-  hasChanged(): boolean;
-  /**
-   * Read page file and parse metadata
-   * Extract configuration defined by definePage macro from Vue SFC
-   */
-  read(): Promise<void>;
-  private readPageMetaFromFile;
-}
-/**
- * Parse Vue Single File Component (SFC)
- * Compatible with different versions of @vue/compiler-sfc
- *
- * @param code - Vue SFC source code
- * @param options - Parse options
- * @returns SFC descriptor object
- */
-declare function parseSFC(code: string, options?: SFCParseOptions): SFCDescriptor;
-/**
- * Try to extract page metadata defined by definePage macro from SFC
- * Support using definePage in script setup or regular script
- *
- * @param sfc - Vue SFC descriptor
- * @returns Page metadata object, or undefined if definePage is not found
- */
-declare function tryPageMetaFromMacro(sfc: SFCDescriptor): Promise<UserPageMeta | undefined>;
-/**
- * Find definePage macro call in AST
- * Support function expressions, arrow functions and object expressions as arguments
- *
- * @param stmts - AST statement array
- * @param filename - Filename for error reporting
- * @returns definePage call expression, or undefined if not found
- */
-declare function findMacro(stmts: t.Statement[], filename: string): t.CallExpression | undefined;
-/**
- * Extract all import declarations from AST
- * Used to provide necessary imports when executing definePage arguments
- *
- * @param stmts - AST statement array
- * @returns Import declaration array
- */
-declare function findImports(stmts: t.Statement[]): t.ImportDeclaration[];
-//#endregion
-//#region src/context.d.ts
-/**
- * Page context class responsible for page scanning, config loading, page metadata merging and pages.json generation
- *
- * Core responsibilities:
- * 1. Scan page directories and collect page files
- * 2. Load user configuration files (pages.config.ts, etc.)
- * 3. Parse page metadata (definePage macro)
- * 4. Merge page configurations and generate pages.json
- * 5. Provide virtual module and HMR support
- */
-declare class PageContext {
-  private _server;
-  /** Parsed configuration object from user config file (pages.config.ts) */
-  pagesGlobConfig: index_d_exports$1.PagesConfig | undefined;
-  /** Source path list of user configuration files */
-  pagesConfigSourcePaths: string[];
-  /** Main package page map, key is the absolute path of the page file */
-  pages: Map<string, Page>;
-  /** Sub-package page map, key is the sub-package root directory, value is the page map under that sub-package */
-  subPages: Map<string, Map<string, Page>>;
-  /** Main package page metadata array for generating pages.json pages field */
-  pageMetaData: PageMetaDatum[];
-  /** Sub-package page metadata array for generating pages.json subPackages field */
-  subPageMetaData: SubPageMetaDatum[];
-  /** Generated pages.json file path */
-  resolvedPagesJSONPath: string;
-  private resolvedPagesJSONIndent?;
-  private resolvedPagesJSONNewline?;
-  private resolvedPagesJSONEofNewline?;
-  /** Original options passed by the user */
-  rawOptions: UserOptions;
-  /** Project root directory */
-  root: string;
-  /** Resolved configuration options */
-  options: ResolvedOptions;
-  logger?: Logger;
-  /** Whether to work with vite-plugin-uni-platform plugin */
-  withUniPlatform: boolean;
-  /** Cached previous pages.json content to avoid redundant writes */
-  private lastPagesJson;
-  /**
-   * Create a PageContext instance
-   * @param userOptions - User configuration options
-   * @param viteRoot - Vite project root directory, defaults to current working directory
-   */
-  constructor(userOptions: UserOptions, viteRoot?: string);
-  /**
-   * Set the Vite logger
-   * @param logger - Vite logger instance
-   */
-  setLogger(logger: Logger): void;
-  /**
-   * Load user page configuration file (e.g. pages.config.ts)
-   * Uses unconfig to load configuration, supporting multiple config file formats
-   */
-  loadUserPagesConfig(): Promise<void>;
-  /**
-   * Scan main package page directories and collect all page file paths
-   * Scan corresponding directories based on the configured dirs option
-   */
-  scanPages(): Promise<void>;
-  /**
-   * Scan sub-package page directories and collect all sub-package page file paths
-   * Scan corresponding directories based on the configured subPackages option
-   */
-  scanSubPages(): Promise<void>;
-  /**
-   * Set up Vite dev server for HMR and file watching
-   * @param server - Vite dev server instance
-   */
-  setupViteServer(server: ViteDevServer): void;
-  /**
-   * Set up file watcher to monitor page file and config file changes
-   * Automatically update pages.json when page files or config files change
-   * @param watcher - chokidar file watcher instance
-   */
-  setupWatcher(watcher: FSWatcher): Promise<void>;
-  /**
-   * Page update callback, triggered when page files or configuration changes
-   * Responsible for invalidating virtual modules and notifying the browser to do a full reload
-   */
-  onUpdate(): void;
-  /**
-   * parse pages rules && set page type
-   * @param pages page path array
-   * @param type  page type
-   * @param overrides custom page config
-   * @returns pages rules
-   */
-  parsePages(pages: Map<string, Page>, type: 'main' | 'sub', overrides?: PageMetaDatum[]): Promise<PageMetaDatum[]>;
-  /**
-   * set home page
-   * @param result pages rules array
-   * @returns pages rules
-   */
-  setHomePage(result: PageMetaDatum[]): PageMetaDatum[];
-  /**
-   * Merge main package page metadata
-   * Filter out pages belonging to sub-packages, then parse page metadata and merge user configuration
-   */
-  mergePageMetaData(): Promise<void>;
-  /**
-   * Merge sub-package page metadata
-   * Parse page metadata for each sub-package and handle sub-package configuration inheritance
-   * Preserves sub-package level properties like plugins from user config
-   */
-  mergeSubPageMetaData(): Promise<void>;
-  /**
-   * Update pages.json file
-   * This is the core method responsible for coordinating the entire page configuration generation flow:
-   * 1. Check file changes (if filepath is specified)
-   * 2. Load user configuration
-   * 3. Scan page files
-   * 4. Merge page metadata
-   * 5. Generate and write pages.json
-   * @param filepath - Changed file path for incremental update judgment
-   * @returns Whether pages.json was successfully updated
-   */
-  updatePagesJSON(filepath?: string): Promise<boolean>;
-  /**
-   * Generate virtual module content
-   * Returns JavaScript code containing pages and subPackages exports
-   * @returns Virtual module code string
-   */
-  virtualModule(): string;
-  /**
-   * Resolve main package route data to JSON string
-   * @returns JSON string of main package page metadata
-   */
-  resolveRoutes(): string;
-  /**
-   * Resolve sub-package route data to JSON string
-   * @returns JSON string of sub-package page metadata
-   */
-  resolveSubRoutes(): string;
-  /**
-   * Resolve tabBar configuration
-   * Merges page-defined tabBar items with config-defined tabBar
-   * @returns Merged tabBar configuration object, or undefined if no tabBar exists
-   */
-  resolveTabBar(): Promise<index_d_exports$1.TabBar | undefined>;
-  /**
-   * Generate TypeScript declaration file
-   * Generate type definitions for page paths to provide type hints during navigation
-   */
-  generateDeclaration(): Promise<void> | undefined;
-  private genratePagesJSON;
-  private readInfoFromPagesJSON;
-  private getIndent;
-  private getNewline;
-  private getEndOfLine;
-}
-//#endregion
-//#region src/utils.d.ts
-/**
- * Invalidate virtual module to trigger HMR update
- * When page configuration changes, the virtual module needs to be invalidated to regenerate content
- *
- * @param server - Vite dev server instance
- */
-declare function invalidatePagesModule(server: ViteDevServer): void;
-/**
- * Debug logging utility
- * Uses debug package for leveled log output
- * Enable via environment variable DEBUG=vite-plugin-uni-pages:*
- */
-declare const debug: {
-  /** HMR related logs */hmr: Debug.Debugger; /** Configuration options related logs */
-  options: Debug.Debugger; /** Main package page scanning logs */
-  pages: Debug.Debugger; /** Sub-package page scanning logs */
-  subPages: Debug.Debugger; /** Error logs */
-  error: Debug.Debugger; /** Cache related logs */
-  cache: Debug.Debugger; /** Declaration file generation logs */
-  declaration: Debug.Debugger; /** definePage macro parsing logs */
-  definePage: Debug.Debugger;
-};
-/**
- * Convert file extensions array to glob pattern
- * @param extensions - File extensions array
- * @returns Glob pattern string
- */
-declare function extsToGlob(extensions: string[]): string;
-/**
- * Check if file is a target page file
- * Determine if the file extension is in the supported page file types list
- *
- * @param path - File path
- * @returns Whether it's a target file
- */
-declare function isTargetFile(path: string): boolean;
-/**
- * merge page meta data array by path and assign style
- * @param pageMetaData  page meta data array
- * TODO: support merge middleware
- */
-declare function mergePageMetaDataArray(pageMetaData: PageMetaDatum[]): PageMetaDatum[];
-/**
- * Convert TypeScript / JavaScript script code to object/function
- *
- * @param options - Configuration required for script execution
- * @param options.imports - List of module import statements to include
- * @param options.code - TypeScript code content to execute
- * @param options.filename - Script filename for error location and context
- * @returns Script execution result, if export is a function then execute and return its return value
- */
-declare function parseCode(options: {
-  imports: string[];
-  code: string;
-  filename: string;
-}): Promise<any>;
-/**
- * Async sleep function
- * @param ms - Sleep duration in milliseconds
- * @returns Promise object
- */
-declare function sleep(ms: number): Promise<unknown>;
-/** Babel code generator for converting AST back to code */
-declare const babelGenerate: typeof babelGenerator;
-//#endregion
-//#region src/types.d.ts
-/** Debug log type, corresponding to methods in the debug object */
-type debugType = keyof typeof debug;
-/** Configuration source type, supports string path or unconfig LoadConfigSource object */
-type ConfigSource = string | LoadConfigSource<index_d_exports$1.PagesConfig> | LoadConfigSource<index_d_exports$1.PagesConfig>[];
-/**
- * Plugin configuration options interface
- * Defines all configuration options that users can pass in
- */
-interface Options {
-  /**
-   * Generate TypeScript declaration for pages path
-   *
-   * Accept boolean or a path related to project root
-   *
-   * @default true
-   */
-  dts?: boolean | string;
-  /**
-   * Load from configs files
-   *
-   * @default 'pages.config.(ts|mts|cts|js|cjs|mjs|json)',
-   */
-  configSource: ConfigSource;
-  /**
-   * The default application entry page is the home page
-   * @default 'pages/index' or 'pages/index/index'
-   */
-  homePage: string;
-  /**
-   * Whether to merge pages in pages.json
-   * @default true
-   */
-  mergePages: boolean;
-  /**
-   * Paths to the directory to search for page components.
-   * @default 'src/pages'
-   */
-  dir: string;
-  /**
-   * Sub-package page directories for uni-app sub-package loading
-   *
-   * Supports string format (directory path) or object format (custom root in pages.json)
-   *
-   * In monorepo projects, pages may be located outside the project root.
-   * Use object format to specify a custom root that appears in pages.json,
-   * avoiding '..' in the generated root path.
-   *
-   * @see https://github.com/uni-helper/vite-plugin-uni-pages/issues/271
-   * @default []
-   */
-  subPackages: (string | SubPackageConfig)[];
-  /**
-   * pages.json dir
-   * @default "src"
-   */
-  outDir: string;
-  /**
-   * pages to be excluded, based on [tinyglobby ignore option](https://superchupu.dev/tinyglobby/documentation#ignore)
-   * @default []
-   */
-  exclude: string[];
-  /**
-   * minify the `pages.json`
-   * @default false
-   */
-  minify: boolean;
-  /**
-   * enable debug log
-   */
-  debug: boolean | debugType;
-  onBeforeLoadUserConfig: (ctx: PageContext) => void;
-  onAfterLoadUserConfig: (ctx: PageContext) => void;
-  onBeforeScanPages: (ctx: PageContext) => void;
-  onAfterScanPages: (ctx: PageContext) => void;
-  onBeforeMergePageMetaData: (ctx: PageContext) => void;
-  onAfterMergePageMetaData: (ctx: PageContext) => void;
-  onBeforeWriteFile: (ctx: PageContext) => void;
-  onAfterWriteFile: (ctx: PageContext) => void;
-}
-/** User configuration options type, all options are optional */
-type UserOptions = Partial<Options>;
-/**
- * Resolved configuration options interface
- * Configuration processed by resolveOptions, all paths resolved to absolute paths
- */
-interface ResolvedOptions extends Omit<Options, 'dir' | 'homePage' | 'configSource' | 'dts' | 'subPackages'> {
-  /**
-   * Resolves to the `root` value from Vite config.
-   * @default config.root
-   */
-  root: string;
-  dts: string | false;
-  /**
-   * Resolved page dirs
-   */
-  dirs: string[];
-  /**
-   * Resolved entry page
-   */
-  homePage: string[];
-  configSource: LoadConfigSource<index_d_exports$1.PagesConfig>[];
-  /**
-   * Resolved sub-package directories
-   */
-  subPackages: string[];
-  /**
-   * Custom root mapping for sub-packages (dir -> root)
-   * Used for monorepo support to specify custom root paths in pages.json
-   */
-  subPackageRootMap: Map<string, string>;
-}
-/**
- * Sub-package configuration interface
- * Allows customizing the root path in pages.json for monorepo support
- *
- * In monorepo projects, pages may be located outside the project root (e.g., ../../packages/login/src/pages).
- * By default, the plugin generates root paths with '..', which uni-app does not support.
- * Use this config to specify a custom root that appears in pages.json instead.
- *
- * @example
- * ```ts
- * subPackages: [
- *   {
- *     dir: '../../packages/login/src/pages',  // Physical directory to scan
- *     root: 'packages/login/src/pages',       // Custom root in pages.json
- *   }
- * ]
- * ```
- */
-interface SubPackageConfig {
-  /** Physical directory path to scan for page files */
-  dir: string;
-  /** Custom root path that appears in pages.json subPackages.root */
-  root: string;
-}
-/**
- * Page path information interface
- * Contains relative and absolute paths of page files
- */
-interface PagePath {
-  /** Path relative to the output directory */
-  relativePath: string;
-  /** Absolute path of the page file */
-  absolutePath: string;
-}
-//#endregion
-//#region src/constant.d.ts
-/** Virtual module identifier for Vite module resolution */
-declare const MODULE_ID_VIRTUAL = "virtual:uni-pages";
-/** Resolved virtual module identifier with \0 prefix to avoid conflicts with other modules */
-declare const RESOLVED_MODULE_ID_VIRTUAL = "\0virtual:uni-pages";
-/** Output filename, the uni-app page configuration file */
-declare const OUTPUT_NAME = "pages.json";
-/** Supported page file extensions */
-declare const FILE_EXTENSIONS: string[];
-//#endregion
-//#region src/files.d.ts
-/**
- * Resolves the files that are valid pages for the given context.
- */
-declare function getPageFiles(path: string, options: ResolvedOptions): string[];
-/**
- * Check the pages.json file at the specified path, create an empty pages.json file if it doesn't exist or is not a valid file
- * @param path - File path to check
- * @returns boolean - Whether the operation was successful
- */
-declare function checkPagesJsonFileSync(path: fs.PathLike): boolean;
-/**
- * Run a task while holding an exclusive file lock.
- *
- * Unlike {@link writeFileWithLock}, this protects the whole read-modify-write
- * critical section. The lock is held from the moment `task` starts until it
- * resolves, so concurrent processes cannot observe or overwrite a half-written
- * state. This is required by pages.json generation, where the new content
- * depends on the current content (other platforms' `#ifdef` blocks).
- *
- * @param path - File path used as the lock target
- * @param task - Async work to run inside the lock; return value is forwarded
- * @param retry - Number of retries when lock acquisition fails, defaults to 3
- * @returns The value resolved by `task`, or `undefined` if the lock could not be acquired
- */
-declare function withFileLock<T>(path: string, task: () => Promise<T>, retry?: number): Promise<T | undefined>;
-/**
- * Safely write file using file lock
- * Avoid data corruption caused by concurrent writes through file lock
- * Use atomic write to ensure file write integrity
- *
- * Note: this only makes the *write* atomic. Callers that need to read the
- * current content before computing the new one must use {@link withFileLock}
- * so the read and write belong to the same critical section.
- *
- * @param path - File path
- * @param content - File content
- * @param retry - Number of retries when lock acquisition fails, defaults to 3
- */
-declare function writeFileWithLock(path: string, content: string, retry?: number): Promise<void | undefined>;
-//#endregion
-//#region src/options.d.ts
-/**
- * Resolve user configuration options
- * Merge user-provided configuration with default values and handle path resolution
- *
- * @param userOptions - User configuration options
- * @param viteRoot - Vite project root directory
- * @returns Resolved configuration options
- */
-declare function resolveOptions(userOptions: UserOptions, viteRoot?: string): ResolvedOptions;
-/**
- * Resolves the page dirs for its for its given globs
- */
-declare function resolvePageDirs(dir: string, root: string, exclude: string[]): string[];
-declare namespace index_d_exports {
-  export { ConfigSource, DefinePage, ExcludeIndexSignature, FILE_EXTENSIONS, MODULE_ID_VIRTUAL, MaybeCallable, MaybePromise, MaybePromiseCallable, OUTPUT_NAME, Options, Page, PageContext, PageMetaDatum, PagePath, RESOLVED_MODULE_ID_VIRTUAL, ResolvedOptions, SubPackageConfig, SubPageMetaDatum, UserOptions, UserPageMeta, UserTabBarItem, VitePluginUniPages, babelGenerate, checkPagesJsonFileSync, debug, debugType, VitePluginUniPages as default, definePage, defineUniPages, extsToGlob, findImports, findMacro, getPageFiles, invalidatePagesModule, isTargetFile, mergePageMetaDataArray, parseCode, parseSFC, resolveOptions, resolvePageDirs, sleep, tryPageMetaFromMacro, withFileLock, writeFileWithLock };
-}
-/**
- * vite-plugin-uni-pages plugin main entry
- *
- * Automatically scan page directories and generate pages.json configuration file
- * Support definePage macro for defining page metadata
- * Support multi-platform conditional compilation
- * Support sub-package configuration
- * Support TypeScript declaration file generation
- *
- * @param userOptions - User configuration options
- * @returns Vite plugin instance
- */
-declare function VitePluginUniPages(userOptions?: UserOptions): Plugin;
-//#endregion
-export { ConfigSource, type DefinePage, type ExcludeIndexSignature, FILE_EXTENSIONS, MODULE_ID_VIRTUAL, type MaybeCallable, type MaybePromise, type MaybePromiseCallable, OUTPUT_NAME, Options, Page, PageContext, type PageMetaDatum, PagePath, RESOLVED_MODULE_ID_VIRTUAL, ResolvedOptions, SubPackageConfig, type SubPageMetaDatum, UserOptions, type UserPageMeta, type UserTabBarItem, VitePluginUniPages, VitePluginUniPages as default, babelGenerate, checkPagesJsonFileSync, debug, debugType, type definePage, defineUniPages, extsToGlob, findImports, findMacro, getPageFiles, invalidatePagesModule, isTargetFile, mergePageMetaDataArray, parseCode, parseSFC, resolveOptions, resolvePageDirs, sleep, tryPageMetaFromMacro, withFileLock, writeFileWithLock };

package/index.d.ts

@@ -1,4 +0,0 @@
-/// <reference path="./client.d.ts" />
-
-export * from './dist/index.d.mts'
-export { default } from './dist/index.d.mts'