ts-fsrs 5.3.2 → 5.4.0

package/dist/index.cjs

@@ -1,5 +1,20 @@
 'use strict';
 
+class FSRSError extends Error {
+  constructor(message = "FSRS Error") {
+    super(message);
+    this.name = "FSRSError";
+    Error.captureStackTrace?.(this, FSRSError);
+  }
+}
+class FSRSValidationError extends FSRSError {
+  constructor(message) {
+    super(message);
+    this.name = "FSRSValidationError";
+    Error.captureStackTrace?.(this, FSRSValidationError);
+  }
+}
+
 var State = /* @__PURE__ */ ((State2) => {
   State2[State2["New"] = 0] = "New";
   State2[State2["Learning"] = 1] = "Learning";
@@ -31,13 +46,13 @@ class TypeConvert {
       const restOfString = value.slice(1).toLowerCase();
       const ret = Rating[`${firstLetter}${restOfString}`];
       if (ret === void 0) {
-        throw new Error(`Invalid rating:[${value}]`);
+        throw new FSRSValidationError(`Invalid rating:[${value}]`);
       }
       return ret;
     } else if (typeof value === "number") {
       return value;
     }
-    throw new Error(`Invalid rating:[${value}]`);
+    throw new FSRSValidationError(`Invalid rating:[${value}]`);
   }
   static state(value) {
     if (typeof value === "string") {
@@ -45,13 +60,13 @@ class TypeConvert {
       const restOfString = value.slice(1).toLowerCase();
       const ret = State[`${firstLetter}${restOfString}`];
       if (ret === void 0) {
-        throw new Error(`Invalid state:[${value}]`);
+        throw new FSRSValidationError(`Invalid state:[${value}]`);
       }
       return ret;
     } else if (typeof value === "number") {
       return value;
     }
-    throw new Error(`Invalid state:[${value}]`);
+    throw new FSRSValidationError(`Invalid state:[${value}]`);
   }
   static time(value) {
     if (value instanceof Date) {
@@ -65,12 +80,12 @@ class TypeConvert {
       if (!Number.isNaN(timestamp)) {
         return new Date(timestamp);
       } else {
-        throw new Error(`Invalid date:[${value}]`);
+        throw new FSRSValidationError(`Invalid date:[${value}]`);
       }
     } else if (typeof value === "number") {
       return new Date(value);
     }
-    throw new Error(`Invalid date:[${value}]`);
+    throw new FSRSValidationError(`Invalid date:[${value}]`);
   }
   static review_log(log) {
     return {
@@ -106,7 +121,7 @@ function date_scheduler(now, t, isDay) {
 }
 function date_diff(now, pre, unit) {
   if (!now || !pre) {
-    throw new Error("Invalid date");
+    throw new FSRSValidationError("Invalid date");
   }
   const diff = TypeConvert.time(now).getTime() - TypeConvert.time(pre).getTime();
   let r = 0;
@@ -232,7 +247,7 @@ const ConvertStepUnitToMinutes = (step) => {
   const unit = step.slice(-1);
   const value = parseInt(step.slice(0, -1), 10);
   if (Number.isNaN(value) || !Number.isFinite(value) || value < 0) {
-    throw new Error(`Invalid step value: ${step}`);
+    throw new FSRSValidationError(`Invalid step value: ${step}`);
   }
   switch (unit) {
     case "m":
@@ -242,7 +257,9 @@ const ConvertStepUnitToMinutes = (step) => {
     case "d":
       return value * 1440;
     default:
-      throw new Error(`Invalid step unit: ${step}, expected m/h/d`);
+      throw new FSRSValidationError(
+        `Invalid step unit: ${step}, expected m/h/d`
+      );
   }
 };
 const BasicLearningStepsStrategy = (params, state, cur_step) => {
@@ -339,8 +356,8 @@ class AbstractScheduler {
     this.init();
   }
   checkGrade(grade) {
-    if (!Number.isFinite(grade) || grade < 0 || grade > 4) {
-      throw new Error(`Invalid grade "${grade}",expected 1-4`);
+    if (!Number.isFinite(grade) || grade < 1 || grade > 4) {
+      throw new FSRSValidationError(`Invalid grade "${grade}",expected 1-4`);
     }
   }
   init() {
@@ -483,7 +500,7 @@ function alea(seed) {
   return prng;
 }
 
-const version="5.3.2";
+const version="5.4.0";
 
 const default_request_retention = 0.9;
 const default_maximum_interval = 36500;
@@ -554,27 +571,31 @@ const CLAMP_PARAMETERS = (w17_w18_ceiling, enable_short_term = default_enable_sh
 ];
 
 const clipParameters = (parameters, numRelearningSteps, enableShortTerm = default_enable_short_term) => {
-  let w17_w18_ceiling = W17_W18_Ceiling;
-  if (Math.max(0, numRelearningSteps) > 1) {
-    const value = -(Math.log(parameters[11]) + Math.log(Math.pow(2, parameters[13]) - 1) + parameters[14] * 0.3) / numRelearningSteps;
-    w17_w18_ceiling = clamp(+value.toFixed(8), 0.01, 2);
-  }
-  const clip = CLAMP_PARAMETERS(w17_w18_ceiling, enableShortTerm).slice(
+  const clip = CLAMP_PARAMETERS(W17_W18_Ceiling, enableShortTerm).slice(
     0,
     parameters.length
   );
+  if (Math.max(0, numRelearningSteps) > 1) {
+    const w11 = clamp(parameters[11] || 0, clip[11][0], clip[11][1]);
+    const w13 = clamp(parameters[13] || 0, clip[13][0], clip[13][1]);
+    const w14 = clamp(parameters[14] || 0, clip[14][0], clip[14][1]);
+    const value = -(Math.log(w11) + Math.log(Math.pow(2, w13) - 1) + w14 * 0.3) / numRelearningSteps;
+    const w17_w18_ceiling = clamp(roundTo(value, 8), 0.01, W17_W18_Ceiling);
+    if (clip[17]) clip[17] = [clip[17][0], w17_w18_ceiling];
+    if (clip[18]) clip[18] = [clip[18][0], w17_w18_ceiling];
+  }
   return clip.map(
     ([min, max], index) => clamp(parameters[index] || 0, min, max)
   );
 };
 const checkParameters = (parameters) => {
-  const invalid = parameters.find(
-    (param) => !Number.isFinite(param) && !Number.isNaN(param)
-  );
+  const invalid = parameters.find((param) => !Number.isFinite(param));
   if (invalid !== void 0) {
-    throw Error(`Non-finite or NaN value in parameters ${parameters}`);
+    throw new FSRSValidationError(
+      `Non-finite or NaN value in parameters ${parameters}`
+    );
   } else if (![17, 19, 21].includes(parameters.length)) {
-    throw Error(
+    throw new FSRSValidationError(
       `Invalid parameter length: ${parameters.length}. Must be 17, 19 or 21 for FSRSv4, 5 and 6 respectively.`
     );
   }
@@ -692,7 +713,9 @@ class FSRSAlgorithm {
    */
   calculate_interval_modifier(request_retention) {
     if (request_retention <= 0 || request_retention > 1) {
-      throw new Error("Requested retention rate should be in the range (0,1]");
+      throw new FSRSValidationError(
+        "Requested retention rate should be in the range (0,1]"
+      );
     }
     const { decay, factor } = computeDecayFactor(this.param.w);
     return roundTo((Math.pow(request_retention, 1 / decay) - 1) / factor, 8);
@@ -908,10 +931,10 @@ class FSRSAlgorithm {
       stability: 0
     };
     if (t < 0) {
-      throw new Error(`Invalid delta_t "${t}"`);
+      throw new FSRSValidationError(`Invalid delta_t "${t}"`);
     }
     if (g < 0 || g > 4) {
-      throw new Error(`Invalid grade "${g}"`);
+      throw new FSRSValidationError(`Invalid grade "${g}"`);
     }
     if (d === 0 && s === 0) {
       return {
@@ -926,7 +949,7 @@ class FSRSAlgorithm {
       };
     }
     if (d < 1 || s < S_MIN) {
-      throw new Error(
+      throw new FSRSValidationError(
         `Invalid memory state { difficulty: ${d}, stability: ${s} }`
       );
     }
@@ -1307,7 +1330,9 @@ class Reschedule {
    */
   handleManualRating(card, state, reviewed, elapsed_days, stability, difficulty, due) {
     if (typeof state === "undefined") {
-      throw new Error("reschedule: state is required for manual rating");
+      throw new FSRSValidationError(
+        "reschedule: state is required for manual rating"
+      );
     }
     let log;
     let next_card;
@@ -1328,7 +1353,9 @@ class Reschedule {
       next_card.last_review = reviewed;
     } else {
       if (typeof due === "undefined") {
-        throw new Error("reschedule: due is required for manual rating");
+        throw new FSRSValidationError(
+          "reschedule: due is required for manual rating"
+        );
       }
       const scheduled_days = date_diff(due, reviewed, "days");
       log = {
@@ -1418,6 +1445,9 @@ class Reschedule {
   }
 }
 
+function applyAfterHandler(value, afterHandler) {
+  return typeof afterHandler === "function" ? afterHandler(value) : value;
+}
 class FSRS extends FSRSAlgorithm {
   strategyHandler = /* @__PURE__ */ new Map();
   Scheduler;
@@ -1533,11 +1563,7 @@ class FSRS extends FSRSAlgorithm {
   repeat(card, now, afterHandler) {
     const instance = this.getScheduler(card, now);
     const recordLog = instance.preview();
-    if (afterHandler && typeof afterHandler === "function") {
-      return afterHandler(recordLog);
-    } else {
-      return recordLog;
-    }
+    return applyAfterHandler(recordLog, afterHandler);
   }
   /**
    * Display the collection of cards and logs for the card scheduled at the current time, after applying a specific grade rating.
@@ -1597,14 +1623,10 @@ class FSRS extends FSRSAlgorithm {
     const instance = this.getScheduler(card, now);
     const g = TypeConvert.rating(grade);
     if (g === Rating.Manual) {
-      throw new Error("Cannot review a manual rating");
+      throw new FSRSValidationError("Cannot review a manual rating");
     }
     const recordLogItem = instance.review(g);
-    if (afterHandler && typeof afterHandler === "function") {
-      return afterHandler(recordLogItem);
-    } else {
-      return recordLogItem;
-    }
+    return applyAfterHandler(recordLogItem, afterHandler);
   }
   /**
    * Get the retrievability of the card
@@ -1649,7 +1671,7 @@ class FSRS extends FSRSAlgorithm {
     const processedCard = TypeConvert.card(card);
     const processedLog = TypeConvert.review_log(log);
     if (processedLog.rating === Rating.Manual) {
-      throw new Error("Cannot rollback a manual rating");
+      throw new FSRSValidationError("Cannot rollback a manual rating");
     }
     let last_due;
     let last_review;
@@ -1681,11 +1703,7 @@ class FSRS extends FSRSAlgorithm {
       state: processedLog.state,
       last_review
     };
-    if (afterHandler && typeof afterHandler === "function") {
-      return afterHandler(prevCard);
-    } else {
-      return prevCard;
-    }
+    return applyAfterHandler(prevCard, afterHandler);
   }
   /**
    *
@@ -1768,11 +1786,7 @@ class FSRS extends FSRSAlgorithm {
       last_review: processedCard.last_review
     };
     const recordLogItem = { card: forget_card, log: forget_log };
-    if (afterHandler && typeof afterHandler === "function") {
-      return afterHandler(recordLogItem);
-    } else {
-      return recordLogItem;
-    }
+    return applyAfterHandler(recordLogItem, afterHandler);
   }
   /**
    * Reschedules the current card and returns the rescheduled collections and reschedule item.
@@ -1839,15 +1853,9 @@ class FSRS extends FSRSAlgorithm {
       len ? collections[len - 1] : void 0,
       updateMemoryState
     );
-    if (recordLogHandler && typeof recordLogHandler === "function") {
-      return {
-        collections: collections.map(recordLogHandler),
-        reschedule_item: manual_item ? recordLogHandler(manual_item) : null
-      };
-    }
     return {
-      collections,
-      reschedule_item: manual_item
+      collections: typeof recordLogHandler === "function" ? collections.map(recordLogHandler) : collections,
+      reschedule_item: manual_item ? applyAfterHandler(manual_item, recordLogHandler) : null
     };
   }
 }