vesper-memory 0.4.0 → 0.5.0

package/dist/scheduler/consolidation-scheduler.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Consolidation Scheduler
+ *
+ * Simple setInterval-based scheduler for nightly consolidation runs.
+ * Default schedule: 3 AM local time.
+ *
+ * Features:
+ * - Configurable schedule time
+ * - Manual trigger capability
+ * - Status reporting
+ * - Graceful shutdown
+ * - Error handling with callback notifications
+ */
+import { ConsolidationPipeline, ConsolidationStats } from '../consolidation/pipeline.js';
+/**
+ * Scheduler configuration options
+ */
+export interface SchedulerConfig {
+    /** Hour to run consolidation (0-23, default: 3) */
+    scheduleHour?: number;
+    /** Minute to run consolidation (0-59, default: 0) */
+    scheduleMinute?: number;
+    /** Timezone for scheduling (default: local timezone) */
+    timezone?: string;
+}
+/**
+ * Scheduler status information
+ */
+export interface SchedulerStatus {
+    /** Whether scheduler is currently running */
+    isRunning: boolean;
+    /** Configured schedule hour */
+    scheduleHour: number;
+    /** Configured schedule minute */
+    scheduleMinute: number;
+    /** Time of last consolidation run */
+    lastRunTime: Date | null;
+    /** Statistics from last run */
+    lastRunStats: ConsolidationStats | null;
+    /** Next scheduled run time */
+    nextRunTime: Date;
+    /** Total number of runs completed */
+    runCount: number;
+}
+/**
+ * Completion callback type
+ * Called after each consolidation run with stats or error
+ */
+export type CompletionCallback = (stats: ConsolidationStats | null, error: Error | null) => void;
+/**
+ * Consolidation Scheduler
+ *
+ * Manages scheduled nightly consolidation runs using setInterval.
+ * Calculates delay until next scheduled time and re-schedules after each run.
+ */
+export declare class ConsolidationScheduler {
+    private pipeline;
+    private config;
+    private callback?;
+    private timer;
+    private isRunning;
+    private lastRunTime;
+    private lastRunStats;
+    private runCount;
+    /**
+     * Create a new consolidation scheduler
+     *
+     * @param pipeline - ConsolidationPipeline instance to run
+     * @param config - Optional scheduler configuration
+     * @param callback - Optional completion callback
+     */
+    constructor(pipeline: ConsolidationPipeline, config?: SchedulerConfig, callback?: CompletionCallback);
+    /**
+     * Calculate the next scheduled run time
+     *
+     * @returns Date object for next scheduled run
+     */
+    getNextRunTime(): Date;
+    /**
+     * Get milliseconds until next scheduled run
+     *
+     * @returns Milliseconds until next run
+     */
+    getMsUntilNextRun(): number;
+    /**
+     * Start the scheduler
+     *
+     * Schedules the next consolidation run based on configured time.
+     * No-op if already running.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler
+     *
+     * Cancels any pending scheduled run.
+     * Safe to call even if not running.
+     */
+    stop(): void;
+    /**
+     * Run consolidation immediately (manual trigger)
+     *
+     * Does not affect scheduled runs.
+     *
+     * @returns Promise resolving to consolidation statistics
+     * @throws Error if consolidation fails
+     */
+    runNow(): Promise<ConsolidationStats>;
+    /**
+     * Get current scheduler status
+     *
+     * @returns SchedulerStatus object
+     */
+    getStatus(): SchedulerStatus;
+    /**
+     * Schedule the next consolidation run
+     * @private
+     */
+    private scheduleNextRun;
+}
+/**
+ * Factory function to create a scheduler
+ *
+ * @param pipeline - ConsolidationPipeline instance
+ * @param config - Optional scheduler configuration
+ * @param callback - Optional completion callback
+ * @returns ConsolidationScheduler instance
+ */
+export declare function createScheduler(pipeline: ConsolidationPipeline, config?: SchedulerConfig, callback?: CompletionCallback): ConsolidationScheduler;
+//# sourceMappingURL=consolidation-scheduler.d.ts.map

package/dist/scheduler/consolidation-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidation-scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/consolidation-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEzF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,+BAA+B;IAC/B,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,8BAA8B;IAC9B,WAAW,EAAE,IAAI,CAAC;IAClB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAChC,KAAK,EAAE,KAAK,GAAG,IAAI,KAChB,IAAI,CAAC;AAEV;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,MAAM,CAAsE;IACpF,OAAO,CAAC,QAAQ,CAAC,CAAqB;IACtC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,QAAQ,CAAK;IAErB;;;;;;OAMG;gBAED,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,GAAE,eAAoB,EAC5B,QAAQ,CAAC,EAAE,kBAAkB;IAW/B;;;;OAIG;IACH,cAAc,IAAI,IAAI;IActB;;;;OAIG;IACH,iBAAiB,IAAI,MAAM;IAM3B;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAab;;;;;OAKG;IACH,IAAI,IAAI,IAAI;IAUZ;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA+B3C;;;;OAIG;IACH,SAAS,IAAI,eAAe;IAY5B;;;OAGG;IACH,OAAO,CAAC,eAAe;CAqBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,sBAAsB,CAExB"}

package/dist/scheduler/consolidation-scheduler.js

@@ -0,0 +1,179 @@
+/**
+ * Consolidation Scheduler
+ *
+ * Simple setInterval-based scheduler for nightly consolidation runs.
+ * Default schedule: 3 AM local time.
+ *
+ * Features:
+ * - Configurable schedule time
+ * - Manual trigger capability
+ * - Status reporting
+ * - Graceful shutdown
+ * - Error handling with callback notifications
+ */
+/**
+ * Consolidation Scheduler
+ *
+ * Manages scheduled nightly consolidation runs using setInterval.
+ * Calculates delay until next scheduled time and re-schedules after each run.
+ */
+export class ConsolidationScheduler {
+    pipeline;
+    config;
+    callback;
+    timer = null;
+    isRunning = false;
+    lastRunTime = null;
+    lastRunStats = null;
+    runCount = 0;
+    /**
+     * Create a new consolidation scheduler
+     *
+     * @param pipeline - ConsolidationPipeline instance to run
+     * @param config - Optional scheduler configuration
+     * @param callback - Optional completion callback
+     */
+    constructor(pipeline, config = {}, callback) {
+        this.pipeline = pipeline;
+        this.config = {
+            scheduleHour: config.scheduleHour ?? 3,
+            scheduleMinute: config.scheduleMinute ?? 0,
+            timezone: config.timezone,
+        };
+        this.callback = callback;
+    }
+    /**
+     * Calculate the next scheduled run time
+     *
+     * @returns Date object for next scheduled run
+     */
+    getNextRunTime() {
+        const now = new Date();
+        const next = new Date(now);
+        next.setHours(this.config.scheduleHour, this.config.scheduleMinute, 0, 0);
+        // If we're past today's schedule time, schedule for tomorrow
+        if (next <= now) {
+            next.setDate(next.getDate() + 1);
+        }
+        return next;
+    }
+    /**
+     * Get milliseconds until next scheduled run
+     *
+     * @returns Milliseconds until next run
+     */
+    getMsUntilNextRun() {
+        const nextRun = this.getNextRunTime();
+        const now = new Date();
+        return nextRun.getTime() - now.getTime();
+    }
+    /**
+     * Start the scheduler
+     *
+     * Schedules the next consolidation run based on configured time.
+     * No-op if already running.
+     */
+    start() {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        this.scheduleNextRun();
+        console.error(`[SCHEDULER] Started. Next run at ${this.getNextRunTime().toISOString()}`);
+    }
+    /**
+     * Stop the scheduler
+     *
+     * Cancels any pending scheduled run.
+     * Safe to call even if not running.
+     */
+    stop() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.isRunning = false;
+        console.error('[SCHEDULER] Stopped');
+    }
+    /**
+     * Run consolidation immediately (manual trigger)
+     *
+     * Does not affect scheduled runs.
+     *
+     * @returns Promise resolving to consolidation statistics
+     * @throws Error if consolidation fails
+     */
+    async runNow() {
+        console.error('[SCHEDULER] Manual consolidation triggered');
+        try {
+            const stats = await this.pipeline.consolidate();
+            this.lastRunTime = new Date();
+            this.lastRunStats = stats;
+            this.runCount++;
+            if (this.callback) {
+                this.callback(stats, null);
+            }
+            console.error(`[SCHEDULER] Consolidation complete. Processed ${stats.memoriesProcessed} memories in ${stats.duration}ms`);
+            return stats;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (this.callback) {
+                this.callback(null, err);
+            }
+            console.error(`[SCHEDULER] Consolidation failed: ${err.message}`);
+            throw err;
+        }
+    }
+    /**
+     * Get current scheduler status
+     *
+     * @returns SchedulerStatus object
+     */
+    getStatus() {
+        return {
+            isRunning: this.isRunning,
+            scheduleHour: this.config.scheduleHour,
+            scheduleMinute: this.config.scheduleMinute,
+            lastRunTime: this.lastRunTime,
+            lastRunStats: this.lastRunStats,
+            nextRunTime: this.getNextRunTime(),
+            runCount: this.runCount,
+        };
+    }
+    /**
+     * Schedule the next consolidation run
+     * @private
+     */
+    scheduleNextRun() {
+        const msUntilRun = this.getMsUntilNextRun();
+        this.timer = setTimeout(async () => {
+            if (!this.isRunning) {
+                return;
+            }
+            try {
+                await this.runNow();
+            }
+            catch (error) {
+                // Error already logged and callback called in runNow
+                // Continue scheduling next run
+            }
+            // Schedule next run for tomorrow
+            if (this.isRunning) {
+                this.scheduleNextRun();
+            }
+        }, msUntilRun);
+    }
+}
+/**
+ * Factory function to create a scheduler
+ *
+ * @param pipeline - ConsolidationPipeline instance
+ * @param config - Optional scheduler configuration
+ * @param callback - Optional completion callback
+ * @returns ConsolidationScheduler instance
+ */
+export function createScheduler(pipeline, config, callback) {
+    return new ConsolidationScheduler(pipeline, config, callback);
+}
+//# sourceMappingURL=consolidation-scheduler.js.map

package/dist/scheduler/consolidation-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidation-scheduler.js","sourceRoot":"","sources":["../../src/scheduler/consolidation-scheduler.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Scheduler Module - Barrel Export
+ *
+ * Exports the consolidation scheduler for nightly memory consolidation.
+ */
+export { ConsolidationScheduler, SchedulerConfig, SchedulerStatus, CompletionCallback, createScheduler, } from './consolidation-scheduler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,GAChB,MAAM,8BAA8B,CAAC"}

package/dist/scheduler/index.js

@@ -0,0 +1,7 @@
+/**
+ * Scheduler Module - Barrel Export
+ *
+ * Exports the consolidation scheduler for nightly memory consolidation.
+ */
+export { ConsolidationScheduler, createScheduler, } from './consolidation-scheduler.js';
+//# sourceMappingURL=index.js.map

package/dist/scheduler/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,sBAAsB,EAItB,eAAe,GAChB,MAAM,8BAA8B,CAAC"}