ts-fsrs 5.3.0 → 5.3.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # ts-fsrs
 
+## 5.3.2
+
+### Patch Changes
+
+- [#329](https://github.com/open-spaced-repetition/ts-fsrs/pull/329) [`5cd8949`](https://github.com/open-spaced-repetition/ts-fsrs/commit/5cd8949544788224eada1b2e6f8597756ca594cb) Thanks [@ishiko732](https://github.com/ishiko732)! - fix: include README, localized package docs, and license files in the published `ts-fsrs` tarball
+
+## 5.3.1
+
+### Patch Changes
+
+- [#315](https://github.com/open-spaced-repetition/ts-fsrs/pull/315) [`40e712e`](https://github.com/open-spaced-repetition/ts-fsrs/commit/40e712ebf229997154682294f40436bf1524022d) Thanks [@moaaz-ae](https://github.com/moaaz-ae)! - fix: prevent unexpected skipping of learning steps when Rating.Good is selected in State.Learning (#311)
+
 ## 5.3.0
 
 ### Minor Changes

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Open Spaced Repetition
+Copyright (c) 2026 Open Spaced Repetition
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,253 @@
+# ts-fsrs
+
+[![fsrs version](https://img.shields.io/badge/FSRS-v6-blue?style=flat-square)](https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm#fsrs-6)
+[![npm version](https://img.shields.io/npm/v/ts-fsrs.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/ts-fsrs)
+[![downloads](https://img.shields.io/npm/dm/ts-fsrs?style=flat-square)](https://www.npmjs.com/package/ts-fsrs)
+
+[Introduction](./README.md) | [简体中文](./README_CN.md) | [はじめに](./README_JA.md)
+
+**ts-fsrs is a TypeScript package that helps developers build their own spaced repetition system using the Free Spaced Repetition Scheduler algorithm.**
+
+## Table of Contents
+
+- [ts-fsrs](#ts-fsrs)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Quickstart](#quickstart)
+  - [Usage](#usage)
+    - [Custom parameters](#custom-parameters)
+    - [`generatorParameters`](#generatorparameters)
+    - [`repeat` vs `next`](#repeat-vs-next)
+    - [Retrievability](#retrievability)
+    - [`next_state` and `next_interval`](#next_state-and-next_interval)
+    - [History helpers](#history-helpers)
+  - [Reference](#reference)
+  - [API Documentation](#api-documentation)
+  - [Examples](#examples)
+  - [Contributing](#contributing)
+
+## Installation
+
+`ts-fsrs` requires Node.js `>=20.0.0`.
+
+```bash
+npm install ts-fsrs
+yarn add ts-fsrs
+pnpm install ts-fsrs
+bun add ts-fsrs
+```
+
+## Quickstart
+
+Import and initialize the scheduler:
+
+```ts
+import { createEmptyCard, fsrs, Rating } from 'ts-fsrs'
+
+const scheduler = fsrs()
+```
+
+Create a new card:
+
+```ts
+const card = createEmptyCard()
+```
+
+Preview all possible scheduling outcomes:
+
+```ts
+const preview = scheduler.repeat(card, new Date())
+
+console.log(preview[Rating.Again].card)
+console.log(preview[Rating.Hard].card)
+console.log(preview[Rating.Good].card)
+console.log(preview[Rating.Easy].card)
+```
+
+Apply a specific rating:
+
+```ts
+const result = scheduler.next(card, new Date(), Rating.Good)
+
+console.log(result.card)
+console.log(result.log)
+```
+
+## Usage
+
+### Custom parameters
+
+```ts
+import { fsrs } from 'ts-fsrs'
+
+const scheduler = fsrs({
+  request_retention: 0.9,
+  maximum_interval: 36500,
+  enable_fuzz: true,
+  enable_short_term: true,
+  learning_steps: ['1m', '10m'],
+  relearning_steps: ['10m'],
+})
+```
+
+`request_retention` Is the percentage (`0.0-1.0`) that the scheduler will try and have you get correct. Higher values increase review load, lower values reduce it.
+
+`maximum_interval` caps how far into the future a card can be scheduled.
+
+`enable_fuzz` adds a small amount of randomness to long intervals.
+
+`enable_short_term`, `learning_steps`, and `relearning_steps` control short-term and relearning step behavior.
+
+### `generatorParameters`
+
+`fsrs()` already applies `generatorParameters()` internally, so in normal scheduler setup you can pass a partial parameter object directly to `fsrs()`.
+
+Use `generatorParameters()` when you need a complete `FSRSParameters` object for serialization, persistence, or reuse:
+
+```ts
+import { fsrs, generatorParameters } from 'ts-fsrs'
+
+const params = generatorParameters({
+  request_retention: 0.9,
+  maximum_interval: 36500,
+})
+
+console.log(JSON.stringify(params))
+
+const scheduler = fsrs(params)
+```
+
+If you persist those parameters and load them later, pass the parsed object back into `fsrs()`:
+
+```ts
+import { fsrs, type FSRSParameters } from 'ts-fsrs'
+
+const serializedParams = '{"request_retention":0.9,"maximum_interval":36500}'
+const params = JSON.parse(serializedParams) as FSRSParameters
+const scheduler = fsrs(params)
+```
+
+If the parameters come from external storage, user input, or the network, validate them at your application boundary before passing them to `fsrs()`. A runtime schema library such as `zod` is a good fit for that.
+
+### `repeat` vs `next`
+
+Use `repeat` when you want to preview all four outcomes before the user answers.
+
+```ts
+const preview = scheduler.repeat(card, new Date())
+```
+
+Use `next` when you already know the selected rating.
+
+```ts
+const result = scheduler.next(card, new Date(), Rating.Good)
+```
+
+If you want to map the result into your own storage type, pass an `afterHandler`.
+
+```ts
+const saved = scheduler.next(card, new Date(), Rating.Good, ({ card, log }) => ({
+  card: {
+    ...card,
+    due: card.due.getTime(),
+    last_review: card.last_review?.getTime() ?? null,
+  },
+  log: {
+    ...log,
+    due: log.due.getTime(),
+    review: log.review.getTime(),
+  },
+}))
+```
+
+### Retrievability
+
+```ts
+const retrievability = scheduler.get_retrievability(result.card, new Date(), false)
+console.log(retrievability)
+```
+
+You can also calculate retrievability directly with `forgetting_curve()` if you already have `elapsed_days`, `stability`, and a valid decay value:
+
+```ts
+import { forgetting_curve } from 'ts-fsrs'
+
+const retrievability = forgetting_curve(0.5, 12, result.card.stability)
+console.log(retrievability)
+```
+
+When you pass a decay value directly, it must be positive and within the range `0.1` to `0.8`.
+
+### `next_state` and `next_interval`
+
+If you are working directly with memory states, you can combine `next_state()` and `next_interval()`:
+
+```ts
+import { fsrs, Rating, type FSRSState } from 'ts-fsrs'
+
+const scheduler = fsrs({ enable_fuzz: false })
+
+const memoryState: FSRSState = {
+  stability: 3.2,
+  difficulty: 5.6,
+}
+
+const elapsedDays = 12
+const nextState = scheduler.next_state(memoryState, elapsedDays, Rating.Good)
+const nextInterval = scheduler.next_interval(nextState.stability, elapsedDays)
+
+console.log(nextState)
+console.log(nextInterval)
+```
+
+This is useful for simulations, analytics, or custom scheduling pipelines. For standard review flows, prefer `repeat()` or `next()`.
+
+### History helpers
+
+The scheduler also provides:
+
+- `rollback(card, log)`
+- `forget(card, now, reset_count?)`
+- `reschedule(card, reviews, options?)`
+
+These are useful when replaying imported review logs or rebuilding state from persistence.
+
+## Reference
+
+Card states:
+
+```ts
+State.New
+State.Learning
+State.Review
+State.Relearning
+```
+
+Review ratings:
+
+```ts
+Rating.Again
+Rating.Hard
+Rating.Good
+Rating.Easy
+```
+
+## API Documentation
+
+- Repository overview: [github.com/open-spaced-repetition/ts-fsrs](https://github.com/open-spaced-repetition/ts-fsrs#readme)
+- TypeDoc API docs: [open-spaced-repetition.github.io/ts-fsrs](https://open-spaced-repetition.github.io/ts-fsrs/)
+- Optimizer package: [`@open-spaced-repetition/binding`](https://www.npmjs.com/package/@open-spaced-repetition/binding)
+- Simplified Chinese README: [README_CN.md](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/packages/fsrs/README_CN.md)
+- Japanese README: [README_JA.md](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/packages/fsrs/README_JA.md)
+
+## Examples
+
+- Browser example: [example/example.html](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/example/example.html)
+- Full-stack demo: [ts-fsrs-demo](https://github.com/ishiko732/ts-fsrs-demo)
+- Other:
+  - [spaced](https://github.com/zsh-eng/spaced)
+  - [Anki Search Stats Extended](https://github.com/Luc-Mcgrady/Anki-Search-Stats-Extended)
+
+## Contributing
+
+Contribution guidelines are available in [`CONTRIBUTING.md`](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/CONTRIBUTING.md).

package/README_CN.md

@@ -0,0 +1,243 @@
+# ts-fsrs
+
+[Introduction](./README.md) | [简体中文](./README_CN.md) | [はじめに](./README_JA.md)
+
+[![fsrs version](https://img.shields.io/badge/FSRS-v6-blue?style=flat-square)](https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm#fsrs-6)
+[![npm version](https://img.shields.io/npm/v/ts-fsrs.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/ts-fsrs)
+[![downloads](https://img.shields.io/npm/dm/ts-fsrs?style=flat-square)](https://www.npmjs.com/package/ts-fsrs)
+
+**ts-fsrs 是一个 TypeScript 包，帮助开发者基于自由间隔重复调度器（FSRS）算法构建自己的间隔重复系统。**
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [使用说明](#使用说明)
+- [参考](#参考)
+- [API 文档](#api-文档)
+- [示例](#示例)
+- [贡献](#贡献)
+
+## 安装
+
+`ts-fsrs` 需要 Node.js `>=20.0.0`。
+
+```bash
+npm install ts-fsrs
+yarn add ts-fsrs
+pnpm install ts-fsrs
+bun add ts-fsrs
+```
+
+## 快速开始
+
+导入并初始化调度器：
+
+```ts
+import { createEmptyCard, fsrs, Rating } from 'ts-fsrs'
+
+const scheduler = fsrs()
+```
+
+创建一张新卡片：
+
+```ts
+const card = createEmptyCard()
+```
+
+预览四种评分下的全部调度结果：
+
+```ts
+const preview = scheduler.repeat(card, new Date())
+
+console.log(preview[Rating.Again].card)
+console.log(preview[Rating.Hard].card)
+console.log(preview[Rating.Good].card)
+console.log(preview[Rating.Easy].card)
+```
+
+如果用户已经作答，可以直接应用一个确定评分：
+
+```ts
+const result = scheduler.next(card, new Date(), Rating.Good)
+
+console.log(result.card)
+console.log(result.log)
+```
+
+## 使用说明
+
+### 自定义参数
+
+```ts
+import { fsrs } from 'ts-fsrs'
+
+const scheduler = fsrs({
+  request_retention: 0.9,
+  maximum_interval: 36500,
+  enable_fuzz: true,
+  enable_short_term: true,
+  learning_steps: ['1m', '10m'],
+  relearning_steps: ['10m'],
+})
+```
+
+`request_retention` 调度器希望维持的最低记忆保持率（0%到100%）。值越高，复习越频繁；值越低，复习越少。
+
+`maximum_interval` 用于限制卡片最多可以被安排到未来多少天。
+
+`enable_fuzz` 会给较长的间隔增加少量随机扰动，避免大量卡片在同一天到期。
+
+`enable_short_term`、`learning_steps` 和 `relearning_steps` 用于控制短期学习和重新学习步骤。
+
+### `generatorParameters`
+
+`fsrs()` 内部已经会调用 `generatorParameters()` 来补齐和规范化参数，所以普通初始化调度器时，直接把部分参数对象传给 `fsrs()` 即可。
+
+当你需要一个完整的 `FSRSParameters` 对象用于序列化、持久化或复用时，再使用 `generatorParameters()`：
+
+```ts
+import { fsrs, generatorParameters } from 'ts-fsrs'
+
+const params = generatorParameters({
+  request_retention: 0.9,
+  maximum_interval: 36500,
+})
+
+console.log(JSON.stringify(params))
+
+const scheduler = fsrs(params)
+```
+
+如果你把参数持久化之后再加载回来，也可以把解析后的对象直接传回 `fsrs()`：
+
+```ts
+import { fsrs, type FSRSParameters } from 'ts-fsrs'
+
+const serializedParams = '{"request_retention":0.9,"maximum_interval":36500}'
+const params = JSON.parse(serializedParams) as FSRSParameters
+const scheduler = fsrs(params)
+```
+
+如果这些参数来自外部存储、用户输入或网络，建议在应用边界先做运行时校验，再传给 `fsrs()`。像 `zod` 这样的运行时 schema 校验库就很适合这个场景。
+
+### `repeat` 与 `next`
+
+如果你需要在用户作答前预览四种评分结果，使用 `repeat`：
+
+```ts
+const preview = scheduler.repeat(card, new Date())
+```
+
+如果你已经拿到了用户的评分，直接使用 `next`：
+
+```ts
+const result = scheduler.next(card, new Date(), Rating.Good)
+```
+
+如果你想把结果直接映射成自己的存储结构，可以传入 `afterHandler`：
+
+```ts
+const saved = scheduler.next(card, new Date(), Rating.Good, ({ card, log }) => ({
+  card: {
+    ...card,
+    due: card.due.getTime(),
+    last_review: card.last_review?.getTime() ?? null,
+  },
+  log: {
+    ...log,
+    due: log.due.getTime(),
+    review: log.review.getTime(),
+  },
+}))
+```
+
+### 可提取率
+
+```ts
+const retrievability = scheduler.get_retrievability(result.card, new Date(), false)
+console.log(retrievability)
+```
+
+如果你已经有 `elapsed_days`、`stability` 和合法的 decay 值，也可以直接用 `forgetting_curve()` 来计算可提取率：
+
+```ts
+import { forgetting_curve } from 'ts-fsrs'
+
+const retrievability = forgetting_curve(0.5, 12, result.card.stability)
+console.log(retrievability)
+```
+
+如果你直接传入 decay，它必须是正数，并且范围在 `0.1` 到 `0.8` 之间。
+
+### `next_state` 与 `next_interval`
+
+如果你直接基于记忆状态做推导，可以把 `next_state()` 和 `next_interval()` 组合使用：
+
+```ts
+import { fsrs, Rating, type FSRSState } from 'ts-fsrs'
+
+const scheduler = fsrs({ enable_fuzz: false })
+
+const memoryState: FSRSState = {
+  stability: 3.2,
+  difficulty: 5.6,
+}
+
+const elapsedDays = 12
+const nextState = scheduler.next_state(memoryState, elapsedDays, Rating.Good)
+const nextInterval = scheduler.next_interval(nextState.stability, elapsedDays)
+
+console.log(nextState)
+console.log(nextInterval)
+```
+
+这种写法适合做模拟、分析，或者你自己维护 `{ stability, difficulty }` 的自定义调度流程。对于普通复习流程，优先使用 `repeat()` 或 `next()`。
+
+### 历史辅助能力
+
+调度器还提供这些辅助方法：
+
+- `rollback(card, log)`
+- `forget(card, now, reset_count?)`
+- `reschedule(card, reviews, options?)`
+
+它们适合导入旧数据、回放历史复习记录，或从持久化日志重建卡片状态。
+
+## 参考
+
+卡片状态：
+
+```ts
+State.New
+State.Learning
+State.Review
+State.Relearning
+```
+
+评分枚举：
+
+```ts
+Rating.Again
+Rating.Hard
+Rating.Good
+Rating.Easy
+```
+
+## API 文档
+
+- 仓库主页：[github.com/open-spaced-repetition/ts-fsrs](https://github.com/open-spaced-repetition/ts-fsrs#readme)
+- TypeDoc API 文档：[open-spaced-repetition.github.io/ts-fsrs](https://open-spaced-repetition.github.io/ts-fsrs/)
+- 优化器包：[`@open-spaced-repetition/binding`](https://www.npmjs.com/package/@open-spaced-repetition/binding)
+
+## 示例
+
+- 浏览器示例：[example/example.html](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/example/example.html)
+- 完整示例项目：[ts-fsrs-demo](https://github.com/ishiko732/ts-fsrs-demo)
+- 其他：
+  - [spaced](https://github.com/zsh-eng/spaced)
+  - [Anki Search Stats Extended](https://github.com/Luc-Mcgrady/Anki-Search-Stats-Extended)
+
+## 贡献
+
+贡献说明见 [`CONTRIBUTING.md`](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/CONTRIBUTING.md)。