Skip to content

Latest commit

 

History

History
528 lines (507 loc) · 28.7 KB

File metadata and controls

528 lines (507 loc) · 28.7 KB

NASL 逻辑 - 内置工具函数

内置工具函数

// 内置函数库
declare namespace nasl.util {
    /* @param timeZone: 时区,默认为 'global' 表示全局配置的时区,'user' 表示当前用户的时区,'UTC' 表示世界标准时间,其他比如 'Asia/Shanghai' 表示具体时区
     * 下面各函数的 timeZone 参数含义相同
     */

    /* 类型转换与格式化函数 */
    /**
     * 各基础数据类型之间转换
     * @typeParam T: 需要手动指定转换的目标类型
     *
     * @example
     * nasl.util.Convert<Date>(nasl.util.CurrDateTime('global')) // 将日期时间转换为日期
     * nasl.util.Convert<Integer>(nasl.util.CurrDateTime('global')) // 将日期时间转换为毫秒时间戳
     * nasl.util.Convert<DateTime>(1744030361707) // 将毫秒时间戳转换为日期时间
     * nasl.util.Convert<Integer>(3.24) // 将小数转换为整数,用于除法后赋值给整数类型
     */
    export function Convert(value: null): <T extends never>() => T;
    /**
     * 返回格式化的数字字符串
     * @param value: 待格式化的数字
     * @param digits: 小数位数
     * @param omit: 是否省略小数位数为0的部分
     * @param showGroups: 是否显示千分位分隔符
     * @param fix: 单位放置于数字的前缀还是后缀,前缀单位如'¥'、'$'等,后缀单位如'元'、'米'等
     * @param unit: 单位,如 $、元等
     */
    export function FormatNumber(value: Decimal | Integer, digits: Integer, omit: Boolean, showGroups: Boolean, fix: 'prefix' | 'suffix', unit: String): String;
    /**
     * 返回格式化百分比字符串
     * @param value: 待格式化的数字
     * @param digits: 小数位数
     * @param omit: 是否省略小数位数为0的部分
     * @param showGroups: 是否显示千分位分隔符
     */
    export function FormatPercent(value: Decimal | Integer, digits: Integer, omit: Boolean, showGroups: Boolean): String;
    /**
     * 返回格式化日期时间字符串
     * @param dateTime: 日期时间
     * @param formatter: 格式化字符串
     * @param timeZone: 时区,默认为 'global' 表示全局配置的时区,'user' 表示当前用户的时区,'UTC' 表示世界标准时间,其他比如 'Asia/Shanghai' 表示具体时区
     *
     * @example nasl.util.FormatDateTime(nasl.util.CurrDateTime('global'), 'yyyy-MM-dd HH:mm:ss', 'global') // 返回当前日期时间的格式化字符串
     * @example nasl.util.Convert<Integer>(nasl.util.FormatDateTime(nasl.util.CurrDateTime('global'), 'mm', 'global')) // 获取当前时间的分钟数
     */
    export function FormatDateTime(dateTime: DateTime, formatter: String, timeZone: String): String;
    /**
     * 返回格式化日期字符串
     * @param date: 日期
     * @param formatter: 格式化字符串
     * @example nasl.util.FormatDate(nasl.util.CurrDate('global'), 'yyyy-MM-dd')
     * @example nasl.util.Convert<Integer>(nasl.util.FormatDate(nasl.util.CurrDate('global'), 'MM', 'global')) // 获取当前月份
     */
    export function FormatDate(date: Date, formatter: String): String;
    /**
     * 返回格式化时间字符串
     * @param time: 时间
     * @param formatter: 格式化字符串
     * @example nasl.util.FormatTime(nasl.util.CurrTime('global'), 'HH:mm:ss')
     */
    export function FormatTime(time: Time, formatter: String): String;
    /**
     * 将字符串转换成其他类型
     * @example
     * nasl.util.FromString<DateTime>('2021-01-01 12:00:00')
     * nasl.util.FromString<Date>('2021-01-01')
     * nasl.util.FromString<Time>('12:00:00')
     * nasl.util.FromString<Integer>('123')
     * nasl.util.FromString<Decimal>('123.456')
     * nasl.util.FromString<Boolean>('true')
     */
    export function FromString<T extends Boolean | Integer | Decimal | Date | Time | DateTime>(value: String): T;
    /**
     * 将各类型转换成字符串
     * @example
     * nasl.util.ToString(123) // '123'
     * nasl.util.ToString(123.456) // '123.456'
     * nasl.util.ToString(true) // 'true'
     * nasl.util.ToString(nasl.util.CurrDateTime('global'), 'global') // 返回当前日期时间全局时区的格式化字符串
     */
    export function ToString(value: DateTime, timeZone: String): String;
    export function ToString(value: any): String;

    /* 字符串函数 */
    export function Length(str: String): Integer;
    export function Length<K, V>(map: Map<K, V>): Integer;
    export function Length<T>(list: List<T>): Integer;
    /**
     * 用于查找字符串中指定字段所在位置,常用的场景包括字符串匹配、字符串替换、数据校验等
     * @param str: 待查找的字符串
     * @param search: 要查找的子字符串
     * @param fromIndex: 开始查找的位置,从0开始
     * @param ignoreCase: 是否忽略大小写
     * @example nasl.util.IndexOf('abc', 'b', 0, false) // 1
     *
     * @note 比较两个字符串是否相等时,直接使用 '==' 运算符直接比较
     * @note 不可用于列表查找,列表查找请使用 ListFind/ListFindIndex 函数
     */
    export function IndexOf(str: String, search: String, fromIndex: Integer, ignoreCase: Boolean): Integer;
    /**
     * 用于连接字符串数组中的所有元素,常用的场景包括字符串拼接、数据展示等
     * @param list: 待连接的字符串数组
     * @param seperator: 连接符
     *
     * @note 当你需要拼接字符串和非字符串类型时,你只能使用模板字符串语法,如 `Hello ${name}`
     * When you need to concatenate string and non-string types, you can only use template string syntax, such as `Hello ${name}`
     *
     * @example
     * let name: String = 'world'
     * let year: Integer = 2024
     * nasl.util.Join(['Hello', name], ' ') // 'Hello world'
     * nasl.util.Join(['Hello', name, year], ' ') // Invalid
     * `Hello ${name} ${year}` // 'Hello world 2024'
     */
    export function Join(list: List<any>, seperator: String): String;
    /**
     * 用于分割字符串,返回一个列表
     * @param str: 待分割的字符串
     * @param seperator: 分割符
     * @param trail: 最后一项为 '' 时,是否保留。
     *   为 true 时,与 JS 的 split 方法一致。如:Split('abc,', ',', true) // ['abc', '']
     *   为 false 时,与 Java 的 split 方法一致。如:Split('abc,', ',', false) // ['abc']
     */
    export function Split(str: String, seperator: String | RegExp, trail: Boolean): List<String>;
    /**
     * 用于从后往前查找字符串中指定字段所在位置,常用的场景包括字符串匹配、字符串替换、数据校验等
     * @param str: 待查找的字符串
     * @param search: 要查找的子字符串
     * @param ignoreCase: 是否忽略大小写
     */
    export function LastIndexOf(str: String, search: String, ignoreCase: Boolean): Integer;
    /**
     * 用于替换字符串中指定片段, 只支持纯字符串替换
     * @param str: 待替换的字符串
     * @param search: 要替换的子字符串, 只能是纯字符串
     * @param replace: 替换的子字符串, 只能是纯字符串
     */
    export function Replace(str: String, search: String | RegExp, replace: String): String;
    /**
     * 用于截取字符串中指定位置的子字符串
     * @param str: 待截取的字符串
     * @param start: 开始位置
     * @param length: 截取长度
     */
    export function SubString(str: String, start: Integer, length: Integer): String;
    export function ToLower(str: String): String;
    export function ToUpper(str: String): String;
    export function Trim(str: String): String;
    export function PadStart(str: String, targetLength: String, fillStr: String): String;
    export function PadEnd(str: String, targetLength: String, fillStr: String): String;
    export function TrimStart(str: String): String;
    export function TrimEnd(str: String): String;

    /**
     * 用于匹配字符串中指定正则表达式,返回匹配到的子字符串列表
     * 与 JS match 方法区别是,不会返回匹配到的子字符串的索引、groups 等结构信息
     * @param str: 待匹配的字符串
     * @param regex: 正则表达式
     * @example nasl.util.MatchRegex('1234', /[0-9]/g) // ['1', '2', '3', '4']
     */
    export function MatchRegex(str: String, regex: RegExp): List<String>;

    /* 日期与时间函数 */
    export function CurrDate(timeZone: String): Date;
    export function CurrDateTime(timeZone: String): DateTime;
    export function CurrTime(timeZone: String): Time;
    /**
     * 计算结束时间减去开始时间的时间差, 如果开始时间大于结束时间, 返回负数
     * @param startDateTime 开始时间点
     * @param endDateTime 结束时间点
     * @param calcType: 计算的时间单位 'y' = 年 | 'q' = 季度 | 'M' = 月 | 'w' = 周 | 'd' = 天 | 'h' = 小时 | 'm' = 分钟 | 's' = 秒
     * @param isAbs: 是否返回绝对值
     */
    export function DateDiff<T extends Date | Time | DateTime>(startDateTime: T, endDateTime: T, calcType: 'y' | 'q' | 'M' | 'w' | 'd' | 'h' | 'm' | 's', isAbs: Boolean): Integer;
    /**
     * 为指定日期(或日期时间)调整增加(或减少)日期(或时间)
     * @param dateTime: 日期或日期时间
     * @param option: 操作类型,'Increase' = 增加 | 'Decrease' = 减少
     * @param amount: 变化的时间单位的数量
     * @param unit: 变化的时间单位。当dateTime为日期类型时,可选 'day' | 'week' | 'month' | 'quarter' | 'year';当dateTime为日期时间类型时,可选 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second'
     *
     * @example nasl.util.AlterDateTime(nasl.util.CurrDateTime('global'), 'Increase', 1, 'hour') // 返回当前日期时间加1小时后的日期时间
     * @example nasl.util.AlterDateTime(nasl.util.CurrDate('global'), 'Decrease', 1, 'quarter') // 返回当前日期减一个季度后的日期
     */
    export function AlterDateTime<T extends Date | DateTime>(dateTime: T, option: 'Increase' | 'Decrease', amount: Integer, unit: 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second' ): T;
    /**
     * 按指定维度计算日期的序号。当输入为 DateTime 类型时,会把数据转到提供的时区的当地时间进行计算
     * @param dateTime: 日期或日期时间
     * @param metric: 计算维度,格式为'小日期单位-大日期单位'。日期单位包括:'year'、'quarter'、'month'、'week'、'day'。
     * @param timeZone
     *
     * @example
     * nasl.util.GetDateCount(nasl.util.CurrDate('global'), 'day-week') // 返回当前日期处于所在周的第几天,返回值为1-7
     * nasl.util.GetDateCount(nasl.util.CurrDate('global'), 'day-month') // 返回当前日期处于所在月的第几天
     * nasl.util.GetDateCount(nasl.util.CurrDate('global'), 'day-quarter') // 返回当前日期处于所在季度的第几天
     * nasl.util.GetDateCount(nasl.util.CurrDate('global'), 'quarter-year') // 返回当前日期处于所在年的第几季度
     * nasl.util.GetDateCount(date1, 'week-quarter') // 返回date1处于所在季度的第几周
     * nasl.util.GetDateCount(date1, 'week-year') // 返回date1处于所在年的第几周
     * nasl.util.GetDateCount(nasl.util.CurrDate('global'), 'year-week') // 错误,前面的单位必须小于后面的单位
     * nasl.util.GetDateCount(date1, 'week-week') // 错误,不支持同级单位的计算
     * nasl.util.GetDateCount(currentTime, 'minute-hour') // 错误,不支持时间单位的计算
     */
    export function GetDateCount(date: Date, metric: 'day-week' | 'day-month' | 'day-quarter' | 'day-year' | 'week-month' | 'week-quarter' | 'week-year' | 'month-quarter' | 'month-year' | 'quarter-year'): Integer;
    export function GetDateCount(dateTime: DateTime, metric: 'day-week' | 'day-month' | 'day-quarter' | 'day-year' | 'week-month' | 'week-quarter' | 'week-year' | 'month-quarter' | 'month-year' | 'quarter-year', timeZone: String): Integer;
    /**
     * 按“星期几”获取指定日期范围内的日子。当输入为 DateTime 类型时,会把数据转到提供的时区的当地时间进行计算。
     * @param startDate: 开始日期/日期时间
     * @param endDate: 结束日期/日期时间
     * @param target: 目标星期几,1-7
     * @param timeZone
     * @returns 返回指定日期范围内的目标星期几日期列表
     *
     * @example
     * nasl.util.GetSpecificDaysOfWeek(nasl.util.CurrDate('global'), nasl.util.AlterDateTime(nasl.util.CurrDate('global'), 'Increase', 1, 'month'), nasl.util.NewList<Integer>([1])) // 返回当前日期到下个月的第一个星期一
     */
    export function GetSpecificDaysOfWeek(startDate: Date, endDate: Date, target: List<Integer>): List<Date>;
    export function GetSpecificDaysOfWeek(startDate: DateTime, endDate: DateTime, target: List<Integer>, timeZone: String): List<DateTime>;

    // 列表(List)函数
    /**
     * @example nasl.util.ListAdd(list, item)
     */
    export function ListAdd<T, K extends T>(list: List<T>, item: K): void;
    /**
     * @example nasl.util.ListAddAll(list, addedList)
     */
    export function ListAddAll<T>(list: List<T>, addList: List<T>): Integer;
    /**
     * 插入元素到列表指定位置
     * @param list: 待插入的列表
     * @param index: 插入位置
     * @param item: 待插入的元素
     * @example nasl.util.ListInsert(list, 0, item)
     * @note 空列表不能插入元素
     */
    export function ListInsert<T, K extends T>(list: List<T>, index: Integer, item: K): void;
    /**
     * 列表list中是否包含元素item
     * @example nasl.util.ListContains(list, item)
     */
    export function ListContains<T, K extends T>(list: List<T>, item: K): Boolean;
    /**
     * @example nasl.util.ListGet(list, index)
     */
    export function ListGet<T>(list: List<T>, index: Integer): T;
    export function ListSet<T, K extends T>(list: List<T>, index: Integer, item: K): T;
    export function ListRemove<T, K extends T>(list: List<T>, item: K): void;
    export function ListRemoveAt<T>(list: List<T>, index: Integer): T;
    export function ListDistinct<T>(list: List<T>): List<T>;
    /**
     * 指定字段去重
     * @param list 列表
     * @param by lambda 的数组,lambda 函数返回一个字段值,多个字段值“且”运算判等去重
     * @example ListDistinctBy(list, [(item) => item.name]); // 根据name去重
     * @example ListDistinctBy(list, [(item) => item.name, (item) => item.gender]); // 根据name和gender去重
     */
    export function ListDistinctBy<T>(list: List<T>, by: Array<(elem: T) => any>): List<T>;
    export function ListFilter<T>(list: List<T>, by: (item: T) => Boolean): List<T>;
    /**
     * 根据指定条件查找元素
     * @param list: 待查找的列表
     * @param by: 查找条件
     * @returns 返回查找到的元素,如果未找到则返回null
     */
    export function ListFind<T>(list: List<T>, by: (item: T) => Boolean): T;
    /**
     * 根据指定条件查找元素的索引
     * @param list: 待查找的列表
     * @param by: 查找条件
     * @returns 返回查找到的元素的索引,如果未找到则返回-1
     */
    export function ListFindIndex<T>(list: List<T>, by: (item: T) => Boolean): Integer;
    /**
     * 列表首元素。**列表长度为 0 时返回值为 `null`**。若实体类型为非空,`T | null` 下仍必须在访问字段前先用 `nasl.util.HasValue(首元素变量)`、`nasl.util.Length(list) > 0` 或与业务相符的错误分支校验,否则会触发运行时空指针类错误(例如 `nasl.error.SystemNullPointerError`)。
     *
     * 典型:**FROM/WHERE** 筛选后、`ListTransform` 得到列表再接 `ListHead` 获取「至多一条」时,无匹配即空列表,**必须先判空再继续**。
     */
    export function ListHead<T>(list: List<T>): T;
    /**
     * 列表末元素。**列表长度为 0 时返回值为 `null`**;判空与安全访问要求同 `ListHead`。
     */
    export function ListLast<T>(list: List<T>): T;
    export function ListFlatten<T>(list: List<List<T>>): List<T>;
    export function ListSum<T extends Integer | Decimal>(list: List<T>): T;
    export function ListProduct<T extends Integer | Decimal>(list: List<T>): T;
    export function ListMax<T extends Integer | Decimal | String>(list: List<T>): T;
    export function ListMin<T extends Integer | Decimal | String>(list: List<T>): T;
    export function ListAverage<T extends Integer | Decimal>(list: List<T>): Decimal;
    export function ListSlice<T>(list: List<T>, start: Integer, end: Integer): List<T>;
    /**
     * 列表排序
     * 支持多字段排序
     * @param list
     * @param args 多个 lambda 排序函数,返回固定的匿名数据结构,可以是一个表达式,也可以是多行代码
     * @example ListSort(list, (item) => ({ by: item.name, asc: true }), (item) => ({ by: item.createdTime, asc: false }));
     * @example ListSort(list, (item) => {
     *   let field = `${item.group}-${item.name}`;
     *   return { by: field, asc: true };
     * });
     */
    export function ListSort<T>(list: List<T>, ...args: Array<(item: T) => { by: PrimitiveType, asc: Boolean }>): List<T>;
    /**
     * 反转列表,原地修改并返回同一列表(类似 JS Array.reverse())
     * @example nasl.util.ListReverse(list)
     */
    export function ListReverse<T>(list: List<T>): List<T>;
    export function ListToMap<T, K extends PrimitiveType, V>(map: List<T>, byKey: (elem: T) => K, byVal: (elem: T) => V): Map<K, V>;
    /**
     * 根据指定字段对列表进行分组
     * @param list: 待分组的列表
     * @param by: 分组字段
     * @example nasl.util.ListGroupBy(list, (elem) => elem.id) // 根据id字段分组
     */
    export function ListGroupBy<A, K extends PrimitiveType>(list: List<A>, by: (elem: A) => K): Map<K, List<A>>;
    /**
     * 对列表中的每个元素进行转换
     * @param list: 待转换的列表
     * @param by: 转换函数, 可以是一个表达式,也可以是多行代码,函数入参数量必须为1
     * @example nasl.util.ListTransform(list, (elem) => elem.id) // 转换为id列表
     * @note NASL中作为参数传递的函数只能是一个表达式,不能是多行代码
     */
    export function ListTransform<T, T1>(list: List<T>, by: (elem: T) => T1): List<T1>;
    /**
     * 生成指定范围的整数列表
     * @param start: 起始值
     * @param end: 结束值, 不包含该值
     * @param step: 步长,默认为1
     * @example nasl.util.ListRange(1, 10, 2) // [1, 3, 5, 7, 9]
     * @example nasl.util.ListRange(5, 0) // [5, 4, 3, 2, 1]
     * @example nasl.util.ListRange(10, 0, -2) // [10, 8, 6, 4, 2]
     */
    export function ListRange(start: Integer, end: Integer, step?: Integer): List<Integer>;
    /* 生成指定长度的重复元素列表 */
    export function ListRepeat<T>(item: T, length: Integer): List<T>;


    /* 映射(Map)函数 */
    export function MapContains<K, V>(map: Map<K, V>, key: K): Boolean;
    export function MapGet<K, V>(map: Map<K, V>, key: K): V;
    export function MapPut<K, V>(map: Map<K, V>, key: K, value: V): void;
    export function MapKeys<K, V>(map: Map<K, V>): List<K>;
    export function MapRemove<K, V>(map: Map<K, V>, key: K): void;
    export function MapValues<K, V>(map: Map<K, V>): List<V>;
    /**
     * 对映射中的key和value分别进行转换
     * @param map: 待转换的映射
     * @param byKey: key转换函数, 只能是一个表达式
     * @param byVal: value转换函数, 只能是一个表达式
     * @example nasl.util.MapTransform(map, (key, value) => key, (key, value) => value) // 不做转换
     * @note 可配合ListGroupBy等函数使用
     */
    export function MapTransform<K, V, K1 extends PrimitiveType, V1>(map: Map<K, V>, byKey: (key: K, value: V) => K1, byVal: (key: K, value: V) => V1): Map<K1, V1>;
    /**
     * 根据指定条件过滤映射
     * @param map: 待过滤的映射
     * @param by: 过滤条件
     * @example nasl.util.MapFilter(map, (key, value) => value > 10) // 过滤出value大于10的映射
     */
    export function MapFilter<K, V>(map: Map<K, V>, by: (key: K, value: V) => Boolean): Map<K, V>;

    /* 枚举函数。项目中的枚举类型均定义在 app.enums 中 */
    type EnumItemStructure<T extends BaseEnum<V extends String | Integer>> = { text: String, value: V, item: T };
    declare class BaseEnum<V extends String | Integer> {}
    /**
     * 返回枚举 value, text 和 item 的 List 集合
     * T 为枚举类型
     * @example nasl.util.EnumToList<app.enums.StatusEnum>()
     */
    export function EnumToList<T extends BaseEnum<V>>(): List<{ text: String, value: V, item: T }>
    /**
     * 返回枚举值对应的 value 和 text 的结构体
     * @example nasl.util.EnumToStructure(app.enums.StatusEnum.Enabled)
     * @example nasl.util.EnumToStructure(status1)
     */
    export function EnumItemToStructure<V extends Integer | String>(enumItem: BaseEnum<V>): EnumItemStructure<V>;
    /**
     * 返回枚举指定value的标题字符串
     * @example nasl.util.EnumItemToText(app.enums.StatusEnum.Enabled)
     * @example nasl.util.EnumItemToText(status1)
     */
    export function EnumItemToText<V extends Integer | String>(enumItem: BaseEnum<V>): String;
    /**
     * 返回枚举指定value的枚举项
     * @example nasl.util.ToEnumItem<app.enums.StatusEnum>("Enabled")
     * @example nasl.util.ToEnumItem<app.enums.StatusEnum>(1)
     */
    export function ToEnumItem<T extends BaseEnum<V>>(value: V): T


    /* 数学函数 */
    /**
     * 整数/小数 操作
     * @example nasl.util.Round(2.6, 'HalfUp') == 3
     * @example nasl.util.Round(-2.6, 'TowardsZero') == -2
     * @example nasl.util.Round(-1.1, 'TowardsInfinity') == -2
     *
     * @param value: 待取整的数值
     * @param mode: 'HalfUp' = 四舍五入 | 'TowardsZero' = '截断、向零取整'| 'TowardsInfinity' = '进位、向正负无穷取整'
     */
    export function Round(value: Decimal, mode: 'HalfUp' | 'TowardsZero' | 'TowardsInfinity'): Integer;
    /**
     * RandomInt 生成的数字为整数, start 和 end 都是闭区间
     * @example nasl.util.RandomInt(1, 10) // 生成1-10的随机整数
     *
     * @param start: 起始值, 包含
     * @param end: 结束值, 包含
     */
    export function RandomInt(start: Integer, end: Integer): Integer;
    export function Ceil(value: Decimal): Integer;
    export function Floor(value: Decimal): Integer;
    export function Trunc(value: Decimal): Integer;
    /** 整除除法,通过截断小数部分实现 */
    export function TruncDivide(dividend: Decimal, divisor: Decimal): Integer;

    export function Abs(value: Integer): Integer;
    export function Abs(value: Decimal): Decimal;

    export function Pow(base: Decimal, exponent: Decimal): Decimal;
    export function Sqrt(value: Decimal): Decimal;
    export function Cbrt(value: Decimal): Decimal;
    /* 返回指定数字的自然对数 */
    export function Log(value: Decimal): Decimal;

    /* 其他函数 */
    /**
     * (修改原数据)清除复杂对象中每个属性的数据(若输入是单个基础类型如 Integer 的值,则不做处理)
     * @param struct: 待清除的复杂对象
     * @param mode: 清除模式,'shallow' = 浅层清除(默认),'deep' = 深度清除
     * @example nasl.util.Clear(struct, 'shallow') // 浅层清除
     * @example nasl.util.Clear(struct, 'deep') // 深度清除
     */
    export function Clear<T>(struct: T, mode?: 'deep' | 'shallow'): T;
    /**
     * 深度拷贝一个值
     */
    export function Clone<T>(struct: T): T;
    /**
     * 判断参数是否为有效值,null、空字符串、纯空格、长度为0的集合均不被视为有效值,传入多个参数时,判断是否全部都是有效值
     */
    export function HasValue(...args: any[]): Boolean;

    /* New 系列函数 */
    /**
     * 生成新的列表,T 类型必填
     * @example let integerList: List<Integer> = nasl.util.NewList<Integer>([1, 2, 3])
     * @example let stringList: List<String> = nasl.util.NewList<String>(['a', 'b', 'c'])
     * @example let decimalList: List<List<Decimal>> = nasl.util.NewList<List<Decimal>>([nasl.util.NewList<Decimal>([1.1, 2.2]), nasl.util.NewList<Decimal>([3.3, 4.4])])
     * @example let booleanOrIntegerList: List<Boolean | Integer> = nasl.util.NewList<Boolean | Integer>([true, false, 1])
     *
     * @note 创建空列表时,函数必须传入[]
     * @example let emptyList: List<Integer> = nasl.util.NewList<Integer>([]) // Correct
     * @example let emptyList: List<Integer> = nasl.util.NewList<Integer>() // Error
     */
    export function NewList<T>(args: T[]): List<T>;
    /**
     * 生成新的映射,K、T 类型必填
     * @example let variable1: Map<String, Integer> = nasl.util.NewMap<String, Integer>({'123': 456})
     */
    export function NewMap<K, T>(args: Record<Stringify<K>, T>): Map<K, T>;

    /**
     * new 关键字
     * @note 仅用于创建实体、结构体、接口/依赖库/连接器中的结构体。这类数据结构均为class类型
     * @example 创建实体
     * let entityObject: app.dataSources.defaultDS.entities.Student = new app.dataSources.defaultDS.entities.Student(); // 创建空实体
     * let entityObjectWithInit: app.dataSources.defaultDS.entities.Student = new app.dataSources.defaultDS.entities.Student({id: 123, name: '张三', age: 18}); // 创建带初始值的实体
     * @example 创建结构体
     * let structureObject: app.structures.Student = new app.structures.Student(); // 创建空结构体
     * let structureObjectWithInit: app.structures.Student = new app.structures.Student({id: 123, name: '张三', age: 18}); // 创建带初始值的结构体
     */

    /**
     * 对于匿名结构体,可直接使用 {} 创建
     * @example
     * let anonymousStructureObject: { id: Integer, name: String, age: Integer } = { id: 123, name: '张三', age: 18 }; // 创建匿名结构体
     */

    export function consoleLog(arg: any): void;
    export function jsonSerialize(arg: DateTime, timeZone: String): String;
    export function jsonSerialize(arg: any): String;
    /**
     * JSON 反序列化
     * @typeParam T: 需要手动指定返回值类型
     * @example nasl.util.jsonDeserialize<Boolean>(variable1);
     */
    export function jsonDeserialize<T>(arg: String): T;
}
- There is no member method for List and Map, chain call like `list.forEach()` `map.forEach()` is not supported; - Always use more advanced built-in functions: - `ListContains` instead of using loop to check if an element exists; - `ListDistinct` or `ListDistinctBy` instead of using loop to remove duplicates; - `ListFind` or `ListFindIndex` instead of using loop to find elements; - `ListAddAll` instead of using loop to add elements; - `ListReverse` instead of using loop to reverse elements; - `ListFilter` instead of using loop to filter elements; - `ListFlatten` instead of using loop to add elements; - `ListGroupBy` instead of using loop and put elements into map; - `ListAverage` or `ListSum` or `ListMax` or `ListMin` or `ListProduct` instead of using loop to calculate; - `ListTransform` instead of loop operation transformation; - `ListToMap` instead of using loop to put elements into map; - `MapTransform` instead of loop to transform map; - `DateDiff` do not need generic type when calling, just pass arguments, the function will automatically infer the type based on the arguments; - **数值类型转换**:Integer 赋值给 Decimal 字段时无需 Convert(隐式兼容);Decimal 赋值给 Integer 字段时必须显式使用 `nasl.util.Convert(value)` 进行强转。 - 只有必须显式指定泛型类型参数的函数调用时,才需要标注类型: - Convert - FromString - EnumToList - ToEnumItem - NewList(强调空列表 [] 必须带类型) - NewMap - jsonDeserialize。如:jsonDeserialize(variable1); - 其他函数(无论声明上无泛型或者有泛型的情况)调用时,都不要标注 类型。如:DateDiff(CurrDateTime('global'), other, 'd', false); - **`ListHead` / `ListLast`(空列表安全)**:二者在列表为空时对元素语义实际为 **`null`**。**禁止**在未经 `nasl.util.HasValue`、`nasl.util.Length(list) > 0`(或等价错误分支、`nasl.errors`)的情况下访问返回值字段。FROM/WHERE **可能无匹配** 时须在实现与设计(含 Speckit 逻辑计划文档)写明无数据路径。 - **NASL 基础类型**:请参考 nasl-book/K002-nasl--types.md 文件 - **NASL 逻辑 - 基本知识**:请参考 nasl-book/K004-backend-logic--basic.md 文件 - **NASL 逻辑 - 分页、实体方法和数据查询**:请参考 nasl-book/K005-backend-logic--paginate-entity-method-data-query.md 文件