查看“︁用户:DGCK81LNN/cosmokit”︁的源代码

{{info|color=red|此文档由 AI 生成并人工修正表述，完整 API 以源码为准：<br/>https://github.com/shigma/cosmokit}}

{{DISPLAYTITLE:Cosmokit 中文文档}}

Cosmokit 是主要由 Shigma 开发的一组灵活的 JavaScript/TypeScript 通用工具库，涵盖常用对象、数组、字符串、二进制和时间操作。

== 安装 ==
<syntaxhighlight lang="shell">
npm install cosmokit
# 或者
yarn add cosmokit
</syntaxhighlight>

<syntaxhighlight lang="javascript">
import { contain, camelCase, Time } from 'cosmokit'
</syntaxhighlight>

== 数组工具 ==

* <syntaxhighlight inline lang="javascript">contain(array1, array2)</syntaxhighlight><br/>判断 array2 的所有元素是否都包含在 array1 内。
* <syntaxhighlight inline lang="javascript">intersection(array1, array2)</syntaxhighlight><br/>计算两数组的交集。
* <syntaxhighlight inline lang="javascript">difference(array1, array2)</syntaxhighlight><br/>计算两数组的差集。
* <syntaxhighlight inline lang="javascript">union(array1, array2)</syntaxhighlight><br/>计算两数组的并集。
* <syntaxhighlight inline lang="javascript">deduplicate(array)</syntaxhighlight><br/>数组去重。
* <syntaxhighlight inline lang="javascript">remove(list, item)</syntaxhighlight><br/>从数组里移除某元素，返回是否成功。
* <syntaxhighlight inline lang="javascript">makeArray(source)</syntaxhighlight><br/>将 null/undefined/单个值/数组标准化为数组。

<syntaxhighlight lang="javascript">
import { deduplicate, union } from 'cosmokit'
deduplicate([1, 2, 2, 3]) // [1, 2, 3]
union([1, 2], [2, 3]) // [1, 2, 3]
</syntaxhighlight>

== 对象通用工具 ==

* <syntaxhighlight inline lang="javascript">noop()</syntaxhighlight><br/>空函数，什么都不做。
* <syntaxhighlight inline lang="javascript">isNullable(value)</syntaxhighlight><br/>判断是否为 null/undefined/void。
* <syntaxhighlight inline lang="javascript">isNonNullable(value)</syntaxhighlight><br/>判断是否不是 null/undefined/void。
* <syntaxhighlight inline lang="javascript">isPlainObject(data)</syntaxhighlight><br/>判断是否为普通对象（非数组）。
* <syntaxhighlight inline lang="javascript">filterKeys(object, fn)</syntaxhighlight><br/>对对象的键值进行筛选。回调函数接收键、值，保留结果为真的键值并组成新的对象。
* <syntaxhighlight inline lang="javascript">mapValues(object, fn)</syntaxhighlight><br/>对对象的键值进行映射。回调函数接收值、键，返回新值并保留原键不变组成新的对象。<br/>别名：<syntaxhighlight inline lang="javascript">valueMap</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">pick(source, keys, forced)</syntaxhighlight><br/>从对象上选出指定的键，返回对应键值组成的新对象。<syntaxhighlight inline lang="javascript">forced</syntaxhighlight> 为真时不存在的键会被强制添加，值为 undefined。
* <syntaxhighlight inline lang="javascript">omit(source, keys)</syntaxhighlight><br/>排除对象上指定的键，返回其余键值组成的新对象。
* <syntaxhighlight inline lang="javascript">defineProperty(object, key, value)</syntaxhighlight><br/>在对象上定义不可枚举属性。

<syntaxhighlight lang="javascript">
import { isNullable, pick, omit } from 'cosmokit'
pick({ a:1, b:2 }, ['a']) // { a: 1 }
omit({ a:1, b:2 }, ['b']) // { a: 1 }
</syntaxhighlight>

== 类型与二进制数据工具 ==

* <syntaxhighlight inline lang="javascript">is(type, value)</syntaxhighlight><br/>判断变量是否为指定全局类型。
* <syntaxhighlight inline lang="javascript">Binary.is(value)</syntaxhighlight><br/>判断是否为 ArrayBuffer/SharedArrayBuffer。
* <syntaxhighlight inline lang="javascript">Binary.isSource(value)</syntaxhighlight><br/>判断是否为二进制源（(Shared)ArrayBuffer/ArrayBufferView）。
* <syntaxhighlight inline lang="javascript">Binary.fromSource(source)</syntaxhighlight><br/>获取二进制源的 ArrayBuffer。
* <syntaxhighlight inline lang="javascript">Binary.toBase64(source)</syntaxhighlight><br/>转 base64 字符串。<br/>全局别名：<syntaxhighlight inline lang="javascript">arrayBufferToBase64</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">Binary.fromBase64(str)</syntaxhighlight><br/>base64 转 ArrayBuffer。<br/>全局别名：<syntaxhighlight inline lang="javascript">base64ToArrayBuffer</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">Binary.toHex(source)</syntaxhighlight><br/>转十六进制字符串。<br/>全局别名：<syntaxhighlight inline lang="javascript">arrayBufferToHex</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">Binary.fromHex(str)</syntaxhighlight><br/>十六进制转 ArrayBuffer。<br/>全局别名：<syntaxhighlight inline lang="javascript">hexToArrayBuffer</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">clone(source)</syntaxhighlight><br/>深拷贝对象，支持 Date。

== 字符串工具 ==

* <syntaxhighlight inline lang="javascript">camelCase(source)</syntaxhighlight><br/>连字符/下划线转小驼峰。<br/>别名：<syntaxhighlight inline lang="javascript">camelize</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">paramCase(source)</syntaxhighlight><br/>转 param-case。<br/>别名：<syntaxhighlight inline lang="javascript">hyphenate</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">snakeCase(source)</syntaxhighlight><br/>转 snake_case。
* <syntaxhighlight inline lang="javascript">formatProperty(key)</syntaxhighlight><br/>格式化属性键：输入字符串或 Symbol 键，输出 <code>.key</code> 或 <code>[value]</code> 格式的字符串。
* <syntaxhighlight inline lang="javascript">trimSlash(source)</syntaxhighlight><br/>去除末尾斜杠。
* <syntaxhighlight inline lang="javascript">sanitize(source)</syntaxhighlight><br/>开头保留斜杠，并去除末尾斜杠。

<syntaxhighlight lang="javascript">
import { camelCase, paramCase } from 'cosmokit'
camelCase('foo_bar') // 'fooBar'
paramCase('fooBar') // 'foo-bar'
</syntaxhighlight>

== 时间工具 ==

<syntaxhighlight inline lang="javascript">Time</syntaxhighlight> 命名空间导出一系列时间相关常量与工具方法。

* 毫秒单位的时间常量：<syntaxhighlight inline lang="javascript">Time.millisecond</syntaxhighlight>、<syntaxhighlight inline lang="javascript">Time.second</syntaxhighlight>、<syntaxhighlight inline lang="javascript">Time.minute</syntaxhighlight>、<syntaxhighlight inline lang="javascript">Time.hour</syntaxhighlight>、<syntaxhighlight inline lang="javascript">Time.day</syntaxhighlight>、<syntaxhighlight inline lang="javascript">Time.week</syntaxhighlight>
* <syntaxhighlight inline lang="javascript">Time.setTimezoneOffset(num)</syntaxhighlight> / <syntaxhighlight inline lang="javascript">Time.getTimezoneOffset()</syntaxhighlight><br/>设置/获取默认时区偏移（本地时间转 UTC 时间需要加上的分钟数，与 <syntaxhighlight inline lang="javascript">Date.prototype.getTimezoneOffset()</syntaxhighlight> 一致）。该默认值会被 Time.getDateNumber 和 Time.fromDateNumber 使用，初始为系统当前时区偏移。
* <syntaxhighlight inline lang="javascript">Time.getDateNumber(date, offset)</syntaxhighlight><br/>获取本地日期编号。date 为 Date 对象或毫秒时间戳。
* <syntaxhighlight inline lang="javascript">Time.fromDateNumber(val, offset)</syntaxhighlight><br/>日期编号转 Date 对象。
* <syntaxhighlight inline lang="javascript">Time.parseTime(str)</syntaxhighlight><br/>解析形如“1d2h5m3s”的时间字符串到毫秒数。
* <syntaxhighlight inline lang="javascript">Time.parseDate(str)</syntaxhighlight><br/>解析日期字符串到 Date 对象。除了 Date 原生支持的格式外还支持下列格式：
** 同 <syntaxhighlight inline lang="javascript">Time.parseTime(str)</syntaxhighlight> 的格式，表示当前时间的指定间隔之后。
** <code>年-月-日-时:分:秒</code>（分、秒可省略），可省略年、月、日（使用当前日期）或只省略年（使用当前年份）。
* <syntaxhighlight inline lang="javascript">Time.format(ms)</syntaxhighlight><br/>将毫秒数格式化为人类可读的大致值，如 3h。
* <syntaxhighlight inline lang="javascript">Time.toDigits(num, length=2)</syntaxhighlight><br/>数字左补零到指定长度。
* <syntaxhighlight inline lang="javascript">Time.template(template, time)</syntaxhighlight><br/>格式化时间戳为指定模板字符串。模板字符串支持以下占位符：yyyy（四位年）、yy（两位年）、MM（两位月）、dd（两位日）、hh（两位小时）、mm（两位分钟）、ss（两位秒）、SSS（三位毫秒）。例如 <code>Time.template('yyyy-MM-dd hh:mm:ss', new Date())</code>。time 必须为 Date 对象，默认取当前时间。

<syntaxhighlight lang="javascript">
import { Time } from 'cosmokit'
Time.parseTime('2h5m') // 7500000
Time.format(60000) // '1m'
Time.template("yyyy-MM-dd hh:mm:ss")
</syntaxhighlight>