@mirascript/mirascript 0.1.15 → 0.1.17

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

@@ -1,10 +1,8 @@
-import { $ToString } from '../../operations.js';
-import { expectArray, required, VmLib } from '../_helpers.js';
+import { expectArray, expectString, VmLib } from '../helpers.js';
 
 export const chars = VmLib(
     (str) => {
-        required('str', str, null);
-        return [...$ToString(str)];
+        return [...expectString('str', str)];
     },
     {
         summary: '将字符串转换为字符数组',
@@ -17,9 +15,7 @@ export const chars = VmLib(
 
 export const starts_with = VmLib(
     (str, search) => {
-        required('str', str, null);
-        required('search', search, null);
-        return $ToString(str).startsWith($ToString(search));
+        return expectString('str', str).startsWith(expectString('search', search));
     },
     {
         summary: '检查字符串是否以指定子串开头',
@@ -31,9 +27,7 @@ export const starts_with = VmLib(
 );
 export const ends_with = VmLib(
     (str, search) => {
-        required('str', str, null);
-        required('search', search, null);
-        return $ToString(str).endsWith($ToString(search));
+        return expectString('str', str).endsWith(expectString('search', search));
     },
     {
         summary: '检查字符串是否以指定子串结尾',
@@ -46,9 +40,7 @@ export const ends_with = VmLib(
 
 export const contains = VmLib(
     (str, search) => {
-        required('str', str, null);
-        required('search', search, null);
-        return $ToString(str).includes($ToString(search));
+        return expectString('str', str).includes(expectString('search', search));
     },
     {
         summary: '检查字符串是否包含指定子串',
@@ -61,8 +53,7 @@ export const contains = VmLib(
 
 export const trim_start = VmLib(
     (str) => {
-        required('str', str, null);
-        return $ToString(str).trimStart();
+        return expectString('str', str).trimStart();
     },
     {
         summary: '去除字符串开头的空白字符',
@@ -75,8 +66,7 @@ export const trim_start = VmLib(
 
 export const trim_end = VmLib(
     (str) => {
-        required('str', str, null);
-        return $ToString(str).trimEnd();
+        return expectString('str', str).trimEnd();
     },
     {
         summary: '去除字符串结尾的空白字符',
@@ -89,8 +79,7 @@ export const trim_end = VmLib(
 
 export const trim = VmLib(
     (str) => {
-        required('str', str, null);
-        return $ToString(str).trim();
+        return expectString('str', str).trim();
     },
     {
         summary: '去除字符串两端的空白字符',
@@ -103,9 +92,10 @@ export const trim = VmLib(
 
 export const replace = VmLib(
     (str, search, replacement = '') => {
-        required('str', str, null);
-        required('search', search, str);
-        return $ToString(str).replaceAll($ToString(search), $ToString(replacement));
+        return expectString('str', str).replaceAll(
+            expectString('search', search),
+            expectString('replacement', replacement),
+        );
     },
     {
         summary: '替换字符串中的指定子串',
@@ -118,9 +108,8 @@ export const replace = VmLib(
 
 export const split = VmLib(
     (str, separator = '') => {
-        required('str', str, null);
-        const s = $ToString(str);
-        const p = $ToString(separator);
+        const s = expectString('str', str);
+        const p = expectString('separator', separator);
         if (!p) return [...s];
         return s.split(p);
     },
@@ -136,8 +125,8 @@ export const split = VmLib(
 export const join = VmLib(
     (arr, separator = '') => {
         expectArray('arr', arr, null);
-        const s = $ToString(separator);
-        return arr.map((v) => $ToString(v)).join(s);
+        const s = expectString('separator', separator);
+        return arr.map((v) => expectString(null, v)).join(s);
     },
     {
         summary: '将字符串数组连接为单个字符串',

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/to-number.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/index.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/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';
+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;
 }
 
@@ -191,7 +279,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,
@@ -200,7 +288,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;
@@ -208,5 +296,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

@@ -0,0 +1,16 @@
+import * as global from './global/index.js';
+import * as mods from './mod/index.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)) {
+    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>);
+    VM_SHARED_CONTEXT[name] = wrapEntry(name, mod, 'global');
+}
+
+export const lib: Readonly<typeof global & typeof mods> = 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';