tina4-nodejs 3.11.17 → 3.11.18

package/packages/core/src/background.ts

@@ -0,0 +1,114 @@
+/**
+ * Background tasks — periodic callbacks that run alongside the HTTP server.
+ *
+ * Mirrors Python's `tina4_python.core.server.background(fn, interval=1.0)`.
+ * Use this instead of `setInterval` directly, so timers integrate with the
+ * server lifecycle and clear cleanly on graceful shutdown (SIGTERM/SIGINT)
+ * or when `stopAllBackgroundTasks()` is called.
+ *
+ *   import { background } from "@tina4/core";
+ *
+ *   background(() => processQueue(), 2);          // every 2 seconds
+ *   background(async () => await healthCheck(), 30);  // async also fine
+ *
+ * Errors thrown from a callback are caught and logged so a single failing
+ * task cannot bring down the rest of the timer wheel.
+ */
+
+import { Log } from "./logger.js";
+
+/** A registered background task — kept so `stopAllBackgroundTasks()` can clear them. */
+interface BackgroundTask {
+  callback: () => unknown | Promise<unknown>;
+  intervalSeconds: number;
+  timer: NodeJS.Timeout;
+}
+
+const _tasks: BackgroundTask[] = [];
+let _signalsBound = false;
+
+/**
+ * Register signal handlers exactly once so SIGTERM/SIGINT during a long-running
+ * process clears all background timers before the runtime exits. The handler
+ * is additive — it does not call `process.exit()` or interfere with other
+ * shutdown logic registered by the CLI or user code.
+ */
+function _bindSignalsOnce(): void {
+  if (_signalsBound) return;
+  _signalsBound = true;
+  const cleanup = () => stopAllBackgroundTasks();
+  process.on("SIGTERM", cleanup);
+  process.on("SIGINT", cleanup);
+}
+
+/**
+ * Register a callback to run periodically alongside the HTTP server.
+ *
+ * @param callback         Function to call (sync or async, no arguments).
+ * @param intervalSeconds  Seconds between invocations (default: 1).
+ * @returns A handle whose `stop()` clears just this one task.
+ */
+export function background(
+  callback: () => unknown | Promise<unknown>,
+  intervalSeconds = 1,
+): { stop: () => void } {
+  if (typeof callback !== "function") {
+    throw new TypeError("background(callback, interval): callback must be a function");
+  }
+  if (typeof intervalSeconds !== "number" || !isFinite(intervalSeconds) || intervalSeconds <= 0) {
+    throw new RangeError(
+      `background(callback, interval): interval must be a positive number (got ${intervalSeconds})`,
+    );
+  }
+
+  _bindSignalsOnce();
+
+  const ms = Math.max(1, Math.round(intervalSeconds * 1000));
+  const timer = setInterval(() => {
+    try {
+      const result = callback();
+      if (result && typeof (result as Promise<unknown>).then === "function") {
+        (result as Promise<unknown>).catch((err) => {
+          Log.error?.(`background task error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+      }
+    } catch (err) {
+      Log.error?.(`background task error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }, ms);
+
+  // Don't keep the event loop alive solely for background tasks — this matches
+  // Python's behaviour, where background tasks live in the server's loop and
+  // exit with it rather than blocking shutdown.
+  if (typeof timer.unref === "function") {
+    timer.unref();
+  }
+
+  const task: BackgroundTask = { callback, intervalSeconds, timer };
+  _tasks.push(task);
+
+  return {
+    stop: () => {
+      clearInterval(task.timer);
+      const idx = _tasks.indexOf(task);
+      if (idx !== -1) _tasks.splice(idx, 1);
+    },
+  };
+}
+
+/**
+ * Clear every registered background task. Called automatically on SIGTERM/SIGINT;
+ * also called from the server's `close()` so a manual server shutdown stops
+ * the timer wheel along with HTTP listeners.
+ */
+export function stopAllBackgroundTasks(): void {
+  while (_tasks.length > 0) {
+    const task = _tasks.pop()!;
+    clearInterval(task.timer);
+  }
+}
+
+/** Number of currently-registered background tasks (test helper). */
+export function backgroundTaskCount(): number {
+  return _tasks.length;
+}

package/packages/core/src/index.ts

@@ -13,6 +13,7 @@ export type {
 } from "./types.js";
 
 export { startServer, resolvePortAndHost, handle, start, stop } from "./server.js";
+export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
 export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";

package/packages/core/src/server.ts

@@ -20,6 +20,7 @@ import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector } from "./devAdmin.js";
 import { I18n } from "./i18n.js";
+import { stopAllBackgroundTasks } from "./background.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -549,6 +550,7 @@ ${reset}
       // Return a handle that kills all workers
       return {
         close: () => {
+          stopAllBackgroundTasks();
           for (const id in cluster.workers) {
             cluster.workers[id]?.kill();
           }
@@ -1075,6 +1077,8 @@ ${reset}
       }
       resolvePromise({
         close: () => {
+          // Clear any registered background timers so graceful shutdown actually exits.
+          stopAllBackgroundTasks();
           if (aiServer) aiServer.close();
           server.close();
           // Close database if ORM was initialized