@cocos/ccbuild 2.3.17 → 2.3.18

package/modules/build-engine/lib/index.d.ts

@@ -1,16 +1,16 @@
 import { StatsQuery } from "../../stats-query/lib/index";
-/**
- * @group Merged Types
+/**
+ * @group Merged Types
  */
 export declare function buildEngine(options: buildEngine.Options): Promise<buildEngine.Result>;
-/**
- * @group Merged Types
+/**
+ * @group Merged Types
  */
 export declare namespace buildEngine {
   type ModuleFormat = 'esm' | 'cjs' | 'system' | 'iife';
   interface IManglePropertiesOptions {
-    /**
-     * Prefix of generated names (default: '_ccprivate$')
+    /**
+     * Prefix of generated names (default: '_ccprivate$')
      */
     prefix?: string;
     mangleList?: string[];
@@ -20,179 +20,179 @@ export declare namespace buildEngine {
     ignoreJsDocTag?: boolean;
   }
   interface IWarningConfig {
-    /**
-     * 当没有显式声明构造函数时，是否要输出警告？
+    /**
+     * 当没有显式声明构造函数时，是否要输出警告？
      */
     noConstructorFound?: boolean;
-    /**
-     * 当函数内 'this.' 数量超过此阈值时，是否要输出警告？
+    /**
+     * 当函数内 'this.' 数量超过此阈值时，是否要输出警告？
      */
     thisDotThreshold?: number;
   }
   interface Options {
-    /**
-     * 引擎仓库目录。
+    /**
+     * 引擎仓库目录。
      */
     engine: string;
-    /**
-     * 输出目录。
+    /**
+     * 输出目录。
      */
     out: string;
     mode: StatsQuery.ConstantManager.ModeType;
     platform: StatsQuery.ConstantManager.PlatformType;
     flags?: Partial<StatsQuery.ConstantManager.IFlagConfig>;
-    /**
-     * 包含的功能。
+    /**
+     * 包含的功能。
      */
     features?: string[];
-    /**
-     * 输出模块格式。
-     * @default 'system'
+    /**
+     * 输出模块格式。
+     * @default 'system'
      */
     moduleFormat?: ModuleFormat;
-    /**
-     * 是否对生成的脚本进行压缩。
-     * @default false
+    /**
+     * 是否对生成的脚本进行压缩。
+     * @default false
      */
     compress?: boolean;
-    /**
-     * 是否内联枚举。支持 typescript const enum 和 enum。
-     * @example
-     * ```ts
-     *  enum MyEnum {
-     *      AAA,
-     *      BBB,
-     *  }
-     *
-     *  const a = MyEnum.AAA;
-     *  const b = MyEnum.BBB;
-     * ```
-     * 将被优化为：
-     * ```ts
-     *  var MyEnum = {
-     *      AAA: 0,
-     *      BBB: 1,
-     *  }
-     *
-     *  const a = 0;
-     *  const b = 1;
-     * ```
-     *
-     * @note 此功能要求项目中不能有同名的 enum，如果需要同名，可以定义枚举的时候用不同名字，然后在导出的时候 export as 跟其它模块同名的 enum。
+    /**
+     * 是否内联枚举。支持 typescript const enum 和 enum。
+     * @example
+     * ```ts
+     *  enum MyEnum {
+     *      AAA,
+     *      BBB,
+     *  }
+     *
+     *  const a = MyEnum.AAA;
+     *  const b = MyEnum.BBB;
+     * ```
+     * 将被优化为：
+     * ```ts
+     *  var MyEnum = {
+     *      AAA: 0,
+     *      BBB: 1,
+     *  }
+     *
+     *  const a = 0;
+     *  const b = 1;
+     * ```
+     *
+     * @note 此功能要求项目中不能有同名的 enum，如果需要同名，可以定义枚举的时候用不同名字，然后在导出的时候 export as 跟其它模块同名的 enum。
      */
     inlineEnum?: boolean;
-    /**
-     * 是否需要压缩私有属性。
-     * @default true
+    /**
+     * 是否需要压缩私有属性。
+     * @default true
      */
     mangleProperties?: boolean | IManglePropertiesOptions;
-    /**
-     * 警告相关配置。
+    /**
+     * 警告相关配置。
      */
     warn?: IWarningConfig;
-    /**
-     * 是否生成 source map。
-     * 若为 `inline` 则生成内联的 source map。
-     * @default false
+    /**
+     * 是否生成 source map。
+     * 若为 `inline` 则生成内联的 source map。
+     * @default false
      */
     sourceMap?: boolean | 'inline';
-    /**
-     * 若 `sourceMap` 为 `true`，此选项指定了 source map 的路径。
-     * @default `${outputPath.map}`
+    /**
+     * 若 `sourceMap` 为 `true`，此选项指定了 source map 的路径。
+     * @default `${outputPath.map}`
      */
     sourceMapFile?: string;
-    /**
-     * 若为 `true`，分割出 **所有** 引擎子模块。
-     * 否则，`.moduleEntries` 指定的所有子模块将被合并成一个单独的 `"cc"` 模块。
-     * @default false
+    /**
+     * 若为 `true`，分割出 **所有** 引擎子模块。
+     * 否则，`.moduleEntries` 指定的所有子模块将被合并成一个单独的 `"cc"` 模块。
+     * @default false
      */
     split?: boolean;
-    /**
-     * 原生代码的打包模式
-     * - 为 `wasm` 时使用 wasm 版本原生库
-     * - 为 `asmjs` 时使用 asmjs 版本的原生库
-     * - 为 `both` 时同时在结果中包含 wasm 与 asmjs 两个版本的原生库
+    /**
+     * 原生代码的打包模式
+     * - 为 `wasm` 时使用 wasm 版本原生库
+     * - 为 `asmjs` 时使用 asmjs 版本的原生库
+     * - 为 `both` 时同时在结果中包含 wasm 与 asmjs 两个版本的原生库
      */
     nativeCodeBundleMode?: 'wasm' | 'asmjs' | 'both';
-    /**
-     * Wasm compression mode, 'brotli' means to compress .wasm to .wasm.br.
-     * @note Currently, only WeChat and ByteDance mini-game support to load '.wasm.br' file.
+    /**
+     * Wasm compression mode, 'brotli' means to compress .wasm to .wasm.br.
+     * @note Currently, only WeChat and ByteDance mini-game support to load '.wasm.br' file.
      */
     wasmCompressionMode?: 'brotli';
-    /**
-     * If true, all deprecated features/API are excluded.
-     * You can also specify a version range(in semver range) to exclude deprecations in specified version(s).
-     * @default false
+    /**
+     * If true, all deprecated features/API are excluded.
+     * You can also specify a version range(in semver range) to exclude deprecations in specified version(s).
+     * @default false
      */
     noDeprecatedFeatures?: string | boolean;
-    /**
-     * Experimental.
+    /**
+     * Experimental.
      */
     incremental?: string;
-    /**
-     * BrowsersList targets.
+    /**
+     * BrowsersList targets.
      */
     targets?: string | string[] | Record<string, string>;
-    /**
-     * Enable loose compilation.
-     *
-     * @deprecated since 1.1.20, we force using true internal.
+    /**
+     * Enable loose compilation.
+     *
+     * @deprecated since 1.1.20, we force using true internal.
      */
     loose?: boolean;
-    /**
-     * How to generate the reference to external assets:
-     * - `'relative-from-out'`
-     * Generate the path relative from `out` directory, does not contain the leading './'.
-     *
-     * - `'relative-from-chunk'`
-     * Generate the path relative from the referencing output chunk.
-     *
-     * - `'dynamic'`(default)
-     * Use runtime `URL` API to resolve the absolute URL.
-     * This requires `URL` and `import.meta.url` to be valid.
+    /**
+     * How to generate the reference to external assets:
+     * - `'relative-from-out'`
+     * Generate the path relative from `out` directory, does not contain the leading './'.
+     *
+     * - `'relative-from-chunk'`
+     * Generate the path relative from the referencing output chunk.
+     *
+     * - `'dynamic'`(default)
+     * Use runtime `URL` API to resolve the absolute URL.
+     * This requires `URL` and `import.meta.url` to be valid.
      */
     assetURLFormat?: 'relative-from-out' | 'relative-from-chunk' | 'runtime-resolved';
-    /**
-     * Preserve engine type info, this options will build a TS engine to the output directory.
-     * It's useful when we need to take a step towards the AOT optimization.
-     * This options is only supported on Open Harmony platform for now.
-     * @default false
+    /**
+     * Preserve engine type info, this options will build a TS engine to the output directory.
+     * It's useful when we need to take a step towards the AOT optimization.
+     * This options is only supported on Open Harmony platform for now.
+     * @default false
      */
     preserveType?: boolean;
     visualize?: boolean | {
       file?: string;
     };
-    /**
-     * Generate cocos/native-binding/decorators.ts for native platforms
+    /**
+     * Generate cocos/native-binding/decorators.ts for native platforms
      */
     generateDecoratorsForJSB?: boolean;
-    /**
-     * Whether to generate 'named' register code for systemjs module format.
-     * SystemJS default register code: System.register([], function(){...});
-     * SystemJS named register code: System.register('module_name', [], function(){...});
-     * @note It's only avaiable when options.moduleFormat is 'system'.
+    /**
+     * Whether to generate 'named' register code for systemjs module format.
+     * SystemJS default register code: System.register([], function(){...});
+     * SystemJS named register code: System.register('module_name', [], function(){...});
+     * @note It's only avaiable when options.moduleFormat is 'system'.
      */
     enableNamedRegisterForSystemJSModuleFormat?: boolean;
   }
   interface Result {
-    /**
-     * Mappings between feature unit name and their actual chunk file, for example:
-     * ```js
-     * {
-     *   "core": "./core.js",
-     *   "gfx-webgl": "./gfx-webgl.js",
-     * }
-     * ```
+    /**
+     * Mappings between feature unit name and their actual chunk file, for example:
+     * ```js
+     * {
+     *   "core": "./core.js",
+     *   "gfx-webgl": "./gfx-webgl.js",
+     * }
+     * ```
      */
     exports: Record<string, string>;
-    /**
-     * The compulsory import mappings that should be applied.
+    /**
+     * The compulsory import mappings that should be applied.
      */
     chunkAliases: Record<string, string>;
-    /**
-     * The dependency graph, only including dependency chunks.
-     *
-     * @deprecated please use `chunkDepGraph` instead.
+    /**
+     * The dependency graph, only including dependency chunks.
+     *
+     * @deprecated please use `chunkDepGraph` instead.
      */
     dependencyGraph?: Record<string, string[]>;
     chunkDepGraph: Record<string, string[]>;
@@ -203,22 +203,22 @@ export declare namespace buildEngine {
     code: string;
   }>;
   function isSourceChanged(incrementalFile: string): Promise<boolean>;
-  /**
-   * Enumerates all chunk files that used by specified feature units.
-   * @param meta Metadata of build result.
-   * @param featureUnits Feature units.
+  /**
+   * Enumerates all chunk files that used by specified feature units.
+   * @param meta Metadata of build result.
+   * @param featureUnits Feature units.
    */
   function enumerateDependentChunks(meta: buildEngine.Result, featureUnits: string[]): string[];
-  /**
-   * Enumerates all asset files that used by specified feature units.
-   * @param meta Metadata of build result.
-   * @param featureUnits Feature units.
+  /**
+   * Enumerates all asset files that used by specified feature units.
+   * @param meta Metadata of build result.
+   * @param featureUnits Feature units.
    */
   function enumerateDependentAssets(meta: buildEngine.Result, featureUnits: string[]): string[];
-  /**
-   * Enumerates all chunk files and asset files that used by specified feature units.
-   * @param meta Metadata of build result.
-   * @param featureUnits Feature units.
+  /**
+   * Enumerates all chunk files and asset files that used by specified feature units.
+   * @param meta Metadata of build result.
+   * @param featureUnits Feature units.
    */
   function enumerateAllDependents(meta: buildEngine.Result, featureUnits: string[]): string[];
 }

package/modules/build-engine/lib/index.js

@@ -50,8 +50,8 @@ function moduleOptionsToBabelEnvModules(moduleOptions) {
       throw new Error(`Unknown module format ${moduleOptions}`);
   }
 }
-/**
- * @group Merged Types
+/**
+ * @group Merged Types
  */
 async function buildEngine(options) {
   applyDefaultOptions(options);
@@ -73,8 +73,8 @@ async function buildEngine(options) {
   }
 }
 exports.buildEngine = buildEngine;
-/**
- * @group Merged Types
+/**
+ * @group Merged Types
  */
 (function (buildEngine) {
   async function transform(code, moduleOption, loose) {
@@ -158,29 +158,29 @@ exports.buildEngine = buildEngine;
     }
     return result;
   }
-  /**
-   * Enumerates all chunk files that used by specified feature units.
-   * @param meta Metadata of build result.
-   * @param featureUnits Feature units.
+  /**
+   * Enumerates all chunk files that used by specified feature units.
+   * @param meta Metadata of build result.
+   * @param featureUnits Feature units.
    */
   function enumerateDependentChunks(meta, featureUnits) {
     return _enumerateDependentChunks(meta, featureUnits);
   }
   buildEngine.enumerateDependentChunks = enumerateDependentChunks;
-  /**
-   * Enumerates all asset files that used by specified feature units.
-   * @param meta Metadata of build result.
-   * @param featureUnits Feature units.
+  /**
+   * Enumerates all asset files that used by specified feature units.
+   * @param meta Metadata of build result.
+   * @param featureUnits Feature units.
    */
   function enumerateDependentAssets(meta, featureUnits) {
     const dependentChunks = _enumerateDependentChunks(meta, featureUnits);
     return _enumerateDependentAssets(meta, dependentChunks);
   }
   buildEngine.enumerateDependentAssets = enumerateDependentAssets;
-  /**
-   * Enumerates all chunk files and asset files that used by specified feature units.
-   * @param meta Metadata of build result.
-   * @param featureUnits Feature units.
+  /**
+   * Enumerates all chunk files and asset files that used by specified feature units.
+   * @param meta Metadata of build result.
+   * @param featureUnits Feature units.
    */
   function enumerateAllDependents(meta, featureUnits) {
     const dependentChunks = _enumerateDependentChunks(meta, featureUnits);

package/modules/dts-bundler/lib/index.js

@@ -315,11 +315,11 @@ exports.build = build;
 function buildIndexModule(featureUnits, statsQuery) {
   return `declare module "cc" {\n${statsQuery.evaluateIndexModuleSource(featureUnits).split('\n').map(line => `    ${line}`).join('\n')}\n}`;
 }
-/**
- * '@cocos/moduleName' -> 'cc/editor/moduleName'
- * '@cocos/moduleName/editor' -> 'cc/editor/moduleName'
- * 'moduleName' -> 'cc/editor/moduleName'
- * @param moduleName
+/**
+ * '@cocos/moduleName' -> 'cc/editor/moduleName'
+ * '@cocos/moduleName/editor' -> 'cc/editor/moduleName'
+ * 'moduleName' -> 'cc/editor/moduleName'
+ * @param moduleName
  */
 function transformToEditorModuleName(moduleName) {
   const split = moduleName.split('/');

package/modules/modularize/lib/module-config.d.ts

@@ -3,130 +3,130 @@ export type MinigamePlatformConfig = { [key in Lowercase<keyof typeof MinigamePl
 export type NativePlatformConfig = { [key in Lowercase<keyof typeof NativePlatform>]?: string };
 export type WebPlatformConfig = { [key in Lowercase<keyof typeof WebPlatform>]?: string };
 export type PlatformType = Uppercase<keyof typeof WebPlatform | keyof typeof MinigamePlatform | keyof typeof NativePlatform> | 'HTML5' | 'NATIVE' | 'NODEJS' | 'INVALID_PLATFORM';
-/**
- * Abstract platform export, like `web`, `native` and `minigame`.
- * Usually this is used for PAL modules.
- * The build tools resolve the relative platform as entry according to the build platform config.
- * - The value can be a `string` or a `object` which requires a default item.
- * eg. { "web": "/path/to/index.ts" } is equals to { "web": { default: "/path/to/index.ts" } }.
- * - We can also specify the exact platform like
- * { "web": {default: "/path/to/index.ts", "web-desktop": "/path/to/index.ts" } }.
+/**
+ * Abstract platform export, like `web`, `native` and `minigame`.
+ * Usually this is used for PAL modules.
+ * The build tools resolve the relative platform as entry according to the build platform config.
+ * - The value can be a `string` or a `object` which requires a default item.
+ * eg. { "web": "/path/to/index.ts" } is equals to { "web": { default: "/path/to/index.ts" } }.
+ * - We can also specify the exact platform like
+ * { "web": {default: "/path/to/index.ts", "web-desktop": "/path/to/index.ts" } }.
  */
 type AbstractPlatformExport<T> = ({
-  /**
-   * Default platform export for unspecified platforms.
+  /**
+   * Default platform export for unspecified platforms.
    */
   default: string;
 } & T) | string;
-/**
- * The export condition. `types` fields are required.
+/**
+ * The export condition. `types` fields are required.
  */
 type ExportCondition<T> = {
-  /**
-   * This is the main module export condition.
-   * - The dts bundle tools resolve this condition as entry.
-   * - The API doc tools resolve this condition as entry.
-   * - If no platform export is specified, the build tools resolve this condition as entry.
+  /**
+   * This is the main module export condition.
+   * - The dts bundle tools resolve this condition as entry.
+   * - The API doc tools resolve this condition as entry.
+   * - If no platform export is specified, the build tools resolve this condition as entry.
    */
   types: string;
-  /**
-   * The custom condition, for example:
-   * - For gfx module: {"webgl1": "/path/to/webgl1/index.ts", "webgl2": "/path/to/webgl2/index.ts"}
-   * - For physics module {"cannon": "/path/to/cannon/index.ts", "physX": "/path/to/physX/index.ts"}
+  /**
+   * The custom condition, for example:
+   * - For gfx module: {"webgl1": "/path/to/webgl1/index.ts", "webgl2": "/path/to/webgl2/index.ts"}
+   * - For physics module {"cannon": "/path/to/cannon/index.ts", "physX": "/path/to/physX/index.ts"}
    */
   [customCondition: string]: string;
 } & T;
 interface ConditionalExports {
-  /**
-   * This is exported to the game runtime.
-   * Also we build the `cc.d.ts` with this export condition's `types` field.
-   * `node` field is required to resolve the path of package.json for build tools.
+  /**
+   * This is exported to the game runtime.
+   * Also we build the `cc.d.ts` with this export condition's `types` field.
+   * `node` field is required to resolve the path of package.json for build tools.
    */
   '.': ExportCondition<{
     minigame?: AbstractPlatformExport<MinigamePlatformConfig>;
     native?: AbstractPlatformExport<NativePlatformConfig>;
     web?: AbstractPlatformExport<WebPlatformConfig>;
   }>;
-  /**
-   * This is exported to the engine internal.
-   * It useful when we need to export some friend interfaces for internal engine modules.
+  /**
+   * This is exported to the engine internal.
+   * It useful when we need to export some friend interfaces for internal engine modules.
    */
   './internal'?: ExportCondition<{
     minigame?: AbstractPlatformExport<MinigamePlatformConfig>;
     native?: AbstractPlatformExport<NativePlatformConfig>;
     web?: AbstractPlatformExport<WebPlatformConfig>;
   }>;
-  /**
-   * This is exported to the editor, which is useful when we need to export some editor only interfaces.
-   * Also we build `cc.editor.d.ts` from this export condition's `types` field.
-   * If this is not specified, we use the '.' export condition by default for module editor export,
-   * otherwise, the build tools merges '.' and './editor' exports together for editor runtime environment.
-   * It is different with `web_editor` or `native_editor` platform export:
-   * - this condition exports some editor specific interfaces which is not cross-platform.
-   * - the `web_editor` or `native_editor` platform export is an editor version of implementation of interfaces defined in `types` field which should be cross-platform.
+  /**
+   * This is exported to the editor, which is useful when we need to export some editor only interfaces.
+   * Also we build `cc.editor.d.ts` from this export condition's `types` field.
+   * If this is not specified, we use the '.' export condition by default for module editor export,
+   * otherwise, the build tools merges '.' and './editor' exports together for editor runtime environment.
+   * It is different with `web_editor` or `native_editor` platform export:
+   * - this condition exports some editor specific interfaces which is not cross-platform.
+   * - the `web_editor` or `native_editor` platform export is an editor version of implementation of interfaces defined in `types` field which should be cross-platform.
    */
   './editor'?: ExportCondition<{}>;
-  /**
-   * This export provide a the path of javascript module which exports some method to query the info of module.
+  /**
+   * This export provide a the path of javascript module which exports some method to query the info of module.
    */
   './query'?: string;
 }
 interface ModuleOverride {
-  /**
-   * The test string to evaluate.
+  /**
+   * The test string to evaluate.
    */
   test: string;
-  /**
-   * The override config, override mapping from key to value.
+  /**
+   * The override config, override mapping from key to value.
    */
   overrides: Record<string, string>;
 }
 export interface ModuleConfig {
   [key: string]: unknown;
-  /**
-   * The module name.
+  /**
+   * The module name.
    */
   name: string;
-  /**
-   * The version of module.
-   * It is useful when we change the module config, then we need to make some migration.
-   * This usually comes with the `cc.migrations` field.
+  /**
+   * The version of module.
+   * It is useful when we change the module config, then we need to make some migration.
+   * This usually comes with the `cc.migrations` field.
    */
   version: string;
-  /**
-   * The config for conditional exports.
+  /**
+   * The config for conditional exports.
    */
   exports?: ConditionalExports;
-  /**
-   * Specify the module dependencies is required if this module import another one.
-   * We need this field to generate the module dependency graph.
+  /**
+   * Specify the module dependencies is required if this module import another one.
+   * We need this field to generate the module dependency graph.
    */
   dependencies?: Record<string, string>;
-  /**
-   * Specify the dev dependencies, these dependencies are always used in `scripts` folder.
+  /**
+   * Specify the dev dependencies, these dependencies are always used in `scripts` folder.
    */
   devDependencies?: Record<string, string>;
-  /**
-   * The dependencies between modules form a tree-structured dependency graph.
-   * The correct dependency relationship should be that the upper module depends on the lower module one-way, and the reverse is wrong.
-   * However, it is normal for modules at the same layer to depend on each other, and such dependencies should be declared as `peerDependencies`.
-   * Otherwise the Turbo pipeline will report an error due to module circular dependencies.
-   * see: https://github.com/vercel/turbo/issues/1480
+  /**
+   * The dependencies between modules form a tree-structured dependency graph.
+   * The correct dependency relationship should be that the upper module depends on the lower module one-way, and the reverse is wrong.
+   * However, it is normal for modules at the same layer to depend on each other, and such dependencies should be declared as `peerDependencies`.
+   * Otherwise the Turbo pipeline will report an error due to module circular dependencies.
+   * see: https://github.com/vercel/turbo/issues/1480
    */
   peerDependencies?: Record<string, string>;
-  /**
-   * This is a CC-specific item difference from the node package.json standard specification.
+  /**
+   * This is a CC-specific item difference from the node package.json standard specification.
    */
   cc?: {
-    /**
-     * The module asset dependencies, which is an array of asset uuid.
+    /**
+     * The module asset dependencies, which is an array of asset uuid.
      */
     assetDependencies?: string[];
-    /**
-     * This is different with conditional exports.
-     * Sometimes we just want to override a script file instead of the whole module.
-     * Module override could support to do this job.
-     * - eg. { "test": "context.mode === 'BUILD'", "overrides": { "/path/to/dev.ts": "/path/to/build.ts" } }
+    /**
+     * This is different with conditional exports.
+     * Sometimes we just want to override a script file instead of the whole module.
+     * Module override could support to do this job.
+     * - eg. { "test": "context.mode === 'BUILD'", "overrides": { "/path/to/dev.ts": "/path/to/build.ts" } }
      */
     moduleOverrides?: ModuleOverride[];
   };