alepha 0.15.1 → 0.15.3

package/src/batch/providers/BatchProvider.ts

@@ -1,4 +1,4 @@
-import { $inject, type Alepha } from "alepha";
+import { $hook, $inject, type Alepha } from "alepha";
 import { DateTimeProvider, type DurationLike } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { type RetryBackoffOptions, RetryProvider } from "alepha/retry";
@@ -130,6 +130,11 @@ export class BatchProvider {
   protected readonly dateTime = $inject(DateTimeProvider);
   protected readonly retryProvider = $inject(RetryProvider);
 
+  /**
+   * All active batch contexts managed by this provider.
+   */
+  protected readonly contexts = new Set<BatchContext<any, any>>();
+
   /**
    * Creates a new batch context with the given options.
    */
@@ -137,7 +142,7 @@ export class BatchProvider {
     alepha: Alepha,
     options: BatchOptions<TItem, TResponse>,
   ): BatchContext<TItem, TResponse> {
-    return {
+    const context: BatchContext<TItem, TResponse> = {
       options,
       itemStates: new Map(),
       partitions: new Map(),
@@ -146,8 +151,30 @@ export class BatchProvider {
       isReady: false,
       alepha,
     };
+    this.contexts.add(context);
+    return context;
   }
 
+  /**
+   * Shutdown hook - flushes all batch contexts on application stop.
+   */
+  protected readonly onStop = $hook({
+    on: "stop",
+    priority: "first",
+    handler: async () => {
+      if (this.contexts.size === 0) {
+        return;
+      }
+      this.log.debug(`Shutting down ${this.contexts.size} batch context(s)...`);
+      const promises: Promise<void>[] = [];
+      for (const context of this.contexts) {
+        promises.push(this.shutdown(context));
+      }
+      await Promise.all(promises);
+      this.log.debug("All batch contexts shut down");
+    },
+  });
+
   /**
    * Get the effective maxSize for a context.
    */

package/src/bucket/__tests__/shared.ts

@@ -1,5 +1,5 @@
 import { Alepha } from "alepha";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { expect } from "vitest";
 import {
   $bucket,

package/src/bucket/index.ts

@@ -43,14 +43,21 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides file storage capabilities through declarative bucket primitives with support for multiple storage backends.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * The bucket module enables unified file operations across different storage systems using the `$bucket` primitive
- * on class properties. It abstracts storage provider differences, offering consistent APIs for local filesystem,
- * cloud storage, or in-memory storage for testing environments.
+ * Unified file storage abstraction across multiple backends.
+ *
+ * **Features:**
+ * - File storage buckets with constraints
+ * - Unified API across all storage backends
+ * - MIME type validation
+ * - File size limits
+ * - Upload/download/delete operations
+ * - TTL-based file expiration
+ * - Providers: Memory (testing), Local filesystem, AWS S3 / Cloudflare R2 / MinIO, Azure Blob Storage, Vercel Blob
  *
- * @see {@link $bucket}
- * @see {@link FileStorageProvider}
  * @module alepha.bucket
  */
 export const AlephaBucket = $module({

package/src/bucket/primitives/$bucket.ts

@@ -6,7 +6,7 @@ import {
   Primitive,
   type Service,
 } from "alepha";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { InvalidFileError } from "../errors/InvalidFileError.ts";
 import { FileStorageProvider } from "../providers/FileStorageProvider.ts";
 import { MemoryFileStorageProvider } from "../providers/MemoryFileStorageProvider.ts";

package/src/bucket/providers/LocalFileStorageProvider.ts

@@ -15,8 +15,8 @@ import {
   type Static,
   t,
 } from "alepha";
-import { FileDetector, FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileDetector, FileSystemProvider } from "alepha/system";
 import { FileNotFoundError } from "../errors/FileNotFoundError.ts";
 import { $bucket } from "../primitives/$bucket.ts";
 import type { FileStorageProvider } from "./FileStorageProvider.ts";

package/src/bucket/providers/MemoryFileStorageProvider.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { $inject, type FileLike } from "alepha";
-import { FileDetector, FileSystemProvider } from "alepha/file";
+import { FileDetector, FileSystemProvider } from "alepha/system";
 import { FileNotFoundError } from "../errors/FileNotFoundError.ts";
 import type { FileStorageProvider } from "./FileStorageProvider.ts";
 

package/src/cache/core/__tests__/shared.ts

@@ -321,6 +321,36 @@ export const testSimpleKeyMappingHandler = async (
   expect(await app.run("C")).toBe("C=3");
 };
 
+export const testCacheIncr = async (
+  env: Env = {},
+  cacheProvider: Service<CacheProvider> = MemoryCacheProvider,
+): Promise<void> => {
+  const app = Alepha.create({
+    env,
+  }).with({
+    provide: CacheProvider,
+    use: cacheProvider,
+  });
+
+  const provider = app.inject(CacheProvider);
+  await app.start();
+
+  const name = "test-incr";
+  const key = `counter:${randomUUID()}`;
+
+  // First increment creates the key
+  const val1 = await provider.incr(name, key, 1);
+  expect(val1).toBe(1);
+
+  // Subsequent increments add to existing value
+  const val2 = await provider.incr(name, key, 5);
+  expect(val2).toBe(6);
+
+  // Negative amounts work (decrement)
+  const val3 = await provider.incr(name, key, -2);
+  expect(val3).toBe(4);
+};
+
 export const testCacheProviderClear = async (
   env: Env = {},
   cacheProvider: Service<CacheProvider> = MemoryCacheProvider,

package/src/cache/core/index.ts

@@ -12,14 +12,19 @@ export * from "./providers/MemoryCacheProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides high-performance caching capabilities for Alepha applications with configurable TTL and multiple storage backends.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * The cache module enables declarative caching through the `$cache` primitive, allowing you to cache method results,
- * API responses, or computed values with automatic invalidation and type safety. It supports both in-memory and
- * persistent storage backends for different performance and durability requirements.
+ * Type-safe caching with TTL support.
+ *
+ * **Features:**
+ * - Cached computations with type-safe keys and values
+ * - Configurable TTL
+ * - Cache invalidation
+ * - Automatic cache population
+ * - Providers: Memory (default), Redis
  *
- * @see {@link $cache}
- * @see {@link CacheProvider}
  * @module alepha.cache
  */
 export const AlephaCache = $module({

package/src/cache/core/primitives/$cache.spec.ts

@@ -7,6 +7,7 @@ import {
   testCacheBasic,
   testCacheClear,
   testCacheDisabled,
+  testCacheIncr,
   testCacheInvalidateAll,
   testCacheInvalidateByArgs,
   testCacheInvalidateByKey,
@@ -108,4 +109,8 @@ describe("$cache", () => {
   it("should clear provider cache", async () => {
     await testCacheProviderClear();
   });
+
+  it("should increment values atomically", async () => {
+    await testCacheIncr();
+  });
 });

package/src/cache/core/providers/CacheProvider.ts

@@ -51,4 +51,21 @@ export abstract class CacheProvider {
    * Remove all keys from all cache names.
    */
   public abstract clear(): Promise<void>;
+
+  /**
+   * Increment the integer value of a key by the given amount.
+   *
+   * If the key does not exist, it is set to 0 before performing the operation.
+   * This operation is atomic when using Redis.
+   *
+   * @param name Cache name, used to group keys.
+   * @param key The key to increment.
+   * @param amount The amount to increment by.
+   * @returns The new value after incrementing.
+   */
+  public abstract incr(
+    name: string,
+    key: string,
+    amount: number,
+  ): Promise<number>;
 }

package/src/cache/core/providers/MemoryCacheProvider.ts

@@ -10,14 +10,150 @@ type CacheValue = {
   timeout?: Timeout;
 };
 
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface MemoryCacheCall {
+  name: string;
+  key: string;
+  timestamp: number;
+}
+
+export interface MemoryCacheSetCall extends MemoryCacheCall {
+  value: Uint8Array;
+  ttl?: number;
+}
+
+export interface MemoryCacheDelCall {
+  name: string;
+  keys: string[];
+  timestamp: number;
+}
+
+export interface MemoryCacheStats {
+  hits: number;
+  misses: number;
+  sets: number;
+  deletes: number;
+}
+
+export interface MemoryCacheProviderOptions {
+  /**
+   * Error to throw on get operations (for testing error handling)
+   */
+  getError?: Error | null;
+  /**
+   * Error to throw on set operations (for testing error handling)
+   */
+  setError?: Error | null;
+  /**
+   * Error to throw on del operations (for testing error handling)
+   */
+  delError?: Error | null;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * In-memory implementation of CacheProvider for testing.
+ *
+ * This provider stores all cache entries in memory, making it ideal for
+ * unit tests that need to verify cache operations without touching Redis or other backends.
+ *
+ * @example
+ * ```typescript
+ * // In tests, substitute the real CacheProvider with MemoryCacheProvider
+ * const alepha = Alepha.create().with({
+ *   provide: CacheProvider,
+ *   use: MemoryCacheProvider,
+ * });
+ *
+ * // Run code that uses caching
+ * const service = alepha.inject(MyService);
+ * await service.fetchWithCache("key");
+ *
+ * // Verify cache behavior
+ * const cache = alepha.inject(MemoryCacheProvider);
+ * expect(cache.stats().misses).toBe(1);
+ * await service.fetchWithCache("key");
+ * expect(cache.stats().hits).toBe(1);
+ * ```
+ */
 export class MemoryCacheProvider implements CacheProvider {
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly log = $logger();
 
   protected store: Record<CacheName, Record<CacheKey, CacheValue>> = {};
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Test tracking
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * All recorded get calls.
+   */
+  public getCalls: MemoryCacheCall[] = [];
+
+  /**
+   * All recorded set calls.
+   */
+  public setCalls: MemoryCacheSetCall[] = [];
+
+  /**
+   * All recorded del calls.
+   */
+  public delCalls: MemoryCacheDelCall[] = [];
+
+  /**
+   * Cache statistics.
+   */
+  protected _stats: MemoryCacheStats = {
+    hits: 0,
+    misses: 0,
+    sets: 0,
+    deletes: 0,
+  };
+
+  /**
+   * Error to throw on get (for testing error handling)
+   */
+  public getError: Error | null = null;
+
+  /**
+   * Error to throw on set (for testing error handling)
+   */
+  public setError: Error | null = null;
+
+  /**
+   * Error to throw on del (for testing error handling)
+   */
+  public delError: Error | null = null;
+
+  constructor(options: MemoryCacheProviderOptions = {}) {
+    this.getError = options.getError ?? null;
+    this.setError = options.setError ?? null;
+    this.delError = options.delError ?? null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // CacheProvider implementation
+  // ─────────────────────────────────────────────────────────────────────────────
+
   public async get(name: string, key: string): Promise<Uint8Array | undefined> {
-    return this.store[name]?.[key]?.data;
+    this.getCalls.push({ name, key, timestamp: Date.now() });
+
+    if (this.getError) {
+      throw this.getError;
+    }
+
+    const data = this.store[name]?.[key]?.data;
+
+    if (data !== undefined) {
+      this._stats.hits++;
+    } else {
+      this._stats.misses++;
+    }
+
+    return data;
   }
 
   public async set(
@@ -26,6 +162,13 @@ export class MemoryCacheProvider implements CacheProvider {
     value: Uint8Array,
     ttl?: number,
   ): Promise<Uint8Array> {
+    this.setCalls.push({ name, key, value, ttl, timestamp: Date.now() });
+    this._stats.sets++;
+
+    if (this.setError) {
+      throw this.setError;
+    }
+
     if (this.store[name] == null) {
       this.store[name] = {};
     }
@@ -52,6 +195,13 @@ export class MemoryCacheProvider implements CacheProvider {
   }
 
   public async del(name: string, ...keys: string[]): Promise<void> {
+    this.delCalls.push({ name, keys, timestamp: Date.now() });
+    this._stats.deletes++;
+
+    if (this.delError) {
+      throw this.delError;
+    }
+
     // delete all keys in name
     if (keys.length === 0) {
       this.log.debug(`Deleting all cache for name`, { name });
@@ -116,4 +266,153 @@ export class MemoryCacheProvider implements CacheProvider {
 
     this.store = {};
   }
+
+  public async incr(
+    name: string,
+    key: string,
+    amount: number,
+  ): Promise<number> {
+    if (this.store[name] == null) {
+      this.store[name] = {};
+    }
+
+    const existing = this.store[name][key]?.data;
+    let current = 0;
+
+    if (existing) {
+      const str = new TextDecoder().decode(existing);
+      current = Number.parseInt(str, 10) || 0;
+    }
+
+    const newValue = current + amount;
+    this.store[name][key] ??= {};
+    this.store[name][key].data = new TextEncoder().encode(String(newValue));
+
+    return newValue;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Test utilities
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get cache statistics (hits, misses, sets, deletes).
+   *
+   * @example
+   * ```typescript
+   * expect(cache.stats().hits).toBe(1);
+   * expect(cache.stats().misses).toBe(0);
+   * ```
+   */
+  public stats(): MemoryCacheStats {
+    return { ...this._stats };
+  }
+
+  /**
+   * Check if a key was set during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.wasSet("my-cache", "user:123")).toBe(true);
+   * ```
+   */
+  public wasSet(name: string, key?: string): boolean {
+    if (key === undefined) {
+      return this.setCalls.some((call) => call.name === name);
+    }
+    return this.setCalls.some((call) => call.name === name && call.key === key);
+  }
+
+  /**
+   * Check if a key was retrieved during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.wasGet("my-cache", "user:123")).toBe(true);
+   * ```
+   */
+  public wasGet(name: string, key?: string): boolean {
+    if (key === undefined) {
+      return this.getCalls.some((call) => call.name === name);
+    }
+    return this.getCalls.some((call) => call.name === name && call.key === key);
+  }
+
+  /**
+   * Check if a key was deleted during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.wasDeleted("my-cache", "user:123")).toBe(true);
+   * ```
+   */
+  public wasDeleted(name: string, key?: string): boolean {
+    if (key === undefined) {
+      return this.delCalls.some((call) => call.name === name);
+    }
+    return this.delCalls.some(
+      (call) => call.name === name && call.keys.includes(key),
+    );
+  }
+
+  /**
+   * Get the number of cached entries for a specific cache name.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.size("my-cache")).toBe(5);
+   * ```
+   */
+  public size(name?: string): number {
+    if (name === undefined) {
+      return Object.values(this.store).reduce(
+        (total, entries) => total + Object.keys(entries).length,
+        0,
+      );
+    }
+    return Object.keys(this.store[name] ?? {}).length;
+  }
+
+  /**
+   * Get all cache names.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.names()).toContain("my-cache");
+   * ```
+   */
+  public names(): string[] {
+    return Object.keys(this.store);
+  }
+
+  /**
+   * Reset all in-memory state (useful between tests).
+   *
+   * @example
+   * ```typescript
+   * beforeEach(() => {
+   *   cache.reset();
+   * });
+   * ```
+   */
+  public reset(): void {
+    // Clear all timeouts
+    for (const name of Object.keys(this.store)) {
+      for (const key of Object.keys(this.store[name])) {
+        const timeout = this.store[name][key]?.timeout;
+        if (timeout) {
+          this.dateTimeProvider.clearTimeout(timeout);
+        }
+      }
+    }
+
+    this.store = {};
+    this.getCalls = [];
+    this.setCalls = [];
+    this.delCalls = [];
+    this._stats = { hits: 0, misses: 0, sets: 0, deletes: 0 };
+    this.getError = null;
+    this.setError = null;
+    this.delError = null;
+  }
 }

package/src/cache/redis/__tests__/cache-redis.spec.ts

@@ -4,6 +4,7 @@ import {
   testCacheBasic,
   testCacheClear,
   testCacheDisabled,
+  testCacheIncr,
   testCacheInvalidateAll,
   testCacheInvalidateByArgs,
   testCacheInvalidateByKey,
@@ -67,4 +68,8 @@ describe("$cache - redis", () => {
   it("should clear provider cache", async () => {
     await testCacheProviderClear(env(), provider);
   });
+
+  it("should increment values atomically", async () => {
+    await testCacheIncr(env(), provider);
+  });
 });

package/src/cache/redis/providers/RedisCacheProvider.ts

@@ -99,6 +99,15 @@ export class RedisCacheProvider implements CacheProvider {
     await this.redisProvider.del(keys);
   }
 
+  public async incr(
+    name: string,
+    key: string,
+    amount: number,
+  ): Promise<number> {
+    const keyWithPrefix = this.prefix(name, key);
+    return this.redisProvider.incr(keyWithPrefix, amount);
+  }
+
   protected prefix(...path: string[]): string {
     const parts = ["cache", ...path];
 

package/src/cli/apps/AlephaCli.ts

@@ -1,5 +1,5 @@
 import { $hook, $inject, $module, Alepha } from "alepha";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { BuildCommand } from "../commands/build.ts";
 import { CleanCommand } from "../commands/clean.ts";
 import { DbCommand } from "../commands/db.ts";
@@ -17,19 +17,6 @@ import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-/**
- * Register `tsx` when running in Node.js, ignore for Bun.
- *
- * It's required to have a full TypeScript support. (mostly .tsx files)
- */
-
-if (typeof Bun === "undefined") {
-  const { register } = await import("tsx/esm/api");
-  register();
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 /**
  * Allow to extend Alepha CLI via `alepha.config.ts` file located in the project root.
  */

package/src/cli/apps/AlephaPackageBuilderCli.ts

@@ -3,7 +3,7 @@ import * as os from "node:os";
 import { join } from "node:path";
 import { $inject, AlephaError } from "alepha";
 import { $command } from "alepha/command";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import type { InlineConfig } from "tsdown";
 
 interface Module {
@@ -11,6 +11,7 @@ interface Module {
   dependencies: string[];
   native?: boolean;
   browser?: boolean;
+  workerd?: boolean;
   bun?: boolean;
   node?: boolean;
 }
@@ -53,6 +54,10 @@ export class AlephaPackageBuilderCli {
             `./src/${item.name}/index.browser.ts`;
         }
 
+        if (item.workerd) {
+          pkgData.exports[path].workerd = `./src/${item.name}/index.workerd.ts`;
+        }
+
         if (item.browser) {
           pkgData.exports[path].browser = `./src/${item.name}/index.browser.ts`;
         }
@@ -321,6 +326,9 @@ export async function analyzeModules(
           );
           const hasBun = await fileExists(join(modulePath, "index.bun.ts"));
           const hasNode = await fileExists(join(modulePath, "index.node.ts"));
+          const hasEdge = await fileExists(
+            join(modulePath, "index.workerd.ts"),
+          );
 
           // Get all .ts/.tsx files in this module
           const files = await getAllFiles(modulePath);
@@ -353,6 +361,7 @@ export async function analyzeModules(
           };
 
           if (hasNative) module.native = true;
+          if (hasEdge) module.workerd = true;
           if (hasBrowser) module.browser = true;
           if (hasBun) module.bun = true;
           if (hasNode) module.node = true;