@shaxpir/duiduidui-models 1.8.1 → 1.9.0

package/dist/models/Condition.d.ts

@@ -37,7 +37,16 @@ export interface DifficultyCondition extends BaseCondition {
     min?: number;
     max?: number;
 }
-export type AnyCondition = TagCondition | GradeCondition | ThetaCondition | TemporalCondition | CountCondition | StarredCondition | DifficultyCondition;
+export interface HasTermCondition extends BaseCondition {
+    type: 'has_term';
+    value: boolean;
+}
+export interface ComponentCondition extends BaseCondition {
+    type: 'component';
+    components: string[];
+    mode: 'any' | 'all';
+}
+export type AnyCondition = TagCondition | GradeCondition | ThetaCondition | TemporalCondition | CountCondition | StarredCondition | DifficultyCondition | HasTermCondition | ComponentCondition;
 export interface ConditionFilters {
     all?: AnyCondition[];
     any?: AnyCondition[];
@@ -72,6 +81,11 @@ export declare const Condition: {
     intermediate: () => DifficultyCondition;
     advanced: () => DifficultyCondition;
     expert: () => DifficultyCondition;
+    hasTerm: () => HasTermCondition;
+    noTerm: () => HasTermCondition;
+    hasComponent: (component: string) => ComponentCondition;
+    hasAnyComponent: (components: string[]) => ComponentCondition;
+    hasAllComponents: (components: string[]) => ComponentCondition;
     /**
      * Check if starred condition is required (in 'all' section)
      */

package/dist/models/Condition.js

@@ -38,6 +38,13 @@ exports.Condition = {
     intermediate: () => ({ type: 'difficulty', min: 500, max: 1500 }), // Medium
     advanced: () => ({ type: 'difficulty', min: 1500, max: 3000 }), // Hard
     expert: () => ({ type: 'difficulty', min: 3000 }), // Very hard
+    // HasTerm conditions
+    hasTerm: () => ({ type: 'has_term', value: true }),
+    noTerm: () => ({ type: 'has_term', value: false }),
+    // Component conditions
+    hasComponent: (component) => ({ type: 'component', components: [component], mode: 'any' }),
+    hasAnyComponent: (components) => ({ type: 'component', components, mode: 'any' }),
+    hasAllComponents: (components) => ({ type: 'component', components, mode: 'all' }),
     // Helper methods to check if conditions are present in filters
     /**
      * Check if starred condition is required (in 'all' section)
@@ -129,6 +136,30 @@ exports.Condition = {
         if (allGrades.length > 1) {
             errors.push(`Cannot require multiple grades: ${allGrades.join(', ')} - an item can only have one grade`);
         }
+        // Check for contradictory has_term conditions
+        const requiresTerm = filters.all?.some(c => c.type === 'has_term' && c.value === true);
+        const excludesTerm = filters.all?.some(c => c.type === 'has_term' && c.value === false);
+        if (requiresTerm && excludesTerm) {
+            errors.push('Cannot require both has_term and no_term');
+        }
+        // Check for implicit term requirements conflicting with no_term
+        const termDependentTypes = ['grade', 'theta', 'starred', 'temporal', 'count'];
+        const hasTermDependentInAll = filters.all?.some(c => termDependentTypes.includes(c.type));
+        const hasTermDependentInAny = filters.any?.some(c => termDependentTypes.includes(c.type));
+        if (excludesTerm && hasTermDependentInAll) {
+            const conflictingTypes = filters.all
+                ?.filter(c => termDependentTypes.includes(c.type))
+                .map(c => c.type)
+                .join(', ');
+            errors.push(`Conditions [${conflictingTypes}] require a term record, but has_term is false`);
+        }
+        if (excludesTerm && hasTermDependentInAny) {
+            const conflictingTypes = filters.any
+                ?.filter(c => termDependentTypes.includes(c.type))
+                .map(c => c.type)
+                .join(', ');
+            errors.push(`Conditions [${conflictingTypes}] in 'any' section require a term record, but has_term is false`);
+        }
         return errors;
     },
     // Backward compatibility aliases (deprecated - use requiresStarred/allowsStarred/excludesStarred instead)

package/dist/models/Device.d.ts

@@ -3,6 +3,7 @@ import { CompactDateTime } from "@shaxpir/shaxpir-common";
 import { ShareSync } from '../repo';
 import { Content, ContentBody, ContentId, ContentMeta } from "./Content";
 import { ConditionFilters } from './Condition';
+import { BuiltInDbState, DatabaseVersion } from '../util/Database';
 export interface LastSync {
     at_utc_time: CompactDateTime | null;
 }
@@ -34,6 +35,7 @@ export interface DevicePayload {
     conditions?: ConditionFilters;
     download_queue?: DownloadQueueItem[];
     upload_queue?: UploadQueueItem[];
+    builtin_db?: BuiltInDbState;
 }
 export interface DeviceBody extends ContentBody {
     meta: ContentMeta;
@@ -49,6 +51,17 @@ export declare class Device extends Content {
     setLastSyncAtUtcTime(value: CompactDateTime): void;
     get chineseFont(): string;
     setChineseFont(value: string): void;
+    getBuiltInDbState(): BuiltInDbState | undefined;
+    getBuiltInDbVersion(): DatabaseVersion;
+    getBuiltInDbPendingVersion(): DatabaseVersion;
+    getBuiltInDbDownloadStatus(): string;
+    getBuiltInDbLastCheck(): CompactDateTime;
+    getBuiltInDbLastError(): string;
+    setBuiltInDbVersion(version: DatabaseVersion | null): void;
+    setBuiltInDbPendingVersion(pending_version: DatabaseVersion | null): void;
+    setBuiltInDbDownloadStatus(download_status: 'none' | 'downloading' | 'ready' | 'failed'): void;
+    setBuiltInDbLastCheck(last_check: CompactDateTime | null): void;
+    setBuiltInDbLastError(last_error: string | null): void;
     get downloadQueue(): DownloadQueueItem[];
     get downloadQueueLength(): number;
     addToDownloadQueue(item: AudioDownloadQueueItem | ImageDownloadQueueItem): void;

package/dist/models/Device.js

@@ -22,7 +22,14 @@ class Device extends Content_1.Content {
             payload: {
                 last_sync: { at_utc_time: null },
                 download_queue: [],
-                upload_queue: []
+                upload_queue: [],
+                builtin_db: {
+                    version: null,
+                    pending_version: null,
+                    download_status: 'none',
+                    last_check: null,
+                    last_error: null
+                }
             }
         });
     }
@@ -59,6 +66,68 @@ class Device extends Content_1.Content {
             batch.commit();
         }
     }
+    // Built-in Database State Methods
+    getBuiltInDbState() {
+        this.checkDisposed("Device.getBuiltInDbState");
+        return shaxpir_common_1.Struct.clone(this.payload.builtin_db);
+    }
+    // Convenience getters for built-in DB state
+    getBuiltInDbVersion() {
+        return this.payload.builtin_db.version;
+    }
+    getBuiltInDbPendingVersion() {
+        return this.payload.builtin_db.pending_version;
+    }
+    getBuiltInDbDownloadStatus() {
+        return this.payload.builtin_db.download_status;
+    }
+    getBuiltInDbLastCheck() {
+        return this.payload.builtin_db.last_check;
+    }
+    getBuiltInDbLastError() {
+        return this.payload.builtin_db.last_error;
+    }
+    // Convenience setters for built-in DB state
+    setBuiltInDbVersion(version) {
+        this.checkDisposed("Device.setBuiltInDbVersion");
+        if (this.getBuiltInDbVersion() !== version) {
+            const batch = new Operation_1.BatchOperation(this);
+            batch.setPathValue(['payload', 'builtin_db', 'version'], version);
+            batch.commit();
+        }
+    }
+    setBuiltInDbPendingVersion(pending_version) {
+        this.checkDisposed("Device.setBuiltInDbPendingVersion");
+        if (this.getBuiltInDbPendingVersion() !== pending_version) {
+            const batch = new Operation_1.BatchOperation(this);
+            batch.setPathValue(['payload', 'builtin_db', 'pending_version'], pending_version);
+            batch.commit();
+        }
+    }
+    setBuiltInDbDownloadStatus(download_status) {
+        this.checkDisposed("Device.setBuiltInDbDownloadStatus");
+        if (this.getBuiltInDbDownloadStatus() !== download_status) {
+            const batch = new Operation_1.BatchOperation(this);
+            batch.setPathValue(['payload', 'builtin_db', 'download_status'], download_status);
+            batch.commit();
+        }
+    }
+    setBuiltInDbLastCheck(last_check) {
+        this.checkDisposed("Device.setBuiltInDbLastCheck");
+        if (this.getBuiltInDbLastCheck() !== last_check) {
+            const batch = new Operation_1.BatchOperation(this);
+            batch.setPathValue(['payload', 'builtin_db', 'last_check'], last_check);
+            batch.commit();
+        }
+    }
+    setBuiltInDbLastError(last_error) {
+        this.checkDisposed("Device.setBuiltInDbLastError");
+        if (this.getBuiltInDbLastError() !== last_error) {
+            const batch = new Operation_1.BatchOperation(this);
+            batch.setPathValue(['payload', 'builtin_db', 'last_error'], last_error);
+            batch.commit();
+        }
+    }
     // Download Queue Methods
     get downloadQueue() {
         this.checkDisposed("Device.downloadQueue");

package/dist/util/Database.d.ts

@@ -0,0 +1,124 @@
+import { CompactDateTime } from '@shaxpir/shaxpir-common';
+declare enum DatabaseVersionBrand {
+}
+/**
+ * Branded type for database version strings (YYYYMMDDx format)
+ * Ensures only validated version strings are used
+ */
+export type DatabaseVersion = string & DatabaseVersionBrand;
+/**
+ * Describes a version of the built-in database available for download
+ */
+export interface BuiltInDbMetadata {
+    version: DatabaseVersion;
+    url: string;
+    uncompressed_size: number;
+    compressed_size: number;
+    checksum: string;
+    published_at: string;
+    min_app_version: string;
+}
+/**
+ * Tracks the state of the built-in database on a device
+ * Stored in Device model's payload.builtin_db field
+ */
+export interface BuiltInDbState {
+    version: DatabaseVersion | null;
+    pending_version: DatabaseVersion | null;
+    download_status: DownloadStatus;
+    last_check: CompactDateTime | null;
+    last_error: string | null;
+}
+/**
+ * General-purpose download status enum
+ * Used for built-in DB, images, or any other downloadable content
+ */
+export type DownloadStatus = 'none' | 'downloading' | 'ready' | 'failed';
+/**
+ * Checksum utilities for validating downloaded files
+ */
+export declare class Checksum {
+    /**
+     * Parse a checksum string into algorithm and hash
+     * Format: "algorithm:hash" (e.g., "sha256:abc123...")
+     */
+    static parse(checksum: string): {
+        algorithm: string;
+        hash: string;
+    } | null;
+    /**
+     * Validate checksum format
+     */
+    static isValid(checksum: string): boolean;
+    /**
+     * Format a checksum (ensures consistent format)
+     */
+    static format(algorithm: string, hash: string): string;
+}
+/**
+ * Database version utilities
+ */
+export declare class DatabaseVersionModel {
+    /**
+     * Validate and create a branded DatabaseVersion from a string
+     * Throws if the version format is invalid
+     */
+    static from(version: string): DatabaseVersion;
+    /**
+     * Validate YYYYMMDDx format (where x is a lowercase letter a-z)
+     * Examples: "20250118a", "20250118b", "20250125a"
+     */
+    static isValid(version: string): boolean;
+    /**
+     * Compare two version strings
+     * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+     */
+    static compare(v1: DatabaseVersion, v2: DatabaseVersion): number;
+    /**
+     * Check if v1 is newer than v2
+     */
+    static isNewer(v1: DatabaseVersion, v2: DatabaseVersion): boolean;
+    /**
+     * Generate next version in sequence for the same day
+     * Example: "20250118a" -> "20250118b"
+     * Returns null if already at 'z'
+     */
+    static nextInDay(version: DatabaseVersion): DatabaseVersion | null;
+    /**
+     * Extract CompactDate from version string (ignores letter suffix)
+     * Example: "20250118a" -> "20250118"
+     */
+    static toCompactDate(version: DatabaseVersion): string;
+    /**
+     * Get the letter suffix from a version string
+     * Example: "20250118a" -> "a"
+     */
+    static getLetterSuffix(version: DatabaseVersion): string;
+}
+/**
+ * Constants for built-in database management
+ */
+export declare const BUILTIN_DB_CONSTANTS: {
+    readonly FILE_PREFIX: "duiduidui-";
+    readonly FILE_EXTENSION: ".sqlite";
+    readonly COMPRESSED_EXTENSION: ".sqlite.gz";
+    readonly VERSION_MANIFEST_FILENAME: "manifest.json";
+    readonly VERSION_FORMAT: "YYYYMMDDx";
+    readonly VERSION_REGEX: RegExp;
+    readonly DEFAULT_HASH_ALGORITHM: "sha256";
+    readonly SUPPORTED_HASH_ALGORITHMS: readonly ["sha256", "sha512"];
+    readonly MANIFEST_CACHE_TTL: 300;
+    readonly FILE_CACHE_TTL: 31536000;
+    readonly UPDATE_CHECK_INTERVAL_HOURS: 24;
+    readonly MAX_RETRIES: 5;
+    readonly RETRY_DELAYS_MS: readonly [1000, 2000, 4000, 8000, 16000];
+    readonly MIN_FREE_SPACE_MULTIPLIER: 2;
+};
+/**
+ * Helper to generate filename for a database version
+ * Examples:
+ *   getBuiltInDbFilename("20250118a", true)  -> "duiduidui-20250118a.sqlite.gz"
+ *   getBuiltInDbFilename("20250118a", false) -> "duiduidui-20250118a.sqlite"
+ */
+export declare function getBuiltInDbFilename(version: DatabaseVersion, compressed?: boolean): string;
+export {};

package/dist/util/Database.js

@@ -0,0 +1,135 @@
+"use strict";
+// Database version and download management types
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_DB_CONSTANTS = exports.DatabaseVersionModel = exports.Checksum = void 0;
+exports.getBuiltInDbFilename = getBuiltInDbFilename;
+var DatabaseVersionBrand;
+(function (DatabaseVersionBrand) {
+})(DatabaseVersionBrand || (DatabaseVersionBrand = {}));
+/**
+ * Checksum utilities for validating downloaded files
+ */
+class Checksum {
+    /**
+     * Parse a checksum string into algorithm and hash
+     * Format: "algorithm:hash" (e.g., "sha256:abc123...")
+     */
+    static parse(checksum) {
+        const match = checksum.match(/^(\w+):([a-f0-9]+)$/);
+        if (!match)
+            return null;
+        return { algorithm: match[1], hash: match[2] };
+    }
+    /**
+     * Validate checksum format
+     */
+    static isValid(checksum) {
+        return this.parse(checksum) !== null;
+    }
+    /**
+     * Format a checksum (ensures consistent format)
+     */
+    static format(algorithm, hash) {
+        return `${algorithm}:${hash}`;
+    }
+}
+exports.Checksum = Checksum;
+/**
+ * Database version utilities
+ */
+class DatabaseVersionModel {
+    /**
+     * Validate and create a branded DatabaseVersion from a string
+     * Throws if the version format is invalid
+     */
+    static from(version) {
+        if (!this.isValid(version)) {
+            throw new Error(`Invalid database version format: ${version}. Expected YYYYMMDDx (e.g., "20250118a")`);
+        }
+        return version;
+    }
+    /**
+     * Validate YYYYMMDDx format (where x is a lowercase letter a-z)
+     * Examples: "20250118a", "20250118b", "20250125a"
+     */
+    static isValid(version) {
+        return /^\d{8}[a-z]$/.test(version);
+    }
+    /**
+     * Compare two version strings
+     * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+     */
+    static compare(v1, v2) {
+        return v1.localeCompare(v2);
+    }
+    /**
+     * Check if v1 is newer than v2
+     */
+    static isNewer(v1, v2) {
+        return this.compare(v1, v2) > 0;
+    }
+    /**
+     * Generate next version in sequence for the same day
+     * Example: "20250118a" -> "20250118b"
+     * Returns null if already at 'z'
+     */
+    static nextInDay(version) {
+        const versionStr = version;
+        const letter = versionStr.charAt(8);
+        if (letter === 'z')
+            return null;
+        const nextLetter = String.fromCharCode(letter.charCodeAt(0) + 1);
+        return (versionStr.slice(0, 8) + nextLetter);
+    }
+    /**
+     * Extract CompactDate from version string (ignores letter suffix)
+     * Example: "20250118a" -> "20250118"
+     */
+    static toCompactDate(version) {
+        return version.slice(0, 8);
+    }
+    /**
+     * Get the letter suffix from a version string
+     * Example: "20250118a" -> "a"
+     */
+    static getLetterSuffix(version) {
+        return version.charAt(8);
+    }
+}
+exports.DatabaseVersionModel = DatabaseVersionModel;
+/**
+ * Constants for built-in database management
+ */
+exports.BUILTIN_DB_CONSTANTS = {
+    // File naming
+    FILE_PREFIX: 'duiduidui-',
+    FILE_EXTENSION: '.sqlite',
+    COMPRESSED_EXTENSION: '.sqlite.gz',
+    VERSION_MANIFEST_FILENAME: 'manifest.json',
+    // Version format
+    VERSION_FORMAT: 'YYYYMMDDx', // x is a lowercase letter a-z
+    VERSION_REGEX: /^\d{8}[a-z]$/,
+    // Checksums
+    DEFAULT_HASH_ALGORITHM: 'sha256',
+    SUPPORTED_HASH_ALGORITHMS: ['sha256', 'sha512'],
+    // Cache TTLs (seconds)
+    MANIFEST_CACHE_TTL: 300, // 5 minutes
+    FILE_CACHE_TTL: 31536000, // 1 year
+    // Update checking
+    UPDATE_CHECK_INTERVAL_HOURS: 24,
+    // Download retry
+    MAX_RETRIES: 5,
+    RETRY_DELAYS_MS: [1000, 2000, 4000, 8000, 16000],
+    // Storage
+    MIN_FREE_SPACE_MULTIPLIER: 2, // Need 2x compressed size free
+};
+/**
+ * Helper to generate filename for a database version
+ * Examples:
+ *   getBuiltInDbFilename("20250118a", true)  -> "duiduidui-20250118a.sqlite.gz"
+ *   getBuiltInDbFilename("20250118a", false) -> "duiduidui-20250118a.sqlite"
+ */
+function getBuiltInDbFilename(version, compressed = true) {
+    const base = `${exports.BUILTIN_DB_CONSTANTS.FILE_PREFIX}${version}${exports.BUILTIN_DB_CONSTANTS.FILE_EXTENSION}`;
+    return compressed ? `${base}.gz` : base;
+}

package/dist/util/index.d.ts

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

package/dist/util/index.js

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

package/package.json

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