@mirascript/mirascript 0.1.13 → 0.1.15

package/src/helpers/serialize.ts

@@ -10,9 +10,10 @@ import {
     isVmFunction,
     isVmModule,
     isVmExtern,
+    isVmArrayLikeRecordByEntires,
 } from '../vm/index.js';
 import { REG_IDENTIFIER, REG_ORDINAL } from './constants.js';
-import { entries, isFinite, isNaN } from '../helpers/utils.js';
+import { entries, hasOwn, isFinite, isNaN } from '../helpers/utils.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);
@@ -42,7 +43,7 @@ export interface SerializeOptions {
     /** 序列化记录 */
     serializeRecord: (value: VmRecord, depth: number, options: SerializeOptions) => string;
     /** 序列化属性名 */
-    serializePropName: (value: string | number, options: SerializeOptions) => string;
+    serializePropName: (value: number | string, options: SerializeOptions) => string;
     /** 序列化模块 */
     serializeModule: (value: VmModule, depth: number, options: SerializeOptions) => string;
     /** 序列化外部值 */
@@ -66,17 +67,23 @@ const DEFAULT_OPTIONS = Object.freeze({
     serializeExtern: serializeNil,
 } satisfies SerializeOptions);
 
+/** 是否为默认选项 */
+function isDefaultOptions(options: Partial<SerializeOptions> | undefined): boolean {
+    return options == null || options === DEFAULT_OPTIONS;
+}
+
 /** 获取选项 */
 function getSerializeOptions(options: Partial<SerializeOptions> | undefined): SerializeOptions {
-    if (options == null) return DEFAULT_OPTIONS;
-    const opt = { ...DEFAULT_OPTIONS };
+    if (isDefaultOptions(options)) return DEFAULT_OPTIONS;
+    let opt: SerializeOptions | null = null;
     for (const key in options) {
+        if (!hasOwn(options, key) || !hasOwn(DEFAULT_OPTIONS, key)) continue;
         const el = options[key as keyof SerializeOptions];
-        if (el != null) {
-            opt[key as keyof SerializeOptions] = el as never;
-        }
+        if (el == null) continue;
+        opt ??= { ...DEFAULT_OPTIONS };
+        opt[key as keyof SerializeOptions] = el as never;
     }
-    return Object.freeze(opt);
+    return opt ? Object.freeze(opt) : DEFAULT_OPTIONS;
 }
 
 /**
@@ -137,8 +144,19 @@ export function serializeString(value: string, options?: Partial<SerializeOption
     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 serializePropNameImpl(value: string, options: SerializeOptions): string {
+function serializeRecordKeyOpt(value: string, options: SerializeOptions): string {
+    if (isDefaultOptions(options)) {
+        return serializeRecordKeyDefault(value);
+    }
     if (REG_ORDINAL_FULL.test(value)) {
         // 合法的数字属性名
         return options.serializePropName(Number(value), options);
@@ -152,8 +170,11 @@ function serializePropNameImpl(value: string, options: SerializeOptions): string
 }
 
 /** 序列化属性名 */
-export function serializePropName(value: string, options?: Partial<SerializeOptions>): string {
-    return serializePropNameImpl(value, getSerializeOptions(options));
+export function serializeRecordKey(key: string, options?: Partial<SerializeOptions>): string {
+    if (isDefaultOptions(options)) {
+        return serializeRecordKeyDefault(key);
+    }
+    return serializeRecordKeyOpt(key, getSerializeOptions(options));
 }
 
 /** 序列化 nil 值 */
@@ -220,18 +241,17 @@ export function serializeRecord(value: VmRecord, depth: number, options: Seriali
         if (k === '0') {
             return `(${serializeImpl(v, depth, options)},)`; // 单个元素数组
         }
-        return `(${serializePropNameImpl(k, options)}: ${serializeImpl(v, depth, options)})`;
+        return `(${serializeRecordKeyOpt(k, options)}: ${serializeImpl(v, depth, options)})`;
     }
 
-    // 根据 ES 标准，数字 key 会按顺序枚举
-    const omitKey = e.length < 10 && e.every(([key], index) => key === String(index));
+    const omitKey = isVmArrayLikeRecordByEntires(e);
     let str = '(';
     for (const [key, val] of e) {
         if (str.length > 1) str += ', ';
         if (omitKey) {
             str += serializeImpl(val, depth, options);
         } else {
-            str += `${serializePropNameImpl(key, options)}: ${serializeImpl(val, depth, options)}`;
+            str += `${serializeRecordKeyOpt(key, options)}: ${serializeImpl(val, depth, options)}`;
         }
     }
     str += ')';

package/src/subtle.ts

@@ -9,7 +9,7 @@ export {
     serializeBoolean,
     serializeNumber,
     serializeString,
-    serializePropName,
+    serializeRecordKey,
     serializeArray,
     serializeRecord,
     type SerializeOptions,

package/src/vm/lib/_helpers.ts

@@ -30,7 +30,7 @@ export function throwError(message: string, recovered: VmAny | (() => VmAny)): n
 
 /** 抛出预期外类型异常 */
 export function throwUnexpectedTypeError(
-    name: string | number,
+    name: number | string,
     expected: string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
@@ -49,7 +49,7 @@ export function rethrowError(prefix: string, error: unknown, recovered: VmAny |
 
 /** 标记参数为必须项 */
 export function required<const T = VmValue>(
-    name: string | number,
+    name: number | string,
     value: T | undefined,
     recovered: VmAny | (() => VmAny),
 ): asserts value is T {
@@ -62,7 +62,7 @@ export function required<const T = VmValue>(
 
 /** 标记参数为数组 */
 export function expectArray(
-    name: string | number,
+    name: number | string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmArray {
@@ -74,7 +74,7 @@ export function expectArray(
 
 /** 标记参数为记录 */
 export function expectRecord(
-    name: string | number,
+    name: number | string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmRecord {
@@ -86,7 +86,7 @@ export function expectRecord(
 
 /** 标记参数为数组或记录 */
 export function expectArrayOrRecord(
-    name: string | number,
+    name: number | string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmArray | VmRecord {
@@ -98,7 +98,7 @@ export function expectArrayOrRecord(
 
 /** 标记参数为复合类型 */
 export function expectCompound(
-    name: string | number,
+    name: number | string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmArray | VmRecord | VmModule | VmExtern {
@@ -110,7 +110,7 @@ export function expectCompound(
 
 /** 标记参数为常量 */
 export function expectConst(
-    name: string | number,
+    name: number | string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmConst {
@@ -122,7 +122,7 @@ export function expectConst(
 
 /** 标记为可调用 */
 export function expectCallable(
-    name: string | number,
+    name: number | string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmFunction | VmExtern {

package/src/vm/lib/global/sequence/entries.ts

@@ -22,7 +22,7 @@ export const keys = VmLib(
         summary: '返回数组、记录、外部对象或模块的键列表',
         params: { data: '要获取键的数组、记录、外部对象或模块' },
         paramsType: { data: 'array | record | extern | module' },
-        returnsType: '(string | number)[]',
+        returnsType: 'number[] | string[]',
         examples: ['keys([10, 20]) // [0, 1]', 'keys((10, 20)) // ["0", "1"]'],
     },
 );
@@ -61,7 +61,7 @@ export const entries = VmLib(
         summary: '返回数组或记录的键值对列表',
         params: { data: '要获取键值对的数组或记录' },
         paramsType: { data: 'array | record' },
-        returnsType: '(string | number, any)[]',
+        returnsType: '(number, any)[] | (string, any)[]',
         examples: ['entries([1]) // [(0, 1)]', 'entries((a: 1)) // [("a", 1)]'],
     },
 );

package/src/vm/lib/global/sequence/find.ts

@@ -9,7 +9,7 @@ export const find = VmLib(
         expectArrayOrRecord('data', data, null);
         required('predicate', predicate, null);
         const p = isVmCallable(predicate)
-            ? (value: VmValue, key: string | number, data: VmValue) => {
+            ? (value: VmValue, key: number | string, data: VmValue) => {
                   const ret = $Call(predicate, [value, key, data]);
                   return $ToBoolean(ret);
               }
@@ -38,14 +38,14 @@ export const find = VmLib(
     {
         summary: '查找数组或记录中的键值对，返回第一个满足条件的键值对',
         params: {
-            data: '查的数组或记录',
+            data: '要查找的数组或记录',
             predicate: '用于测试每个键值对的函数，或要查找的值',
         },
         paramsType: {
             data: 'array | record',
-            predicate: '(fn(value: any, key: number | string | nil, input: type(data)) -> boolean) | any',
+            predicate: '(fn(value: any, key: number | string, input: type(data)) -> boolean) | any',
         },
-        returnsType: '(string | number, any) | nil',
+        returnsType: '(number | string, any) | nil',
         examples: ['find([3, 5, 8], fn (v) { v % 2 == 0 }) // (2, 8)', `find((x: 1, y: 2, z: 3), 2) // ('y', 2)`],
     },
 );

package/src/vm/lib/global/sequence/map-filter.ts

@@ -32,7 +32,7 @@ export const map = VmLib(
         },
         paramsType: {
             data: 'array | record',
-            f: 'fn(value: any, key: number | string | nil, input: type(data)) -> any',
+            f: 'fn(value: any, key: number | string, input: type(data)) -> any',
         },
         returnsType: 'type(data)',
         examples: ['map([1, 2, 3], fn (v) { v * v }) // [1, 4, 9]'],
@@ -53,7 +53,7 @@ export const filter = VmLib(
         },
         paramsType: {
             data: 'array | record',
-            predicate: 'fn(value: any, key: number | string | nil, input: type(data)) -> boolean',
+            predicate: 'fn(value: any, key: number | string, input: type(data)) -> boolean',
         },
         returnsType: 'type(data)',
         examples: ['filter([1, 2, 3, 4], fn (v) { v % 2 == 0 }) // [2, 4]'],
@@ -74,7 +74,7 @@ export const filter_map = VmLib(
         },
         paramsType: {
             data: 'array | record',
-            f: 'fn(value: any, key: number | string | nil, input: type(data)) -> any | nil',
+            f: 'fn(value: any, key: number | string, input: type(data)) -> any | nil',
         },
         returnsType: 'type(data)',
         examples: ['filter_map([1, 2, 3], fn (v) { if v % 2 == 0 { v * v } else { nil } }) // [4]'],

package/src/vm/lib/global/sequence/with.ts

@@ -125,7 +125,7 @@ const _with = VmLib(
         },
         paramsType: {
             data: 'array | record',
-            '..entries': `[..[string | number | (string | number)[], any][]]`,
+            '..entries': `[..[number | string | (number | string)[], any][]]`,
         },
         returnsType: 'type(data)',
         examples: [

package/src/vm/lib/global/sequence/zip.ts

@@ -15,7 +15,7 @@ export const zip = VmLib(
             len = Math.max(len, arr.length);
         }
         if (len === 0) return [];
-        const result: Array<Record<string | number, VmConst>> = [];
+        const result: Array<Record<number | string, VmConst>> = [];
         const isArr = isVmArray(data);
         for (let i = 0; i < len; i++) {
             Cp();

package/src/vm/lib/global/time.ts

@@ -19,7 +19,7 @@ export const to_timestamp = VmLib(
     {
         summary: '将数据转换为 Unix 毫秒时间戳',
         params: { datetime: '要转换的数据，默认为当前时间' },
-        paramsType: { datetime: 'string | number' },
+        paramsType: { datetime: 'number | string' },
         returnsType: 'number',
         examples: ['to_timestamp("1970-01-01T00:00:00Z") // 0'],
     },
@@ -49,7 +49,7 @@ export const to_datetime = VmLib(
             datetime: '要转换的数据，默认为当前时间',
             offset: '时区偏移量（单位：小时），默认为 0',
         },
-        paramsType: { datetime: 'string | number', offset: 'number' },
+        paramsType: { datetime: 'number | string', offset: 'number' },
         returnsType: 'Date',
         examples: [
             `
@@ -73,7 +73,7 @@ export const to_iso8601 = VmLib(
     {
         summary: '将数据转换为 ISO 8601 格式的字符串',
         params: { datetime: '要转换的数据，默认为当前时间' },
-        paramsType: { datetime: 'string | number' },
+        paramsType: { datetime: 'number | string' },
         returnsType: 'string',
         examples: ['to_iso8601(0) // "1970-01-01T00:00:00.000Z"'],
     },

package/src/vm/operations.ts

@@ -221,7 +221,7 @@ export const $Length = (value: VmAny): number => {
     }
     return Number.NaN;
 };
-export const $Omit = (value: VmAny, omitted: ReadonlyArray<string | number>): VmRecord => {
+export const $Omit = (value: VmAny, omitted: ReadonlyArray<number | string>): VmRecord => {
     $AssertInit(value);
     if (value == null || !isVmRecord(value)) return {};
     const result: Record<string, VmConst> = {};
@@ -234,7 +234,7 @@ export const $Omit = (value: VmAny, omitted: ReadonlyArray<string | number>): Vm
     }
     return result;
 };
-export const $Pick = (value: VmAny, picked: ReadonlyArray<string | number>): VmRecord => {
+export const $Pick = (value: VmAny, picked: ReadonlyArray<number | string>): VmRecord => {
     $AssertInit(value);
     if (value == null || !isVmRecord(value)) return {};
     const result: Record<string, VmConst> = {};
@@ -313,9 +313,9 @@ function numberToString(value: number): string {
 }
 
 /** 将值转为字符串 */
-function innerToString(value: VmAny, useBraces: boolean): string {
+export function $InnerToString(value: VmAny, useBraces: boolean): string {
     if (value == null) return 'nil';
-    if (isVmWrapper(value)) return value.toString();
+    if (isVmWrapper(value)) return value.toString(useBraces);
     if (typeof value == 'function') {
         const name = getVmFunctionInfo(value)?.fullName;
         return name ? `<function ${name}>` : `<function>`;
@@ -323,7 +323,7 @@ function innerToString(value: VmAny, useBraces: boolean): string {
     if (isVmArray(value)) {
         const strings: string[] = [];
         for (const item of value) {
-            strings.push(innerToString(item, true));
+            strings.push($InnerToString(item, true));
         }
         // 在 join 过程中会自动把 null/undefined 和 empty slot 转为 ''
         // 与 innerToString 行为不一致
@@ -333,7 +333,7 @@ function innerToString(value: VmAny, useBraces: boolean): string {
     }
     if (typeof value == 'object') {
         const entries = keys(value)
-            .map((key) => `${key}: ${innerToString(value[key], true)}`)
+            .map((key) => `${key}: ${$InnerToString(value[key], true)}`)
             .join(', ');
         if (!useBraces) return entries;
         return `(${entries})`;
@@ -347,7 +347,7 @@ export const $ToString = (value: VmAny): string => {
     $AssertInit(value);
     if (typeof value == 'string') return value;
     if (value === null) return '';
-    return innerToString(value, false);
+    return $InnerToString(value, false);
 };
 export const $ToNumber = (value: VmAny): number => {
     $AssertInit(value);

package/src/vm/types/any.ts

@@ -0,0 +1,33 @@
+import { isVmConst } from './const.js';
+import { isVmFunction } from './function.js';
+import { isVmWrapper } from './wrapper.js';
+import type { VmValue } from './value.js';
+
+/** Mirascript 虚拟机内的值（包括未初始化变量） */
+export type VmAny = VmValue | VmUninitialized;
+
+/** Mirascript 虚拟机内的未初始化变量 */
+export type VmUninitialized = undefined;
+
+/**
+ * 检查是否为 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
+    }
+}

package/src/vm/types/array.ts

@@ -0,0 +1,19 @@
+import { isArray } from '../../helpers/utils.js';
+import type { VmAny, VmConst } from './index.js';
+
+/**
+ * Mirascript 数组
+ * 数组中的 `undefined`、`null` 及 <empty slot> 均视作 `nil`
+ */
+export type VmArray = ReadonlyArray<VmConst | undefined>;
+
+export const VM_ARRAY_MAX_LENGTH = 2 ** 31 - 1;
+
+/**
+ * 检查值是否为 Mirascript 数组
+ */
+export function isVmArray(value: VmAny): value is VmArray {
+    if (!isArray(value)) return false;
+    value as VmArray satisfies VmArray;
+    return true;
+}

package/src/vm/types/callable.ts

@@ -0,0 +1,10 @@
+import { isVmExtern, type VmExtern } from './extern.js';
+import { isVmFunction, type VmFunction, type VmFunctionLike } from './function.js';
+
+/** 检查值是否为 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');
+}

package/src/vm/types/{checker.ts → const.ts}

@@ -1,8 +1,12 @@
+import type { VmArray } from './array.js';
+import type { VmPrimitive } from './primitive.js';
+import type { VmRecord } from './record.js';
+import type { VmAny } from './any.js';
 import { getPrototypeOf, isArray, values } from '../../helpers/utils.js';
-import type { VmAny, VmArray, VmConst, VmImmutable, VmRecord, VmValue } from './index.js';
 import { isVmWrapper } from './wrapper.js';
-import { isVmModule } from './module.js';
-import { isVmFunction } from './function.js';
+
+/** Mirascript 虚拟机内的值语义值 */
+export type VmConst = VmPrimitive | VmRecord | VmArray;
 
 const MAX_DEPTH = 32;
 /**
@@ -103,55 +107,3 @@ export function isVmConst(value: unknown, checkDeep = false): value is VmConst {
             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 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);
-}
-
-/**
- * 检查是否为 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
-    }
-}

package/src/vm/types/context.ts

@@ -9,6 +9,7 @@ import {
 } from './index.js';
 import { create, entries, keys } from '../../helpers/utils.js';
 import type * as global from '../lib/global/index.js';
+import { VmError } from '../error.js';
 
 /** 全局导入的标准库 */
 type GlobalKeys = keyof typeof global;
@@ -31,15 +32,27 @@ export interface VmContext {
     keys(): Iterable<string>;
     /** 描述值，返回 MarkDown 文本，仅在 LSP 中使用 */
     describe?(key: string): string | undefined;
-    /** 获取指定 key 的值 `global[key]` */
+    /**
+     * 获取指定 key 的值 `global[key]`
+     * @throws {VmError} 如果值不存在则抛出异常
+     */
     get(key: string): VmValue;
     /** 查找指定 key 是否存在 `key in global` */
     has(key: string): boolean;
 }
 /** MiraScript 执行上下文 */
-export type VmContextRecord = Record<string, VmValue | undefined>;
+export type VmContextRecord = Record<string, VmValue>;
+/** MiraScript 执行上下文 */
+export type VmContextRecordLoose = Record<string, VmValue | undefined>;
 export const VmSharedContext = create(null) as VmSharedContext;
 
+let VmSharedContextKeys: readonly string[] | null = null;
+
+/** 全局变量未找到 */
+function globalVarNotFound(name: string): never {
+    throw new VmError(`Global variable '${name}' is not defined.`, null);
+}
+
 /** 定义在所有 MiraScript 执行上下文中共享的全局变量 */
 export function defineVmContextValue(
     name: string,
@@ -57,6 +70,7 @@ export function defineVmContextValue(
         v = value;
     }
     VmSharedContext[name] = v ?? null;
+    VmSharedContextKeys = null;
 }
 
 /** 无后备的实现 */
@@ -64,11 +78,14 @@ export const DefaultVmContext: VmContext = Object.freeze({
     [kVmContext]: true as const,
     /** @inheritdoc */
     keys(): Iterable<string> {
-        return keys(VmSharedContext);
+        VmSharedContextKeys ??= Object.freeze(keys(VmSharedContext));
+        return VmSharedContextKeys;
     },
     /** @inheritdoc */
     get(key: string): VmValue {
-        return VmSharedContext[key] ?? null;
+        const val = VmSharedContext[key];
+        if (val === undefined) globalVarNotFound(key);
+        return val;
     },
     /** @inheritdoc */
     has(key: string): boolean {
@@ -87,7 +104,9 @@ class ValueVmContext implements VmContext {
     }
     /** @inheritdoc */
     get(key: string): VmValue {
-        return this.env[key] ?? null;
+        const val = this.env[key];
+        if (val === undefined) globalVarNotFound(key);
+        return val;
     }
     /** @inheritdoc */
     has(key: string): boolean {
@@ -128,7 +147,7 @@ class FactoryVmContext implements VmContext {
 
 /** 以值为后备的实现 */
 type CreateVmContextWithValues = readonly [
-    vmValues?: VmContextRecord | null | undefined,
+    vmValues?: VmContextRecordLoose | null | undefined,
     externValues?: Record<string, unknown> | null | undefined,
     describer?: ((key: string) => string | undefined) | null | undefined,
 ];

package/src/vm/types/extern.ts

@@ -1,14 +1,17 @@
 import { VmError } from '../error.js';
 import { VmWrapper } from './wrapper.js';
 import type { TypeName, VmAny, VmConst, VmPrimitive, VmValue } from './index.js';
-import { getPrototypeOf, hasOwn, apply } from '../../helpers/utils.js';
+import { getPrototypeOf, hasOwn, apply, isArray } from '../../helpers/utils.js';
 import { unwrapFromVmValue, wrapToVmValue } from './boundary.js';
+import { $InnerToString } from '../operations.js';
 
 const ObjectPrototype = Object.prototype;
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const ObjectToString = ObjectPrototype.toString;
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const FunctionToString = Function.prototype.toString;
+const ArrayToString = Array.prototype.toString;
+const ArrayMap = Array.prototype.map;
 /** 包装 Mirascript `extern` 类型的对象 */
 export class VmExtern<const T extends object = object> extends VmWrapper<T> {
     constructor(
@@ -88,16 +91,25 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
         return this.value === other.value && this.thisArg === other.thisArg;
     }
     /** @inheritdoc */
-    override toString(): string {
+    override toString(useBraces: boolean): string {
         // eslint-disable-next-line @typescript-eslint/unbound-method
         const { toString } = this.value;
         if (typeof toString != 'function' || toString === ObjectToString || toString === FunctionToString) {
-            return super.toString();
+            return super.toString(useBraces);
+        }
+        if (toString === ArrayToString && isArray(this.value)) {
+            const mapped = ArrayMap.call(this.value, (item: unknown) => {
+                if (item === undefined) return '';
+                return $InnerToString(wrapToVmValue(item ?? null, null), true);
+            });
+            const str = mapped.join(', ');
+            if (useBraces) return `[${str}]`;
+            return str;
         }
         try {
             return String(this.value);
         } catch {
-            return super.toString();
+            return super.toString(useBraces);
         }
     }
     /** @inheritdoc */
@@ -107,7 +119,9 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
     /** @inheritdoc */
     override get describe(): string {
         const tag = ObjectToString.call(this.value).slice(8, -1);
-        if (tag === 'Object') {
+        if (isArray(this.value)) {
+            return `${tag}(${this.value.length})`;
+        } else if (tag === 'Object') {
             const proto = getPrototypeOf(this.value);
             if (proto === ObjectPrototype) {
                 return 'Object';

package/src/vm/types/immutable.ts

@@ -0,0 +1,22 @@
+import type { VmAny } from './any.js';
+import { isVmConst, type VmConst } from './const.js';
+import { isVmFunction, type VmFunction } from './function.js';
+import { isVmModule, type VmModule } from './module.js';
+
+/** Mirascript 虚拟机内的不可变值 */
+export type VmImmutable = VmConst | VmFunction | VmModule;
+
+/**
+ * 检查是否为 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);
+}