tina4-nodejs 3.13.91 → 3.13.94

package/types/core/src/response.d.ts

@@ -0,0 +1,28 @@
+import type { ServerResponse } from "node:http";
+import type { Tina4Response } from "./types.js";
+/**
+ * Set the default templates directory for render().
+ * Called by server.ts during startup.
+ */
+export declare function setDefaultTemplatesDir(dir: string): void;
+/**
+ * Return the global Frond engine, creating a default if needed.
+ */
+export declare function getFrond(): Promise<InstanceType<any>>;
+/**
+ * Return the singleton Frond engine for built-in framework templates.
+ * Syncs custom filters/globals from the user engine.
+ */
+export declare function getFrameworkFrond(): Promise<InstanceType<any> | null>;
+/**
+ * Register a pre-configured Frond engine for response.render().
+ */
+export declare function setFrond(engine: InstanceType<any>): void;
+export declare function createResponse(res: ServerResponse): Tina4Response;
+/**
+ * Build a standard error response envelope (standalone helper).
+ *
+ * Usage:
+ *   return response(errorResponse("VALIDATION_FAILED", "Email is required", 400), 400);
+ */
+export declare function errorResponse(code: string, message: string, status?: number): Record<string, unknown>;

package/types/core/src/routeDiscovery.d.ts

@@ -0,0 +1,12 @@
+import type { RouteDefinition } from "./types.js";
+export declare function discoverRoutes(routesDir: string): Promise<RouteDefinition[]>;
+/**
+ * Re-run the most recent route scan — called by POST /__dev/api/reload so a
+ * newly-added OR edited file in src/routes/ registers without a server restart.
+ * A file is re-imported when it's new or its mtime increased; unchanged files
+ * are skipped. The router replaces routes by pattern, so a re-imported route
+ * overwrites the stale handler. No-op if discoverRoutes() has never been called.
+ */
+export declare function rediscoverRoutes(): Promise<RouteDefinition[]>;
+/** Test-only: reset the seen-files state so tests can replay the same dir. */
+export declare function _resetRouteDiscovery(): void;

package/types/core/src/router.d.ts

@@ -0,0 +1,355 @@
+import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, MiddlewareSpec, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
+/**
+ * Whether `TINA4_TRAILING_SLASH_REDIRECT` is enabled.
+ *
+ * Default: false. When true, a request to `/foo/` that has no exact match
+ * but matches `/foo` will be treated as a hit on `/foo` — callers can use
+ * the returned pattern to issue a 308 redirect (Python parity).
+ */
+export declare function isTrailingSlashRedirectEnabled(): boolean;
+interface MatchResult {
+    handler: RouteHandler;
+    params: Record<string, string | number>;
+    pattern: string;
+    meta?: RouteMeta;
+    middlewares?: MiddlewareSpec[];
+    template?: string;
+    secure?: boolean;
+    cached?: boolean;
+    noAuth?: boolean;
+}
+interface CompiledRoute {
+    pattern: string;
+    regex: RegExp;
+    paramNames: string[];
+    paramTypes: string[];
+    handler: RouteHandler;
+    meta?: RouteMeta;
+    filePath?: string;
+    middlewares?: MiddlewareSpec[];
+    secure?: boolean;
+    cached?: boolean;
+    noAuth?: boolean;
+    cacheStore?: Map<string, {
+        data: unknown;
+        expires: number;
+    }>;
+    cacheTtl?: number;
+    template?: string;
+}
+/**
+ * Thin reference to a registered WebSocket route, enabling chained modifiers
+ * — the WS analogue of {@link RouteRef}.
+ *
+ * Usage:
+ *   router.websocket("/ws/secure", handler).secure();
+ */
+export declare class WsRouteRef {
+    private route;
+    constructor(route: WebSocketRouteDefinition);
+    /** Mark this WS route as requiring a valid JWT on the upgrade handshake. */
+    secure(): this;
+}
+/**
+ * Thin reference to a registered route, enabling chained modifiers.
+ *
+ * Usage:
+ *   router.get("/api/data", handler).secure().cache();
+ */
+export declare class RouteRef {
+    private route;
+    constructor(route: CompiledRoute);
+    /** Mark this route as requiring bearer-token authentication. */
+    secure(): this;
+    /** Opt out of secure-by-default auth (for public write routes). */
+    noAuth(): this;
+    /** Mark this route's response as cacheable. */
+    cache(): this;
+    /**
+     * Append middleware to this route. Accepts middleware functions and/or
+     * string specs (e.g. `"ResponseCache:300"`), resolved when the route runs.
+     */
+    middleware(...middlewareClasses: MiddlewareSpec[]): this;
+}
+export interface RouteInfo {
+    method: string;
+    path: string;
+    handler: string;
+    middlewareCount: number;
+    cached: boolean;
+    secure: boolean;
+}
+export declare class Router {
+    private routes;
+    private wsRoutes;
+    /** Class-based middleware registered via `use()` / `Router.use()`. */
+    private static _classMiddlewares;
+    /**
+     * Register a class-based middleware (beforeX / afterX convention).
+     * Classes are stored globally and executed by MiddlewareRunner.
+     */
+    static use(middlewareClass: any): void;
+    /**
+     * Get all registered class-based middleware classes.
+     */
+    static getClassMiddlewares(): any[];
+    /**
+     * Clear all registered class-based middleware (useful for testing).
+     */
+    static clearClassMiddlewares(): void;
+    /**
+     * Add a raw route definition (used internally and by file-based routing).
+     */
+    addRoute(definition: RouteDefinition): RouteRef;
+    /**
+     * Register a GET route programmatically.
+     */
+    get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a POST route programmatically.
+     */
+    post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a PUT route programmatically.
+     */
+    put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a PATCH route programmatically.
+     */
+    patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a DELETE route programmatically.
+     */
+    delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register an explicit HEAD route. By default the framework auto-handles
+     * HEAD by falling back to the GET route and stripping the body
+     * (RFC 9110 §9.3.2). Use this only when you need a HEAD handler that
+     * does something different from GET — e.g. cheaper existence-check
+     * logic, custom validator headers without the cost of building the body.
+     * The framework still strips the response body for you on the way out.
+     */
+    head(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register an explicit OPTIONS route. By default the framework auto-
+     * handles OPTIONS by building an Allow header from every method
+     * registered for the path and returning 204 (RFC 9110 §9.3.7). Use
+     * this to take over that behaviour.
+     */
+    options(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a route that matches ANY HTTP method.
+     */
+    any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Create a route group with a shared prefix and optional middlewares.
+     */
+    group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void;
+    /**
+     * Match a request method + pathname to a registered route.
+     *
+     * When `TINA4_TRAILING_SLASH_REDIRECT=true` and the request path ends in
+     * a trailing slash that doesn't match a registered route, retry without
+     * the trailing slash. Returning the de-slashed pattern lets callers issue
+     * a 308 redirect instead of a hard 404 — Python parity.
+     */
+    match(method: string, path: string): MatchResult | null;
+    /**
+     * Return the list of HTTP methods registered for ``path``, in canonical
+     * order GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS. Used by the
+     * dispatcher to build the ``Allow:`` header on 405 / OPTIONS responses
+     * (RFC 9110 §10.2.1, §9.3.7).
+     *
+     * If GET is registered, HEAD is appended implicitly (HEAD auto-fallback).
+     * OPTIONS is appended whenever any method exists for the path (the
+     * framework auto-handles OPTIONS).
+     */
+    methodsAllowedForPath(path: string): string[];
+    /** Inner match against a list of compiled routes, no trailing-slash logic. */
+    private matchRoute;
+    /**
+     * Get all registered route definitions.
+     */
+    getRoutes(): RouteDefinition[];
+    /** Alias for getRoutes(). */
+    allRoutes(): RouteDefinition[];
+    /**
+     * List all routes in a debug-friendly format for CLI output.
+     */
+    listRoutes(): RouteInfo[];
+    /**
+     * Register a WebSocket route.
+     *
+     * A WS route is PUBLIC by default (mirrors GET). It can be marked secured in
+     * EITHER way the HTTP routes support:
+     *   • imperatively — `websocket(path, fn, { secured: true })`, or chain the
+     *     returned ref: `websocket(path, fn).secure()`;
+     *   • decorator-style — a `_secured` flag on the handler function, set in
+     *     either order relative to registration (the ref keeps a back-reference
+     *     to the route so a later `.secure()` / `_secured` still flips it).
+     *
+     * When secured, the upgrade handshake requires a valid JWT (Authorization
+     * header / `bearer` subprotocol / `?token=`) or the upgrade is rejected.
+     */
+    websocket(path: string, handler: WebSocketRouteHandler, options?: {
+        secured?: boolean;
+    }): WsRouteRef;
+    /**
+     * Get all registered WebSocket route definitions.
+     */
+    getWebSocketRoutes(): WebSocketRouteDefinition[];
+    /**
+     * Match a WebSocket upgrade request path to a registered ws route.
+     * Returns the route only; use {@link matchWebSocketWithParams} when the
+     * upgrade handler needs the extracted `{param}` values.
+     */
+    matchWebSocket(pathname: string): WebSocketRouteDefinition | null;
+    /**
+     * Match a WebSocket upgrade path AND extract its `{param}` values, using the
+     * same pattern compiler as HTTP routes. A literal pattern (`/ws/chat`) still
+     * matches exactly with empty params; a parameterised pattern
+     * (`/ws/rtc/{room}`) matches `/ws/rtc/abc` and yields `{ room: "abc" }`.
+     * (Previously WS matching was exact-string only, so `{param}` routes never
+     * matched and `connection.params` was always empty.)
+     */
+    matchWebSocketWithParams(pathname: string): {
+        route: WebSocketRouteDefinition;
+        params: Record<string, string>;
+    } | null;
+    clear(): void;
+    /**
+     * Register a route for a specific HTTP method.
+     * Core registration method — all convenience methods delegate here.
+     */
+    static add(method: string, path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a GET route on the default global router.
+     */
+    static get(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a POST route on the default global router.
+     */
+    static post(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a PUT route on the default global router.
+     */
+    static put(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a PATCH route on the default global router.
+     */
+    static patch(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a DELETE route on the default global router.
+     */
+    static delete(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a route that matches ANY HTTP method on the default global router.
+     */
+    static any(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a WebSocket route on the default global router.
+     */
+    static websocket(path: string, handler: WebSocketRouteHandler, options?: {
+        secured?: boolean;
+    }): WsRouteRef;
+    /**
+     * Match a WebSocket upgrade path against routes on the default global router.
+     * Returns the matched route definition (with its `authRequired` flag) or null.
+     */
+    static matchWebSocket(pathname: string): WebSocketRouteDefinition | null;
+    static matchWebSocketWithParams(pathname: string): {
+        route: WebSocketRouteDefinition;
+        params: Record<string, string>;
+    } | null;
+    /** All WebSocket route definitions on the default global router. */
+    static getWebSocketRoutes(): WebSocketRouteDefinition[];
+    /**
+     * Create a route group on the default global router.
+     */
+    static group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void;
+    /**
+     * Supported typed-parameter constraints. Mirrored verbatim in
+     * tina4-python / tina4-php / tina4-ruby for cross-framework parity.
+     *
+     * Any type name not in this table throws at route registration time —
+     * we never silently fall through to the default matcher, because a
+     * typo like `{id:inetger}` would otherwise match anything and create
+     * a security footgun (see tina4-book#125).
+     */
+    private static readonly PARAM_TYPE_PATTERNS;
+    private compilePattern;
+}
+/**
+ * Route group for grouping routes under a shared prefix with optional middlewares.
+ */
+export declare class RouteGroup {
+    private router;
+    private prefix;
+    private groupMiddlewares?;
+    constructor(router: Router, prefix: string, groupMiddlewares?: MiddlewareSpec[] | undefined);
+    private mergeMiddlewares;
+    get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Nested groups.
+     */
+    group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void;
+}
+/**
+ * Resolve a string-form middleware spec to a middleware function.
+ *
+ * Forms (parity with Python/PHP/Ruby):
+ *   "ResponseCache"      → responseCache() with the default/env TTL
+ *   "ResponseCache:300"  → responseCache({ ttl: 300 })
+ *
+ * The head before the first ":" names the middleware; any trailing
+ * colon-separated parts are its arguments (numeric parts are parsed as
+ * integers). Unknown names throw so a typo surfaces instead of silently
+ * dropping the middleware. `responseCache` is loaded via a dynamic import so
+ * the router carries no import-time dependency on the cache module.
+ *
+ * Exported so route dispatch (and tests) can turn a spec into a runnable
+ * middleware.
+ */
+export declare function resolveStringMiddleware(spec: string): Promise<Middleware>;
+/**
+ * Run per-route middleware chain, then call the handler.
+ *
+ * Accepts middleware functions and/or string specs (e.g. "ResponseCache:300").
+ * Each spec is resolved to a middleware function just before it runs.
+ */
+export declare function runRouteMiddlewares(middlewares: MiddlewareSpec[], req: Tina4Request, res: Tina4Response): Promise<boolean>;
+/**
+ * Default global router instance.
+ * Top-level get(), post(), etc. register routes here.
+ * The server merges these routes on startup.
+ */
+export declare const defaultRouter: Router;
+/**
+ * Top-level route registration functions — mirrors Python's decorator pattern.
+ *
+ * Usage:
+ *   import { get, post } from "@tina4/core";
+ *
+ *   get("/hello", async (req, res) => {
+ *     res.json({ message: "Hello" });
+ *   });
+ *
+ *   post("/users/{id}", async (req, res) => {
+ *     res.json({ id: req.params.id }, 201);
+ *   });
+ */
+export declare function get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function del(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function websocket(path: string, handler: WebSocketRouteHandler, options?: {
+    secured?: boolean;
+}): WsRouteRef;
+export { del as delete };

package/types/core/src/scss.d.ts

@@ -0,0 +1,19 @@
+export interface ScssConfig {
+    importPaths?: string[];
+    variables?: Record<string, string>;
+}
+export declare class ScssCompiler {
+    private _importPaths;
+    private _variables;
+    constructor(config?: ScssConfig);
+    /** Compile an SCSS string to CSS. */
+    compile(source: string): string;
+    /** Compile an SCSS file to CSS. */
+    compileFile(filePath: string): string;
+    /** Add a directory to the import resolution path. */
+    addImportPath(path: string): void;
+    /** Set or override an SCSS variable. */
+    setVariable(name: string, value: string): void;
+    /** Compile all .scss files in a directory into a single CSS output file. */
+    compileScss(scssDir?: string, output?: string, minify?: boolean): string;
+}

package/types/core/src/server.d.ts

@@ -0,0 +1,131 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import type { Tina4Config } from "./types.js";
+import { Router } from "./router.js";
+/**
+ * Build the startup banner's optional surface lines (issue #99).
+ *
+ * Only advertise a surface that is actually REACHABLE. In production, or with
+ * TINA4_DEBUG off, /swagger and /__dev return 404 -- printing them anyway both
+ * misleads an operator into believing a dev surface is exposed and sends a
+ * developer to a dead link.
+ *
+ * Kept as a pure function of (port, two booleans) so the contract is unit
+ * testable without booting a server and grepping stdout. Parity: Python
+ * banner_surface_lines, PHP App::bannerSurfaceLines, Ruby
+ * Tina4.banner_surface_lines.
+ *
+ * @returns [swaggerLine, dashboardLine] -- each empty, or a newline plus the
+ *          banner row, ready to interpolate.
+ */
+export declare function bannerSurfaceLines(port: number, opts: {
+    swaggerEnabled: boolean;
+    devAdminEnabled: boolean;
+}): [string, string];
+/**
+ * Apply pending DB migrations on startup — NON-BREAKING.
+ *
+ * When a `migrations/` folder exists (with at least one `.sql` file, excluding
+ * `.down.sql`) and `TINA4_AUTO_MIGRATE` is not disabled (default "true";
+ * false/0/no/off disable), pending migrations are applied during boot so the
+ * schema is current with no manual `tina4 migrate` step. A failure here is
+ * logged LOUD via `Log.error` and the service STILL starts — a bad migration
+ * must never take the backend down. (The explicit `tina4 migrate` CLI stays
+ * fail-fast so CI still gets a non-zero exit. Only this startup hook swallows.)
+ *
+ * Disable with `TINA4_AUTO_MIGRATE=false` — e.g. multi-instance production that
+ * migrates as a separate deploy step (concurrent first-apply can race).
+ *
+ * @param migrationDir - migrations directory (default "migrations", relative to base)
+ * @param base - project root used to resolve the migrations directory
+ */
+export declare function autoMigrateOnStartup(migrationDir?: string, base?: string): Promise<void>;
+/**
+ * Refuse to boot if pre-3.12 un-prefixed env vars are still set.
+ *
+ * Tina4 v3.12 hard-renamed every framework-specific env var to use the
+ * `TINA4_` prefix. Booting silently with a legacy `DATABASE_URL` or
+ * `SECRET` would let auth, DB, or mail fall back to insecure defaults
+ * while the user thought their config was being read. Better to die
+ * loudly with a list of names to fix.
+ *
+ * Bypass with `TINA4_ALLOW_LEGACY_ENV=true` in CI / migration scripts
+ * that genuinely need both names set during a transition window.
+ */
+export declare function _checkLegacyEnvVars(): void;
+/**
+ * Resolve port and host with priority: explicit config > ENV var > default.
+ * Exported for testability.
+ *
+ * Host resolution prefers `TINA4_HOST` (the framework-prefixed name —
+ * matches Python parity) and falls back to the unprefixed `HOST` env var
+ * for backwards compatibility.
+ */
+export declare function resolvePortAndHost(config?: {
+    port?: number;
+    host?: string;
+}): {
+    port: number;
+    host: string;
+};
+/**
+ * Whether the boot banner should be suppressed. Set TINA4_SUPPRESS=true to
+ * silence the ASCII-art banner and route table on startup — useful in CI,
+ * test runners, and embedded contexts where stdout is consumed by another
+ * process.
+ */
+export declare function isBannerSuppressed(): boolean;
+/**
+ * Honour TINA4_TEMPLATE_ROUTING=off|false|0|no|disabled as an explicit kill
+ * switch. Default: enabled. Drop a file in src/templates/pages/ and it serves
+ * at the matching URL — the zero-config Tina4 convention. Operators who want
+ * explicit-only routing can set TINA4_TEMPLATE_ROUTING=off and every URL
+ * must be registered via get() / post() (or be a static file).
+ */
+export declare function templateAutoRoutingEnabled(): boolean;
+/**
+ * Return the canonical HTTP reason phrase for `status`. Falls back to a
+ * sensible label when an exotic status is used. Never returns an empty string.
+ */
+export declare function httpReason(status: number): string;
+/**
+ * Reset the production template cache. Tests use this between scenarios so
+ * a fresh scan picks up fixture files in a tmp project.
+ */
+export declare function resetTemplateCache(): void;
+/**
+ * Resolve a URL path to a template file in src/templates/pages/.
+ *
+ * Only files inside `src/templates/pages/` auto-route from a URL. Anything
+ * in `src/templates/` outside `pages/` (partials, layouts, base.twig,
+ * errors, components) is never served standalone.
+ *
+ * Dev mode: checks filesystem every time for live changes.
+ * Production: uses a cached lookup built once at startup.
+ *
+ * The whole feature can be turned off with `TINA4_TEMPLATE_ROUTING=off`.
+ */
+export declare function resolveTemplate(pathname: string, templatesDir: string): string | null;
+/**
+ * Start the Tina4 HTTP server.
+ * Thin wrapper around startServer() for cross-framework parity with PHP and Ruby.
+ */
+export declare function start(config?: Tina4Config): Promise<{
+    close: () => void;
+    router: Router;
+    port: number;
+}>;
+/**
+ * Stop the running Tina4 server gracefully.
+ */
+export declare function stop(): void;
+/**
+ * Dispatch a raw Node.js request through the Tina4 router and write the response.
+ * Requires startServer() to have been called first.
+ * Useful for testing and embedding.
+ */
+export declare function handle(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
+export declare function startServer(config?: Tina4Config): Promise<{
+    close: () => void;
+    router: Router;
+    port: number;
+}>;

package/types/core/src/service.d.ts

@@ -0,0 +1,115 @@
+export interface ServiceOptions {
+    timing?: string;
+    daemon?: boolean;
+    interval?: number;
+    maxRetries?: number;
+}
+export interface ServiceContext {
+    running: boolean;
+    lastRun: Date | null;
+    name: string;
+}
+export type ServiceHandler = (context: ServiceContext) => Promise<void> | void;
+export interface ServiceInfo {
+    name: string;
+    options: ServiceOptions;
+    running: boolean;
+    lastRun: Date | null;
+    retries: number;
+}
+/**
+ * Parse a single cron field and check if the given value matches.
+ * Supports: * (every), N/n (step), N,N,N (list), N-N (range), plain number.
+ */
+export declare function matchCronField(field: string, value: number): boolean;
+/**
+ * Check whether a Date matches a 5-field cron expression.
+ * Fields: minute hour dayOfMonth month dayOfWeek
+ */
+export declare function matchesCron(expression: string, date: Date): boolean;
+export declare abstract class Tina4Service {
+    private _running;
+    /** Main work loop — subclasses MUST override. */
+    abstract run(): Promise<void> | void;
+    /**
+     * Signal this service to stop. The next `shouldStop()` check returns true.
+     * Override for custom shutdown behaviour but always call `super.stop()`.
+     */
+    stop(): void;
+    /**
+     * Returns true once `stop()` has been called. Use inside `run()` loops
+     * as the exit condition:
+     *
+     *     async run() {
+     *       while (!this.shouldStop()) { ... }
+     *     }
+     */
+    shouldStop(): boolean;
+    /**
+     * Return a callable that ServiceRunner can register. Used by
+     * ServiceRunner.registerService under the hood.
+     */
+    asHandler(): ServiceHandler;
+}
+export declare class ServiceRunner {
+    /**
+     * Register a service with a handler and options.
+     */
+    static register(name: string, handler: ServiceHandler, options?: ServiceOptions): void;
+    /**
+     * Register a class-based service (subclass of {@link Tina4Service}) by name.
+     *
+     * Wraps the service's `run()` method as the runner's handler. Defaults
+     * to `daemon: true` because Tina4Service subclasses manage their own
+     * loop inside `run()`. Override via `options`.
+     *
+     *     class EmailWorker extends Tina4Service { async run() { ... } }
+     *     ServiceRunner.registerService("emails", new EmailWorker());
+     *     await ServiceRunner.start();
+     *
+     * Cross-framework parity with PHP `ServiceRunner::registerService` and
+     * Ruby `Tina4::ServiceRunner.register_service`.
+     */
+    static registerService(name: string, service: Tina4Service, options?: ServiceOptions): void;
+    /**
+     * Discover services from a directory. Each file should export
+     * { name, handler, timing?, interval?, daemon?, maxRetries? }.
+     */
+    static discover(serviceDir?: string): Promise<ServiceInfo[]>;
+    /**
+     * Start all registered services, or a specific one by name.
+     */
+    static start(name?: string): void;
+    /**
+     * Stop all running services, or a specific one by name.
+     */
+    static stop(name?: string): void;
+    /**
+     * List all registered services with their current state.
+     */
+    static list(): ServiceInfo[];
+    /**
+     * Check if a specific service is running.
+     */
+    static isRunning(name: string): boolean;
+    /**
+     * Remove a service from the registry (stops it first if running).
+     */
+    static remove(name: string): boolean;
+    /**
+     * Clear all registered services (stops them all first).
+     */
+    static clear(): void;
+    /**
+     * Check if a 5-field cron pattern matches the given (or current) date/time.
+     */
+    static matchCron(pattern: string, now?: Date): boolean;
+    /**
+     * Watch service files for changes and hot-reload in dev mode.
+     */
+    static watch(serviceDir?: string): void;
+    /**
+     * Stop watching service files.
+     */
+    static unwatch(): void;
+}