c8y-nitro 0.7.2 → 0.9.0

package/dist/utils.d.mts

@@ -1,9 +1,10 @@
 import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
-import { Client, ICredentials, ICurrentUser } from "@c8y/client";
+import { RealtimeClient } from "c8y-realtime";
+import { Client, ICredentials, ICurrentUser, IResultList } from "@c8y/client";
 import { createError as createError$1, createLogger } from "evlog";
 import { EventHandler, H3Event, HTTPEvent } from "nitro/h3";
 import { ServerRequest, TaskContext, TaskPayload } from "nitro/types";
-import { C8YRoles, C8YSettingsCategory, C8YTenantOptionKey } from "c8y-nitro/types";
+import { C8YRole, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey } from "c8y-nitro/types";
 //#region src/utils/client.d.ts
 /**
  * Creates a Cumulocity client authenticated with the current user's credentials.\
@@ -51,8 +52,98 @@ declare function useSubscribedTenantClients(): Promise<Record<string, Client>>;
  */
 declare function useDeployedTenantClient(): Promise<Client>;
 //#endregion
+//#region src/utils/paging.d.ts
+/**
+ * The first page of a Cumulocity list result, in any of the shapes a caller
+ * naturally has on hand:
+ *
+ * - an already-awaited {@link IResultList} (`await client.inventory.list(...)`)
+ * - the pending `list()` promise itself (`client.inventory.list(...)`)
+ * - a thunk that produces it lazily (`() => client.inventory.list(...)`)
+ *
+ * Only the first page has to be supplied. Every subsequent page is fetched via
+ * the result's own `paging.next()`, which re-uses the exact client, auth, and
+ * filter that produced the first page — so there is no client to pass and no
+ * ambiguity between user, tenant, or microservice clients.
+ */
+type PageSource<T> = IResultList<T> | Promise<IResultList<T>> | (() => IResultList<T> | Promise<IResultList<T>>);
+/**
+ * Optional safety guards for walking large or unbounded Cumulocity collections.
+ */
+interface PagingOptions {
+  /**
+   * Stop after fetching this many pages. Guards against runaway iteration over
+   * unexpectedly large collections. Unlimited when omitted.
+   */
+  maxPages?: number;
+  /**
+   * Stop once this many items have been produced. The page that crosses the
+   * limit is truncated so exactly `maxItems` items are yielded. Unlimited when
+   * omitted.
+   */
+  maxItems?: number;
+}
+/**
+ * Lazily walks a Cumulocity list result page by page, yielding each page's data
+ * array. This is the engine behind {@link paginate} and {@link fetchAllPages}.
+ *
+ * Pages are fetched on demand: the next request is only issued when the consumer
+ * asks for the next value. Iteration stops when a page comes back shorter than
+ * the requested page size (Cumulocity's signal that there is no more data),
+ * when the result carries no paging information, or when a {@link PagingOptions}
+ * guard is hit.
+ *
+ * @param source - The first page (result, promise, or thunk). See {@link PageSource}.
+ * @param options - Optional {@link PagingOptions} safety guards.
+ * @yields Each page as an array of items.
+ * @example
+ * // Process one page at a time (e.g. bulk insert per page):
+ * for await (const page of paginatePages(client.event.list({ pageSize: 2000 }))) {
+ *   await bulkInsert(page)
+ * }
+ */
+declare function paginatePages<T>(source: PageSource<T>, options?: PagingOptions): AsyncGenerator<T[]>;
+/**
+ * Lazily iterates every item across all pages of a Cumulocity list result,
+ * yielding one entry at a time — ideal for streaming large collections with a
+ * low memory footprint.
+ *
+ * Pages are fetched on demand as iteration advances, walking via the result's
+ * own `paging.next()` (same client and filter as the first page). Iteration
+ * stops when a page comes back shorter than the requested page size.
+ *
+ * @param source - The first page (result, promise, or thunk). See {@link PageSource}.
+ * @param options - Optional {@link PagingOptions} safety guards.
+ * @yields Each item, in order, across all pages.
+ * @example
+ * // Stream every active alarm, one at a time:
+ * for await (const alarm of paginate(() => client.alarm.list({ pageSize: 2000, status: 'ACTIVE' }))) {
+ *   await handleAlarm(alarm)
+ * }
+ */
+declare function paginate<T>(source: PageSource<T>, options?: PagingOptions): AsyncGenerator<T>;
+/**
+ * Collects every item across all pages of a Cumulocity list result into a single
+ * array, awaiting until all pages have been fetched.
+ *
+ * Walks via the result's own `paging.next()` (same client and filter as the
+ * first page), stopping when a page comes back shorter than the requested page
+ * size. For very large collections prefer {@link paginate} to avoid holding
+ * every item in memory at once, or cap the result with
+ * {@link PagingOptions.maxItems}.
+ *
+ * @param source - The first page (result, promise, or thunk). See {@link PageSource}.
+ * @param options - Optional {@link PagingOptions} safety guards.
+ * @returns All items across all pages, in order.
+ * @example
+ * // Fetch every managed object matching a fragment:
+ * const client = useUserClient(event)
+ * const all = await fetchAllPages(client.inventory.list({ pageSize: 2000, fragmentType: 'c8y_Sensor' }))
+ */
+declare function fetchAllPages<T>(source: PageSource<T>, options?: PagingOptions): Promise<T[]>;
+//#endregion
 //#region src/utils/middleware.d.ts
-type UserRole = keyof C8YRoles | (string & {});
+type UserRole = keyof C8YRoles | C8YRole;
 /**
  * Middleware to check if the current user has the required role.\
  * If the user doesn't have the required role, throws a 403 Forbidden error.\
@@ -502,110 +593,288 @@ 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
+/**
+ * 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 JobConcurrency = 'single' | 'parallel';
+type TaskRegistryPayload = TaskPayload;
+type TaskRegistryContext = TaskContext;
+/**
+ * The event passed to a task handler on every execution.
+ */
+interface TaskEvent<TPayload = TaskRegistryPayload> {
+  /**
+   * Name of the task (function) being executed.
+   */
+  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 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.
+ * A task handler function registered via {@link TaskRegistry.createTask}.
  */
-type ScheduledTaskInput = Date | number | string;
+type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: TaskEvent<TPayload>) => TResult | Promise<TResult>;
 /**
- * Options for scheduling a Nitro task to run once in the future.\
- * `payload` and `context` are forwarded to the task handler's `run()` method.
+ * 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, from now — either a number of seconds (`{ in: 30 }`) or a
+ *   human duration string (`{ in: '5 minutes' }`, `{ in: '1 hour' }`).
+ * - `{ 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.
  */
-interface ScheduleTaskOptions {
+type JobSchedule = {
+  cron: string;
+} | {
+  in: number | string;
+} | {
+  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;
   /**
-   * Payload forwarded to the task handler's `TaskEvent.payload`.
+   * Name of a task registered via `createTask()` that this job runs.
    */
-  payload?: ScheduledTaskPayload;
+  task: TTask;
   /**
-   * Context forwarded to the task handler's `TaskEvent.context`.
+   * When the job should run.
    */
-  context?: ScheduledTaskContext;
+  schedule: TSchedule;
   /**
-   * When the task should run. Numbers are seconds from now.
+   * 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.
    */
-  schedule: ScheduledTaskInput;
+  payload?: TPayload;
+  /**
+   * Data forwarded to the handler's `event.context`.
+   */
+  context?: TaskRegistryContext;
+  /**
+   * Concurrency policy for this job. Defaults to `'single'`.
+   */
+  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.
    */
-  runAt: string;
+  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.
+   */
+  running: boolean;
+}
+/**
+ * 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 }`).
+ */
+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[];
 }
 /**
- * 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.
+ * Public information about a registered job. A discriminated union on `kind` —
+ * returned by `scheduleJob()`, `getJob()` and `listJobs()`.
+ */
+type JobInfo = OnceJobInfo | RecurringJobInfo;
+/**
+ * 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 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
+ * 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
- * // Run a task in 30 seconds:
- * const scheduled = await scheduleTask('emails:send', {
- *   payload: { messageId: 'abc123' },
- *   schedule: 30,
- * })
+ * import { c8yTasks } from 'c8y-nitro/utils'
  *
- * @example
- * // Run a task using a human-readable duration:
- * await scheduleTask('reports:generate', {
- *   payload: { reportId: 'report-1' },
- *   schedule: '1 hour',
- * })
+ * export const tasks = c8yTasks()
+ *   .createTask('sync', async ({ payload }) => {
+ *     const config = await loadConfig(payload.configId) // resolve live state here
+ *     await sync(config)
+ *   })
  *
- * @example
- * // Run a task at an exact time:
- * await scheduleTask('cleanup:tenant', {
- *   payload: { tenant: 't12345' },
- *   schedule: new Date('2026-05-01T12:00:00Z'),
- * })
+ * // 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' })
+ *
+ * @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 scheduleTask(taskName: string, options: ScheduleTaskOptions): Promise<ScheduledTaskInfo>;
+declare function c8yTasks(): TaskRegistry;
+//#endregion
+//#region src/utils/realtime.d.ts
 /**
- * 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)
- * }
+ * Anything a caller might already have on hand that identifies a tenant, from
+ * which {@link useTenantRealtimeClient} resolves the tenant's service
+ * credentials: a tenant id, that tenant's credentials, a `@c8y/client` scoped to
+ * it, or the current request.
  */
-declare function listScheduledTasks(): Promise<Record<string, ScheduledTaskInfo>>;
+type TenantRealtimeInput = string | ICredentials | Client | H3Event | ServerRequest;
 /**
- * Cancels a scheduled task before it starts running.\
- * Once the underlying Nitro task has started, it cannot be cancelled with this utility.
- *
- * @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
- * @returns `true` when a pending task was cancelled, otherwise `false`
+ * Get the pooled Notification 2.0 realtime client for a tenant, creating it on
+ * first use and reusing it after. Accepts whatever identifies the tenant — a
+ * tenant id, that tenant's credentials, a `@c8y/client`, or the current request
+ * — and always connects with the tenant's **service** credentials.
  *
+ * Register handlers directly on the returned client (see `c8y-realtime`):
  * @example
- * const scheduled = await scheduleTask('emails:send', {
- *   payload: { messageId: 'abc123' },
- *   schedule: '10 minutes',
- * })
- *
- * const cancelled = await cancelScheduledTask(scheduled.id)
+ * const rt = await useTenantRealtimeClient(event)
+ * rt.alarms.onCreate('*', alarm => log.info(alarm.severity, alarm.text))
+ * rt.measurements.onCreate('device42', m => log.info(m.type, m.time))
+ * @param input - A tenant id, `ICredentials`, a `Client`, or an `H3Event`/`ServerRequest`.
  */
-declare function cancelScheduledTask(id: string): Promise<boolean>;
+declare function useTenantRealtimeClient(input: TenantRealtimeInput): Promise<RealtimeClient>;
 //#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, PageSource, PagingOptions, RecurringJobInfo, ScheduleJobOptions, SetEditableOptions, TaskEvent, TaskHandler, TaskMap, TaskRegistry, TaskRegistryContext, TaskRegistryPayload, TaskShape, TenantOption, TenantOptionCategory, TenantOptionKeyInput, type TenantRealtimeInput, c8yTasks, createError, createLogger, fetchAllPages, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, paginate, paginatePages, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useTenantRealtimeClient, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };