@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/scheduling/scheduler.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ *
+ * Wraps the `node-cron` library with a unified interface for defining, starting,
+ * stopping, and listing recurring tasks. The `node-cron` module is loaded lazily
+ * on first use — it is not imported at startup. This keeps the module importable
+ * in any environment; runtime errors surface only when scheduling is actually
+ * attempted in an unsupported environment (e.g., Cloudflare Workers).
+ *
+ * **Node.js only.** Calling `schedule()` in a non-Node.js runtime throws
+ * `McpError(ConfigurationError)`.
+ *
+ * @module src/utils/scheduling/scheduler
+ */
+import type { ScheduledTask } from 'node-cron';
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Represents a scheduled job managed by the {@link SchedulerService}.
+ *
+ * @example
+ * const jobs = scheduler.listJobs();
+ * for (const job of jobs) {
+ *   console.log(`${job.id} (${job.schedule}): running=${job.isRunning}`);
+ * }
+ */
+export interface Job {
+    /** Human-readable description of what the job does. */
+    description: string;
+    /** Unique identifier for the job, supplied at scheduling time. */
+    id: string;
+    /**
+     * Whether the task function is currently executing.
+     * The scheduler skips a tick if `true` to prevent overlapping runs.
+     */
+    isRunning: boolean;
+    /** Cron pattern that defines the job's schedule (e.g., `'0 * * * *'`). */
+    schedule: string;
+    /** The underlying `node-cron` task instance. Use `start()`/`stop()` via the service rather than directly. */
+    task: ScheduledTask;
+}
+/**
+ * Singleton service for scheduling and managing cron jobs.
+ *
+ * Depends on the `node-cron` peer dependency, which is loaded lazily on the
+ * first call to {@link schedule}. Cron jobs skip overlapping executions: if a
+ * task is still running when its next tick fires, that tick is logged and
+ * discarded. Each execution receives a fresh {@link RequestContext} for
+ * correlated logging.
+ *
+ * Use the pre-constructed {@link schedulerService} export rather than
+ * instantiating this class directly.
+ *
+ * @example
+ * import { schedulerService } from '../../utils/scheduling/scheduler.js';
+ *
+ * await schedulerService.schedule(
+ *   'cleanup',
+ *   '0 3 * * *',
+ *   async (ctx) => { await purgeOldRecords(ctx); },
+ *   'Nightly cleanup of expired records',
+ * );
+ * schedulerService.start('cleanup');
+ */
+export declare class SchedulerService {
+    private static instance;
+    private jobs;
+    /** @private */
+    private constructor();
+    /**
+     * Returns the singleton instance of {@link SchedulerService}, creating it on
+     * first call.
+     *
+     * @returns The shared `SchedulerService` instance.
+     * @example
+     * const scheduler = SchedulerService.getInstance();
+     */
+    static getInstance(): SchedulerService;
+    /**
+     * Registers and creates a new cron job. The job is created in a stopped
+     * state — call {@link start} to begin execution.
+     *
+     * Lazily imports `node-cron` on the first call. Validates the cron pattern
+     * before storing the job. Each execution of `taskFunction` receives a fresh
+     * {@link RequestContext} with `operation` set to `scheduler:job:<id>`.
+     * Overlapping runs are skipped: if the previous execution is still in
+     * progress when the next tick fires, that tick is logged and discarded.
+     * Errors thrown by `taskFunction` are caught and logged; they do not
+     * propagate to the scheduler.
+     *
+     * @param id - Unique identifier for the job. Must not already be registered.
+     * @param schedule - Standard cron expression (five or six fields, e.g. `'0 * * * *'`).
+     * @param taskFunction - Async (or sync) function to run on each tick. Receives a
+     *   `RequestContext` scoped to the job execution.
+     * @param description - Human-readable description stored on the {@link Job} object.
+     * @returns The newly created {@link Job} (in stopped state).
+     * @throws {McpError} `Conflict` (-32002) if a job with the same `id` already exists.
+     * @throws {McpError} `InvalidParams` (-32602) if `schedule` is not a valid cron expression.
+     * @throws {McpError} `ConfigurationError` (-32008) if called outside a Node.js runtime.
+     * @example
+     * const job = await schedulerService.schedule(
+     *   'ping',
+     *   '* * * * *',
+     *   async (ctx) => { logger.info('ping', ctx); },
+     *   'Logs a ping every minute',
+     * );
+     * schedulerService.start('ping');
+     */
+    schedule(id: string, schedule: string, taskFunction: (context: RequestContext) => void | Promise<void>, description: string): Promise<Job>;
+    /**
+     * Starts a previously registered job, causing it to execute on its cron schedule.
+     *
+     * @param id - ID of the job to start, as supplied to {@link schedule}.
+     * @returns `void`
+     * @throws {McpError} `NotFound` (-32001) if no job with the given `id` exists.
+     * @example
+     * schedulerService.start('cleanup');
+     */
+    start(id: string): void;
+    /**
+     * Stops a running job. The job remains registered and can be restarted with
+     * {@link start}. Any in-progress execution completes normally.
+     *
+     * @param id - ID of the job to stop.
+     * @returns `void`
+     * @throws {McpError} `NotFound` (-32001) if no job with the given `id` exists.
+     * @example
+     * schedulerService.stop('cleanup');
+     */
+    stop(id: string): void;
+    /**
+     * Stops and permanently removes a job from the scheduler. The job cannot be
+     * restarted after removal; call {@link schedule} to re-register it.
+     *
+     * @param id - ID of the job to remove.
+     * @returns `void`
+     * @throws {McpError} `NotFound` (-32001) if no job with the given `id` exists.
+     * @example
+     * schedulerService.remove('cleanup');
+     */
+    remove(id: string): void;
+    /**
+     * Looks up a job by ID.
+     *
+     * @param id - Job ID to look up.
+     * @returns The {@link Job} record.
+     * @throws {McpError} `NotFound` (-32001) if the job does not exist.
+     */
+    private resolveJob;
+    /**
+     * Returns a snapshot of all currently registered jobs, regardless of their
+     * running state.
+     *
+     * @returns Array of all {@link Job} objects in insertion order.
+     * @example
+     * for (const job of schedulerService.listJobs()) {
+     *   console.log(job.id, job.isRunning ? 'running' : 'stopped');
+     * }
+     */
+    listJobs(): Job[];
+}
+/**
+ * Pre-constructed singleton instance of {@link SchedulerService}.
+ *
+ * Import and use this throughout the application rather than calling
+ * `SchedulerService.getInstance()` directly.
+ *
+ * @example
+ * import { schedulerService } from '../../utils/scheduling/scheduler.js';
+ *
+ * await schedulerService.schedule('heartbeat', '* * * * *', heartbeatFn, 'Heartbeat');
+ * schedulerService.start('heartbeat');
+ */
+export declare const schedulerService: SchedulerService;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/utils/scheduling/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/utils/scheduling/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AA0BzE;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG;IAClB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,6GAA6G;IAC7G,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmB;IAC1C,OAAO,CAAC,IAAI,CAA+B;IAE3C,eAAe;IACf,OAAO;IAMP;;;;;;;OAOG;WACW,WAAW,IAAI,gBAAgB;IAO7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,QAAQ,CACnB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC/D,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,GAAG,CAAC;IA2Df;;;;;;;;OAQG;IACI,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAU9B;;;;;;;;;OASG;IACI,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAU7B;;;;;;;;;OASG;IACI,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAW/B;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;;;;OASG;IACI,QAAQ,IAAI,GAAG,EAAE;CAGzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,kBAAiC,CAAC"}

package/dist/utils/scheduling/scheduler.js

@@ -0,0 +1,248 @@
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+import { runtimeCaps } from '../../utils/internal/runtime.js';
+/**
+ * Lazily loads the `node-cron` module on first call and caches the resulting
+ * promise so subsequent calls resolve from the same import. Throws
+ * `McpError(ConfigurationError)` immediately if called outside a Node.js runtime.
+ *
+ * @throws {McpError} `ConfigurationError` when not running in Node.js.
+ */
+let cronModulePromise = null;
+async function loadCron() {
+    if (!runtimeCaps.isNode) {
+        throw new McpError(JsonRpcErrorCode.ConfigurationError, 'SchedulerService requires a Node.js runtime. Cron scheduling is not available in Workers or browser environments.');
+    }
+    if (!cronModulePromise) {
+        cronModulePromise = import('node-cron');
+    }
+    return await cronModulePromise;
+}
+/**
+ * Singleton service for scheduling and managing cron jobs.
+ *
+ * Depends on the `node-cron` peer dependency, which is loaded lazily on the
+ * first call to {@link schedule}. Cron jobs skip overlapping executions: if a
+ * task is still running when its next tick fires, that tick is logged and
+ * discarded. Each execution receives a fresh {@link RequestContext} for
+ * correlated logging.
+ *
+ * Use the pre-constructed {@link schedulerService} export rather than
+ * instantiating this class directly.
+ *
+ * @example
+ * import { schedulerService } from '../../utils/scheduling/scheduler.js';
+ *
+ * await schedulerService.schedule(
+ *   'cleanup',
+ *   '0 3 * * *',
+ *   async (ctx) => { await purgeOldRecords(ctx); },
+ *   'Nightly cleanup of expired records',
+ * );
+ * schedulerService.start('cleanup');
+ */
+export class SchedulerService {
+    static instance;
+    jobs = new Map();
+    /** @private */
+    constructor() {
+        // The constructor is intentionally left empty to prevent instantiation with 'new'.
+        // Logging has been removed from here to break a circular dependency
+        // with the logger, which was causing a ReferenceError on startup.
+    }
+    /**
+     * Returns the singleton instance of {@link SchedulerService}, creating it on
+     * first call.
+     *
+     * @returns The shared `SchedulerService` instance.
+     * @example
+     * const scheduler = SchedulerService.getInstance();
+     */
+    static getInstance() {
+        if (!SchedulerService.instance) {
+            SchedulerService.instance = new SchedulerService();
+        }
+        return SchedulerService.instance;
+    }
+    /**
+     * Registers and creates a new cron job. The job is created in a stopped
+     * state — call {@link start} to begin execution.
+     *
+     * Lazily imports `node-cron` on the first call. Validates the cron pattern
+     * before storing the job. Each execution of `taskFunction` receives a fresh
+     * {@link RequestContext} with `operation` set to `scheduler:job:<id>`.
+     * Overlapping runs are skipped: if the previous execution is still in
+     * progress when the next tick fires, that tick is logged and discarded.
+     * Errors thrown by `taskFunction` are caught and logged; they do not
+     * propagate to the scheduler.
+     *
+     * @param id - Unique identifier for the job. Must not already be registered.
+     * @param schedule - Standard cron expression (five or six fields, e.g. `'0 * * * *'`).
+     * @param taskFunction - Async (or sync) function to run on each tick. Receives a
+     *   `RequestContext` scoped to the job execution.
+     * @param description - Human-readable description stored on the {@link Job} object.
+     * @returns The newly created {@link Job} (in stopped state).
+     * @throws {McpError} `Conflict` (-32002) if a job with the same `id` already exists.
+     * @throws {McpError} `InvalidParams` (-32602) if `schedule` is not a valid cron expression.
+     * @throws {McpError} `ConfigurationError` (-32008) if called outside a Node.js runtime.
+     * @example
+     * const job = await schedulerService.schedule(
+     *   'ping',
+     *   '* * * * *',
+     *   async (ctx) => { logger.info('ping', ctx); },
+     *   'Logs a ping every minute',
+     * );
+     * schedulerService.start('ping');
+     */
+    async schedule(id, schedule, taskFunction, description) {
+        if (this.jobs.has(id)) {
+            throw new McpError(JsonRpcErrorCode.Conflict, `Job with ID '${id}' already exists.`);
+        }
+        const cron = await loadCron();
+        if (!cron.validate(schedule)) {
+            throw new McpError(JsonRpcErrorCode.InvalidParams, `Invalid cron schedule: ${schedule}`);
+        }
+        const task = cron.createTask(schedule, async () => {
+            const job = this.jobs.get(id);
+            const context = requestContextService.createRequestContext({
+                operation: `scheduler:job:${id}`,
+                jobId: id,
+                schedule,
+            });
+            if (job?.isRunning) {
+                logger.warning(`Job '${id}' is already running. Skipping this execution.`, context);
+                return;
+            }
+            if (job) {
+                job.isRunning = true;
+            }
+            logger.info(`Starting job '${id}'...`, context);
+            try {
+                await Promise.resolve(taskFunction(context));
+                logger.info(`Job '${id}' completed successfully.`, context);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger.error(`Job '${id}' failed.`, err, context);
+            }
+            finally {
+                if (job) {
+                    job.isRunning = false;
+                }
+            }
+        });
+        const newJob = {
+            id,
+            schedule,
+            description,
+            task,
+            isRunning: false,
+        };
+        const context = requestContextService.createRequestContext({
+            operation: 'scheduler:schedule',
+            jobId: id,
+        });
+        this.jobs.set(id, newJob);
+        logger.info(`Job '${id}' scheduled: ${description}`, context);
+        return newJob;
+    }
+    /**
+     * Starts a previously registered job, causing it to execute on its cron schedule.
+     *
+     * @param id - ID of the job to start, as supplied to {@link schedule}.
+     * @returns `void`
+     * @throws {McpError} `NotFound` (-32001) if no job with the given `id` exists.
+     * @example
+     * schedulerService.start('cleanup');
+     */
+    start(id) {
+        const job = this.resolveJob(id);
+        void job.task.start();
+        const context = requestContextService.createRequestContext({
+            operation: 'scheduler:start',
+            jobId: id,
+        });
+        logger.info(`Job '${id}' started.`, context);
+    }
+    /**
+     * Stops a running job. The job remains registered and can be restarted with
+     * {@link start}. Any in-progress execution completes normally.
+     *
+     * @param id - ID of the job to stop.
+     * @returns `void`
+     * @throws {McpError} `NotFound` (-32001) if no job with the given `id` exists.
+     * @example
+     * schedulerService.stop('cleanup');
+     */
+    stop(id) {
+        const job = this.resolveJob(id);
+        void job.task.stop();
+        const context = requestContextService.createRequestContext({
+            operation: 'scheduler:stop',
+            jobId: id,
+        });
+        logger.info(`Job '${id}' stopped.`, context);
+    }
+    /**
+     * Stops and permanently removes a job from the scheduler. The job cannot be
+     * restarted after removal; call {@link schedule} to re-register it.
+     *
+     * @param id - ID of the job to remove.
+     * @returns `void`
+     * @throws {McpError} `NotFound` (-32001) if no job with the given `id` exists.
+     * @example
+     * schedulerService.remove('cleanup');
+     */
+    remove(id) {
+        const job = this.resolveJob(id);
+        void job.task.stop();
+        this.jobs.delete(id);
+        const context = requestContextService.createRequestContext({
+            operation: 'scheduler:remove',
+            jobId: id,
+        });
+        logger.info(`Job '${id}' removed.`, context);
+    }
+    /**
+     * Looks up a job by ID.
+     *
+     * @param id - Job ID to look up.
+     * @returns The {@link Job} record.
+     * @throws {McpError} `NotFound` (-32001) if the job does not exist.
+     */
+    resolveJob(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new McpError(JsonRpcErrorCode.NotFound, `Job with ID '${id}' not found.`);
+        }
+        return job;
+    }
+    /**
+     * Returns a snapshot of all currently registered jobs, regardless of their
+     * running state.
+     *
+     * @returns Array of all {@link Job} objects in insertion order.
+     * @example
+     * for (const job of schedulerService.listJobs()) {
+     *   console.log(job.id, job.isRunning ? 'running' : 'stopped');
+     * }
+     */
+    listJobs() {
+        return Array.from(this.jobs.values());
+    }
+}
+/**
+ * Pre-constructed singleton instance of {@link SchedulerService}.
+ *
+ * Import and use this throughout the application rather than calling
+ * `SchedulerService.getInstance()` directly.
+ *
+ * @example
+ * import { schedulerService } from '../../utils/scheduling/scheduler.js';
+ *
+ * await schedulerService.schedule('heartbeat', '* * * * *', heartbeatFn, 'Heartbeat');
+ * schedulerService.start('heartbeat');
+ */
+export const schedulerService = SchedulerService.getInstance();
+//# sourceMappingURL=scheduler.js.map

package/dist/utils/scheduling/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../../src/utils/scheduling/scheduler.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;;;;GAMG;AACH,IAAI,iBAAiB,GAA+C,IAAI,CAAC;AAEzE,KAAK,UAAU,QAAQ;IACrB,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,mHAAmH,CACpH,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,iBAAiB,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,iBAAiB,CAAC;AACjC,CAAC;AA2BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAC,QAAQ,CAAmB;IAClC,IAAI,GAAqB,IAAI,GAAG,EAAE,CAAC;IAE3C,eAAe;IACf;QACE,mFAAmF;QACnF,oEAAoE;QACpE,kEAAkE;IACpE,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC;YAC/B,gBAAgB,CAAC,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACrD,CAAC;QACD,OAAO,gBAAgB,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACI,KAAK,CAAC,QAAQ,CACnB,EAAU,EACV,QAAgB,EAChB,YAA+D,EAC/D,WAAmB;QAEnB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;QACvF,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,EAAE,CAAC;QAE9B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,0BAA0B,QAAQ,EAAE,CAAC,CAAC;QAC3F,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAChD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;gBACzD,SAAS,EAAE,iBAAiB,EAAE,EAAE;gBAChC,KAAK,EAAE,EAAE;gBACT,QAAQ;aACT,CAAC,CAAC;YAEH,IAAI,GAAG,EAAE,SAAS,EAAE,CAAC;gBACnB,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,gDAAgD,EAAE,OAAO,CAAC,CAAC;gBACpF,OAAO;YACT,CAAC;YAED,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC;YACvB,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YAChD,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC7C,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,2BAA2B,EAAE,OAAO,CAAC,CAAC;YAC9D,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBACtE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YACpD,CAAC;oBAAS,CAAC;gBACT,IAAI,GAAG,EAAE,CAAC;oBACR,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC;gBACxB,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAQ;YAClB,EAAE;YACF,QAAQ;YACR,WAAW;YACX,IAAI;YACJ,SAAS,EAAE,KAAK;SACjB,CAAC;QAEF,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,oBAAoB;YAC/B,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,EAAU;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAChC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,iBAAiB;YAC5B,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;OASG;IACI,IAAI,CAAC,EAAU;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAChC,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,gBAAgB;YAC3B,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,EAAU;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAChC,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrB,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,kBAAkB;YAC7B,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACK,UAAU,CAAC,EAAU;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,cAAc,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;;;;;OASG;IACI,QAAQ;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,WAAW,EAAE,CAAC"}

package/dist/utils/security/idGenerator.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Defines the structure for configuring entity prefixes.
+ * Keys are entity type names (e.g., "project", "task"), and values are their corresponding ID prefixes (e.g., "PROJ", "TASK").
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * Defines options for customizing ID generation.
+ */
+export interface IdGenerationOptions {
+    /** Character set to draw from when building the random part. Defaults to `A-Z0-9`. */
+    charset?: string;
+    /** Length of the random part of the ID. Defaults to `6`. */
+    length?: number;
+    /** String placed between the prefix and the random part. Defaults to `'_'`. */
+    separator?: string;
+}
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export declare class IdGenerator {
+    /**
+     * Default character set for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_CHARSET;
+    /**
+     * Default separator character between prefix and random part.
+     * @private
+     */
+    private static DEFAULT_SEPARATOR;
+    /**
+     * Default length for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_LENGTH;
+    /**
+     * Stores the mapping of entity types to their prefixes.
+     * @private
+     */
+    private entityPrefixes;
+    /**
+     * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+     * @private
+     */
+    private prefixToEntityType;
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal reverse lookup map.
+     * @param entityPrefixes - A map where keys are entity type names and values are their desired ID prefixes.
+     */
+    setEntityPrefixes(entityPrefixes: EntityPrefixConfig): void;
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * Generates a cryptographically secure random string.
+     * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
+     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @returns The generated random string.
+     */
+    generateRandomString(length?: number, charset?: string): string;
+    /**
+     * Generates a unique ID, optionally prepended with a prefix.
+     * @param prefix - An optional prefix for the ID.
+     * @param options - Optional parameters for ID generation (length, separator, charset).
+     * @returns A unique identifier string.
+     */
+    generate(prefix?: string, options?: IdGenerationOptions): string;
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * @param entityType - The type of entity (must be registered).
+     * @param options - Optional parameters for ID generation.
+     * @returns A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered.
+     */
+    generateForEntity(entityType: string, options?: IdGenerationOptions): string;
+    /**
+     * Validates if an ID conforms to the expected format for a specific entity type.
+     * @param id - The ID string to validate.
+     * @param entityType - The expected entity type of the ID.
+     * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    private escapeRegex;
+    /**
+     * Strips the prefix and separator from an ID string, returning only the random part.
+     * If the separator does not appear in the string, the original ID is returned unchanged.
+     * Handles edge cases where the separator character appears in the random part by
+     * rejoining all parts after the first split.
+     *
+     * @param id - The full ID string (e.g., `"PROJ_A6B3J0"`).
+     * @param separator - The separator character used in the ID. Defaults to `'_'`.
+     * @returns The random part of the ID without the prefix (e.g., `"A6B3J0"`), or the
+     *   original string if the separator is not present.
+     *
+     * @example
+     * ```ts
+     * idGenerator.stripPrefix('PROJ_A6B3J0');         // → 'A6B3J0'
+     * idGenerator.stripPrefix('PROJ-A6B3J0', '-');    // → 'A6B3J0'
+     * idGenerator.stripPrefix('NOPREFIXID');           // → 'NOPREFIXID'
+     * ```
+     */
+    stripPrefix(id: string, separator?: string): string;
+    /**
+     * Determines the entity type from an ID string by its prefix (case-insensitive).
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The determined entity type.
+     * @throws {McpError} If ID format is invalid or prefix is unknown.
+     */
+    getEntityType(id: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID so that the prefix matches its registered casing and the random
+     * part is uppercased. Delegates to {@link getEntityType} to resolve the canonical prefix.
+     *
+     * Note: Uppercasing the random part is correct for the default `A-Z0-9` charset. For custom
+     * charsets that include lowercase or non-alphabetic characters, `toUpperCase()` may produce
+     * unexpected results.
+     *
+     * @param id - The ID to normalize (e.g., `"proj_a6b3j0"`).
+     * @param separator - The separator used in the ID. Defaults to `'_'`.
+     * @returns The normalized ID with canonical prefix casing and uppercase random part
+     *   (e.g., `"PROJ_A6B3J0"`).
+     * @throws {McpError} With {@link JsonRpcErrorCode.ValidationError} if the entity type
+     *   cannot be determined from the ID's prefix.
+     *
+     * @example
+     * ```ts
+     * idGenerator.setEntityPrefixes({ project: 'PROJ' });
+     * idGenerator.normalize('proj_a6b3j0'); // → 'PROJ_A6B3J0'
+     * idGenerator.normalize('PROJ_a6b3j0'); // → 'PROJ_A6B3J0'
+     * ```
+     */
+    normalize(id: string, separator?: string): string;
+}
+/**
+ * Default singleton instance of {@link IdGenerator}, initialized with no entity prefixes.
+ * Call `idGenerator.setEntityPrefixes({ ... })` during application startup to register prefixes
+ * before calling `generateForEntity` or `getEntityType`.
+ */
+export declare const idGenerator: IdGenerator;
+/**
+ * Generates a standard Version 4 UUID using the Web Crypto API (`crypto.randomUUID()`).
+ * Cross-runtime: works in Node.js 19+, Cloudflare Workers, and browsers.
+ *
+ * @returns A new UUID v4 string (e.g., `"110e8400-e29b-41d4-a716-446655440000"`).
+ *
+ * @example
+ * ```ts
+ * const id = generateUUID(); // → '110e8400-e29b-41d4-a716-446655440000'
+ * ```
+ */
+export declare const generateUUID: () => string;
+/**
+ * Generates a short, human-readable request context ID in the format `XXXXX-XXXXX`
+ * (two 5-character alphanumeric segments joined by a hyphen, e.g., `"A3K9Z-BQ72M"`).
+ *
+ * This function is self-contained — it does not call `IdGenerator` or any other module-level
+ * export — specifically to avoid circular dependencies with `requestContextService`, which
+ * itself calls this function during initialization.
+ *
+ * Uses rejection sampling against the Web Crypto API for uniform, bias-free character selection.
+ *
+ * @returns A 11-character string in `XXXXX-XXXXX` format suitable for request tracing.
+ *
+ * @example
+ * ```ts
+ * const reqId = generateRequestContextId(); // → 'A3K9Z-BQ72M'
+ * ```
+ */
+export declare const generateRequestContextId: () => string;
+//# sourceMappingURL=idGenerator.d.ts.map

package/dist/utils/security/idGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IACxE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IACvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAA0B;IAChD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;gBACS,cAAc,GAAE,kBAAuB;IAKnD;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI;IAalE;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB;IAI9C;;;;;OAKG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM;IAuBT;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM;IAa3E;;;;;;OAMG;IACI,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM;IAWvF;;;;;;;OAOG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO;IAuB1F;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM;IAKzF;;;;;;OAMG;IACI,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM;IAqB3F;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM;CAUxF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MA8B3C,CAAC"}