@beeblock/svelar 0.4.0

package/dist/scheduler/ScheduleMonitor.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Schedule Monitor
+ *
+ * Utility for inspecting and managing scheduled tasks from the admin dashboard.
+ * Tracks task execution history, health metrics, and provides task management
+ * capabilities.
+ *
+ * @example
+ * ```ts
+ * import { ScheduleMonitor } from 'svelar/scheduler';
+ *
+ * // Configure with your scheduler instance
+ * ScheduleMonitor.configure(scheduler);
+ *
+ * // List all tasks with their status
+ * const tasks = ScheduleMonitor.listTasks();
+ *
+ * // Get health metrics
+ * const health = ScheduleMonitor.getHealth();
+ *
+ * // Manually run a task
+ * await ScheduleMonitor.runTask('SendDailyReport');
+ *
+ * // Toggle task enabled state
+ * ScheduleMonitor.disableTask('SendDailyReport');
+ * ```
+ */
+import type { Scheduler } from './index.js';
+export interface TaskRunRecord {
+    /** When the task was run */
+    timestamp: Date;
+    /** Whether execution succeeded */
+    success: boolean;
+    /** How long the task took (ms) */
+    duration: number;
+    /** Error message if failed */
+    error?: string;
+}
+export interface TaskInfo {
+    /** Task name */
+    name: string;
+    /** Cron expression */
+    expression: string;
+    /** Human-readable schedule description */
+    humanReadable: string;
+    /** Next scheduled run time */
+    nextRun: Date;
+    /** Last execution timestamp */
+    lastRun?: Date;
+    /** Duration of last execution (ms) */
+    lastDuration?: number;
+    /** Success/failure status of last run */
+    lastStatus?: 'success' | 'failed';
+    /** Whether the task is enabled */
+    enabled: boolean;
+    /** Whether the task is currently running */
+    isRunning: boolean;
+    /** Recent execution history */
+    history: TaskRunRecord[];
+}
+export interface SchedulerHealth {
+    /** Total registered tasks */
+    totalTasks: number;
+    /** Number of enabled tasks */
+    enabledTasks: number;
+    /** Number of currently running tasks */
+    runningTasks: number;
+    /** Recent errors */
+    lastErrors: Array<{
+        task: string;
+        error: string;
+        timestamp: Date;
+    }>;
+    /** Scheduler uptime in milliseconds */
+    uptime: number;
+}
+declare class ScheduleMonitorService {
+    private scheduler;
+    private startTime;
+    private taskEnabled;
+    /**
+     * Configure the monitor with a scheduler instance
+     */
+    configure(scheduler: Scheduler): void;
+    /**
+     * List all registered tasks with their current status.
+     * Reads run history from the database so all processes (CLI, web) share the same data.
+     */
+    listTasks(): Promise<TaskInfo[]>;
+    /**
+     * Get info for a specific task by name
+     */
+    getTask(name: string): Promise<TaskInfo | null>;
+    /**
+     * Enable a task
+     */
+    enableTask(name: string): void;
+    /**
+     * Disable a task
+     */
+    disableTask(name: string): void;
+    /**
+     * Manually trigger a task to run (if not disabled).
+     * Persists the result to the database.
+     */
+    runTask(name: string): Promise<void>;
+    /**
+     * Get execution history for a task from the database
+     */
+    getTaskHistory(name: string, limit?: number): Promise<TaskRunRecord[]>;
+    /**
+     * Get overall scheduler health metrics
+     */
+    getHealth(): Promise<SchedulerHealth>;
+    /**
+     * Load task run history from the database.
+     * Single query fetches the latest N records per task.
+     */
+    private loadHistoryFromDb;
+    /**
+     * Persist a task result to the database
+     */
+    private persistResult;
+    /**
+     * Create a TaskInfo object from a ScheduledTask and its DB history
+     */
+    private createTaskInfo;
+    /**
+     * Convert a cron expression to a human-readable description
+     */
+    private humanizeExpression;
+    /**
+     * Calculate the next run time for a task given its cron expression
+     */
+    private getNextRun;
+}
+/**
+ * Export as a singleton instance
+ */
+export declare const ScheduleMonitor: ScheduleMonitorService;
+export {};

package/dist/scheduler/ScheduleMonitor.js

@@ -0,0 +1 @@
+var v=Object.defineProperty;var g=(c,t)=>()=>(c&&(t=c(c=0)),t);var R=(c,t)=>{for(var e in t)v(c,e,{get:t[e],enumerable:!0})};import{hostname as S}from"os";var C,k=g(()=>{"use strict";C=`${S()}:${process.pid}:${Math.random().toString(36).slice(2,10)}`});function d(c,t){let e=Symbol.for(c),s=globalThis;return s[e]||(s[e]=t()),s[e]}var T=g(()=>{"use strict"});var m={};R(m,{Connection:()=>D});var f,D,p=g(()=>{"use strict";T();f=class{connections=new Map;config=null;defaultName="default";configure(t){this.config=t,this.defaultName=t.default}async connection(t){let e=t??this.defaultName;if(this.connections.has(e))return this.connections.get(e).drizzle;if(!this.config)throw new Error("Database not configured. Call Connection.configure() first, or register DatabaseServiceProvider.");let s=this.config.connections[e];if(!s)throw new Error(`Database connection "${e}" is not defined in configuration.`);let n=await this.createConnection(s);return this.connections.set(e,n),n.drizzle}async rawClient(t){let e=t??this.defaultName;return await this.connection(e),this.connections.get(e).rawClient}async raw(t,e=[],s){let n=await this.connection(s),r=this.getConfig(s);switch(r.driver){case"sqlite":{let i=await this.rawClient(s),o=e.map(l=>typeof l=="boolean"?l?1:0:l instanceof Date?l.toISOString():l),a=i.prepare(t),u=t.trimStart().toUpperCase();return u.startsWith("SELECT")||u.startsWith("PRAGMA")||u.startsWith("WITH")?a.all(...o):a.run(...o)}case"postgres":return(await this.rawClient(s))(t,...e);case"mysql":{let i=await this.rawClient(s),[o]=await i.execute(t,e);return o}default:throw new Error(`Unsupported driver: ${r.driver}`)}}getDriver(t){return this.getConfig(t).driver}getConfig(t){let e=t??this.defaultName;if(!this.config)throw new Error("Database not configured.");let s=this.config.connections[e];if(!s)throw new Error(`Database connection "${e}" is not defined.`);return s}async disconnect(t){if(t){let e=this.connections.get(t);e&&(await this.closeConnection(e),this.connections.delete(t))}else{for(let[e,s]of this.connections)await this.closeConnection(s);this.connections.clear()}}isConnected(t){return this.connections.has(t??this.defaultName)}async transaction(t,e){let s=this.getConfig(e),n=await this.rawClient(e);switch(s.driver){case"sqlite":{n.exec("BEGIN");try{let r=await t();return n.exec("COMMIT"),r}catch(r){throw n.exec("ROLLBACK"),r}}case"postgres":{await n`BEGIN`;try{let r=await t();return await n`COMMIT`,r}catch(r){throw await n`ROLLBACK`,r}}case"mysql":{let r=await n.getConnection();await r.beginTransaction();try{let i=await t();return await r.commit(),r.release(),i}catch(i){throw await r.rollback(),r.release(),i}}default:throw new Error(`Unsupported driver: ${s.driver}`)}}async createConnection(t){switch(t.driver){case"sqlite":return this.createSQLiteConnection(t);case"postgres":return this.createPostgresConnection(t);case"mysql":return this.createMySQLConnection(t);default:throw new Error(`Unsupported database driver: ${t.driver}`)}}async createSQLiteConnection(t){let e=t.filename??t.database??":memory:";try{let s=(await import("better-sqlite3")).default,{drizzle:n}=await import("drizzle-orm/better-sqlite3"),r=new s(e);return r.pragma("journal_mode = WAL"),r.pragma("foreign_keys = ON"),{drizzle:n(r),config:t,rawClient:r}}catch(s){let n;try{n=(await new Function("mod","return import(mod)")("node:sqlite")).DatabaseSync}catch{throw new Error(`No SQLite driver available. Install better-sqlite3 (npm install better-sqlite3) or use Node.js v22+ which includes built-in SQLite support. Original error: ${s instanceof Error?s.message:String(s)}`)}let r=new n(e);r.exec("PRAGMA journal_mode = WAL"),r.exec("PRAGMA foreign_keys = ON");let i={prepare(a){let u=r.prepare(a);return{all(...l){return u.all(...l)},run(...l){return u.run(...l)},get(...l){return u.get(...l)}}},exec(a){r.exec(a)},pragma(a){return r.prepare(`PRAGMA ${a}`).all()},close(){r.close()}},o;try{let{drizzle:a}=await import("drizzle-orm/better-sqlite3");o=a(i)}catch{o=i}return{drizzle:o,config:t,rawClient:i}}}async createPostgresConnection(t){let e=(await import("postgres")).default,{drizzle:s}=await import("drizzle-orm/postgres-js"),n=t.url??`postgres://${t.user}:${t.password}@${t.host??"localhost"}:${t.port??5432}/${t.database}`,r=e(n);return{drizzle:s(r),config:t,rawClient:r}}async createMySQLConnection(t){let e=await import("mysql2/promise"),{drizzle:s}=await import("drizzle-orm/mysql2"),n=e.createPool({host:t.host??"localhost",port:t.port??3306,database:t.database,user:t.user,password:t.password,uri:t.url});return{drizzle:s(n),config:t,rawClient:n}}async closeConnection(t){try{switch(t.config.driver){case"sqlite":t.rawClient.close();break;case"postgres":await t.rawClient.end();break;case"mysql":await t.rawClient.end();break}}catch{}}},D=d("svelar.connection",()=>new f)});k();function h(c,t,e){if(c==="*")return null;let s=new Set;for(let n of c.split(",")){let[r,i]=n.split("/"),o=i?parseInt(i,10):1;if(r==="*")for(let a=t;a<=e;a+=o)s.add(a);else if(r.includes("-")){let[a,u]=r.split("-"),l=parseInt(a,10),b=parseInt(u,10);for(let w=l;w<=b;w+=o)s.add(w)}else s.add(parseInt(r,10))}return[...s].sort((n,r)=>n-r)}function I(c){let t=c.trim().split(/\s+/);if(t.length!==5)throw new Error(`Invalid cron expression: "${c}". Expected 5 fields.`);return{minute:h(t[0],0,59),hour:h(t[1],0,23),dayOfMonth:h(t[2],1,31),month:h(t[3],1,12),dayOfWeek:h(t[4],0,6)}}function E(c,t){let e=I(c),s=t.getMinutes(),n=t.getHours(),r=t.getDate(),i=t.getMonth()+1,o=t.getDay();return!(e.minute&&!e.minute.includes(s)||e.hour&&!e.hour.includes(n)||e.dayOfMonth&&!e.dayOfMonth.includes(r)||e.month&&!e.month.includes(i)||e.dayOfWeek&&!e.dayOfWeek.includes(o))}T();var y=class{scheduler=null;startTime=new Date;taskEnabled=new Map;configure(t){this.scheduler=t,this.startTime=new Date;for(let e of t.getTasks())this.taskEnabled.has(e.name)||this.taskEnabled.set(e.name,!0)}async listTasks(){if(!this.scheduler)return[];let t=this.scheduler.getTasks(),e=await this.loadHistoryFromDb(t.map(s=>s.name));return t.map(s=>this.createTaskInfo(s,e.get(s.name)||[]))}async getTask(t){if(!this.scheduler)return null;let e=this.scheduler.getTasks().find(n=>n.name===t);if(!e)return null;let s=await this.loadHistoryFromDb([t]);return this.createTaskInfo(e,s.get(t)||[])}enableTask(t){this.taskEnabled.set(t,!0)}disableTask(t){this.taskEnabled.set(t,!1)}async runTask(t){if(!this.scheduler)throw new Error("Scheduler not configured");if(this.taskEnabled.has(t)&&!this.taskEnabled.get(t))throw new Error(`Task "${t}" is disabled`);let e=this.scheduler.getTasks().find(n=>n.name===t);if(!e)throw new Error(`Task "${t}" not found`);let s=await e.executeTask();await this.persistResult(s).catch(()=>{})}async getTaskHistory(t,e=10){return(await this.loadHistoryFromDb([t],e)).get(t)||[]}async getHealth(){if(!this.scheduler)return{totalTasks:0,enabledTasks:0,runningTasks:0,lastErrors:[],uptime:0};let t=this.scheduler.getTasks(),e=t.filter(i=>!this.taskEnabled.has(i.name)||this.taskEnabled.get(i.name)).length,s=t.filter(i=>i.isRunning()).length,n=[];try{let{Connection:i}=await Promise.resolve().then(()=>(p(),m)),o=await i.raw("SELECT task, error, ran_at FROM scheduled_task_runs WHERE error IS NOT NULL ORDER BY ran_at DESC LIMIT 10");for(let a of o)n.push({task:a.task,error:a.error,timestamp:new Date(a.ran_at)})}catch{}let r=Date.now()-this.startTime.getTime();return{totalTasks:t.length,enabledTasks:e,runningTasks:s,lastErrors:n,uptime:r}}async loadHistoryFromDb(t,e=20){let s=new Map;if(t.length===0)return s;try{let{Connection:n}=await Promise.resolve().then(()=>(p(),m)),r=t.map(()=>"?").join(", "),i=await n.raw(`SELECT task, success, duration, error, ran_at FROM scheduled_task_runs WHERE task IN (${r}) ORDER BY ran_at DESC LIMIT ?`,[...t,t.length*e]);for(let o of i){s.has(o.task)||s.set(o.task,[]);let a=s.get(o.task);a.length<e&&a.push({timestamp:new Date(o.ran_at),success:!!o.success,duration:o.duration,error:o.error||void 0})}}catch{}return s}async persistResult(t){let{Connection:e}=await Promise.resolve().then(()=>(p(),m));await e.raw("INSERT INTO scheduled_task_runs (task, success, duration, error, ran_at) VALUES (?, ?, ?, ?, ?)",[t.task,t.success,t.duration,t.error||null,t.timestamp.toISOString()])}createTaskInfo(t,e){let s=t.getExpression(),n=e.length>0?e[0]:null,r=!this.taskEnabled.has(t.name)||this.taskEnabled.get(t.name)===!0;return{name:t.name,expression:s,humanReadable:this.humanizeExpression(s),nextRun:this.getNextRun(s),lastRun:n?.timestamp,lastDuration:n?.duration,lastStatus:n?.success?"success":"failed",enabled:r,isRunning:t.isRunning(),history:e.slice(0,5)}}humanizeExpression(t){let e=t.trim().split(/\s+/);if(e.length!==5)return t;let[s,n,r,i,o]=e;if(t==="* * * * *")return"Every minute";if(t==="*/5 * * * *")return"Every 5 minutes";if(t==="*/10 * * * *")return"Every 10 minutes";if(t==="*/15 * * * *")return"Every 15 minutes";if(t==="*/30 * * * *")return"Every 30 minutes";if(t==="0 * * * *")return"Every hour";if(t==="0 0 * * *")return"Daily at midnight";if(t==="0 0 * * 0")return"Weekly (Sunday at midnight)";if(t==="0 0 1 * *")return"Monthly (1st at midnight)";if(t==="0 0 1 1 *")return"Yearly (Jan 1st at midnight)";if(r==="*"&&i==="*"&&o==="*"&&n!=="*"&&s!=="*"){let a=parseInt(n,10),u=parseInt(s,10);return`Daily at ${a.toString().padStart(2,"0")}:${u.toString().padStart(2,"0")}`}if(o==="1-5"&&r==="*"&&i==="*"&&n!=="*"&&s!=="*"){let a=parseInt(n,10),u=parseInt(s,10);return`Weekdays at ${a.toString().padStart(2,"0")}:${u.toString().padStart(2,"0")}`}return t}getNextRun(t){let e=new Date,s=new Date(e);s.setSeconds(0),s.setMilliseconds(0),s.setMinutes(s.getMinutes()+1);let n=366*24*60,r=0;for(;r<n;){if(E(t,s))return s;s.setMinutes(s.getMinutes()+1),r++}return e}},z=d("svelar.scheduleMonitor",()=>new y);export{z as ScheduleMonitor};

package/dist/scheduler/SchedulerLock.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Distributed Scheduler Lock
+ *
+ * Database-backed distributed locking for scheduled tasks.
+ * Prevents duplicate task execution across multiple scheduler instances.
+ * Supports SQLite, PostgreSQL, and MySQL via the Connection abstraction.
+ *
+ * The `scheduler_locks` table is auto-created on first use.
+ */
+export declare class SchedulerLock {
+    /**
+     * Get the unique owner ID for this process.
+     */
+    static getOwnerId(): string;
+    /**
+     * Ensure the scheduler_locks table exists (auto-created on first use).
+     */
+    static ensureTable(): Promise<void>;
+    /**
+     * Try to acquire a distributed lock for a task.
+     * Returns true if the lock was acquired, false if another process holds it.
+     */
+    static acquire(taskKey: string, ttlMinutes?: number): Promise<boolean>;
+    /**
+     * Release a lock (only if this process owns it).
+     */
+    static release(taskKey: string): Promise<void>;
+    /**
+     * Release all locks held by this process.
+     * Called during graceful shutdown.
+     */
+    static releaseAll(): Promise<void>;
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Svelar Task Scheduler
+ *
+ * Laravel-inspired task scheduler with cron expressions.
+ * Schedule recurring tasks, chain operations, and manage
+ * background work.
+ *
+ * @example
+ * ```ts
+ * import { Scheduler, ScheduledTask } from 'svelar/scheduler';
+ *
+ * // Define tasks
+ * class PruneExpiredTokens extends ScheduledTask {
+ *   schedule() { return this.daily(); }
+ *
+ *   async handle(): Promise<void> {
+ *     await Connection.raw(
+ *       'DELETE FROM tokens WHERE expires_at < ?',
+ *       [new Date().toISOString()]
+ *     );
+ *   }
+ * }
+ *
+ * class SendDailyReport extends ScheduledTask {
+ *   schedule() { return this.dailyAt('09:00'); }
+ *
+ *   async handle(): Promise<void> {
+ *     const users = await User.count();
+ *     await Mailer.send({ to: 'admin@example.com', body: `Users: ${users}` });
+ *   }
+ * }
+ *
+ * // Register tasks
+ * const scheduler = new Scheduler();
+ * scheduler.register(new PruneExpiredTokens());
+ * scheduler.register(new SendDailyReport());
+ *
+ * // Run the scheduler (call every minute, e.g., via cron or setInterval)
+ * await scheduler.run();
+ *
+ * // Or start the built-in ticker
+ * scheduler.start();
+ * ```
+ */
+interface CronFields {
+    minute: number[] | null;
+    hour: number[] | null;
+    dayOfMonth: number[] | null;
+    month: number[] | null;
+    dayOfWeek: number[] | null;
+}
+declare function parseCron(expression: string): CronFields;
+declare function cronMatches(expression: string, date: Date): boolean;
+export interface TaskSchedule {
+    expression: string;
+    timezone?: string;
+    withoutOverlapping?: boolean;
+    onSuccess?: () => void | Promise<void>;
+    onFailure?: (error: Error) => void | Promise<void>;
+}
+export interface TaskResult {
+    task: string;
+    success: boolean;
+    duration: number;
+    error?: string;
+    timestamp: Date;
+}
+export declare abstract class ScheduledTask {
+    /** Task name (defaults to class name) */
+    name: string;
+    /** Whether this task is currently running */
+    private _running;
+    /** Whether to prevent overlapping execution */
+    protected withoutOverlapping: boolean;
+    /** Lock TTL in minutes for distributed locking (default: 5) */
+    protected _lockTtlMinutes: number;
+    /** The cron expression */
+    private _expression;
+    /**
+     * Define the schedule for this task.
+     * Return `this` after calling a scheduling method.
+     */
+    schedule(): this;
+    /**
+     * The task logic — override this.
+     */
+    abstract handle(): Promise<void>;
+    /**
+     * Called when the task succeeds
+     */
+    onSuccess(): void | Promise<void>;
+    /**
+     * Called when the task fails
+     */
+    onFailure(error: Error): void | Promise<void>;
+    /** Run every minute */
+    everyMinute(): this;
+    /** Run every N minutes */
+    everyMinutes(n: number): this;
+    /** Run every 5 minutes */
+    everyFiveMinutes(): this;
+    /** Run every 10 minutes */
+    everyTenMinutes(): this;
+    /** Run every 15 minutes */
+    everyFifteenMinutes(): this;
+    /** Run every 30 minutes */
+    everyThirtyMinutes(): this;
+    /** Run every hour */
+    hourly(): this;
+    /** Run every hour at a specific minute */
+    hourlyAt(minute: number): this;
+    /** Run every day at midnight */
+    daily(): this;
+    /** Run every day at a specific time (HH:MM) */
+    dailyAt(time: string): this;
+    /** Run twice daily at specific hours */
+    twiceDaily(hour1?: number, hour2?: number): this;
+    /** Run every week (Sunday at midnight) */
+    weekly(): this;
+    /** Run on a specific day and time */
+    weeklyOn(day: number, time?: string): this;
+    /** Run on weekdays (Mon-Fri) */
+    weekdays(): this;
+    /** Run on weekends (Sat-Sun) */
+    weekends(): this;
+    /** Run monthly (1st at midnight) */
+    monthly(): this;
+    /** Run monthly on a specific day and time */
+    monthlyOn(day: number, time?: string): this;
+    /** Run quarterly (1st of Jan, Apr, Jul, Oct) */
+    quarterly(): this;
+    /** Run yearly (Jan 1st at midnight) */
+    yearly(): this;
+    /** Set a custom cron expression */
+    cron(expression: string): this;
+    /** Prevent overlapping execution (uses distributed lock across processes) */
+    preventOverlap(): this;
+    /** Set the distributed lock TTL (default: 5 minutes). If a task takes longer, increase this. */
+    lockExpiresAfter(minutes: number): this;
+    /** @internal */
+    getExpression(): string;
+    /** @internal */
+    isRunning(): boolean;
+    /** @internal */
+    executeTask(): Promise<TaskResult>;
+}
+export declare class Scheduler {
+    private tasks;
+    private timer;
+    private history;
+    private maxHistory;
+    private _persistToDb;
+    /**
+     * Enable database persistence for task run history.
+     * Requires the `scheduled_task_runs` table to exist.
+     */
+    persistToDatabase(): this;
+    /**
+     * Register a scheduled task
+     */
+    register(task: ScheduledTask): this;
+    /**
+     * Register multiple tasks
+     */
+    registerMany(tasks: ScheduledTask[]): this;
+    /**
+     * Run all due tasks (call this every minute)
+     */
+    run(now?: Date): Promise<TaskResult[]>;
+    /**
+     * Start the scheduler, aligned to the top of each minute like crontab.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler and release all distributed locks held by this process.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get all registered tasks
+     */
+    getTasks(): ScheduledTask[];
+    /**
+     * Get task execution history (in-memory)
+     */
+    getHistory(): TaskResult[];
+    /**
+     * Check which tasks are due right now
+     */
+    dueTasks(now?: Date): ScheduledTask[];
+    /**
+     * Remove a task by name
+     */
+    remove(name: string): boolean;
+    /**
+     * Clear all tasks
+     */
+    clear(): void;
+    private addToHistory;
+    private _historyTableEnsured;
+    private ensureHistoryTable;
+    private persistResult;
+}
+/**
+ * Create a scheduled task from a simple function
+ */
+export declare function task(name: string, handler: () => Promise<void>, scheduleConfig?: (task: ScheduledTask) => void): ScheduledTask;
+export { parseCron, cronMatches };
+export { SchedulerLock } from './SchedulerLock.js';

package/dist/scheduler/index.js

@@ -0,0 +1,34 @@
+var R=Object.defineProperty;var E=(a,t)=>()=>(a&&(t=a(a=0)),t);var b=(a,t)=>{for(var e in t)R(a,e,{get:t[e],enumerable:!0})};function N(a,t){let e=Symbol.for(a),s=globalThis;return s[e]||(s[e]=t()),s[e]}var C=E(()=>{"use strict"});var m={};b(m,{Connection:()=>A});var k,A,T=E(()=>{"use strict";C();k=class{connections=new Map;config=null;defaultName="default";configure(t){this.config=t,this.defaultName=t.default}async connection(t){let e=t??this.defaultName;if(this.connections.has(e))return this.connections.get(e).drizzle;if(!this.config)throw new Error("Database not configured. Call Connection.configure() first, or register DatabaseServiceProvider.");let s=this.config.connections[e];if(!s)throw new Error(`Database connection "${e}" is not defined in configuration.`);let n=await this.createConnection(s);return this.connections.set(e,n),n.drizzle}async rawClient(t){let e=t??this.defaultName;return await this.connection(e),this.connections.get(e).rawClient}async raw(t,e=[],s){let n=await this.connection(s),r=this.getConfig(s);switch(r.driver){case"sqlite":{let i=await this.rawClient(s),c=e.map(u=>typeof u=="boolean"?u?1:0:u instanceof Date?u.toISOString():u),o=i.prepare(t),l=t.trimStart().toUpperCase();return l.startsWith("SELECT")||l.startsWith("PRAGMA")||l.startsWith("WITH")?o.all(...c):o.run(...c)}case"postgres":return(await this.rawClient(s))(t,...e);case"mysql":{let i=await this.rawClient(s),[c]=await i.execute(t,e);return c}default:throw new Error(`Unsupported driver: ${r.driver}`)}}getDriver(t){return this.getConfig(t).driver}getConfig(t){let e=t??this.defaultName;if(!this.config)throw new Error("Database not configured.");let s=this.config.connections[e];if(!s)throw new Error(`Database connection "${e}" is not defined.`);return s}async disconnect(t){if(t){let e=this.connections.get(t);e&&(await this.closeConnection(e),this.connections.delete(t))}else{for(let[e,s]of this.connections)await this.closeConnection(s);this.connections.clear()}}isConnected(t){return this.connections.has(t??this.defaultName)}async transaction(t,e){let s=this.getConfig(e),n=await this.rawClient(e);switch(s.driver){case"sqlite":{n.exec("BEGIN");try{let r=await t();return n.exec("COMMIT"),r}catch(r){throw n.exec("ROLLBACK"),r}}case"postgres":{await n`BEGIN`;try{let r=await t();return await n`COMMIT`,r}catch(r){throw await n`ROLLBACK`,r}}case"mysql":{let r=await n.getConnection();await r.beginTransaction();try{let i=await t();return await r.commit(),r.release(),i}catch(i){throw await r.rollback(),r.release(),i}}default:throw new Error(`Unsupported driver: ${s.driver}`)}}async createConnection(t){switch(t.driver){case"sqlite":return this.createSQLiteConnection(t);case"postgres":return this.createPostgresConnection(t);case"mysql":return this.createMySQLConnection(t);default:throw new Error(`Unsupported database driver: ${t.driver}`)}}async createSQLiteConnection(t){let e=t.filename??t.database??":memory:";try{let s=(await import("better-sqlite3")).default,{drizzle:n}=await import("drizzle-orm/better-sqlite3"),r=new s(e);return r.pragma("journal_mode = WAL"),r.pragma("foreign_keys = ON"),{drizzle:n(r),config:t,rawClient:r}}catch(s){let n;try{n=(await new Function("mod","return import(mod)")("node:sqlite")).DatabaseSync}catch{throw new Error(`No SQLite driver available. Install better-sqlite3 (npm install better-sqlite3) or use Node.js v22+ which includes built-in SQLite support. Original error: ${s instanceof Error?s.message:String(s)}`)}let r=new n(e);r.exec("PRAGMA journal_mode = WAL"),r.exec("PRAGMA foreign_keys = ON");let i={prepare(o){let l=r.prepare(o);return{all(...u){return l.all(...u)},run(...u){return l.run(...u)},get(...u){return l.get(...u)}}},exec(o){r.exec(o)},pragma(o){return r.prepare(`PRAGMA ${o}`).all()},close(){r.close()}},c;try{let{drizzle:o}=await import("drizzle-orm/better-sqlite3");c=o(i)}catch{c=i}return{drizzle:c,config:t,rawClient:i}}}async createPostgresConnection(t){let e=(await import("postgres")).default,{drizzle:s}=await import("drizzle-orm/postgres-js"),n=t.url??`postgres://${t.user}:${t.password}@${t.host??"localhost"}:${t.port??5432}/${t.database}`,r=e(n);return{drizzle:s(r),config:t,rawClient:r}}async createMySQLConnection(t){let e=await import("mysql2/promise"),{drizzle:s}=await import("drizzle-orm/mysql2"),n=e.createPool({host:t.host??"localhost",port:t.port??3306,database:t.database,user:t.user,password:t.password,uri:t.url});return{drizzle:s(n),config:t,rawClient:n}}async closeConnection(t){try{switch(t.config.driver){case"sqlite":t.rawClient.close();break;case"postgres":await t.rawClient.end();break;case"mysql":await t.rawClient.end();break}}catch{}}},A=N("svelar.connection",()=>new k)});var g={};b(g,{SchedulerLock:()=>y});import{hostname as L}from"os";async function d(){let{Connection:a}=await Promise.resolve().then(()=>(T(),m));return a}async function D(){return(await d()).getDriver()}var _,h,y,p=E(()=>{"use strict";_=!1,h=`${L()}:${process.pid}:${Math.random().toString(36).slice(2,10)}`;y=class{static getOwnerId(){return h}static async ensureTable(){if(_)return;let t=await d();switch(t.getDriver()){case"sqlite":await t.raw(`CREATE TABLE IF NOT EXISTS scheduler_locks (
+            task_key TEXT PRIMARY KEY,
+            owner TEXT NOT NULL,
+            expires_at TEXT NOT NULL
+          )`);break;case"postgres":await t.raw(`CREATE TABLE IF NOT EXISTS scheduler_locks (
+            task_key VARCHAR(255) PRIMARY KEY,
+            owner VARCHAR(255) NOT NULL,
+            expires_at TIMESTAMPTZ NOT NULL
+          )`);break;case"mysql":await t.raw(`CREATE TABLE IF NOT EXISTS scheduler_locks (
+            task_key VARCHAR(255) PRIMARY KEY,
+            owner VARCHAR(255) NOT NULL,
+            expires_at DATETIME NOT NULL
+          ) ENGINE=InnoDB`);break}_=!0}static async acquire(t,e=5){await this.ensureTable();let s=await d(),n=await D(),r=new Date().toISOString(),i=new Date(Date.now()+e*6e4).toISOString();try{await s.transaction(async()=>{switch(await s.raw("DELETE FROM scheduler_locks WHERE task_key = ? AND expires_at < ?",[t,r]),n){case"sqlite":await s.raw("INSERT OR IGNORE INTO scheduler_locks (task_key, owner, expires_at) VALUES (?, ?, ?)",[t,h,i]);break;case"postgres":await s.raw("INSERT INTO scheduler_locks (task_key, owner, expires_at) VALUES ($1, $2, $3) ON CONFLICT (task_key) DO NOTHING",[t,h,i]);break;case"mysql":await s.raw("INSERT IGNORE INTO scheduler_locks (task_key, owner, expires_at) VALUES (?, ?, ?)",[t,h,i]);break}});let c=await s.raw("SELECT owner FROM scheduler_locks WHERE task_key = ?",[t]);return c.length>0&&c[0].owner===h}catch{return!1}}static async release(t){try{await(await d()).raw("DELETE FROM scheduler_locks WHERE task_key = ? AND owner = ?",[t,h])}catch{}}static async releaseAll(){try{await(await d()).raw("DELETE FROM scheduler_locks WHERE owner = ?",[h])}catch{}}}});p();function w(a,t,e){if(a==="*")return null;let s=new Set;for(let n of a.split(",")){let[r,i]=n.split("/"),c=i?parseInt(i,10):1;if(r==="*")for(let o=t;o<=e;o+=c)s.add(o);else if(r.includes("-")){let[o,l]=r.split("-"),u=parseInt(o,10),S=parseInt(l,10);for(let f=u;f<=S;f+=c)s.add(f)}else s.add(parseInt(r,10))}return[...s].sort((n,r)=>n-r)}function x(a){let t=a.trim().split(/\s+/);if(t.length!==5)throw new Error(`Invalid cron expression: "${a}". Expected 5 fields.`);return{minute:w(t[0],0,59),hour:w(t[1],0,23),dayOfMonth:w(t[2],1,31),month:w(t[3],1,12),dayOfWeek:w(t[4],0,6)}}function I(a,t){let e=x(a),s=t.getMinutes(),n=t.getHours(),r=t.getDate(),i=t.getMonth()+1,c=t.getDay();return!(e.minute&&!e.minute.includes(s)||e.hour&&!e.hour.includes(n)||e.dayOfMonth&&!e.dayOfMonth.includes(r)||e.month&&!e.month.includes(i)||e.dayOfWeek&&!e.dayOfWeek.includes(c))}var v=class{name=this.constructor.name;_running=!1;withoutOverlapping=!1;_lockTtlMinutes=5;_expression="* * * * *";schedule(){return this}onSuccess(){}onFailure(t){console.error(`[Scheduler] Task "${this.name}" failed:`,t.message)}everyMinute(){return this._expression="* * * * *",this}everyMinutes(t){return this._expression=`*/${t} * * * *`,this}everyFiveMinutes(){return this.everyMinutes(5)}everyTenMinutes(){return this.everyMinutes(10)}everyFifteenMinutes(){return this.everyMinutes(15)}everyThirtyMinutes(){return this.everyMinutes(30)}hourly(){return this._expression="0 * * * *",this}hourlyAt(t){return this._expression=`${t} * * * *`,this}daily(){return this._expression="0 0 * * *",this}dailyAt(t){let[e,s]=t.split(":").map(Number);return this._expression=`${s??0} ${e} * * *`,this}twiceDaily(t=1,e=13){return this._expression=`0 ${t},${e} * * *`,this}weekly(){return this._expression="0 0 * * 0",this}weeklyOn(t,e="00:00"){let[s,n]=e.split(":").map(Number);return this._expression=`${n??0} ${s} * * ${t}`,this}weekdays(){return this._expression=`${this._expression.split(" ").slice(0,4).join(" ")} 1-5`,this}weekends(){return this._expression=`${this._expression.split(" ").slice(0,4).join(" ")} 0,6`,this}monthly(){return this._expression="0 0 1 * *",this}monthlyOn(t,e="00:00"){let[s,n]=e.split(":").map(Number);return this._expression=`${n??0} ${s} ${t} * *`,this}quarterly(){return this._expression="0 0 1 1,4,7,10 *",this}yearly(){return this._expression="0 0 1 1 *",this}cron(t){return this._expression=t,this}preventOverlap(){return this.withoutOverlapping=!0,this}lockExpiresAfter(t){return this._lockTtlMinutes=t,this}getExpression(){return this.schedule(),this._expression}isRunning(){return this._running}async executeTask(){if(this.withoutOverlapping&&this._running)return{task:this.name,success:!0,duration:0,timestamp:new Date};let t=!1;if(this.withoutOverlapping)try{let{SchedulerLock:s}=await Promise.resolve().then(()=>(p(),g));if(t=await s.acquire(this.name,this._lockTtlMinutes),!t)return{task:this.name,success:!0,duration:0,timestamp:new Date}}catch{}this._running=!0;let e=Date.now();try{await this.handle();let s=Date.now()-e;return await this.onSuccess(),{task:this.name,success:!0,duration:s,timestamp:new Date}}catch(s){let n=Date.now()-e;return await this.onFailure(s),{task:this.name,success:!1,duration:n,error:s.message,timestamp:new Date}}finally{if(this._running=!1,t)try{let{SchedulerLock:s}=await Promise.resolve().then(()=>(p(),g));await s.release(this.name)}catch{}}}},O=class{tasks=[];timer=null;history=[];maxHistory=100;_persistToDb=!1;persistToDatabase(){return this._persistToDb=!0,this}register(t){return this.tasks.push(t),this}registerMany(t){for(let e of t)this.register(e);return this}async run(t){let e=t??new Date,s=[];for(let n of this.tasks){let r=n.getExpression();if(I(r,e)){let i=await n.executeTask();s.push(i),this.addToHistory(i)}}return s}start(){if(this.timer)return;this.run().catch(s=>console.error("[Scheduler] Error:",s));let e=6e4-Date.now()%6e4;this.timer=setTimeout(()=>{this.run().catch(s=>console.error("[Scheduler] Error:",s)),this.timer=setInterval(()=>{this.run().catch(s=>console.error("[Scheduler] Error:",s))},6e4)},e),console.log(`[Scheduler] Started with ${this.tasks.length} task(s). Next tick in ${Math.round(e/1e3)}s.`)}async stop(){this.timer&&(clearTimeout(this.timer),clearInterval(this.timer),this.timer=null);try{let{SchedulerLock:t}=await Promise.resolve().then(()=>(p(),g));await t.releaseAll()}catch{}console.log("[Scheduler] Stopped.")}getTasks(){return[...this.tasks]}getHistory(){return[...this.history]}dueTasks(t){let e=t??new Date;return this.tasks.filter(s=>I(s.getExpression(),e))}remove(t){let e=this.tasks.findIndex(s=>s.name===t);return e!==-1?(this.tasks.splice(e,1),!0):!1}clear(){this.tasks=[]}addToHistory(t){this.history.push(t),this.history.length>this.maxHistory&&this.history.shift(),this._persistToDb&&this.persistResult(t).catch(()=>{})}_historyTableEnsured=!1;async ensureHistoryTable(){if(this._historyTableEnsured)return;let{Connection:t}=await Promise.resolve().then(()=>(T(),m));switch(t.getDriver()){case"sqlite":await t.raw(`CREATE TABLE IF NOT EXISTS scheduled_task_runs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            task TEXT NOT NULL,
+            success INTEGER NOT NULL,
+            duration INTEGER NOT NULL,
+            error TEXT,
+            ran_at TEXT NOT NULL
+          )`);break;case"postgres":await t.raw(`CREATE TABLE IF NOT EXISTS scheduled_task_runs (
+            id SERIAL PRIMARY KEY,
+            task VARCHAR(255) NOT NULL,
+            success BOOLEAN NOT NULL,
+            duration INTEGER NOT NULL,
+            error TEXT,
+            ran_at TIMESTAMPTZ NOT NULL
+          )`);break;case"mysql":await t.raw(`CREATE TABLE IF NOT EXISTS scheduled_task_runs (
+            id INT AUTO_INCREMENT PRIMARY KEY,
+            task VARCHAR(255) NOT NULL,
+            success TINYINT NOT NULL,
+            duration INT NOT NULL,
+            error TEXT,
+            ran_at DATETIME NOT NULL
+          ) ENGINE=InnoDB`);break}this._historyTableEnsured=!0}async persistResult(t){try{await this.ensureHistoryTable();let{Connection:e}=await Promise.resolve().then(()=>(T(),m));await e.raw("INSERT INTO scheduled_task_runs (task, success, duration, error, ran_at) VALUES (?, ?, ?, ?, ?)",[t.task,t.success,t.duration,t.error||null,t.timestamp.toISOString()])}catch{}}};function U(a,t,e){class s extends v{name=a;schedule(){return e&&e(this),this}async handle(){return t()}}return new s}export{v as ScheduledTask,O as Scheduler,y as SchedulerLock,I as cronMatches,x as parseCron,U as task};

package/dist/services/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Svelar Service Layer
+ *
+ * Base classes for the service layer in a hybrid DDD architecture.
+ * Services orchestrate business logic, coordinate actions, and
+ * interact with repositories.
+ *
+ * @example
+ * ```ts
+ * import { Service } from 'svelar/services';
+ *
+ * class UserService extends Service {
+ *   constructor(private userRepo: UserRepository) {
+ *     super();
+ *   }
+ *
+ *   async register(data: RegisterDTO): Promise<User> {
+ *     const exists = await this.userRepo.findByEmail(data.email);
+ *     if (exists) throw new ConflictError('Email already taken');
+ *
+ *     const hashedPassword = await Hash.make(data.password);
+ *     const user = await this.userRepo.create({
+ *       ...data,
+ *       password: hashedPassword,
+ *     });
+ *
+ *     await this.emit('user:registered', user);
+ *     return user;
+ *   }
+ * }
+ * ```
+ */
+export interface ServiceResult<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    errors?: Record<string, string[]>;
+}
+export declare abstract class Service {
+    private eventDispatchFn?;
+    /**
+     * Set the event dispatch function for this service
+     */
+    setEventDispatcher(dispatchFn: (event: any) => Promise<void>): void;
+    /**
+     * Emit a domain event object
+     */
+    protected emit(event: any): Promise<void>;
+    /**
+     * Return a success result
+     */
+    protected ok<T>(data?: T): ServiceResult<T>;
+    /**
+     * Return a failure result
+     */
+    protected fail(error: string, errors?: Record<string, string[]>): ServiceResult<never>;
+    /**
+     * Execute an action within a try/catch, returning a ServiceResult
+     */
+    protected attempt<T>(fn: () => Promise<T>): Promise<ServiceResult<T>>;
+}
+/**
+ * Pre-built CRUD service that delegates to a repository.
+ * Extend to add custom business logic.
+ */
+export declare abstract class CrudService<TModel = any, TCreateDTO = any, TUpdateDTO = any> extends Service {
+    protected abstract repository(): Repository<TModel>;
+    findAll(options?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<TModel[]>;
+    findById(id: any): Promise<TModel | null>;
+    findByIdOrFail(id: any): Promise<TModel>;
+    create(data: TCreateDTO): Promise<TModel>;
+    update(id: any, data: TUpdateDTO): Promise<TModel>;
+    delete(id: any): Promise<void>;
+}
+import { Repository } from '../repositories/index.js';
+export { Repository };

package/dist/services/index.js

@@ -0,0 +1 @@
+var o=class{query(){return this.model().query()}async all(){return this.model().all()}async findById(e){return this.model().find(e)}async findByIdOrFail(e){return this.model().findOrFail(e)}async findWhere(e,r){return this.model().where(e,r).get()}async findFirstWhere(e,r){return this.model().where(e,r).first()}async create(e){return this.model().create(e)}async update(e,r){let t=await this.findByIdOrFail(e);return await t.update(r),t}async delete(e){await(await this.findByIdOrFail(e)).delete()}async createMany(e){let r=[];for(let t of e)r.push(await this.create(t));return r}async deleteWhere(e,r){return this.query().where(e,r).delete()}async count(){return this.model().count()}async countWhere(e,r){return this.query().where(e,r).count()}async exists(e,r){return this.query().where(e,r).exists()}async paginate(e=1,r=15){let t=await this.query().paginate(e,r);return{data:t.data,meta:{total:t.total,page:t.currentPage,perPage:t.perPage,lastPage:t.lastPage,hasNextPage:t.currentPage<t.lastPage,hasPrevPage:t.currentPage>1}}}async latest(e,r="created_at"){let t=this.query().orderBy(r,"desc");return e&&t.limit(e),t.get()}async oldest(e,r="created_at"){let t=this.query().orderBy(r,"asc");return e&&t.limit(e),t.get()}async firstOrCreate(e,r){let t=Object.entries(e),a=this.query();for(let[s,i]of t)a=a.where(s,i);let n=await a.first();return n||this.create({...e,...r})}async updateOrCreate(e,r){let t=Object.entries(e),a=this.query();for(let[s,i]of t)a=a.where(s,i);let n=await a.first();return n?(await n.update(r),n):this.create({...e,...r})}async filter(e,r){let t=this.query();for(let{column:a,operator:n,value:s}of e)switch(n){case"in":t=t.whereIn(a,s);break;case"not_in":t=t.whereNotIn(a,s);break;case"like":t=t.where(a,"like",s);break;default:t=t.where(a,n,s)}return r&&(t=t.orderBy(r.column,r.direction)),t.get()}async pluck(e){return this.query().pluck(e)}};var c=class{eventDispatchFn;setEventDispatcher(e){this.eventDispatchFn=e}async emit(e){this.eventDispatchFn&&await this.eventDispatchFn(e)}ok(e){return{success:!0,data:e}}fail(e,r){return{success:!1,error:e,errors:r}}async attempt(e){try{let r=await e();return this.ok(r)}catch(r){return this.fail(r.message)}}},l=class extends c{async findAll(e){return e?.page?(await this.repository().paginate(e.page,e.perPage)).data:this.repository().all()}async findById(e){return this.repository().findById(e)}async findByIdOrFail(e){let r=await this.repository().findById(e);if(!r)throw new Error(`Record with id ${e} not found`);return r}async create(e){return this.repository().create(e)}async update(e,r){return this.repository().update(e,r)}async delete(e){return this.repository().delete(e)}};export{l as CrudService,o as Repository,c as Service};