@mirascript/mirascript 0.1.92 → 0.1.93

package/src/experimental-context.ts

@@ -0,0 +1,121 @@
+import { VmFunction, type VmFunctionLike, type VmFunctionOptionLike } from './vm/types/function.js';
+import { wrapEffect } from './vm/effects/wrap.js';
+import type { VmValue } from './vm/types/index.js';
+import { defineProperty } from './helpers/utils.js';
+
+/**
+ * ## 实验性执行上下文
+ * JS backend 可通过 `experimental-context` 显式启用可挂起的 Host Function。
+ * 生成的脚本仍是同步函数，运行时在异步操作完成后从入口重新执行，并复用已记录的 effect。
+ *
+ * ```ts
+ * import { compileSync, createVmContext, VmFunction } from '@mirascript/mirascript';
+ * import { runInContext } from '@mirascript/mirascript/experimental-context';
+ *
+ * const globals = createVmContext({
+ *   load: VmFunction.async(
+ *     async (id) => {
+ *       if (typeof id !== 'string') throw new TypeError('id must be a string');
+ *       // Host 实现显式转换外部结果，返回合法 VM 值。
+ *       return { id, value: 42 };
+ *     },
+ *     { name: 'load', summary: '加载数据' },
+ *   ),
+ * });
+ *
+ * runInContext(
+ *   compileSync('load("example").value'),
+ *   globals,
+ *   (value) => console.log(value),
+ *   (error) => console.error(error),
+ * );
+ * ```
+ *
+ * 实际导入实验入口后，现有 `VmFunction` 对象获得以下方法；也可使用
+ * `import '@mirascript/mirascript/experimental-context'` 仅安装扩展。
+ * `import type` 不会安装运行时方法。模块声明增强在包含该入口的整个 TypeScript 编译项目中生效。
+ *
+ * | 方法                            | 用途                          | 在执行上下文中的行 * 为                             |
+ * | ------------------------------- | ----------------------------- |  * ------------------------------------------------ |
+ * | `VmFunction.memo(fn, option?)`  | 随机数、时间、外部状态读取    | 每个逻辑调用缓存结果或异 * 常                       |
+ * | `VmFunction.once(fn, option?)`  | 输出等立即发生的副作用        | 每个逻辑调用只执行一次，缓存结果或异 * 常，不回滚   |
+ * | `VmFunction.async(fn, option?)` | 返回 PromiseLike 的 Host 操作 | 启动一次，等待完成，在原逻辑调用处返 * 回结果或抛错 |
+ *
+ * 三个方法都直接返回已包装的 `VmFunction`，`option` 与普通构造器一致。
+ * 输入参数遵循 `VmFunctionLike`，包含缺省参数的 `undefined`；返回值或异步完成值必须为
+ * `VmAny | void`。三个方法均为泛型函数，像普通 `VmFunction` 一样保留输入函数的类型；
+ * `async` 保留参数与 `this` 类型，将 PromiseLike 的完成值作为同步返回值。
+ * 包装器不转换普通 JS 对象，调用方自行检查或断言 VM 参数与脚本结果。
+ *
+ * `runInContext(script, globals, onDone, onError)` 接受 `VmScript` 和
+ * `VmContext | null | undefined`，返回 `void`。结果固定为 `VmValue`，错误为 `unknown`。
+ * 无挂起时，完成或错误回调在当前调用栈中执行；挂起后，通过微任务恢复执行。
+ * 回调只通知一次，并在退出执行上下文后调用。回调自身抛错不会转交另一个回调；
+ * 同步时直接传播，异步时作为微任务异常抛出。
+ *
+ * 普通 `script(globals)` 保持同步，不创建 effect journal。
+ * `memo/once` 在上下文外直接执行，`async` 则在启动 Host 实现之前抛出 `AsyncRequiredError`。
+ * 实验入口同时导出 `ReplayMismatchError` 和 `ContextReentrancyError`。
+ *
+ * 内置 `random`、时间转换函数未传日期或传入 `nil` 时的当前时间读取，以及
+ * `debug_print`、`panic` 的输出部分已接入 effect 管理。日志沿用原有异步输出时序，
+ * 完成回调不等待日志输出。Checkpoint 超时仅约束每轮同步执行，不包括异步等待。
+ *
+ * ### Replay 条件与限制
+ *
+ * - 包装函数应在执行入口之外创建，确保每次 replay 使用相同的函数身份。
+ * - 缓存按调用顺序记录，不按参数去重；循环中的同一函数可有多个独立逻辑调用。
+ * - 未包装的函数、globals 查询和外部对象读取必须满足 replay 条件。运行时不快照 globals、
+ *   拦截 getter 或外部对象写入，也不管理未声明的副作用。
+ * - 结果按引用缓存，不拷贝或冻结。不要在运行期间修改缓存对象或影响控制流的外部状态。
+ * - 函数身份或调用序列长度变化会报错，但不会比较参数，不能检测所有 replay 分歧。
+ * - 支持独立执行交错等待；拒绝执行中的嵌套 `runInContext`，以及被管理 Host 实现同步调用
+ *   其他 effect。Host 实现在 `await` 后回调脚本执行 effect 不受支持。
+ * - 不要捕获并吞掉运行时控制信号后继续产生副作用。已记录的挂起或致命契约错误不会因此消失。
+ * - 不提供取消、事务、deferred commit 或跨安装副本的 context 互操作；Rust/Python backend 不变。
+ */
+
+/**
+ * 异步 Mirascript 函数签名
+ * @see {@link VmFunctionLike}
+ */
+type VmAsyncFunctionLike = (
+    this: void,
+    ...args: ReadonlyArray<VmValue | undefined>
+) => PromiseLike<ReturnType<VmFunctionLike>> | ReturnType<VmFunctionLike>;
+
+/** 保留异步函数的参数类型，将完成值作为同步返回值 */
+type ResumedFunction<T extends VmAsyncFunctionLike> = T extends (...args: infer A extends readonly unknown[]) => unknown
+    ? (this: void, ...args: A) => Awaited<ReturnType<T>>
+    : never;
+
+declare module './vm/types/function.js' {
+    namespace VmFunction {
+        /** 创建读取函数，每次逻辑调用缓存返回值或异常 */
+        function memo<T extends VmFunctionLike>(fn: T, option?: VmFunctionOptionLike<T>): VmFunction<T>;
+        /** 创建副作用函数，每次逻辑调用最多执行一次，不支持回滚 */
+        function once<T extends VmFunctionLike>(fn: T, option?: VmFunctionOptionLike<T>): VmFunction<T>;
+        /** 创建可挂起的异步函数，需要通过 runInContext 执行 */
+        function async<T extends VmAsyncFunctionLike>(
+            fn: T,
+            option?: VmFunctionOptionLike<ResumedFunction<T>>,
+        ): VmFunction<ResumedFunction<T>>;
+    }
+}
+
+/** 创建 effect 函数，已标记的 Mirascript 函数也需要重新包装 */
+function createEffectWrapper(kind: 'memo' | 'once' | 'async') {
+    return (fn: VmFunctionLike | VmAsyncFunctionLike, option?: VmFunctionOptionLike) => {
+        if (typeof fn != 'function') throw new TypeError('Invalid function');
+        const wrapped = wrapEffect<ReadonlyArray<VmValue | undefined>, ReturnType<VmFunctionLike>>(kind, fn);
+        defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+        return VmFunction(wrapped, option);
+    };
+}
+
+defineProperty(VmFunction, 'memo', { value: createEffectWrapper('memo') });
+defineProperty(VmFunction, 'once', { value: createEffectWrapper('once') });
+defineProperty(VmFunction, 'async', { value: createEffectWrapper('async') });
+
+export { runInContext } from './vm/effects/run.js';
+export { AsyncRequiredError, ReplayMismatchError, ContextReentrancyError } from './vm/effects/state.js';

package/src/helpers/convert/boolean.ts

@@ -1,6 +1,6 @@
 import type { VmAny } from '../../vm/index.js';
 import { VmError } from '../error.js';
-import { display } from '../serialize.js';
+import { display } from '../serialize/display.js';
 
 /** 转换为 boolean */
 export function toBoolean<F = undefined>(value: VmAny, fallback?: F): boolean | Exclude<F, undefined> {

package/src/helpers/convert/number.ts

@@ -1,6 +1,6 @@
 import type { VmAny } from '../../vm/index.js';
 import { VmError } from '../error.js';
-import { display } from '../serialize.js';
+import { display } from '../serialize/display.js';
 import { NegativeInfinity, NotNumber, PositiveInfinity } from '../utils.js';
 
 const parseInt = (value: string, radix: number): number => Number.parseInt(value.slice(2), radix);

package/src/helpers/convert/string.ts

@@ -1,17 +1,11 @@
 import type { VmAny, VmRecord } from '../../vm/index.js';
+import { rethrowControl } from '../../vm/effects/state.js';
 import { isVmArray, isVmWrapper } from '../types/index.js';
 import { VmError } from '../error.js';
-import { display, displayFunction } from '../serialize.js';
-import { keys, isNaN } from '../utils.js';
-
-/** 转换为 string */
-export function numberToString(value: number, minusZero: boolean): string {
-    if (isNaN(value)) return 'nan';
-    if (value === Infinity) return 'inf';
-    if (value === -Infinity) return '-inf';
-    if (minusZero && value === 0 && 1 / value < 0) return '-0';
-    return String(value);
-}
+import { keys } from '../utils.js';
+import { display } from '../serialize/display.js';
+import { numberToString } from '../serialize/simple.js';
+import { displayFunction } from '../serialize/display.js';
 
 /** 转换为 string */
 export function innerToString(value: VmAny, useBraces: boolean): string {
@@ -46,6 +40,7 @@ export function toString<F = undefined>(value: VmAny, fallback?: F): string | Ex
     try {
         return innerToString(value, false);
     } catch (ex) {
+        rethrowControl(ex);
         if (fallback === undefined) {
             const e = new VmError(`Failed to convert value to string: ${display(value)}`, '');
             e.cause = ex;

package/src/helpers/error.ts

@@ -1,4 +1,5 @@
 import type { VmAny } from '../vm/types/index.js';
+import { rethrowControl } from '../vm/effects/state.js';
 
 /**
  * VM 预期的错误
@@ -16,6 +17,7 @@ export class VmError extends Error {
 
     /** 从其他错误构造 */
     static from(prefix: string, error: unknown, recovered: VmAny): VmError {
+        rethrowControl(error);
         if (prefix) {
             if (prefix.endsWith(':')) {
                 prefix += ' ';

package/src/helpers/serialize/display.ts

@@ -0,0 +1,60 @@
+import type { VmAny, VmExtern, VmFunction, VmModule } from '../../vm/index.js';
+import { rethrowControl } from '../../vm/effects/state.js';
+import { getVmFunctionInfo } from '../types/index.js';
+import type { SerializeOptions } from './interface.js';
+import { DEFAULT_OPTIONS, mergeOptions, serializeImpl } from './serialize.js';
+
+/** 将 MiraScript 函数转化为 MiraScript 字符串 */
+export function displayFunction(value: VmFunction): string {
+    try {
+        const name = getVmFunctionInfo(value)?.fullName;
+        return name ? `<function ${name}>` : `<function>`;
+        /* c8 ignore next 4 */
+    } catch (error) {
+        rethrowControl(error);
+        return `<function>`;
+    }
+}
+
+/** 将 MiraScript 模块转化为 MiraScript 字符串 */
+export function displayModule(value: VmModule): string {
+    try {
+        return value.toString(true);
+        /* c8 ignore next 4 */
+    } catch (error) {
+        rethrowControl(error);
+        return `<module>`;
+    }
+}
+
+/** 将 MiraScript 外部值转化为 MiraScript 字符串 */
+export function displayExtern(value: VmExtern): string {
+    try {
+        const tag = `<extern ${value.tag}>`;
+        const rep = value.toString(true);
+        if (rep === tag || rep.length > 50) {
+            return tag;
+        }
+        return `${tag} ${rep}`;
+        /* c8 ignore next 4 */
+    } catch (error) {
+        rethrowControl(error);
+        return `<extern>`;
+    }
+}
+
+export const DISPLAY_OPTIONS = Object.freeze({
+    ...DEFAULT_OPTIONS,
+    maxDepth: 3,
+    serializeFunction: displayFunction,
+    serializeModule: displayModule,
+    serializeExtern: displayExtern,
+} satisfies SerializeOptions);
+
+/**
+ * 将 MiraScript 值转化为 MiraScript 字符串。
+ */
+export function display(value: VmAny, options?: Partial<SerializeOptions>): string {
+    const opt = mergeOptions(DISPLAY_OPTIONS, options);
+    return serializeImpl(value, 0, opt);
+}

package/src/helpers/serialize/index.ts

@@ -0,0 +1,4 @@
+export { serializeNil, serializeBoolean, serializeNumber } from './simple.js';
+export type { SerializeOptions } from './interface.js';
+export { serialize, serializeArray, serializeString, serializeRecord, serializeRecordKey } from './serialize.js';
+export { display as serializeForDisplay } from './display.js';

package/src/helpers/serialize/interface.ts

@@ -0,0 +1,33 @@
+import type { VmArray, VmExtern, VmFunction, VmModule, VmRecord } from '../../vm/index.js';
+
+/** 序列化设置 */
+export interface SerializeOptions {
+    /** 最大递归深度，超过该深度的值将被序列化为 `nil`，默认值为 128 */
+    maxDepth: number;
+    /** 序列化 nil 值 */
+    serializeNil: (options: SerializeOptions) => string;
+    /** 序列化布尔值 */
+    serializeBoolean: (value: boolean, options: SerializeOptions) => string;
+    /** 序列化数字 */
+    serializeNumber: (value: number, options: SerializeOptions) => string;
+    /** 序列化字符串 */
+    serializeString: (value: string, options: SerializeOptions) => string;
+    /** 序列化字符串引号 */
+    serializeStringQuote: (value: string, open: boolean, options: SerializeOptions) => string;
+    /** 序列化字符串转义序列 */
+    serializeStringEscape: (value: string, options: SerializeOptions) => string;
+    /** 序列化字符串常规内容 */
+    serializeStringContent: (value: string, options: SerializeOptions) => string;
+    /** 序列化数组 */
+    serializeArray: (value: VmArray, depth: number, options: SerializeOptions) => string;
+    /** 序列化记录 */
+    serializeRecord: (value: VmRecord, depth: number, options: SerializeOptions) => string;
+    /** 序列化属性名 */
+    serializePropName: (value: number | string, options: SerializeOptions) => string;
+    /** 序列化函数 */
+    serializeFunction: (value: VmFunction, options: SerializeOptions) => string;
+    /** 序列化模块 */
+    serializeModule: (value: VmModule, depth: number, options: SerializeOptions) => string;
+    /** 序列化外部值 */
+    serializeExtern: (value: VmExtern, depth: number, options: SerializeOptions) => string;
+}

package/src/helpers/serialize/serialize.ts

@@ -0,0 +1,200 @@
+import { REG_IDENTIFIER_FULL, REG_ORDINAL_FULL } from '@mirascript/constants';
+import type { VmArray, VmAny, VmRecord } from '../../vm/index.js';
+import { entries, hasOwn } from '../utils.js';
+import {
+    isVmArray,
+    isVmArrayLikeRecordByEntries,
+    isVmExtern,
+    isVmFunction,
+    isVmModule,
+    isVmRecord,
+} from '../types/index.js';
+import type { SerializeOptions } from './interface.js';
+import { serializeNil, serializeBoolean, serializeNumber } from './simple.js';
+import { serializeStringImpl } from './string.js';
+
+/**
+ * 将 MiraScript 字符串序列化为 MiraScript 字面量。
+ */
+export function serializeString(value: string, options?: Partial<SerializeOptions>): string {
+    return serializeStringImpl(value, getSerializeOptions(options));
+}
+
+/** 使用默认选项序列化属性名 */
+function serializeRecordKeyDefault(key: string): string {
+    if (REG_ORDINAL_FULL.test(key) || REG_IDENTIFIER_FULL.test(key)) {
+        return key;
+    }
+    return serializeStringImpl(key, DEFAULT_OPTIONS);
+}
+
+/** 序列化属性名 */
+function serializeRecordKeyOpt(value: string, options: Readonly<SerializeOptions>): string {
+    if (isDefaultOptions(options)) {
+        return serializeRecordKeyDefault(value);
+    }
+    if (REG_ORDINAL_FULL.test(value)) {
+        // 合法的数字属性名
+        return options.serializePropName(Number(value), options);
+    }
+    if (REG_IDENTIFIER_FULL.test(value)) {
+        // 合法的标识符
+        return options.serializePropName(value, options);
+    }
+    // 否则，序列化为字符串
+    return options.serializeString(value, options);
+}
+
+/** 序列化属性名 */
+export function serializeRecordKey(key: string, options?: Partial<SerializeOptions>): string {
+    if (isDefaultOptions(options)) {
+        return serializeRecordKeyDefault(key);
+    }
+    return serializeRecordKeyOpt(key, getSerializeOptions(options));
+}
+
+/** 序列化数组 */
+export function serializeArray(value: VmArray, depth: number, options: Readonly<SerializeOptions>): string {
+    if (depth > options.maxDepth) return `[]`;
+    if (value.length === 0) return '[]';
+    let result = '[';
+    for (let i = 0; i < value.length; i++) {
+        if (i > 0) result += ', ';
+        result += serializeImpl(value[i], depth, options);
+    }
+    result += ']';
+    return result;
+}
+
+// eslint-disable-next-line @typescript-eslint/unbound-method
+const { valueOf } = Object.prototype;
+/**
+ * 如果值有自定义的 valueOf 方法，调用它并返回结果，否则返回 undefined。
+ */
+function customValueOf(value: VmRecord): VmAny | undefined {
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const thisValueOf = value.valueOf;
+    if (typeof thisValueOf !== 'function' || thisValueOf === valueOf) {
+        return undefined;
+    }
+    const customValue = thisValueOf.call(value) as VmAny | undefined;
+    if (customValue === value) return undefined;
+    return customValue;
+}
+
+/** 序列化记录 */
+export function serializeRecord(value: VmRecord, depth: number, options: Readonly<SerializeOptions>): string {
+    const customValue = customValueOf(value);
+    if (customValue !== undefined) {
+        return serializeImpl(customValue, depth - 1, options);
+    }
+    if (depth > options.maxDepth) return `()`;
+    const e = entries(value);
+    if (e.length === 0) return '()';
+    if (e.length === 1) {
+        const [k, v] = e[0]!;
+        if (k === '0') {
+            return `(${serializeImpl(v, depth, options)},)`; // 单个元素数组
+        }
+        return `(${serializeRecordKeyOpt(k, options)}: ${serializeImpl(v, depth, options)})`;
+    }
+
+    const omitKey = isVmArrayLikeRecordByEntries(e);
+    let result = '(';
+    for (const [key, val] of e) {
+        if (result.length > 1) result += ', ';
+        if (omitKey) {
+            result += serializeImpl(val, depth, options);
+        } else {
+            result += `${serializeRecordKeyOpt(key, options)}: ${serializeImpl(val, depth, options)}`;
+        }
+    }
+    result += ')';
+    return result;
+}
+
+/** 序列化 */
+export function serializeImpl(value: VmAny | undefined, depth: number, options: Readonly<SerializeOptions>): string {
+    if (value == null) {
+        return options.serializeNil(options);
+    }
+    if (typeof value == 'boolean') {
+        return options.serializeBoolean(value, options);
+    }
+    if (typeof value == 'number') {
+        return options.serializeNumber(value, options);
+    }
+    if (typeof value == 'string') {
+        return options.serializeString(value, options);
+    }
+    if (isVmFunction(value)) {
+        return options.serializeFunction(value, options);
+    }
+    if (isVmModule(value)) {
+        return options.serializeModule(value, depth + 1, options);
+    }
+    if (isVmExtern(value)) {
+        return options.serializeExtern(value, depth + 1, options);
+    }
+    if (isVmArray(value)) {
+        return options.serializeArray(value, depth + 1, options);
+    }
+    if (isVmRecord(value)) {
+        return options.serializeRecord(value, depth + 1, options);
+    }
+    // 不支持序列化的值
+    value satisfies never;
+    return options.serializeNil(options);
+}
+
+/**
+ * 将 MiraScript 值序列化为 MiraScript 字面量字符串，非常量值默认转换为 `nil`。
+ */
+export function serialize(value: VmAny, options?: Partial<SerializeOptions>): string {
+    return serializeImpl(value, 0, getSerializeOptions(options));
+}
+
+/** 是否为默认选项 */
+function isDefaultOptions(options: Partial<SerializeOptions> | undefined): boolean {
+    return options == null || options === DEFAULT_OPTIONS;
+}
+
+/** 合并选项 */
+export function mergeOptions(
+    base: Readonly<SerializeOptions>,
+    options: Partial<SerializeOptions> | null | undefined,
+): Readonly<SerializeOptions> {
+    if (options == null) return base;
+    let opt: SerializeOptions | null = null;
+    for (const key in options) {
+        if (!hasOwn(options, key) || !hasOwn(base, key)) continue;
+        const el = options[key as keyof SerializeOptions];
+        if (el == null) continue;
+        opt ??= { ...base };
+        opt[key as keyof SerializeOptions] = el as never;
+    }
+    return opt ? Object.freeze(opt) : base;
+}
+
+/** 获取选项 */
+function getSerializeOptions(options: Partial<SerializeOptions> | undefined): Readonly<SerializeOptions> {
+    if (isDefaultOptions(options)) return DEFAULT_OPTIONS;
+    return mergeOptions(DEFAULT_OPTIONS, options);
+}
+
+export const DEFAULT_OPTIONS = Object.freeze({
+    maxDepth: 128,
+    serializeNil,
+    serializeBoolean,
+    serializeNumber,
+    serializeString: serializeStringImpl,
+    serializeStringQuote: (value) => value,
+    serializeStringEscape: (value) => value,
+    serializeStringContent: (value) => value,
+    serializeArray,
+    serializeRecord,
+    serializePropName: String,
+    serializeFunction: serializeNil,
+    serializeModule: serializeNil,
+    serializeExtern: serializeNil,
+} satisfies SerializeOptions);

package/src/helpers/serialize/simple.ts

@@ -0,0 +1,25 @@
+import { isNaN } from '../utils.js';
+
+/** 序列化 nil 值 */
+export function serializeNil(): string {
+    return 'nil';
+}
+
+/** 序列化布尔值 */
+export function serializeBoolean(value: boolean): string {
+    return value ? 'true' : 'false';
+}
+
+/** 转换为 string */
+export function numberToString(value: number, minusZero: boolean): string {
+    if (isNaN(value)) return 'nan';
+    if (value === Infinity) return 'inf';
+    if (value === -Infinity) return '-inf';
+    if (minusZero && value === 0 && 1 / value < 0) return '-0';
+    return String(value);
+}
+
+/** 序列化数字 */
+export function serializeNumber(value: number): string {
+    return numberToString(value, true);
+}

package/src/helpers/serialize/string.ts

@@ -0,0 +1,91 @@
+import type { SerializeOptions } from './interface.js';
+
+/**
+ * 将 MiraScript 转义字符串序列化为 MiraScript 字面量。
+ */
+function serializeStringEscaped(escaped: string, options: Readonly<SerializeOptions>): string {
+    return options.serializeStringEscape('\\' + escaped, options);
+}
+
+/**
+ * 将 MiraScript 普通字符串序列化为 MiraScript 字面量。
+ */
+function serializeStringContent(value: string, options: Readonly<SerializeOptions>): string {
+    return options.serializeStringContent(value, options);
+}
+
+const STRING_QUOTE = `'`;
+const STRING_REG = new RegExp(String.raw`[${STRING_QUOTE}\\\$\p{C}\u2028\u2029]`, 'gu');
+const STRING_MARK = /^[\p{M}]$/u;
+
+/**
+ * 序列化为特殊字符
+ */
+function serializeSpecialChar(char: string, options: Readonly<SerializeOptions>): string {
+    if (char === STRING_QUOTE) {
+        return serializeStringEscaped(STRING_QUOTE, options);
+    } else if (char === '\0') {
+        return serializeStringEscaped(`0`, options);
+    } else if (char === '\n') {
+        return serializeStringEscaped(`n`, options);
+    } else if (char === '\r') {
+        return serializeStringEscaped(`r`, options);
+    } else if (char === '\t') {
+        return serializeStringEscaped(`t`, options);
+    } else if (char === '\b') {
+        return serializeStringEscaped(`b`, options);
+    } else if (char === '\f') {
+        return serializeStringEscaped(`f`, options);
+    } else if (char === '\v') {
+        return serializeStringEscaped(`v`, options);
+    } else if (char === '\\') {
+        return serializeStringEscaped(`\\`, options);
+    } else if (char === '$') {
+        return serializeStringEscaped(`$`, options);
+    } else {
+        const code = char.codePointAt(0)!;
+        if (code <= 0x7f) {
+            return serializeStringEscaped(`x${code.toString(16).padStart(2, '0')}`, options);
+        } else if (code >= 0xd800 && code <= 0xdfff) {
+            // 无效的代理对
+            return serializeStringContent('�', options);
+        } else {
+            return serializeStringEscaped(`u{${code.toString(16)}}`, options);
+        }
+    }
+}
+
+/**
+ * 将 MiraScript 字符串序列化为 MiraScript 字面量。
+ */
+export function serializeStringImpl(value: string, options: Readonly<SerializeOptions>): string {
+    const oq = options.serializeStringQuote(STRING_QUOTE, true, options);
+    const cq = options.serializeStringQuote(STRING_QUOTE, false, options);
+    if (value.length === 0) {
+        return oq + cq;
+    }
+
+    let ret = oq;
+    let lastIndex = 0;
+
+    // 当开头字符是 \p{M} 时，使用转义序列化
+    while (value.length > lastIndex) {
+        const cp = value.codePointAt(lastIndex)!;
+        const ch = String.fromCodePoint(cp);
+        if (!STRING_MARK.test(ch)) break;
+        ret += serializeStringEscaped(`u{${cp.toString(16)}}`, options);
+        lastIndex += ch.length;
+    }
+
+    // 序列化字符串内容，遇到特殊字符时使用转义序列化
+    STRING_REG.lastIndex = lastIndex;
+    let match: RegExpExecArray | null;
+    while ((match = STRING_REG.exec(value)) !== null) {
+        ret += serializeStringContent(value.slice(lastIndex, match.index), options);
+        lastIndex = STRING_REG.lastIndex;
+        ret += serializeSpecialChar(match[0], options);
+    }
+    ret += serializeStringContent(value.slice(lastIndex), options);
+    ret += cq;
+    return ret;
+}

package/src/helpers/utils.ts

@@ -39,12 +39,13 @@ const SPECIAL_KEYS = new Set(getOwnPropertyNames(Object.prototype));
  * Set property on an vm record.
  */
 export const setRecord = (obj: Record<string, VmConst | undefined>, key: string, value: VmConst | undefined): void => {
+    value ??= null;
     if (!SPECIAL_KEYS.has(key)) {
-        obj[key] = value ?? null;
+        obj[key] = value;
     } else {
         defineProperty(obj, key, {
             __proto__: null,
-            value: value ?? null,
+            value,
             configurable: true,
             writable: true,
             enumerable: true,
@@ -59,3 +60,11 @@ export const getRecord = (obj: VmRecord, key: string): VmConst | undefined => {
     if (!hasOwnEnumerable(obj, key)) return undefined;
     return obj[key] ?? null;
 };
+
+/**
+ * Checks if a value is Promise-like (i.e., has a `then` method).
+ */
+export const isPromiseLike = (value: unknown): value is PromiseLike<unknown> => {
+    if (value == null || typeof value != 'object') return false;
+    return typeof (value as PromiseLike<unknown>).then == 'function';
+};

package/src/index.ts

@@ -1,5 +1,5 @@
 import './compiler/load-module.js';
 
-export { serialize } from './helpers/serialize.js';
+export { serialize } from './helpers/serialize/index.js';
 export * from './compiler/index.js';
 export * from './vm/index.js';

package/src/subtle.ts

@@ -6,7 +6,7 @@ export * as convert from './helpers/convert/index.js';
 export { DefaultVmContext } from './vm/types/context.js';
 export * as operations from './vm/operations/index.js';
 export {
-    display as serializeForDisplay,
+    serializeForDisplay,
     serialize,
     serializeNil,
     serializeBoolean,
@@ -16,7 +16,7 @@ export {
     serializeArray,
     serializeRecord,
     type SerializeOptions,
-} from './helpers/serialize.js';
+} from './helpers/serialize/index.js';
 export { lib, type Lib, type VmLibOption } from './vm/lib/index.js';
 export * from './compiler/diagnostic.js';
 export { compileVerbose } from './compiler/verbose.js';