kotlin-scope-functions-js/README.md

A JavaScript library implementing Kotlin-like scope functions: let and also

# kotlin-scope-functions-js

一个实现了类似 Kotlin 中的 scope functions( `let`/`also`/`takeIf`/`takeUnless` ) 的 JavaScript 库。

这些函数主要用在可选链 `?.` 中，用于简化代码。

**注意：** 不要在开发通用库时使用该库，因为它依赖于全局对象的扩展。开发多人项目时也需慎重选用。

## 功能

- `let` 函数：用于转换值并返回结果
- `also` 函数：用于执行操作并返回对象本身
- `takeIf` 函数：如果条件满足则返回对象本身，否则返回 null
- `takeUnless` 函数：如果条件不满足则返回对象本身，否则返回 null

## 特色

- [x] 完整的 TypeScript 类型定义
- [x] 函数定义使用 `Object.defineProperty` 添加，设置为不可枚举，不会出现在 `for...in` 循环中。个人项目放心使用。
- [x] 对基本类型支持度最高，在这些类型上使用时，会正确保留原始类型，而不会转换为对象。 (以下类型的 instanceof object 均为 false)
  - [x] string/字符串
  - [x] number/数字
  - [x] bigint/大整数
  - [x] boolean/布尔值
  - [x] symbol/符号

## 对于不支持 with/run/apply 的说明

- 个人不喜欢使用 this
- 这些函数的参数不能使用箭头函数，因为箭头函数的 this 指向是固定的

## 安装

```bash
npm install kotlin-scope-functions-js
```

## 使用方法

```javascript
// 引入库
// esm 方式
import 'kotlin-scope-functions-js';
// 或者 cjs 方式
// require('kotlin-scope-functions-js');

// 使用 let 函数 - 转换值
const url = maybeNull();
const result = await url?.let(it => fetch(it));

// 等价于：
const result = await (url ? fetch(url) : null);

// 使用 also 函数 - 操作对象
const person = (new Persion).also(it => {
  it.name = 'John';
  it.age = 30;
});

// 使用 takeIf 函数 - 条件判断
const user = getUserOrNull()?.takeIf(it => it.age >= 18);
```