@mirascript/mirascript 0.1.16 → 0.1.18

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

@@ -1,13 +1,87 @@
 import supportsColor from 'supports-color';
 import { VmError } from '../../../helpers/error.js';
-import { toString } from '../../../helpers/convert.js';
+import { toString } from '../../../helpers/convert/index.js';
 import type { VmAny } from '../../types/index.js';
 import { VmLib } from '../helpers.js';
 
+/** 序列化格式 */
+type SerializeFormat =
+    /** 表示未指定格式 */
+    | ''
+    /** 以 `%` 开头的格式占位符 */
+    | `%${string}`;
+/**
+ * 默认的序列化函数
+ * @param arg 要序列化的值
+ * @param format 序列化格式
+ * @returns 序列化后的字符串，或 null 表示直接将原值传递给控制台
+ */
+function defaultSerializer(arg: VmAny, format: SerializeFormat): string | null {
+    return null;
+}
+
+/** 序列化值 */
+function serializeValue(arg: VmAny, format: SerializeFormat, serializer: typeof defaultSerializer): string | null {
+    if (serializer == null || serializer === defaultSerializer) {
+        return defaultSerializer(arg, format);
+    }
+    try {
+        return serializer(arg, format);
+    } catch {
+        return defaultSerializer(arg, format);
+    }
+}
+
 export const debug_print = VmLib(
     (...args) => {
+        const { serializer } = debug_print;
+        if (args.length <= 1 || typeof args[0] != 'string' || !args[0].includes('%')) {
+            // eslint-disable-next-line no-console
+            console.log(...debug_print.prefix, ...args.map((v) => serializeValue(v, '', serializer) ?? v));
+            return;
+        }
+        const [prefix, ...additional] = debug_print.prefix;
+        const [arg0, ...argsRest] = args;
+        const format = `${prefix || ''} ${arg0}`;
+        const values = [...additional, ...argsRest];
+        const parts = format.split(/(%[%\w])/g);
+        const messageToConsole: string[] = [];
+        const valuesToConsole: unknown[] = [];
+        let valIndex = 0;
+        for (let i = 0; i < parts.length; i++) {
+            if (i % 2 === 0) {
+                // Regular string part
+                messageToConsole.push(parts[i]!);
+                continue;
+            }
+            // Specifier part
+            const specifier = parts[i]!;
+            if (specifier === '%%') {
+                messageToConsole.push('%');
+            } else {
+                if (valIndex >= values.length) {
+                    messageToConsole.push(specifier);
+                    continue;
+                }
+                const arg = values[valIndex++]!;
+                const f = serializeValue(arg, specifier as SerializeFormat, serializer);
+                if (f != null) {
+                    messageToConsole.push('%s');
+                    valuesToConsole.push(f);
+                } else {
+                    messageToConsole.push(specifier);
+                    valuesToConsole.push(arg);
+                }
+            }
+        }
+
+        // Append any remaining arguments separated by spaces
+        if (valIndex < values.length) {
+            const remaining = values.slice(valIndex);
+            valuesToConsole.push(...remaining.map((v) => serializeValue(v, '', serializer) ?? v));
+        }
         // eslint-disable-next-line no-console
-        console.log(...debug_print.prefix, ...args);
+        console.log(messageToConsole.join(''), ...valuesToConsole);
     },
     {
         summary: '打印调试信息到控制台',
@@ -17,7 +91,8 @@ export const debug_print = VmLib(
         examples: ['debug_print("value:", 42);'],
     },
     {
-        prefix: ['MiraScript'] as readonly string[],
+        prefix: ['MiraScript'] as readonly [prefix: string, ...additional: readonly string[]],
+        serializer: defaultSerializer,
     },
 );
 
@@ -26,7 +101,7 @@ export const panic = VmLib(
         // eslint-disable-next-line no-console
         if (message === undefined) console.error(...panic.prefix);
         // eslint-disable-next-line no-console
-        else console.error(...panic.prefix, message);
+        else console.error(...panic.prefix, serializeValue(message, '', panic.serializer));
         const mgsStr = toString(message, null);
         const error = !mgsStr ? 'panic' : 'panic: ' + mgsStr;
         throw new VmError(error, undefined);
@@ -40,14 +115,16 @@ export const panic = VmLib(
     },
     {
         prefix: ['MiraScript'] as readonly string[],
+        serializer: defaultSerializer,
     },
 );
 
 if (typeof location != 'undefined') {
-    const badge = '%cMiraScript';
+    const badge = '%cMiraScript%c';
     const common = 'display: inline-block; padding: 1px 4px; border-radius: 3px;';
-    debug_print.prefix = [badge, `${common} background: #007acc; color: #fff;`];
-    panic.prefix = [badge, `${common} background: #d23d3d; color: #fff;`];
+    const reset = '';
+    debug_print.prefix = [badge, `${common} background: #007acc; color: #fff;`, reset];
+    panic.prefix = [badge, `${common} background: #d23d3d; color: #fff;`, reset];
 } else {
     if (supportsColor.stdout) {
         debug_print.prefix = ['\u001B[44;37m MiraScript \u001B[0m'];

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

@@ -1,5 +1,5 @@
 import { isVmExtern, isVmModule } from '../../types/index.js';
-import { required, rethrowError, VmLib } from '../helpers.js';
+import { expectString, required, rethrowError, VmLib } from '../helpers.js';
 const { parse, stringify } = JSON;
 
 export const to_json = VmLib(
@@ -26,10 +26,9 @@ export const to_json = VmLib(
 
 export const from_json = VmLib(
     (json, fallback) => {
-        required('json', json, null);
-        if (typeof json != 'string') return json;
+        const j = expectString('json', json);
         try {
-            return parse(json);
+            return parse(j);
         } catch (ex) {
             if (fallback !== undefined) return fallback;
             rethrowError('Invalid JSON', ex, null);

package/src/vm/lib/global/sequence/all-any.ts

@@ -1,4 +1,4 @@
-import { toBoolean } from '../../../../helpers/convert.js';
+import { toBoolean } from '../../../../helpers/convert/to-boolean.js';
 import { entries } from '../../../../helpers/utils.js';
 import { Cp } from '../../../helpers.js';
 import { $Call } from '../../../operations.js';

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

@@ -1,4 +1,4 @@
-import { toBoolean } from '../../../../helpers/convert.js';
+import { toBoolean } from '../../../../helpers/convert/to-boolean.js';
 import { entries } from '../../../../helpers/utils.js';
 import { Cp } from '../../../helpers.js';
 import { $Call, $Same } from '../../../operations.js';

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

@@ -1,4 +1,4 @@
-import { toBoolean } from '../../../../helpers/convert.js';
+import { toBoolean } from '../../../../helpers/convert/to-boolean.js';
 import { $Call } from '../../../operations.js';
 import { isVmConst, type VmAny, type VmValue } from '../../../types/index.js';
 import { VmLib, expectCallable, expectConst, map as mapImpl } from '../../helpers.js';

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

@@ -1,4 +1,4 @@
-import { toNumber } from '../../../../helpers/convert.js';
+import { toNumber } from '../../../../helpers/convert/to-number.js';
 import { $Call } from '../../../operations.js';
 import type { VmAny, VmConst, VmValue } from '../../../types/index.js';
 import { VmLib, expectArray, expectCallable } from '../../helpers.js';

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

@@ -1,5 +1,5 @@
 import { VM_ARRAY_MAX_LENGTH } from '../../../../helpers/constants.js';
-import { toNumber, toString } from '../../../../helpers/convert.js';
+import { toNumber, toString } from '../../../../helpers/convert/index.js';
 import { isVmArray, isVmRecord } from '../../../../helpers/types.js';
 import { isArray, isInteger, isNaN } from '../../../../helpers/utils.js';
 import { Element } from '../../../helpers.js';

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

@@ -1,6 +1,6 @@
 import { describeParam, expectNumberRange, throwError, throwUnexpectedTypeError, VmLib } from '../helpers.js';
 import { isNaN, isFinite } from '../../../helpers/utils.js';
-import { toNumber } from '../../../helpers/convert.js';
+import { toNumber } from '../../../helpers/convert/to-number.js';
 import { display } from '../../../helpers/serialize.js';
 import type { VmAny } from '../../types/index.js';
 

package/src/vm/lib/global/to-primitive.ts

@@ -1,4 +1,4 @@
-import { toBoolean, toFormat, toNumber, toString } from '../../../helpers/convert.js';
+import { toBoolean, toFormat, toNumber, toString } from '../../../helpers/convert/index.js';
 import { expectString, required, VmLib } from '../helpers.js';
 
 export const to_string = VmLib(

package/src/vm/lib/helpers.ts

@@ -1,7 +1,7 @@
 import type { Writable } from 'type-fest';
 import { VM_ARRAY_MAX_LENGTH } from '../../helpers/constants.js';
 import { isNaN, entries, fromEntries, isSafeInteger, isFinite } from '../../helpers/utils.js';
-import { toBoolean, toNumber, toString } from '../../helpers/convert.js';
+import { toBoolean, toNumber, toString } from '../../helpers/convert/index.js';
 import { display } from '../../helpers/serialize.js';
 import { isVmArray, isVmFunction, isVmPrimitive, isVmConst, isVmCallable, isVmRecord } from '../../helpers/types.js';
 import { VmError } from '../../helpers/error.js';
@@ -243,6 +243,7 @@ export function arrayLen(len: number | null | undefined): number {
 /** 应用映射函数 */
 export function map(
     data: VmConst,
+    /** 返回 `undefined` 表示跳过该元素 */
     mapper: (value: VmConst, index: number | string | null, data: VmConst) => VmConst | undefined,
 ): VmConst {
     if (isVmPrimitive(data)) {
@@ -279,7 +280,7 @@ export type VmLibOption = Pick<
 export type VmLib<T extends VmFunctionLike = VmFunctionLike> = T & VmLibOption;
 
 /** 创建库函数 */
-export function VmLib<T extends VmFunctionLike, P extends Record<string, unknown>>(
+export function VmLib<const T extends VmFunctionLike, P extends Record<string, unknown> = Record<never, never>>(
     fn: T,
     option: VmLibOption,
     properties?: P,
@@ -288,7 +289,7 @@ export function VmLib<T extends VmFunctionLike, P extends Record<string, unknown
     if (typeof fn != 'function') throw new TypeError('Invalid function');
     if (isVmFunction(fn)) throw new TypeError('Cannot create VmLib from a VmFunction');
 
-    const ret = fn as T & VmLibOption & P as Writable<T & VmLibOption & P>;
+    const ret = fn as Writable<VmLib<T>> & P;
     Object.assign(ret, properties);
     ret.params = option.params;
     ret.paramsType = option.paramsType;
@@ -296,5 +297,5 @@ export function VmLib<T extends VmFunctionLike, P extends Record<string, unknown
     ret.returnsType = option.returnsType;
     ret.summary = option.summary;
     ret.examples = option.examples;
-    return ret as T & VmLibOption & P;
+    return ret as VmLib<T> & P;
 }

package/src/vm/lib/index.ts

@@ -1,16 +1,16 @@
 import * as global from './global/index.js';
 import * as mods from './mod/index.js';
-import { VmSharedContext } from '../types/context.js';
+import { VM_SHARED_CONTEXT } from '../types/context.js';
 import { create, entries } from '../../helpers/utils.js';
 import { createModule, wrapEntry, type RawValue } from './loader.js';
 
 for (const [name, value] of entries(global)) {
-    VmSharedContext[name] = wrapEntry(name, value as RawValue, 'global');
+    VM_SHARED_CONTEXT[name] = wrapEntry(name, value as RawValue, 'global');
 }
 
 for (const [name, value] of entries(mods)) {
     const mod = createModule(name, value as Record<string, RawValue>);
-    VmSharedContext[name] = wrapEntry(name, mod, 'global');
+    VM_SHARED_CONTEXT[name] = wrapEntry(name, mod, 'global');
 }
 
-export const lib = Object.freeze(Object.assign(create(null), global, mods));
+export const lib: Readonly<typeof global & typeof mods> = Object.freeze(Object.assign(create(null), global, mods));

package/src/vm/lib/mod/matrix.ts

@@ -1,4 +1,4 @@
-import { toNumber } from '../../../helpers/convert.js';
+import { toNumber } from '../../../helpers/convert/to-number.js';
 import { isArray } from '../../../helpers/utils.js';
 import { Cp } from '../../helpers.js';
 import { $Add, $Call, $Div, $Mul, $Sub } from '../../operations.js';

package/src/vm/operations.ts

@@ -1,6 +1,6 @@
 import { VmError } from '../helpers/error.js';
 import { hasOwnEnumerable, isNaN, isSafeInteger, keys, create } from '../helpers/utils.js';
-import { toNumber, toString, toBoolean, toFormat } from '../helpers/convert.js';
+import { toNumber, toString, toBoolean, toFormat } from '../helpers/convert/index.js';
 import { display } from '../helpers/serialize.js';
 import { isVmPrimitive, isVmArray, isVmRecord, isVmFunction, isVmExtern, isVmWrapper } from '../helpers/types.js';
 import type { TypeName, VmAny, VmImmutable, VmRecord, VmValue, VmArray, VmConst } from './types/index.js';
@@ -200,10 +200,9 @@ export const $Length = (value: VmAny): number => {
     $AssertInit(value);
     if (isVmArray(value)) return value.length;
     if (isVmRecord(value)) return keys(value).length;
-    if (isVmWrapper(value)) {
-        return value.keys().length;
-    }
-    return Number.NaN;
+    if (isVmWrapper(value)) return value.keys().length;
+
+    throw new VmError(`Value has no length: ${display(value)}`, 0);
 };
 export const $Omit = (value: VmAny, omitted: ReadonlyArray<number | string>): VmRecord => {
     $AssertInit(value);
@@ -250,14 +249,14 @@ const sliceCore = (value: VmArray, start: number, end: number, exclusive: boolea
 };
 export const $Slice = (value: VmAny, start: VmAny, end: VmAny): VmArray => {
     $AssertInit(value);
-    if (!isVmArray(value)) throw new VmError(`Expected array, got ${$Type(value)}`, []);
+    if (!isVmArray(value)) throw new VmError(`Expected array, got ${display(value)}`, []);
     const s = start != null ? $ToNumber(start) : 0;
     const e = end != null ? $ToNumber(end) : value.length - 1;
     return sliceCore(value, s, e, false);
 };
 export const $SliceExclusive = (value: VmAny, start: VmAny, end: VmAny): VmArray => {
     $AssertInit(value);
-    if (!isVmArray(value)) throw new VmError(`Expected array, got ${$Type(value)}`, []);
+    if (!isVmArray(value)) throw new VmError(`Expected array, got ${display(value)}`, []);
     const s = start != null ? $ToNumber(start) : 0;
     const e = end != null ? $ToNumber(end) : value.length;
     return sliceCore(value, s, e, true);
@@ -323,7 +322,7 @@ export const $IsArray = (value: VmAny): value is VmArray => {
 export const $AssertNonNil = (value: VmAny): asserts value is NonNullable<VmValue> => {
     $AssertInit(value);
     if (value !== null) return;
-    throw new VmError('Expected non-nil value', null);
+    throw new VmError(`Expected non-nil value`, null);
 };
 export const $Has = (obj: VmAny, key: VmAny): boolean => {
     $AssertInit(obj);
@@ -350,7 +349,7 @@ export const $Set = (obj: VmAny, key: VmAny, value: VmAny): void => {
     $AssertInit(value);
     const pk = $ToString(key);
     if (obj == null) return;
-    if (!isVmExtern(obj)) throw new VmError(`Expected extern, got ${$Type(obj)}`, undefined);
+    if (!isVmExtern(obj)) throw new VmError(`Expected extern, got ${display(obj)}`, undefined);
     obj.set(pk, value);
 };
 export const $Iterable = (value: VmAny): Iterable<VmValue | undefined> => {
@@ -358,7 +357,7 @@ export const $Iterable = (value: VmAny): Iterable<VmValue | undefined> => {
     if (isVmWrapper(value)) return value.keys();
     if (isVmArray(value)) return value;
     if (value != null && typeof value == 'object') return keys(value);
-    throw new VmError(`Value is not iterable`, isVmFunction(value) ? [] : [value]);
+    throw new VmError(`Value is not iterable: ${display(value)}`, isVmFunction(value) ? [] : [value]);
 };
 
 export const $RecordSpread = (record: VmAny): VmRecord | null => {
@@ -384,7 +383,7 @@ export const $RecordSpread = (record: VmAny): VmRecord | null => {
         }
         return result;
     }
-    throw new VmError(`Expected record, array, extern or nil, got ${$Type(record)}`, null);
+    throw new VmError(`Expected record, array, extern or nil, got ${display(record)}`, null);
 };
 
 export const $ArraySpread = (array: VmAny): Iterable<VmConst | undefined> => {
@@ -403,7 +402,7 @@ export const $ArraySpread = (array: VmAny): Iterable<VmConst | undefined> => {
         }
         return result;
     }
-    throw new VmError(`Expected array, iterable extern or nil, got ${$Type(array)}`, []);
+    throw new VmError(`Expected array, iterable extern or nil, got ${display(array)}`, []);
 };
 
 export const $Format = (value: VmAny, format: VmAny): string => {

package/src/vm/types/context.ts

@@ -2,33 +2,17 @@ import { create, entries, keys } from '../../helpers/utils.js';
 import { isVmAny } from '../../helpers/types.js';
 import { VmError } from '../../helpers/error.js';
 import { kVmContext } from '../../helpers/constants.js';
-import type { lib } from '../lib/index.js';
-import type { VmAny, VmImmutable, VmValue, VmFunctionLike, VmModule } from './index.js';
+import type { VmAny, VmImmutable, VmValue } from './index.js';
 import { wrapToVmValue } from './boundary.js';
 import { VmFunction } from './function.js';
+const { freeze } = Object;
 
-/** 全局导入的标准库值 */
-type ToLibValue<V> = V extends VmFunctionLike
-    ? VmFunction<V>
-    : V extends Record<string, VmImmutable | VmFunctionLike>
-      ? ToLibModule<V>
-      : V;
-/** 全局导入的标准库值 */
-type ToLibModule<V extends Record<string, VmImmutable | VmFunctionLike>> = VmModule<{
-    [key in keyof V]: ToLibValue<V[key]>;
-}>;
-/** 全局导入的标准库 */
-type VmContextBase = {
-    [key in keyof typeof lib]: ToLibValue<(typeof lib)[key]>;
-};
-/** MiraScript 执行上下文的基础，仅包含标准库 */
-export type VmSharedContext = VmContextBase & Record<string, VmImmutable>;
 /** MiraScript 执行上下文 */
 export interface VmContext {
     /** 内部标识符 */
     readonly [kVmContext]: true;
     /** 枚举所有 key，仅在 LSP 中使用 */
-    keys(): Iterable<string>;
+    keys(): readonly string[];
     /** 描述值，返回 MarkDown 文本，仅在 LSP 中使用 */
     describe?(key: string): string | undefined;
     /**
@@ -43,9 +27,9 @@ export interface VmContext {
 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;
+export const VM_SHARED_CONTEXT: Record<string, VmImmutable> = create(null);
+/** 缓存 {@link VM_SHARED_CONTEXT} 的 keys */
+let VM_SHARED_CONTEXT_KEYS: readonly string[] | null = null;
 
 /** 全局变量未找到 */
 function globalVarNotFound(name: string): never {
@@ -58,7 +42,7 @@ export function defineVmContextValue(
     value: VmImmutable | ((...args: VmAny[]) => VmAny),
     override = false,
 ): void {
-    if (!override && name in VmSharedContext) throw new Error(`Global variable '${name}' is already defined.`);
+    if (!override && name in VM_SHARED_CONTEXT) throw new Error(`Global variable '${name}' is already defined.`);
     let v: VmImmutable;
     if (typeof value == 'function') {
         v = VmFunction(value, {
@@ -68,38 +52,42 @@ export function defineVmContextValue(
     } else {
         v = value;
     }
-    VmSharedContext[name] = v ?? null;
-    VmSharedContextKeys = null;
+    VM_SHARED_CONTEXT[name] = v ?? null;
+    VM_SHARED_CONTEXT_KEYS = null;
 }
 
 /** 无后备的实现 */
-export const DefaultVmContext: VmContext = Object.freeze({
+export const DefaultVmContext: VmContext = freeze({
     [kVmContext]: true as const,
     /** @inheritdoc */
-    keys(): Iterable<string> {
-        VmSharedContextKeys ??= Object.freeze(keys(VmSharedContext));
-        return VmSharedContextKeys;
+    keys(): readonly string[] {
+        VM_SHARED_CONTEXT_KEYS ??= freeze(keys(VM_SHARED_CONTEXT));
+        return VM_SHARED_CONTEXT_KEYS;
     },
     /** @inheritdoc */
     get(key: string): VmValue {
-        const val = VmSharedContext[key];
+        const val = VM_SHARED_CONTEXT[key];
         if (val === undefined) globalVarNotFound(key);
         return val;
     },
     /** @inheritdoc */
     has(key: string): boolean {
-        return key in VmSharedContext;
+        return key in VM_SHARED_CONTEXT;
     },
 });
 
 /** 以值为后备的实现 */
 class ValueVmContext implements VmContext {
     readonly [kVmContext] = true;
-    private cachedKeys: readonly string[] | null = null;
+    private cachedKeys: readonly [def: readonly string[], all: readonly string[]] | null = null;
     /** @inheritdoc */
-    keys(): Iterable<string> {
-        this.cachedKeys ??= keys(this.env);
-        return [...this.cachedKeys, ...DefaultVmContext.keys()];
+    keys(): readonly string[] {
+        const defaultKeys = DefaultVmContext.keys();
+        if (this.cachedKeys?.[0] !== defaultKeys) {
+            const allKeys = freeze([...keys(this.env), ...defaultKeys]);
+            this.cachedKeys = freeze([defaultKeys, allKeys]);
+        }
+        return this.cachedKeys[1];
     }
     /** @inheritdoc */
     get(key: string): VmValue {
@@ -122,9 +110,9 @@ class ValueVmContext implements VmContext {
 class FactoryVmContext implements VmContext {
     readonly [kVmContext] = true;
     /** @inheritdoc */
-    keys(): Iterable<string> {
+    keys(): readonly string[] {
         if (!this.enumerator) return DefaultVmContext.keys();
-        return [...this.enumerator(), ...DefaultVmContext.keys()];
+        return freeze([...this.enumerator(), ...DefaultVmContext.keys()]);
     }
     /** @inheritdoc */
     get(key: string): VmValue {
@@ -169,7 +157,7 @@ export function createVmContext(...args: CreateVmContextWithValues | CreateVmCon
     }
 
     const [vmValues, externValues, describer] = args as CreateVmContextWithValues;
-    const env = create(VmSharedContext) as VmContextRecord;
+    const env: VmContextRecord = create(VM_SHARED_CONTEXT);
     if (vmValues) {
         for (const [key, value] of entries(vmValues)) {
             if (!isVmAny(value, false)) continue;

package/src/vm/types/extern.ts

@@ -1,6 +1,6 @@
 import { VmError } from '../../helpers/error.js';
 import { getPrototypeOf, hasOwn, apply, isArray } from '../../helpers/utils.js';
-import { innerToString } from '../../helpers/convert.js';
+import { innerToString } from '../../helpers/convert/to-string.js';
 import { isVmExtern } from '../../helpers/types.js';
 import { kVmExtern } from '../../helpers/constants.js';
 import type { TypeName, VmAny, VmConst, VmPrimitive, VmValue } from './index.js';

package/src/vm/types/index.ts

@@ -76,7 +76,7 @@ export {
 
 export { wrapToVmValue, unwrapFromVmValue } from './boundary.js';
 
-export { type VmContext, type VmSharedContext, defineVmContextValue, createVmContext } from './context.js';
+export { type VmContext, defineVmContextValue, createVmContext } from './context.js';
 export { VmExtern } from './extern.js';
 export { VmFunction, type VmFunctionInfo, type VmFunctionLike, type VmFunctionOption } from './function.js';
 export { VmModule } from './module.js';