@shaxpir/duiduidui-models 1.9.18 → 1.9.20

package/dist/models/Collection.d.ts

@@ -13,15 +13,6 @@ export interface CollectionDisplay {
     icon?: string;
     sort_order: number;
 }
-/**
- * A snapshot of a term's proficiency within this collection.
- * Stored in term_scores map, keyed by termId.
- */
-export interface CollectionTermScore {
-    text: string;
-    sense_rank: number;
-    theta: number;
-}
 /**
  * The payload for a Collection document.
  *
@@ -34,7 +25,7 @@ export interface CollectionPayload {
     display: CollectionDisplay;
     proficiency: UncertainValue;
     term_scores: {
-        [termId: string]: CollectionTermScore;
+        [termKey: string]: number;
     };
     total_cards: number;
     last_activity_utc: CompactDateTime | null;
@@ -61,6 +52,18 @@ export declare class Collection extends Content {
      * The same user + collectionKey always produces the same ID.
      */
     static makeCollectionId(userId: ContentId, collectionKey: string): ContentId;
+    /**
+     * Encode a term key from text and sense_rank.
+     * Uses the standard SenseRankEncoder format: "text [N+1]" or "text [radical]"
+     */
+    static encodeTermKey(text: string, senseRank: number): string;
+    /**
+     * Decode a term key back to text and sense_rank.
+     */
+    static decodeTermKey(termKey: string): {
+        text: string;
+        senseRank: number;
+    };
     constructor(doc: Doc, shouldAcquire: boolean, shareSync: ShareSync);
     /**
      * Create a new Collection for a user.
@@ -79,16 +82,20 @@ export declare class Collection extends Content {
     get proficiencyRatingDeviation(): number;
     get proficiencyVolatility(): number;
     get termScores(): {
-        [termId: string]: CollectionTermScore;
+        [termKey: string]: number;
     };
     /**
      * Get the number of unique terms the user has reviewed in this collection.
      */
     get termsReviewedCount(): number;
     /**
-     * Get the term score for a specific term, or undefined if not reviewed.
+     * Get the theta score for a specific term, or undefined if not reviewed.
+     */
+    getTermScore(text: string, senseRank: number): number | undefined;
+    /**
+     * Get the theta score by encoded term key, or undefined if not reviewed.
      */
-    getTermScore(termId: string): CollectionTermScore | undefined;
+    getTermScoreByKey(termKey: string): number | undefined;
     get totalCards(): number;
     get lastActivityUtc(): CompactDateTime | null;
     get isVisible(): boolean;
@@ -124,16 +131,11 @@ export declare class Collection extends Content {
     /**
      * Update or add a term score in the collection.
      */
-    setTermScore(termId: string, score: CollectionTermScore): void;
-    /**
-     * Update just the theta value for an existing term score.
-     * Does nothing if the term doesn't exist in term_scores.
-     */
-    updateTermTheta(termId: string, theta: number): void;
+    setTermScore(text: string, senseRank: number, theta: number): void;
     /**
      * Remove a term score from the collection.
      */
-    removeTermScore(termId: string): void;
+    removeTermScore(text: string, senseRank: number): void;
     /**
      * Update the cached total card count for this collection.
      */

package/dist/models/Collection.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Collection = void 0;
 const shaxpir_common_1 = require("@shaxpir/shaxpir-common");
 const repo_1 = require("../repo");
+const SenseRankEncoder_1 = require("../util/SenseRankEncoder");
 const Content_1 = require("./Content");
 const ContentKind_1 = require("./ContentKind");
 const Operation_1 = require("./Operation");
@@ -14,6 +15,19 @@ class Collection extends Content_1.Content {
     static makeCollectionId(userId, collectionKey) {
         return shaxpir_common_1.CachingHasher.makeMd5Base62Hash(`${ContentKind_1.ContentKind.COLLECTION}-${userId}-${collectionKey}`);
     }
+    /**
+     * Encode a term key from text and sense_rank.
+     * Uses the standard SenseRankEncoder format: "text [N+1]" or "text [radical]"
+     */
+    static encodeTermKey(text, senseRank) {
+        return (0, SenseRankEncoder_1.encodeSenseRank)(text, senseRank);
+    }
+    /**
+     * Decode a term key back to text and sense_rank.
+     */
+    static decodeTermKey(termKey) {
+        return (0, SenseRankEncoder_1.decodeSenseRank)(termKey);
+    }
     constructor(doc, shouldAcquire, shareSync) {
         super(doc, shouldAcquire, shareSync);
     }
@@ -131,11 +145,19 @@ class Collection extends Content_1.Content {
         return Object.keys(this.payload.term_scores).length;
     }
     /**
-     * Get the term score for a specific term, or undefined if not reviewed.
+     * Get the theta score for a specific term, or undefined if not reviewed.
      */
-    getTermScore(termId) {
+    getTermScore(text, senseRank) {
         this.checkDisposed("Collection.getTermScore");
-        return this.payload.term_scores[termId];
+        const termKey = Collection.encodeTermKey(text, senseRank);
+        return this.payload.term_scores[termKey];
+    }
+    /**
+     * Get the theta score by encoded term key, or undefined if not reviewed.
+     */
+    getTermScoreByKey(termKey) {
+        this.checkDisposed("Collection.getTermScoreByKey");
+        return this.payload.term_scores[termKey];
     }
     // ============================================================
     // Progress statistics getters
@@ -178,7 +200,7 @@ class Collection extends Content_1.Content {
         const scores = Object.values(this.payload.term_scores);
         if (scores.length === 0)
             return 0;
-        const mastered = scores.filter(s => s.theta >= 0.8).length;
+        const mastered = scores.filter(theta => theta >= 0.8).length;
         return Math.round((mastered / scores.length) * 100);
     }
     /**
@@ -199,11 +221,11 @@ class Collection extends Content_1.Content {
         this.checkDisposed("Collection.getGradeDistribution");
         const scores = Object.values(this.payload.term_scores);
         return {
-            A: scores.filter(s => s.theta >= 0.8).length,
-            B: scores.filter(s => s.theta >= 0.6 && s.theta < 0.8).length,
-            C: scores.filter(s => s.theta >= 0.4 && s.theta < 0.6).length,
-            D: scores.filter(s => s.theta >= 0.2 && s.theta < 0.4).length,
-            F: scores.filter(s => s.theta < 0.2).length
+            A: scores.filter(theta => theta >= 0.8).length,
+            B: scores.filter(theta => theta >= 0.6 && theta < 0.8).length,
+            C: scores.filter(theta => theta >= 0.4 && theta < 0.6).length,
+            D: scores.filter(theta => theta >= 0.2 && theta < 0.4).length,
+            F: scores.filter(theta => theta < 0.2).length
         };
     }
     // ============================================================
@@ -225,32 +247,22 @@ class Collection extends Content_1.Content {
     /**
      * Update or add a term score in the collection.
      */
-    setTermScore(termId, score) {
+    setTermScore(text, senseRank, theta) {
         this.checkDisposed("Collection.setTermScore");
+        const termKey = Collection.encodeTermKey(text, senseRank);
         const batch = new Operation_1.BatchOperation(this);
-        batch.setPathValue(['payload', 'term_scores', termId], score);
+        batch.setPathValue(['payload', 'term_scores', termKey], theta);
         batch.commit();
     }
-    /**
-     * Update just the theta value for an existing term score.
-     * Does nothing if the term doesn't exist in term_scores.
-     */
-    updateTermTheta(termId, theta) {
-        this.checkDisposed("Collection.updateTermTheta");
-        if (this.payload.term_scores[termId]) {
-            const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'term_scores', termId, 'theta'], theta);
-            batch.commit();
-        }
-    }
     /**
      * Remove a term score from the collection.
      */
-    removeTermScore(termId) {
+    removeTermScore(text, senseRank) {
         this.checkDisposed("Collection.removeTermScore");
-        if (this.payload.term_scores[termId]) {
+        const termKey = Collection.encodeTermKey(text, senseRank);
+        if (this.payload.term_scores[termKey] !== undefined) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.removeValueAtPath(['payload', 'term_scores', termId]);
+            batch.removeValueAtPath(['payload', 'term_scores', termKey]);
             batch.commit();
         }
     }

package/dist/util/ConditionMatcher.d.ts

@@ -0,0 +1,57 @@
+import { CompactDateTime } from "@shaxpir/shaxpir-common";
+import { AnyCondition, Conditions } from '../models/Condition';
+/**
+ * Interface for objects that can be matched against Conditions.
+ * This is the minimum set of fields needed for condition matching.
+ *
+ * Implementers include AnnotatedPhrase (in the app) and potentially
+ * other phrase-like objects that need condition checking.
+ */
+export interface ConditionMatchable {
+    tags?: string[];
+    starred_at?: CompactDateTime | null;
+    theta?: number | null;
+    difficulty: number;
+    content_id?: string;
+    last_review_utc?: CompactDateTime | null;
+    created_at?: CompactDateTime;
+    updated_at?: CompactDateTime;
+    review_count?: number;
+    implied_review_count?: number;
+}
+/**
+ * Utility for checking if objects match Conditions.
+ *
+ * This is used by:
+ * - UnifiedSearchQuery to filter search results
+ * - CollectionProficiencyService to determine which Collections contain a phrase
+ */
+export declare const ConditionMatcher: {
+    /**
+     * Check if a single condition matches a matchable object.
+     */
+    conditionMatches(condition: AnyCondition, item: ConditionMatchable): boolean;
+    /**
+     * Check if an item matches all the provided conditions.
+     *
+     * Conditions use three logical groups:
+     * - all: Item must match ALL of these conditions
+     * - any: Item must match AT LEAST ONE of these conditions
+     * - none: Item must match NONE of these conditions
+     */
+    matchesConditions(item: ConditionMatchable, conditions: Conditions | undefined): boolean;
+    /**
+     * Filter an array of items to only those matching the conditions.
+     */
+    filterByConditions<T extends ConditionMatchable>(items: T[], conditions: Conditions | undefined): T[];
+    /**
+     * Check if an item matches any of the provided Conditions sets.
+     * Useful for checking membership in multiple Collections at once.
+     */
+    matchesAnyConditions(item: ConditionMatchable, conditionsList: Conditions[]): boolean;
+    /**
+     * Find all Conditions sets that an item matches.
+     * Returns indices of matching conditions in the input array.
+     */
+    findMatchingConditions(item: ConditionMatchable, conditionsList: Conditions[]): number[];
+};

package/dist/util/ConditionMatcher.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConditionMatcher = void 0;
+/**
+ * Utility for checking if objects match Conditions.
+ *
+ * This is used by:
+ * - UnifiedSearchQuery to filter search results
+ * - CollectionProficiencyService to determine which Collections contain a phrase
+ */
+exports.ConditionMatcher = {
+    /**
+     * Check if a single condition matches a matchable object.
+     */
+    conditionMatches(condition, item) {
+        switch (condition.type) {
+            case 'tag': {
+                const tagCond = condition;
+                const allTags = item.tags || [];
+                return allTags.includes(tagCond.tag);
+            }
+            case 'starred': {
+                const starredCond = condition;
+                const isStarred = item.starred_at !== null && item.starred_at !== undefined;
+                return starredCond.value === isStarred;
+            }
+            case 'theta': {
+                const thetaCond = condition;
+                if (item.theta === null || item.theta === undefined)
+                    return false;
+                if (thetaCond.min !== undefined && item.theta < thetaCond.min)
+                    return false;
+                if (thetaCond.max !== undefined && item.theta > thetaCond.max)
+                    return false;
+                return true;
+            }
+            case 'grade': {
+                const gradeCond = condition;
+                if (item.theta === null || item.theta === undefined)
+                    return false;
+                // Map theta to grade: A (0.8-1), B (0.6-0.8), C (0.4-0.6), D (0.2-0.4), F (0-0.2)
+                let itemGrade;
+                if (item.theta >= 0.8)
+                    itemGrade = 'A';
+                else if (item.theta >= 0.6)
+                    itemGrade = 'B';
+                else if (item.theta >= 0.4)
+                    itemGrade = 'C';
+                else if (item.theta >= 0.2)
+                    itemGrade = 'D';
+                else
+                    itemGrade = 'F';
+                return itemGrade === gradeCond.grade;
+            }
+            case 'difficulty': {
+                const diffCond = condition;
+                if (diffCond.min !== undefined && item.difficulty < diffCond.min)
+                    return false;
+                if (diffCond.max !== undefined && item.difficulty > diffCond.max)
+                    return false;
+                return true;
+            }
+            case 'has_term': {
+                const hasTermCond = condition;
+                const hasTerm = item.content_id !== undefined;
+                return hasTermCond.value === hasTerm;
+            }
+            case 'temporal': {
+                const tempCond = condition;
+                let fieldValue;
+                switch (tempCond.field) {
+                    case 'last_review_utc':
+                        fieldValue = item.last_review_utc;
+                        break;
+                    case 'starred_at':
+                        fieldValue = item.starred_at;
+                        break;
+                    case 'created_at':
+                        fieldValue = item.created_at;
+                        break;
+                    case 'updated_at':
+                        fieldValue = item.updated_at;
+                        break;
+                }
+                if (fieldValue === null || fieldValue === undefined) {
+                    // No value means condition can't be satisfied for most operators
+                    return false;
+                }
+                // For temporal conditions, we'd need to compare against current time
+                // This is complex because we need access to ClockService
+                // For now, return true (don't filter out) - these conditions are
+                // typically used in SQL queries rather than in-memory filtering
+                return true;
+            }
+            case 'count': {
+                const countCond = condition;
+                let fieldValue;
+                switch (countCond.field) {
+                    case 'review_count':
+                        fieldValue = item.review_count ?? 0;
+                        break;
+                    case 'implied_review_count':
+                        fieldValue = item.implied_review_count ?? 0;
+                        break;
+                }
+                switch (countCond.operator) {
+                    case '>': return fieldValue > countCond.value;
+                    case '<': return fieldValue < countCond.value;
+                    case '>=': return fieldValue >= countCond.value;
+                    case '<=': return fieldValue <= countCond.value;
+                    case '=': return fieldValue === countCond.value;
+                    case '!=': return fieldValue !== countCond.value;
+                }
+                return true;
+            }
+            case 'component': {
+                // Component conditions require database lookups and are not
+                // suitable for in-memory filtering. Return true (don't filter out).
+                return true;
+            }
+            default:
+                // For unsupported conditions, default to true (don't filter out)
+                return true;
+        }
+    },
+    /**
+     * Check if an item matches all the provided conditions.
+     *
+     * Conditions use three logical groups:
+     * - all: Item must match ALL of these conditions
+     * - any: Item must match AT LEAST ONE of these conditions
+     * - none: Item must match NONE of these conditions
+     */
+    matchesConditions(item, conditions) {
+        if (!conditions)
+            return true;
+        // Check 'all' conditions - item must match ALL of these
+        if (conditions.all && conditions.all.length > 0) {
+            for (const cond of conditions.all) {
+                if (!exports.ConditionMatcher.conditionMatches(cond, item)) {
+                    return false;
+                }
+            }
+        }
+        // Check 'any' conditions - item must match AT LEAST ONE of these
+        if (conditions.any && conditions.any.length > 0) {
+            let matchedAny = false;
+            for (const cond of conditions.any) {
+                if (exports.ConditionMatcher.conditionMatches(cond, item)) {
+                    matchedAny = true;
+                    break;
+                }
+            }
+            if (!matchedAny)
+                return false;
+        }
+        // Check 'none' conditions - item must match NONE of these
+        if (conditions.none && conditions.none.length > 0) {
+            for (const cond of conditions.none) {
+                if (exports.ConditionMatcher.conditionMatches(cond, item)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    },
+    /**
+     * Filter an array of items to only those matching the conditions.
+     */
+    filterByConditions(items, conditions) {
+        if (!conditions)
+            return items;
+        return items.filter(item => exports.ConditionMatcher.matchesConditions(item, conditions));
+    },
+    /**
+     * Check if an item matches any of the provided Conditions sets.
+     * Useful for checking membership in multiple Collections at once.
+     */
+    matchesAnyConditions(item, conditionsList) {
+        for (const conditions of conditionsList) {
+            if (exports.ConditionMatcher.matchesConditions(item, conditions)) {
+                return true;
+            }
+        }
+        return false;
+    },
+    /**
+     * Find all Conditions sets that an item matches.
+     * Returns indices of matching conditions in the input array.
+     */
+    findMatchingConditions(item, conditionsList) {
+        const matches = [];
+        for (let i = 0; i < conditionsList.length; i++) {
+            if (exports.ConditionMatcher.matchesConditions(item, conditionsList[i])) {
+                matches.push(i);
+            }
+        }
+        return matches;
+    }
+};

package/dist/util/SenseRankEncoder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Utilities for encoding and decoding sense_rank into search text.
+ *
+ * Encoding format (1-based for user display):
+ * - sense_rank >= 0: "text [N+1]" where N is the sense_rank (displayed as 1-based)
+ * - sense_rank = -1: "text [radical]"
+ *
+ * Examples:
+ * - "王 [1]" -> sense_rank: 0 (displayed as 1, stored as 0)
+ * - "王 [2]" -> sense_rank: 1 (displayed as 2, stored as 1)
+ * - "王 [radical]" -> sense_rank: -1
+ *
+ * Note: [0] and negative numbers in brackets are invalid and default to sense_rank 0.
+ */
+export interface DecodedSearchText {
+    text: string;
+    senseRank: number;
+}
+/**
+ * Encodes a text and sense_rank into a search string.
+ *
+ * @param text The Chinese text
+ * @param senseRank The sense rank (-1, 0, 1, 2, ...)
+ * @returns Encoded search string
+ */
+export declare function encodeSenseRank(text: string, senseRank: number): string;
+/**
+ * Decodes a search string into text and sense_rank.
+ *
+ * @param searchText The search string (possibly encoded)
+ * @returns Decoded text and sense_rank
+ */
+export declare function decodeSenseRank(searchText: string): DecodedSearchText;

package/dist/util/SenseRankEncoder.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Utilities for encoding and decoding sense_rank into search text.
+ *
+ * Encoding format (1-based for user display):
+ * - sense_rank >= 0: "text [N+1]" where N is the sense_rank (displayed as 1-based)
+ * - sense_rank = -1: "text [radical]"
+ *
+ * Examples:
+ * - "王 [1]" -> sense_rank: 0 (displayed as 1, stored as 0)
+ * - "王 [2]" -> sense_rank: 1 (displayed as 2, stored as 1)
+ * - "王 [radical]" -> sense_rank: -1
+ *
+ * Note: [0] and negative numbers in brackets are invalid and default to sense_rank 0.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSenseRank = encodeSenseRank;
+exports.decodeSenseRank = decodeSenseRank;
+/**
+ * Encodes a text and sense_rank into a search string.
+ *
+ * @param text The Chinese text
+ * @param senseRank The sense rank (-1, 0, 1, 2, ...)
+ * @returns Encoded search string
+ */
+function encodeSenseRank(text, senseRank) {
+    if (senseRank === -1) {
+        return `${text} [radical]`;
+    }
+    else if (senseRank >= 0) {
+        // Convert to 1-based indexing for user display
+        return `${text} [${senseRank + 1}]`;
+    }
+    else {
+        // For any other negative values (shouldn't happen), treat as radical
+        return `${text} [radical]`;
+    }
+}
+/**
+ * Decodes a search string into text and sense_rank.
+ *
+ * @param searchText The search string (possibly encoded)
+ * @returns Decoded text and sense_rank
+ */
+function decodeSenseRank(searchText) {
+    // Trim the input first to handle leading/trailing whitespace
+    const trimmed = searchText.trim();
+    // Pattern to match "[N]" or "[radical]" at the end of the string
+    // Whitespace before the bracket is optional
+    // Note: If multiple bracket groups exist (e.g., "要[1][2]"), the regex will match
+    // the last valid one due to backtracking, treating "要[1]" as text with senseRank=1
+    const pattern = /^(.+?)\s*\[(\d+|radical)\]$/;
+    const match = trimmed.match(pattern);
+    if (!match) {
+        // No encoding found, treat as sense_rank = 0
+        return {
+            text: searchText.trim(),
+            senseRank: 0
+        };
+    }
+    const text = match[1].trim();
+    const senseRankStr = match[2];
+    if (senseRankStr === 'radical') {
+        return {
+            text,
+            senseRank: -1
+        };
+    }
+    else {
+        // Convert from 1-based display indexing back to 0-based storage
+        const displayIndex = parseInt(senseRankStr, 10);
+        // [0] and negative numbers are invalid, default to sense_rank 0
+        if (displayIndex <= 0) {
+            return {
+                text,
+                senseRank: 0
+            };
+        }
+        return {
+            text,
+            senseRank: displayIndex - 1
+        };
+    }
+}

package/dist/util/index.d.ts

@@ -1,4 +1,6 @@
 export * from './AvatarUri';
+export * from './ConditionMatcher';
 export * from './Database';
 export * from './Encryption';
 export * from './Logging';
+export * from './SenseRankEncoder';

package/dist/util/index.js

@@ -16,6 +16,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./AvatarUri"), exports);
+__exportStar(require("./ConditionMatcher"), exports);
 __exportStar(require("./Database"), exports);
 __exportStar(require("./Encryption"), exports);
 __exportStar(require("./Logging"), exports);
+__exportStar(require("./SenseRankEncoder"), exports);

package/package.json

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