@mirascript/mirascript 0.1.15 → 0.1.16

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

@@ -1,35 +1,60 @@
-import { $ToString, $ToNumber } from '../../operations.js';
-import { VmLib } from '../_helpers.js';
-import { isFinite } from '../../../helpers/utils.js';
+import { describeParam, expectNumberRange, throwError, throwUnexpectedTypeError, VmLib } from '../helpers.js';
+import { isNaN, isFinite } from '../../../helpers/utils.js';
+import { toNumber } from '../../../helpers/convert.js';
+import { display } from '../../../helpers/serialize.js';
+import type { VmAny } from '../../types/index.js';
+
+const fromNumber = (datetime: number, fallback: boolean): number | null => {
+    const n = new Date(datetime).getTime();
+    if (isFinite(n)) return n;
+    if (fallback) return null;
+    throwError(`${describeParam('datetime')} is an invalid timestamp: ${display(datetime)}`, Number.NaN);
+};
+
+const getTimestamp = (datetime: VmAny, fallback: boolean): number | null => {
+    if (datetime == null) {
+        return Date.now();
+    }
+    if (typeof datetime == 'number') {
+        return fromNumber(datetime, fallback);
+    }
+    if (typeof datetime != 'string') {
+        if (fallback) return null;
+        throwUnexpectedTypeError('datetime', 'number | string', datetime, Number.NaN);
+    }
+    const num = toNumber(datetime, Number.NaN);
+    if (!isNaN(num)) {
+        return fromNumber(num, fallback);
+    }
+    const parsed = Date.parse(datetime);
+    if (isFinite(parsed)) return parsed;
+    if (fallback) return null;
+    throwError(`${describeParam('datetime')} cannot be parsed as datetime: ${display(datetime)}`, Number.NaN);
+};
 
 export const to_timestamp = VmLib(
-    (datetime) => {
-        if (datetime == null) {
-            return Date.now();
-        }
-        if (typeof datetime == 'number') {
-            return new Date(datetime).getTime();
-        }
-        const str = $ToString(datetime);
-        if (!str) return Number.NaN;
-        const num = $ToNumber(str);
-        if (isFinite(num)) return num;
-        return Date.parse(str);
+    (datetime, fallback) => {
+        const timestamp = getTimestamp(datetime, fallback !== undefined);
+        if (timestamp == null) return fallback;
+        return timestamp;
     },
     {
         summary: '将数据转换为 Unix 毫秒时间戳',
-        params: { datetime: '要转换的数据，默认为当前时间' },
-        paramsType: { datetime: 'number | string' },
-        returnsType: 'number',
+        params: {
+            datetime: '要转换的数据，默认为当前时间',
+            fallback: '转换失败时的返回值',
+        },
+        paramsType: { datetime: 'number | string', fallback: 'any' },
+        returnsType: 'number | type(fallback)',
         examples: ['to_timestamp("1970-01-01T00:00:00Z") // 0'],
     },
 );
 
 export const to_datetime = VmLib(
-    (datetime, offset) => {
-        const timestamp = to_timestamp(datetime);
-        if (!isFinite(timestamp)) return null;
-        const o = $ToNumber(offset ?? 0) || 0;
+    (datetime, offset, fallback) => {
+        const timestamp = getTimestamp(datetime, fallback !== undefined);
+        if (timestamp == null) return fallback;
+        const o = expectNumberRange('offset', offset ?? 0, -24, 24);
         const dateOffset = new Date(timestamp + o * 1000 * 60 * 60);
         return {
             year: dateOffset.getUTCFullYear(),
@@ -48,9 +73,10 @@ export const to_datetime = VmLib(
         params: {
             datetime: '要转换的数据，默认为当前时间',
             offset: '时区偏移量（单位：小时），默认为 0',
+            fallback: '转换失败时的返回值',
         },
-        paramsType: { datetime: 'number | string', offset: 'number' },
-        returnsType: 'Date',
+        paramsType: { datetime: 'number | string', offset: 'number', fallback: 'any' },
+        returnsType: 'Date | type(fallback)',
         examples: [
             `
 to_datetime(0)
@@ -65,16 +91,19 @@ to_datetime(0)
 );
 
 export const to_iso8601 = VmLib(
-    (datetime) => {
-        const timestamp = to_timestamp(datetime);
-        if (!isFinite(timestamp)) return null;
+    (datetime, fallback) => {
+        const timestamp = getTimestamp(datetime, fallback !== undefined);
+        if (timestamp == null) return fallback;
         return new Date(timestamp).toISOString();
     },
     {
         summary: '将数据转换为 ISO 8601 格式的字符串',
-        params: { datetime: '要转换的数据，默认为当前时间' },
-        paramsType: { datetime: 'number | string' },
-        returnsType: 'string',
+        params: {
+            datetime: '要转换的数据，默认为当前时间',
+            fallback: '转换失败时的返回值',
+        },
+        paramsType: { datetime: 'number | string', fallback: 'any' },
+        returnsType: 'string | type(fallback)',
         examples: ['to_iso8601(0) // "1970-01-01T00:00:00.000Z"'],
     },
 );

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

@@ -1,44 +1,53 @@
-import { $ToString, $ToNumber, $ToBoolean, $Format } from '../../operations.js';
-import { required, VmLib } from '../_helpers.js';
+import { toBoolean, toFormat, toNumber, toString } from '../../../helpers/convert.js';
+import { expectString, required, VmLib } from '../helpers.js';
 
 export const to_string = VmLib(
-    (data) => {
+    (data, fallback) => {
         required('data', data, '');
-        return $ToString(data);
+        return toString(data, fallback);
     },
     {
         summary: '将数据转换为字符串',
-        params: { data: '要转换的数据' },
-        paramsType: { data: 'any' },
-        returnsType: 'string',
+        params: {
+            data: '要转换的数据',
+            fallback: '转换失败时的返回值',
+        },
+        paramsType: { data: 'any', fallback: 'any' },
+        returnsType: 'string | type(fallback)',
         examples: ['to_string([1, 2]) // "1, 2"'],
     },
 );
 
 export const to_number = VmLib(
-    (data) => {
+    (data, fallback) => {
         required('data', data, Number.NaN);
-        return $ToNumber(data);
+        return toNumber(data, fallback);
     },
     {
         summary: '将数据转换为数字',
-        params: { data: '要转换的数据' },
-        paramsType: { data: 'any' },
-        returnsType: 'number',
+        params: {
+            data: '要转换的数据',
+            fallback: '转换失败时的返回值',
+        },
+        paramsType: { data: 'any', fallback: 'any' },
+        returnsType: 'number | type(fallback)',
         examples: ['to_number("1.5") // 1.5'],
     },
 );
 
 export const to_boolean = VmLib(
-    (data) => {
+    (data, fallback) => {
         required('data', data, false);
-        return $ToBoolean(data);
+        return toBoolean(data, fallback);
     },
     {
         summary: '将数据转换为布尔值',
-        params: { data: '要转换的数据' },
-        paramsType: { data: 'any' },
-        returnsType: 'boolean',
+        params: {
+            data: '要转换的数据',
+            fallback: '转换失败时的返回值',
+        },
+        paramsType: { data: 'any', fallback: 'any' },
+        returnsType: 'boolean | type(fallback)',
         examples: ['to_boolean(nil) // false'],
     },
 );
@@ -46,7 +55,7 @@ export const to_boolean = VmLib(
 export const format = VmLib(
     (data, format) => {
         required('data', data, '');
-        return $Format(data, format);
+        return toFormat(data, expectString('format', format));
     },
     {
         summary: '将数据格式化为指定格式的字符串',

package/src/vm/lib/{_helpers.ts → helpers.ts}

@@ -1,44 +1,59 @@
 import type { Writable } from 'type-fest';
-import { VmError } from '../error.js';
-import { $ToNumber, $Type } from '../operations.js';
-import {
-    isVmArray,
-    isVmFunction,
-    type VmExtern,
-    type VmFunction,
-    type VmAny,
-    type VmArray,
-    type VmValue,
-    isVmRecord,
-    type VmRecord,
-    type VmModule,
-    isVmPrimitive,
-    type VmConst,
-    isVmConst,
-    VM_ARRAY_MAX_LENGTH,
-    isVmCallable,
+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 { display } from '../../helpers/serialize.js';
+import { isVmArray, isVmFunction, isVmPrimitive, isVmConst, isVmCallable, isVmRecord } from '../../helpers/types.js';
+import { VmError } from '../../helpers/error.js';
+import type {
+    VmExtern,
+    VmFunction,
+    VmAny,
+    VmArray,
+    VmValue,
+    VmRecord,
+    VmModule,
+    VmConst,
+    VmFunctionLike,
+    VmFunctionOption,
 } from '../types/index.js';
-import type { VmFunctionLike, VmFunctionOption } from '../types/function.js';
 import { Cp } from '../helpers.js';
-import { isNaN, entries, fromEntries } from '../../helpers/utils.js';
 
 /** 抛出异常 */
 export function throwError(message: string, recovered: VmAny | (() => VmAny)): never {
     const recoveredValue = typeof recovered === 'function' && !isVmFunction(recovered) ? recovered() : recovered;
     throw new VmError(message, recoveredValue);
 }
+/** 描述参数 */
+type ParamIndex = number | string | null;
+/** 描述参数 */
+export function describeParam(name: ParamIndex): string {
+    if (name == null) return 'Value';
+    if (typeof name == 'string') {
+        if (!name) return 'Argument';
+        return `Argument '${name}'`;
+    }
+    const pos = name <= 0 ? 'first' : name <= 1 ? 'second' : `${name + 1}th`;
+    return `Argument at the ${pos} position`;
+}
 
 /** 抛出预期外类型异常 */
 export function throwUnexpectedTypeError(
-    name: number | string,
+    name: ParamIndex,
+    expected: string,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): never {
+    throwError(`${describeParam(name)} is not ${expected}: ${display(value)}`, recovered);
+}
+/** 抛出预期外类型异常 */
+export function throwUnconvertedTypeError(
+    name: ParamIndex,
     expected: string,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): never {
-    const actual = $Type(value);
-    if (typeof name == 'string') throwError(`Expected ${expected} for parameter '${name}', got ${actual}`, recovered);
-    const pos = name <= 0 ? 'first' : name <= 1 ? 'second' : name + 1 + 'th';
-    throwError(`Expected ${expected} at the ${pos} position, got ${actual}`, recovered);
+    throwError(`${describeParam(name)} cannot be converted to ${expected}: ${display(value)}`, recovered);
 }
 
 /** 重新抛出异常 */
@@ -49,20 +64,86 @@ export function rethrowError(prefix: string, error: unknown, recovered: VmAny |
 
 /** 标记参数为必须项 */
 export function required<const T = VmValue>(
-    name: number | string,
+    name: ParamIndex,
     value: T | undefined,
     recovered: VmAny | (() => VmAny),
 ): asserts value is T {
     if (value === undefined) {
-        if (typeof name == 'string') throwError(`Missing required parameter '${name}'`, recovered);
-        const pos = name <= 0 ? 'first' : name <= 1 ? 'second' : name + 1 + 'th';
-        throwError(`Missing required parameter at the ${pos} position`, recovered);
+        throwError(`${describeParam(name)} is required`, recovered);
     }
 }
 
+/** 标记并转换参数为数字 */
+export function expectNumber(name: ParamIndex, value: VmAny): number {
+    required(name, value, Number.NaN);
+    const v = toNumber(value, null);
+    if (v == null) {
+        throwUnconvertedTypeError(name, 'number', value, Number.NaN);
+    }
+    return v;
+}
+/** 标记并转换参数为数字 */
+export function expectNumberRange(name: ParamIndex, value: VmAny, min: number, max: number): number {
+    const v = expectNumber(name, value);
+    if (!isFinite(v)) {
+        throwError(`${describeParam(name)} is not a finite number: ${display(value)}`, Number.NaN);
+    }
+    if (v < min) {
+        throwError(`${describeParam(name)} is less than minimum value ${min}: ${display(value)}`, min);
+    }
+    if (v > max) {
+        throwError(`${describeParam(name)} is greater than maximum value ${max}: ${display(value)}`, max);
+    }
+    return v;
+}
+/** 标记并转换参数为整数 */
+export function expectIntegerRange(name: ParamIndex, value: VmAny, min: number, max: number): number {
+    const i = expectInteger(name, value);
+    if (i < min) {
+        throwError(`${describeParam(name)} is less than minimum value ${min}: ${display(value)}`, min);
+    }
+    if (i > max) {
+        throwError(`${describeParam(name)} is greater than maximum value ${max}: ${display(value)}`, max);
+    }
+    return i;
+}
+/** 标记并转换参数为整数 */
+export function expectInteger(name: ParamIndex, value: VmAny): number {
+    required(name, value, 0);
+    const v = toNumber(value, null);
+    if (v == null) {
+        throwUnconvertedTypeError(name, 'integer', value, 0);
+    }
+    const i = Math.trunc(v);
+    if (!isSafeInteger(i)) {
+        throwUnconvertedTypeError(name, 'integer', value, 0);
+    }
+    return i;
+}
+
+/** 标记并转换参数为布尔值 */
+export function expectBoolean(name: ParamIndex, value: VmAny): boolean {
+    required(name, value, false);
+    const v = toBoolean(value, null);
+    if (v == null) {
+        throwUnconvertedTypeError(name, 'boolean', value, false);
+    }
+    return v;
+}
+
+/** 标记并转换参数为字符串 */
+export function expectString(name: ParamIndex, value: VmAny): string {
+    required(name, value, '');
+    const v = toString(value, null);
+    if (v == null) {
+        throwUnconvertedTypeError(name, 'string', value, '');
+    }
+    return v;
+}
+
 /** 标记参数为数组 */
 export function expectArray(
-    name: number | string,
+    name: ParamIndex,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmArray {
@@ -74,7 +155,7 @@ export function expectArray(
 
 /** 标记参数为记录 */
 export function expectRecord(
-    name: number | string,
+    name: ParamIndex,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmRecord {
@@ -86,7 +167,7 @@ export function expectRecord(
 
 /** 标记参数为数组或记录 */
 export function expectArrayOrRecord(
-    name: number | string,
+    name: ParamIndex,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmArray | VmRecord {
@@ -98,7 +179,7 @@ export function expectArrayOrRecord(
 
 /** 标记参数为复合类型 */
 export function expectCompound(
-    name: number | string,
+    name: ParamIndex,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmArray | VmRecord | VmModule | VmExtern {
@@ -110,7 +191,7 @@ export function expectCompound(
 
 /** 标记参数为常量 */
 export function expectConst(
-    name: number | string,
+    name: ParamIndex,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmConst {
@@ -122,7 +203,7 @@ export function expectConst(
 
 /** 标记为可调用 */
 export function expectCallable(
-    name: number | string,
+    name: ParamIndex,
     value: VmAny,
     recovered: VmAny | (() => VmAny),
 ): asserts value is VmFunction | VmExtern {
@@ -135,20 +216,27 @@ export function expectCallable(
 /** Get numbers from the arguments. */
 export function getNumbers(args: readonly VmAny[]): number[] {
     if (args.length === 0) return [];
-    if (args.length === 1 && isVmArray(args[0])) args = args[0];
+    let useFirst = false;
+    if (args.length === 1 && isVmArray(args[0])) {
+        args = args[0];
+        useFirst = true;
+    }
     const numbers: number[] = [];
-    for (const arg of args) {
-        if (arg == null) continue;
-        numbers.push($ToNumber(arg));
+    for (let len = args.length, i = 0; i < len; i++) {
+        numbers.push(expectNumber(useFirst ? null : i, args[i]));
     }
     return numbers;
 }
 
 /** 将值转为数组长度 */
 export function arrayLen(len: number | null | undefined): number {
-    if (len == null || isNaN(len) || len <= 0) return 0;
+    if (len == null || isNaN(len) || len <= -1) {
+        throwError('Array length must be a non-negative integer', null);
+    }
     len = Math.trunc(len);
-    if (len > VM_ARRAY_MAX_LENGTH) throwError(`Array length exceeds maximum limit of ${VM_ARRAY_MAX_LENGTH}`, null);
+    if (len > VM_ARRAY_MAX_LENGTH) {
+        throwError(`Array length exceeds maximum limit of ${VM_ARRAY_MAX_LENGTH}`, null);
+    }
     return len;
 }
 

package/src/vm/lib/index.ts

@@ -0,0 +1,16 @@
+import * as global from './global/index.js';
+import * as mods from './mod/index.js';
+import { VmSharedContext } 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');
+}
+
+for (const [name, value] of entries(mods)) {
+    const mod = createModule(name, value as Record<string, RawValue>);
+    VmSharedContext[name] = wrapEntry(name, mod, 'global');
+}
+
+export const lib = Object.freeze(Object.assign(create(null), global, mods));

package/src/vm/lib/{_loader.ts → loader.ts}

@@ -1,20 +1,14 @@
 import { VmFunction, VmModule, type VmConst, type VmFunctionLike, type VmImmutable } from '../types/index.js';
 import { create, defineProperty, entries } from '../../helpers/utils.js';
-import { VmSharedContext } from '../types/context.js';
 
-import type { VmLib, VmLibOption } from './_helpers.js';
-import * as global from './global/index.js';
-
-for (const [name, value] of entries(global)) {
-    VmSharedContext[name] = wrapEntry(name, value as RawValue, 'global');
-}
+import type { VmLib, VmLibOption } from './helpers.js';
 
 /** 原始值 */
-type RawValue = VmLib | VmConst | VmModule;
+export type RawValue = VmLib | VmConst | VmModule;
 /** 包装值 */
 type ToWrappedValue<V extends RawValue> = V extends VmFunctionLike ? VmFunction<V> : V;
 /** 包装值 */
-function wrapEntry<const T extends RawValue>(name: string, value: T, module: string): ToWrappedValue<T> {
+export function wrapEntry<const T extends RawValue>(name: string, value: T, module: string): ToWrappedValue<T> {
     if (typeof value == 'function') {
         if (value.name !== name) {
             // 如果函数名和导出名不一致，则重命名
@@ -47,5 +41,3 @@ export function createModule<const T extends Record<string, RawValue>>(name: str
     }
     return new VmModule(name, mod) as ToWrappedModule<T>;
 }
-
-export const lib = global;

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

@@ -0,0 +1 @@
+export * as matrix from './matrix.js';

package/src/vm/lib/{global/mod → mod}/matrix.ts

@@ -1,7 +1,8 @@
-import { isArray } from '../../../../helpers/utils.js';
-import { Cp } from '../../../helpers.js';
-import { $Add, $Call, $Div, $Mul, $Sub, $ToNumber } from '../../../operations.js';
-import { isVmArray, isVmConst, type VmAny, type VmArray, type VmConst, type VmValue } from '../../../types/index.js';
+import { toNumber } from '../../../helpers/convert.js';
+import { isArray } from '../../../helpers/utils.js';
+import { Cp } from '../../helpers.js';
+import { $Add, $Call, $Div, $Mul, $Sub } from '../../operations.js';
+import { isVmArray, isVmConst, type VmAny, type VmArray, type VmConst, type VmValue } from '../../types/index.js';
 import {
     VmLib,
     expectArray,
@@ -12,7 +13,8 @@ import {
     getNumbers,
     arrayLen,
     map,
-} from '../../_helpers.js';
+    expectInteger,
+} from '../helpers.js';
 
 /** 计算尺寸 */
 function sizeImpl(matrix: VmValue): [] | [number] | [number, number] {
@@ -35,7 +37,7 @@ function sizeImpl(matrix: VmValue): [] | [number] | [number, number] {
 
 /** 数组元素转为 number */
 function num(v: VmConst | undefined): number {
-    return $ToNumber(v ?? null);
+    return toNumber(v, undefined);
 }
 
 export const size = VmLib(
@@ -535,7 +537,7 @@ export const identity = VmLib(
 export const diagonal = VmLib(
     (x, k = 0) => {
         expectArray('x', x, []);
-        const fk = Math.round($ToNumber(k) || 0);
+        const fk = expectInteger('k', k);
         if (x.every((e) => isArray(e))) {
             // 获取对角线元素
             const diag: VmConst[] = [];