c8y-nitro 0.7.1 → 0.8.0

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.1",
+  "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",

package/dist/options-B7_yb_wr.mjs

@@ -1,147 +0,0 @@
-import { c as getTenantOptionsByCategory, f as upsertTenantOption, i as deleteTenantOption, n as createBasicAuthHeader, p as createC8yManifest, s as getTenantOption } from "./c8y-api-BFjK6AYb.mjs";
-import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
-import { defineCommand } from "citty";
-import { consola } from "consola";
-//#region src/cli/commands/options.ts
-var options_default = defineCommand({
-	meta: {
-		name: "options",
-		description: "Manage tenant options on the development tenant"
-	},
-	args: {},
-	async run() {
-		consola.info("Loading configuration...");
-		const { env, nitroConfig, configDir } = await loadC8yConfig();
-		consola.info("Validating environment variables...");
-		const envVars = validateBootstrapEnv(env);
-		consola.info("Loading manifest...");
-		const manifest = await createC8yManifest(configDir, nitroConfig);
-		const category = manifest.settingsCategory || manifest.contextPath || manifest.name;
-		if (!manifest.settings || manifest.settings.length === 0) throw new Error("No settings defined in manifest. Add settings to your c8y.manifest configuration.");
-		consola.success(`Using category: ${category}`);
-		const authHeader = createBasicAuthHeader(envVars.C8Y_DEVELOPMENT_TENANT, envVars.C8Y_DEVELOPMENT_USER, envVars.C8Y_DEVELOPMENT_PASSWORD);
-		consola.info("Fetching current tenant options...");
-		const currentOptions = await getTenantOptionsByCategory(envVars.C8Y_BASEURL, category, authHeader);
-		const availableKeys = manifest.settings.map((s) => s.key);
-		consola.success(`Found ${Object.keys(currentOptions).length} options set on tenant`);
-		const action = await consola.prompt("What do you want to do?", {
-			type: "select",
-			options: [
-				{
-					label: "Read option value",
-					value: "read"
-				},
-				{
-					label: "Update/Create option",
-					value: "update"
-				},
-				{
-					label: "Delete option(s)",
-					value: "delete"
-				}
-			]
-		});
-		if (action === "read") await handleRead(envVars.C8Y_BASEURL, category, authHeader, availableKeys, currentOptions);
-		else if (action === "update") await handleUpdate(envVars.C8Y_BASEURL, category, authHeader, availableKeys, currentOptions);
-		else if (action === "delete") await handleDelete(envVars.C8Y_BASEURL, category, authHeader, availableKeys, currentOptions);
-	}
-});
-/**
-* Handle reading a single option
-* @param baseUrl - The Cumulocity base URL
-* @param category - The tenant option category
-* @param authHeader - The Basic Auth header
-* @param availableKeys - List of available option keys
-* @param currentOptions - Current option values from tenant
-*/
-async function handleRead(baseUrl, category, authHeader, availableKeys, currentOptions) {
-	const setKeys = availableKeys.filter((k) => !k.startsWith("credentials.") && currentOptions[k] !== void 0);
-	const credentialsKeys = availableKeys.filter((k) => k.startsWith("credentials."));
-	const allKeys = [...setKeys, ...credentialsKeys];
-	if (allKeys.length === 0) {
-		consola.warn("No options are currently set");
-		return;
-	}
-	if (credentialsKeys.length > 0) consola.warn("Encrypted credentials.* options cannot be read in decrypted form with the development user in this CLI.");
-	const key = await consola.prompt("Select option to read:", {
-		type: "select",
-		options: allKeys.map((k) => ({
-			label: k.startsWith("credentials.") ? `${k} (unknown)` : k,
-			value: k
-		})),
-		cancel: "reject"
-	});
-	consola.info(`Reading option: ${key}`);
-	const value = await getTenantOption(baseUrl, category, key, authHeader);
-	if (value === void 0) consola.warn(`Option '${key}' is not set`);
-	else consola.success(`Value: ${value}`);
-}
-/**
-* Handle updating options (with loop for multiple updates)
-* @param baseUrl - The Cumulocity base URL
-* @param category - The tenant option category
-* @param authHeader - The Basic Auth header
-* @param availableKeys - List of available option keys
-* @param currentOptions - Current option values from tenant
-*/
-async function handleUpdate(baseUrl, category, authHeader, availableKeys, currentOptions) {
-	let continueUpdating = true;
-	while (continueUpdating) {
-		const key = await consola.prompt("Select option to update:", {
-			type: "select",
-			options: availableKeys.map((k) => ({
-				label: currentOptions[k] !== void 0 ? `${k} (current: ${currentOptions[k]})` : k.startsWith("credentials.") ? `${k} (current: unknown)` : `${k} (not set)`,
-				value: k
-			})),
-			cancel: "reject"
-		});
-		const currentValue = currentOptions[key];
-		const newValue = await consola.prompt("Enter new value:", {
-			type: "text",
-			default: currentValue,
-			cancel: "reject"
-		});
-		consola.info(`Updating option: ${key}`);
-		await upsertTenantOption(baseUrl, category, key, newValue, authHeader);
-		currentOptions[key] = newValue;
-		consola.success(`Option '${key}' updated successfully`);
-		if (!await consola.prompt("Update another option?", {
-			type: "confirm",
-			initial: false,
-			cancel: "reject"
-		})) continueUpdating = false;
-	}
-}
-/**
-* Handle deleting multiple options
-* @param baseUrl - The Cumulocity base URL
-* @param category - The tenant option category
-* @param authHeader - The Basic Auth header
-* @param availableKeys - List of available option keys
-* @param currentOptions - Current option values from tenant
-*/
-async function handleDelete(baseUrl, category, authHeader, availableKeys, currentOptions) {
-	const setKeys = availableKeys.filter((k) => !k.startsWith("credentials.") && currentOptions[k] !== void 0);
-	const credentialsKeys = availableKeys.filter((k) => k.startsWith("credentials."));
-	const allKeys = [...setKeys, ...credentialsKeys];
-	if (allKeys.length === 0) {
-		consola.warn("No options are currently set");
-		return;
-	}
-	const keysToDelete = await consola.prompt("Select option(s) to delete:", {
-		type: "multiselect",
-		options: allKeys,
-		required: true,
-		cancel: "reject"
-	});
-	consola.info(`Deleting ${keysToDelete.length} option(s)...`);
-	for (const key of keysToDelete) {
-		consola.info(`Deleting option: ${key}`);
-		await deleteTenantOption(baseUrl, category, key, authHeader);
-		delete currentOptions[key];
-		consola.success(`✓ Deleted: ${key}`);
-	}
-	consola.success("Delete operation completed");
-}
-//#endregion
-export { options_default as default };