@plotday/twister 0.60.0 → 0.62.0

package/src/tools/tasks.ts

@@ -132,4 +132,105 @@ export abstract class Tasks extends ITool {
    * @returns Promise that resolves when all cancellations are processed
    */
   abstract cancelAllTasks(): Promise<void>;
+
+  /**
+   * Schedules a **one-shot singleton** task identified by `key`: scheduling
+   * under a key that already has a pending task atomically cancels the existing
+   * one and replaces it. At most one scheduled task per `key` is ever live.
+   *
+   * Use this for **one-shot keyed deferred work** — a single future task whose
+   * pending occurrence should be atomically replaced if re-scheduled (e.g.
+   * a deferred cleanup, a one-time expiry action, a single future send).
+   *
+   * For **recurring/self-renewing jobs** (watch renewals, polling loops,
+   * periodic syncs, self-heal checks), use {@link scheduleRecurring} instead.
+   * It owns the cadence on the platform side, so the chain survives dropped
+   * runs, suspensions, and deploys without the callback needing to reschedule
+   * itself.
+   *
+   * Replacement is atomic on the server, so concurrent executions racing to
+   * schedule the same key converge on a single task rather than leaking.
+   *
+   * @param key - Stable identifier for this logical task. Scope it to what it
+   *   renews, e.g. `` `watch-renewal:${folderId}` ``.
+   * @param callback - Callback created with `this.callback()`
+   * @param options.runAt - When to run. Required: keying only applies to
+   *   scheduled tasks (immediate tasks go straight to the queue).
+   * @returns Promise resolving to the cancellation token for the scheduled task
+   *
+   * @example
+   * ```typescript
+   * const cb = await this.callback(this.renewWatch, folderId);
+   * await this.scheduleTask(`watch-renewal:${folderId}`, cb, { runAt });
+   * // ...later, on disable:
+   * await this.cancelScheduledTask(`watch-renewal:${folderId}`);
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract scheduleTask(
+    key: string,
+    callback: Callback,
+    options: { runAt: Date }
+  ): Promise<string | void>;
+
+  /**
+   * Cancels the singleton task previously scheduled under `key` (if any).
+   *
+   * No error is thrown if no task exists for the key or it has already run.
+   * Pair this with {@link scheduleTask} in teardown paths (e.g.
+   * `onChannelDisabled`, `stopSync`).
+   *
+   * @param key - The same key passed to {@link scheduleTask}
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract cancelScheduledTask(key: string): Promise<void>;
+
+  /**
+   * Schedules a **durable recurring** task identified by `key`. Unlike
+   * {@link scheduleTask} (one-shot, deleted when it fires), a recurring task's
+   * next occurrence is owned by the platform: the runtime re-arms it every
+   * `intervalMs` automatically, so the chain survives a dropped queue message,
+   * a suspension, a deploy/eviction, or a callback that throws before it could
+   * reschedule. The callback just does the work, idempotently — it does NOT
+   * need to reschedule itself.
+   *
+   * `intervalMs` is a **safety ceiling** (the maximum gap between fires). For
+   * data-dependent cadence (e.g. renew 24h before a provider-returned expiry),
+   * pass `firstRunAt` for the precise next fire and re-call `scheduleRecurring`
+   * with the same key on each run to keep tightening it; the ceiling guarantees
+   * the chain still fires if a run is lost. `firstRunAt` can pull the next fire
+   * earlier than the ceiling but never later.
+   *
+   * Recurring tasks are keyed/singleton: re-scheduling under the same key
+   * atomically replaces the pending occurrence (one live task per key). Tear
+   * down with {@link cancelScheduledTask}.
+   *
+   * @param key - Stable identifier, scoped to what it maintains, e.g.
+   *   `` `watch-renewal:${folderId}` `` or `"mailbox-self-heal"`.
+   * @param callback - Callback created with `this.callback()`.
+   * @param options.intervalMs - Safety-ceiling cadence in milliseconds.
+   * @param options.firstRunAt - Optional precise time for the next fire
+   *   (clamped to no later than now + intervalMs).
+   *
+   * @example
+   * ```typescript
+   * // Fixed cadence (self-heal, polling): register once, never reschedule.
+   * const cb = await this.callback(this.selfHealCheck);
+   * await this.scheduleRecurring("mailbox-self-heal", cb, { intervalMs: 60 * 60 * 1000 });
+   *
+   * // Variable cadence (watch renewal): precise firstRunAt + safety ceiling.
+   * const renew = await this.callback(this.renewWatch, folderId);
+   * await this.scheduleRecurring(`watch-renewal:${folderId}`, renew, {
+   *   intervalMs: 3.5 * 24 * 60 * 60 * 1000,   // ceiling: half the 7-day watch
+   *   firstRunAt: new Date(expiry.getTime() - 24 * 60 * 60 * 1000),
+   * });
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract scheduleRecurring(
+    key: string,
+    callback: Callback,
+    options: { intervalMs: number; firstRunAt?: Date }
+  ): Promise<void>;
 }

package/src/twist.ts

@@ -294,6 +294,59 @@ export abstract class Twist<TSelf> {
     return this.tools.tasks.cancelAllTasks();
   }
 
+  /**
+   * Schedules a **singleton** task keyed by `key`: re-scheduling under the same
+   * key atomically replaces any pending task, so at most one is ever live.
+   *
+   * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs
+   * (watch renewals, polling, deferred cleanup) — it removes the error-prone
+   * "store token, cancel before re-scheduling" bookkeeping that otherwise leaks
+   * parallel task chains. See {@link Tasks.scheduleTask}.
+   *
+   * @param key - Stable identifier scoped to what the task renews
+   * @param callback - The callback token created with `this.callback()`
+   * @param options.runAt - When to run (required)
+   * @returns Promise resolving to the scheduled task's cancellation token
+   */
+  protected async scheduleTask(
+    key: string,
+    callback: Callback,
+    options: { runAt: Date }
+  ): Promise<string | void> {
+    return this.tools.tasks.scheduleTask(key, callback, options);
+  }
+
+  /**
+   * Cancels the singleton task previously scheduled under `key` (if any).
+   * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.
+   *
+   * @param key - The same key passed to {@link scheduleTask}
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  protected async cancelScheduledTask(key: string): Promise<void> {
+    return this.tools.tasks.cancelScheduledTask(key);
+  }
+
+  /**
+   * Schedules a durable recurring task under a stable key. The platform
+   * re-arms the task every `intervalMs` automatically — the callback does NOT
+   * need to reschedule itself. Re-scheduling under the same key atomically
+   * replaces the pending occurrence (at most one live task per key). Tear down
+   * with {@link cancelScheduledTask}. See {@link Tasks.scheduleRecurring}.
+   *
+   * @param key - Stable identifier, e.g. `"mailbox-self-heal"`
+   * @param callback - Callback token created with `this.callback()`
+   * @param options.intervalMs - Safety-ceiling cadence in milliseconds
+   * @param options.firstRunAt - Optional precise time for the next fire
+   */
+  protected async scheduleRecurring(
+    key: string,
+    callback: Callback,
+    options: { intervalMs: number; firstRunAt?: Date }
+  ): Promise<void> {
+    return this.tools.tasks.scheduleRecurring(key, callback, options);
+  }
+
   /**
    * Called when the twist is installed by a user.
    *