@esmx/core 3.0.0-rc.10

package/dist/utils/cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 缓存处理函数的类型定义
+ *
+ * @template T - 缓存数据的类型
+ * @param name - 缓存项的唯一标识符
+ * @param fetch - 获取数据的异步函数
+ * @returns 返回缓存的数据或新获取的数据
+ *
+ * @example
+ * ```ts
+ * const cache = createCache(true);
+ *
+ * // 第一次调用会执行 fetch 函数
+ * const data1 = await cache('key', async () => {
+ *   return await fetchSomeData();
+ * });
+ *
+ * // 第二次调用会直接返回缓存的结果
+ * const data2 = await cache('key', async () => {
+ *   return await fetchSomeData();
+ * });
+ * ```
+ */
+export type CacheHandle = <T>(name: string, fetch: () => Promise<T>) => Promise<T>;
+/**
+ * 创建一个缓存处理函数
+ *
+ * @param enable - 是否启用缓存功能
+ * @returns 返回一个缓存处理函数
+ *
+ * @description
+ * 当 enable 为 true 时，会创建一个带有内存缓存的处理函数，相同的 name 只会执行一次 fetch。
+ * 当 enable 为 false 时，每次调用都会执行 fetch 函数，不会缓存结果。
+ *
+ * @example
+ * ```ts
+ * // 创建一个启用缓存的处理函数
+ * const cacheEnabled = createCache(true);
+ *
+ * // 创建一个禁用缓存的处理函数
+ * const cacheDisabled = createCache(false);
+ *
+ * // 使用缓存处理函数
+ * const result = await cacheEnabled('userProfile', async () => {
+ *   return await fetchUserProfile(userId);
+ * });
+ * ```
+ */
+export declare function createCache(enable: boolean): <T>(name: string, fetch: () => Promise<T>) => Promise<T>;

package/dist/utils/cache.mjs

@@ -0,0 +1,16 @@
+export function createCache(enable) {
+  if (enable) {
+    const map = /* @__PURE__ */ new Map();
+    return async (name, fetch) => {
+      if (map.has(name)) {
+        return map.get(name);
+      }
+      const result = await fetch();
+      map.set(name, result);
+      return result;
+    };
+  }
+  return (name, fetch) => {
+    return fetch();
+  };
+}

package/dist/utils/import-map.d.ts

@@ -0,0 +1,8 @@
+import type { ImportMap } from '@esmx/import';
+import type { RuntimeTarget } from '../esmx';
+import type { ManifestJson } from '../manifest-json';
+import type { ParsedModuleConfig } from '../module-config';
+/**
+ * 获取导入映射对象
+ */
+export declare function getImportMap(target: RuntimeTarget, manifests: readonly ManifestJson[], moduleConfig: ParsedModuleConfig): Promise<ImportMap>;

package/dist/utils/import-map.mjs

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { pathWithoutIndex } from "./path-without-index.mjs";
+export async function getImportMap(target, manifests, moduleConfig) {
+  const imports = {};
+  if (target === "client") {
+    for (const manifest of manifests) {
+      for (const [name, value] of Object.entries(manifest.exports)) {
+        imports[`${manifest.name}/${name}`] = `/${manifest.name}/${value}`;
+      }
+    }
+  } else {
+    for (const manifest of manifests) {
+      const link = moduleConfig.links.find(
+        (item) => item.name === manifest.name
+      );
+      if (!link) {
+        throw new Error(
+          `'${manifest.name}' service did not find module config`
+        );
+      }
+      for (const [name, value] of Object.entries(manifest.exports)) {
+        imports[`${manifest.name}/${name}`] = path.resolve(
+          link.root,
+          "server",
+          value
+        );
+      }
+    }
+  }
+  pathWithoutIndex(imports);
+  return { imports };
+}

package/dist/utils/middleware.d.ts

@@ -0,0 +1,57 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Esmx } from '../esmx';
+/**
+ * 中间件函数类型定义
+ *
+ * @description
+ * 中间件是一个函数，用于处理 HTTP 请求。它接收请求对象、响应对象和下一个中间件函数作为参数。
+ * 中间件可以执行以下操作：
+ * - 修改请求和响应对象
+ * - 结束请求-响应循环
+ * - 调用下一个中间件
+ *
+ * @example
+ * ```ts
+ * // 创建一个简单的日志中间件
+ * const loggerMiddleware: Middleware = (req, res, next) => {
+ *   console.log(`${req.method} ${req.url}`);
+ *   next();
+ * };
+ * ```
+ */
+export type Middleware = (req: IncomingMessage, res: ServerResponse, next: Function) => void;
+/**
+ * 判断文件路径是否是一个符合 esmx 规范的不可变文件
+ * @param path 文件路径
+ */
+export declare function isImmutableFile(filename: string): boolean;
+/**
+ * 创建 Esmx 应用的中间件
+ *
+ * @param esmx - Esmx 实例
+ * @returns 返回一个处理静态资源的中间件
+ *
+ * @description
+ * 该函数创建一个中间件，用于处理模块的静态资源请求。它会：
+ * - 根据模块配置创建对应的静态资源中间件
+ * - 处理资源的缓存控制
+ * - 支持不可变文件的长期缓存
+ *
+ * @example
+ * ```ts
+ * import { Esmx, createMiddleware } from '@esmx/core';
+ *
+ * const esmx = new Esmx();
+ * const middleware = createMiddleware(esmx);
+ *
+ * // 在 HTTP 服务器中使用
+ * server.use(middleware);
+ * ```
+ */
+export declare function createMiddleware(esmx: Esmx): Middleware;
+/**
+ * 将多个中间件，合并成一个中间件执行
+ * @param middlewares 中间件列表
+ * @returns
+ */
+export declare function mergeMiddlewares(middlewares: Middleware[]): Middleware;

package/dist/utils/middleware.mjs

@@ -0,0 +1,51 @@
+import path from "node:path";
+import send from "send";
+const reFinal = /\.final\.[a-zA-Z0-9]+$/;
+export function isImmutableFile(filename) {
+  return reFinal.test(filename);
+}
+export function createMiddleware(esmx) {
+  const middlewares = esmx.moduleConfig.links.map((item) => {
+    const base = `/${item.name}/`;
+    const baseUrl = new URL(`file:`);
+    const root = path.resolve(item.root, "client");
+    return (req, res, next) => {
+      const url = req.url ?? "/";
+      const { pathname } = new URL(req.url ?? "/", baseUrl);
+      if (!url.startsWith(base) || req.method !== "GET") {
+        next();
+        return;
+      }
+      send(req, pathname.substring(base.length - 1), {
+        root
+      }).on("headers", () => {
+        if (isImmutableFile(pathname)) {
+          res.setHeader(
+            "cache-control",
+            "public, max-age=31536000, immutable"
+          );
+        } else {
+          res.setHeader("cache-control", "no-cache");
+        }
+      }).pipe(res);
+    };
+  });
+  return mergeMiddlewares(middlewares);
+}
+export function mergeMiddlewares(middlewares) {
+  return (req, res, next) => {
+    let index = 0;
+    function dispatch() {
+      if (index < middlewares.length) {
+        middlewares[index](req, res, () => {
+          index++;
+          dispatch();
+        });
+        return;
+      } else {
+        next();
+      }
+    }
+    dispatch();
+  };
+}

package/dist/utils/path-without-index.d.ts

@@ -0,0 +1 @@
+export declare function pathWithoutIndex(i: Record<string, string>): void;

package/dist/utils/path-without-index.mjs

@@ -0,0 +1,9 @@
+export function pathWithoutIndex(i) {
+  const s = "/index";
+  Object.entries(i).forEach(([k, v]) => {
+    if (k.endsWith(s)) {
+      k = k.substring(0, k.length - s.length);
+      i[k] = v;
+    }
+  });
+}

package/dist/utils/resolve-path.d.ts

@@ -0,0 +1,2 @@
+export type ProjectPath = './' | 'dist' | 'dist/index.js' | 'dist/package.json' | 'dist/client' | 'dist/client/manifest.json' | 'dist/client/css' | 'dist/client/images' | 'dist/client/media' | 'dist/client/fonts' | 'dist/client/workers' | 'dist/client/importmap' | 'dist/client/versions/latest.tgz' | 'dist/server' | 'dist/server/manifest.json' | 'dist/node' | 'dist/node/src/entry.node.js' | 'src' | 'src/entry.node.ts' | 'src/entry.client.ts' | 'src/entry.server.ts' | 'package.json';
+export declare function resolvePath(root: string, projectPath: ProjectPath, ...args: string[]): string;

package/dist/utils/resolve-path.mjs

@@ -0,0 +1,4 @@
+import path from "node:path";
+export function resolvePath(root, projectPath, ...args) {
+  return path.resolve(root, projectPath, ...args);
+}

package/dist/utils/static-import-lexer.d.ts

@@ -0,0 +1,26 @@
+import type fs from 'node:fs';
+/**
+ * 从 JS 代码中获取静态 import 的模块名列表。也许不能并发多个调用，没实验过。
+ * @param code js 代码
+ * @returns `Promise<string[]>` 静态 import 的模块名列表
+ */
+export declare function getImportsFromJsCode(code: string): Promise<string[]>;
+/**
+ * 从 JS 文件中获取静态 import 的模块名列表。
+ * @param filepath js 文件路径
+ * @returns `Promise<string[]>` 静态 import 的模块名列表
+ */
+export declare function getImportsFromJsFile(filepath: fs.PathLike | fs.promises.FileHandle): Promise<string[]>;
+import type { ImportMap, SpecifierMap } from '@esmx/import';
+import type { ParsedModuleConfig } from '../module-config';
+export type ImportPreloadInfo = SpecifierMap;
+/**
+ * 获取导入的预加载信息。
+ * @param specifier 模块名
+ * @param importMap 导入映射对象
+ * @param moduleConfig 模块配置
+ * @returns
+ *   - `Promise<{ [specifier: string]: ImportPreloadPathString }>` 模块名和文件路径的映射对象
+ *   - `null` specifier 不存在
+ */
+export declare function getImportPreloadInfo(specifier: string, importMap: ImportMap, moduleConfig: ParsedModuleConfig): Promise<SpecifierMap | null>;

package/dist/utils/static-import-lexer.mjs

@@ -0,0 +1,43 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import * as esmLexer from "es-module-lexer";
+export async function getImportsFromJsCode(code) {
+  await esmLexer.init;
+  const [imports] = esmLexer.parse(code);
+  return imports.filter((item) => item.t === 1 && item.n).map((item) => item.n);
+}
+export async function getImportsFromJsFile(filepath) {
+  const source = await fsp.readFile(filepath, "utf-8");
+  return getImportsFromJsCode(source);
+}
+export async function getImportPreloadInfo(specifier, importMap, moduleConfig) {
+  const importInfo = importMap.imports;
+  if (!importInfo || !(specifier in importInfo)) {
+    return null;
+  }
+  const ans = {};
+  const needHandles = [[specifier]];
+  while (needHandles.length) {
+    const needHandle = [];
+    for (const specifier2 of needHandles.shift()) {
+      let filepath = importInfo[specifier2];
+      const splitRes = filepath.split("/");
+      if (splitRes[0] === "") splitRes.shift();
+      const name = splitRes.shift() + "";
+      const link = moduleConfig.links.find((item) => item.name === name);
+      if (!link) {
+        continue;
+      }
+      filepath = path.join(link.root, "client", ...splitRes);
+      const imports = await getImportsFromJsFile(filepath);
+      imports.forEach((specifier3) => {
+        if (specifier3 in importInfo && !ans[specifier3]) {
+          ans[specifier3] = importInfo[specifier3];
+          needHandle.push(specifier3);
+        }
+      });
+    }
+    needHandle.length && needHandles.push(needHandle);
+  }
+  return ans;
+}

package/package.json

@@ -0,0 +1,103 @@
+{
+    "name": "@esmx/core",
+    "description": "A high-performance microfrontend framework supporting Vue, React, Preact, Solid, and Svelte with SSR and Module Federation capabilities.",
+    "author": {
+        "name": "lzxb",
+        "url": "https://github.com/lzxb"
+    },
+    "contributors": [
+        {
+            "name": "RockShi1994",
+            "url": "https://github.com/RockShi1994"
+        },
+        {
+            "name": "jerrychan7",
+            "url": "https://github.com/jerrychan7"
+        }
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/js-esm/esmx.git",
+        "directory": "packages/core"
+    },
+    "homepage": "https://github.com/js-esm/esmx",
+    "bugs": {
+        "url": "https://github.com/js-esm/esmx/issues"
+    },
+    "template": "library-node",
+    "keywords": [
+        "Vue",
+        "React",
+        "Preact",
+        "Solid",
+        "Svelte",
+        "ESM",
+        "Microfrontend",
+        "SSR",
+        "Rspack",
+        "Module Federation",
+        "High Performance",
+        "TypeScript"
+    ],
+    "license": "MIT",
+    "bin": {
+        "esmx": "./dist/cli/index.mjs"
+    },
+    "engines": {
+        "node": ">=22.6"
+    },
+    "scripts": {
+        "lint:js": "biome check --write --no-errors-on-unmatched",
+        "lint:css": "stylelint '**/*.{css,vue}' --fix --aei",
+        "lint:type": "tsc --noEmit",
+        "test": "vitest run --pass-with-no-tests",
+        "coverage": "vitest run --coverage --pass-with-no-tests",
+        "build": "unbuild"
+    },
+    "dependencies": {
+        "@esmx/import": "3.0.0-rc.10",
+        "@types/serialize-javascript": "^5.0.4",
+        "es-module-lexer": "^1.6.0",
+        "find": "^0.3.0",
+        "send": "^1.1.0",
+        "serialize-javascript": "^6.0.2",
+        "write": "^2.0.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "1.9.4",
+        "@esmx/lint": "3.0.0-rc.10",
+        "@types/find": "^0.2.4",
+        "@types/node": "22.13.10",
+        "@types/send": "^0.17.4",
+        "@types/write": "^2.0.4",
+        "@vitest/coverage-v8": "3.0.8",
+        "stylelint": "16.15.0",
+        "typescript": "5.8.2",
+        "unbuild": "2.0.0",
+        "vitest": "3.0.8"
+    },
+    "version": "3.0.0-rc.10",
+    "type": "module",
+    "private": false,
+    "exports": {
+        ".": {
+            "import": "./dist/index.mjs",
+            "types": "./dist/index.d.ts"
+        },
+        "./cli": {
+            "import": "./dist/cli/cli.mjs",
+            "types": "./dist/cli/cli.d.ts"
+        }
+    },
+    "module": "dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "lib",
+        "src",
+        "dist",
+        "*.mjs",
+        "template",
+        "public"
+    ],
+    "gitHead": "4a528ffecfdc6f2c6e7d97bc952427745f467691"
+}

package/src/app.ts

@@ -0,0 +1,144 @@
+import { pathToFileURL } from 'node:url';
+import { createLoaderImport } from '@esmx/import';
+import type { COMMAND, Esmx } from './esmx';
+import {
+    RenderContext,
+    type RenderContextOptions,
+    type ServerRenderHandle
+} from './render-context';
+import { type Middleware, createMiddleware } from './utils/middleware';
+
+/**
+ * 应用程序实例接口。
+ *
+ * App 是 Esmx 框架的应用抽象，提供了统一的接口来管理应用的生命周期、
+ * 静态资源和服务端渲染。
+ *
+ * @example
+ * ```ts
+ * // entry.node.ts
+ * export default {
+ *   // 开发环境配置
+ *   async devApp(esmx) {
+ *     return import('@esmx/rspack').then((m) =>
+ *       m.createRspackHtmlApp(esmx, {
+ *         config(rc) {
+ *           // 自定义 Rspack 配置
+ *         }
+ *       })
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export interface App {
+    /**
+     * 静态资源处理中间件。
+     *
+     * 开发环境：
+     * - 处理源码的静态资源请求
+     * - 支持实时编译和热更新
+     * - 使用 no-cache 缓存策略
+     *
+     * 生产环境：
+     * - 处理构建后的静态资源
+     * - 支持不可变文件的长期缓存（.final.xxx）
+     * - 优化的资源加载策略
+     *
+     * @example
+     * ```ts
+     * server.use(esmx.middleware);
+     * ```
+     */
+    middleware: Middleware;
+
+    /**
+     * 服务端渲染函数。
+     *
+     * 根据运行环境提供不同实现：
+     * - 生产环境（start）：加载构建后的服务端入口文件（entry.server）执行渲染
+     * - 开发环境（dev）：加载源码中的服务端入口文件执行渲染
+     *
+     * @param options - 渲染选项
+     * @returns 返回渲染上下文，包含渲染结果
+     *
+     * @example
+     * ```ts
+     * const rc = await esmx.render({
+     *   params: { url: '/page' }
+     * });
+     * res.end(rc.html);
+     * ```
+     */
+    render: (options?: RenderContextOptions) => Promise<RenderContext>;
+
+    /**
+     * 生产环境构建函数。
+     * 用于资源打包和优化。
+     *
+     * @returns 构建成功返回 true，失败返回 false
+     */
+    build?: () => Promise<boolean>;
+
+    /**
+     * 资源清理函数。
+     * 用于关闭服务器、断开连接等。
+     *
+     * @returns 清理成功返回 true，失败返回 false
+     */
+    destroy?: () => Promise<boolean>;
+}
+
+/**
+ * 创建生产环境的应用程序实例，开发环境不可用。
+ */
+export async function createApp(esmx: Esmx, command: COMMAND): Promise<App> {
+    const render =
+        command === esmx.COMMAND.start
+            ? await createStartRender(esmx) // 提供实际的渲染函数
+            : createErrorRender(esmx); // 提供错误提示渲染函数
+    return {
+        middleware: createMiddleware(esmx),
+        render
+    };
+}
+
+/**
+ * 创建生产环境渲染函数。
+ * 加载构建后的服务端入口文件（entry.server）执行渲染。
+ *
+ * @param esmx - Esmx 实例
+ * @returns 返回渲染函数
+ * @internal
+ *
+ * @example
+ * ```ts
+ * // 服务端入口文件 (entry.server)
+ * export default async function render(rc: RenderContext) {
+ *   rc.html = '<html>...</html>';
+ * }
+ * ```
+ */
+async function createStartRender(esmx: Esmx) {
+    const baseURL = pathToFileURL(esmx.root) as URL;
+    const importMap = await esmx.getImportMap('server');
+    const loaderImport = createLoaderImport(baseURL, importMap);
+
+    return async (options?: RenderContextOptions): Promise<RenderContext> => {
+        const rc = new RenderContext(esmx, options);
+        const result = await loaderImport(`${esmx.name}/src/entry.server`);
+        const serverRender: ServerRenderHandle = result[rc.entryName];
+        if (typeof serverRender === 'function') {
+            await serverRender(rc);
+        }
+        return rc;
+    };
+}
+
+function createErrorRender(esmx: Esmx) {
+    return (options?: RenderContextOptions) => {
+        throw new Error(
+            `App instance is only available in production and can only execute built artifacts.`
+        );
+    };
+}

package/src/cli/cli.ts

@@ -0,0 +1,99 @@
+import module from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { COMMAND, Esmx, type EsmxOptions } from '../esmx';
+
+async function getSrcOptions(): Promise<EsmxOptions> {
+    return import(path.resolve(process.cwd(), './src/entry.node.ts')).then(
+        (m) => m.default
+    );
+}
+
+export async function cli(command: string) {
+    if (command !== COMMAND.dev) {
+        process.env.NODE_ENV = 'production';
+    }
+    let esmx: Esmx | null;
+    let opts: EsmxOptions | null = null;
+    switch (command) {
+        case COMMAND.dev:
+            opts = await getSrcOptions();
+            esmx = new Esmx(opts);
+            exit(await esmx.init(COMMAND.dev));
+
+            // 释放内存
+            esmx = null;
+            opts = null;
+            break;
+        case COMMAND.start:
+            throw new Error(
+                `Please use 'NODE_ENV=production node dist/index.js' to run the built program`
+            );
+        case COMMAND.build:
+            // 编译代码。
+            opts = await getSrcOptions();
+            esmx = new Esmx(opts);
+            exit(await esmx.init(COMMAND.build));
+            exit(await esmx.destroy());
+
+            if (typeof opts.postBuild === 'function') {
+                // 生产模式运行
+                esmx = new Esmx({
+                    ...opts,
+                    server: undefined
+                });
+                exit(await esmx.init(COMMAND.start));
+                exit(await esmx.postBuild());
+            }
+
+            // 释放内存
+            esmx = null;
+            opts = null;
+            break;
+        case COMMAND.preview:
+            opts = await getSrcOptions();
+            // 编译代码
+            esmx = new Esmx(opts);
+            exit(await esmx.init(COMMAND.build));
+            exit(await esmx.destroy());
+
+            // 生产模式运行
+            esmx = new Esmx(opts);
+            exit(await esmx.init(COMMAND.start));
+            exit(await esmx.postBuild());
+
+            // 释放内存
+            esmx = null;
+            opts = null;
+            break;
+        default:
+            await import(path.resolve(process.cwd(), command));
+            break;
+    }
+}
+
+function exit(ok: boolean) {
+    if (!ok) {
+        process.exit(17);
+    }
+}
+
+// 支持 TS 文件不需要编写 .ts 后缀。
+module.register(fileURLToPath(import.meta.url), {
+    parentURL: import.meta.url
+});
+
+export function resolve(
+    specifier: string,
+    context: Record<string, any>,
+    nextResolve: Function
+) {
+    if (
+        context?.parentURL.endsWith('.ts') &&
+        specifier.startsWith('.') &&
+        !specifier.endsWith('.ts')
+    ) {
+        return nextResolve(specifier + '.ts', context);
+    }
+    return nextResolve(specifier, context);
+}

package/src/cli/index.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node --no-warnings --experimental-vm-modules --experimental-import-meta-resolve --experimental-strip-types
+
+import { cli } from './cli';
+
+cli(process.argv.slice(2)[0] || '');