@esmx/core 3.0.0-rc.10

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { type EsmxOptions, type COMMAND, type RuntimeTarget, type ImportMap, type SpecifierMap, type ScopesMap, Esmx } from './esmx';
+export { PathType, type ModuleConfig, type ParsedModuleConfig, parseModuleConfig } from './module-config';
+export { type PackConfig, type ParsedPackConfig, parsePackConfig } from './pack-config';
+export { type App, createApp } from './app';
+export { type RenderContextOptions, type ServerRenderHandle, type RenderFiles, RenderContext } from './render-context';
+export { isImmutableFile, type Middleware, createMiddleware, mergeMiddlewares } from './utils/middleware';
+export type { ManifestJson, ManifestJsonChunkSizes, ManifestJsonChunks } from './manifest-json';

package/dist/index.mjs

@@ -0,0 +1,19 @@
+export {
+  Esmx
+} from "./esmx";
+export {
+  PathType,
+  parseModuleConfig
+} from "./module-config.mjs";
+export {
+  parsePackConfig
+} from "./pack-config.mjs";
+export { createApp } from "./app.mjs";
+export {
+  RenderContext
+} from "./render-context.mjs";
+export {
+  isImmutableFile,
+  createMiddleware,
+  mergeMiddlewares
+} from "./utils/middleware.mjs";

package/dist/manifest-json.d.ts

@@ -0,0 +1,48 @@
+import type { RuntimeTarget } from './esmx';
+import type { ParsedModuleConfig } from './module-config';
+export interface ManifestJsonChunks {
+    /**
+     * 当前编译的 JS 文件。
+     */
+    js: string;
+    /**
+     * 当前编译的 CSS 文件。
+     */
+    css: string[];
+    /**
+     * 其它的资源文件。
+     */
+    resources: string[];
+    /**
+     * 构建产物的大小。
+     */
+    sizes: ManifestJsonChunkSizes;
+}
+export interface ManifestJsonChunkSizes {
+    js: number;
+    css: number;
+    resource: number;
+}
+export interface ManifestJson {
+    /**
+     * 服务名字，来自于：EsmxOptions.name
+     */
+    name: string;
+    /**
+     * 对外导出的文件
+     */
+    exports: Record<string, string>;
+    /**
+     * 构建的全部文件清单
+     */
+    buildFiles: string[];
+    /**
+     * 编译的文件信息
+     * 类型：Record<源文件, 编译信息>
+     */
+    chunks: Record<string, ManifestJsonChunks>;
+}
+/**
+ * 获取服务清单文件
+ */
+export declare function getManifestList(target: RuntimeTarget, moduleConfig: ParsedModuleConfig): Promise<ManifestJson[]>;

package/dist/manifest-json.mjs

@@ -0,0 +1,21 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+async function readJson(filename) {
+  return JSON.parse(await fsp.readFile(filename, "utf-8"));
+}
+export async function getManifestList(target, moduleConfig) {
+  return Promise.all(
+    moduleConfig.links.map(async (item) => {
+      const filename = path.resolve(item.root, target, "manifest.json");
+      try {
+        const data = await readJson(filename);
+        data.name = item.name;
+        return data;
+      } catch (e) {
+        throw new Error(
+          `'${item.name}' service '${target}/manifest.json' file read error`
+        );
+      }
+    })
+  );
+}

package/dist/module-config.d.ts

@@ -0,0 +1,185 @@
+export declare enum PathType {
+    npm = "npm:",
+    root = "root:"
+}
+/**
+ * 模块配置接口。
+ * 用于定义服务的导出、导入和外部依赖配置。
+ *
+ * @example
+ * ```ts
+ * // entry.node.ts
+ * import type { EsmxOptions } from '@esmx/core';
+ *
+ * export default {
+ *   modules: {
+ *     // 导出配置
+ *     exports: [
+ *       'root:src/components/button.vue',  // 导出源码文件
+ *       'root:src/utils/format.ts',
+ *       'npm:vue',  // 导出第三方依赖
+ *       'npm:vue-router'
+ *     ],
+ *
+ *     // 导入配置
+ *     links: {
+ *       // 源码安装方式：需要指向 dist 目录
+ *       'ssr-remote': 'root:./node_modules/ssr-remote/dist',
+ *       // 软件包安装方式：直接指向包目录
+ *       'other-remote': 'root:./node_modules/other-remote'
+ *     },
+ *
+ *     // 外部依赖配置
+ *     imports: {
+ *       'vue': 'ssr-remote/npm/vue',
+ *       'vue-router': 'ssr-remote/npm/vue-router'
+ *     }
+ *   }
+ * } satisfies EsmxOptions;
+ * ```
+ */
+export interface ModuleConfig {
+    /**
+     * 导出配置列表。
+     * 将服务中的特定代码单元（如组件、工具函数等）以 ESM 格式对外暴露。
+     *
+     * 支持两种类型：
+     * - root:* - 导出源码文件，如：'root:src/components/button.vue'
+     * - npm:* - 导出第三方依赖，如：'npm:vue'
+     *
+     * @example
+     * ```ts
+     * exports: [
+     *   // 导出源码文件
+     *   'root:src/components/button.vue',
+     *   'root:src/utils/format.ts',
+     *   // 导出第三方依赖
+     *   'npm:vue',
+     *   'npm:vue-router'
+     * ]
+     * ```
+     */
+    exports?: string[];
+    /**
+     * 导入配置映射。
+     * 配置需要导入的远程模块及其本地路径。
+     *
+     * 安装方式不同，配置也不同：
+     * - 源码安装（Workspace、Git）：需要指向 dist 目录
+     * - 软件包安装（Link、静态服务器、私有镜像源、File）：直接指向包目录
+     *
+     * @example
+     * ```ts
+     * links: {
+     *   // 源码安装方式：需要指向 dist 目录
+     *   'ssr-remote': 'root:./node_modules/ssr-remote/dist',
+     *   // 软件包安装方式：直接指向包目录
+     *   'other-remote': 'root:./node_modules/other-remote'
+     * }
+     * ```
+     */
+    links?: Record<string, string>;
+    /**
+     * 外部依赖映射。
+     * 配置要使用的外部依赖，通常是使用远程模块中的依赖。
+     *
+     * @example
+     * ```ts
+     * imports: {
+     *   // 使用远程模块中的依赖
+     *   'vue': 'ssr-remote/npm/vue',
+     *   'vue-router': 'ssr-remote/npm/vue-router'
+     * }
+     * ```
+     */
+    imports?: Record<string, string>;
+}
+/**
+ * 解析后的模块配置。
+ * 将原始的模块配置转换为标准化的内部格式，用于模块的加载和解析。
+ */
+export interface ParsedModuleConfig {
+    /**
+     * 当前服务的名称。
+     * 用于标识模块和生成导入路径。
+     */
+    name: string;
+    /**
+     * 当前服务的根目录路径。
+     * 用于解析相对路径和构建产物的存放。
+     */
+    root: string;
+    /**
+     * 导出配置列表。
+     * 定义了当前服务对外暴露的模块。
+     */
+    exports: {
+        /**
+         * 原始导出路径。
+         * 例如：'npm:vue' 或 'root:src/components'
+         */
+        name: string;
+        /**
+         * 路径类型。
+         * - npm: node_modules 中的依赖
+         * - root: 项目根目录下的文件
+         */
+        type: PathType;
+        /**
+         * 导入名称。
+         * 格式：'${serviceName}/${type}/${path}'
+         * 例如：'your-app-name/npm/vue' 或 'your-app-name/src/components'
+         */
+        importName: string;
+        /**
+         * 导出路径。
+         * 相对于服务根目录的路径。
+         * 例如：'./npm/vue' 或 './src/components'
+         */
+        exportName: string;
+        /**
+         * 实际的文件路径。
+         * 例如：'vue' 或 './src/components.ts'
+         */
+        exportPath: string;
+        /**
+         * 外部依赖名称。
+         * 用于其他服务导入此模块时的标识。
+         * 例如：'vue' 或 'your-app-name/src/components'
+         */
+        externalName: string;
+    }[];
+    /**
+     * 导入配置列表。
+     * 定义了当前服务需要导入的外部模块。
+     */
+    links: Array<{
+        /**
+         * 软包名称
+         */
+        name: string;
+        /**
+         * 软件包根目录
+         */
+        root: string;
+    }>;
+    /**
+     * 外部依赖映射。
+     * 将模块的导入路径映射到实际的模块位置。
+     *
+     * @example
+     * ```ts
+     * {
+     *   'vue': {
+     *     match: /^vue$/,  // 匹配导入语句
+     *     import: 'your-app-name/npm/vue'  // 实际的模块路径
+     *   }
+     * }
+     * ```
+     */
+    imports: Record<string, {
+        match: RegExp;
+        import?: string;
+    }>;
+}
+export declare function parseModuleConfig(name: string, root: string, config?: ModuleConfig): ParsedModuleConfig;

package/dist/module-config.mjs

@@ -0,0 +1,79 @@
+import path from "node:path";
+export var PathType = /* @__PURE__ */ ((PathType2) => {
+  PathType2["npm"] = "npm:";
+  PathType2["root"] = "root:";
+  return PathType2;
+})(PathType || {});
+export function parseModuleConfig(name, root, config = {}) {
+  const exports = [];
+  if (config.exports) {
+    config.exports.forEach((key) => {
+      if (key.startsWith("npm:" /* npm */)) {
+        const exportName = key.substring("npm:" /* npm */.length);
+        exports.push({
+          name: key,
+          type: "npm:" /* npm */,
+          importName: `${name}/npm/${exportName}`,
+          exportName: `./npm/${exportName}`,
+          exportPath: exportName,
+          externalName: exportName
+        });
+      } else if (key.startsWith("root:" /* root */)) {
+        const exportName = key.substring("root:" /* root */.length);
+        const exportNameNoSuffix = exportName.replace(/\.(ts|js)$/, "");
+        exports.push({
+          name: key,
+          type: "root:" /* root */,
+          importName: `${name}/${exportNameNoSuffix}`,
+          exportName: `./${exportNameNoSuffix}`,
+          exportPath: `./${exportName}`,
+          externalName: `${name}/${exportNameNoSuffix}`
+        });
+      }
+    });
+  }
+  const links = [];
+  if (config.links) {
+    const getLocalPath = (dir) => {
+      if (dir.startsWith("root:" /* root */)) {
+        return path.resolve(root, dir.substring("root:" /* root */.length));
+      } else if (path.isAbsolute(dir)) {
+        return dir;
+      }
+      return path.resolve(process.cwd(), dir);
+    };
+    const _links = config.links;
+    Object.keys(config.links).forEach((key) => {
+      const value = _links[key].trim();
+      links.push({
+        name: key,
+        root: getLocalPath(value)
+      });
+    });
+  }
+  const imports = {};
+  exports.forEach(({ importName, externalName }) => {
+    imports[externalName] = {
+      match: new RegExp(`^${externalName}$`),
+      import: importName
+    };
+  });
+  links.forEach(({ name: name2 }) => {
+    imports[name2] = {
+      match: new RegExp(`^${[name2]}/`)
+    };
+  });
+  if (config.imports) {
+    Object.entries(config.imports).forEach(([key, value]) => {
+      imports[key] = {
+        import: value,
+        match: new RegExp(`^${key}$`)
+      };
+    });
+  }
+  links.push({
+    name,
+    root: path.resolve(root, "dist")
+  });
+  return { name, root, exports, links, imports };
+}

package/dist/pack-config.d.ts

@@ -0,0 +1,251 @@
+import type { Esmx } from './esmx';
+/**
+ * 软件包打包配置接口。
+ * 用于将服务的构建产物打包成标准的 npm .tgz 格式软件包。
+ *
+ * 特点：
+ * - **标准化**：使用 npm 标准的 .tgz 打包格式
+ * - **完整性**：包含模块的源代码、类型声明和配置文件等所有必要文件
+ * - **兼容性**：与 npm 生态系统完全兼容，支持标准的包管理工作流
+ *
+ * 使用场景：
+ * - 模块打包发布
+ * - 版本发布管理
+ * - CI/CD 流程集成
+ *
+ * @example
+ * ```ts
+ * // entry.node.ts
+ * import type { EsmxOptions } from '@esmx/core';
+ *
+ * export default {
+ *   modules: {
+ *     // 配置需要导出的模块
+ *     exports: [
+ *       'root:src/components/button.vue',
+ *       'root:src/utils/format.ts',
+ *       'npm:vue',
+ *       'npm:vue-router'
+ *     ]
+ *   },
+ *   // 打包配置
+ *   pack: {
+ *     // 启用打包功能
+ *     enable: true,
+ *
+ *     // 同时输出多个版本
+ *     outputs: [
+ *       'dist/versions/latest.tgz',
+ *       'dist/versions/1.0.0.tgz'
+ *     ],
+ *
+ *     // 自定义 package.json
+ *     packageJson: async (esmx, pkg) => {
+ *       pkg.name = '@your-scope/your-app';
+ *       pkg.version = '1.0.0';
+ *       // 添加构建脚本
+ *       pkg.scripts = {
+ *         "prepare": "npm run build",
+ *         "build": "npm run build:dts && npm run build:ssr",
+ *         "build:ssr": "esmx build",
+ *         "build:dts": "tsc --declaration --emitDeclarationOnly --outDir dist/src"
+ *       };
+ *       return pkg;
+ *     },
+ *
+ *     // 打包前准备
+ *     onBefore: async (esmx, pkg) => {
+ *       // 添加必要文件
+ *       await fs.writeFile('dist/README.md', '# Your App\n\n模块导出说明...');
+ *       // 执行类型检查
+ *       await runTypeCheck();
+ *     },
+ *
+ *     // 打包后处理
+ *     onAfter: async (esmx, pkg, file) => {
+ *       // 发布到私有 npm 镜像源
+ *       await publishToRegistry(file, {
+ *         registry: 'https://npm.your-registry.com/'
+ *       });
+ *       // 或部署到静态服务器
+ *       await uploadToServer(file, 'https://static.example.com/packages');
+ *     }
+ *   }
+ * } satisfies EsmxOptions;
+ * ```
+ */
+export interface PackConfig {
+    /**
+     * 是否启用打包功能。
+     * 启用后会将构建产物打包成标准的 npm .tgz 格式软件包。
+     * @default false
+     */
+    enable?: boolean;
+    /**
+     * 指定输出的软件包文件路径。
+     * 支持以下配置方式：
+     * - string: 单个输出路径，如 'dist/versions/my-app.tgz'
+     * - string[]: 多个输出路径，用于同时生成多个版本
+     * - boolean: true 时使用默认路径 'dist/client/versions/latest.tgz'
+     *
+     * @example
+     * ```ts
+     * // 单个输出
+     * outputs: 'dist/app.tgz'
+     *
+     * // 多个版本
+     * outputs: [
+     *   'dist/versions/latest.tgz',
+     *   'dist/versions/1.0.0.tgz'
+     * ]
+     *
+     * // 使用默认路径
+     * outputs: true
+     * ```
+     *
+     * @default 'dist/client/versions/latest.tgz'
+     */
+    outputs?: string | string[] | boolean;
+    /**
+     * package.json 处理函数。
+     * 在打包前调用，用于自定义 package.json 的内容。
+     *
+     * 常见用途：
+     * - 修改包名和版本号
+     * - 添加或更新依赖项
+     * - 添加自定义字段
+     * - 配置发布相关信息
+     *
+     * @param esmx - Esmx 实例
+     * @param pkgJson - 原始的 package.json 内容
+     * @returns 处理后的 package.json 内容
+     *
+     * @example
+     * ```ts
+     * packageJson: async (esmx, pkg) => {
+     *   // 设置包信息
+     *   pkg.name = 'my-app';
+     *   pkg.version = '1.0.0';
+     *   pkg.description = '我的应用';
+     *
+     *   // 添加依赖
+     *   pkg.dependencies = {
+     *     'vue': '^3.0.0',
+     *     'express': '^4.17.1'
+     *   };
+     *
+     *   // 添加发布配置
+     *   pkg.publishConfig = {
+     *     registry: 'https://registry.example.com'
+     *   };
+     *
+     *   return pkg;
+     * }
+     * ```
+     */
+    packageJson?: (esmx: Esmx, pkgJson: Record<string, any>) => Promise<Record<string, any>>;
+    /**
+     * 打包前的钩子函数。
+     * 在生成 .tgz 文件之前调用，用于执行准备工作。
+     *
+     * 常见用途：
+     * - 添加额外的文件（README、LICENSE 等）
+     * - 执行测试或构建验证
+     * - 生成文档或元数据
+     * - 清理临时文件
+     *
+     * @param esmx - Esmx 实例
+     * @param pkgJson - 处理后的 package.json 内容
+     *
+     * @example
+     * ```ts
+     * onBefore: async (esmx, pkg) => {
+     *   // 添加文档
+     *   await fs.writeFile('dist/README.md', '# My App');
+     *   await fs.writeFile('dist/LICENSE', 'MIT License');
+     *
+     *   // 执行测试
+     *   await runTests();
+     *
+     *   // 生成文档
+     *   await generateDocs();
+     * }
+     * ```
+     */
+    onBefore?: (esmx: Esmx, pkgJson: Record<string, any>) => Promise<void>;
+    /**
+     * 打包后的钩子函数。
+     * 在 .tgz 文件生成后调用，用于处理打包产物。
+     *
+     * 常见用途：
+     * - 发布到 npm 仓库（公共或私有）
+     * - 上传到静态资源服务器
+     * - 执行版本管理
+     * - 触发 CI/CD 流程
+     *
+     * @param esmx - Esmx 实例
+     * @param pkgJson - 最终的 package.json 内容
+     * @param file - 生成的 .tgz 文件内容
+     *
+     * @example
+     * ```ts
+     * onAfter: async (esmx, pkg, file) => {
+     *   // 发布到 npm 私有仓库
+     *   await publishToRegistry(file, {
+     *     registry: 'https://registry.example.com'
+     *   });
+     *
+     *   // 上传到静态资源服务器
+     *   await uploadToServer(file, 'https://assets.example.com/packages');
+     *
+     *   // 创建版本标签
+     *   await createGitTag(pkg.version);
+     *
+     *   // 触发部署流程
+     *   await triggerDeploy(pkg.version);
+     * }
+     * ```
+     */
+    onAfter?: (esmx: Esmx, pkgJson: Record<string, any>, file: Buffer) => Promise<void>;
+}
+/**
+ * PackConfig 配置解析后的内部接口。
+ * 将用户配置标准化，设置默认值，便于框架内部使用。
+ *
+ * 主要处理：
+ * - 确保所有可选字段都有默认值
+ * - 统一输出路径格式
+ * - 标准化回调函数
+ */
+export interface ParsedPackConfig {
+    /**
+     * 是否启用打包功能。
+     * 解析后总是有确定的布尔值。
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * 解析后的输出文件路径列表。
+     * 将所有输出格式统一转换为字符串数组：
+     * - 布尔值 true → ['dist/client/versions/latest.tgz']
+     * - 字符串 → [输入的字符串]
+     * - 字符串数组 → 保持不变
+     */
+    outputs: string[];
+    /**
+     * 标准化的 package.json 处理函数。
+     * 未配置时使用默认函数，保持原始内容不变。
+     */
+    packageJson: (esmx: Esmx, pkgJson: Record<string, any>) => Promise<Record<string, any>>;
+    /**
+     * 标准化的打包前钩子函数。
+     * 未配置时使用空函数。
+     */
+    onBefore: (esmx: Esmx, pkgJson: Record<string, any>) => Promise<void>;
+    /**
+     * 标准化的打包后钩子函数。
+     * 未配置时使用空函数。
+     */
+    onAfter: (esmx: Esmx, pkgJson: Record<string, any>, file: Buffer) => Promise<void>;
+}
+export declare function parsePackConfig(config?: PackConfig): ParsedPackConfig;

package/dist/pack-config.mjs

@@ -0,0 +1,26 @@
+export function parsePackConfig(config = {}) {
+  const outputs = [];
+  if (typeof config.outputs === "string") {
+    outputs.push(config.outputs);
+  } else if (Array.isArray(config.outputs)) {
+    outputs.push(...config.outputs);
+  } else if (config.outputs !== false) {
+    outputs.push("dist/client/versions/latest.tgz");
+  }
+  return {
+    enable: config.enable ?? false,
+    outputs,
+    async packageJson(esmx, pkgJson) {
+      if (config.packageJson) {
+        pkgJson = await config.packageJson(esmx, pkgJson);
+      }
+      return pkgJson;
+    },
+    async onBefore(esmx, pkgJson) {
+      await config.onBefore?.(esmx, pkgJson);
+    },
+    async onAfter(esmx, pkgJson, file) {
+      await config.onAfter?.(esmx, pkgJson, file);
+    }
+  };
+}