# norn

> `Norn`是一个 JavaScript/TypeScript 的可扩展运算符工具。它的构想是设计一种可读性强的自定义 JS 语法，来实现支持 TS 类型安全的可扩展运算符的方法。

Latest version **0.4.2** (published 2024-12-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install norn
pnpm add norn
yarn add norn
bun add norn
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2024-12-16 |
| First published | 2022-03-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 77.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Joe_Sky |
| Maintainers | joe_sky |

## Links

- npm: https://www.npmjs.com/package/norn
- Repository: https://github.com/joe-sky/norn
- Homepage: https://github.com/joe-sky/norn#readme
- Issues: https://github.com/joe-sky/norn/issues
- npm.io page: https://npm.io/package/norn

## Recent versions

- 0.4.2 (latest) — 2024-12-16
- 0.4.1 — 2024-07-19
- 0.4.0 — 2024-01-03
- 0.4.0-alpha.4 — 2023-05-24
- 0.4.0-alpha.3 — 2023-05-08
- 0.4.0-alpha.2 — 2023-04-07
- 0.4.0-alpha.1 — 2023-04-06
- 0.3.0-alpha.5 — 2023-02-24
- 0.3.0-alpha.4 — 2023-02-23
- 0.3.0-alpha.3 — 2023-02-23
- 0.3.0-alpha.2 — 2023-02-21
- 0.3.0-alpha.1 — 2023-02-20
- 0.2.0-alpha.2 — 2022-07-21
- 0.2.0-alpha.1 — 2022-07-18
- 0.1.0-alpha.3 — 2022-07-05
- … 3 more at https://npm.io/package/norn/versions

## README

# Norn

## 概述

`Norn`是一个 JavaScript/TypeScript 的可扩展运算符工具。它的构想是设计一种可读性强的自定义 JS 语法，来实现支持 TS 类型安全的可扩展运算符的方法。

> 本工具的运行思路与 ES 管道运算符提案相对较为近似，具体可[参考这里](https://github.com/tc39/proposal-pipeline-operator)。

这里演示下目前`Norn`实现的可运行版本语法，比如我们想创建一套实现特殊逻辑的简单数学运算符：

```tsx
import Norn from 'norn';

const n = Norn.operator('+1', (x: number) => {
  return x + 1;
})
  .operator('x2', (x: number) => {
    return x * 2;
  })
  .operator('/4', (x: number) => {
    return x / 4;
  })
  .create();

const result = n(100, '+1', 'x2', '/4'); // result变量的值经过三次运算后为50.5, TS类型为number
```

如果在上面例子的运算符间插入更多参数也是支持的，比如我们需要设置每次运算的极限值，如果大于极限则直接返回极限值：

```tsx
const n = Norn.operator('+1', (x: number, limit: number) => {
  const result = x + 1;
  return result > limit ? limit : result;
})
  .operator('x2', (x: number, limit: number) => {
    const result = x * 2;
    return result > limit ? limit : result;
  })
  .operator('/4', (x: number, limit: number) => {
    const result = x / 4;
    return result > limit ? limit : result;
  })
  .create();

const result = n(100, '+1', 100, 'x2', 200, '/4', 30); // 初始值100，在经"+1"运算后为100；"x2"运算后为200；"/4"运算后为30
```

## 这个工具适合用来做什么

- 一些使用运算符形式更容易将逻辑表达清楚的代码

- 作为常用工具函数的一种使用方法

- 一些适合使用 Emoji 图标表达的工具函数

## 使用方法

### 创建运算符

使用`Norn.operator`来创建每种自定义运算符：

```tsx
import Norn from 'norn';

// 使用Norn.operator创建运算符实例
const nornInstance = Norn.operator('custom operator', (initialValue: number, param1: number, param2: number) => {
  return (initialValue + param1) * param2;
});

// 由运算符实例来创建运算符函数
const n = nornInstance.create();

// 执行运算符函数得到结果
const result = n(10, 'custom operator', 100, 2); // 运算结果为220
```

如上例：

- `Norn.operator`的第一个参数`custom operator`为运算符标识，类型为 string；

- `Norn.operator`的第二个参数为一个用于执行运算符逻辑的函数，该函数的第一个参数`initialValue`运算符左侧传入的参数，限传 1 个；从第二个参数开始为运算符右侧传入的参数，理论上可以传任意个；

- `Norn.operator`方法的结果是一个`运算符实例`；调用运算符实例的`create`方法会创建用于执行的`运算符函数`；

- 调用运算符函数即可得到运算结果。运算符右侧支持传入任意个参数（含没有参数）。

### 创建多个运算符

`Norn.operator`可以链式调用多次，来创建支持多种自定义运算符的实例：

```tsx
import Norn from 'norn';

const nornInstance = Norn.operator('x10', (initialValue: number) => {
  return initialValue * 10;
})
  .operator('x20', (initialValue: number) => {
    return initialValue * 20;
  })
  .operator('x30', (initialValue: number) => {
    return initialValue * 30;
  });

const n = nornInstance.create();

const result = n(10, 'x10', 'x20', 'x30'); // 运算结果为60000
```

### 设定运算符实例参数

目前此工具的实现由于考虑到须正确处理运算符各参数、返回值的 TS 类型安全，以及提高 TS 类型运算性能，所以在创建运算符实例的 API 给出了一些限制参数。具体为在调用`nornInstance.create`时可传入：

- 运算符最大步长

```tsx
const n = nornInstance.create({
  steps: 4
});

/**
 * 如果steps设置为4，那么运算符函数最多可以运行4步（运行一次n函数，最多支持连续调用4次运算符）
 * 如果超过4次，会报出TS类型错误
 */
const result = n(10, 'x10', 'x20', 'x30', 'x40');
```

- 运算符右侧最大参数数量

```tsx
const n = nornInstance.create({
  args: 2
});

/**
 * 例如args设置为2时，每个运算符右侧可以0-2个参数
 * 如果超过2个，会报出TS类型错误
 */
const result = n(10, 'x10', param1, 'x20', param2, param3, 'x30', param4, 'x40');

// 另外，参数个数还可以制定得更精确一些：

/**
 * 例如argsRange设置为[1, 2]时，每个运算符右侧需要传1-2个参数
 * 如超过2个，或者没传参数，会报出TS类型错误
 */
const n2 = nornInstance.create({
  argsRange: [1, 2]
});
```

- 是否支持运算符左侧无参数

```tsx
const ln = nornInstance.create({
  type: 'l'
});

const n = nornInstance.create();

/**
 * 例如type设置为"l"，运算符函数可以支持在最左侧不传初始参数
 * 如果不设置type时在运算符最左侧不传初始参数，会报出TS类型错误
 */

// TS类型正确
const result = ln('operator1', param1, 'operator2', 'operator3');

// TS类型报错
const result2 = n('operator1', param1, 'operator2', 'operator3');
```

### 内置运算符

工具内置了 2 个运算符，可直接使用：

```ts
import { n } from 'norn';

const result = n(1, '..', 100); // 输出填充了1-100数字的数组

const result2 = n(1, '..<', 100); // 输出填充了1-99数字的数组
```

<!-- ## Roadmap -->

<!-- ## 它的命名

<p>
  <img src="https://joe-sky.github.io/nornj/static/banshee-norn.19486ec7.jpg" alt="Banshee Norn" width="800" />
</p> -->

## License

MIT

---
_Source: https://npm.io/package/norn · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._