c8y-nitro 0.7.2 → 0.8.0

package/dist/cli/index.mjs

@@ -1,4 +1,4 @@
-import { n as name, r as version, t as description } from "../package-BHOzdhHp.mjs";
+import { n as name, r as version, t as description } from "../package-CNWz76PV.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/cli/index.ts
 runMain(defineCommand({

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { _ as GENERATED_READINESS_ROUTE, g as GENERATED_LIVENESS_ROUTE, h as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, m as createC8yManifestFromNitro, p as createC8yManifest } from "./c8y-api-DscUs-Kd.mjs";
 import { t as autoBootstrap } from "./autoBootstrap-Drk7ltXK.mjs";
-import { n as name } from "./package-BHOzdhHp.mjs";
+import { n as name } from "./package-CNWz76PV.mjs";
 import { basename, dirname, join, relative } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { x } from "tinyexec";

package/dist/{package-BHOzdhHp.mjs → package-CNWz76PV.mjs}

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "c8y-nitro";
-var version = "0.7.2";
+var version = "0.8.0";
 var description = "Lightning fast Cumulocity IoT microservice development powered by Nitro";
 //#endregion
 export { name as n, version as r, description as t };

package/dist/utils.d.mts

@@ -502,110 +502,264 @@ declare function useLogger<T extends object = Record<string, unknown>>(eventOrRe
  */
 declare const createError: typeof createError$1;
 //#endregion
-//#region src/utils/schedule.d.ts
-type ScheduledTaskPayload = TaskPayload;
-type ScheduledTaskContext = TaskContext;
+//#region src/utils/tasks.d.ts
 /**
- * A one-shot schedule definition for `scheduleTask()`.\
- * Numbers are treated as seconds from now, strings are parsed as human-readable durations
- * such as `"10 minutes"`, and dates are used as exact run times.
+ * Concurrency policy for a single job.
+ * - `'single'`: at most one run of the job is in flight at a time. A tick that
+ *   fires while the previous run is still going is skipped, and a manual
+ *   {@link TaskRegistry.triggerJob} while a run is active joins the in-flight run.
+ * - `'parallel'`: every tick (or trigger) starts a fresh run, even if a previous
+ *   run has not finished. Runs of the same job may overlap.
  */
-type ScheduledTaskInput = Date | number | string;
+type JobConcurrency = 'single' | 'parallel';
+type TaskRegistryPayload = TaskPayload;
+type TaskRegistryContext = TaskContext;
 /**
- * Options for scheduling a Nitro task to run once in the future.\
- * `payload` and `context` are forwarded to the task handler's `run()` method.
+ * The event passed to a task handler on every execution.
  */
-interface ScheduleTaskOptions {
+interface TaskEvent<TPayload = TaskRegistryPayload> {
   /**
-   * Payload forwarded to the task handler's `TaskEvent.payload`.
+   * Name of the task (function) being executed.
    */
-  payload?: ScheduledTaskPayload;
+  task: string;
+  /**
+   * Name of the job that triggered this run, when the run originates from a scheduled or triggered job.
+   */
+  job?: string;
+  /**
+   * Data bound when the job was scheduled (or passed to `run()`/`triggerJob()`).
+   */
+  payload: TPayload;
+  /**
+   * Arbitrary context bound alongside the payload.
+   */
+  context: TaskRegistryContext;
+}
+/**
+ * A task handler function registered via {@link TaskRegistry.createTask}.
+ */
+type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: TaskEvent<TPayload>) => TResult | Promise<TResult>;
+/**
+ * When a job should run.
+ * - `{ cron }`: recurring on a cron expression. 5- or 6-field (with seconds) is
+ *   supported. Evaluated in UTC by default, or in the job's `timezone` if set.
+ * - `{ in }`: one-shot, `in` seconds from now.
+ * - `{ at }`: one-shot, at an exact instant given as a `Date` or ISO 8601 string,
+ *   taken literally (never re-projected to another timezone). Times in the past
+ *   fire almost immediately.
+ */
+type JobSchedule = {
+  cron: string;
+} | {
+  in: number;
+} | {
+  at: Date | string;
+};
+/**
+ * Options for scheduling a job via {@link TaskRegistry.scheduleJob}.
+ */
+interface ScheduleJobOptions<TTask extends string = string, TPayload = TaskRegistryPayload, TSchedule extends JobSchedule = JobSchedule> {
+  /**
+   * Unique, caller-chosen job name. This is the handle used by `cancelJob()`, `getJob()` and `triggerJob()`.
+   */
+  name: string;
+  /**
+   * Name of a task registered via `createTask()` that this job runs.
+   */
+  task: TTask;
+  /**
+   * When the job should run.
+   */
+  schedule: TSchedule;
+  /**
+   * Data forwarded to the handler's `event.payload`.\
+   * Prefer stable identifiers (e.g. a config id) over live object references so the
+   * handler can resolve current values at run time and the schedule stays serializable.
+   */
+  payload?: TPayload;
   /**
-   * Context forwarded to the task handler's `TaskEvent.context`.
+   * Data forwarded to the handler's `event.context`.
    */
-  context?: ScheduledTaskContext;
+  context?: TaskRegistryContext;
   /**
-   * When the task should run. Numbers are seconds from now.
+   * Concurrency policy for this job. Defaults to `'single'`.
    */
-  schedule: ScheduledTaskInput;
+  concurrency?: JobConcurrency;
+  /**
+   * Recurring only: the IANA timezone the cron expression is evaluated in
+   * (e.g. `'Europe/Berlin'`). Defaults to `'UTC'` so the schedule is deterministic
+   * regardless of the container's local time. croner performs the alignment — no
+   * conversion is done by `c8y-nitro`. Ignored for one-shot schedules.
+   */
+  timezone?: string;
+  /**
+   * Recurring only: also run once immediately on registration, in addition to the cron. Defaults to `false`.
+   */
+  immediate?: boolean;
+  /**
+   * Recurring only: stop after this many scheduled runs.
+   */
+  maxRuns?: number;
+  /**
+   * Overwrite an existing job with the same name instead of throwing. Defaults to `false`.
+   */
+  replace?: boolean;
 }
 /**
- * Public information about a pending scheduled task.\
- * Returned by `scheduleTask()` and by `listScheduledTasks()`.
+ * Fields common to every job, regardless of kind.
  */
-interface ScheduledTaskInfo {
+interface BaseJobInfo {
   /**
-   * Stable UUID used to list or cancel the scheduled task.
+   * The job's unique name.
    */
-  id: string;
+  name: string;
   /**
-   * Nitro task name that will be passed to `runTask()`.
+   * The task (function) the job runs.
    */
   task: string;
   /**
-   * Exact execution time as an ISO date string.
+   * The job's concurrency policy.
+   */
+  concurrency: JobConcurrency;
+  /**
+   * Next scheduled execution as an ISO datetime string, or `null` if nothing is pending.
+   */
+  nextRun: string | null;
+  /**
+   * Whether a run of this job is currently in flight.
    */
-  runAt: string;
+  running: boolean;
 }
 /**
- * Schedules a Nitro task to run once in the future.\
- * Resolves and calls the task handler directly from Nitro's virtual task registry\
- * Numbers are treated as seconds, strings are parsed as human-readable durations, and dates are used as exact run times.
- *
- * @param taskName - The Nitro task name to run (from `tasks/*.ts`)
- * @param options - Task payload, context, and the schedule time
- * @returns Information about the scheduled task
- *
- * @example
- * // Run a task in 30 seconds:
- * const scheduled = await scheduleTask('emails:send', {
- *   payload: { messageId: 'abc123' },
- *   schedule: 30,
- * })
- *
- * @example
- * // Run a task using a human-readable duration:
- * await scheduleTask('reports:generate', {
- *   payload: { reportId: 'report-1' },
- *   schedule: '1 hour',
- * })
- *
- * @example
- * // Run a task at an exact time:
- * await scheduleTask('cleanup:tenant', {
- *   payload: { tenant: 't12345' },
- *   schedule: new Date('2026-05-01T12:00:00Z'),
- * })
+ * Information about a one-shot job (scheduled with `{ in }` or `{ at }`).
+ */
+interface OnceJobInfo extends BaseJobInfo {
+  kind: 'once';
+  /**
+   * Always `null` for one-shot jobs.
+   */
+  cron: null;
+}
+/**
+ * Information about a recurring job (scheduled with `{ cron }`).
  */
-declare function scheduleTask(taskName: string, options: ScheduleTaskOptions): Promise<ScheduledTaskInfo>;
+interface RecurringJobInfo extends BaseJobInfo {
+  kind: 'recurring';
+  /**
+   * The cron expression the job runs on.
+   */
+  cron: string;
+  /**
+   * The IANA timezone the cron expression is evaluated in.
+   */
+  timezone: string;
+  /**
+   * A few upcoming executions as ISO datetime strings.
+   */
+  nextRuns: string[];
+}
 /**
- * Lists all tasks that are currently scheduled and have not started yet.\
- * The returned object is keyed by the scheduled task UUID for easy lookup and cancellation.
- *
- * @returns Object mapping scheduled task IDs to their public task information
- *
- * @example
- * const tasks = await listScheduledTasks()
- * for (const [id, task] of Object.entries(tasks)) {
- *   console.log(id, task.task, task.runAt)
- * }
+ * Public information about a registered job. A discriminated union on `kind` —
+ * returned by `scheduleJob()`, `getJob()` and `listJobs()`.
  */
-declare function listScheduledTasks(): Promise<Record<string, ScheduledTaskInfo>>;
+type JobInfo = OnceJobInfo | RecurringJobInfo;
 /**
- * Cancels a scheduled task before it starts running.\
- * Once the underlying Nitro task has started, it cannot be cancelled with this utility.
+ * Maps a {@link JobSchedule} to the {@link JobInfo} variant it produces.
+ */
+type JobInfoFor<TSchedule extends JobSchedule> = TSchedule extends {
+  cron: string;
+} ? RecurringJobInfo : OnceJobInfo;
+/**
+ * Describes the payload and result type of a single registered task.
+ */
+interface TaskShape<TPayload = TaskRegistryPayload, TResult = unknown> {
+  payload: TPayload;
+  result: TResult;
+}
+/**
+ * A map of task name to its {@link TaskShape}, accumulated by the builder.
+ */
+type TaskMap = Record<string, TaskShape>;
+/**
+ * A type-charged registry of tasks (functions) and the jobs that schedule them.
  *
- * @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
- * @returns `true` when a pending task was cancelled, otherwise `false`
+ * Each `createTask()` call widens the registry's type with the new task name, so
+ * `run()`, `scheduleJob()` and `triggerJob()` autocomplete known task names and
+ * reject typos at compile time.
+ */
+interface TaskRegistry<TTasks extends TaskMap = {}> {
+  /**
+   * Registers a task (function) under a compile-time-known name.\
+   * Passing a name that is already registered is a type error (and throws at runtime).
+   *
+   * @param name - Unique task name
+   * @param handler - The function to run. Annotate its event to type the payload,
+   * e.g. `(e: TaskEvent<{ configId: string }>) => ...`.
+   */
+  createTask: <TName extends string, TPayload extends TaskRegistryPayload = TaskRegistryPayload, TResult = unknown>(name: TName extends keyof TTasks ? never : TName, handler: TaskHandler<TPayload, TResult>) => TaskRegistry<TTasks & Record<TName, TaskShape<TPayload, TResult>>>;
+  /**
+   * Runs a task immediately and ad-hoc, without registering a job. Always runs
+   * fresh (no deduplication). Use a job with `'single'` concurrency when you need
+   * overlap protection.
+   */
+  run: <TName extends keyof TTasks & string>(task: TName, options?: {
+    payload?: TTasks[TName]['payload'];
+    context?: TaskRegistryContext;
+  }) => Promise<TTasks[TName]['result']>;
+  /**
+   * Schedules a named job that runs a task once or repeatedly. The return type is
+   * inferred from the schedule: `{ cron }` yields a {@link RecurringJobInfo},
+   * `{ in }`/`{ at }` yield a {@link OnceJobInfo}.
+   */
+  scheduleJob: <TName extends keyof TTasks & string, TSchedule extends JobSchedule>(options: ScheduleJobOptions<TName, TTasks[TName]['payload'], TSchedule>) => JobInfoFor<TSchedule>;
+  /**
+   * Runs an already-registered job immediately, respecting its concurrency policy.
+   * For a `'single'` job with a run in flight this returns the in-flight promise.
+   */
+  triggerJob: <TResult = unknown>(name: string, options?: {
+    payload?: TaskRegistryPayload;
+    context?: TaskRegistryContext;
+  }) => Promise<TResult>;
+  /**
+   * Cancels a scheduled job by name.
+   * @returns `true` when a job was found and cancelled, otherwise `false`.
+   */
+  cancelJob: (name: string) => boolean;
+  /**
+   * Lists all currently registered jobs.
+   */
+  listJobs: () => JobInfo[];
+  /**
+   * Returns information about a single job, or `undefined` if it does not exist.
+   */
+  getJob: (name: string) => JobInfo | undefined;
+  /**
+   * Returns `true` when a task with the given name is registered.
+   */
+  hasTask: (name: string) => boolean;
+}
+/**
+ * Creates a new, empty task registry.
  *
  * @example
- * const scheduled = await scheduleTask('emails:send', {
- *   payload: { messageId: 'abc123' },
- *   schedule: '10 minutes',
- * })
+ * import { c8yTasks } from 'c8y-nitro/utils'
+ *
+ * export const tasks = c8yTasks()
+ *   .createTask('sync', async ({ payload }) => {
+ *     const config = await loadConfig(payload.configId) // resolve live state here
+ *     await sync(config)
+ *   })
+ *
+ * // one per config, each an independent job
+ * tasks.scheduleJob({ name: 'sync-abc', task: 'sync', payload: { configId: 'abc' }, schedule: { cron: '*\/5 * * * *' } })
+ * tasks.scheduleJob({ name: 'sync-def', task: 'sync', payload: { configId: 'def' }, schedule: { cron: '*\/5 * * * *' }, concurrency: 'parallel' })
  *
- * const cancelled = await cancelScheduledTask(scheduled.id)
+ * @remarks
+ * The registry is a plain runtime singleton — export it from one module and import
+ * it wherever you schedule or cancel jobs. Recurring jobs only arm when the module
+ * that schedules them executes, so register them from a Nitro plugin (or another
+ * startup path) if they must run from boot.
  */
-declare function cancelScheduledTask(id: string): Promise<boolean>;
+declare function c8yTasks(): TaskRegistry;
 //#endregion
-export { ForeignTenantOptionCategory, ForeignTenantOptionKeyInput, ScheduleTaskOptions, ScheduledTaskContext, ScheduledTaskInfo, ScheduledTaskInput, ScheduledTaskPayload, SetEditableOptions, TenantOption, TenantOptionCategory, TenantOptionKeyInput, cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+export { BaseJobInfo, ForeignTenantOptionCategory, ForeignTenantOptionKeyInput, JobConcurrency, JobInfo, JobInfoFor, JobSchedule, OnceJobInfo, RecurringJobInfo, ScheduleJobOptions, SetEditableOptions, TaskEvent, TaskHandler, TaskMap, TaskRegistry, TaskRegistryContext, TaskRegistryPayload, TaskShape, TenantOption, TenantOptionCategory, TenantOptionKeyInput, c8yTasks, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/dist/utils.mjs

@@ -1,5 +1,5 @@
 import { Buffer } from "node:buffer";
-import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import process from "node:process";
 import { useLogger as useLogger$1 } from "evlog/nitro/v3";
 import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
@@ -9,8 +9,7 @@ import { useRuntimeConfig } from "nitro/runtime-config";
 import { useNitroHooks } from "nitro/app";
 import { defineHandler } from "nitro/h3";
 import { c8yManifest } from "c8y-nitro/runtime";
-import { ms } from "itty-time";
-import { tasks } from "#nitro/virtual/tasks";
+import { Cron } from "croner";
 //#region src/utils/internal/common.ts
 /**
 * Converts undici Request headers to the format expected by MicroserviceClientRequestAuth.\
@@ -884,168 +883,167 @@ const useTenantOptions = Object.assign(useTenantOptionsBase, {
 	refreshAll: () => refreshFetchers(() => true)
 });
 //#endregion
-//#region src/utils/schedule.ts
-const MAX_TIMEOUT_MS = 2147483647;
-const SCHEDULE_LOOKAHEAD_MS = 3600 * 1e3;
-const SCHEDULER_TICK_MS = 100;
-const scheduledTasks = /* @__PURE__ */ new Map();
-const scheduledTaskTimers = /* @__PURE__ */ new Map();
-const schedulerReady = Promise.resolve();
-let schedulerInterval;
-function createScheduledTaskId() {
-	return randomUUID();
-}
-function resolveScheduleTime(schedule) {
-	if (schedule instanceof Date) {
-		const timestamp = schedule.getTime();
-		if (Number.isNaN(timestamp)) throw new TypeError("schedule date must be valid");
-		return timestamp;
-	}
-	if (typeof schedule === "number") {
-		if (!Number.isFinite(schedule) || schedule < 0) throw new TypeError("schedule number must be a non-negative number of seconds");
-		return Date.now() + schedule * 1e3;
+//#region src/utils/tasks.ts
+function resolveOnceDate(schedule) {
+	if ("in" in schedule) {
+		if (!Number.isFinite(schedule.in) || schedule.in < 0) throw new TypeError("schedule.in must be a non-negative number of seconds");
+		return new Date(Date.now() + schedule.in * 1e3);
 	}
-	const delay = ms(schedule);
-	if (!Number.isFinite(delay) || delay < 0) throw new TypeError("schedule string must be a valid non-negative duration");
-	return Date.now() + delay;
-}
-async function executeScheduledTask(id) {
-	const record = scheduledTasks.get(id);
-	if (!record) return;
-	if (record.timeoutId !== void 0) scheduledTaskTimers.delete(record.timeoutId);
-	scheduledTasks.delete(id);
-	stopSchedulerIntervalIfIdle();
-	const taskDef = tasks[record.taskName];
-	if (!taskDef) throw new Error(`Task "${record.taskName}" is not available!`);
-	if (!taskDef.resolve) throw new Error(`Task "${record.taskName}" is not implemented!`);
-	await (await taskDef.resolve()).run({
-		name: record.taskName,
-		payload: record.payload,
-		context: record.context
-	});
-}
-function armScheduledTaskTimeout(id) {
-	const record = scheduledTasks.get(id);
-	if (!record || record.timeoutId !== void 0) return;
-	const remainingMs = Math.max(record.runAt - Date.now(), 0);
-	if (remainingMs > SCHEDULE_LOOKAHEAD_MS) return;
-	const timeout = setTimeout(() => {
-		executeScheduledTask(id);
-	}, Math.min(remainingMs, MAX_TIMEOUT_MS));
-	record.timeoutId = Number(timeout);
-	scheduledTaskTimers.set(record.timeoutId, timeout);
-}
-function runSchedulerTick() {
-	for (const record of scheduledTasks.values()) armScheduledTaskTimeout(record.id);
-}
-function ensureSchedulerInterval() {
-	if (schedulerInterval) return;
-	schedulerInterval = setInterval(runSchedulerTick, SCHEDULER_TICK_MS);
-}
-function stopSchedulerIntervalIfIdle() {
-	if (!schedulerInterval || scheduledTasks.size > 0) return;
-	clearInterval(schedulerInterval);
-	schedulerInterval = void 0;
-}
-/**
-* Schedules a Nitro task to run once in the future.\
-* Resolves and calls the task handler directly from Nitro's virtual task registry\
-* Numbers are treated as seconds, strings are parsed as human-readable durations, and dates are used as exact run times.
-*
-* @param taskName - The Nitro task name to run (from `tasks/*.ts`)
-* @param options - Task payload, context, and the schedule time
-* @returns Information about the scheduled task
-*
-* @example
-* // Run a task in 30 seconds:
-* const scheduled = await scheduleTask('emails:send', {
-*   payload: { messageId: 'abc123' },
-*   schedule: 30,
-* })
-*
-* @example
-* // Run a task using a human-readable duration:
-* await scheduleTask('reports:generate', {
-*   payload: { reportId: 'report-1' },
-*   schedule: '1 hour',
-* })
-*
-* @example
-* // Run a task at an exact time:
-* await scheduleTask('cleanup:tenant', {
-*   payload: { tenant: 't12345' },
-*   schedule: new Date('2026-05-01T12:00:00Z'),
-* })
-*/
-async function scheduleTask(taskName, options) {
-	if (!import.meta._tasks) throw new Error("scheduleTask() requires tasks to be enabled. Set `experimental: { tasks: true }` in your nitro.config.ts.");
-	if (!taskName) throw new TypeError("taskName is required");
-	const runAt = resolveScheduleTime(options.schedule);
-	const record = {
-		id: createScheduledTaskId(),
-		taskName,
-		payload: options.payload ?? {},
-		context: options.context ?? {},
-		runAt
-	};
-	scheduledTasks.set(record.id, record);
-	armScheduledTaskTimeout(record.id);
-	ensureSchedulerInterval();
-	return {
-		id: record.id,
-		task: record.taskName,
-		runAt: new Date(record.runAt).toISOString()
-	};
+	const date = schedule.at instanceof Date ? schedule.at : new Date(schedule.at);
+	if (Number.isNaN(date.getTime())) throw new TypeError("schedule.at must be a valid Date or ISO 8601 string");
+	return date;
 }
 /**
-* Lists all tasks that are currently scheduled and have not started yet.\
-* The returned object is keyed by the scheduled task UUID for easy lookup and cancellation.
-*
-* @returns Object mapping scheduled task IDs to their public task information
+* Creates a new, empty task registry.
 *
 * @example
-* const tasks = await listScheduledTasks()
-* for (const [id, task] of Object.entries(tasks)) {
-*   console.log(id, task.task, task.runAt)
-* }
-*/
-async function listScheduledTasks() {
-	await schedulerReady;
-	return Object.fromEntries([...scheduledTasks.values()].map((record) => [record.id, {
-		id: record.id,
-		task: record.taskName,
-		runAt: new Date(record.runAt).toISOString()
-	}]));
-}
-/**
-* Cancels a scheduled task before it starts running.\
-* Once the underlying Nitro task has started, it cannot be cancelled with this utility.
+* import { c8yTasks } from 'c8y-nitro/utils'
 *
-* @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
-* @returns `true` when a pending task was cancelled, otherwise `false`
+* export const tasks = c8yTasks()
+*   .createTask('sync', async ({ payload }) => {
+*     const config = await loadConfig(payload.configId) // resolve live state here
+*     await sync(config)
+*   })
 *
-* @example
-* const scheduled = await scheduleTask('emails:send', {
-*   payload: { messageId: 'abc123' },
-*   schedule: '10 minutes',
-* })
+* // one per config, each an independent job
+* tasks.scheduleJob({ name: 'sync-abc', task: 'sync', payload: { configId: 'abc' }, schedule: { cron: '*\/5 * * * *' } })
+* tasks.scheduleJob({ name: 'sync-def', task: 'sync', payload: { configId: 'def' }, schedule: { cron: '*\/5 * * * *' }, concurrency: 'parallel' })
 *
-* const cancelled = await cancelScheduledTask(scheduled.id)
+* @remarks
+* The registry is a plain runtime singleton — export it from one module and import
+* it wherever you schedule or cancel jobs. Recurring jobs only arm when the module
+* that schedules them executes, so register them from a Nitro plugin (or another
+* startup path) if they must run from boot.
 */
-async function cancelScheduledTask(id) {
-	await schedulerReady;
-	const record = scheduledTasks.get(id);
-	if (!record) return false;
-	if (record.timeoutId !== void 0) {
-		const timeout = scheduledTaskTimers.get(record.timeoutId);
-		if (timeout) {
-			clearTimeout(timeout);
-			scheduledTaskTimers.delete(record.timeoutId);
+function c8yTasks() {
+	const tasks = /* @__PURE__ */ new Map();
+	const jobs = /* @__PURE__ */ new Map();
+	function execute(record, override) {
+		const definition = tasks.get(record.task);
+		if (!definition) return Promise.reject(/* @__PURE__ */ new Error(`Task "${record.task}" is not registered`));
+		if (record.concurrency === "single" && record.inFlight) return record.inFlight;
+		const event = {
+			task: record.task,
+			job: record.name,
+			payload: override?.payload ?? record.payload,
+			context: override?.context ?? record.context
+		};
+		const promise = (async () => definition.handler(event))();
+		if (record.concurrency === "single") {
+			record.inFlight = promise;
+			promise.finally(() => {
+				if (record.inFlight === promise) record.inFlight = void 0;
+			});
 		}
+		return promise;
 	}
-	const cancelled = scheduledTasks.delete(id);
-	stopSchedulerIntervalIfIdle();
-	return cancelled;
+	function toJobInfo(record) {
+		const next = record.cron.nextRun();
+		const base = {
+			name: record.name,
+			task: record.task,
+			concurrency: record.concurrency,
+			nextRun: next ? next.toISOString() : null,
+			running: record.inFlight !== void 0
+		};
+		if (record.kind === "recurring") return {
+			...base,
+			kind: "recurring",
+			cron: record.cronExpr,
+			timezone: record.timezone,
+			nextRuns: record.cron.nextRuns(3).map((date) => date.toISOString())
+		};
+		return {
+			...base,
+			kind: "once",
+			cron: null
+		};
+	}
+	function cancelJob(name) {
+		const record = jobs.get(name);
+		if (!record) return false;
+		record.cron.stop();
+		return jobs.delete(name);
+	}
+	const api = {
+		createTask(name, handler) {
+			if (typeof name !== "string" || !name) throw new TypeError("task name is required");
+			if (tasks.has(name)) throw new Error(`Task "${name}" is already registered`);
+			tasks.set(name, {
+				name,
+				handler
+			});
+			return api;
+		},
+		async run(task, options) {
+			const definition = tasks.get(task);
+			if (!definition) throw new Error(`Task "${task}" is not registered`);
+			return definition.handler({
+				task,
+				payload: options?.payload ?? {},
+				context: options?.context ?? {}
+			});
+		},
+		scheduleJob(options) {
+			const { name, task, schedule, concurrency = "single", replace = false } = options;
+			if (!name) throw new TypeError("job name is required");
+			if (!tasks.has(task)) throw new Error(`Task "${task}" is not registered. Register it with createTask() first.`);
+			if (jobs.has(name)) {
+				if (!replace) throw new Error(`Job "${name}" already exists. Pass { replace: true } to overwrite it.`);
+				cancelJob(name);
+			}
+			const isRecurring = "cron" in schedule;
+			const timezone = options.timezone ?? "UTC";
+			const record = {
+				name,
+				task,
+				kind: isRecurring ? "recurring" : "once",
+				concurrency,
+				cronExpr: isRecurring ? schedule.cron : null,
+				timezone,
+				payload: options.payload ?? {},
+				context: options.context ?? {},
+				cron: void 0
+			};
+			const callback = () => {
+				Promise.resolve(execute(record)).catch((error) => {
+					console.error(`c8y-nitro: job "${name}" (task "${task}") failed`, error);
+				}).finally(() => {
+					if (!record.cron.nextRun()) jobs.delete(name);
+				});
+			};
+			if (isRecurring) {
+				const cronOptions = { timezone };
+				if (typeof options.maxRuns === "number") cronOptions.maxRuns = options.maxRuns;
+				record.cron = new Cron(schedule.cron, cronOptions, callback);
+			} else {
+				const fireAt = Math.max(resolveOnceDate(schedule).getTime(), Date.now() + 50);
+				record.cron = new Cron(new Date(fireAt), { maxRuns: 1 }, callback);
+			}
+			jobs.set(name, record);
+			if (isRecurring && options.immediate) Promise.resolve(execute(record)).catch((error) => {
+				console.error(`c8y-nitro: job "${name}" immediate run failed`, error);
+			});
+			return toJobInfo(record);
+		},
+		triggerJob(name, options) {
+			const record = jobs.get(name);
+			if (!record) throw new Error(`Job "${name}" is not registered`);
+			return execute(record, options);
+		},
+		cancelJob,
+		listJobs() {
+			return [...jobs.values()].map(toJobInfo);
+		},
+		getJob(name) {
+			const record = jobs.get(name);
+			return record ? toJobInfo(record) : void 0;
+		},
+		hasTask(name) {
+			return tasks.has(name);
+		}
+	};
+	return api;
 }
 //#endregion
-export { cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+export { c8yTasks, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8y-nitro",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -41,8 +41,8 @@
     "c12": "^4.0.0-beta.5",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
+    "croner": "^10.0.1",
     "evlog": "^2.21.0",
-    "itty-time": "^2.0.2",
     "jszip": "^3.10.1",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.1",