swpp-backends 3.0.0-alpha.3 → 3.0.0-alpha.310

package/{types → dist}/swpp/SwCompiler.d.ts

@@ -1,10 +1,13 @@
 import { CompilationEnv } from './database/CompilationEnv';
+import { CompilationFileParser } from './database/CompilationFileParser';
 import { CrossDepCode } from './database/CrossDepCode';
+import { DomCode } from './database/DomCode';
 import { RuntimeCoreCode } from './database/RuntimeCoreCode';
 import { RuntimeDepCode } from './database/RuntimeDepCode';
 import { CrossEnv } from './database/CrossEnv';
 import { RuntimeEventCode } from './database/RuntimeEventCode';
 import { RuntimeKeyValueDatabase } from './database/RuntimeKeyValueDatabase';
+import { CallChainRecorder } from './debug/CallChainRecorder';
 export declare class SwCompiler {
     private swCode;
     /**
@@ -15,24 +18,34 @@ export declare class SwCompiler {
 /** 运行时数据 */
 export declare class RuntimeData {
     /** 控制插入顺序 */
-    readonly insertOrder: (Exclude<keyof RuntimeData, 'insertOrder'> | string)[];
+    insertOrder: (Exclude<keyof RuntimeData, 'insertOrder' | 'domConfig'> | string)[];
     /** 运行时环境变量 */
-    readonly crossEnv: CrossEnv;
+    crossEnv: CrossEnv;
     /** 运行时工具函数 */
-    readonly runtimeDep: RuntimeDepCode;
+    runtimeDep: RuntimeDepCode;
     /** 运行时核心功能函数 */
-    readonly runtimeCore: RuntimeCoreCode;
+    runtimeCore: RuntimeCoreCode;
     /** 运行时事件注册 */
-    readonly runtimeEvent: RuntimeEventCode;
+    runtimeEvent: RuntimeEventCode;
     /** 运行时/编译时工具函数 */
-    readonly crossDep: CrossDepCode;
+    crossDep: CrossDepCode;
+    /** DOM 相关设置 */
+    domConfig: DomCode;
+    /** 追踪调用链 */
+    debugCallChain: CallChainRecorder;
+    constructor(compilationData: CompilationData);
     getDatabase(key: string): RuntimeKeyValueDatabase<any, {}>;
+    initCompilation(compilation: CompilationData): void;
+    freezeAll(): void;
 }
 /** 编译时数据 */
-export interface CompilationData {
+export declare class CompilationData {
     compilationEnv: CompilationEnv;
-    crossEnv: CrossEnv;
     crossDep: CrossDepCode;
+    crossEnv: CrossEnv;
+    fileParser: CompilationFileParser;
+    initRuntime(runtime: RuntimeData): void;
+    freezeAll(): void;
 }
 /** 版本号信息 */
 export interface BrowserVersion {

package/dist/swpp/SwCompiler.js

@@ -1,11 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuntimeData = exports.SwCompiler = void 0;
+exports.CompilationData = exports.RuntimeData = exports.SwCompiler = void 0;
+const CompilationEnv_1 = require("./database/CompilationEnv");
+const CompilationFileParser_1 = require("./database/CompilationFileParser");
 const CrossDepCode_1 = require("./database/CrossDepCode");
+const DomCode_1 = require("./database/DomCode");
+const KeyValueDatabase_1 = require("./database/KeyValueDatabase");
 const RuntimeCoreCode_1 = require("./database/RuntimeCoreCode");
 const RuntimeDepCode_1 = require("./database/RuntimeDepCode");
 const CrossEnv_1 = require("./database/CrossEnv");
 const RuntimeEventCode_1 = require("./database/RuntimeEventCode");
+const CallChainRecorder_1 = require("./debug/CallChainRecorder");
 const untils_1 = require("./untils");
 class SwCompiler {
     constructor() {
@@ -18,7 +23,6 @@ class SwCompiler {
     buildSwCode(runtime) {
         if (this.swCode)
             return this.swCode;
-        runtime.runtimeDep.fixDepFunction();
         this.swCode = '(() => {' + runtime.insertOrder
             .map(it => runtime.getDatabase(it).buildJsSource())
             .join(';\n')
@@ -29,35 +33,65 @@ class SwCompiler {
 exports.SwCompiler = SwCompiler;
 /** 运行时数据 */
 class RuntimeData {
-    constructor() {
+    constructor(compilationData) {
         /** 控制插入顺序 */
         this.insertOrder = [
             'crossEnv', 'crossDep', 'runtimeDep', 'runtimeCore', 'runtimeEvent'
         ];
-        /** 运行时环境变量 */
-        this.crossEnv = new CrossEnv_1.CrossEnv();
         /** 运行时工具函数 */
         this.runtimeDep = new RuntimeDepCode_1.RuntimeDepCode();
         /** 运行时核心功能函数 */
         this.runtimeCore = new RuntimeCoreCode_1.RuntimeCoreCode();
         /** 运行时事件注册 */
         this.runtimeEvent = new RuntimeEventCode_1.RuntimeEventCode();
-        /** 运行时/编译时工具函数 */
-        this.crossDep = new CrossDepCode_1.CrossDepCode();
+        /** DOM 相关设置 */
+        this.domConfig = new DomCode_1.DomCode();
+        /** 追踪调用链 */
+        this.debugCallChain = new CallChainRecorder_1.CallChainRecorder();
+        this.crossDep = compilationData.crossDep;
+        this.crossEnv = compilationData.crossEnv;
     }
     getDatabase(key) {
         if (!(key in this))
-            throw {
-                code: untils_1.exceptionNames.invalidKey,
-                message: `传入的 key [${key}] 不在当前对象中存在`
-            };
+            throw new untils_1.RuntimeException(untils_1.exceptionNames.invalidKey, `传入的 key [${key}] 不在当前对象中存在`);
         if (key == 'insertOrder')
-            throw {
-                code: untils_1.exceptionNames.invalidKey,
-                message: `传入的 key [${key}] 非法`
-            };
+            throw new untils_1.RuntimeException(untils_1.exceptionNames.invalidKey, `传入的 key [${key}] 非法`);
         // @ts-ignore
         return this[key];
     }
+    initCompilation(compilation) {
+        for (let key of this.insertOrder) {
+            this.getDatabase(key).initRuntimeAndCompilation(this, compilation);
+        }
+    }
+    freezeAll() {
+        this.insertOrder.forEach(it => this.getDatabase(it).freeze());
+    }
 }
 exports.RuntimeData = RuntimeData;
+/** 编译时数据 */
+class CompilationData {
+    constructor() {
+        this.compilationEnv = new CompilationEnv_1.CompilationEnv();
+        this.crossDep = new CrossDepCode_1.CrossDepCode();
+        this.crossEnv = new CrossEnv_1.CrossEnv();
+        this.fileParser = new CompilationFileParser_1.CompilationFileParser();
+    }
+    initRuntime(runtime) {
+        for (let key in this) {
+            const value = this[key];
+            if (value instanceof KeyValueDatabase_1.KeyValueDatabase) {
+                value.initRuntimeAndCompilation(runtime, this);
+            }
+        }
+    }
+    freezeAll() {
+        for (let key in this) {
+            const value = this[key];
+            if (value instanceof KeyValueDatabase_1.KeyValueDatabase) {
+                value.freeze();
+            }
+        }
+    }
+}
+exports.CompilationData = CompilationData;

package/{types → dist}/swpp/config/ConfigCluster.d.ts

@@ -1,31 +1,15 @@
+import * as crypto from 'node:crypto';
 import { COMMON_TYPE_COMP_ENV } from '../database/CompilationEnv';
+import { COMMON_TYPE_COMP_FP, FileParser } from '../database/CompilationFileParser';
 import { COMMON_TYPE_CROSS_DEP } from '../database/CrossDepCode';
 import { COMMON_TYPE_CROSS_ENV } from '../database/CrossEnv';
 import { COMMON_TYPE_DOM_CODE } from '../database/DomCode';
+import { DatabaseValue } from '../database/KeyValueDatabase';
 import { COMMON_TYPE_RUNTIME_CORE } from '../database/RuntimeCoreCode';
 import { COMMON_KEY_RUNTIME_DEP, FunctionInBrowser } from '../database/RuntimeDepCode';
 import { COMMON_TYPE_RUNTIME_EVENT } from '../database/RuntimeEventCode';
-import { CompilationData } from '../SwCompiler';
-import { IndivisibleName, SwppConfigModifier } from './ConfigLoader';
-/** 定义一个通过 `export default` 导出的配置 */
-export declare function defineConfig(config: SwppConfigTemplate): SwppConfigTemplate;
-/** 定义一个通过 `export const compilationEnv` 导出的配置 */
-export declare function defineCompilationEnv(config: SwppConfigCompilationEnv): SwppConfigCompilationEnv;
-/** 定义一个通过 `export const crossEnv` 导出的配置 */
-export declare function defineCrossEnv(config: SwppConfigCrossEnv): SwppConfigCrossDep;
-/** 定义一个通过 `export const runtimeDep` 导出的配置 */
-export declare function defineRuntimeDep(config: SwppConfigRuntimeDep): SwppConfigRuntimeDep;
-/** 定义一个通过 `export const crossDep` 导出的配置 */
-export declare function defineCrossDep(config: SwppConfigCrossDep): SwppConfigCrossDep;
-/** 定义一个通过 `export const runtimeCore` 导出的配置 */
-export declare function defineRuntimeCore(config: SwppConfigRuntimeCore): SwppConfigRuntimeCore;
-/** 定义一个通过 `export const domConfig` 导出的配置 */
-export declare function defineDomConfig(config: SwppConfigDomConfig): SwppConfigDomConfig;
-/** 定义一个通过 `export const runtimeEvent` 导出的配置 */
-export declare function defineRuntimeEvent(config: SwppConfigRuntimeEvent): SwppConfigRuntimeEvent;
-export type IndivisibleConfig<T> = {
-    [K in typeof IndivisibleName]: true;
-} & T;
+import { SwppConfigModifier } from './ConfigLoader';
+import { IndivisibleConfig, LazyInitConfig, NoCacheConfig, RuntimeSpecialConfig, RuntimeSupplier } from './SpecialConfig';
 /**
  * 定义一个无法分割的对象配置，这对一些强依赖对象内部属性的设置很有用，可以避免对象被错误地拼接。
  *
@@ -59,8 +43,59 @@ export type IndivisibleConfig<T> = {
  * }
  * ```
  */
-export declare function defineIndivisibleConfig<T extends Record<string, any>>(value: T): IndivisibleConfig<T>;
-type ValueOrReturnValue<T> = T | ((this: CompilationData) => T);
+export declare function defineIndivisibleConfig<T extends object>(value: T): IndivisibleConfig<T>;
+/**
+ * 定义一个不会被缓存的配置项。
+ *
+ * 默认情况下，swpp 会缓存配置项的结果，下一次读取同一个配置项时便不需要经过类型检查等操作。
+ *
+ * 有些时候可能希望每一次读取值时都动态读取，那么可以使用此方法禁用缓存。
+ *
+ * 注意：
+ *
+ * 1. 该选项禁用缓存后对于性能有些许影响，计算结果和校验的成本越高影响越大，一般情况下无显著影响。
+ * 2. 使用无缓存配置时也会同时禁用配置合并
+ *
+ * ---
+ *
+ * 例：
+ *
+ * ```typescript
+ * // config 1
+ * export const xxx = defineXxx({
+ *     example: Date.now()
+ * })
+ * // config 2
+ * export const nnn = defineNnn({
+ *     example: defineNoCacheConfig(() => Date.now())
+ * })
+ * ```
+ *
+ * 对于上方这个例子，第一种写法每次读取该项配置时，结果都将相同，第一次为 `123456` 那么以后永远都将是 `123456`，而对于第二种写法，则每次调用时都能动态地获取当前系统时间。
+ */
+export declare function defineNoCacheConfig<T>(getter: RuntimeSupplier<T>): NoCacheConfig<T>;
+/**
+ * 定义一个延迟初始化的配置项。
+ *
+ * 默认情况下，swpp 会在加载配置文件时对各项配置的值进行计算，此时就出现了一个问题，您无法在设置配置时访问其它配置内容。
+ *
+ * 如果您希望能够延后计算配置项的值以访问其它配置项，则可以使用该函数定义配置。
+ *
+ * ---
+ *
+ * 例：
+ *
+ * ```typescript
+ * export const xxx = defineXxx({
+ *     example: defineLazyInitConfig((runtime, compilation) => {
+ *         // 这里的代码将在第一次读取配置时执行
+ *         // do something
+ *         return <value>
+ *     })
+ * })
+ * ```
+ */
+export declare function defineLazyInitConfig<T>(getter: RuntimeSupplier<T>): LazyInitConfig<T>;
 /**
  * SWPP 配置模板
  *
@@ -81,15 +116,26 @@ export interface SwppConfigTemplate {
     runtimeEvent?: SwppConfigRuntimeEvent;
     /** @see {SwppConfigDomConfig} */
     domConfig?: SwppConfigDomConfig;
+    /** @see {SwppConfigCompilationFileParser} */
+    compilationFileParser?: SwppConfigCompilationFileParser;
     /** 配置编辑器 */
     modifier?: SwppConfigModifier;
 }
+type OptionalMap<T> = T extends object ? {
+    [K in keyof T]?: T[K];
+} : T;
+type SwppConfigValueExp<T> = T extends RuntimeSpecialConfig<any> ? (T | OptionalMap<ReturnType<T['get']>>) : (OptionalMap<T> | RuntimeSpecialConfig<T>);
+type SwppConfigHelper<R, C extends Record<string, DatabaseValue<R>>> = {
+    [K in keyof C]?: SwppConfigValueExp<C[K]['default']>;
+} & {
+    [K in string]: SwppConfigValueExp<R>;
+};
 /**
  * 运行时函数依赖。
  *
  * 该配置项用于放置所有仅在浏览器 SW 环境下执行的工具函数。
  *
- * 对于每一项配置 `<KEY>: <function>`：<KEY> 是函数名（推荐使用小写驼峰式命名），<function> 是函数体。
+ * 对于每一项配置 `<KEY>: <function>`：`<KEY>` 是函数名（推荐使用小写驼峰式命名），`<function>` 是函数体。
  *
  * 如果函数体中需要使用其它运行时的环境变量、函数依赖等内容，直接调用即可，
  * 如果需要避免 IDE 报错/警告，可以在配置文件中声明一些不导出的变量，以此假装上下文中存在该函数。
@@ -109,14 +155,11 @@ export interface SwppConfigTemplate {
  * }
  * // 如果为了避免 IDE 报错，还可以在文件任意一个位置编写类似的代码：
  * // let example: () => void       good
- * // type example = () => void     good
  * // let example = any             不推荐，因为丢失了类型，会影响 IDE 的自动补全和静态类型推断
  * // 或者直接在函数调用的位置使用 @ts-ignore 也可以避免报错，同样不推荐，理由同上
  * ```
  */
-export type SwppConfigRuntimeDep = {
-    [K in keyof COMMON_KEY_RUNTIME_DEP | string]?: K extends keyof COMMON_KEY_RUNTIME_DEP ? COMMON_KEY_RUNTIME_DEP[K]['default'] : FunctionInBrowser<any[], any>;
-};
+export type SwppConfigRuntimeDep = SwppConfigHelper<FunctionInBrowser<any[], any> | null, COMMON_KEY_RUNTIME_DEP>;
 /**
  * 运行时核心功能.
  *
@@ -125,22 +168,20 @@ export type SwppConfigRuntimeDep = {
  * 该配置项与 RuntimeDep 不同的是两者的定位，RuntimeDep 中主要放置一些简单的工具函数，而 RuntimeCore 则放置一些核心代码。
  * 默认情况下，RuntimeCore 也将被插入到 RuntimeDep 的后面，在一些特殊情况下可以避免一些声明顺序导致的问题。
  */
-export type SwppConfigRuntimeCore = {
-    [K in keyof COMMON_TYPE_RUNTIME_CORE | string]?: K extends keyof COMMON_TYPE_RUNTIME_CORE ? COMMON_TYPE_RUNTIME_CORE[K]['default'] : FunctionInBrowser<any[], any>;
-};
+export type SwppConfigRuntimeCore = SwppConfigHelper<FunctionInBrowser<any[], any>, COMMON_TYPE_RUNTIME_CORE>;
 /**
  * 运行时 & 编译期的函数依赖。
  *
  * 该配置项用于放置所有同时在浏览器和 NodeJs 环境下执行的工具函数。
  *
- * 对于每一项配置 `<KEY>: { <runOnBrowser>, <runOnNode> }`：<KEY> 是函数名，
- * <runOnBrowser> 是在浏览器环境下执行的代码，<runOnNode> 是在 NodeJs 环境下执行的代码。
+ * 对于每一项配置 `<KEY>: { <runOnBrowser>, <runOnNode> }`：`<KEY>` 是函数名，
+ * `<runOnBrowser>` 是在浏览器环境下执行的代码，`<runOnNode>` 是在 NodeJs 环境下执行的代码。
  *
  * 对于在浏览器环境下执行的代码，可以像 {@link SwppConfigRuntimeDep} 一样引用其它运行时的环境变量、依赖函数等内容。
  *
- * 对于在 NodeJs 环境下执行的代码，可以使用 `this` 调用 <runOnBrowser>（前提是 <runOnBrowser> 中没有依赖浏览器环境的代码）。
+ * 对于在 NodeJs 环境下执行的代码，可以使用 `this` 调用 `<runOnBrowser>`（前提是 `<runOnBrowser>` 中没有依赖浏览器环境的代码）。
  *
- * <runOnBrowser> 和 <runOnNode> 中的代码的行为应当完全一致。注意：此处说的行为一致是两者应当产生相同的副作用，内部具体实现可以不一样。
+ * `<runOnBrowser>` 和 `<runOnNode>` 中的代码的行为应当完全一致。注意：此处说的行为一致是两者应当产生相同的副作用，内部具体实现可以不一样。
  *
  * ---
  *
@@ -161,15 +202,13 @@ export type SwppConfigRuntimeCore = {
  * }
  * ```
  */
-export type SwppConfigCrossDep = {
-    [K in keyof COMMON_TYPE_CROSS_DEP | string]?: K extends keyof COMMON_TYPE_CROSS_DEP ? COMMON_TYPE_CROSS_DEP[K]['default'] : any;
-};
+export type SwppConfigCrossDep = SwppConfigHelper<any, COMMON_TYPE_CROSS_DEP>;
 /**
  * 运行时事件注册。
  *
  * 该配置项用于在 sw 中注册指定的事件，可以和 {@link SwppConfigRuntimeDep} 一样引用运行时的内容。
  *
- * 对于每一项配置 `<KEY>: <function>`：<KEY> 是事件名，<function> 是事件执行体。
+ * 对于每一项配置 `<KEY>: <function>`：`<KEY>` 是事件名，`<function>` 是事件执行体。
  *
  * ---
  *
@@ -189,17 +228,13 @@ export type SwppConfigCrossDep = {
  * }
  * ```
  */
-export type SwppConfigRuntimeEvent = {
-    [K in keyof COMMON_TYPE_RUNTIME_EVENT | string]?: K extends keyof COMMON_TYPE_RUNTIME_EVENT ? COMMON_TYPE_RUNTIME_EVENT[K]['default'] : FunctionInBrowser<[Event], any>;
-};
+export type SwppConfigRuntimeEvent = SwppConfigHelper<FunctionInBrowser<[Event], any>, COMMON_TYPE_RUNTIME_EVENT>;
 /**
  * 运行时 & 编译期环境变量。
  *
  * 该配置项用于放置需要同时在浏览器环境和 NodeJs 环境中使用的环境变量。
  *
- * 对于每一项配置 `<KEY>: <value | function(): value>`：<KEY> 是函数名（推荐使用大写下划线式命名），`value` 是环境变量的值。
- *
- * 环境变量中应对仅包含非函数内容，当填写的配置项为函数时，swpp 会将函数返回的内容插入到环境变量中。
+ * 对于每一项配置 `<KEY>: <value>`：`<KEY>` 是变量名（推荐使用大写下划线式命名），`value` 是环境变量的值，环境变量中应对仅包含非函数内容。
  *
  * 配置项填写的函数的执行环境为 NodeJs，所以不要编写依赖浏览器环境的代码。
  *
@@ -208,34 +243,34 @@ export type SwppConfigRuntimeEvent = {
  * 例：
  *
  * ```typescript
- * // 该代码将在 sw.js 中插入一系列常量，同时在编译期也可以动态读取
+ * // 该代码将在 sw.js 中插入一个常量
  * // const EXAMPLE = 'hello swpp'
- * // const FUN_EXAMPLE = 'fun hello swpp'
  * crossEnv: {
- *     EXAMPLE: 'hello swpp',
- *     FUN_EXAMPLE: function() {
- *         return 'fun ' + this.crossEnv.read('EXAMPLE')
- *     }
+ *     EXAMPLE: 'hello swpp'
  * }
  * ```
  */
-export type SwppConfigCrossEnv = {
-    [K in keyof COMMON_TYPE_CROSS_ENV | string]: ValueOrReturnValue<K extends keyof COMMON_TYPE_CROSS_ENV ? COMMON_TYPE_CROSS_ENV[K]['default'] : any>;
-};
+export type SwppConfigCrossEnv = SwppConfigHelper<any, COMMON_TYPE_CROSS_ENV>;
 /**
  * 构建期使用的环境变量。
  *
  * 该配置项用于放置仅需要在 NodeJs 环境中使用的环境变量。
  *
- * 对于每一项配置 `<KEY>: <value | function(): value>`：<KEY> 是函数名（推荐使用大写下划线式命名），`value` 是环境变量的值。
- *
- * 环境变量中应对仅包含非函数内容，当填写的配置项为函数时，swpp 会将函数返回的内容插入到环境变量中。
+ * 对于每一项配置 `<KEY>: <value | function(): value>`：`<KEY>` 是属性名（推荐函数使用小写驼峰，常量使用大写下划线式命名），`<value>` 是环境变量的值。
  *
  * 该环境变量中的代码在 NodeJs 环境下执行，执行结果不会被放入 sw.js 中。
  */
-export type SwppConfigCompilationEnv = {
-    [K in keyof COMMON_TYPE_COMP_ENV | string]?: K extends keyof COMMON_TYPE_COMP_ENV ? COMMON_TYPE_COMP_ENV[K]['default'] : any;
-};
+export type SwppConfigCompilationEnv = SwppConfigHelper<any, COMMON_TYPE_COMP_ENV>;
+/**
+ * 构建期使用的文件处理器。
+ *
+ * 该配置项用于放置需要在 NodeJs 环境中使用的文件处理器。
+ *
+ * 对于每一项配置 `<KEY>: <FileParser>`: <KEY> 是文件拓展名（不包括 `.`），<FileParser> 是处理机。
+ *
+ * @see {FileParser}
+ */
+export type SwppConfigCompilationFileParser = SwppConfigHelper<FileParser<crypto.BinaryLike>, COMMON_TYPE_COMP_FP>;
 /**
  * 运行时使用的常量、函数。
  *
@@ -244,8 +279,8 @@ export type SwppConfigCompilationEnv = {
  * 对于每一项配置 `<KEY>: <value>`：<KEY> 是常量名或函数名，常量推荐大写下划线命名，函数推荐小写驼峰命名，<value> 是值。
  *
  * 该配置项中的值只能使用本配置项中包含的内容，不能使用其它编译期、运行期的内容。
+ *
+ * 该配置项中所有以 `_inline` 开头的内容必须为 `() => void` 类型的函数，其将会以 `(function content)()` 的形式在插入的位置执行。
  */
-export type SwppConfigDomConfig = {
-    [K in keyof COMMON_TYPE_DOM_CODE | string]?: K extends keyof COMMON_TYPE_DOM_CODE ? COMMON_TYPE_DOM_CODE[K]['default'] : any;
-};
+export type SwppConfigDomConfig = SwppConfigHelper<any, COMMON_TYPE_DOM_CODE>;
 export {};

package/dist/swpp/config/ConfigCluster.js

@@ -1,47 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineConfig = defineConfig;
-exports.defineCompilationEnv = defineCompilationEnv;
-exports.defineCrossEnv = defineCrossEnv;
-exports.defineRuntimeDep = defineRuntimeDep;
-exports.defineCrossDep = defineCrossDep;
-exports.defineRuntimeCore = defineRuntimeCore;
-exports.defineDomConfig = defineDomConfig;
-exports.defineRuntimeEvent = defineRuntimeEvent;
 exports.defineIndivisibleConfig = defineIndivisibleConfig;
-const ConfigLoader_1 = require("./ConfigLoader");
-/** 定义一个通过 `export default` 导出的配置 */
-function defineConfig(config) {
-    return config;
-}
-/** 定义一个通过 `export const compilationEnv` 导出的配置 */
-function defineCompilationEnv(config) {
-    return config;
-}
-/** 定义一个通过 `export const crossEnv` 导出的配置 */
-function defineCrossEnv(config) {
-    return config;
-}
-/** 定义一个通过 `export const runtimeDep` 导出的配置 */
-function defineRuntimeDep(config) {
-    return config;
-}
-/** 定义一个通过 `export const crossDep` 导出的配置 */
-function defineCrossDep(config) {
-    return config;
-}
-/** 定义一个通过 `export const runtimeCore` 导出的配置 */
-function defineRuntimeCore(config) {
-    return config;
-}
-/** 定义一个通过 `export const domConfig` 导出的配置 */
-function defineDomConfig(config) {
-    return config;
-}
-/** 定义一个通过 `export const runtimeEvent` 导出的配置 */
-function defineRuntimeEvent(config) {
-    return config;
-}
+exports.defineNoCacheConfig = defineNoCacheConfig;
+exports.defineLazyInitConfig = defineLazyInitConfig;
+const SpecialConfig_1 = require("./SpecialConfig");
 /**
  * 定义一个无法分割的对象配置，这对一些强依赖对象内部属性的设置很有用，可以避免对象被错误地拼接。
  *
@@ -76,11 +38,61 @@ function defineRuntimeEvent(config) {
  * ```
  */
 function defineIndivisibleConfig(value) {
-    Object.defineProperty(value, ConfigLoader_1.IndivisibleName, {
-        value: true,
-        writable: false,
-        configurable: false,
-        enumerable: false
-    });
-    return value;
+    return new SpecialConfig_1.IndivisibleConfig(value);
+}
+/**
+ * 定义一个不会被缓存的配置项。
+ *
+ * 默认情况下，swpp 会缓存配置项的结果，下一次读取同一个配置项时便不需要经过类型检查等操作。
+ *
+ * 有些时候可能希望每一次读取值时都动态读取，那么可以使用此方法禁用缓存。
+ *
+ * 注意：
+ *
+ * 1. 该选项禁用缓存后对于性能有些许影响，计算结果和校验的成本越高影响越大，一般情况下无显著影响。
+ * 2. 使用无缓存配置时也会同时禁用配置合并
+ *
+ * ---
+ *
+ * 例：
+ *
+ * ```typescript
+ * // config 1
+ * export const xxx = defineXxx({
+ *     example: Date.now()
+ * })
+ * // config 2
+ * export const nnn = defineNnn({
+ *     example: defineNoCacheConfig(() => Date.now())
+ * })
+ * ```
+ *
+ * 对于上方这个例子，第一种写法每次读取该项配置时，结果都将相同，第一次为 `123456` 那么以后永远都将是 `123456`，而对于第二种写法，则每次调用时都能动态地获取当前系统时间。
+ */
+function defineNoCacheConfig(getter) {
+    return new SpecialConfig_1.NoCacheConfig(getter);
+}
+/**
+ * 定义一个延迟初始化的配置项。
+ *
+ * 默认情况下，swpp 会在加载配置文件时对各项配置的值进行计算，此时就出现了一个问题，您无法在设置配置时访问其它配置内容。
+ *
+ * 如果您希望能够延后计算配置项的值以访问其它配置项，则可以使用该函数定义配置。
+ *
+ * ---
+ *
+ * 例：
+ *
+ * ```typescript
+ * export const xxx = defineXxx({
+ *     example: defineLazyInitConfig((runtime, compilation) => {
+ *         // 这里的代码将在第一次读取配置时执行
+ *         // do something
+ *         return <value>
+ *     })
+ * })
+ * ```
+ */
+function defineLazyInitConfig(getter) {
+    return new SpecialConfig_1.LazyInitConfig(getter);
 }

package/dist/swpp/config/ConfigLoader.d.ts

@@ -0,0 +1,78 @@
+import { CompilationData, RuntimeData } from '../SwCompiler';
+import { SwppConfigCompilationEnv, SwppConfigCompilationFileParser, SwppConfigCrossDep, SwppConfigCrossEnv, SwppConfigDomConfig, SwppConfigRuntimeCore, SwppConfigRuntimeDep, SwppConfigRuntimeEvent, SwppConfigTemplate } from './ConfigCluster';
+export declare class ConfigLoader {
+    /** 支持的拓展名列表 */
+    private static readonly extensions;
+    private static jiti;
+    private static prevTask;
+    private config;
+    private modifierList;
+    constructor();
+    /**
+     * 加载一个配置文件，越早加载的优先级越高
+     * @param file 配置文件的绝对路径
+     */
+    load(file: string): Promise<void>;
+    /**
+     * 加载一个在代码层面编写的配置
+     */
+    loadFromCode(config: SwppConfigTemplate): Promise<void>;
+    private static waitLoad;
+    /** 将配置项的内容写入到环境中 */
+    generate(): Readonly<{
+        runtime: RuntimeData;
+        compilation: CompilationData;
+    }>;
+    /** 将新配置合并到已有配置中 */
+    private static mergeConfig;
+}
+/**
+ * 配置编辑器
+ */
+export interface SwppConfigModifier {
+    /**
+     * 自定义运行时和编译期的属性表
+     *
+     * 优先级越高越优先生效
+     */
+    build?: () => {
+        runtime: RuntimeData;
+        compilation: CompilationData;
+    };
+    /**
+     * 本函数用于向系统注册新的属性。
+     *
+     * 该函数内应当只调用 xxx.append 函数及其它工具函数，非必要不应当包含其它有副作用的操作。
+     *
+     * 优先级越低该函数越早执行。
+     */
+    registry?: (runtime: RuntimeData, compilation: CompilationData) => void;
+    /**
+     * 本函数用于动态修改属性的值。
+     *
+     * 该函数内应当只调用 xxx.update 函数及其它工具函数，非必要不应当包含其它有副作用的操作。
+     *
+     * 优先级越低该函数越早执行
+     */
+    dynamicUpdate?: (runtime: RuntimeData, compilation: CompilationData) => void;
+}
+/** 定义一个通过 `export default` 导出的配置 */
+export declare function defineConfig(config: SwppConfigTemplate): void;
+/** 定义一个通过 `export const compilationEnv` 导出的配置 */
+export declare function defineCompilationEnv(config: SwppConfigCompilationEnv): void;
+/** 定义一个通过 `export const compilationFileParser` 导出的配置 */
+export declare function defineCompilationFP(config: SwppConfigCompilationFileParser): void;
+/** 定义一个通过 `export const crossEnv` 导出的配置 */
+export declare function defineCrossEnv(config: SwppConfigCrossEnv): void;
+/** 定义一个通过 `export const runtimeDep` 导出的配置 */
+export declare function defineRuntimeDep(config: SwppConfigRuntimeDep): void;
+/** 定义一个通过 `export const crossDep` 导出的配置 */
+export declare function defineCrossDep(config: SwppConfigCrossDep): void;
+/** 定义一个通过 `export const runtimeCore` 导出的配置 */
+export declare function defineRuntimeCore(config: SwppConfigRuntimeCore): void;
+/** 定义一个通过 `export const domConfig` 导出的配置 */
+export declare function defineDomConfig(config: SwppConfigDomConfig): void;
+/** 定义一个通过 `export const runtimeEvent` 导出的配置 */
+export declare function defineRuntimeEvent(config: SwppConfigRuntimeEvent): void;
+/** 定义一个通过 `export const modifier` 导出的配置 */
+export declare function defineModifier(config: SwppConfigModifier): void;