alepha 0.20.2 → 0.20.4

package/src/bucket/index.ts

@@ -7,6 +7,7 @@ import {
 import { FileStorageProvider } from "./providers/FileStorageProvider.ts";
 import { LocalFileStorageProvider } from "./providers/LocalFileStorageProvider.ts";
 import { MemoryFileStorageProvider } from "./providers/MemoryFileStorageProvider.ts";
+import { NodeS3BucketProvider } from "./providers/NodeS3BucketProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -16,6 +17,7 @@ export * from "./providers/CloudflareR2Provider.ts";
 export * from "./providers/FileStorageProvider.ts";
 export * from "./providers/LocalFileStorageProvider.ts";
 export * from "./providers/MemoryFileStorageProvider.ts";
+export * from "./providers/NodeS3BucketProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -38,6 +40,14 @@ declare module "alepha" {
       id: string;
       bucket: BucketPrimitive;
     };
+    /**
+     * Triggered when a file is downloaded from a bucket.
+     */
+    "bucket:file:downloaded": {
+      id: string;
+      file: FileLike;
+      bucket: BucketPrimitive;
+    };
   }
 }
 
@@ -61,15 +71,22 @@ export const AlephaBucket = $module({
   name: "alepha.bucket",
   primitives: [$bucket],
   services: [FileStorageProvider],
-  variants: [MemoryFileStorageProvider, LocalFileStorageProvider],
+  variants: [
+    MemoryFileStorageProvider,
+    LocalFileStorageProvider,
+    NodeS3BucketProvider,
+  ],
   register: (alepha) => {
+    const useS3 = !!alepha.env.S3_ENDPOINT;
     alepha.with({
       optional: true,
       provide: FileStorageProvider,
       use:
         alepha.isTest() || alepha.isServerless()
           ? MemoryFileStorageProvider
-          : LocalFileStorageProvider,
+          : useS3
+            ? NodeS3BucketProvider
+            : LocalFileStorageProvider,
     });
   },
 });

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

@@ -288,7 +288,15 @@ export class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {
    * Downloads a file from the bucket.
    */
   public async download(fileId: string): Promise<FileLike> {
-    return this.provider.download(this.name, fileId);
+    const file = await this.provider.download(this.name, fileId);
+
+    await this.alepha.events.emit("bucket:file:downloaded", {
+      id: fileId,
+      bucket: this,
+      file,
+    });
+
+    return file;
   }
 
   protected $provider() {

package/src/bucket/providers/CloudflareR2Provider.ts

@@ -1,3 +1,4 @@
+import type { R2Bucket } from "@cloudflare/workers-types";
 import {
   $env,
   $hook,
@@ -14,142 +15,6 @@ import type { FileStorageProvider } from "./FileStorageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-/**
- * R2Bucket interface matching Cloudflare's R2 API.
- */
-export interface R2Bucket {
-  put(
-    key: string,
-    value:
-      | ReadableStream
-      | ArrayBuffer
-      | ArrayBufferView
-      | string
-      | Blob
-      | null,
-    options?: R2PutOptions,
-  ): Promise<R2Object | null>;
-  get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
-  head(key: string): Promise<R2Object | null>;
-  delete(keys: string | string[]): Promise<void>;
-  list(options?: R2ListOptions): Promise<R2Objects>;
-  createMultipartUpload(
-    key: string,
-    options?: R2MultipartOptions,
-  ): Promise<R2MultipartUpload>;
-}
-
-export interface R2Object {
-  key: string;
-  version: string;
-  size: number;
-  etag: string;
-  httpEtag: string;
-  checksums: R2Checksums;
-  uploaded: Date;
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  range?: R2Range;
-  storageClass: string;
-}
-
-export interface R2ObjectBody extends R2Object {
-  body: ReadableStream;
-  bodyUsed: boolean;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  text(): Promise<string>;
-  json<T>(): Promise<T>;
-  blob(): Promise<Blob>;
-}
-
-export interface R2PutOptions {
-  onlyIf?: R2Conditional;
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  md5?: ArrayBuffer | string;
-  sha1?: ArrayBuffer | string;
-  sha256?: ArrayBuffer | string;
-  sha384?: ArrayBuffer | string;
-  sha512?: ArrayBuffer | string;
-  storageClass?: string;
-}
-
-export interface R2GetOptions {
-  onlyIf?: R2Conditional;
-  range?: R2Range;
-}
-
-export interface R2ListOptions {
-  limit?: number;
-  prefix?: string;
-  cursor?: string;
-  delimiter?: string;
-  startAfter?: string;
-  include?: ("httpMetadata" | "customMetadata")[];
-}
-
-export interface R2Objects {
-  objects: R2Object[];
-  truncated: boolean;
-  cursor?: string;
-  delimitedPrefixes: string[];
-}
-
-export interface R2Checksums {
-  md5?: ArrayBuffer;
-  sha1?: ArrayBuffer;
-  sha256?: ArrayBuffer;
-  sha384?: ArrayBuffer;
-  sha512?: ArrayBuffer;
-}
-
-export interface R2HTTPMetadata {
-  contentType?: string;
-  contentLanguage?: string;
-  contentDisposition?: string;
-  contentEncoding?: string;
-  cacheControl?: string;
-  cacheExpiry?: Date;
-}
-
-export interface R2Conditional {
-  etagMatches?: string;
-  etagDoesNotMatch?: string;
-  uploadedBefore?: Date;
-  uploadedAfter?: Date;
-  secondsGranularity?: boolean;
-}
-
-export interface R2Range {
-  offset?: number;
-  length?: number;
-  suffix?: number;
-}
-
-export interface R2MultipartOptions {
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  storageClass?: string;
-}
-
-export interface R2MultipartUpload {
-  key: string;
-  uploadId: string;
-  uploadPart(
-    partNumber: number,
-    value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob,
-  ): Promise<R2UploadedPart>;
-  abort(): Promise<void>;
-  complete(uploadedParts: R2UploadedPart[]): Promise<R2Object>;
-}
-
-export interface R2UploadedPart {
-  partNumber: number;
-  etag: string;
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 /**
  * Cloudflare R2 storage provider.
  *
@@ -311,7 +176,7 @@ export class CloudflareR2Provider implements FileStorageProvider {
       type: contentType,
       size: object.size,
       lastModified: object.uploaded.getTime(),
-      stream: () => object.body,
+      stream: () => object.body as unknown as ReadableStream,
       arrayBuffer: () => object.arrayBuffer(),
       text: () => object.text(),
     };

package/src/bucket/providers/NodeS3BucketProvider.ts

@@ -0,0 +1,218 @@
+import { Buffer } from "node:buffer";
+import {
+  $env,
+  $hook,
+  $inject,
+  Alepha,
+  AlephaError,
+  type FileLike,
+  type Static,
+  t,
+} from "alepha";
+import { $logger } from "alepha/logger";
+import { FileDetector, FileSystemProvider } from "alepha/system";
+import { S3mini } from "s3mini";
+import { FileNotFoundError } from "../errors/FileNotFoundError.ts";
+import { $bucket } from "../primitives/$bucket.ts";
+import type { FileStorageProvider } from "./FileStorageProvider.ts";
+
+const envSchema = t.object({
+  /**
+   * S3 endpoint URL. The bucket name is appended (path-style) per request.
+   *
+   * Examples:
+   * - AWS S3: `https://s3.us-east-1.amazonaws.com`
+   * - Cloudflare R2: `https://<account-id>.r2.cloudflarestorage.com`
+   * - MinIO: `http://localhost:9000`
+   * - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`
+   */
+  S3_ENDPOINT: t.string(),
+
+  /**
+   * AWS region or "auto" for R2.
+   *
+   * @default "auto"
+   */
+  S3_REGION: t.optional(t.string()),
+
+  /**
+   * Access key ID for S3 authentication.
+   */
+  S3_ACCESS_KEY_ID: t.string(),
+
+  /**
+   * Secret access key for S3 authentication.
+   */
+  S3_SECRET_ACCESS_KEY: t.string(),
+});
+
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
+
+/**
+ * S3-compatible file storage provider for Node.js.
+ *
+ * Backed by `s3mini` (zero-dep, ~20 KB). Works with AWS S3, Cloudflare R2,
+ * MinIO, DigitalOcean Spaces, Backblaze B2, and any other S3-compatible service.
+ *
+ * Uses path-style addressing (`<endpoint>/<bucket>`).
+ */
+export class NodeS3BucketProvider implements FileStorageProvider {
+  protected readonly log = $logger();
+  protected readonly env = $env(envSchema);
+  protected readonly alepha = $inject(Alepha);
+  protected readonly fileSystem = $inject(FileSystemProvider);
+  protected readonly fileDetector = $inject(FileDetector);
+  protected readonly clients: Map<string, S3mini> = new Map();
+
+  /**
+   * Convert bucket name to S3-compatible format.
+   * S3 bucket names must be lowercase, 3-63 characters, no underscores.
+   */
+  public convertName(name: string): string {
+    return name.replaceAll("/", "-").replaceAll("_", "-").toLowerCase();
+  }
+
+  protected getClient(bucketName: string): S3mini {
+    const name = this.convertName(bucketName);
+    let client = this.clients.get(name);
+    if (!client) {
+      const endpoint = this.env.S3_ENDPOINT.replace(/\/+$/, "");
+      client = new S3mini({
+        accessKeyId: this.env.S3_ACCESS_KEY_ID,
+        secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,
+        region: this.env.S3_REGION || "auto",
+        endpoint: `${endpoint}/${name}`,
+      });
+      this.clients.set(name, client);
+    }
+    return client;
+  }
+
+  protected readonly onStart = $hook({
+    on: "start",
+    handler: async () => {
+      for (const bucket of this.alepha.primitives($bucket)) {
+        if (bucket.provider !== this) {
+          continue;
+        }
+
+        const name = this.convertName(bucket.name);
+        const client = this.getClient(bucket.name);
+
+        this.log.debug(`Preparing S3 bucket '${name}'...`);
+
+        const exists = await client.bucketExists();
+        if (!exists) {
+          this.log.debug(`Creating S3 bucket '${name}'...`);
+          const created = await client.createBucket();
+          if (!created) {
+            throw new AlephaError(`Failed to create S3 bucket '${name}'`);
+          }
+        }
+
+        this.log.info(`S3 bucket '${bucket.name}' OK`);
+      }
+    },
+  });
+
+  protected createId(mimeType: string): string {
+    const ext = this.fileDetector.getExtensionFromMimeType(mimeType);
+    return `${crypto.randomUUID()}.${ext}`;
+  }
+
+  public async upload(
+    bucketName: string,
+    file: FileLike,
+    fileId?: string,
+  ): Promise<string> {
+    fileId ??= this.createId(file.type);
+
+    this.log.trace(
+      `Uploading file '${file.name}' to bucket '${bucketName}' with id '${fileId}'...`,
+    );
+
+    const client = this.getClient(bucketName);
+
+    try {
+      const buffer = new Uint8Array(await file.arrayBuffer());
+      await client.putObject(
+        fileId,
+        buffer,
+        file.type || "application/octet-stream",
+        undefined,
+        { "x-amz-meta-name": encodeURIComponent(file.name) },
+        file.size,
+      );
+
+      this.log.trace(`File uploaded successfully: ${fileId}`);
+      return fileId;
+    } catch (error) {
+      this.log.error(`Failed to upload file: ${error}`);
+      if (error instanceof Error) {
+        throw new AlephaError(`Upload failed: ${error.message}`, {
+          cause: error,
+        });
+      }
+      throw error;
+    }
+  }
+
+  public async download(bucketName: string, fileId: string): Promise<FileLike> {
+    this.log.trace(
+      `Downloading file '${fileId}' from bucket '${bucketName}'...`,
+    );
+
+    const client = this.getClient(bucketName);
+    const response = await client.getObjectResponse(fileId);
+
+    if (!response) {
+      throw new FileNotFoundError(
+        `File '${fileId}' not found in bucket '${bucketName}'`,
+      );
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+
+    const mimeType =
+      response.headers.get("content-type") ||
+      this.fileDetector.getContentType(fileId);
+
+    const metaName = response.headers.get("x-amz-meta-name");
+    const name = metaName ? decodeURIComponent(metaName) : fileId;
+
+    return this.fileSystem.createFile({
+      buffer,
+      name,
+      type: mimeType,
+      size: buffer.length,
+    });
+  }
+
+  public async exists(bucketName: string, fileId: string): Promise<boolean> {
+    this.log.trace(
+      `Checking existence of file '${fileId}' in bucket '${bucketName}'...`,
+    );
+
+    const client = this.getClient(bucketName);
+    const result = await client.objectExists(fileId);
+    return result === true;
+  }
+
+  public async delete(bucketName: string, fileId: string): Promise<void> {
+    this.log.trace(`Deleting file '${fileId}' from bucket '${bucketName}'...`);
+
+    const client = this.getClient(bucketName);
+
+    try {
+      await client.deleteObject(fileId);
+    } catch (error) {
+      this.log.error(`Failed to delete file: ${error}`);
+      if (error instanceof Error) {
+        throw new FileNotFoundError("Error deleting file", { cause: error });
+      }
+      throw error;
+    }
+  }
+}

package/src/cache/core/index.ts

@@ -12,6 +12,35 @@ export * from "./providers/MemoryCacheProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Fires when a cache lookup finds a value.
+     */
+    "cache:hit": {
+      container: string;
+      key: string;
+    };
+    /**
+     * Fires when a cache lookup does not find a value.
+     */
+    "cache:miss": {
+      container: string;
+      key: string;
+    };
+    /**
+     * Fires when a value is written to the cache.
+     */
+    "cache:set": {
+      container: string;
+      key: string;
+      ttlMs?: number;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * Type-safe caching with TTL support.
  *

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

@@ -239,6 +239,12 @@ export class CachePrimitive<
       ttl: px > 0 ? px : undefined,
       compress: this.options.compress,
     });
+
+    await this.alepha.events.emit("cache:set", {
+      container: this.container,
+      key,
+      ttlMs: px > 0 ? px : undefined,
+    });
   }
 
   public async get(key: string): Promise<TReturn | undefined> {
@@ -250,7 +256,14 @@ export class CachePrimitive<
       return undefined;
     }
 
-    return this.provider.getTyped<TReturn>(this.container, key);
+    const value = await this.provider.getTyped<TReturn>(this.container, key);
+
+    await this.alepha.events.emit(
+      value === undefined ? "cache:miss" : "cache:hit",
+      { container: this.container, key },
+    );
+
+    return value;
   }
 
   protected $provider(): CacheProvider {

package/src/cli/config/defineConfig.ts

@@ -1,4 +1,4 @@
-import type { Alepha } from "alepha";
+import type { Alepha, Service } from "alepha";
 import {
   type AppEntryOptions,
   appEntryOptions,
@@ -10,15 +10,6 @@ import {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type AlephaCliConfigPlugin = (
-  config: AlephaCliConfig,
-  alepha: Alepha,
-) => void;
-
-export const cliConfigPlugins: AlephaCliConfigPlugin[] = [];
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 export interface AlephaCliConfig {
   /**
    * Override entry paths.
@@ -28,7 +19,12 @@ export interface AlephaCliConfig {
   /**
    * Register more services to the Alepha CLI (enhancements, commands, etc.).
    */
-  services?: Array<any>;
+  services?: Array<Service>;
+
+  /**
+   * @alias services Register more services to the Alepha CLI (enhancements, commands, etc.).
+   */
+  plugins?: Array<Service>;
 
   /**
    * Configure Alepha build command.
@@ -58,6 +54,12 @@ export const defineConfig = (config: AlephaCliConfig) => {
       }
     }
 
+    if (config.plugins) {
+      for (const it of config.plugins) {
+        alepha.with(it);
+      }
+    }
+
     if (config.env) {
       for (const [key, value] of Object.entries(config.env)) {
         process.env[key] = String(value);
@@ -76,10 +78,6 @@ export const defineConfig = (config: AlephaCliConfig) => {
       alepha.set(appEntryOptions, config.entry);
     }
 
-    for (const plugin of cliConfigPlugins) {
-      plugin(config, alepha);
-    }
-
     return {};
   };
 };