ts-fsrs 5.3.0 → 5.3.2

package/README_JA.md

@@ -0,0 +1,251 @@
+# 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 は、Free Spaced Repetition Scheduler (FSRS) アルゴリズムを使って独自の間隔反復システムを構築するための TypeScript パッケージです。**
+
+## 目次
+
+- [ts-fsrs](#ts-fsrs)
+  - [目次](#目次)
+  - [インストール](#インストール)
+  - [クイックスタート](#クイックスタート)
+  - [使い方](#使い方)
+    - [カスタムパラメータ](#カスタムパラメータ)
+    - [`generatorParameters`](#generatorparameters)
+    - [`repeat` と `next`](#repeat-と-next)
+    - [想起確率](#想起確率)
+    - [`next_state` と `next_interval`](#next_state-と-next_interval)
+    - [履歴関連のヘルパー](#履歴関連のヘルパー)
+  - [リファレンス](#リファレンス)
+  - [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()
+```
+
+4 つの評価に対する結果をまとめてプレビューします。
+
+```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()` に渡せます。
+
+`generatorParameters()` は、シリアライズ、保存、または完全な `FSRSParameters` オブジェクトの再利用が必要な場合に使ってください。
+
+```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`
+
+ユーザーが回答する前に 4 通りの結果を見たい場合は `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) を参照してください。

package/dist/index.cjs

@@ -483,7 +483,7 @@ function alea(seed) {
   return prng;
 }
 
-const version="5.3.0";
+const version="5.3.2";
 
 const default_request_retention = 0.9;
 const default_maximum_interval = 36500;
@@ -971,9 +971,7 @@ class BasicScheduler extends AbstractScheduler {
     const steps_strategy = this.learningStepsStrategy(
       parameters,
       card.state,
-      // In the original learning steps setup (Again = 5m, Hard = 10m, Good = FSRS),
-      // not adding 1 can cause slight variations in the memory state’s ds.
-      this.current.state === State.Learning && grade !== Rating.Again && grade !== Rating.Hard ? card.learning_steps + 1 : card.learning_steps
+      card.learning_steps
     );
     const scheduled_minutes = Math.max(
       0,