ts-fsrs 3.0.3 → 3.0.5

package/README.md

@@ -30,26 +30,91 @@ const now = new Date('2022-2-2 10:00:00');// new Date();
 const scheduling_cards = f.repeat(card, now);
 
 // console.log(scheduling_cards);
-Object.keys(Rating).filter(key => typeof Rating[key as any] === 'number').forEach(key => {
-  // @ts-ignore
-  const { log, card } = scheduling_cards[Rating[key]];
-  console.group(`${key}`);
-  console.table({
-    [`card_${key}`]: {
-      ...card,
-      due: formatDate(card.due),
-      last_review: formatDate(card.last_review),
-    },
-  });
-  console.table({
-    [`log_${key}`]: {
-      ...log,
-      review: formatDate(log.review),
-    },
-  });
-  console.groupEnd();
-  console.log('----------------------------------------------------------------');
-});
-```
-
-> More examples refer to the [Example](https://github.com/ishiko732/ts-fsrs/blob/master/example/index.ts)
+Object.keys(Rating)
+    .filter(key => !isNaN(Number(key)))
+    .map(key => Number(key) as Rating) // [Rating.Again, Rating.Hard, Rating.Good, Rating.Easy]
+    .forEach(grade => {
+        const { log, card } = scheduling_cards[grade];
+        console.group(`${Rating[grade]}`);
+        console.table({
+            [`card_${Rating[grade]}`]: {
+                ...card,
+                due: formatDate(card.due),
+                last_review: formatDate(card.last_review as Date),
+            },
+        });
+        console.table({
+            [`log_${Rating[grade]}`]: {
+                ...log,
+                review: formatDate(log.review),
+            },
+        });
+        console.groupEnd();
+        console.log('----------------------------------------------------------------');
+    });
+```
+
+> More examples refer to the [Example](https://github.com/ishiko732/ts-fsrs/blob/master/example/index.ts)
+
+
+# Basic Use 
+
+## 1. **Initialization**:
+To begin, create an empty card instance and set the current date:
+
+```typescript
+import { Card, createEmptyCard } from "ts-fsrs";
+let card: Card = createEmptyCard();
+```
+
+## 2. **Parameter Configuration**:
+The library allows for customization of SRS parameters. Use `generatorParameters` to produce the final set of parameters for the SRS algorithm. Here's an example setting a maximum interval:
+
+```typescript
+import { Card, createEmptyCard, generatorParameters, FSRSParameters } from "ts-fsrs";
+let card: Card = createEmptyCard();
+const params: FSRSParameters = generatorParameters({ maximum_interval: 1000 });
+```
+
+## 3. **Scheduling with FSRS**:
+The core functionality lies in the `fsrs` function. When invoked, it returns a collection of cards scheduled based on different potential user ratings:
+
+```typescript
+import {
+  Card,
+  createEmptyCard,
+  generatorParameters,
+  FSRSParameters,
+  FSRS,
+  RecordLog,
+} from "ts-fsrs";
+
+let card: Card = createEmptyCard();
+const f: FSRS = new FSRS(); // or const f: FSRS = fsrs(params);
+let scheduling_cards: RecordLog = f.repeat(card, new Date());
+```
+
+## 4. **Retrieving Scheduled Cards**:
+Once you have the `scheduling_cards` object, you can retrieve cards based on user ratings. For instance, to access the card scheduled for a 'Good' rating:
+
+```typescript
+const good: RecordLogItem = scheduling_cards[Rating.Good];
+const newCard: Card = good.card;
+```
+
+## 5. **Understanding Card Attributes**:
+Each `Card` object consists of various attributes that determine its status, scheduling, and other metrics:
+
+```typescript
+type Card = {
+  due: Date;           // Date when the card is next due for review
+  stability: number;   // A measure of how well the information is retained
+  difficulty: number;  // Reflects the inherent difficulty of the card content
+  elapsed_days: number; // Days since the card was last reviewed
+  scheduled_days: number; // The interval at which the card is next scheduled
+  reps: number;          // Total number of times the card has been reviewed
+  lapses: number;        // Times the card was forgotten or remembered incorrectly
+  state: State;          // The current state of the card (New, Learning, Review, Relearning)
+  last_review?: Date;    // The most recent review date, if applicable
+};
+```

package/dist/algorithm.d.ts

@@ -0,0 +1,99 @@
+import { SchedulingCard } from "./index";
+import { FSRSParameters, Rating } from "./models";
+import type { int } from "./type";
+export declare class FSRSAlgorithm {
+    protected param: FSRSParameters;
+    private readonly intervalModifier;
+    protected seed?: string;
+    constructor(param: Partial<FSRSParameters>);
+    init_ds(s: SchedulingCard): void;
+    /**
+     * Updates the difficulty and stability values of the scheduling card based on the last difficulty,
+     * last stability, and the current retrievability.
+     * @param {SchedulingCard} s scheduling Card
+     * @param {number} last_d Difficulty
+     * @param {number} last_s Stability
+     * @param retrievability Retrievability
+     */
+    next_ds(s: SchedulingCard, last_d: number, last_s: number, retrievability: number): void;
+    /**
+     * The formula used is :
+     * S_0(G) = w_{G-1}
+     * \max \{S_0,0.1\}
+     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @return Stability (interval when R=90%)
+     */
+    init_stability(g: number): number;
+    /**
+     * The formula used is :
+     * $$D_0(G) = w_4 - (G-3) \cdot w_5$$
+     * $$\min \{\max \{D_0(G),1\},10\}$$
+     * where the D_0(3)=w_4 when the first rating is good.
+     * @param {number} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @return {number} Difficulty D \in [1,10]
+     */
+    init_difficulty(g: number): number;
+    /**
+     * If fuzzing is disabled or ivl is less than 2.5, it returns the original interval.
+     * @param {number} ivl - The interval to be fuzzed.
+     * @return {number} - The fuzzed interval.
+     **/
+    apply_fuzz(ivl: number): number;
+    /**
+     *  Ref:
+     *   constructor(param: Partial<FSRSParameters>)
+     *   this.intervalModifier = 9 * (1 / this.param.request_retention - 1);
+     *   @param {number} s - Stability (interval when R=90%)
+     */
+    next_interval(s: number): int;
+    /**
+     * The formula used is :
+     * $$next_d = D - w_6 \cdot (R - 2)$$
+     * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
+     * @param {number} d Difficulty D \in [1,10]
+     * @param {Rating} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @return {number} next_D
+     */
+    next_difficulty(d: number, g: number): number;
+    /**
+     * The formula used is :
+     * $$\min \{\max \{D_0,1\},10\}$$
+     * @param {number} difficulty D \in [1,10]
+     */
+    constrain_difficulty(difficulty: number): number;
+    /**
+     * The formula used is :
+     * $$w_7 \cdot init +(1 - w_7) \cdot current$$
+     * @param {number} init $$w_2 : D_0(3) = w_2 + (R-2) \cdot w_3= w_2$$
+     * @param {number} current $$D - w_6 \cdot (R - 2)$$
+     * @return {number} difficulty
+     */
+    mean_reversion(init: number, current: number): number;
+    /**
+     * The formula used is :
+     * $$S^\prime_r(D,S,R,G) = S\cdot(e^{w_8}\cdot (11-D)\cdot S^{-w_9}\cdot(e^{w_10\cdot(1-R)}-1)\cdot w_15(if G=2) \cdot w_16(if G=4)+1)$$
+     * @param {number} d Difficulty D \in [1,10]
+     * @param {number} s Stability (interval when R=90%)
+     * @param {number} r Retrievability (probability of recall)
+     * @param {Rating} g Grade (Rating[0.again,1.hard,2.good,3.easy])
+     * @return {number} S^\prime_r new stability after recall
+     */
+    next_recall_stability(d: number, s: number, r: number, g: Rating): number;
+    /**
+     * The formula used is :
+     * $$S^\prime_f(D,S,R) = w_11\cdot D^{-w_{12}}\cdot ((S+1)^{w_{13}}-1) \cdot e^{w_{14}\cdot(1-R)}.$$
+     * @param {number} d Difficulty D \in [1,10]
+     * @param {number} s Stability (interval when R=90%)
+     * @param {number} r Retrievability (probability of recall)
+     * @return {number} S^\prime_f new stability after forgetting
+     */
+    next_forget_stability(d: number, s: number, r: number): number;
+    /**
+     * The formula used is :
+     * $$R(t,S) = (1 + \frac{t}{9 \cdot S})^{-1},$$
+     * @param {number} t t days since the last review
+     * @param {number} s Stability (interval when R=90%)
+     * @return {number} r Retrievability (probability of recall)
+     */
+    current_retrievability(t: number, s: number): number;
+}

package/dist/algorithm.js

@@ -0,0 +1,171 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FSRSAlgorithm = void 0;
+const seedrandom_1 = __importDefault(require("seedrandom"));
+const index_1 = require("./index");
+const models_1 = require("./models");
+// Ref: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm#fsrs-v4
+class FSRSAlgorithm {
+    param;
+    intervalModifier;
+    seed;
+    constructor(param) {
+        this.param = (0, index_1.generatorParameters)(param);
+        // Ref: https://github.com/open-spaced-repetition/py-fsrs/blob/ecd68e453611eb808c7367c7a5312d7cadeedf5c/src/fsrs/fsrs.py#L79
+        // The formula used is : I(r,s)=9 \cdot  s \cdot (\frac{1}{r}-1)
+        this.intervalModifier = 9 * (1 / this.param.request_retention - 1);
+    }
+    init_ds(s) {
+        s.again.difficulty = this.init_difficulty(models_1.Rating.Again);
+        s.again.stability = this.init_stability(models_1.Rating.Again);
+        s.hard.difficulty = this.init_difficulty(models_1.Rating.Hard);
+        s.hard.stability = this.init_stability(models_1.Rating.Hard);
+        s.good.difficulty = this.init_difficulty(models_1.Rating.Good);
+        s.good.stability = this.init_stability(models_1.Rating.Good);
+        s.easy.difficulty = this.init_difficulty(models_1.Rating.Easy);
+        s.easy.stability = this.init_stability(models_1.Rating.Easy);
+    }
+    /**
+     * Updates the difficulty and stability values of the scheduling card based on the last difficulty,
+     * last stability, and the current retrievability.
+     * @param {SchedulingCard} s scheduling Card
+     * @param {number} last_d Difficulty
+     * @param {number} last_s Stability
+     * @param retrievability Retrievability
+     */
+    next_ds(s, last_d, last_s, retrievability) {
+        s.again.difficulty = this.next_difficulty(last_d, models_1.Rating.Again);
+        s.again.stability = this.next_forget_stability(s.again.difficulty, last_s, retrievability);
+        s.hard.difficulty = this.next_difficulty(last_d, models_1.Rating.Hard);
+        s.hard.stability = this.next_recall_stability(s.hard.difficulty, last_s, retrievability, models_1.Rating.Hard);
+        s.good.difficulty = this.next_difficulty(last_d, models_1.Rating.Good);
+        s.good.stability = this.next_recall_stability(s.good.difficulty, last_s, retrievability, models_1.Rating.Good);
+        s.easy.difficulty = this.next_difficulty(last_d, models_1.Rating.Easy);
+        s.easy.stability = this.next_recall_stability(s.easy.difficulty, last_s, retrievability, models_1.Rating.Easy);
+    }
+    /**
+     * The formula used is :
+     * S_0(G) = w_{G-1}
+     * \max \{S_0,0.1\}
+     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @return Stability (interval when R=90%)
+     */
+    init_stability(g) {
+        return Math.max(this.param.w[g - 1], 0.1);
+    }
+    /**
+     * The formula used is :
+     * $$D_0(G) = w_4 - (G-3) \cdot w_5$$
+     * $$\min \{\max \{D_0(G),1\},10\}$$
+     * where the D_0(3)=w_4 when the first rating is good.
+     * @param {number} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @return {number} Difficulty D \in [1,10]
+     */
+    init_difficulty(g) {
+        return Math.min(Math.max(this.param.w[4] - (g - 3) * this.param.w[5], 1), 10);
+    }
+    /**
+     * If fuzzing is disabled or ivl is less than 2.5, it returns the original interval.
+     * @param {number} ivl - The interval to be fuzzed.
+     * @return {number} - The fuzzed interval.
+     **/
+    apply_fuzz(ivl) {
+        if (!this.param.enable_fuzz || ivl < 2.5)
+            return ivl;
+        const generator = (0, seedrandom_1.default)(this.seed);
+        const fuzz_factor = generator();
+        ivl = Math.round(ivl);
+        const min_ivl = Math.max(2, Math.round(ivl * 0.95 - 1));
+        const max_ivl = Math.round(ivl * 1.05 + 1);
+        return Math.floor(fuzz_factor * (max_ivl - min_ivl + 1) + min_ivl);
+    }
+    /**
+     *  Ref:
+     *   constructor(param: Partial<FSRSParameters>)
+     *   this.intervalModifier = 9 * (1 / this.param.request_retention - 1);
+     *   @param {number} s - Stability (interval when R=90%)
+     */
+    next_interval(s) {
+        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_6 \cdot (R - 2)$$
+     * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
+     * @param {number} d Difficulty D \in [1,10]
+     * @param {Rating} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @return {number} next_D
+     */
+    next_difficulty(d, g) {
+        const next_d = d - this.param.w[6] * (g - 3);
+        return this.constrain_difficulty(this.mean_reversion(this.param.w[4], next_d));
+    }
+    /**
+     * The formula used is :
+     * $$\min \{\max \{D_0,1\},10\}$$
+     * @param {number} difficulty D \in [1,10]
+     */
+    constrain_difficulty(difficulty) {
+        return Math.min(Math.max(Number(difficulty.toFixed(2)), 1), 10);
+    }
+    /**
+     * The formula used is :
+     * $$w_7 \cdot init +(1 - w_7) \cdot current$$
+     * @param {number} init $$w_2 : D_0(3) = w_2 + (R-2) \cdot w_3= w_2$$
+     * @param {number} current $$D - w_6 \cdot (R - 2)$$
+     * @return {number} difficulty
+     */
+    mean_reversion(init, current) {
+        return this.param.w[7] * init + (1 - this.param.w[7]) * current;
+    }
+    /**
+     * The formula used is :
+     * $$S^\prime_r(D,S,R,G) = S\cdot(e^{w_8}\cdot (11-D)\cdot S^{-w_9}\cdot(e^{w_10\cdot(1-R)}-1)\cdot w_15(if G=2) \cdot w_16(if G=4)+1)$$
+     * @param {number} d Difficulty D \in [1,10]
+     * @param {number} s Stability (interval when R=90%)
+     * @param {number} r Retrievability (probability of recall)
+     * @param {Rating} g Grade (Rating[0.again,1.hard,2.good,3.easy])
+     * @return {number} S^\prime_r new stability after recall
+     */
+    next_recall_stability(d, s, r, g) {
+        const hard_penalty = models_1.Rating.Hard === g ? this.param.w[15] : 1;
+        const easy_bound = models_1.Rating.Easy === g ? this.param.w[16] : 1;
+        return (s *
+            (1 +
+                Math.exp(this.param.w[8]) *
+                    (11 - d) *
+                    Math.pow(s, -this.param.w[9]) *
+                    (Math.exp((1 - r) * this.param.w[10]) - 1) *
+                    hard_penalty *
+                    easy_bound));
+    }
+    /**
+     * The formula used is :
+     * $$S^\prime_f(D,S,R) = w_11\cdot D^{-w_{12}}\cdot ((S+1)^{w_{13}}-1) \cdot e^{w_{14}\cdot(1-R)}.$$
+     * @param {number} d Difficulty D \in [1,10]
+     * @param {number} s Stability (interval when R=90%)
+     * @param {number} r Retrievability (probability of recall)
+     * @return {number} S^\prime_f new stability after forgetting
+     */
+    next_forget_stability(d, s, r) {
+        return (this.param.w[11] *
+            Math.pow(d, -this.param.w[12]) *
+            (Math.pow(s + 1, this.param.w[13]) - 1) *
+            Math.exp((1 - r) * this.param.w[14]));
+    }
+    /**
+     * The formula used is :
+     * $$R(t,S) = (1 + \frac{t}{9 \cdot S})^{-1},$$
+     * @param {number} t t days since the last review
+     * @param {number} s Stability (interval when R=90%)
+     * @return {number} r Retrievability (probability of recall)
+     */
+    current_retrievability(t, s) {
+        return Math.pow(1 + t / (9 * s), -1);
+    }
+}
+exports.FSRSAlgorithm = FSRSAlgorithm;

package/dist/default.d.ts

@@ -6,11 +6,6 @@ export declare const default_maximum_interval: number;
 export declare const default_w: number[];
 export declare const default_enable_fuzz: boolean;
 export declare const FSRSVersion: string;
-export declare const generatorParameters: (props?: Partial<FSRSParameters>) => {
-    request_retention: number;
-    maximum_interval: number;
-    w: number[];
-    enable_fuzz: boolean;
-};
+export declare const generatorParameters: (props?: Partial<FSRSParameters>) => FSRSParameters;
 export declare const createEmptyCard: (now?: Date) => Card;
 export declare const fsrs: (params?: Partial<FSRSParameters>) => FSRS;

package/dist/default.js

@@ -29,7 +29,7 @@ exports.default_w = exports.envParams.FSRS_W || [
     0.34, 1.26, 0.29, 2.61,
 ];
 exports.default_enable_fuzz = exports.envParams.FSRS_ENABLE_FUZZ || false;
-exports.FSRSVersion = "3.0.3";
+exports.FSRSVersion = "3.0.5";
 const generatorParameters = (props) => {
     return {
         request_retention: props?.request_retention || exports.default_request_retention,

package/dist/fsrs.d.ts

@@ -1,138 +1,11 @@
-import { SchedulingCard } from "./index";
-import { FSRSParameters, Card, State, Rating, CardInput, DateInput } from "./models";
-import type { int } from "./type";
-export declare class FSRS {
-    private param;
-    private readonly intervalModifier;
-    private seed?;
+import { FSRSParameters, Card, CardInput, DateInput, RecordLog } from "./models";
+import { FSRSAlgorithm } from "./algorithm";
+export declare class FSRS extends FSRSAlgorithm {
     constructor(param: Partial<FSRSParameters>);
     preProcess(_card: CardInput, _now: DateInput): {
         card: Card;
         now: Date;
     };
-    repeat: (card: CardInput, now: DateInput) => {
-        1: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-        2: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-        3: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-        4: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-    };
+    repeat: (card: CardInput, now: DateInput) => RecordLog;
     get_retrievability: (card: Card, now: Date) => undefined | string;
-    init_ds(s: SchedulingCard): void;
-    /**
-     *
-     * @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;
-    /**
-     * The formula used is :
-     * $$S_0(G) = w_{G-1}$$
-     * $$\max \{S_0,0.1\}$$
-     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
-     * @return Stability (interval when R=90%)
-     */
-    init_stability(g: number): number;
-    /**
-     * The formula used is :
-     * $$D_0(G) = w_4 - (G-3) \cdot w_5$$
-     * $$\min \{\max \{D_0(G),1\},10\}$$
-     * where the D_0(3)=w_4 when the first rating is good.
-     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
-     * @return Difficulty D \in [1,10]
-     */
-    init_difficulty(g: number): number;
-    apply_fuzz(ivl: number): number;
-    /**
-     *  Ref:
-     *   constructor(param: Partial<FSRSParameters>)
-     *   this.intervalModifier = 9 * (1 / this.param.request_retention - 1);
-     */
-    next_interval(s: number): int;
-    /**
-     * The formula used is :
-     * $$next_d = D - w_6 \cdot (R - 2)$$
-     * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
-     * @param d
-     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
-     * @return next_D
-     */
-    next_difficulty(d: number, g: number): number;
-    /**
-     * The formula used is :
-     * $$\min \{\max \{D_0,1\},10\}$$
-     */
-    constrain_difficulty(difficulty: number): number;
-    /**
-     * The formula used is :
-     * $$w_7 \cdot init +(1 - w_7) \cdot current$$
-     * @param init $$w_2 : D_0(3) = w_2 + (R-2) \cdot w_3= w_2$$
-     * @param current $$D - w_6 \cdot (R - 2)$$
-     * @return difficulty
-     */
-    mean_reversion(init: number, current: number): number;
-    /**
-     * The formula used is :
-     * $$S^\prime_r(D,S,R,G) = S\cdot(e^{w_8}\cdot (11-D)\cdot S^{-w_9}\cdot(e^{w_10\cdot(1-R)}-1)\cdot w_15(if G=2) \cdot w_16(if G=4)+1)$$
-     * @param d Difficulty D \in [1,10]
-     * @param s Stability (interval when R=90%)
-     * @param r Retrievability (probability of recall)
-     * @param g Grade (Rating[0.again,1.hard,2.good,3.easy])
-     * @return S^\prime_r new stability after recall
-     */
-    next_recall_stability(d: number, s: number, r: number, g: Rating): number;
-    /**
-     * The formula used is :
-     * $$S^\prime_f(D,S,R) = w_11\cdot D^{-w_{12}}\cdot ((S+1)^{w_{13}}-1) \cdot e^{w_{14}\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) = (1 + \frac{t}{9 \cdot S})^{-1},$$
-     * @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/dist/fsrs.js

@@ -1,23 +1,13 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FSRS = void 0;
-const seedrandom_1 = __importDefault(require("seedrandom"));
 const index_1 = require("./index");
 const help_1 = require("./help");
 const models_1 = require("./models");
-// Ref: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm#fsrs-v4
-class FSRS {
-    param;
-    intervalModifier;
-    seed;
+const algorithm_1 = require("./algorithm");
+class FSRS extends algorithm_1.FSRSAlgorithm {
     constructor(param) {
-        this.param = (0, index_1.generatorParameters)(param);
-        // Ref: https://github.com/open-spaced-repetition/py-fsrs/blob/ecd68e453611eb808c7367c7a5312d7cadeedf5c/src/fsrs/fsrs.py#L79
-        // The formula used is : I(r,s)=9 \cdot  s \cdot (\frac{1}{r}-1)
-        this.intervalModifier = 9 * (1 / this.param.request_retention - 1);
+        super(param);
     }
     preProcess(_card, _now) {
         const card = {
@@ -37,8 +27,7 @@ class FSRS {
             card.state === models_1.State.New ? 0 : now.diff(card.last_review, "days"); //相距时间
         card.last_review = now; // 上次复习时间
         card.reps += 1;
-        const s = new index_1.SchedulingCard(card);
-        s.update_state(card.state);
+        const s = new index_1.SchedulingCard(card).update_state(card.state);
         this.seed = String(card.last_review.getTime()) + String(card.elapsed_days);
         let easy_interval, good_interval, hard_interval;
         switch (card.state) {
@@ -85,146 +74,5 @@ class FSRS {
         const t = Math.max(now.diff(card.last_review, "days"), 0);
         return ((this.current_retrievability(t, card.stability) * 100).toFixed(2) + "%");
     };
-    init_ds(s) {
-        s.again.difficulty = this.init_difficulty(models_1.Rating.Again);
-        s.again.stability = this.init_stability(models_1.Rating.Again);
-        s.hard.difficulty = this.init_difficulty(models_1.Rating.Hard);
-        s.hard.stability = this.init_stability(models_1.Rating.Hard);
-        s.good.difficulty = this.init_difficulty(models_1.Rating.Good);
-        s.good.stability = this.init_stability(models_1.Rating.Good);
-        s.easy.difficulty = this.init_difficulty(models_1.Rating.Easy);
-        s.easy.stability = this.init_stability(models_1.Rating.Easy);
-    }
-    /**
-     *
-     * @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, models_1.Rating.Again);
-        s.again.stability = this.next_forget_stability(s.again.difficulty, last_s, retrievability);
-        s.hard.difficulty = this.next_difficulty(last_d, models_1.Rating.Hard);
-        s.hard.stability = this.next_recall_stability(s.hard.difficulty, last_s, retrievability, models_1.Rating.Hard);
-        s.good.difficulty = this.next_difficulty(last_d, models_1.Rating.Good);
-        s.good.stability = this.next_recall_stability(s.good.difficulty, last_s, retrievability, models_1.Rating.Good);
-        s.easy.difficulty = this.next_difficulty(last_d, models_1.Rating.Easy);
-        s.easy.stability = this.next_recall_stability(s.easy.difficulty, last_s, retrievability, models_1.Rating.Easy);
-    }
-    /**
-     * The formula used is :
-     * $$S_0(G) = w_{G-1}$$
-     * $$\max \{S_0,0.1\}$$
-     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
-     * @return Stability (interval when R=90%)
-     */
-    init_stability(g) {
-        return Math.max(this.param.w[g - 1], 0.1);
-    }
-    /**
-     * The formula used is :
-     * $$D_0(G) = w_4 - (G-3) \cdot w_5$$
-     * $$\min \{\max \{D_0(G),1\},10\}$$
-     * where the D_0(3)=w_4 when the first rating is good.
-     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
-     * @return Difficulty D \in [1,10]
-     */
-    init_difficulty(g) {
-        return Math.min(Math.max(this.param.w[4] - (g - 3) * this.param.w[5], 1), 10);
-    }
-    apply_fuzz(ivl) {
-        if (!this.param.enable_fuzz || ivl < 2.5)
-            return ivl;
-        const generator = (0, seedrandom_1.default)(this.seed);
-        const fuzz_factor = generator();
-        ivl = Math.round(ivl);
-        const min_ivl = Math.max(2, Math.round(ivl * 0.95 - 1));
-        const max_ivl = Math.round(ivl * 1.05 + 1);
-        return Math.floor(fuzz_factor * (max_ivl - min_ivl + 1) + min_ivl);
-    }
-    /**
-     *  Ref:
-     *   constructor(param: Partial<FSRSParameters>)
-     *   this.intervalModifier = 9 * (1 / this.param.request_retention - 1);
-     */
-    next_interval(s) {
-        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_6 \cdot (R - 2)$$
-     * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
-     * @param d
-     * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
-     * @return next_D
-     */
-    next_difficulty(d, g) {
-        const next_d = d - this.param.w[6] * (g - 3);
-        return this.constrain_difficulty(this.mean_reversion(this.param.w[4], 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_7 \cdot init +(1 - w_7) \cdot current$$
-     * @param init $$w_2 : D_0(3) = w_2 + (R-2) \cdot w_3= w_2$$
-     * @param current $$D - w_6 \cdot (R - 2)$$
-     * @return difficulty
-     */
-    mean_reversion(init, current) {
-        return this.param.w[7] * init + (1 - this.param.w[7]) * current;
-    }
-    /**
-     * The formula used is :
-     * $$S^\prime_r(D,S,R,G) = S\cdot(e^{w_8}\cdot (11-D)\cdot S^{-w_9}\cdot(e^{w_10\cdot(1-R)}-1)\cdot w_15(if G=2) \cdot w_16(if G=4)+1)$$
-     * @param d Difficulty D \in [1,10]
-     * @param s Stability (interval when R=90%)
-     * @param r Retrievability (probability of recall)
-     * @param g Grade (Rating[0.again,1.hard,2.good,3.easy])
-     * @return S^\prime_r new stability after recall
-     */
-    next_recall_stability(d, s, r, g) {
-        const hard_penalty = models_1.Rating.Hard === g ? this.param.w[15] : 1;
-        const easy_bound = models_1.Rating.Easy === g ? this.param.w[16] : 1;
-        return (s *
-            (1 +
-                Math.exp(this.param.w[8]) *
-                    (11 - d) *
-                    Math.pow(s, -this.param.w[9]) *
-                    (Math.exp((1 - r) * this.param.w[10]) - 1) *
-                    hard_penalty *
-                    easy_bound));
-    }
-    /**
-     * The formula used is :
-     * $$S^\prime_f(D,S,R) = w_11\cdot D^{-w_{12}}\cdot ((S+1)^{w_{13}}-1) \cdot e^{w_{14}\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[11] *
-            Math.pow(d, -this.param.w[12]) *
-            (Math.pow(s + 1, this.param.w[13]) - 1) *
-            Math.exp((1 - r) * this.param.w[14]));
-    }
-    /**
-     * The formula used is :
-     * $$R(t,S) = (1 + \frac{t}{9 \cdot S})^{-1},$$
-     * @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.pow(1 + t / (9 * s), -1);
-    }
 }
 exports.FSRS = FSRS;

package/dist/help.d.ts

@@ -8,6 +8,13 @@ declare global {
         dueFormat(last_review: Date, unit?: boolean): string;
     }
 }
+/**
+ * 计算日期和时间的偏移，并返回一个新的日期对象。
+ * @param now 当前日期和时间
+ * @param t 时间偏移量，当 isDay 为 true 时表示天数，为 false 时表示分钟
+ * @param isDay （可选）是否按天数单位进行偏移，默认为 false，表示按分钟单位计算偏移
+ * @returns 偏移后的日期和时间对象
+ */
 export declare function date_scheduler(now: Date, t: number, isDay?: boolean): Date;
 export declare function date_diff(now: Date, pre: Date, unit: unit): number;
 export declare function formatDate(date: Date): string;

package/dist/help.js

@@ -19,6 +19,13 @@ Date.prototype.format = function () {
 Date.prototype.dueFormat = function (last_review, unit) {
     return show_diff_message(this, last_review, unit);
 };
+/**
+ * 计算日期和时间的偏移，并返回一个新的日期对象。
+ * @param now 当前日期和时间
+ * @param t 时间偏移量，当 isDay 为 true 时表示天数，为 false 时表示分钟
+ * @param isDay （可选）是否按天数单位进行偏移，默认为 false，表示按分钟单位计算偏移
+ * @returns 偏移后的日期和时间对象
+ */
 function date_scheduler(now, t, isDay) {
     return new Date(isDay
         ? now.getTime() + t * 24 * 60 * 60 * 1000

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { SchedulingCard } from "./scheduler";
 export { default_request_retention, default_maximum_interval, default_w, default_enable_fuzz, FSRSVersion, generatorParameters, createEmptyCard, fsrs, envParams } from "./default";
 export { date_scheduler, date_diff, formatDate, show_diff_message, } from "./help";
 export type { int, double } from "./type";
-export type { FSRSParameters, Card, ReviewLog, StateType, RatingType, CardInput, DateInput } from "./models";
+export type { FSRSParameters, Card, ReviewLog, RecordLog, RecordLogItem, StateType, RatingType, CardInput, DateInput } from "./models";
 export { State, Rating } from "./models";
 export { FSRS } from "./fsrs";

package/dist/models.d.ts

@@ -19,6 +19,13 @@ export interface ReviewLog {
     scheduled_days: number;
     review: Date;
 }
+export type RecordLogItem = {
+    card: Card;
+    log: ReviewLog;
+};
+export type RecordLog = {
+    [key in Rating]: RecordLogItem;
+};
 export interface Card {
     due: Date;
     stability: number;

package/dist/scheduler.d.ts

@@ -1,4 +1,4 @@
-import { Card, Rating, State } from "./models";
+import { Card, RecordLog, State } from "./models";
 export declare class SchedulingCard {
     again: Card;
     hard: Card;
@@ -8,46 +8,5 @@ export declare class SchedulingCard {
     constructor(card: Card);
     update_state(state: State): this;
     schedule(now: Date, hard_interval: number, good_interval: number, easy_interval: number): SchedulingCard;
-    record_log(card: Card, now: Date): {
-        1: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-        2: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-        3: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-        4: {
-            card: Card;
-            log: {
-                rating: Rating;
-                state: State;
-                elapsed_days: number;
-                scheduled_days: number;
-                review: Date;
-            };
-        };
-    };
+    record_log(card: Card, now: Date): RecordLog;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-fsrs",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "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": "dist/index.js",
   "types": "dist/index.d.ts",