ts-fsrs 5.3.2 → 5.4.0

package/dist/index.umd.js

@@ -4,6 +4,23 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.FSRS = {}));
 })(this, (function (exports) { 'use strict';
 
+  class FSRSError extends Error {
+    constructor(message = "FSRS Error") {
+      var _a;
+      super(message);
+      this.name = "FSRSError";
+      (_a = Error.captureStackTrace) == null ? void 0 : _a.call(Error, this, FSRSError);
+    }
+  }
+  class FSRSValidationError extends FSRSError {
+    constructor(message) {
+      var _a;
+      super(message);
+      this.name = "FSRSValidationError";
+      (_a = Error.captureStackTrace) == null ? void 0 : _a.call(Error, this, FSRSValidationError);
+    }
+  }
+
   var State = /* @__PURE__ */ ((State2) => {
     State2[State2["New"] = 0] = "New";
     State2[State2["Learning"] = 1] = "Learning";
@@ -53,13 +70,13 @@
         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") {
@@ -67,13 +84,13 @@
         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) {
@@ -87,12 +104,12 @@
         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 __spreadProps$2(__spreadValues$2({}, log), {
@@ -127,7 +144,7 @@
   }
   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;
@@ -253,7 +270,7 @@
     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":
@@ -263,7 +280,9 @@
       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) => {
@@ -364,8 +383,8 @@
       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() {
@@ -511,7 +530,7 @@
     return prng;
   }
 
-  const version="5.3.2";
+  const version="5.4.0";
 
   const default_request_retention = 0.9;
   const default_maximum_interval = 36500;
@@ -582,27 +601,31 @@
   ];
 
   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.`
       );
     }
@@ -732,7 +755,9 @@
      */
     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);
@@ -940,10 +965,10 @@
         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 {
@@ -958,7 +983,7 @@
         };
       }
       if (d < 1 || s < S_MIN) {
-        throw new Error(
+        throw new FSRSValidationError(
           `Invalid memory state { difficulty: ${d}, stability: ${s} }`
         );
       }
@@ -1363,7 +1388,9 @@
      */
     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;
@@ -1384,7 +1411,9 @@
         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 = {
@@ -1493,6 +1522,9 @@
   };
   var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
   var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  function applyAfterHandler(value, afterHandler) {
+    return typeof afterHandler === "function" ? afterHandler(value) : value;
+  }
   class FSRS extends FSRSAlgorithm {
     constructor(param) {
       super(param);
@@ -1608,11 +1640,7 @@
     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.
@@ -1672,14 +1700,10 @@
       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
@@ -1724,7 +1748,7 @@
       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;
@@ -1755,11 +1779,7 @@
         state: processedLog.state,
         last_review
       });
-      if (afterHandler && typeof afterHandler === "function") {
-        return afterHandler(prevCard);
-      } else {
-        return prevCard;
-      }
+      return applyAfterHandler(prevCard, afterHandler);
     }
     /**
      *
@@ -1841,11 +1861,7 @@
         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.
@@ -1912,15 +1928,9 @@
         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
       };
     }
   }