@mirascript/mirascript 0.1.0

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

@@ -0,0 +1,67 @@
+import { isVmArray, isVmRecord, type VmConst } from '../../../types/index.js';
+import { VmLib, expectArrayOrRecord, expectCompound } from '../../_helpers.js';
+import { keys as _keys, values as _values, entries as _entries } from '../../../../helpers/utils.js';
+
+export const keys = VmLib(
+    (data) => {
+        expectCompound('data', data, []);
+        if (isVmArray(data)) {
+            const arr: number[] = [];
+            const len = data.length;
+            for (let i = 0; i < len; i++) {
+                arr.push(i);
+            }
+            return arr;
+        }
+        if (isVmRecord(data)) {
+            return _keys(data);
+        }
+        return data.keys();
+    },
+    {
+        summary: '返回数组、记录、外部对象或模块的键列表',
+        params: { data: '要获取键的数组、记录、外部对象或模块' },
+        paramsType: { data: 'array | record | extern | module' },
+        returnsType: '(string | number)[]',
+        examples: ['keys([10, 20]) // [0, 1]', 'keys((10, 20)) // ["0", "1"]'],
+    },
+);
+
+export const values = VmLib(
+    (data) => {
+        expectArrayOrRecord('data', data, []);
+        if (isVmArray(data)) {
+            return data;
+        }
+        return _values(data);
+    },
+    {
+        summary: '返回数组或记录的值列表',
+        params: { data: '要获取值的数组或记录' },
+        paramsType: { data: 'array | record' },
+        returnsType: 'array',
+        examples: ['values((a: 1, b: 2)) // [1, 2]'],
+    },
+);
+
+export const entries = VmLib(
+    (data) => {
+        expectArrayOrRecord('data', data, []);
+        if (isVmArray(data)) {
+            const arr: Array<{ 0: number; 1: VmConst }> = [];
+            const len = data.length;
+            for (let i = 0; i < len; i++) {
+                arr.push({ 0: i, 1: data[i] ?? null });
+            }
+            return arr;
+        }
+        return _entries(data).map(([key, value]) => ({ 0: key, 1: value ?? null }));
+    },
+    {
+        summary: '返回数组或记录的键值对列表',
+        params: { data: '要获取键值对的数组或记录' },
+        paramsType: { data: 'array | record' },
+        returnsType: '(string | number, any)[]',
+        examples: ['entries([1]) // [(0, 1)]', 'entries((a: 1)) // [("a", 1)]'],
+    },
+);

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

@@ -0,0 +1,49 @@
+import { entries } from '../../../../helpers/utils.js';
+import { Cp } from '../../../helpers.js';
+import { $Call, $ToBoolean } from '../../../operations.js';
+import { type VmValue, isVmArray } from '../../../types/index.js';
+import { VmLib, expectArrayOrRecord, expectCallable } from '../../_helpers.js';
+
+export const find = VmLib(
+    (data, predicate) => {
+        expectArrayOrRecord('data', data, null);
+        expectCallable('predicate', predicate, data);
+        const p = (value: VmValue, key: string | number, data: VmValue) => {
+            const ret = $Call(predicate, [value, key, data]);
+            return $ToBoolean(ret);
+        };
+        if (isVmArray(data)) {
+            const { length } = data;
+            for (let i = 0; i < length; i++) {
+                Cp();
+                const value = data[i] ?? null;
+                const ret = p(value, i, data);
+                if (!ret) continue;
+                return { 0: i, 1: value };
+            }
+            return null;
+        } else {
+            for (const [key, v] of entries(data)) {
+                Cp();
+                const value = v ?? null;
+                const ret = p(value, key, data);
+                if (!ret) continue;
+                return { 0: key, 1: value };
+            }
+            return null;
+        }
+    },
+    {
+        summary: '查找数组或记录中的键值对，返回第一个满足条件的键值对',
+        params: {
+            data: '查的数组或记录',
+            predicate: '用于测试每个键值对的函数，返回 true 或 false',
+        },
+        paramsType: {
+            data: 'array | record',
+            predicate: 'fn(value: any, key: number | string | nil, input: type(data)) -> boolean',
+        },
+        returnsType: '(string | number, any) | nil',
+        examples: ['find([3, 5, 8], fn (v) { v % 2 == 0 }) // (2, 8)'],
+    },
+);

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

@@ -0,0 +1,16 @@
+import { $ToNumber } from '../../../operations.js';
+import { VmLib, expectArray } from '../../_helpers.js';
+
+export const flatten = VmLib(
+    (data, depth = 1) => {
+        expectArray('data', data, data);
+        return data.flat($ToNumber(depth) as 1);
+    },
+    {
+        summary: '将数组扁平化',
+        params: { data: '要扁平化的数组', depth: '扁平化的深度，默认为 1' },
+        paramsType: { data: 'array', depth: 'number' },
+        returnsType: 'array',
+        examples: ['flatten([[1, 2], [3, [4]]], 2) // [1, 2, 3, 4]'],
+    },
+);

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

@@ -0,0 +1,11 @@
+export * from './with.js';
+export * from './entries.js';
+export * from './len.js';
+export * from './map-filter.js';
+export * from './find.js';
+export * from './flatten.js';
+export * from './reverse.js';
+export * from './zip.js';
+export * from './all-any.js';
+export * from './sort.js';
+export * from './repeat.js';

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

@@ -0,0 +1,15 @@
+import { VmLib, expectArray } from '../../_helpers.js';
+
+export const len = VmLib(
+    (arr) => {
+        expectArray('arr', arr, Number.NaN);
+        return arr.length;
+    },
+    {
+        summary: '返回数组的长度',
+        params: { arr: '要求长度的数组' },
+        paramsType: { arr: 'array' },
+        returnsType: 'number',
+        examples: ['len([1, 2, 3]) // 3'],
+    },
+);

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

@@ -0,0 +1,82 @@
+import { $Call, $ToBoolean } from '../../../operations.js';
+import { isVmConst, type VmAny, type VmValue } from '../../../types/index.js';
+import { VmLib, expectCallable, expectConst, map as mapImpl } from '../../_helpers.js';
+
+export * from './with.js';
+export * from './entries.js';
+export * from './len.js';
+
+/** map 和 filter 的实现 */
+function mapImplWrapped(
+    data: VmAny,
+    fnName: string,
+    fn: VmAny,
+    mapper: (fn: VmValue, value: VmValue, index: number | string | null, data: VmValue) => VmValue | undefined,
+): VmValue {
+    expectConst('data', data, null);
+    expectCallable(fnName, fn, data);
+    return mapImpl(data, (value, index, data) => {
+        const ret = mapper(fn, value, index, data);
+        if (ret === undefined || isVmConst(ret)) return ret;
+        return null;
+    });
+}
+
+export const map = VmLib(
+    (data, f) => mapImplWrapped(data, 'f', f, (fn, value, key, data) => $Call(fn, [value, key, data])),
+    {
+        summary: '对数组或记录中的每个元素应用函数，并返回结果',
+        params: {
+            data: '要映射的数组或记录',
+            f: '应用于每个元素的函数',
+        },
+        paramsType: {
+            data: 'array | record',
+            f: 'fn(value: any, key: number | string | nil, input: type(data)) -> any',
+        },
+        returnsType: 'type(data)',
+        examples: ['map([1, 2, 3], fn (v) { v * v }) // [1, 4, 9]'],
+    },
+);
+
+export const filter = VmLib(
+    (data, predicate) =>
+        mapImplWrapped(data, 'predicate', predicate, (fn, value, key, data) => {
+            const ret = $Call(fn, [value, key, data]);
+            return $ToBoolean(ret) ? value : undefined;
+        }),
+    {
+        summary: '过滤数组或记录中的元素，返回满足条件的元素',
+        params: {
+            data: '要过滤的数组或记录',
+            predicate: '用于测试每个元素的函数，返回 true 或 false',
+        },
+        paramsType: {
+            data: 'array | record',
+            predicate: 'fn(value: any, key: number | string | nil, input: type(data)) -> boolean',
+        },
+        returnsType: 'type(data)',
+        examples: ['filter([1, 2, 3, 4], fn (v) { v % 2 == 0 }) // [2, 4]'],
+    },
+);
+
+export const filter_map = VmLib(
+    (data, f) =>
+        mapImplWrapped(data, 'f', f, (fn, value, key, data) => {
+            const ret = $Call(fn, [value, key, data]);
+            return ret ?? undefined;
+        }),
+    {
+        summary: '对数组或记录中的每个元素应用函数，并返回非 nil 的结果',
+        params: {
+            data: '要映射的数组或记录',
+            f: '应用于每个元素的函数，返回 nil 或非 nil 的值',
+        },
+        paramsType: {
+            data: 'array | record',
+            f: 'fn(value: any, key: number | string | nil, input: type(data)) -> any | nil',
+        },
+        returnsType: 'type(data)',
+        examples: ['filter_map([1, 2, 3], fn (v) { if v % 2 == 0 { v * v } else { nil } }) // [4]'],
+    },
+);

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

@@ -0,0 +1,28 @@
+import { $ToNumber } from '../../../operations.js';
+import type { VmConst } from '../../../types/index.js';
+import { arrayLen, expectConst, required, VmLib } from '../../_helpers.js';
+
+export const repeat = VmLib(
+    (data, times) => {
+        expectConst('data', data, []);
+        required('times', times, []);
+        const n = arrayLen($ToNumber(times));
+        const result: VmConst[] = [];
+        result.length = n;
+        result.fill(data);
+        return result;
+    },
+    {
+        summary: '创建一个包含重复元素的数组',
+        params: {
+            data: '要重复的元素',
+            times: '重复的次数，必须是非负整数',
+        },
+        paramsType: {
+            data: 'any',
+            times: 'number',
+        },
+        returnsType: 'type(data)[]',
+        examples: ['repeat(0, 5) // [0, 0, 0, 0, 0]', 'repeat("a", 3) // ["a", "a", "a"]'],
+    },
+);

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

@@ -0,0 +1,17 @@
+import { VmLib, expectArray } from '../../_helpers.js';
+
+export const reverse = VmLib(
+    (arr) => {
+        expectArray('arr', arr, null);
+        const dup = [...arr];
+        dup.reverse();
+        return dup;
+    },
+    {
+        summary: '返回数组的反转副本',
+        params: { arr: '要反转的数组' },
+        paramsType: { arr: 'array' },
+        returnsType: 'array',
+        examples: ['reverse([1, 2, 3]) // [3, 2, 1]'],
+    },
+);

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

@@ -0,0 +1,88 @@
+import { $Call, $ToNumber } from '../../../operations.js';
+import type { VmAny, VmConst, VmValue } from '../../../types/index.js';
+import { VmLib, expectArray, expectCallable } from '../../_helpers.js';
+
+/** 默认比较 */
+function defaultCompare(a: VmValue, b: VmValue): number {
+    a ??= '';
+    b ??= '';
+    if (typeof a == 'string' && typeof b == 'string') {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+    }
+    if (Object.is(a, b)) return 0;
+    const an = $ToNumber(a) || 0;
+    const bn = $ToNumber(b) || 0;
+    return an - bn;
+}
+
+/** 获取比较函数 */
+function cmp(comparator: VmAny, recovered: VmValue): typeof defaultCompare {
+    if (comparator == null) return defaultCompare;
+    expectCallable('comparator', comparator, recovered);
+    return (a: VmValue, b: VmValue) => {
+        const ret = $Call(comparator, [a, b]);
+        return $ToNumber(ret);
+    };
+}
+
+export const sort = VmLib(
+    (data, comparator) => {
+        expectArray('data', data, null);
+        const compare = cmp(comparator, data);
+        const arr: VmConst[] = [];
+        for (const v of data) {
+            arr.push(v ?? null);
+        }
+        arr.sort(compare);
+        return arr;
+    },
+    {
+        summary: '对数组中的元素进行排序，并返回排序后的结果',
+        params: {
+            data: '要排序的数组',
+            comparator: '用于比较两个元素的函数，返回一个数字，表示它们的相对顺序，默认按升序排列',
+        },
+        paramsType: {
+            data: 'array',
+            comparator: 'fn(a: any, b: any) -> number',
+        },
+        returnsType: 'array',
+        examples: ['sort(["c", "a", "b"]) // ["a", "b", "c"]'],
+    },
+);
+
+export const sort_by = VmLib(
+    (data, key_fn, comparator) => {
+        expectArray('data', data, null);
+        expectCallable('key_fn', key_fn, data);
+        const compare = cmp(comparator, data);
+        const arr: Array<{ o: VmConst; k: VmValue }> = [];
+        const len = data.length;
+        for (let i = 0; i < len; i++) {
+            const v = data[i] ?? null;
+            arr.push({
+                o: v,
+                k: $Call(key_fn, [v, i, data]),
+            });
+        }
+        arr.sort((a, b) => compare(a.k, b.k));
+        return arr.map((e) => e.o);
+    },
+    {
+        summary: '根据键函数对数组中的元素进行排序，并返回排序后的结果',
+        params: {
+            data: '要排序的数组',
+            key_fn: '用于提取排序键的函数，接受一个元素并返回其排序键',
+            comparator: '用于比较两个排序键的函数，返回一个数字，表示它们的相对顺序，默认按升序排列',
+        },
+        paramsType: {
+            data: 'array',
+            key_fn: 'fn(value: any, index: number, arr: type(data)) -> any',
+            comparator: 'fn(a: any, b: any) -> number',
+        },
+        returnsType: 'array',
+        examples: ['sort_by([(0, "x"), (2, "y"), (1, "z")], fn (item) { item[0] }) // [(0, "x"), (1, "z"), (2, "y")]'],
+    },
+);

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

@@ -0,0 +1,43 @@
+import { Element } from '../../../helpers.js';
+import { $ToNumber, $ToString } from '../../../operations.js';
+import { isVmArray, type VmConst } from '../../../types/index.js';
+import { VmLib, expectArrayOrRecord, throwError } from '../../_helpers.js';
+import { isSafeInteger } from '../../../../helpers/utils.js';
+
+const _with = VmLib(
+    (data, ...entries) => {
+        expectArrayOrRecord('data', data, data);
+        if (entries.length % 2 !== 0) {
+            throwError('Expected even number of entries', data);
+        }
+        if (isVmArray(data)) {
+            const result: Array<VmConst | undefined> = [...data];
+            for (let i = 0; i < entries.length; i += 2) {
+                const index = Math.trunc($ToNumber(entries[i]));
+                if (!isSafeInteger(index) || index < 0) continue;
+                const value = entries[i + 1];
+                while (index > result.length) {
+                    result.push(null);
+                }
+                result[index] = Element(value);
+            }
+            return result;
+        } else {
+            const result: Record<string, VmConst | undefined> = { ...data };
+            for (let i = 0; i < entries.length; i += 2) {
+                const key = $ToString(entries[i]);
+                const value = entries[i + 1];
+                result[key] = Element(value);
+            }
+            return result;
+        }
+    },
+    {
+        summary: '在数组或记录中设置多个键值对',
+        params: { data: '要设置的数组或记录', '..entries': '要设置的键值对，成对出现' },
+        paramsType: { data: 'array | record', '..entries': '[..[string | number, any][]]' },
+        returnsType: 'type(data)',
+        examples: ['with([10, 20], 2, 99) // [10, 20, 99]', 'with((a: 1), "b", 2) // (a: 1, b: 2)'],
+    },
+);
+export { _with as 'with' };

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

@@ -0,0 +1,40 @@
+import { serialize } from '../../../../subtle.js';
+import { Cp } from '../../../helpers.js';
+import { isVmArray, type VmConst, type VmArray } from '../../../types/index.js';
+import { VmLib, throwError } from '../../_helpers.js';
+import { entries } from './entries.js';
+
+export const zip = VmLib(
+    (data) => {
+        const ets = entries(data);
+        let len = 0;
+        for (const { 0: key, 1: arr } of ets) {
+            if (!isVmArray(arr)) {
+                throwError(`data[${serialize(key)}] is not an array`, null);
+            }
+            len = Math.max(len, arr.length);
+        }
+        if (len === 0) return [];
+        const result: Array<Record<string | number, VmConst>> = [];
+        const isArr = isVmArray(data);
+        for (let i = 0; i < len; i++) {
+            Cp();
+            const obj: Record<number | string, VmConst> = isArr ? ([] as Record<number, VmConst>) : {};
+            for (const { 0: key, 1: arr } of ets) {
+                obj[key] = (arr as VmArray)[i] ?? null;
+            }
+            result.push(obj);
+        }
+        return result;
+    },
+    {
+        summary: '将数组的数组/记录转换为数组/记录的数组',
+        params: { data: '要转换的数组/记录' },
+        paramsType: { data: 'array | record' },
+        returnsType: '(array | record)[]',
+        examples: [
+            'zip((x: [1, 2], y: ["a", "b"])) // [(x: 1, y: "a"), (x: 2, y: "b")]',
+            `zip([[1, 2], ["a", "b"]]) // [[1, "a"], [2, "b"]]`,
+        ],
+    },
+);

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

@@ -0,0 +1,149 @@
+import { $ToString } from '../../operations.js';
+import { expectArray, required, VmLib } from '../_helpers.js';
+
+export const chars = VmLib(
+    (str) => {
+        required('str', str, null);
+        return [...$ToString(str)];
+    },
+    {
+        summary: '将字符串转换为字符数组',
+        params: { str: '要转换的字符串' },
+        paramsType: { str: 'string' },
+        returnsType: 'string[]',
+        examples: ['chars("Mira") // ["M", "i", "r", "a"]'],
+    },
+);
+
+export const starts_with = VmLib(
+    (str, search) => {
+        required('str', str, null);
+        required('search', search, null);
+        return $ToString(str).startsWith($ToString(search));
+    },
+    {
+        summary: '检查字符串是否以指定子串开头',
+        params: { str: '要检查的字符串', search: '要匹配的子串' },
+        paramsType: { str: 'string', search: 'string' },
+        returnsType: 'boolean',
+        examples: ['starts_with("mira", "mi") // true'],
+    },
+);
+export const ends_with = VmLib(
+    (str, search) => {
+        required('str', str, null);
+        required('search', search, null);
+        return $ToString(str).endsWith($ToString(search));
+    },
+    {
+        summary: '检查字符串是否以指定子串结尾',
+        params: { str: '要检查的字符串', search: '要匹配的子串' },
+        paramsType: { str: 'string', search: 'string' },
+        returnsType: 'boolean',
+        examples: ['ends_with("mira", "ra") // true'],
+    },
+);
+
+export const contains = VmLib(
+    (str, search) => {
+        required('str', str, null);
+        required('search', search, null);
+        return $ToString(str).includes($ToString(search));
+    },
+    {
+        summary: '检查字符串是否包含指定子串',
+        params: { str: '要检查的字符串', search: '要匹配的子串' },
+        paramsType: { str: 'string', search: 'string' },
+        returnsType: 'boolean',
+        examples: ['contains("hello", "ll") // true'],
+    },
+);
+
+export const trim_start = VmLib(
+    (str) => {
+        required('str', str, null);
+        return $ToString(str).trimStart();
+    },
+    {
+        summary: '去除字符串开头的空白字符',
+        params: { str: '要处理的字符串' },
+        paramsType: { str: 'string' },
+        returnsType: 'string',
+        examples: ['trim_start("  mira") // "mira"'],
+    },
+);
+
+export const trim_end = VmLib(
+    (str) => {
+        required('str', str, null);
+        return $ToString(str).trimEnd();
+    },
+    {
+        summary: '去除字符串结尾的空白字符',
+        params: { str: '要处理的字符串' },
+        paramsType: { str: 'string' },
+        returnsType: 'string',
+        examples: ['trim_end("mira  ") // "mira"'],
+    },
+);
+
+export const trim = VmLib(
+    (str) => {
+        required('str', str, null);
+        return $ToString(str).trim();
+    },
+    {
+        summary: '去除字符串两端的空白字符',
+        params: { str: '要处理的字符串' },
+        paramsType: { str: 'string' },
+        returnsType: 'string',
+        examples: ['trim("  mira  ") // "mira"'],
+    },
+);
+
+export const replace = VmLib(
+    (str, search, replacement = '') => {
+        required('str', str, null);
+        required('search', search, str);
+        return $ToString(str).replaceAll($ToString(search), $ToString(replacement));
+    },
+    {
+        summary: '替换字符串中的指定子串',
+        params: { str: '要处理的字符串', search: '要替换的子串', replacement: '替换后的字符串' },
+        paramsType: { str: 'string', search: 'string', replacement: 'string' },
+        returnsType: 'string',
+        examples: ['replace("foo bar foo", "foo", "baz") // "baz bar baz"'],
+    },
+);
+
+export const split = VmLib(
+    (str, separator = '') => {
+        required('str', str, null);
+        const s = $ToString(str);
+        const p = $ToString(separator);
+        if (!p) return [...s];
+        return s.split(p);
+    },
+    {
+        summary: '将字符串拆分为子串数组',
+        params: { str: '要拆分的字符串', separator: '分隔符' },
+        paramsType: { str: 'string', separator: 'string' },
+        returnsType: 'string[]',
+        examples: ['split("a,b,c", ",") // ["a", "b", "c"]'],
+    },
+);
+
+export const join = VmLib(
+    (arr, separator = '') => {
+        expectArray('arr', arr, null);
+        const s = $ToString(separator);
+        return arr.map((v) => $ToString(v)).join(s);
+    },
+    {
+        summary: '将字符串数组连接为单个字符串',
+        params: { arr: '要连接的字符串数组', separator: '分隔符' },
+        paramsType: { arr: 'string[]', separator: 'string' },
+        returnsType: 'string',
+        examples: ['join(["a", "b", "c"], "-") // "a-b-c"'],
+    },
+);