@mirascript/mirascript 0.1.15 → 0.1.17

package/src/compiler/index.ts

@@ -1,24 +1,24 @@
 import { loadModule } from '@mirascript/bindings';
-import type { VmScript } from '../vm/index.js';
 import type { ScriptInput, TranspileOptions } from './types.js';
-import { emit } from './emit.js';
-import { createScript } from './create-script.js';
+import { emit } from './emit/index.js';
+import { createScript, type VmScript } from './create-script.js';
 import { compileFast } from './compile-fast.js';
-import { DiagnosticCode, formatDiagnostic, parseDiagnostics } from './diagnostic.js';
+import { DiagnosticCode, formatDiagnostics, parseDiagnostics } from './diagnostic.js';
 import { generateBytecode, generateBytecodeSync } from './generate-bytecode.js';
 import { compileWorker } from './worker-manager.js';
 await loadModule();
 
 export { generateBytecode, generateBytecodeSync };
-export type { TranspileOptions, ScriptInput, InputMode } from './types.js';
+export * from './types.js';
+export type { VmScript };
 
 // 目前编译速度约 2000kB/s
 const WORKER_MIN_LEN = typeof Worker != 'function' ? Number.MAX_VALUE : 1024;
 
 /** 报告编译错误 */
-function reportDiagnostic(source: ScriptInput, diagnostics: Uint32Array): never {
+function reportDiagnostic(source: ScriptInput, diagnostics: Uint32Array, fileName: string | undefined): never {
     const parsed = parseDiagnostics(source, diagnostics);
-    const messages = parsed.errors.map(formatDiagnostic);
+    const messages = formatDiagnostics(parsed.errors, source, fileName);
     throw new Error(`Failed to compile:\n${messages.join('\n')}`);
 }
 
@@ -31,7 +31,7 @@ export function emitScript(
     options: TranspileOptions,
 ): VmScript {
     if (!code) {
-        reportDiagnostic(source, diagnostics);
+        reportDiagnostic(source, diagnostics, options.fileName);
     }
     const sourcemaps = options.sourceMap
         ? parseDiagnostics(source, diagnostics, (c) => c === DiagnosticCode.SourceMap).sourcemaps
@@ -59,7 +59,7 @@ export async function compile(this: void, source: ScriptInput, options: Transpil
     }
     const [target, diagnostics] = await compileWorker(source, options);
     if (target == null) {
-        reportDiagnostic(source, diagnostics);
+        reportDiagnostic(source, diagnostics, options.fileName);
     }
     return createScript(source, target);
 }

package/src/compiler/worker.ts

@@ -1,5 +1,5 @@
 import type { ScriptInput, TranspileOptions } from './types.js';
-import { emit } from './emit.js';
+import { emit } from './emit/index.js';
 import { generateBytecode } from './generate-bytecode.js';
 import { DiagnosticCode, parseDiagnostics } from './diagnostic.js';
 

package/src/helpers/constants.ts

@@ -6,3 +6,15 @@ export const REG_HEX = /0[xX][a-fA-F0-9_]*[a-fA-F0-9]/;
 export const REG_OCT = /0[oO][0-7_]*[0-7]/;
 export const REG_BIN = /0[bB][01_]*[01]/;
 export const REG_NUMBER = /\d[\d_]*(?:\.[\d_]+)?(?:[eE][+-]?[\d_]*\d)?/u;
+export const VM_ARRAY_MAX_LENGTH = 2 ** 31 - 1;
+
+export const kVmScript = Symbol.for('mirascript.vm.script');
+export const kVmFunction = Symbol.for('mirascript.vm.function');
+export const kVmFunctionProxy = Symbol.for('mirascript.vm.function.proxy');
+export const kVmContext = Symbol.for('mirascript.vm.context');
+export const kVmExtern = Symbol.for('mirascript.vm.extern');
+export const kVmModule = Symbol.for('mirascript.vm.module');
+export const kVmWrapper = Symbol.for('mirascript.vm.wrapper');
+
+export const VM_SCRIPT_NAME = `<script_root>`;
+export const VM_FUNCTION_ANONYMOUS_NAME = `<anonymous>`;

package/src/helpers/convert/index.ts

@@ -0,0 +1,4 @@
+export { toNumber } from './to-number.js';
+export { toString } from './to-string.js';
+export { toFormat } from './to-format.js';
+export { toBoolean } from './to-boolean.js';

package/src/helpers/convert/to-boolean.ts

@@ -0,0 +1,12 @@
+import type { VmAny } from '../../vm/index.js';
+import { VmError } from '../error.js';
+import { display } from '../serialize.js';
+
+/** 转换为 boolean */
+export function toBoolean<F = undefined>(value: VmAny, fallback?: F): boolean | Exclude<F, undefined> {
+    if (typeof value === 'boolean') return value;
+    if (fallback === undefined) {
+        throw new VmError(`Failed to convert value to boolean: ${display(value)}`, false);
+    }
+    return fallback as Exclude<F, undefined>;
+}

package/src/helpers/convert/to-format.ts

@@ -0,0 +1,37 @@
+import type { VmAny } from '../../vm/index.js';
+import { isFinite } from '../utils.js';
+import { toString } from './to-string.js';
+
+/** 渲染数字 */
+function formatNumber(value: number): string {
+    if (!isFinite(value)) return toString(value, undefined as never);
+    if (value === 0) return '0';
+    const s = value.toString();
+    let ps;
+    const abs = Math.abs(value);
+    if (abs >= 1000 || abs < 0.001) {
+        const ps1 = value.toExponential();
+        const ps2 = value.toExponential(5);
+        ps = ps1.length < ps2.length ? ps1 : ps2;
+    } else {
+        ps = value.toPrecision(6);
+    }
+    return ps.length < s.length ? ps : s;
+}
+
+/** 格式化为 string */
+export function toFormat(value: VmAny, format: string | null | undefined): string {
+    const f = format == null ? '' : format.trim();
+
+    if (typeof value == 'number') {
+        if (/^\.\d+$/.test(f)) {
+            let digits = Math.trunc(Number(f.slice(1)));
+            if (!(digits <= 100)) digits = 100;
+            return value.toFixed(digits);
+        } else {
+            return formatNumber(value);
+        }
+    }
+
+    return toString(value, undefined as never);
+}

package/src/helpers/convert/to-number.ts

@@ -0,0 +1,35 @@
+import type { VmAny } from '../../vm/index.js';
+import { VmError } from '../error.js';
+import { display } from '../serialize.js';
+import { isNaN } from '../utils.js';
+const { POSITIVE_INFINITY, NEGATIVE_INFINITY } = Number;
+
+/** 转换为 number */
+export function toNumber<F = undefined>(value: VmAny, fallback?: F): number | Exclude<F, undefined> {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value == 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (typeof value == 'string') {
+        value = value.trim();
+        if (value !== '') {
+            if (value === 'inf' || value === '+inf' || value === 'Infinity' || value === '+Infinity') {
+                return POSITIVE_INFINITY;
+            }
+            if (value === '-inf' || value === '-Infinity') {
+                return NEGATIVE_INFINITY;
+            }
+            if (value === 'nan' || value === 'NaN') {
+                return Number.NaN;
+            }
+            const num = Number(value);
+            if (!isNaN(num)) return num;
+        }
+    }
+    if (fallback === undefined) {
+        throw new VmError(`Failed to convert value to number: ${display(value)}`, Number.NaN);
+    }
+    return fallback as Exclude<F, undefined>;
+}

package/src/helpers/convert/to-string.ts

@@ -0,0 +1,55 @@
+import type { VmAny, VmRecord } from '../../vm/index.js';
+import { isVmArray, isVmWrapper } from '../types.js';
+import { VmError } from '../error.js';
+import { display, displayFunction } from '../serialize.js';
+import { keys, isNaN } from '../utils.js';
+
+/** 转换为 string */
+function numberToString(value: number): string {
+    if (isNaN(value)) return 'nan';
+    if (value === Infinity) return 'inf';
+    if (value === -Infinity) return '-inf';
+    return String(value);
+}
+
+/** 转换为 string */
+export function innerToString(value: VmAny, useBraces: boolean): string {
+    if (value == null) return 'nil';
+    if (typeof value == 'number') return numberToString(value);
+    if (typeof value == 'string' || typeof value == 'boolean') return String(value);
+    if (typeof value == 'function') return displayFunction(value);
+    if (isVmWrapper(value)) return value.toString(useBraces);
+    if (isVmArray(value)) {
+        const strings: string[] = [];
+        for (const item of value) {
+            strings.push(innerToString(item, true));
+        }
+        // 在 join 过程中会自动把 null/undefined 和 empty slot 转为 ''
+        // 与 innerToString 行为不一致
+        const results = strings.join(', ');
+        if (!useBraces) return results;
+        return `[${results}]`;
+    } else {
+        const entries = keys(value satisfies VmRecord)
+            .map((key) => `${key}: ${innerToString(value[key], true)}`)
+            .join(', ');
+        if (!useBraces) return entries;
+        return `(${entries})`;
+    }
+}
+
+/** 转换为 string */
+export function toString<F = undefined>(value: VmAny, fallback?: F): string | Exclude<F, undefined> {
+    if (typeof value === 'string') return value;
+    if (value == null) return '';
+    try {
+        return innerToString(value, false);
+    } catch (ex) {
+        if (fallback === undefined) {
+            const e = new VmError(`Failed to convert value to string: ${display(value)}`, '');
+            e.cause = ex;
+            throw e;
+        }
+        return fallback as Exclude<F, undefined>;
+    }
+}

package/src/{vm → helpers}/error.ts

@@ -1,4 +1,4 @@
-import type { VmAny } from './types/index.js';
+import type { VmAny } from '../vm/types/index.js';
 
 /**
  * VM 预期的错误

package/src/helpers/serialize.ts

@@ -1,19 +1,16 @@
+import type { VmArray, VmExtern, VmFunction, VmModule, VmAny, VmRecord } from '../vm/index.js';
+import { REG_IDENTIFIER, REG_ORDINAL } from './constants.js';
+import { entries, hasOwn, isFinite, isNaN } from '../helpers/utils.js';
 import {
+    getVmFunctionInfo,
     isVmArray,
-    isVmRecord,
-    type VmArray,
-    type VmExtern,
-    type VmFunction,
-    type VmModule,
-    type VmAny,
-    type VmRecord,
+    isVmArrayLikeRecordByEntires,
+    isVmExtern,
     isVmFunction,
     isVmModule,
-    isVmExtern,
-    isVmArrayLikeRecordByEntires,
-} from '../vm/index.js';
-import { REG_IDENTIFIER, REG_ORDINAL } from './constants.js';
-import { entries, hasOwn, isFinite, isNaN } from '../helpers/utils.js';
+    isVmRecord,
+} from './types.js';
+import type { VmWrapper } from '../vm/types/wrapper.js';
 
 const REG_IDENTIFIER_FULL = new RegExp(`^${REG_IDENTIFIER.source}$`, REG_IDENTIFIER.flags);
 const REG_ORDINAL_FULL = new RegExp(`^${REG_ORDINAL.source}$`, REG_ORDINAL.flags);
@@ -72,24 +69,33 @@ function isDefaultOptions(options: Partial<SerializeOptions> | undefined): boole
     return options == null || options === DEFAULT_OPTIONS;
 }
 
-/** 获取选项 */
-function getSerializeOptions(options: Partial<SerializeOptions> | undefined): SerializeOptions {
-    if (isDefaultOptions(options)) return DEFAULT_OPTIONS;
+/** 合并选项 */
+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(DEFAULT_OPTIONS, key)) continue;
+        if (!hasOwn(options, key) || !hasOwn(base, key)) continue;
         const el = options[key as keyof SerializeOptions];
         if (el == null) continue;
-        opt ??= { ...DEFAULT_OPTIONS };
+        opt ??= { ...base };
         opt[key as keyof SerializeOptions] = el as never;
     }
-    return opt ? Object.freeze(opt) : DEFAULT_OPTIONS;
+    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);
 }
 
 /**
  * 将 MiraScript 字符串序列化为 MiraScript 字面量。
  */
-function serializeStringImpl(value: string, options: SerializeOptions): string {
+function serializeStringImpl(value: string, options: Readonly<SerializeOptions>): string {
     if (!/[\p{C}'"`$\\]/u.test(value)) {
         // 不包含特殊字符
         const oq = options.serializeStringQuote(`'`, true, options);
@@ -153,7 +159,7 @@ function serializeRecordKeyDefault(key: string): string {
 }
 
 /** 序列化属性名 */
-function serializeRecordKeyOpt(value: string, options: SerializeOptions): string {
+function serializeRecordKeyOpt(value: string, options: Readonly<SerializeOptions>): string {
     if (isDefaultOptions(options)) {
         return serializeRecordKeyDefault(value);
     }
@@ -199,7 +205,7 @@ export function serializeNumber(value: number): string {
 }
 
 /** 序列化数组 */
-export function serializeArray(value: VmArray, depth: number, options: SerializeOptions): string {
+export function serializeArray(value: VmArray, depth: number, options: Readonly<SerializeOptions>): string {
     if (depth > options.maxDepth) return `[]`;
     if (value.length === 0) return '[]';
     let str = '[';
@@ -228,7 +234,7 @@ function customValueOf(value: VmRecord): VmAny | undefined {
 }
 
 /** 序列化记录 */
-export function serializeRecord(value: VmRecord, depth: number, options: SerializeOptions): string {
+export function serializeRecord(value: VmRecord, depth: number, options: Readonly<SerializeOptions>): string {
     const customValue = customValueOf(value);
     if (customValue !== undefined) {
         return serializeImpl(customValue, depth - 1, options);
@@ -259,7 +265,7 @@ export function serializeRecord(value: VmRecord, depth: number, options: Seriali
 }
 
 /** 序列化 */
-function serializeImpl(value: VmAny | undefined, depth: number, options: SerializeOptions): string {
+function serializeImpl(value: VmAny | undefined, depth: number, options: Readonly<SerializeOptions>): string {
     if (value == null) {
         return options.serializeNil(options);
     }
@@ -293,8 +299,50 @@ function serializeImpl(value: VmAny | undefined, depth: number, options: Seriali
 }
 
 /**
- * 将 MiraScript 值序列化为 MiraScript 字面量字符串，非常量值将被转换为 `nil`。
+ * 将 MiraScript 值序列化为 MiraScript 字面量字符串，非常量值默认转换为 `nil`。
  */
 export function serialize(value: VmAny, options?: Partial<SerializeOptions>): string {
     return serializeImpl(value, 0, getSerializeOptions(options));
 }
+
+/** 将 MiraScript function 转化为 MiraScript 字符串 */
+export function displayFunction(value: VmFunction): string {
+    try {
+        const name = getVmFunctionInfo(value)?.fullName;
+        return name ? `<function ${name}>` : `<function>`;
+        /* c8 ignore next 3 */
+    } catch {
+        return `<function>`;
+    }
+}
+/** 将 MiraScript module 转化为 MiraScript 字符串 */
+export function displayWrapper(value: VmWrapper<object>, useBraces: boolean, fallback: string): string {
+    try {
+        return value.toString(useBraces);
+    } catch {
+        return fallback;
+    }
+}
+const DISPLAY_OPTIONS = Object.freeze({
+    maxDepth: 3,
+    serializeNil,
+    serializeBoolean,
+    serializeNumber,
+    serializeString: serializeStringImpl,
+    serializeStringQuote: (value) => value,
+    serializeStringEscape: (value) => value,
+    serializeStringContent: (value) => value,
+    serializeArray,
+    serializeRecord,
+    serializePropName: String,
+    serializeFunction: displayFunction,
+    serializeModule: (value) => displayWrapper(value, true, '<module>'),
+    serializeExtern: (value) => displayWrapper(value, true, '<extern>'),
+} 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/types.ts

@@ -0,0 +1,267 @@
+import type { VmScript } from '../compiler/index.js';
+import type {
+    VmAny,
+    VmArray,
+    VmConst,
+    VmContext,
+    VmExtern,
+    VmFunction,
+    VmFunctionInfo,
+    VmFunctionLike,
+    VmImmutable,
+    VmModule,
+    VmPrimitive,
+    VmRecord,
+    VmValue,
+} from '../vm/types/index.js';
+import type { VmWrapper } from '../vm/types/wrapper.js';
+import {
+    kVmContext,
+    kVmExtern,
+    kVmFunction,
+    kVmModule,
+    kVmScript,
+    kVmWrapper,
+    VM_ARRAY_MAX_LENGTH,
+} from './constants.js';
+import { getPrototypeOf, isArray, keys, values } from './utils.js';
+
+/** 检查是否为 Mirascript 脚本 */
+export function isVmScript(value: unknown): value is VmScript {
+    return typeof value === 'function' && kVmScript in value;
+}
+
+/** 检查是否为执行上下文 */
+export function isVmContext(context: unknown): context is VmContext {
+    return context != null && typeof context == 'object' && kVmContext in context;
+}
+/** 检查是否为 Mirascript 函数 */
+export function isVmFunction<T extends VmFunctionLike>(value: unknown): value is VmFunction<T> {
+    return typeof value == 'function' && kVmFunction in value;
+}
+/** 检查是否为 Mirascript 函数，并获取其信息 */
+export function getVmFunctionInfo(value: unknown): VmFunctionInfo | undefined {
+    if (typeof value != 'function') return undefined;
+    return (value as VmFunction)[kVmFunction];
+}
+/** 检查值是否为 MiraScript 包装器 */
+export function isVmWrapper<T extends object>(value: unknown): value is VmWrapper<T> {
+    return value != null && typeof value == 'object' && kVmWrapper in value;
+}
+/** 检查值是否为 Mirascript 模块 */
+export function isVmModule<T extends Record<string, VmImmutable>>(value: unknown): value is VmModule<T> {
+    return value != null && typeof value == 'object' && kVmModule in value;
+}
+/** 检查值是否为 Mirascript 外部值 */
+export function isVmExtern<T extends object>(value: unknown): value is VmExtern<T> {
+    return value != null && typeof value == 'object' && kVmExtern in value;
+}
+
+/** 检查值是否为 Mirascript 可调用值 */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function isVmCallable<E extends Function, F extends VmFunctionLike>(
+    value: unknown,
+): value is VmFunction<F> | VmExtern<E> {
+    return isVmFunction<F>(value) || (isVmExtern<E>(value) && typeof value.value == 'function');
+}
+
+/** 检查值是否为 Mirascript 原始值 */
+export function isVmPrimitive(value: unknown): value is VmPrimitive {
+    if (value === null || typeof value == 'number' || typeof value == 'string' || typeof value == 'boolean') {
+        value as VmPrimitive satisfies typeof value;
+        value satisfies VmPrimitive;
+        return true;
+    }
+    return false;
+}
+
+/** 检查值是否为 Mirascript 数组 */
+export function isVmArray(value: VmAny): value is VmArray {
+    if (!isArray(value)) return false;
+    value as VmArray satisfies VmArray;
+    return true;
+}
+
+/** 检查值是否为 Mirascript 记录 */
+export function isVmRecord(value: VmAny): value is VmRecord {
+    if (value == null || typeof value !== 'object') return false;
+    if (isVmWrapper(value)) return false;
+    if (isVmArray(value)) return false;
+    value satisfies VmRecord;
+    return true;
+}
+
+/** 检查是否为仅包含从 0 开始的连续数字键的 MiraScript 记录 */
+export function isVmArrayLikeRecordByEntires(entries: ReadonlyArray<readonly [string, unknown]>): boolean {
+    const { length } = entries;
+    if (length === 0) return true;
+    if (length > VM_ARRAY_MAX_LENGTH) return false;
+    const firstKey = entries[0]![0];
+    if (firstKey !== '0') return false;
+    const lastKey = entries[length - 1]![0];
+    if (lastKey !== String(length - 1)) return false;
+    return true;
+}
+
+/** 检查是否为仅包含从 0 开始的连续数字键的 MiraScript 记录 */
+export function isVmArrayLikeRecordByKeys(keys: readonly string[]): boolean {
+    const { length } = keys;
+    if (length === 0) return true;
+    if (length > VM_ARRAY_MAX_LENGTH) return false;
+    const firstKey = keys[0]!;
+    if (firstKey !== '0') return false;
+    const lastKey = keys[length - 1]!;
+    if (lastKey !== String(length - 1)) return false;
+    return true;
+}
+
+/** 检查是否为仅包含从 0 开始的连续数字键的 MiraScript 记录 */
+export function isVmArrayLikeRecord(value: VmRecord): boolean {
+    return isVmArrayLikeRecordByKeys(keys(value));
+}
+
+const MAX_DEPTH = 16;
+/**
+ * 检查是否为 Mirascript 数组
+ */
+function isVmArrayDeep(value: readonly unknown[], depth: number): value is VmArray {
+    // VmArray 应为普通数组
+    // Array.prototype
+    const proto1: unknown = getPrototypeOf(value);
+    if (!isArray(proto1)) return false;
+    if (!depth) return true;
+    return value.every((item) => isVmConstInner(item, depth));
+}
+/**
+ * 检查是否为 Mirascript 记录
+ */
+function isVmRecordDeep(value: object, depth: number): value is VmRecord {
+    // VmRecord 应为普通对象或空原型对象
+    let isRecord;
+    // Object.prototype
+    const proto1: unknown = getPrototypeOf(value);
+    if (proto1 == null) {
+        isRecord = true;
+    } else {
+        // null
+        const proto2: unknown = getPrototypeOf(proto1);
+        if (proto2 != null) {
+            isRecord = false;
+        } else {
+            isRecord = 'hasOwnProperty' in value;
+        }
+    }
+    if (!isRecord) return false;
+    if (!depth) return true;
+    return values(value).every((value) => isVmConstInner(value, depth));
+}
+/**
+ * 检查是否为 Mirascript 值语义值
+ */
+function isVmConstInner(value: unknown, depth: number): value is VmConst {
+    if (depth++ >= MAX_DEPTH) return false;
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'undefined': // undefined 在复合类型内部被视为 nil
+            return true;
+        case 'object':
+            if (value == null) return true;
+            if (isVmWrapper(value)) return false;
+            if (isArray(value)) {
+                return isVmArrayDeep(value, depth);
+            } else {
+                return isVmRecordDeep(value, depth);
+            }
+        case 'function':
+        case 'bigint':
+        case 'symbol':
+        default:
+            return false; // Other types are not valid
+    }
+}
+
+/**
+ * 检查是否为 Mirascript 值语义值
+ */
+export function isVmConst(value: VmAny): value is VmConst;
+/**
+ * 检查是否为 Mirascript 值语义值
+ */
+export function isVmConst(value: unknown, checkDeep: boolean): value is VmConst;
+/**
+ * 检查是否为 Mirascript 值语义值
+ */
+export function isVmConst(value: unknown, checkDeep = false): value is VmConst {
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return true;
+        case 'object':
+            if (value == null) return true;
+            if (isVmWrapper(value)) return false;
+            if (!checkDeep) {
+                if (isArray(value)) {
+                    return isVmArrayDeep(value, 0);
+                } else {
+                    return isVmRecordDeep(value, 0);
+                }
+            } else {
+                return isVmConstInner(value, 1);
+            }
+        case 'undefined':
+        case 'function':
+        case 'bigint':
+        case 'symbol':
+        default:
+            return false; // Other types are not valid
+    }
+}
+
+/**
+ * 检查是否为 Mirascript 不可变值
+ */
+export function isVmImmutable(value: VmAny): value is VmImmutable;
+/**
+ * 检查是否为 Mirascript 不可变值
+ */
+export function isVmImmutable(value: unknown, checkDeep: boolean): value is VmImmutable;
+/**
+ * 检查是否为 Mirascript 不可变值
+ */
+export function isVmImmutable(value: unknown, checkDeep = false): value is VmImmutable {
+    return isVmModule(value) || isVmFunction(value) || isVmConst(value, checkDeep);
+}
+
+/** 检查是否为 Mirascript 值 */
+export function isVmAny(value: unknown, checkDeep: boolean): value is VmAny {
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'undefined':
+            return true;
+        case 'object':
+            if (value == null) return true;
+            if (isVmWrapper(value)) return true;
+            return isVmConst(value, checkDeep);
+        case 'function':
+            return isVmFunction(value);
+        case 'bigint':
+        case 'symbol':
+        default:
+            return false; // Other types are not valid
+    }
+}
+
+/** 检查是否为 Mirascript 合法值 */
+export function isVmValue(value: VmAny): value is VmValue;
+/** 检查是否为 Mirascript 合法值 */
+export function isVmValue(value: unknown, checkDeep: boolean): value is VmValue;
+/** 检查是否为 Mirascript 合法值 */
+export function isVmValue(value: unknown, checkDeep = false): value is VmValue {
+    if (value === undefined) return false;
+    return isVmAny(value, checkDeep);
+}

package/src/subtle.ts

@@ -1,9 +1,11 @@
 import { getModule } from '@mirascript/bindings';
 
 export * as constants from './helpers/constants.js';
-export { VmSharedContext, DefaultVmContext } from './vm/types/context.js';
+export * as convert from './helpers/convert/index.js';
+export { DefaultVmContext } from './vm/types/context.js';
 export * as operations from './vm/operations.js';
 export {
+    display as serializeForDisplay,
     serialize,
     serializeNil,
     serializeBoolean,
@@ -14,7 +16,7 @@ export {
     serializeRecord,
     type SerializeOptions,
 } from './helpers/serialize.js';
-export { lib } from './vm/lib/_loader.js';
+export { lib } from './vm/lib/index.js';
 export * from './compiler/diagnostic.js';
 export { generateBytecode, generateBytecodeSync, emitScript } from './compiler/index.js';