timed-silky/README.md

Timed-Silky 是基于一款基于 TypeScript 的定时任务调度器。得益于 TypeScript，Timed-Silky 可以用符合特定句式的自然语言描述任务的调度规则，提供丝滑的链式调用接口。

# Timed-Silky（丝滑的定时任务调度器）

## 介绍

Timed-Silky 是基于一款基于 TypeScript 的定时任务调度器。得益于 TypeScript，Timed-Silky 可以用符合特定句式的自然语言描述任务的调度规则，提供丝滑的链式调用接口。

## 功能

- 支持按**固定时刻**，**特定频率**调度任务，还可限定**时间范围**。
- 支持秒级、分钟级、小时级、天级的频率调度。（未来可能会支持毫秒级、周级、月级、年级，看需求而定）。
- 充分利用 TypeScript 的类型能力，提供易于使用的两种接口：
    - 符合特定句式的链式调用接口。
    - 符合特定句式的自然语言描述接口。

## 优点

- 直观：可以用符合特定句式的自然语言描述定时任务，易于理解和维护。
- 简洁：提供符合特定句法的链式接口。
- 无心智负担：充分利用编辑器的智能提示，写代码时无需查看接口文档和源码。
- 依赖小，只依赖于浏览器和 Node.js 提供的 `setTimeout`，未来可以还会依赖 `SetInterval`。

## 使用

### 安装

```shell
pip install timed-silky
```

### 示例

#### 秒级任务

```typescript
import { silkyTimer } from "timed-silky";
let blink = () => {
    console.log(`${new Date().toLocaleString()}:眨眼`);
};

// 每 5 秒眨眼一次
silkyTimer.run(blink).timed("every 5 seconds");
// 7:30 至 23:00，每 5 秒眨眼一次，使用链式调用接口
silkyTimer.run(blink).every(5).seconds().from('7:30').to('23:00');
// 或者，使用自然语言接口
silkyTimer.run(blink).timed("every 5 seconds from 7:30 to 23:00");

// 启动
silkyTimer.start();
```

#### 分钟级任务

```typescript
import { silkyTimer } from "timed-silky";

let rest = () => {
    console.log(`${new Date().toLocaleString()}:休息`);
};

// 从 8:00 至 18:00，每 45 分钟休息一次
silkyTimer.run(rest).every(45).minutes().from('8:00').to('18:00');
// 或者
silkyTimer.run(rest).timed('every 45 minutes from 8:00 to 18:00');

// 启动
silkyTimer.start();
```

#### 小时级任务

```typescript
import { silkyTimer } from "timed-silky";

let eat = () => {
    console.log(`${new Date().toLocaleString()}:吃饭`);
};

// 每天 8 点、12 点、18 点 吃饭
silkyTimer.run(eat).timed('at 8:00,12:00 and 18:00');
// 或者，换种表达方式，还能接受语法检查
silkyTimer.run(eat).at('8:00', '12:00', '18:00');
// 或者，你比较随性，每四小时吃一次
silkyTimer.run(eat).every(4).hours().from("8:00").to("18:00");

// 启动
silkyTimer.start();
```

#### 天极任务

```TypeScript
import { silkyTimer } from "timed-silky";
// 一组待调度的任务
let clock = () => {
    console.log(`${new Date().toLocaleString()}:打上班卡`);
};

let report = () => {
    console.log(`${new Date().toLocaleString()}:写周报`);
};

let exercise = () => {
    console.log(`${new Date().toLocaleString()}:锻炼身体`);
}

// 每7天发一次周报
silkyTimer.run(report).every(7).days();
// 周一到周五，每天打一次上班卡
silkyTimer.run(clock).every_day().on('monday').to('friday');
// 周三、周六锻炼身体
silkyTimer.run(exercise).every_day().on('wednesday', 'saturday');
// 除了周六，每天都上班
silkyTimer.run(clock).every_day().except("saturday");
// 启动
silkyTimer.start();
```

## 注意

- Time-Silky 本质上还是调用 `setTimeout` 接口，被调度的任务在主线程执行，如果某个任务占用主线程太长时间，会推迟其他任务的执行时间。所以尽量安排异步任务、耗时不长的同步任务。
- Time-Silky 的能力只是 Linux Corn 能力的子集，但是更好理解，更好用。
- 在 1.0 版本未发布前，不要用于生产环境。