alepha 0.15.3 → 0.15.5

package/src/redis/index.ts

@@ -18,9 +18,9 @@ export * from "./providers/RedisSubscriberProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun|
  *
  * Redis client wrapper.
  *

package/src/retry/index.ts

@@ -12,9 +12,9 @@ export * from "./providers/RetryProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.12.0 | node, bun, workerd, browser, expo|
  *
  * Automatic retry with backoff.
  *

package/src/router/index.ts

@@ -1,7 +1,7 @@
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | frontend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.2.0 | node, bun, workerd, browser, expo|
  *
  * Frontend routing infrastructure.
  *

package/src/scheduler/index.ts

@@ -35,9 +35,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun, workerd|
  *
  * Cron and interval-based task execution.
  *

package/src/scheduler/index.workerd.ts

@@ -0,0 +1,43 @@
+import { $module } from "alepha";
+import { AlephaLock } from "alepha/lock";
+import { $scheduler } from "./primitives/$scheduler.ts";
+import { CronProvider } from "./providers/CronProvider.ts";
+import { WorkerdCronProvider } from "./providers/WorkerdCronProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./constants/CRON.ts";
+export * from "./primitives/$scheduler.ts";
+export * from "./providers/CronProvider.ts";
+export * from "./providers/WorkerdCronProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Cloudflare Workers scheduled event.
+     *
+     * Emitted when a cron trigger fires in Cloudflare Workers.
+     */
+    "cloudflare:scheduled": {
+      cron: string;
+      scheduledTime: number;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaScheduler = $module({
+  name: "alepha.scheduler",
+  primitives: [$scheduler],
+  services: [AlephaLock, CronProvider, WorkerdCronProvider],
+  register: (alepha) => {
+    // Replace CronProvider with WorkerdCronProvider for Cloudflare Workers
+    alepha.with({
+      provide: CronProvider,
+      use: WorkerdCronProvider,
+    });
+  },
+});

package/src/scheduler/providers/CronProvider.ts

@@ -16,6 +16,11 @@ export class CronProvider {
   protected readonly start = $hook({
     on: "start",
     handler: () => {
+      if (this.alepha.isServerless()) {
+        this.log.info("Ignoring cron jobs in serverless environment");
+        return;
+      }
+
       for (const cron of this.cronJobs) {
         if (!cron.running) {
           cron.running = true;
@@ -62,12 +67,12 @@ export class CronProvider {
         ? this.cronJobs.find((c) => c.name === name)
         : name;
 
-    if (!cron) {
+    if (!cron || !cron.running) {
       return;
     }
 
     cron.running = false;
-    cron.abort.abort();
+    cron.abort?.abort();
     this.log.debug(`Cron task '${cron.name}' stopped`);
   }
 
@@ -109,13 +114,13 @@ export class CronProvider {
     }
 
     const duration = next.getTime() - now.toDate().getTime();
-
-    task.abort = new AbortController();
+    const abort = new AbortController();
+    task.abort = abort;
 
     this.dt
       .wait(duration, {
         now: now.valueOf(),
-        signal: task.abort.signal,
+        signal: abort.signal,
       })
       .then(() => {
         if (!task.running) {
@@ -141,6 +146,48 @@ export class CronProvider {
         this.log.warn("Issue during cron waiting timer", err as Error);
       });
   }
+
+  /**
+   * Trigger a specific cron job by name.
+   */
+  public async trigger(name: string): Promise<void> {
+    const job = this.cronJobs.find((j) => j.name === name);
+    if (!job) {
+      this.log.warn(`Cron job '${name}' not found`);
+      return;
+    }
+    await this.runJobs([job], this.dt.now());
+  }
+
+  /**
+   * Trigger all registered cron jobs.
+   */
+  public async triggerAll(): Promise<void> {
+    await this.runJobs(this.cronJobs, this.dt.now());
+  }
+
+  /**
+   * Run multiple cron jobs in parallel.
+   */
+  protected async runJobs(jobs: CronJob[], now: DateTime): Promise<void> {
+    const results = await Promise.allSettled(
+      jobs.map(async (job) => {
+        this.log.debug(`Running cron job '${job.name}'`);
+        try {
+          await job.handler({ now });
+          this.log.debug(`Cron job '${job.name}' completed`);
+        } catch (error) {
+          this.log.error(`Cron job '${job.name}' failed`, error);
+          throw error;
+        }
+      }),
+    );
+
+    const failures = results.filter((r) => r.status === "rejected");
+    if (failures.length > 0) {
+      this.log.error(`${failures.length}/${jobs.length} cron jobs failed`);
+    }
+  }
 }
 
 export interface CronJob {
@@ -151,5 +198,5 @@ export interface CronJob {
   loop: boolean;
   running?: boolean;
   onError?: (error: Error) => void;
-  abort: AbortController;
+  abort?: AbortController;
 }

package/src/scheduler/providers/WorkerdCronProvider.ts

@@ -0,0 +1,102 @@
+import { $hook } from "alepha";
+import type { DateTime } from "alepha/datetime";
+import { parseCronExpression } from "cron-schedule";
+import { CronProvider } from "./CronProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Cloudflare Workers scheduled event.
+     *
+     * Emitted when a cron trigger fires in Cloudflare Workers.
+     */
+    "cloudflare:scheduled": {
+      cron: string;
+      scheduledTime: number;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Cloudflare Workers cron provider.
+ *
+ * This provider handles scheduled events from Cloudflare Workers Cron Triggers.
+ * Unlike the Node.js CronProvider, this doesn't use intervals/timeouts - instead,
+ * it reacts to scheduled events triggered by Cloudflare.
+ *
+ * **Usage:**
+ * 1. Define schedulers with `$scheduler({ cron: "0 * * * *", handler: ... })`
+ * 2. Build your app with `alepha build` - cron triggers are automatically added to `wrangler.jsonc`
+ * 3. Deploy to Cloudflare Workers
+ *
+ * **How it works:**
+ * - During build, all registered `$scheduler` cron expressions are collected
+ * - The build generates `wrangler.jsonc` with `triggers.crons` automatically filled
+ * - When Cloudflare fires a cron trigger, the `scheduled` handler emits `cloudflare:scheduled`
+ * - This provider listens to that event and runs matching schedulers
+ *
+ * @see https://developers.cloudflare.com/workers/configuration/cron-triggers/
+ */
+export class WorkerdCronProvider extends CronProvider {
+  /**
+   * Override to avoid creating AbortController in global scope.
+   * Cloudflare Workers doesn't allow this during initialization.
+   */
+  public override createCronJob(
+    name: string,
+    expression: string,
+    handler: (context: { now: DateTime }) => Promise<void>,
+  ): void {
+    this.cronJobs.push({
+      name,
+      cron: parseCronExpression(expression),
+      expression,
+      handler,
+      loop: false,
+    });
+  }
+
+  /**
+   * Handle a scheduled event from Cloudflare Workers.
+   */
+  protected readonly onScheduledEvent = $hook({
+    on: "cloudflare:scheduled",
+    handler: async (event) => {
+      const now = this.dt.of(event.scheduledTime);
+
+      this.log.info("Received scheduled event", {
+        cron: event.cron,
+        scheduledTime: now.format(),
+      });
+
+      // Find jobs that match this cron expression
+      const matchingJobs = this.cronJobs.filter(
+        (job) => job.expression === event.cron,
+      );
+
+      if (matchingJobs.length === 0) {
+        // No exact match - try to find jobs that would fire at this time
+        const matchingByTime = this.cronJobs.filter((job) =>
+          job.cron.matchDate(now.toDate()),
+        );
+
+        if (matchingByTime.length > 0) {
+          this.log.debug(
+            `No exact cron match for '${event.cron}', found ${matchingByTime.length} jobs matching by time`,
+          );
+          await this.runJobs(matchingByTime, now);
+          return;
+        }
+
+        this.log.warn(`No cron jobs found for expression '${event.cron}'`);
+        return;
+      }
+
+      await this.runJobs(matchingJobs, now);
+    },
+  });
+}

package/src/security/index.ts

@@ -89,9 +89,9 @@ declare module "alepha/server" {
 }
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | epic | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun, workerd, browser|
  *
  * Complete authentication and authorization system with JWT, RBAC, and multi-issuer support.
  *

package/src/security/providers/JwtProvider.ts

@@ -47,7 +47,7 @@ export class JwtProvider {
     } else if (this.isSecretKey(secretKeyOrJwks)) {
       const secretKey = this.encoder.encode(secretKeyOrJwks);
       this.log.info(
-        `will verify JWTs from '${name}' with secret a key (${secretKey.length} bytes)`,
+        `will verify JWTs from issuer '${name}' with secret key (${secretKey.length} bytes)`,
       );
       this.keystore.push({
         name,
@@ -56,7 +56,7 @@ export class JwtProvider {
       });
     } else {
       this.log.info(
-        `will verify JWTs from '${name}' with JWKS ${secretKeyOrJwks}`,
+        `will verify JWTs from issuer '${name}' with JWKS ${secretKeyOrJwks}`,
       );
       this.keystore.push({
         name,

package/src/server/auth/index.ts

@@ -29,9 +29,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.8.0 | node, bun, workerd|
  *
  * OAuth2/OIDC authentication with social login providers.
  *

package/src/server/cache/index.ts

@@ -9,9 +9,9 @@ export * from "./providers/ServerCacheProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.10.0 | node, bun, workerd|
  *
  * ETag-based response caching.
  *

package/src/server/compress/index.ts

@@ -9,9 +9,9 @@ export * from "./providers/ServerCompressProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.13.0 | node, bun|
  *
  * Response compression.
  *

package/src/server/compress/providers/ServerCompressProvider.ts

@@ -62,6 +62,12 @@ export class ServerCompressProvider {
   public readonly onResponse = $hook({
     on: "server:onResponse",
     handler: async ({ request, response }) => {
+      // In serverless (Cloudflare Workers), skip compression entirely:
+      // Cloudflare's edge network automatically compresses responses
+      if (this.alepha.isServerless()) {
+        return;
+      }
+
       // skip if already compressed
       if (response.headers["content-encoding"]) {
         return;

package/src/server/cookies/index.ts

@@ -18,9 +18,9 @@ declare module "alepha/server" {
 }
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.3.0 | node, bun, workerd|
  *
  * Server and browser-safe cookie handling.
  *

package/src/server/core/index.ts

@@ -114,9 +114,9 @@ export * from "./services/UserAgentParser.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | epic | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun, workerd|
  *
  * Convention-driven HTTP server with automatic validation and type inference.
  *

package/src/server/core/primitives/$action.spec.ts

@@ -81,8 +81,9 @@ describe("$action", () => {
 
     expect(await app.a1.fetch({}).then((it) => it.data)).toBe("ok:a1");
     expect(await app.a2.fetch({}).then((it) => it.data)).toBe("Not Found");
-    // note: $action disabled is callable locally
-    expect(await app.a2.run({})).toBe("ok:a2");
+    await expect(app.a2.run({})).rejects.toThrowError(
+      "Action 'a2' is disabled.",
+    );
   });
 
   test("should return nothing", async ({ expect }) => {

package/src/server/core/primitives/$action.ts

@@ -1,6 +1,7 @@
 import {
   $env,
   $inject,
+  AlephaError,
   type Async,
   createPrimitive,
   isTypeFile,
@@ -188,8 +189,8 @@ export interface ActionPrimitiveOptions<TConfig extends RequestConfigSchema>
   description?: string;
 
   /**
-   * Disable the route. Useful with env variables do disable one specific route.
-   * Route won't be available in the API but can still be called locally!
+   * Disable the route. Useful with env variables to disable one specific route.
+   * Route won't be available in the API nor locally.
    */
   disabled?: boolean;
 
@@ -317,6 +318,9 @@ export class ActionPrimitive<
     config?: ClientRequestEntry<TConfig>,
     options: ClientRequestOptions = {}, // most of the options are ignored here
   ): Promise<ClientRequestResponse<TConfig>> {
+    if (this.options.disabled) {
+      throw new AlephaError(`Action '${this.name}' is disabled.`);
+    }
     const handler = this.options.handler;
     const {
       body,

package/src/server/core/providers/NodeHttpServerProvider.ts

@@ -76,22 +76,9 @@ export class NodeHttpServerProvider extends ServerProvider {
     res.end("Internal Server Error");
   };
 
-  // P3: Pre-allocated event object to avoid { req, res } allocation per request
-  // Safe because handleNodeRequest completes before the next request reuses this object
-  protected readonly nodeRequestEvent = {
-    req: null as unknown as IncomingMessage,
-    res: null as unknown as ServerResponse,
-  };
-
   public readonly server = this.createHttpServer((req, res) => {
-    // Reuse pre-allocated event object instead of creating { req, res } per request
-    const ev = this.nodeRequestEvent;
-    ev.req = req;
-    ev.res = res;
-    // Note: handleNodeRequest returns a promise that resolves after response is sent
-    this.handleNodeRequest(ev).catch((err) =>
-      this.handleRequestError(res, err),
-    );
+    const promise = this.handleNodeRequest({ req, res });
+    promise.catch((err) => this.handleRequestError(res, err));
   });
 
   public readonly start = $hook({

package/src/server/core/providers/ServerProvider.ts

@@ -220,13 +220,15 @@ export class ServerProvider {
 
     // empty body - just send status & headers
     if (!response.body) {
-      res.writeHead(response.status, response.headers).end();
+      res.writeHead(response.status, response.headers);
+      res.end();
       return;
     }
 
     // if response.body is string or buffer
     if (typeof response.body === "string" || Buffer.isBuffer(response.body)) {
-      res.writeHead(response.status, response.headers).end(response.body);
+      res.writeHead(response.status, response.headers);
+      res.end(response.body);
       return;
     }
 

package/src/server/core/providers/ServerRouterProvider.ts

@@ -45,23 +45,6 @@ export class ServerRouterProvider extends RouterProvider<ServerRouteMatcher> {
   >;
   protected compiledOnError?: CompiledEventExecutor<Hooks["server:onError"]>;
 
-  // Reusable context.run options object - mutated per request
-  // Includes slots for request data to avoid closure allocation in context.run
-  protected readonly contextRunOptions = {
-    context: "",
-    // Request data slots - populated before context.run, read by processRequestBound
-    _request: null as unknown as ServerRequest,
-    _route: null as unknown as ServerRoute,
-    _responseKind: "any" as ResponseKind,
-  };
-
-  // Pre-bound method reference - created once at instantiation, reused for all requests
-  // Reads arguments from contextRunOptions to avoid closure allocation per request
-  protected readonly processRequestBound = (): Promise<any> => {
-    const opts = this.contextRunOptions;
-    return this.processRequest(opts._request, opts._route, opts._responseKind);
-  };
-
   // Cache query schema keys to avoid property enumeration on every request
   // WeakMap allows GC of schemas that are no longer referenced
   protected readonly queryKeysCache = new WeakMap<object, string[]>();
@@ -137,16 +120,11 @@ export class ServerRouterProvider extends RouterProvider<ServerRouteMatcher> {
         const request =
           this.serverRequestParser.createServerRequest(rawRequest);
 
-        // Populate pre-allocated options with request data
-        // This avoids closure allocation - processRequestBound reads from these slots
-        const opts = this.contextRunOptions;
-        opts.context = this.getContextId(rawRequest.headers);
-        opts._request = request;
-        opts._route = route;
-        opts._responseKind = responseKind;
-
-        // Use pre-bound method reference instead of creating closure per request
-        return this.alepha.context.run(this.processRequestBound, opts);
+        // Create context options per request to avoid race conditions with concurrent requests
+        return this.alepha.context.run(
+          () => this.processRequest(request, route, responseKind),
+          { context: this.getContextId(rawRequest.headers) },
+        );
       },
     });
   }

package/src/server/cors/index.ts

@@ -25,9 +25,9 @@ declare module "alepha/server" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.3.0 | node, bun, workerd|
  *
  * Cross-Origin Resource Sharing configuration.
  *

package/src/server/health/index.ts

@@ -10,9 +10,9 @@ export * from "./schemas/healthSchema.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | devops | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.7.0 | node, bun, workerd|
  *
  * Application health monitoring endpoints.
  *

package/src/server/helmet/index.ts

@@ -9,9 +9,9 @@ export * from "./providers/ServerHelmetProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.15.0 | node, bun, workerd|
  *
  * HTTP security headers.
  *

package/src/server/links/index.ts

@@ -35,9 +35,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.6.0 | node, bun, workerd, expo |
  *
  * Type-safe API client with request deduplication.
  *