@mirascript/mirascript 0.1.0

package/src/vm/types/checker.ts

@@ -0,0 +1,164 @@
+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';
+
+const MAX_DEPTH = 32;
+/**
+ * 检查是否为 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 (value instanceof VmWrapper) 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 (value instanceof VmWrapper) 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 value instanceof VmModule || 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 (value instanceof VmWrapper) 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

@@ -0,0 +1,161 @@
+import {
+    VmFunction,
+    type VmAny,
+    type VmImmutable,
+    type VmValue,
+    wrapToVmValue,
+    isVmAny,
+    type VmFunctionLike,
+} from './index.js';
+import { entries, keys } from '../../helpers/utils.js';
+import type * as global from '../lib/global/index.js';
+
+/** 全局导入的标准库 */
+type GlobalKeys = keyof typeof global;
+/** 全局导入的标准库值 */
+type ToGlobalValue<T extends GlobalKeys> = (typeof global)[T] extends VmFunctionLike
+    ? VmFunction<(typeof global)[T]>
+    : (typeof global)[T];
+/** 全局导入的标准库 */
+type VmContextBase = {
+    [key in GlobalKeys]: ToGlobalValue<key>;
+};
+const kVmContext = Symbol.for('mira:vm-context');
+/** MiraScript 执行上下文的基础，仅包含标准库 */
+export type VmSharedContext = VmContextBase & Record<string, VmImmutable>;
+/** MiraScript 执行上下文 */
+export interface VmContext {
+    /** 内部标识符 */
+    readonly [kVmContext]: true;
+    /** 枚举所有 key，仅在 LSP 中使用 */
+    keys(): Iterable<string>;
+    /** 获取指定 key 的值 `global[key]` */
+    get(key: string): VmValue;
+    /** 查找指定 key 是否存在 `key in global` */
+    has(key: string): boolean;
+}
+/** MiraScript 执行上下文 */
+export type VmContextRecord = Record<string, VmValue | undefined>;
+export const VmSharedContext = { __proto__: null } as object as VmSharedContext;
+
+/** 定义在所有 MiraScript 执行上下文中共享的全局变量 */
+export function defineVmContextValue(
+    name: string,
+    value: VmImmutable | ((...args: VmAny[]) => VmAny),
+    override = false,
+): void {
+    if (!override && name in VmSharedContext) throw new Error(`Global variable '${name}' is already defined.`);
+    let v: VmImmutable;
+    if (typeof value == 'function') {
+        v = VmFunction(value, {
+            isLib: true,
+            fullName: `global.${name}`,
+        });
+    } else {
+        v = value;
+    }
+    VmSharedContext[name] = v ?? null;
+}
+
+/** 无后备的实现 */
+export const DefaultVmContext: VmContext = Object.freeze({
+    [kVmContext]: true as const,
+    /** @inheritdoc */
+    keys(): Iterable<string> {
+        return keys(VmSharedContext);
+    },
+    /** @inheritdoc */
+    get(key: string): VmValue {
+        return VmSharedContext[key] ?? null;
+    },
+    /** @inheritdoc */
+    has(key: string): boolean {
+        return key in VmSharedContext;
+    },
+});
+
+/** 以值为后备的实现 */
+class ValueVmContext implements VmContext {
+    readonly [kVmContext] = true;
+    private cachedKeys: readonly string[] | null = null;
+    /** @inheritdoc */
+    keys(): Iterable<string> {
+        this.cachedKeys ??= keys(this.env);
+        return [...this.cachedKeys, ...DefaultVmContext.keys()];
+    }
+    /** @inheritdoc */
+    get(key: string): VmValue {
+        return this.env[key] ?? null;
+    }
+    /** @inheritdoc */
+    has(key: string): boolean {
+        return key in this.env;
+    }
+    constructor(private readonly env: VmContextRecord & { __proto__: VmSharedContext }) {}
+}
+
+/** 以工厂函数为后备的实现 */
+class FactoryVmContext implements VmContext {
+    readonly [kVmContext] = true;
+    /** @inheritdoc */
+    keys(): Iterable<string> {
+        if (!this.enumerator) return DefaultVmContext.keys();
+        return [...this.enumerator(), ...DefaultVmContext.keys()];
+    }
+    /** @inheritdoc */
+    get(key: string): VmValue {
+        const value = this.getter(key);
+        if (value !== undefined) return value;
+        return DefaultVmContext.get(key);
+    }
+    /** @inheritdoc */
+    has(key: string): boolean {
+        return this.getter(key) !== undefined || DefaultVmContext.has(key);
+    }
+    constructor(
+        private readonly getter: (key: string) => VmValue | undefined,
+        private readonly enumerator?: () => Iterable<string>,
+    ) {}
+}
+
+/** 创建用于执行脚本的执行上下文 */
+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 {
+    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 [vmValues, externValues] = args;
+    const env = { __proto__: VmSharedContext } as { __proto__: VmSharedContext } & VmContextRecord;
+    if (vmValues) {
+        for (const [key, value] of entries(vmValues)) {
+            if (!isVmAny(value, false)) continue;
+            env[key] = value ?? null;
+        }
+    }
+    if (externValues) {
+        for (const [key, value] of entries(externValues as Record<string, unknown>)) {
+            env[key] = value == null ? null : wrapToVmValue(value, null);
+        }
+    }
+    return new ValueVmContext(env);
+}
+
+/** 检查是否为执行上下文 */
+export function isVmContext(context: unknown): context is VmContext {
+    if (context == null || typeof context != 'object') return false;
+    return (context as VmContext)[kVmContext] === true;
+}

package/src/vm/types/extern.ts

@@ -0,0 +1,166 @@
+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);
+        },
+    });
+}
+
+const ObjectPrototype = Object.prototype;
+// eslint-disable-next-line @typescript-eslint/unbound-method
+const ObjectToString = ObjectPrototype.toString;
+/** 包装 Mirascript `extern` 类型的对象 */
+export class VmExtern<const T extends object = object> extends VmWrapper<T> {
+    constructor(
+        value: T,
+        readonly caller: VmExtern | null = null,
+    ) {
+        super(value);
+    }
+
+    /** Check if the object has a property */
+    protected access(key: string, read: boolean): boolean {
+        // __proto__ and other private properties are not accessible
+        if (key.startsWith('_')) return false;
+        // Function-specific properties are not accessible
+        if (typeof this.value == 'function' && (key === 'prototype' || key === 'arguments' || key === 'caller'))
+            return false;
+        if (hasOwn(this.value, key)) return true;
+        if (!read) return true;
+        if (!(key in this.value)) return false;
+        if (key === 'constructor') return false; // constructor is not accessible
+        const prop = (this.value as Record<string, unknown>)[key];
+        if (key in Function.prototype && prop === Function.prototype[key as keyof (() => void)]) return false;
+        if (key in Array.prototype && prop === Array.prototype[key as keyof unknown[]]) return false;
+        if (key in Object.prototype && prop === Object.prototype[key as keyof object]) return false;
+        return true;
+    }
+
+    /** @inheritdoc */
+    override has(key: string): boolean {
+        return this.access(key, true);
+    }
+    /** @inheritdoc */
+    override get(key: string): VmAny {
+        if (!this.has(key)) return undefined;
+        const prop = (this.value as Record<string, unknown>)[key];
+        return wrapToVmValue(prop, this);
+    }
+    /** Set a property on the object */
+    set(key: string, value: VmValue): boolean {
+        if (!this.access(key, false)) return false;
+        const prop = unwrapFromVmValue(value);
+        (this.value as Record<string, unknown>)[key] = prop;
+        return true;
+    }
+    /** Call extern value */
+    call(args: readonly VmValue[]): VmAny {
+        const { value } = this;
+        const caller = this.caller?.value ?? null;
+        const unwrappedArgs = args.map(unwrapFromVmValue);
+        try {
+            const ret: unknown = apply(value as (...args: unknown[]) => unknown, caller, unwrappedArgs);
+            return wrapToVmValue(ret, null);
+        } catch (ex) {
+            throw VmError.from(`Not a callable extern`, ex, null);
+        }
+    }
+    /** @inheritdoc */
+    override keys(): string[] {
+        const keys: string[] = [];
+        for (const key in this.value) {
+            if (this.has(key)) keys.push(key);
+        }
+        return keys;
+    }
+    /** @inheritdoc */
+    override same(other: VmAny): boolean {
+        if (!(other instanceof VmExtern)) return false;
+        return this.value === other.value && this.caller === other.caller;
+    }
+    /** @inheritdoc */
+    override toString(): string {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { toString } = this.value;
+        if (typeof toString != 'function' || toString === ObjectToString) {
+            return super.toString();
+        }
+        try {
+            return String(this.value);
+        } catch {
+            return super.toString();
+        }
+    }
+    /** @inheritdoc */
+    override get type(): TypeName {
+        return 'extern';
+    }
+    /** @inheritdoc */
+    override get describe(): string {
+        const tag = ObjectToString.call(this.value).slice(8, -1);
+        if (tag === 'Object') {
+            const proto = getPrototypeOf(this.value);
+            if (proto === ObjectPrototype) {
+                return 'Object';
+            }
+            if (proto == null) {
+                return 'Object: null prototype';
+            }
+            if (typeof proto.constructor === 'function' && proto.constructor.name) {
+                return proto.constructor.name;
+            }
+        } else if (tag === 'Function' && 'prototype' in this.value && typeof this.value.prototype == 'object') {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+            const { name } = this.value as unknown as Function;
+            if (name) {
+                return `Class ${name}`;
+            } else {
+                return 'Class';
+            }
+        }
+        return tag;
+    }
+}

package/src/vm/types/function.ts

@@ -0,0 +1,136 @@
+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';
+
+const kVmFunction = Symbol.for('mirascript.vm.function');
+const kProxy = Symbol.for('mirascript.vm.function.proxy');
+
+/**
+ * Mirascript 函数签名
+ *
+ * 虽然所有输入参数的类型均为 {@linkcode VmValue}，但当参数不足时，对应的参数会被填充为 `undefined`。
+ */
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+export type VmFunctionLike = (...args: ReadonlyArray<VmValue | undefined>) => VmAny | void;
+
+/** Mirascript 函数 */
+export type VmFunction<T extends VmFunctionLike = VmFunctionLike> = T & { readonly [kVmFunction]: VmFunctionInfo };
+
+/** Mirascript 函数信息 */
+export interface VmFunctionInfo {
+    /** 完整名称 */
+    readonly fullName: string;
+    /** 是否为库函数 */
+    readonly isLib: boolean;
+    /** 文档字符串 */
+    readonly summary?: string;
+    /** 文档字符串 */
+    readonly params?: Record<string, string>;
+    /** 文档字符串 */
+    readonly paramsType?: Record<string, string>;
+    /** 文档字符串 */
+    readonly returns?: string;
+    /** 文档字符串 */
+    readonly returnsType?: string;
+    /** 文档字符串 */
+    readonly examples?: string[];
+    /** 如果添加了包装，返回原函数 */
+    readonly original?: VmFunctionLike;
+}
+
+/** Mirascript 函数创建选项 */
+export type VmFunctionOption = Partial<
+    Omit<VmFunctionInfo, 'original'> & {
+        readonly injectCp: boolean;
+    }
+>;
+
+/** 检查是否为 Mirascript 函数 */
+export function isVmFunction<T extends VmFunctionLike>(value: unknown): value is VmFunction<T> {
+    return getVmFunctionInfo(value) != null;
+}
+
+/** 检查是否为 Mirascript 函数，并获取其信息 */
+export function getVmFunctionInfo(value: unknown): VmFunctionInfo | undefined {
+    if (typeof value != 'function') return undefined;
+    return (value as VmFunction)[kVmFunction];
+}
+
+/** 创建 Mirascript 函数 */
+export function VmFunction<T extends VmFunctionLike>(fn: T, option: VmFunctionOption = {}): VmFunction<T> {
+    if (typeof fn != 'function') {
+        throw new TypeError('Invalid function');
+    }
+
+    const exists = fromVmFunctionProxy(fn);
+    // 如果已经是 VmFunction，则直接返回
+    if (exists) return exists;
+
+    const info: Writable<VmFunctionInfo> = {
+        fullName: option.fullName ?? fn.name,
+        isLib: option.isLib ?? false,
+        summary: option.summary || undefined,
+        params: option.params,
+        paramsType: option.paramsType,
+        returns: option.returns || undefined,
+        returnsType: option.returnsType || undefined,
+        examples: option.examples?.length ? option.examples : undefined,
+    };
+    if (option.injectCp) {
+        const original = fn;
+        info.original = original;
+        fn = ((...args) => {
+            try {
+                CpEnter();
+                const ret = original(...args);
+                return ret;
+            } finally {
+                CpExit();
+            }
+        }) as typeof fn;
+        defineProperty(fn, 'name', {
+            value: original.name,
+            configurable: true,
+        });
+    }
+    defineProperty(fn, kVmFunction, {
+        value: Object.freeze(info),
+    });
+    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;
+}