@mirascript/mirascript 0.1.1 → 0.1.3

package/src/vm/types/boundary.ts

@@ -0,0 +1,95 @@
+import { isVmFunction, type VmFunctionLike, type VmFunction } from './function.js';
+import { isVmExtern, VmExtern } from './extern.js';
+import { isVmWrapper } from './wrapper.js';
+import type { VmAny, VmConst, VmModule, VmPrimitive, VmValue } from './index.js';
+import { $Call } from '../operations.js';
+import { defineProperty, apply } from '../../helpers/utils.js';
+
+const kProxy = Symbol.for('mirascript.vm.function.proxy');
+
+/** 创建 Mirascript 函数在宿主语言运行的代理 */
+export function toVmFunctionProxy<T extends VmFunctionLike>(fn: VmFunction<T>): T {
+    if (!isVmFunction(fn)) return fn;
+
+    const cached = (fn as unknown as { [kProxy]?: T })[kProxy];
+    if (cached != null) return cached;
+
+    const proxy = (...args: unknown[]) => {
+        const ret = $Call(
+            fn,
+            // 作为函数参数传入的值一定丢失了它的 this
+            args.map((v) => wrapToVmValue(v, null)),
+        );
+        return unwrapFromVmValue(ret);
+    };
+    defineProperty(fn, kProxy, { value: proxy });
+    defineProperty(proxy, kProxy, { value: fn });
+    defineProperty(proxy, 'name', {
+        value: fn.name,
+        configurable: true,
+    });
+    return proxy as T;
+}
+
+/** 解开 Mirascript 函数在宿主语言运行的代理 */
+export function fromVmFunctionProxy<T extends VmFunctionLike>(fn: T): VmFunction<T> | undefined {
+    if (isVmFunction(fn)) return fn;
+
+    const original = (fn as unknown as { [kProxy]?: VmFunction<T> })[kProxy];
+    if (original && isVmFunction(original)) return original;
+
+    return undefined;
+}
+
+/** 将宿主语言的值包装为 Mirascript 类型 */
+export function wrapToVmValue(
+    value: unknown,
+    thisArg: VmExtern | null = null,
+    assumeVmValue?: (obj: object) => obj is Exclude<VmConst, VmPrimitive>,
+): VmValue {
+    if (value == null) return null;
+    switch (typeof value) {
+        case 'function': {
+            const unwrapped = fromVmFunctionProxy(value as VmFunctionLike);
+            if (unwrapped) return unwrapped;
+            return new VmExtern(value as () => never, thisArg);
+        }
+        case 'object': {
+            if (isVmWrapper(value)) return value as VmModule | VmExtern;
+            if (value instanceof Date) return value.valueOf();
+            if (assumeVmValue?.(value)) return value;
+            // Only functions preserve thisArg
+            return new VmExtern(value);
+        }
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return value;
+        case 'bigint':
+            return Number(value);
+        case 'symbol':
+        case 'undefined':
+        default:
+            return null;
+    }
+}
+
+/** 取消宿主语言的值的 Mirascript 包装  */
+export function unwrapFromVmValue(value: VmAny): unknown {
+    if (typeof value == 'function') {
+        return toVmFunctionProxy(value);
+    }
+    if (value == null || typeof value != 'object') return value;
+    if (!isVmExtern(value)) return value;
+
+    if (value.thisArg == null || typeof value.value != 'function') {
+        return value.value;
+    }
+    const f = value as VmExtern<(...args: unknown[]) => unknown>;
+    const caller = f.thisArg!.value;
+    return new Proxy(f.value, {
+        apply(target, thisArg, args): unknown {
+            return apply(target, caller, args);
+        },
+    });
+}

package/src/vm/types/checker.ts

@@ -1,15 +1,8 @@
 import { getPrototypeOf, isArray, values } from '../../helpers/utils.js';
-import {
-    isVmFunction,
-    VmModule,
-    type VmAny,
-    type VmArray,
-    type VmConst,
-    type VmImmutable,
-    type VmRecord,
-    type VmValue,
-} from './index.js';
-import { VmWrapper } from './wrapper.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';
 
 const MAX_DEPTH = 32;
 /**
@@ -59,7 +52,7 @@ function isVmConstInner(value: unknown, depth: number): value is VmConst {
             return true;
         case 'object':
             if (value == null) return true;
-            if (value instanceof VmWrapper) return false;
+            if (isVmWrapper(value)) return false;
             if (isArray(value)) {
                 return isVmArrayDeep(value, depth);
             } else {
@@ -92,7 +85,7 @@ export function isVmConst(value: unknown, checkDeep = false): value is VmConst {
             return true;
         case 'object':
             if (value == null) return true;
-            if (value instanceof VmWrapper) return false;
+            if (isVmWrapper(value)) return false;
             if (!checkDeep) {
                 if (isArray(value)) {
                     return isVmArrayDeep(value, 0);
@@ -122,7 +115,7 @@ export function isVmImmutable(value: unknown, checkDeep: boolean): value is VmIm
  * 检查是否为 Mirascript 不可变值
  */
 export function isVmImmutable(value: unknown, checkDeep = false): value is VmImmutable {
-    return value instanceof VmModule || isVmFunction(value) || isVmConst(value, checkDeep);
+    return isVmModule(value) || isVmFunction(value) || isVmConst(value, checkDeep);
 }
 /**
  * 检查是否为 Mirascript 合法值
@@ -152,7 +145,7 @@ export function isVmAny(value: unknown, checkDeep: boolean): value is VmAny {
             return true;
         case 'object':
             if (value == null) return true;
-            if (value instanceof VmWrapper) return true;
+            if (isVmWrapper(value)) return true;
             return isVmConst(value, checkDeep);
         case 'function':
             return isVmFunction(value);

package/src/vm/types/context.ts

@@ -7,7 +7,7 @@ import {
     isVmAny,
     type VmFunctionLike,
 } from './index.js';
-import { entries, keys } from '../../helpers/utils.js';
+import { create, entries, keys } from '../../helpers/utils.js';
 import type * as global from '../lib/global/index.js';
 
 /** 全局导入的标准库 */
@@ -29,6 +29,8 @@ export interface VmContext {
     readonly [kVmContext]: true;
     /** 枚举所有 key，仅在 LSP 中使用 */
     keys(): Iterable<string>;
+    /** 描述值，返回 MarkDown 文本，仅在 LSP 中使用 */
+    describe?(key: string): string | undefined;
     /** 获取指定 key 的值 `global[key]` */
     get(key: string): VmValue;
     /** 查找指定 key 是否存在 `key in global` */
@@ -36,7 +38,7 @@ export interface VmContext {
 }
 /** MiraScript 执行上下文 */
 export type VmContextRecord = Record<string, VmValue | undefined>;
-export const VmSharedContext = { __proto__: null } as object as VmSharedContext;
+export const VmSharedContext = create(null) as VmSharedContext;
 
 /** 定义在所有 MiraScript 执行上下文中共享的全局变量 */
 export function defineVmContextValue(
@@ -91,7 +93,11 @@ class ValueVmContext implements VmContext {
     has(key: string): boolean {
         return key in this.env;
     }
-    constructor(private readonly env: VmContextRecord & { __proto__: VmSharedContext }) {}
+    constructor(
+        private readonly env: VmContextRecord,
+        /** @inheritdoc */
+        readonly describe?: (key: string) => string | undefined,
+    ) {}
 }
 
 /** 以工厂函数为后备的实现 */
@@ -115,31 +121,37 @@ class FactoryVmContext implements VmContext {
     constructor(
         private readonly getter: (key: string) => VmValue | undefined,
         private readonly enumerator?: () => Iterable<string>,
+        /** @inheritdoc */
+        readonly describe?: (key: string) => string | undefined,
     ) {}
 }
 
+/** 以值为后备的实现 */
+type CreateVmContextWithValues = readonly [
+    vmValues?: VmContextRecord | null | undefined,
+    externValues?: Record<string, unknown> | null | undefined,
+    describer?: ((key: string) => string | undefined) | null | undefined,
+];
+/** 以工厂函数为后备的实现 */
+type CreateVmContextWithFactory = readonly [
+    getter: (key: string) => VmValue | undefined,
+    enumerator?: (() => Iterable<string>) | null | undefined,
+    describer?: ((key: string) => string | undefined) | null | undefined,
+];
+
 /** 创建用于执行脚本的执行上下文 */
-export function createVmContext(
-    ...args:
-        | readonly [
-              vmValues?: VmContextRecord | null | undefined,
-              externValues?: Record<string, unknown> | null | undefined,
-          ]
-        | readonly [
-              getter: (key: string) => VmValue | undefined,
-              enumerator?: (() => Iterable<string>) | null | undefined,
-          ]
-): VmContext {
+export function createVmContext(...args: CreateVmContextWithValues | CreateVmContextWithFactory): VmContext {
     if (args[0] == null && args[1] == null) {
         return { ...DefaultVmContext };
     }
 
     if (typeof args[0] == 'function') {
-        return new FactoryVmContext(args[0], args[1] as (() => Iterable<string>) | undefined);
+        const [getter, enumerator, describer] = args as CreateVmContextWithFactory;
+        return new FactoryVmContext(getter, enumerator ?? undefined, describer ?? undefined);
     }
 
-    const [vmValues, externValues] = args;
-    const env = { __proto__: VmSharedContext } as { __proto__: VmSharedContext } & VmContextRecord;
+    const [vmValues, externValues, describer] = args as CreateVmContextWithValues;
+    const env = create(VmSharedContext) as VmContextRecord;
     if (vmValues) {
         for (const [key, value] of entries(vmValues)) {
             if (!isVmAny(value, false)) continue;
@@ -147,11 +159,11 @@ export function createVmContext(
         }
     }
     if (externValues) {
-        for (const [key, value] of entries(externValues as Record<string, unknown>)) {
+        for (const [key, value] of entries(externValues)) {
             env[key] = value == null ? null : wrapToVmValue(value, null);
         }
     }
-    return new ValueVmContext(env);
+    return new ValueVmContext(env, describer ?? undefined);
 }
 
 /** 检查是否为执行上下文 */

package/src/vm/types/extern.ts

@@ -1,62 +1,19 @@
 import { VmError } from '../error.js';
-import { fromVmFunctionProxy, toVmFunctionProxy, type VmFunctionLike } from './function.js';
 import { VmWrapper } from './wrapper.js';
-import type { TypeName, VmAny, VmModule, VmValue } from './index.js';
-import { getPrototypeOf, hasOwn } from '../../helpers/utils.js';
-const { apply } = Reflect;
-
-/** 包装为 Mirascript 类型 */
-export function wrapToVmValue(value: unknown, caller: VmExtern | null): VmValue {
-    if (value == null) return null;
-    switch (typeof value) {
-        case 'function': {
-            const unwrapped = fromVmFunctionProxy(value as VmFunctionLike);
-            if (unwrapped) return unwrapped;
-            return new VmExtern(value, caller);
-        }
-        case 'object':
-            if (value instanceof VmWrapper) return value as VmModule | VmExtern;
-            return new VmExtern(value, null);
-        case 'string':
-        case 'number':
-        case 'boolean':
-            return value;
-        case 'bigint':
-            return Number(value);
-        case 'symbol':
-        case 'undefined':
-        default:
-            return null;
-    }
-}
-
-/** 取消 Mirascript 类型包装  */
-export function unwrapFromVmValue(value: VmAny): unknown {
-    if (typeof value == 'function') {
-        return toVmFunctionProxy(value);
-    }
-    if (value == null || typeof value != 'object') return value;
-    if (!(value instanceof VmExtern)) return value;
-    if (value.caller == null || typeof value.value != 'function') {
-        return value.value;
-    }
-    const caller = value.caller.value;
-    const func = value.value as (...args: unknown[]) => unknown;
-    return new Proxy(func, {
-        apply(target, thisArg, args): unknown {
-            return apply(target, caller, args);
-        },
-    });
-}
+import type { TypeName, VmAny, VmConst, VmPrimitive, VmValue } from './index.js';
+import { getPrototypeOf, hasOwn, apply } from '../../helpers/utils.js';
+import { unwrapFromVmValue, wrapToVmValue } from './boundary.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;
 /** 包装 Mirascript `extern` 类型的对象 */
 export class VmExtern<const T extends object = object> extends VmWrapper<T> {
     constructor(
         value: T,
-        readonly caller: VmExtern | null = null,
+        readonly thisArg: T extends (...args: readonly never[]) => unknown ? VmExtern | null : null = null,
     ) {
         super(value);
     }
@@ -79,6 +36,11 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
         return true;
     }
 
+    /** 决定是否对属性进行包装 */
+    protected assumeVmValue(value: object, key: keyof T | undefined): value is Exclude<VmConst, VmPrimitive> {
+        return false;
+    }
+
     /** @inheritdoc */
     override has(key: string): boolean {
         return this.access(key, true);
@@ -87,7 +49,7 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
     override get(key: string): VmAny {
         if (!this.has(key)) return undefined;
         const prop = (this.value as Record<string, unknown>)[key];
-        return wrapToVmValue(prop, this);
+        return wrapToVmValue(prop, this, (v) => this.assumeVmValue(v, key as keyof T));
     }
     /** Set a property on the object */
     set(key: string, value: VmValue): boolean {
@@ -99,14 +61,18 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
     /** Call extern value */
     call(args: readonly VmValue[]): VmAny {
         const { value } = this;
-        const caller = this.caller?.value ?? null;
+        if (typeof value != 'function') {
+            throw VmError.from(`Not a callable extern`, null, null);
+        }
+        const caller = this.thisArg?.value ?? null;
         const unwrappedArgs = args.map(unwrapFromVmValue);
+        let ret: unknown;
         try {
-            const ret: unknown = apply(value as (...args: unknown[]) => unknown, caller, unwrappedArgs);
-            return wrapToVmValue(ret, null);
+            ret = apply(value, caller, unwrappedArgs);
         } catch (ex) {
-            throw VmError.from(`Not a callable extern`, ex, null);
+            throw VmError.from(`Callable extern`, ex, null);
         }
+        return wrapToVmValue(ret, null, (obj) => this.assumeVmValue(obj, undefined));
     }
     /** @inheritdoc */
     override keys(): string[] {
@@ -118,14 +84,14 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
     }
     /** @inheritdoc */
     override same(other: VmAny): boolean {
-        if (!(other instanceof VmExtern)) return false;
-        return this.value === other.value && this.caller === other.caller;
+        if (!isVmExtern(other)) return false;
+        return this.value === other.value && this.thisArg === other.thisArg;
     }
     /** @inheritdoc */
     override toString(): string {
         // eslint-disable-next-line @typescript-eslint/unbound-method
         const { toString } = this.value;
-        if (typeof toString != 'function' || toString === ObjectToString) {
+        if (typeof toString != 'function' || toString === ObjectToString || toString === FunctionToString) {
             return super.toString();
         }
         try {
@@ -164,3 +130,10 @@ export class VmExtern<const T extends object = object> extends VmWrapper<T> {
         return tag;
     }
 }
+
+const kVmExtern = Symbol.for('mirascript.vm.extern');
+Object.defineProperty(VmExtern.prototype, kVmExtern, { value: true });
+/** 检查值是否为 Mirascript 外部值 */
+export function isVmExtern<T extends object>(value: unknown): value is VmExtern<T> {
+    return value != null && typeof value == 'object' && kVmExtern in value;
+}

package/src/vm/types/function.ts

@@ -1,12 +1,10 @@
 import type { Writable } from 'type-fest';
 import { defineProperty } from '../../helpers/utils.js';
 import { CpEnter, CpExit } from '../helpers.js';
-import { $Call } from '../operations.js';
 import type { VmAny, VmValue } from './index.js';
-import { wrapToVmValue, unwrapFromVmValue } from './extern.js';
+import { fromVmFunctionProxy } from './boundary.js';
 
 const kVmFunction = Symbol.for('mirascript.vm.function');
-const kProxy = Symbol.for('mirascript.vm.function.proxy');
 
 /**
  * Mirascript 函数签名
@@ -101,37 +99,3 @@ export function VmFunction<T extends VmFunctionLike>(fn: T, option: VmFunctionOp
     });
     return fn as VmFunction<T>;
 }
-
-/** 创建 Mirascript 函数在宿主语言运行的代理 */
-export function toVmFunctionProxy<T extends VmFunctionLike>(fn: VmFunction<T>): T {
-    if (!isVmFunction(fn)) return fn;
-
-    const cached = (fn as unknown as { [kProxy]?: T })[kProxy];
-    if (cached) return cached;
-
-    const proxy = (...args: unknown[]) => {
-        const ret = $Call(
-            fn,
-            // 作为函数参数传入的值一定丢失了它的 this
-            args.map((v) => wrapToVmValue(v, null)),
-        );
-        return unwrapFromVmValue(ret);
-    };
-    defineProperty(fn, kProxy, { value: proxy });
-    defineProperty(proxy, kProxy, { value: fn });
-    defineProperty(proxy, 'name', {
-        value: fn.name,
-        configurable: true,
-    });
-    return proxy as T;
-}
-
-/** 解开 Mirascript 函数在宿主语言运行的代理 */
-export function fromVmFunctionProxy<T extends VmFunctionLike>(fn: T): VmFunction<T> | undefined {
-    if (isVmFunction(fn)) return fn;
-
-    const original = (fn as unknown as { [kProxy]?: VmFunction<T> })[kProxy];
-    if (original && isVmFunction(original)) return original;
-
-    return undefined;
-}

package/src/vm/types/index.ts

@@ -1,8 +1,8 @@
 import { isArray } from '../../helpers/utils.js';
-import { VmExtern } from './extern.js';
-import type { VmFunction } from './function.js';
-import { VmModule } from './module.js';
-import { VmWrapper } from './wrapper.js';
+import { isVmExtern, VmExtern } from './extern.js';
+import { isVmFunction, VmFunction } from './function.js';
+import { VmModule, isVmModule } from './module.js';
+import { isVmWrapper } from './wrapper.js';
 
 /** Mirascript 原始值 */
 export type VmPrimitive = null | string | number | boolean;
@@ -74,7 +74,7 @@ export function isVmArray(value: VmAny): value is VmArray {
  */
 export function isVmRecord(value: VmAny): value is VmRecord {
     if (value == null || typeof value !== 'object') return false;
-    if (value instanceof VmWrapper) return false;
+    if (isVmWrapper(value)) return false;
     if (isVmArray(value)) return false;
     value satisfies VmRecord;
     return true;
@@ -92,28 +92,16 @@ export function isVmPrimitive(value: unknown): value is VmPrimitive {
     return false;
 }
 
-export { VmExtern, wrapToVmValue, unwrapFromVmValue } from './extern.js';
+export { VmFunction, isVmFunction, VmExtern, isVmExtern, VmModule, isVmModule, isVmWrapper };
+export { wrapToVmValue, unwrapFromVmValue, toVmFunctionProxy, fromVmFunctionProxy } from './boundary.js';
 
-/** 检查值是否为 Mirascript 外部值 */
-export function isVmExtern(value: unknown): value is VmExtern {
-    return value instanceof VmExtern;
+/** 检查值是否为 Mirascript 可调用值 */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function isVmCallable(value: unknown): value is VmFunction | VmExtern<Function> {
+    return isVmFunction(value) || (isVmExtern(value) && typeof value.value == 'function');
 }
 
-export {
-    VmFunction,
-    isVmFunction,
-    getVmFunctionInfo,
-    type VmFunctionInfo,
-    type VmFunctionLike,
-    type VmFunctionOption,
-} from './function.js';
-
-export { VmModule } from './module.js';
-
-/** 检查值是否为 Mirascript 模块 */
-export function isVmModule(value: unknown): value is VmModule {
-    return value instanceof VmModule;
-}
+export { getVmFunctionInfo, type VmFunctionInfo, type VmFunctionLike, type VmFunctionOption } from './function.js';
 
 export { type VmContext, type VmSharedContext, isVmContext, defineVmContextValue, createVmContext } from './context.js';
 

package/src/vm/types/module.ts

@@ -38,3 +38,10 @@ export class VmModule<const T extends Record<string, VmValue> = Record<string, V
         return this.name;
     }
 }
+
+const kVmModule = Symbol.for('mirascript.vm.module');
+Object.defineProperty(VmModule.prototype, kVmModule, { value: true });
+/** 检查值是否为 Mirascript 模块 */
+export function isVmModule<T extends Record<string, VmValue>>(value: unknown): value is VmModule<T> {
+    return value != null && typeof value == 'object' && kVmModule in value;
+}

package/src/vm/types/wrapper.ts

@@ -26,3 +26,10 @@ export abstract class VmWrapper<T extends object> {
         return `<${this.type} ${this.describe}>`;
     }
 }
+
+const kVmWrapper = Symbol.for('mirascript.vm.wrapper');
+Object.defineProperty(VmWrapper.prototype, kVmWrapper, { value: true });
+/** 检查值是否为 MiraScript 包装器 */
+export function isVmWrapper<T extends object>(value: unknown): value is VmWrapper<T> {
+    return value != null && typeof value == 'object' && kVmWrapper in value;
+}