# @art-suite/art-core-ts-comprehensions 中文文档

规范地址：https://npmcn.com/package/%40art-suite/art-core-ts-comprehensions/

版本：0\.5\.1
npm 元数据更新时间：2026-06-19T10:22:11.209Z
中文译文更新时间：2026-11-06T20:38:05.793Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40art-suite/art-core-ts-comprehensions
原文对照：https://npmcn.com/package/%40art-suite/art-core-ts-comprehensions/?lang=original
项目主页：https://github.com/art-suite/art-suite-ts#readme
源码仓库：https://github.com/art-suite/art-suite-ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：135 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-05-12T09:00:43.373Z
- 最新版本发布：2026-06-19T10:22:11.106Z
- 近 30 天下载量：3233（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 5 个）

## 中文简介

TypeScript 字符串工具库

## 安装

```sh
npm install @art-suite/art-core-ts-comprehensions
```

也可以使用：`pnpm add @art-suite/art-core-ts-comprehensions`、`yarn add @art-suite/art-core-ts-comprehensions`、`bun add @art-suite/art-core-ts-comprehensions`

## README

# @art-site/art-core-ts-compossibleons (中文(简体) )

用于JavaScript的强大而灵活的理解库,为与数组,对象,和其他可移动性的工作提供统一的接口. 它为不同数据结构的绘图、过滤和缩小等共同操作提供了一致的方式.

这个库与其他理解的最大区别是每个理解函数都可以接受任何输入容器作为源:对象,数组或任何可移动的. 理解函数的名称表示返回类型 :

-   `object` 返回对象
-   `array` 返回数组
-   `find` 返回已找到的值
-   `reduce` 返回减少的值
-   `each` 返回时 `returning` 值或未定义

## 特征

-   用于与数组、对象和其他可移动性工作的统一接口
-   不同数据结构之间的一致行为
-   支持同步操作和同步操作
-   具有类型脚本支持的类型安全操作
-   保持原始数据结构特点的有效实施

## 安装

```bash
npm install @art-suite/art-core-ts-comprehensions
```

## API 概览

### 核心职能

所有理解函数需要 0, 1 或 2 个参数 :

-   **参数 1**: 升起的容器
    
-   **参数 2**: 有功能或选项对象
    
-   **`each(source, withOrOptions?)`**:在源头上标出,执行每个项目的功能。 返回 `returning` 如果提供,则不提供 `undefined`。 。 。 .
    
-   **`array(source, withOrOptions?)`**: 通过对源的每个项目应用同功能来创建新数组.
    
-   **`object(source, withOrOptions?)`**: 通过对源中的每个项目应用与功能创建新对象.
    
-   **`reduce(source, withOrOptions?)`**: 使用同功能将源降低为单个值.
    
-   **`find(source, withOrOptions?)`**: 返回源代码中满足功能的第一个项目.
    

## 深入理解

这个 `DeepComprehensions` 模块为绘图和在深层嵌入的阵列和物体上延展提供了先进的公用设备。 这些函数在需要任意嵌入处理数据结构时特别有用.

> **说明:** 这些函数现在可以直接从软件包中导入:
> 
> ```javascript
> import {
>   map,
>   deepEach,
>   deepMap,
> } from "@art-suite/art-core-ts-comprehensions";
> ```

### 出口

-   **`map(source, withOrOptions?)`**:在阵列或物体上浅意地映射,返回带有映射值的同类型新容器。 不再出现于嵌入式容器.
-   **`deepEach(source, withOrOptions?)`**: 在所有值上以深层嵌入的阵列或对象结构来排列,称为每个非容器值的同函数. 支持可选 `when` 过滤器.
-   **`deepMap(source, withOrOptions?)`**:在深层嵌入的阵列或对象中对所有值进行回溯映射,返回形状相同但有映射值的新结构. 支持可选 `when` 过滤器.

### 用法实例

```javascript
import { deepMap, deepEach, map } from "@art-suite/art-core-ts-comprehensions";

const nested = {
  a: 1,
  b: 2,
  c: [1, 2, 3],
};

// Deeply map all values, incrementing each by 1
const incremented = deepMap(nested, (value) => value + 1);
// Result: { a: 2, b: 3, c: [2, 3, 4] }

// Deeply map, but only for keys not equal to 'c'
const filtered = deepMap(nested, {
  with: (value) => value + 1,
  when: (value, key) => key !== "c",
});
// Result: { a: 2, b: 3 }

// Deeply iterate and sum all values
let sum = 0;
deepEach(nested, (value) => (sum += value));
// sum === 9

// Shallow map (does not recurse into arrays/objects)
const shallow = map(nested, (value) => value + 10);
// Result: { a: 11, b: 12, c: "1,2,310" } // Note: [1,2,3] + 10 coerces to string
```

## 用法实例

### 基本阵列操作

```javascript
import { array, each, find } from "@art-suite/art-core-ts-comprehensions";

const numbers = [1, 2, 3, 4, 5];

// Map operation
const doubled = array(numbers, (x) => x * 2);
// Result: [2, 4, 6, 8, 10]

// Filter and transform
const evenDoubled = array(numbers, {
  with: (x) => x * 2,
  when: (x) => x % 2 === 0,
});
// Result: [4, 8]

// ForEach operation
each(numbers, (x) => console.log(x));
// Logs each number

// Find operation with when option
const firstEven = find(numbers, { when: (x) => x % 2 === 0 });
// Result: 2

// Find and transform
const firstEvenDoubled = find(numbers, {
  when: (x) => x % 2 === 0,
  with: (x) => x * 2,
});
// Result: 4
```

### 对象操作

```javascript
import { object, each } from "@art-suite/art-core-ts-comprehensions";

const data = {
  a: 1,
  b: 2,
  c: 3,
};

// Transform object values
const doubled = object(data, (value, key) => value * 2);
// Result: { a: 2, b: 4, c: 6 }

// Transform keys with withKey option
const keyTransformed = object(data, { withKey: (value) => value * 11 });
// Result: { 11: 1, 22: 2, 33: 3 }

// Iterate over object
each(data, (value, key) => console.log(`${key}: ${value}`));
// Logs each key-value pair

// Each with returning value
const result = each(data, {
  returning: "done",
  with: (value, key) => console.log(`${key}: ${value}`),
});
// Logs each key-value pair, result === "done"
```

### 减少业务

```javascript
import { reduce } from "@art-suite/art-core-ts-comprehensions";

const numbers = [1, 2, 3, 4, 5];

// Sum all numbers (uses first element as initial value)
const sum = reduce(numbers, (acc, x) => acc + x);
// Result: 15

// Sum with inject option
const sumWithInitial = reduce(numbers, {
  with: (acc, x) => acc + x,
  inject: 10,
});
// Result: 25

// Multiply with inject option
const product = reduce(numbers, {
  with: (acc, x) => acc * x,
  inject: 1,
});
// Result: 120

// Filter and reduce
const evenSum = reduce(numbers, {
  with: (acc, x) => acc + x,
  when: (x) => x % 2 === 0,
});
// Result: 6 (sum of even numbers only)

// Reduce with inject
reduce([1, 2, 3], { with: (acc, x) => acc + x, inject: 10 });
// Result: 16

// Each with returning
const result = each([1, 2, 3], {
  returning: "done",
  with: (x) => console.log(x),
});
// Result: "done"
```

### 使用不同的数据结构

```javascript
import { array, object } from "@art-suite/art-core-ts-comprehensions";

// Array-like object
const arrayLike = { 0: "a", 1: "b", 2: "c", length: 3 };
const result1 = array(arrayLike, (x) => x.toUpperCase());
// Result: ['A', 'B', 'C']

// Set
const set = new Set([1, 2, 3]);
const result2 = array(set, (x) => x * 2);
// Result: [2, 4, 6]

// Map
const map = new Map([
  ["a", 1],
  ["b", 2],
]);
const result3 = object(map, (value, key) => value * 2);
// Result: { a: 2, b: 4 }

// Stop iteration early with stopWhen
const result4 = array([1, 2, 3, 4], {
  with: (x) => x * 2,
  stopWhen: (x) => x === 3,
});
// Result: [2, 4] (stops when value equals 3)

// Use into option to append to existing array
const existingArray = [100, 200];
const result5 = array([1, 2, 3], { with: (x) => x * 10, into: existingArray });
// Result: [100, 200, 10, 20, 30]

// Use into option to merge into existing object
const existingObject = { x: 999 };
const result6 = object([1, 2, 3], {
  with: (x) => x * 10,
  into: existingObject,
});
// Result: { x: 999, 1: 10, 2: 20, 3: 30 }
```

## 选项参考

所有理解函数接受一个选项对象作为第二个参数. 以下是所有可用选项的完整参考,以及支持这些选项的功能:

### 常见选项( 所有函数)

这些选项得到所有理解函数的支持:

-   **`with`**: 转换每个值的函数
    
    -   **签署**数字 : `(value, key) => transformedValue` (计: `array`, (中文(简体) ), `object`, (中文(简体) ), `find`, (中文(简体) ), `each`(中文(简体) )
    -   **签署**数字 : `(accumulator, value, key) => newAccumulator` (计: `reduce`(中文(简体) )
    -   **默认**: 如果未提供, 返回原值不变
    -   **用于**数字 : `array`, (中文(简体) ), `object`, (中文(简体) ), `reduce`, (中文(简体) ), `find`, (中文(简体) ), `each`
-   **`when`**: 要过滤元素的函数( 预览)
    
    -   **签署**数字 : `(value, key) => boolean`
    -   **行为**: 只处理返回的元素 `true`
    -   **用于**数字 : `array`, (中文(简体) ), `object`, (中文(简体) ), `reduce`, (中文(简体) ), `find`, (中文(简体) ), `each`
-   **`stopWhen`**: 及早停止重复的函数
    
    -   **签署**数字 : `(value, key) => boolean`
    -   **行为**: 返回时停止迭代 `true`
    -   **用于**数字 : `array`, (中文(简体) ), `object`, (中文(简体) ), `each`

### 函数特定选项

#### `array(source, withOrOptions?)`

-   **`into`**: 推动结果的矩阵
    -   **类型**数字 : `Array`
    -   **默认**: 创建新数组
    -   **行为**: 结果被推入此数组, 而不是创建新的数组

#### `object(source, withOrOptions?)`

-   **`into`**: 指定结果为
    -   **类型**数字 : `Object`
    -   **默认**: 创建新对象
    -   **行为**: 给此对象分配结果而不是创建新对象
-   **`withKey`**: 确定输出密钥的函数
    -   **签署**数字 : `(value, key) => newKey`
    -   **默认**: 使用原始密钥(用于对象)或值(用于数组/可插入)
    -   **行为**:返回的值成为输出对象中的密钥

#### `reduce(source, withOrOptions?)`

-   **`inject`**: 减少的初始值
    -   **类型**: 任何值
    -   **默认**: 使用第一个元素作为初始值
    -   **行为**: 此值成为初始累积器

#### `each(source, withOrOptions?)`

-   **`returning`**: 要返回的值
    -   **类型**: 任何值
    -   **默认**数字 : `undefined`
    -   **行为**: 返回此值(未由 `each` 页:1

#### `find(source, withOrOptions?)`

-   除共同选项外,没有特定函数选项

### 选项组合和行为

-   **`with` + 键 `when`**: 仅转换已过滤的元素
-   **`with` + 键 `stopWhen`**: 变换直到满足停止条件
-   **`when` + 键 `stopWhen`**: 筛选直到满足停止条件
-   **`with` + 键 `when` + 键 `stopWhen`**: 变形过滤元素直到满足停止条件

### 选项使用示例

```javascript
// Basic with function
array([1, 2, 3], { with: (x) => x * 2 });
// Result: [2, 4, 6]

// Filter with when
array([1, 2, 3, 4], { when: (x) => x % 2 === 0 });
// Result: [2, 4]

// Transform and filter
array([1, 2, 3, 4], { with: (x) => x * 2, when: (x) => x % 2 === 0 });
// Result: [4, 8]

// Stop early
array([1, 2, 3, 4], { with: (x) => x * 2, stopWhen: (x) => x === 3 });
// Result: [2, 4]

// Use into option
const existing = [100];
array([1, 2, 3], { with: (x) => x * 10, into: existing });
// Result: [100, 10, 20, 30]

// Object with custom keys
object([1, 2, 3], { withKey: (x) => `key_${x}`, with: (x) => x * 10 });
// Result: { key_1: 10, key_2: 20, key_3: 30 }

// Reduce with inject
reduce([1, 2, 3], { with: (acc, x) => acc + x, inject: 10 });
// Result: 16

// Each with returning
const result = each([1, 2, 3], {
  returning: "done",
  with: (x) => console.log(x),
});
// Result: "done"
```

## 关键概念

### 源类型

图书馆使用各种来源类型:

-   阵列
-   对象
-   设定
-   地图
-   类似矩阵的对象
-   带有 a 的任何对象 `forEach` 方法
-   带有 a 的任何对象 `map` 方法
-   带有 a 的任何对象 `reduce` 方法

### 有函数

每个操作接受一个随功能,接收:

-   当前值
-   当前密钥/索引
-   源对象
-   当前迭代索引

**说明**编号: `reduce`,带有函数签名的是 `(accumulator, value, key)` 改为 `(value, key)`。 。 。 .

### 返回值

-   `each`: 返回 `returning` 如果提供,则不提供 `undefined`
-   `array`: 返回新数组
-   `object`: 返回新对象
-   `reduce`: 返回累积值
-   `find`: 返回第一个匹配项或未定义

## 支持的容器类型

此库可区分容器 **斜拉** 和容器 **生成**数字 :

### 容器,你可以重排过

您可以使用理解函数( 如 `each`, (中文(简体) ), `reduce`, (中文(简体) ), `find`等,还有 `object` 财务报告和审定财务报表 `array`以下列任何一项为准:

-   阵列
-   对象
-   设定
-   地图
-   类似矩阵对象(带有 `length` 属性和索引要素)
-   执行可执行协议的任何对象(有: `[Symbol.iterator]` 方法)

### 可以生成的容器

目前,仅 **数组** 财务报告和审定财务报表 **普通对象** 可以通过理解函数(例如: `array`, (中文(简体) ), `object`, (中文(简体) ), `deepMap`(见a/c.5/49/70,附件).

> **说明:** 未来可能会添加对生成地图和集的支持.

这意味着,当您可以覆盖许多不同类型的容器时,当您使用返回新容器的函数时(如 `array`, (中文(简体) ), `object`,或 `deepMap`),结果将始终是一个新的数组或一个新的平原对象,这取决于所使用的函数和输入类型.

## 许可证

麻省理工学院

## 常见问题

### @art-suite/art-core-ts-comprehensions 是什么？

TypeScript 字符串工具库

### 如何安装 @art-suite/art-core-ts-comprehensions？

在项目目录运行 npm install @art-suite/art-core-ts-comprehensions，或使用 pnpm add / yarn add / bun add。

### @art-suite/art-core-ts-comprehensions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @art-suite/art-core-ts-comprehensions 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @art-suite/art-core-ts-comprehensions 可以商用吗？

@art-suite/art-core-ts-comprehensions 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @art-suite/art-core-ts-comprehensions 的下载量有多少？

根据 npm 官方下载统计，@art-suite/art-core-ts-comprehensions 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,233 次，日均约 108 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @art-suite/art-core-ts-comprehensions 还在维护吗？

最新版本 0\.5\.1 发布于 2026/06/19（4 个月前）；至今共发布 30 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/05/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。