@shaxpir/duiduidui-models 1.36.2 → 1.37.0

package/dist/models/BayesianScore.d.ts

@@ -11,6 +11,11 @@ export interface BayesianScore {
 }
 export declare class BayesianScoreModel {
     static apply(prevScore: BayesianScore, result: ReviewResult, weight: number): BayesianScore;
+    /**
+     * Reverse a previously applied Bayesian update.
+     * Subtracts the same deltas that apply() added, then recalculates theta and uncertainty.
+     */
+    static reverse(currentScore: BayesianScore, result: ReviewResult, weight: number): BayesianScore;
     /**
      * Calculate uncertainty for a given Bayesian score.
      * Higher values indicate less confidence in the theta estimate.

package/dist/models/BayesianScore.js

@@ -24,6 +24,31 @@ class BayesianScoreModel {
         nextScore.uncertainty = BayesianScoreModel.calculateUncertainty(nextScore.alpha, nextScore.beta);
         return nextScore;
     }
+    /**
+     * Reverse a previously applied Bayesian update.
+     * Subtracts the same deltas that apply() added, then recalculates theta and uncertainty.
+     */
+    static reverse(currentScore, result, weight) {
+        if (isNaN(weight) || !isFinite(weight) || weight < 0 || weight > 1) {
+            throw new Error(`illegal weight value: ${weight}`);
+        }
+        const prevScore = shaxpir_common_1.Struct.clone(currentScore);
+        if (result == 'EASY') {
+            prevScore.alpha -= (weight * 1.0);
+        }
+        else if (result == 'GOOD') {
+            prevScore.alpha -= (weight * 0.7);
+        }
+        else if (result == 'HARD') {
+            prevScore.beta -= (weight * 0.3);
+        }
+        else if (result == 'FAIL') {
+            prevScore.beta -= (weight * 1.0);
+        }
+        prevScore.theta = prevScore.alpha / (prevScore.alpha + prevScore.beta);
+        prevScore.uncertainty = BayesianScoreModel.calculateUncertainty(prevScore.alpha, prevScore.beta);
+        return prevScore;
+    }
     /**
      * Calculate uncertainty for a given Bayesian score.
      * Higher values indicate less confidence in the theta estimate.

package/dist/models/Collection.d.ts

@@ -37,6 +37,7 @@ export interface CollectionPayload {
     term_scores: {
         [termKey: string]: number;
     };
+    engagement_score: number;
     total_cards: number;
     last_activity_utc: CompactDateTime | null;
     is_visible: boolean;
@@ -96,6 +97,12 @@ export declare class Collection extends Content {
     get termScores(): {
         [termKey: string]: number;
     };
+    /**
+     * Cached sum of all term_scores values. Maintained incrementally by
+     * setTermScore() and removeTermScore() so that engagement-based sorting
+     * doesn't need to iterate the full map.
+     */
+    get engagementScore(): number;
     /**
      * Get the number of unique terms the user has reviewed in this collection.
      */

package/dist/models/Collection.js

@@ -59,6 +59,7 @@ class Collection extends Content_1.Content {
                 proficiency: SkillLevel_1.SkillLevelModel.createDefault(),
                 // Empty term scores map - populated as user reviews cards
                 term_scores: {},
+                engagement_score: 0,
                 // Progress starts at zero
                 total_cards: 0,
                 last_activity_utc: null,
@@ -141,6 +142,15 @@ class Collection extends Content_1.Content {
         this.checkDisposed("Collection.termScores");
         return this.payload.term_scores;
     }
+    /**
+     * Cached sum of all term_scores values. Maintained incrementally by
+     * setTermScore() and removeTermScore() so that engagement-based sorting
+     * doesn't need to iterate the full map.
+     */
+    get engagementScore() {
+        this.checkDisposed("Collection.engagementScore");
+        return this.payload.engagement_score ?? 0;
+    }
     /**
      * Get the number of unique terms the user has reviewed in this collection.
      */
@@ -274,8 +284,11 @@ class Collection extends Content_1.Content {
     setTermScore(text, senseRank, theta) {
         this.checkDisposed("Collection.setTermScore");
         const termKey = Collection.encodeTermKey(text, senseRank);
+        const prevTheta = this.payload.term_scores[termKey] ?? 0;
+        const prevEngagement = this.payload.engagement_score ?? 0;
         const batch = new Operation_1.BatchOperation(this);
         batch.setPathValue(['payload', 'term_scores', termKey], theta);
+        batch.setPathValue(['payload', 'engagement_score'], prevEngagement - prevTheta + theta);
         batch.commit();
     }
     /**
@@ -284,9 +297,12 @@ class Collection extends Content_1.Content {
     removeTermScore(text, senseRank) {
         this.checkDisposed("Collection.removeTermScore");
         const termKey = Collection.encodeTermKey(text, senseRank);
-        if (this.payload.term_scores[termKey] !== undefined) {
+        const prevTheta = this.payload.term_scores[termKey];
+        if (prevTheta !== undefined) {
+            const prevEngagement = this.payload.engagement_score ?? 0;
             const batch = new Operation_1.BatchOperation(this);
             batch.removeValueAtPath(['payload', 'term_scores', termKey]);
+            batch.setPathValue(['payload', 'engagement_score'], prevEngagement - prevTheta);
             batch.commit();
         }
     }

package/dist/models/Session.d.ts

@@ -88,6 +88,11 @@ export declare class Session extends Content {
     get deviceId(): ContentId;
     get reviews(): Review[];
     get reviewCount(): number;
+    /**
+     * Remove the last review from this session.
+     * Decrements review_count.
+     */
+    removeLastReview(): void;
     addReview(review: Review): void;
     get config(): ReviewConfig | undefined;
     setConfig(config: ReviewConfig): void;

package/dist/models/Session.js

@@ -95,6 +95,20 @@ class Session extends Content_1.Content {
         this.checkDisposed("Session.getReviewCount");
         return this._reviewsView.length;
     }
+    /**
+     * Remove the last review from this session.
+     * Decrements review_count.
+     */
+    removeLastReview() {
+        this.checkDisposed("Session.removeLastReview");
+        if (this._reviewsView.length === 0)
+            return;
+        const lastIndex = this._reviewsView.length - 1;
+        this._reviewsView.removeAt(lastIndex);
+        const batch = new Operation_1.BatchOperation(this);
+        batch.setPathValue(['payload', 'review_count'], this._reviewsView.length);
+        batch.commit();
+    }
     addReview(review) {
         this.checkDisposed("Session.addReview");
         if (review.hasOwnProperty('context') && review.hasOwnProperty('weight')) {

package/dist/models/SkillLevel.d.ts

@@ -113,6 +113,16 @@ export declare class SkillLevelModel {
      * @returns Updated skill level with new mu and sigma
      */
     static update(mu: number, sigma: number, cardDifficulty: number, outcome: ReviewResult, params?: SkillUpdateParams): SkillLevel;
+    /**
+     * Reverse a previously applied skill level update.
+     * Algebraically inverts the forward update: oldMu = (newMu - coeff * difficulty) / (1 - coeff).
+     * If the forward update was uninformative (no change), this is also a no-op.
+     *
+     * Note: If the forward update hit the Math.max(0, ...) clamp on mu, the original value
+     * is not perfectly recoverable. In practice this doesn't happen because mu represents
+     * a character count and starts at 0 moving upward.
+     */
+    static reverse(mu: number, sigma: number, cardDifficulty: number, outcome: ReviewResult, params?: SkillUpdateParams): SkillLevel;
     /**
      * Map a review outcome to a success score for IRT.
      *

package/dist/models/SkillLevel.js

@@ -73,6 +73,35 @@ class SkillLevelModel {
             sigma: Math.max(minSigma, Math.min(maxSigma, newSigma))
         };
     }
+    /**
+     * Reverse a previously applied skill level update.
+     * Algebraically inverts the forward update: oldMu = (newMu - coeff * difficulty) / (1 - coeff).
+     * If the forward update was uninformative (no change), this is also a no-op.
+     *
+     * Note: If the forward update hit the Math.max(0, ...) clamp on mu, the original value
+     * is not perfectly recoverable. In practice this doesn't happen because mu represents
+     * a character count and starts at 0 moving upward.
+     */
+    static reverse(mu, sigma, cardDifficulty, outcome, params = {}) {
+        const { updateCoefficient = exports.DEFAULT_SKILL_PARAMS.updateCoefficient, sigmaDecay = exports.DEFAULT_SKILL_PARAMS.sigmaDecay, minSigma = exports.DEFAULT_SKILL_PARAMS.minSigma, maxSigma = exports.DEFAULT_SKILL_PARAMS.maxSigma } = params;
+        // Reverse sigma first: oldSigma = newSigma / sigmaDecay
+        const oldSigma = sigma / sigmaDecay;
+        // Reverse mu: oldMu = (newMu - coeff * difficulty) / (1 - coeff)
+        const oldMu = (mu - updateCoefficient * cardDifficulty) / (1 - updateCoefficient);
+        // Check if the forward update would have been uninformative from the original state.
+        // If so, mu and sigma didn't change — return the current values unchanged.
+        const isSuccess = outcome === 'EASY' || outcome === 'GOOD';
+        const isFailure = outcome === 'FAIL' || outcome === 'HARD';
+        const wasInformative = (isSuccess && cardDifficulty > oldMu) ||
+            (isFailure && cardDifficulty < oldMu);
+        if (!wasInformative) {
+            return { mu, sigma };
+        }
+        return {
+            mu: Math.max(0, oldMu),
+            sigma: Math.max(minSigma, Math.min(maxSigma, oldSigma))
+        };
+    }
     /**
      * Map a review outcome to a success score for IRT.
      *

package/dist/models/Term.d.ts

@@ -91,5 +91,15 @@ export declare class Term extends Content {
     get impliedReviews(): ImpliedReview[];
     get reviewCount(): number;
     get impliedReviewCount(): number;
+    /**
+     * Remove the last direct review from this term.
+     * Decrements review_count and restores last_review_utc from the previous review.
+     */
+    removeLastReview(): void;
+    /**
+     * Remove the last implied review from this term.
+     * Decrements implied_review_count.
+     */
+    removeLastImpliedReview(): void;
     addReview(review: ReviewLike): void;
 }

package/dist/models/Term.js

@@ -256,6 +256,42 @@ class Term extends Content_1.Content {
         this.checkDisposed("Term.impliedReviewCount");
         return this.payload.implied_review_count;
     }
+    /**
+     * Remove the last direct review from this term.
+     * Decrements review_count and restores last_review_utc from the previous review.
+     */
+    removeLastReview() {
+        this.checkDisposed("Term.removeLastReview");
+        if (this._reviewsView.length === 0)
+            return;
+        const lastIndex = this._reviewsView.length - 1;
+        this._reviewsView.removeAt(lastIndex);
+        const batch = new Operation_1.BatchOperation(this);
+        batch.setPathValue(['payload', 'review_count'], this._reviewsView.length);
+        // Restore last_review_utc from the new last review, or null if no reviews remain
+        if (this._reviewsView.length > 0) {
+            const prevLast = this._reviewsView.get(this._reviewsView.length - 1);
+            batch.setPathValue(['payload', 'last_review_utc'], prevLast.at_utc_time);
+        }
+        else {
+            batch.setPathValue(['payload', 'last_review_utc'], null);
+        }
+        batch.commit();
+    }
+    /**
+     * Remove the last implied review from this term.
+     * Decrements implied_review_count.
+     */
+    removeLastImpliedReview() {
+        this.checkDisposed("Term.removeLastImpliedReview");
+        if (this._impliedReviewsView.length === 0)
+            return;
+        const lastIndex = this._impliedReviewsView.length - 1;
+        this._impliedReviewsView.removeAt(lastIndex);
+        const batch = new Operation_1.BatchOperation(this);
+        batch.setPathValue(['payload', 'implied_review_count'], this._impliedReviewsView.length);
+        batch.commit();
+    }
     // Add either an implied or explicit review
     addReview(review) {
         this.checkDisposed("Term.addReview");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaxpir/duiduidui-models",
-  "version": "1.36.2",
+  "version": "1.37.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/shaxpir/duiduidui-models"