ts-fsrs 1.0.2 → 1.2.0

package/lib/fsrs.d.ts

@@ -3,33 +3,83 @@ import { Card, FSRSParameters, SchedulingCard } from "./index";
 export default class FSRS {
     private param;
     private readonly intervalModifier;
-    private seed;
+    private seed?;
     constructor(param?: FSRSParameters);
     repeat: (card: Card, now: dayjs.Dayjs) => import("./models").SchedulingLog;
+    get_retrievability: (card: Card, now: dayjs.Dayjs) => undefined | string;
     init_ds(s: SchedulingCard): void;
     /**
      *
-     * @param s 调度卡片
-     * @param last_d 难度
-     * @param last_s 稳定性
-     * @param retrievability 可提取性
+     * @param s scheduling Card
+     * @param last_d Difficulty
+     * @param last_s Stability
+     * @param retrievability Retrievability
      */
     next_ds(s: SchedulingCard, last_d: number, last_s: number, retrievability: number): void;
     /**
-     * 初始化记忆稳定化衰减
-     * @param r Rating
+     * The formula used is :
+     * $$S_0(G) = w_0 + G \cdot w_1$$
+     * $$\max \{S_0,0.1\}$$
+     * @param g Grade (rating at Anki) [0.again,1.hard,2.good,3.easy]
+     * @return Stability (interval when R=90%)
      */
-    init_stability(r: number): number;
+    init_stability(g: number): number;
     /**
-     * 初始化记忆稳定化曲线
-     * @param r Rating
+     * The formula used is :
+     * $$D_0(G) = w_2 + (G-2) \cdot w_3$$
+     * $$\min \{\max \{D_0(G),1\},10\}$$
+     * @param g Grade (rating at Anki) [0.again,1.hard,2.good,3.easy]
+     * @return Difficulty D \in [1,10]
      */
-    init_difficulty(r: number): number;
+    init_difficulty(g: number): number;
     apply_fuzz(ivl: number): number;
     next_interval(s: number): number;
+    /**
+     * The formula used is :
+     * $$next_d = D + w_4 \cdot (R - 2)$$
+     * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
+     * @param d
+     * @param r Rating[0.again,1.hard,2.good,3.easy]
+     * @return next_D
+     */
     next_difficulty(d: number, r: number): number;
+    /**
+     * The formula used is :
+     * $$\min \{\max \{D_0,1\},10\}$$
+     */
     constrain_difficulty(difficulty: number): number;
+    /**
+     * The formula used is :
+     * $$w_5 \cdot init +(1 - w_5) \cdot current$$
+     * @param init $$w_2 : D_0(2) = w_2 + (R-2) \cdot w_3= w_2$$
+     * @param current $$D + w_4 \cdot (R - 2)$$
+     * @return difficulty
+     */
     mean_reversion(init: number, current: number): number;
+    /**
+     * The formula used is :
+     * $$S^\prime_r(D,S,R) = S\cdot(e^{w_6}\cdot (11-D)\cdot S^{w_7}\cdot(e^{w_8\cdot(1-R)}-1)+1)$$
+     * @param d Difficulty D \in [1,10]
+     * @param s Stability (interval when R=90%)
+     * @param r Retrievability (probability of recall)
+     * @return S^\prime_r new stability after recall
+     */
     next_recall_stability(d: number, s: number, r: number): number;
+    /**
+     * The formula used is :
+     * $$S^\prime_f(D,S,R) = w_9\cdot D^{w_{10}}\cdot S^{w_{11}}\cdot e^{w_{12}\cdot(1-R)}.$$
+     * @param d Difficulty D \in [1,10]
+     * @param s Stability (interval when R=90%)
+     * @param r Retrievability (probability of recall)
+     * @return S^\prime_f new stability after forgetting
+     */
     next_forget_stability(d: number, s: number, r: number): number;
+    /**
+     * The formula used is :
+     * $$R(t,S) = 0.9^{\frac{t}{S}}$$
+     * @param t t days since the last review
+     * @param s Stability (interval when R=90%)
+     * @return r Retrievability (probability of recall)
+     */
+    current_retrievability(t: number, s: number): number;
 }

package/lib/fsrs.js

@@ -30,8 +30,8 @@ class FSRS {
                     break;
                 case index_1.State.Learning:
                 case index_1.State.Relearning:
-                    hard_interval = this.next_interval(s.hard.stability);
-                    good_interval = Math.max(this.next_interval(s.good.stability), hard_interval + 1);
+                    hard_interval = 0;
+                    good_interval = this.next_interval(s.good.stability);
                     easy_interval = Math.max(this.next_interval(s.easy.stability * this.param.easy_bonus), good_interval + 1);
                     s.schedule(now, hard_interval, good_interval, easy_interval);
                     break;
@@ -39,7 +39,7 @@ class FSRS {
                     const interval = card.elapsed_days;
                     const last_d = card.difficulty;
                     const last_s = card.stability;
-                    const retrievability = Math.exp(Math.log(0.9) * interval / last_s);
+                    const retrievability = this.current_retrievability(interval, last_s);
                     this.next_ds(s, last_d, last_s, retrievability);
                     hard_interval = this.next_interval(last_s * this.param.hard_factor);
                     good_interval = this.next_interval(s.good.stability);
@@ -51,9 +51,15 @@ class FSRS {
             }
             return s.record_log(card, now);
         };
+        this.get_retrievability = (card, now) => {
+            if (card.state !== index_1.State.Review) {
+                return undefined;
+            }
+            const t = Math.max(now.diff((0, dayjs_1.default)(card.last_review), "days"), 0);
+            return (this.current_retrievability(t, card.stability) * 100).toFixed(2) + '%';
+        };
         this.param = param || (0, index_1.generatorParameters)();
         this.intervalModifier = Math.log(this.param.request_retention) / Math.log(0.9);
-        this.seed = this.param.enable_fuzz ? "" : String(this.param.maximum_interval) + String(this.param.easy_bonus);
     }
     init_ds(s) {
         s.again.difficulty = this.init_difficulty(index_1.Rating.Again);
@@ -67,10 +73,10 @@ class FSRS {
     }
     /**
      *
-     * @param s 调度卡片
-     * @param last_d 难度
-     * @param last_s 稳定性
-     * @param retrievability 可提取性
+     * @param s scheduling Card
+     * @param last_d Difficulty
+     * @param last_s Stability
+     * @param retrievability Retrievability
      */
     next_ds(s, last_d, last_s, retrievability) {
         s.again.difficulty = this.next_difficulty(last_d, index_1.Rating.Again);
@@ -83,18 +89,24 @@ class FSRS {
         s.easy.stability = this.next_recall_stability(s.easy.difficulty, last_s, retrievability);
     }
     /**
-     * 初始化记忆稳定化衰减
-     * @param r Rating
+     * The formula used is :
+     * $$S_0(G) = w_0 + G \cdot w_1$$
+     * $$\max \{S_0,0.1\}$$
+     * @param g Grade (rating at Anki) [0.again,1.hard,2.good,3.easy]
+     * @return Stability (interval when R=90%)
      */
-    init_stability(r) {
-        return Math.max(this.param.w[0] + this.param.w[1] * r, 0.1);
+    init_stability(g) {
+        return Math.max(this.param.w[0] + this.param.w[1] * g, 0.1);
     }
     /**
-     * 初始化记忆稳定化曲线
-     * @param r Rating
+     * The formula used is :
+     * $$D_0(G) = w_2 + (G-2) \cdot w_3$$
+     * $$\min \{\max \{D_0(G),1\},10\}$$
+     * @param g Grade (rating at Anki) [0.again,1.hard,2.good,3.easy]
+     * @return Difficulty D \in [1,10]
      */
-    init_difficulty(r) {
-        return Math.min(Math.max(this.param.w[2] + this.param.w[3] * (r - 2), 1), 10);
+    init_difficulty(g) {
+        return Math.min(Math.max(this.param.w[2] + this.param.w[3] * (g - 2), 1), 10);
     }
     apply_fuzz(ivl) {
         if (!this.param.enable_fuzz || ivl < 2.5)
@@ -110,24 +122,69 @@ class FSRS {
         const newInterval = this.apply_fuzz(s * this.intervalModifier);
         return Math.min(Math.max(Math.round(newInterval), 1), this.param.maximum_interval);
     }
+    /**
+     * The formula used is :
+     * $$next_d = D + w_4 \cdot (R - 2)$$
+     * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
+     * @param d
+     * @param r Rating[0.again,1.hard,2.good,3.easy]
+     * @return next_D
+     */
     next_difficulty(d, r) {
         const next_d = d + this.param.w[4] * (r - 2);
         return this.constrain_difficulty(this.mean_reversion(this.param.w[2], next_d));
     }
+    /**
+     * The formula used is :
+     * $$\min \{\max \{D_0,1\},10\}$$
+     */
     constrain_difficulty(difficulty) {
         return Math.min(Math.max(Number(difficulty.toFixed(2)), 1), 10);
     }
+    /**
+     * The formula used is :
+     * $$w_5 \cdot init +(1 - w_5) \cdot current$$
+     * @param init $$w_2 : D_0(2) = w_2 + (R-2) \cdot w_3= w_2$$
+     * @param current $$D + w_4 \cdot (R - 2)$$
+     * @return difficulty
+     */
     mean_reversion(init, current) {
         return this.param.w[5] * init + (1 - this.param.w[5]) * current;
     }
+    /**
+     * The formula used is :
+     * $$S^\prime_r(D,S,R) = S\cdot(e^{w_6}\cdot (11-D)\cdot S^{w_7}\cdot(e^{w_8\cdot(1-R)}-1)+1)$$
+     * @param d Difficulty D \in [1,10]
+     * @param s Stability (interval when R=90%)
+     * @param r Retrievability (probability of recall)
+     * @return S^\prime_r new stability after recall
+     */
     next_recall_stability(d, s, r) {
         return s * (1 + Math.exp(this.param.w[6]) *
             (11 - d) *
             Math.pow(s, this.param.w[7]) *
             (Math.exp((1 - r) * this.param.w[8]) - 1));
     }
+    /**
+     * The formula used is :
+     * $$S^\prime_f(D,S,R) = w_9\cdot D^{w_{10}}\cdot S^{w_{11}}\cdot e^{w_{12}\cdot(1-R)}.$$
+     * @param d Difficulty D \in [1,10]
+     * @param s Stability (interval when R=90%)
+     * @param r Retrievability (probability of recall)
+     * @return S^\prime_f new stability after forgetting
+     */
     next_forget_stability(d, s, r) {
         return this.param.w[9] * Math.pow(d, this.param.w[10]) * Math.pow(s, this.param.w[11]) * Math.exp((1 - r) * this.param.w[12]);
     }
+    /**
+     * The formula used is :
+     * $$R(t,S) = 0.9^{\frac{t}{S}}$$
+     * @param t t days since the last review
+     * @param s Stability (interval when R=90%)
+     * @return r Retrievability (probability of recall)
+     */
+    current_retrievability(t, s) {
+        return Math.exp(Math.log(0.9) * t / s);
+    }
 }
 exports.default = FSRS;

package/lib/index.d.ts

@@ -18,7 +18,7 @@ declare const generatorParameters: (props?: {
     w: number[];
     enable_fuzz: boolean;
 };
-declare const FSRS_Version = 1;
+declare const FSRS_Version = 1.2;
 export { fsrs, FSRS_Version, State, Rating, SchedulingCard, createEmptyCard, generatorParameters };
 export type { StateType, RatingType, ReviewLog, Card, SchedulingLog, FSRSParameters };
 export { default_request_retention, default_maximum_interval, default_easy_bonus, default_hard_factor, default_w, default_enable_fuzz };

package/lib/index.js

@@ -56,5 +56,5 @@ const generatorParameters = (props) => {
     };
 };
 exports.generatorParameters = generatorParameters;
-const FSRS_Version = 1.00;
+const FSRS_Version = 1.20;
 exports.FSRS_Version = FSRS_Version;

package/lib/scheduler.js

@@ -23,7 +23,7 @@ class SchedulingCard {
         }
         else if (state === models_1.State.Learning || state === models_1.State.Relearning) {
             this.again.state = state;
-            this.hard.state = models_1.State.Review;
+            this.hard.state = state;
             this.good.state = models_1.State.Review;
             this.easy.state = models_1.State.Review;
         }
@@ -42,7 +42,7 @@ class SchedulingCard {
         this.good.scheduled_days = good_interval;
         this.easy.scheduled_days = easy_interval;
         this.again.due = now.add(5, 'minutes');
-        this.hard.due = now.add(hard_interval, 'days');
+        this.hard.due = hard_interval > 0 ? now.add(hard_interval, 'days') : now.add(10, 'minutes');
         this.good.due = now.add(good_interval, 'days');
         this.easy.due = now.add(easy_interval, 'days');
         return this;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-fsrs",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "ts-fsrs is a TypeScript package used to implement the Free Spaced Repetition Scheduler (FSRS) algorithm. It helps developers apply FSRS to their flashcard applications, thereby improving the user learning experience.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -20,11 +20,16 @@
   },
   "scripts": {
     "test": "ts-node test/index.ts",
-    "build": "tsc"
+    "build": "tsc",
+    "test_publish": "yalc publish"
   },
   "author": "ishiko",
   "license": "MIT",
-  "files": ["lib/**/*"],
+  "files": [
+    "lib/**/*",
+    "README.md",
+    "LICENSE"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ishiko732/ts-fsrs.git"