ts-fsrs 5.2.2 → 5.3.0

package/dist/index.d.ts

@@ -325,9 +325,10 @@ declare class FSRSAlgorithm {
      * @param memory_state - The current state of memory, which can be null.
      * @param t - The time elapsed since the last review.
      * @param {Rating} g Grade (Rating[0.Manual,1.Again,2.Hard,3.Good,4.Easy])
+     * @param r - Optional retrievability value. If not provided, it will be calculated.
      * @returns The next state of memory with updated difficulty and stability.
      */
-    next_state(memory_state: FSRSState | null, t: number, g: number): FSRSState;
+    next_state(memory_state: FSRSState | null, t: number, g: number, r?: number): FSRSState;
 }
 
 declare enum StrategyMode {
@@ -560,6 +561,7 @@ declare function get_fuzz_range(interval: number, elapsed_days: number, maximum_
     max_ivl: number;
 };
 declare function clamp(value: number, min: number, max: number): number;
+declare function roundTo(num: number, decimals: number): number;
 declare function dateDiffInDays(last: Date, cur: Date): number;
 
 declare const ConvertStepUnitToMinutes: (step: StepUnit) => number;
@@ -587,5 +589,5 @@ declare function DefaultInitSeedStrategy(this: AbstractScheduler): string;
  */
 declare function GenSeedStrategyWithCardId(card_id_field: string | number): TSeedStrategy;
 
-export { AbstractScheduler, BasicLearningStepsStrategy, CLAMP_PARAMETERS, ConvertStepUnitToMinutes, DefaultInitSeedStrategy, FSRS, FSRS5_DEFAULT_DECAY, FSRS6_DEFAULT_DECAY, FSRSAlgorithm, FSRSVersion, GenSeedStrategyWithCardId, Grades, INIT_S_MAX, Rating, S_MAX, S_MIN, State, StrategyMode, TypeConvert, W17_W18_Ceiling, checkParameters, clamp, clipParameters, computeDecayFactor, createEmptyCard, dateDiffInDays, date_diff, date_scheduler, default_enable_fuzz, default_enable_short_term, default_learning_steps, default_maximum_interval, default_relearning_steps, default_request_retention, default_w, fixDate, fixRating, fixState, forgetting_curve, formatDate, fsrs, generatorParameters, get_fuzz_range, migrateParameters, show_diff_message };
+export { AbstractScheduler, BasicLearningStepsStrategy, CLAMP_PARAMETERS, ConvertStepUnitToMinutes, DefaultInitSeedStrategy, FSRS, FSRS5_DEFAULT_DECAY, FSRS6_DEFAULT_DECAY, FSRSAlgorithm, FSRSVersion, GenSeedStrategyWithCardId, Grades, INIT_S_MAX, Rating, S_MAX, S_MIN, State, StrategyMode, TypeConvert, W17_W18_Ceiling, checkParameters, clamp, clipParameters, computeDecayFactor, createEmptyCard, dateDiffInDays, date_diff, date_scheduler, default_enable_fuzz, default_enable_short_term, default_learning_steps, default_maximum_interval, default_relearning_steps, default_request_retention, default_w, fixDate, fixRating, fixState, forgetting_curve, formatDate, fsrs, generatorParameters, get_fuzz_range, migrateParameters, roundTo, show_diff_message };
 export type { Card, CardInput, DateInput, FSRSHistory, FSRSParameters, FSRSReview, FSRSState, Grade, GradeType, IFSRS, IPreview, IReschedule, IScheduler, RatingType, RecordLog, RecordLogItem, RescheduleOptions, ReviewLog, ReviewLogInput, StateType, StepUnit, Steps, TLearningStepsStrategy, TSchedulerStrategy, TSeedStrategy, TStrategyHandler, TimeUnit, double, int, unit };

package/dist/index.mjs

@@ -52,8 +52,12 @@ class TypeConvert {
     throw new Error(`Invalid state:[${value}]`);
   }
   static time(value) {
-    if (typeof value === "object" && value instanceof Date) {
+    if (value instanceof Date) {
       return value;
+    }
+    const date = new Date(value);
+    if (typeof value === "object" && value !== null && !Number.isNaN(Date.parse(value) || +date)) {
+      return date;
     } else if (typeof value === "string") {
       const timestamp = Date.parse(value);
       if (!Number.isNaN(timestamp)) {
@@ -77,15 +81,19 @@ class TypeConvert {
   }
 }
 
+/* istanbul ignore next -- @preserve */
 Date.prototype.scheduler = function(t, isDay) {
   return date_scheduler(this, t, isDay);
 };
+/* istanbul ignore next -- @preserve */
 Date.prototype.diff = function(pre, unit) {
   return date_diff(this, pre, unit);
 };
+/* istanbul ignore next -- @preserve */
 Date.prototype.format = function() {
   return formatDate(this);
 };
+/* istanbul ignore next -- @preserve */
 Date.prototype.dueFormat = function(last_review, unit, timeUnit) {
   return show_diff_message(this, last_review, unit, timeUnit);
 };
@@ -145,12 +153,15 @@ function show_diff_message(due, last_review, unit, timeUnit = TIMEUNITFORMAT) {
   }
   return `${Math.floor(diff)}${unit ? timeUnit[i] : ""}`;
 }
+/* istanbul ignore next -- @preserve */
 function fixDate(value) {
   return TypeConvert.time(value);
 }
+/* istanbul ignore next -- @preserve */
 function fixState(value) {
   return TypeConvert.state(value);
 }
+/* istanbul ignore next -- @preserve */
 function fixRating(value) {
   return TypeConvert.rating(value);
 }
@@ -194,6 +205,10 @@ function get_fuzz_range(interval, elapsed_days, maximum_interval) {
 function clamp(value, min, max) {
   return Math.min(Math.max(value, min), max);
 }
+function roundTo(num, decimals) {
+  const factor = 10 ** decimals;
+  return Math.round(num * factor) / factor;
+}
 function dateDiffInDays(last, cur) {
   const utc1 = Date.UTC(
     last.getUTCFullYear(),
@@ -466,7 +481,7 @@ function alea(seed) {
   return prng;
 }
 
-const version="5.2.2";
+const version="5.3.0";
 
 const default_request_retention = 0.9;
 const default_maximum_interval = 36500;
@@ -640,11 +655,11 @@ function createEmptyCard(now, afterHandler) {
 const computeDecayFactor = (decayOrParams) => {
   const decay = typeof decayOrParams === "number" ? -decayOrParams : -decayOrParams[20];
   const factor = Math.exp(Math.pow(decay, -1) * Math.log(0.9)) - 1;
-  return { decay, factor: +factor.toFixed(8) };
+  return { decay, factor: roundTo(factor, 8) };
 };
 function forgetting_curve(decayOrParams, elapsed_days, stability) {
   const { decay, factor } = computeDecayFactor(decayOrParams);
-  return +Math.pow(1 + factor * elapsed_days / stability, decay).toFixed(8);
+  return roundTo(Math.pow(1 + factor * elapsed_days / stability, decay), 8);
 }
 class FSRSAlgorithm {
   param;
@@ -678,7 +693,7 @@ class FSRSAlgorithm {
       throw new Error("Requested retention rate should be in the range (0,1]");
     }
     const { decay, factor } = computeDecayFactor(this.param.w);
-    return +((Math.pow(request_retention, 1 / decay) - 1) / factor).toFixed(8);
+    return roundTo((Math.pow(request_retention, 1 / decay) - 1) / factor, 8);
   }
   /**
    * Get the parameters of the algorithm.
@@ -745,8 +760,9 @@ class FSRSAlgorithm {
    * @return {number} Difficulty $$D \in [1,10]$$
    */
   init_difficulty(g) {
-    const d = this.param.w[4] - Math.exp((g - 1) * this.param.w[5]) + 1;
-    return +d.toFixed(8);
+    const w = this.param.w;
+    const d = w[4] - Math.exp((g - 1) * w[5]) + 1;
+    return roundTo(d, 8);
   }
   /**
    * If fuzzing is disabled or ivl is less than 2.5, it returns the original interval.
@@ -781,7 +797,7 @@ class FSRSAlgorithm {
    * @see https://github.com/open-spaced-repetition/fsrs4anki/issues/697
    */
   linear_damping(delta_d, old_d) {
-    return +(delta_d * (10 - old_d) / 9).toFixed(8);
+    return roundTo(delta_d * (10 - old_d) / 9, 8);
   }
   /**
    * The formula used is :
@@ -809,9 +825,8 @@ class FSRSAlgorithm {
    * @return {number} difficulty
    */
   mean_reversion(init, current) {
-    return +(this.param.w[7] * init + (1 - this.param.w[7]) * current).toFixed(
-      8
-    );
+    const w = this.param.w;
+    return roundTo(w[7] * init + (1 - w[7]) * current, 8);
   }
   /**
    * The formula used is :
@@ -823,13 +838,17 @@ class FSRSAlgorithm {
    * @return {number} S^\prime_r new stability after recall
    */
   next_recall_stability(d, s, r, g) {
-    const hard_penalty = Rating.Hard === g ? this.param.w[15] : 1;
-    const easy_bound = Rating.Easy === g ? this.param.w[16] : 1;
-    return +clamp(
-      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),
-      S_MIN,
-      36500
-    ).toFixed(8);
+    const w = this.param.w;
+    const hard_penalty = Rating.Hard === g ? w[15] : 1;
+    const easy_bound = Rating.Easy === g ? w[16] : 1;
+    return roundTo(
+      clamp(
+        s * (1 + Math.exp(w[8]) * (11 - d) * Math.pow(s, -w[9]) * (Math.exp((1 - r) * w[10]) - 1) * hard_penalty * easy_bound),
+        S_MIN,
+        36500
+      ),
+      8
+    );
   }
   /**
    * The formula used is :
@@ -842,11 +861,15 @@ class FSRSAlgorithm {
    * @return {number} S^\prime_f new stability after forgetting
    */
   next_forget_stability(d, s, r) {
-    return +clamp(
-      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]),
-      S_MIN,
-      36500
-    ).toFixed(8);
+    const w = this.param.w;
+    return roundTo(
+      clamp(
+        w[11] * Math.pow(d, -w[12]) * (Math.pow(s + 1, w[13]) - 1) * Math.exp((1 - r) * w[14]),
+        S_MIN,
+        36500
+      ),
+      8
+    );
   }
   /**
    * The formula used is :
@@ -855,9 +878,10 @@ class FSRSAlgorithm {
    * @param {Grade} g Grade (Rating[0.again,1.hard,2.good,3.easy])
    */
   next_short_term_stability(s, g) {
-    const sinc = Math.pow(s, -this.param.w[19]) * Math.exp(this.param.w[17] * (g - 3 + this.param.w[18]));
-    const maskedSinc = g >= 3 ? Math.max(sinc, 1) : sinc;
-    return +clamp(s * maskedSinc, S_MIN, 36500).toFixed(8);
+    const w = this.param.w;
+    const sinc = Math.pow(s, -w[19]) * Math.exp(w[17] * (g - 3 + w[18]));
+    const maskedSinc = g >= Rating.Hard ? Math.max(sinc, 1) : sinc;
+    return roundTo(clamp(s * maskedSinc, S_MIN, 36500), 8);
   }
   /**
    * The formula used is :
@@ -873,9 +897,10 @@ class FSRSAlgorithm {
    * @param memory_state - The current state of memory, which can be null.
    * @param t - The time elapsed since the last review.
    * @param {Rating} g Grade (Rating[0.Manual,1.Again,2.Hard,3.Good,4.Easy])
+   * @param r - Optional retrievability value. If not provided, it will be calculated.
    * @returns The next state of memory with updated difficulty and stability.
    */
-  next_state(memory_state, t, g) {
+  next_state(memory_state, t, g, r) {
     const { difficulty: d, stability: s } = memory_state ?? {
       difficulty: 0,
       stability: 0
@@ -903,22 +928,22 @@ class FSRSAlgorithm {
         `Invalid memory state { difficulty: ${d}, stability: ${s} }`
       );
     }
-    const r = this.forgetting_curve(t, s);
-    const s_after_success = this.next_recall_stability(d, s, r, g);
-    const s_after_fail = this.next_forget_stability(d, s, r);
-    const s_after_short_term = this.next_short_term_stability(s, g);
-    let new_s = s_after_success;
-    if (g === 1) {
+    const w = this.param.w;
+    r = typeof r === "number" ? r : this.forgetting_curve(t, s);
+    let new_s;
+    if (t === 0 && this.param.enable_short_term) {
+      new_s = this.next_short_term_stability(s, g);
+    } else if (g === 1) {
+      const s_after_fail = this.next_forget_stability(d, s, r);
       let [w_17, w_18] = [0, 0];
       if (this.param.enable_short_term) {
-        w_17 = this.param.w[17];
-        w_18 = this.param.w[18];
+        w_17 = w[17];
+        w_18 = w[18];
       }
       const next_s_min = s / Math.exp(w_17 * w_18);
-      new_s = clamp(+next_s_min.toFixed(8), S_MIN, s_after_fail);
-    }
-    if (t === 0 && this.param.enable_short_term) {
-      new_s = s_after_short_term;
+      new_s = clamp(roundTo(next_s_min, 8), S_MIN, s_after_fail);
+    } else {
+      new_s = this.next_recall_stability(d, s, r, g);
     }
     const new_d = this.next_difficulty(d, g);
     return { difficulty: new_d, stability: new_s };
@@ -1003,9 +1028,7 @@ class BasicScheduler extends AbstractScheduler {
     if (exist) {
       return exist;
     }
-    const next = TypeConvert.card(this.current);
-    next.difficulty = clamp(this.algorithm.init_difficulty(grade), 1, 10);
-    next.stability = this.algorithm.init_stability(grade);
+    const next = this.next_ds(this.elapsed_days, grade);
     this.applyLearningSteps(next, grade, State.Learning);
     const item = {
       card: next,
@@ -1019,14 +1042,11 @@ class BasicScheduler extends AbstractScheduler {
     if (exist) {
       return exist;
     }
-    const { state, difficulty, stability } = this.last;
-    const next = TypeConvert.card(this.current);
-    next.difficulty = this.algorithm.next_difficulty(difficulty, grade);
-    next.stability = this.algorithm.next_short_term_stability(stability, grade);
+    const next = this.next_ds(this.elapsed_days, grade);
     this.applyLearningSteps(
       next,
       grade,
-      state
+      this.last.state
       /** Learning or Relearning */
     );
     const item = {
@@ -1042,21 +1062,14 @@ class BasicScheduler extends AbstractScheduler {
       return exist;
     }
     const interval = this.elapsed_days;
-    const { difficulty, stability } = this.last;
-    const retrievability = this.algorithm.forgetting_curve(interval, stability);
-    const next_again = TypeConvert.card(this.current);
-    const next_hard = TypeConvert.card(this.current);
-    const next_good = TypeConvert.card(this.current);
-    const next_easy = TypeConvert.card(this.current);
-    this.next_ds(
-      next_again,
-      next_hard,
-      next_good,
-      next_easy,
-      difficulty,
-      stability,
-      retrievability
+    const retrievability = this.algorithm.forgetting_curve(
+      interval,
+      this.current.stability
     );
+    const next_again = this.next_ds(interval, Rating.Again, retrievability);
+    const next_hard = this.next_ds(interval, Rating.Hard, retrievability);
+    const next_good = this.next_ds(interval, Rating.Good, retrievability);
+    const next_easy = this.next_ds(interval, Rating.Easy, retrievability);
     this.next_interval(next_hard, next_good, next_easy, interval);
     this.next_state(next_hard, next_good, next_easy);
     this.applyLearningSteps(next_again, Rating.Again, State.Relearning);
@@ -1086,50 +1099,20 @@ class BasicScheduler extends AbstractScheduler {
   /**
    * Review next_ds
    */
-  next_ds(next_again, next_hard, next_good, next_easy, difficulty, stability, retrievability) {
-    next_again.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Again
-    );
-    const nextSMin = stability / Math.exp(
-      this.algorithm.parameters.w[17] * this.algorithm.parameters.w[18]
-    );
-    const s_after_fail = this.algorithm.next_forget_stability(
-      difficulty,
-      stability,
-      retrievability
-    );
-    next_again.stability = clamp(+nextSMin.toFixed(8), S_MIN, s_after_fail);
-    next_hard.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Hard
-    );
-    next_hard.stability = this.algorithm.next_recall_stability(
-      difficulty,
-      stability,
-      retrievability,
-      Rating.Hard
-    );
-    next_good.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Good
-    );
-    next_good.stability = this.algorithm.next_recall_stability(
-      difficulty,
-      stability,
-      retrievability,
-      Rating.Good
-    );
-    next_easy.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Easy
-    );
-    next_easy.stability = this.algorithm.next_recall_stability(
-      difficulty,
-      stability,
-      retrievability,
-      Rating.Easy
+  next_ds(t, g, r) {
+    const next_state = this.algorithm.next_state(
+      {
+        difficulty: this.current.difficulty,
+        stability: this.current.stability
+      },
+      t,
+      g,
+      r
     );
+    const card = TypeConvert.card(this.current);
+    card.difficulty = next_state.difficulty;
+    card.stability = next_state.stability;
+    return card;
   }
   /**
    * Review next_interval
@@ -1172,12 +1155,11 @@ class LongTermScheduler extends AbstractScheduler {
     }
     this.current.scheduled_days = 0;
     this.current.elapsed_days = 0;
-    const next_again = TypeConvert.card(this.current);
-    const next_hard = TypeConvert.card(this.current);
-    const next_good = TypeConvert.card(this.current);
-    const next_easy = TypeConvert.card(this.current);
-    this.init_ds(next_again, next_hard, next_good, next_easy);
     const first_interval = 0;
+    const next_again = this.next_ds(first_interval, Rating.Again);
+    const next_hard = this.next_ds(first_interval, Rating.Hard);
+    const next_good = this.next_ds(first_interval, Rating.Good);
+    const next_easy = this.next_ds(first_interval, Rating.Easy);
     this.next_interval(
       next_again,
       next_hard,
@@ -1189,31 +1171,20 @@ class LongTermScheduler extends AbstractScheduler {
     this.update_next(next_again, next_hard, next_good, next_easy);
     return this.next.get(grade);
   }
-  init_ds(next_again, next_hard, next_good, next_easy) {
-    next_again.difficulty = clamp(
-      this.algorithm.init_difficulty(Rating.Again),
-      1,
-      10
-    );
-    next_again.stability = this.algorithm.init_stability(Rating.Again);
-    next_hard.difficulty = clamp(
-      this.algorithm.init_difficulty(Rating.Hard),
-      1,
-      10
-    );
-    next_hard.stability = this.algorithm.init_stability(Rating.Hard);
-    next_good.difficulty = clamp(
-      this.algorithm.init_difficulty(Rating.Good),
-      1,
-      10
-    );
-    next_good.stability = this.algorithm.init_stability(Rating.Good);
-    next_easy.difficulty = clamp(
-      this.algorithm.init_difficulty(Rating.Easy),
-      1,
-      10
+  next_ds(t, g, r) {
+    const next_state = this.algorithm.next_state(
+      {
+        difficulty: this.current.difficulty,
+        stability: this.current.stability
+      },
+      t,
+      g,
+      r
     );
-    next_easy.stability = this.algorithm.init_stability(Rating.Easy);
+    const card = TypeConvert.card(this.current);
+    card.difficulty = next_state.difficulty;
+    card.stability = next_state.stability;
+    return card;
   }
   /**
    * @see https://github.com/open-spaced-repetition/ts-fsrs/issues/98#issuecomment-2241923194
@@ -1227,72 +1198,20 @@ class LongTermScheduler extends AbstractScheduler {
       return exist;
     }
     const interval = this.elapsed_days;
-    const { difficulty, stability } = this.last;
-    const retrievability = this.algorithm.forgetting_curve(interval, stability);
-    const next_again = TypeConvert.card(this.current);
-    const next_hard = TypeConvert.card(this.current);
-    const next_good = TypeConvert.card(this.current);
-    const next_easy = TypeConvert.card(this.current);
-    this.next_ds(
-      next_again,
-      next_hard,
-      next_good,
-      next_easy,
-      difficulty,
-      stability,
-      retrievability
+    const retrievability = this.algorithm.forgetting_curve(
+      interval,
+      this.current.stability
     );
+    const next_again = this.next_ds(interval, Rating.Again, retrievability);
+    const next_hard = this.next_ds(interval, Rating.Hard, retrievability);
+    const next_good = this.next_ds(interval, Rating.Good, retrievability);
+    const next_easy = this.next_ds(interval, Rating.Easy, retrievability);
     this.next_interval(next_again, next_hard, next_good, next_easy, interval);
     this.next_state(next_again, next_hard, next_good, next_easy);
     next_again.lapses += 1;
     this.update_next(next_again, next_hard, next_good, next_easy);
     return this.next.get(grade);
   }
-  /**
-   * Review next_ds
-   */
-  next_ds(next_again, next_hard, next_good, next_easy, difficulty, stability, retrievability) {
-    next_again.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Again
-    );
-    const s_after_fail = this.algorithm.next_forget_stability(
-      difficulty,
-      stability,
-      retrievability
-    );
-    next_again.stability = clamp(stability, S_MIN, s_after_fail);
-    next_hard.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Hard
-    );
-    next_hard.stability = this.algorithm.next_recall_stability(
-      difficulty,
-      stability,
-      retrievability,
-      Rating.Hard
-    );
-    next_good.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Good
-    );
-    next_good.stability = this.algorithm.next_recall_stability(
-      difficulty,
-      stability,
-      retrievability,
-      Rating.Good
-    );
-    next_easy.difficulty = this.algorithm.next_difficulty(
-      difficulty,
-      Rating.Easy
-    );
-    next_easy.stability = this.algorithm.next_recall_stability(
-      difficulty,
-      stability,
-      retrievability,
-      Rating.Easy
-    );
-  }
   /**
    * Review/New next_interval
    */
@@ -1936,5 +1855,5 @@ const fsrs = (params) => {
   return new FSRS(params || {});
 };
 
-export { AbstractScheduler, BasicLearningStepsStrategy, CLAMP_PARAMETERS, ConvertStepUnitToMinutes, DefaultInitSeedStrategy, FSRS, FSRS5_DEFAULT_DECAY, FSRS6_DEFAULT_DECAY, FSRSAlgorithm, FSRSVersion, GenSeedStrategyWithCardId, Grades, INIT_S_MAX, Rating, S_MAX, S_MIN, State, StrategyMode, TypeConvert, W17_W18_Ceiling, checkParameters, clamp, clipParameters, computeDecayFactor, createEmptyCard, dateDiffInDays, date_diff, date_scheduler, default_enable_fuzz, default_enable_short_term, default_learning_steps, default_maximum_interval, default_relearning_steps, default_request_retention, default_w, fixDate, fixRating, fixState, forgetting_curve, formatDate, fsrs, generatorParameters, get_fuzz_range, migrateParameters, show_diff_message };
+export { AbstractScheduler, BasicLearningStepsStrategy, CLAMP_PARAMETERS, ConvertStepUnitToMinutes, DefaultInitSeedStrategy, FSRS, FSRS5_DEFAULT_DECAY, FSRS6_DEFAULT_DECAY, FSRSAlgorithm, FSRSVersion, GenSeedStrategyWithCardId, Grades, INIT_S_MAX, Rating, S_MAX, S_MIN, State, StrategyMode, TypeConvert, W17_W18_Ceiling, checkParameters, clamp, clipParameters, computeDecayFactor, createEmptyCard, dateDiffInDays, date_diff, date_scheduler, default_enable_fuzz, default_enable_short_term, default_learning_steps, default_maximum_interval, default_relearning_steps, default_request_retention, default_w, fixDate, fixRating, fixState, forgetting_curve, formatDate, fsrs, generatorParameters, get_fuzz_range, migrateParameters, roundTo, show_diff_message };
 //# sourceMappingURL=index.mjs.map