alepha 0.8.0 → 0.9.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Feunard
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Feunard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,44 +1,47 @@
-<div align="center">
-
-<h1 >
-<img
-	src="https://raw.githubusercontent.com/feunard/alepha/main/assets/logo.png"
-	width="128"
-	height="128"
-	alt="Logo"
-  valign="middle"
-/>
-Alepha
-</h1>
-<p style="max-width: 512px">
-🚧
-</p>
-<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/v/alepha.svg" alt="npm"/></a>
-<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/l/alepha.svg" alt="npm"/></a>
-<a href="https://codecov.io/gh/feunard/alepha"><img src="https://codecov.io/gh/feunard/alepha/graph/badge.svg?token=ZDLWI514CP" alt="npm"/></a>
-<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/dt/alepha.svg" alt="npm"/></a>
-<a href="https://github.com/feunard/alepha"><img src="https://img.shields.io/github/stars/feunard/alepha.svg?style=social" alt="GitHub stars"/></a>
-</div>
-
-## Installation
-
-```bash
-npm install alepha
-```
-
-## Usage
-
-Minimalist http server with a single endpoint.
-
-```ts
-import { run } from "alepha";
-import { $action } from "alepha/server";
-
-class App {
-  hello = $action({
-    handler: () => "Hello world!",
-  })
-}
-
-run(App);
-```
+<div align="center">
+<h1 >
+<img
+	src="https://raw.githubusercontent.com/feunard/alepha/main/assets/logo.png"
+	width="128"
+	height="128"
+	alt="Logo"
+  valign="middle"
+/>
+Alepha
+</h1>
+<p style="max-width: 512px">
+🚧
+</p>
+<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/v/alepha.svg" alt="npm"/></a>
+<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/l/alepha.svg" alt="npm"/></a>
+<a href="https://codecov.io/gh/feunard/alepha"><img src="https://codecov.io/gh/feunard/alepha/graph/badge.svg?token=ZDLWI514CP" alt="npm"/></a>
+<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/dt/alepha.svg" alt="npm"/></a>
+<a href="https://github.com/feunard/alepha"><img src="https://img.shields.io/github/stars/feunard/alepha.svg?style=social" alt="GitHub stars"/></a>
+</div>
+
+Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.
+
+## Installation
+
+```bash
+npm install alepha
+```
+
+## Usage
+
+Minimalist http server with a single endpoint.
+
+```ts
+import { run } from "alepha";
+import { $action } from "alepha/server";
+
+class App {
+  hello = $action({
+    handler: () => "Hello world!",
+  })
+}
+
+run(App);
+```
+
+👉 For more information, please visit the [documentation](https://feunard.github.io/alepha/).

package/batch.d.ts

@@ -1,114 +1,113 @@
-import { Alepha, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TSchema } from "alepha";
-import { DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
+import * as _alepha_core0$1 from "alepha";
+import * as _alepha_core0 from "alepha";
+import { Descriptor, KIND, Static, TSchema } from "alepha";
+import { DateTimeProvider, DurationLike } from "alepha/datetime";
+import * as _alepha_retry0 from "alepha/retry";
 import { RetryDescriptorOptions } from "alepha/retry";
 
 //#region src/descriptors/$batch.d.ts
-declare const KEY = "BATCH";
+/**
+ * Creates a batch processor. This is useful for grouping multiple operations
+ * (like API calls or database writes) into a single one to improve performance.
+ */
+declare const $batch: {
+  <TItem extends TSchema, TResponse>(options: BatchDescriptorOptions<TItem, TResponse>): BatchDescriptor<TItem, TResponse>;
+  [KIND]: typeof BatchDescriptor;
+};
 interface BatchDescriptorOptions<TItem extends TSchema, TResponse = any> {
   /**
-  * A TypeBox schema to validate each item pushed to the batch.
-  */
+   * A TypeBox schema to validate each item pushed to the batch.
+   */
   schema: TItem;
   /**
-  * The handler function that processes a batch of items.
-  */
+   * The handler function that processes a batch of items.
+   */
   handler: (items: Static<TItem>[]) => TResponse;
   /**
-  * The maximum number of items in a batch. When this size is reached,
-  * the batch is flushed automatically.
-  * @default 10
-  */
+   * The maximum number of items in a batch. When this size is reached,
+   * the batch is flushed automatically.
+   * @default 10
+   */
   maxSize?: number;
   /**
-  * The maximum duration to wait before flushing a batch, even if it's not full.
-  * Starts from the moment the first item is added to a partition.
-  * @default [1, "second"]
-  */
+   * The maximum duration to wait before flushing a batch, even if it's not full.
+   * Starts from the moment the first item is added to a partition.
+   * @default [1, "second"]
+   */
   maxDuration?: DurationLike;
   /**
-  * A function to determine the partition key for an item. Items with the
-  * same key are batched together. If not provided, all items are placed in a single, default partition.
-  */
+   * A function to determine the partition key for an item. Items with the
+   * same key are batched together. If not provided, all items are placed in a single, default partition.
+   */
   partitionBy?: (item: Static<TItem>) => string;
   /**
-  * The maximum number of concurrent `handler` executions.
-  * @default 1
-  */
+   * The maximum number of concurrent `handler` executions.
+   * @default 1
+   */
   concurrency?: number;
   /**
-  * Retry options for the batch handler if it fails.
-  * Leverages the `@alepha/retry` module.
-  */
+   * Retry options for the batch handler if it fails.
+   * Leverages the `@alepha/retry` module.
+   */
   retry?: Omit<RetryDescriptorOptions<() => Array<Static<TItem>>>, "handler">;
 }
-interface BatchDescriptor<TItem extends TSchema, TResponse = any> {
-  [KIND]: typeof KEY;
-  [OPTIONS]: BatchDescriptorOptions<TItem, TResponse>;
+declare class BatchDescriptor<TItem extends TSchema, TResponse = any> extends Descriptor<BatchDescriptorOptions<TItem, TResponse>> {
+  protected readonly log: _alepha_core0$1.Logger;
+  protected readonly dateTime: DateTimeProvider;
+  protected readonly partitions: Map<any, any>;
+  protected activeHandlers: PromiseWithResolvers<void>[];
+  protected retry: _alepha_retry0.RetryDescriptorFn<(items: (TItem & {
+    params: [];
+  })["static"][]) => TResponse>;
   /**
-  * Pushes an item into the batch. The item will be processed
-  * asynchronously with other items when the batch is flushed.
-  */
-  push: (item: Static<TItem>) => Promise<TResponse>;
-  /**
-  * Manually triggers a flush for one or all partitions.
-  * @param partitionKey Optional. If provided, only flushes the specified partition. Otherwise, all partitions are flushed.
-  */
-  flush: (partitionKey?: string) => Promise<TResponse>;
-}
-/**
-* Creates a batch processor. This is useful for grouping multiple operations
-* (like API calls or database writes) into a single one to improve performance.
-*/
-declare const $batch: {
-  <TItem extends TSchema, TResponse>(options: BatchDescriptorOptions<TItem, TResponse>): BatchDescriptor<TItem, TResponse>;
-  [KIND]: string;
-};
-//#endregion
-//#region src/providers/BatchDescriptorProvider.d.ts
-interface PartitionState<TItem extends TSchema> {
-  items: Static<TItem>[];
-  timeout?: Timeout;
-  // Promises to resolve/reject when the batch is processed
-  resolvers: Array<{
-    resolve: (result?: any) => void;
-    reject: (reason?: any) => void;
-  }>;
-}
-interface BatchInstance<TItem extends TSchema> {
-  id: string;
-  options: BatchDescriptorOptions<TItem>;
-  partitions: Map<string, PartitionState<TItem>>;
-  activeHandlers: PromiseWithResolvers<void>[];
-  handler: (items: Static<TItem>[]) => Promise<void>;
-}
-declare class BatchDescriptorProvider {
-  protected readonly alepha: Alepha;
-  protected readonly log: Logger;
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly instances: Map<string, BatchInstance<any>>;
-  protected readonly configure: HookDescriptor<"configure">;
-  // On application stop, flush all pending batches gracefully.
-  protected readonly onStop: HookDescriptor<"stop">;
-  protected push<TItem>(id: string, item: TItem): Promise<void>;
-  protected flush(id: string, partitionKey?: string): Promise<void>;
-  protected flushPartition<TItem extends TSchema>(instance: BatchInstance<TItem>, partitionKey: string): Promise<void>;
+   * Pushes an item into the batch. The item will be processed
+   * asynchronously with other items when the batch is flushed.
+   */
+  push(item: Static<TItem>): Promise<TResponse>;
+  flush(partitionKey?: string): Promise<void>;
+  protected flushPartition(partitionKey: string): Promise<void>;
+  protected readonly dispose: _alepha_core0$1.HookDescriptor<"stop">;
 }
+//# sourceMappingURL=$batch.d.ts.map
 //#endregion
 //#region src/index.d.ts
-// ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Batch Module
-*
-* This module provides a powerful batch processing utility that can group
-* multiple operations into a single one based on size, time, or partitions.
-*
-* @see {@link $batch}
-* @module alepha.batch
-*/
-declare class AlephaBatch implements Module {
-  readonly name = "alepha.batch";
-  readonly $services: (alepha: Alepha) => Alepha;
-}
+ * This module allows you to group multiple asynchronous operations into a single "batch," which is then processed together.
+ * This is an essential pattern for improving performance, reducing I/O, and interacting efficiently with rate-limited APIs or databases.
+ *
+ * ```ts
+ * import { Alepha, $hook, run, t } from "alepha";
+ * import { $batch } from "alepha/batch";
+ *
+ * class LoggingService {
+ *   // define the batch processor
+ *   logBatch = $batch({
+ *     schema: t.string(),
+ *     maxSize: 10,
+ *     maxDuration: [5, "seconds"],
+ *     handler: async (items) => {
+ *       console.log(`[BATCH LOG] Processing ${items.length} events:`, items);
+ *     },
+ *   });
+ *
+ *   // example of how to use it
+ *   onReady = $hook({
+ *     on: "ready",
+ *     handler: async () => {
+ *       this.logBatch.push("Application started.");
+ *       this.logBatch.push("User authenticated.");
+ *       // ... more events pushed from elsewhere in the app
+ *     },
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link $batch}
+ * @module alepha.batch
+ */
+declare const AlephaBatch: _alepha_core0.ModuleDescriptor;
+//# sourceMappingURL=index.d.ts.map
+
 //#endregion
-export { $batch, AlephaBatch, BatchDescriptor, BatchDescriptorOptions, BatchDescriptorProvider };
+export { $batch, AlephaBatch, BatchDescriptor, BatchDescriptorOptions };
 //# sourceMappingURL=index.d.ts.map

package/bucket.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/bucket');
+Object.keys(m).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return m[k]; }
+	});
+});

package/bucket.d.ts

@@ -0,0 +1,194 @@
+import * as _alepha_core0$1 from "alepha";
+import * as _alepha_core0 from "alepha";
+import { Alepha, Descriptor, FileLike, KIND, Service } from "alepha";
+import * as fs from "node:fs";
+import * as _sinclair_typebox0 from "@sinclair/typebox";
+
+//#region src/providers/FileStorageProvider.d.ts
+declare abstract class FileStorageProvider {
+  /**
+   * Uploads a file to the storage.
+   *
+   * @param bucketName - Container name
+   * @param file - File to upload
+   * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.
+   * @return The identifier of the uploaded file.
+   */
+  abstract upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
+  /**
+   * Downloads a file from the storage.
+   *
+   * @param bucketName - Container name
+   * @param fileId - Identifier of the file to download
+   * @return The downloaded file as a FileLike object.
+   */
+  abstract download(bucketName: string, fileId: string): Promise<FileLike>;
+  /**
+   * Check if fileId exists in the storage bucket.
+   *
+   * @param bucketName - Container name
+   * @param fileId - Identifier of the file to stream
+   * @return True is the file exists, false otherwise.
+   */
+  abstract exists(bucketName: string, fileId: string): Promise<boolean>;
+  /**
+   * Delete permanently a file from the storage.
+   *
+   * @param bucketName - Container name
+   * @param fileId - Identifier of the file to delete
+   */
+  abstract delete(bucketName: string, fileId: string): Promise<void>;
+}
+//# sourceMappingURL=FileStorageProvider.d.ts.map
+//#endregion
+//#region src/providers/MemoryFileStorageProvider.d.ts
+declare class MemoryFileStorageProvider implements FileStorageProvider {
+  readonly files: Record<string, FileLike>;
+  upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
+  download(bucketName: string, fileId: string): Promise<FileLike>;
+  exists(bucketName: string, fileId: string): Promise<boolean>;
+  delete(bucketName: string, fileId: string): Promise<void>;
+  protected createId(): string;
+}
+//# sourceMappingURL=MemoryFileStorageProvider.d.ts.map
+
+//#endregion
+//#region src/descriptors/$bucket.d.ts
+/**
+ * Create a container for storing files.
+ *
+ * @example
+ * ```ts
+ * import { $bucket } from "alepha/bucket";
+ *
+ * class App {
+ *   images = $bucket();
+ *
+ *   uploadImage(file: FileLike): Promise<string> {
+ *     return this.images.upload(file);
+ *   }
+ * }
+ * ```
+ */
+declare const $bucket: {
+  (options: BucketDescriptorOptions): BucketDescriptor;
+  [KIND]: typeof BucketDescriptor;
+};
+interface BucketDescriptorOptions extends BucketFileOptions {
+  /**
+   * File storage provider. If not provided, the default provider will be used.
+   */
+  provider?: Service<FileStorageProvider> | "memory";
+  /**
+   * Optional name of the bucket. If not provided, the key of the descriptor will be used.
+   */
+  name?: string;
+}
+declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
+  readonly provider: MemoryFileStorageProvider | FileStorageProvider;
+  get name(): string;
+  /**
+   * Uploads a file to the bucket.
+   */
+  upload(file: FileLike, options?: BucketFileOptions): Promise<string>;
+  /**
+   * Delete permanently a file from the bucket.
+   */
+  delete(fileId: string): Promise<void>;
+  /**
+   * Checks if a file exists in the bucket.
+   */
+  exists(fileId: string): Promise<boolean>;
+  /**
+   * Downloads a file from the bucket.
+   */
+  download(fileId: string): Promise<FileLike>;
+  protected $provider(): MemoryFileStorageProvider | FileStorageProvider;
+}
+interface BucketFileOptions {
+  /**
+   * Optional description of the bucket.
+   */
+  description?: string;
+  /**
+   * Allowed MIME types.
+   */
+  mimeTypes?: string[];
+  /**
+   * Maximum size of the files in the bucket.
+   *
+   * @default 10
+   */
+  maxSize?: number;
+}
+//# sourceMappingURL=$bucket.d.ts.map
+//#endregion
+//#region src/errors/FileNotFoundError.d.ts
+declare class FileNotFoundError extends Error {
+  readonly status = 404;
+}
+//# sourceMappingURL=FileNotFoundError.d.ts.map
+//#endregion
+//#region src/providers/LocalFileStorageProvider.d.ts
+declare class LocalFileStorageProvider implements FileStorageProvider {
+  static METADATA_HEADER_LENGTH: number;
+  protected readonly alepha: Alepha;
+  options: {
+    storagePath: string;
+  };
+  protected readonly configure: _alepha_core0$1.HookDescriptor<"start">;
+  upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
+  download(bucketName: string, fileId: string): Promise<FileLike>;
+  exists(bucketName: string, fileId: string): Promise<boolean>;
+  delete(bucketName: string, fileId: string): Promise<void>;
+  protected stat(container: string, fileId: string): Promise<fs.Stats>;
+  protected createId(): string;
+  protected path(container: string, fileId?: string): string;
+  protected isErrorNoEntry(error: unknown): boolean;
+}
+declare const fileMetadataSchema: _sinclair_typebox0.TObject<{
+  name: _sinclair_typebox0.TString;
+  type: _sinclair_typebox0.TString;
+  size: _sinclair_typebox0.TNumber;
+}>;
+//# sourceMappingURL=LocalFileStorageProvider.d.ts.map
+//#endregion
+//#region src/index.d.ts
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Triggered when a file is uploaded to a bucket.
+     * Can be used to perform actions after a file is uploaded, like creating a database record!
+     */
+    "bucket:file:uploaded": {
+      id: string;
+      file: FileLike;
+      bucket: BucketDescriptor;
+      options: BucketFileOptions;
+    };
+    /**
+     * Triggered when a file is deleted from a bucket.
+     */
+    "bucket:file:deleted": {
+      id: string;
+      bucket: BucketDescriptor;
+    };
+  }
+}
+/**
+ * Provides file storage capabilities through declarative bucket descriptors with support for multiple storage backends.
+ *
+ * The bucket module enables unified file operations across different storage systems using the `$bucket` descriptor
+ * on class properties. It abstracts storage provider differences, offering consistent APIs for local filesystem,
+ * cloud storage, or in-memory storage for testing environments.
+ *
+ * @see {@link $bucket}
+ * @see {@link FileStorageProvider}
+ * @module alepha.bucket
+ */
+declare const AlephaBucket: _alepha_core0.ModuleDescriptor;
+//# sourceMappingURL=index.d.ts.map
+
+//#endregion
+export { $bucket, AlephaBucket, BucketDescriptor, BucketDescriptorOptions, BucketFileOptions, FileNotFoundError, FileStorageProvider, LocalFileStorageProvider, MemoryFileStorageProvider, fileMetadataSchema };
+//# sourceMappingURL=index.d.ts.map

package/bucket.js

@@ -0,0 +1 @@
+export * from '@alepha/bucket'

package/cache/redis.d.ts

@@ -1,10 +1,12 @@
 import { CacheProvider } from "alepha/cache";
-import { Alepha, Logger, Module, Static, TObject, TOptional, TString } from "alepha";
+import * as _alepha_core0$1 from "alepha";
+import * as _alepha_core0 from "alepha";
+import { Alepha, Logger, Static } from "alepha";
 import { RedisProvider } from "alepha/redis";
 
 //#region src/providers/RedisCacheProvider.d.ts
-declare const envSchema: TObject<{
-  REDIS_CACHE_PREFIX: TOptional<TString>;
+declare const envSchema: _alepha_core0$1.TObject<{
+  REDIS_CACHE_PREFIX: _alepha_core0$1.TOptional<_alepha_core0$1.TString>;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -18,24 +20,20 @@ declare class RedisCacheProvider implements CacheProvider {
   set(name: string, key: string, value: Uint8Array | string, ttl?: number): Promise<Uint8Array>;
   del(name: string, ...keys: string[]): Promise<void>;
   has(name: string, key: string): Promise<boolean>;
-  keys(name: string): Promise<string[]>;
+  keys(name: string, filter?: string): Promise<string[]>;
   protected prefix(...path: string[]): string;
 }
 //#endregion
 //#region src/index.d.ts
-// ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Cache Redis Module
-*
-* Plugin for Alepha Cache that provides Redis caching capabilities.
-*
-* @see {@link RedisCacheProvider}
-* @module alepha.cache.redis
-*/
-declare class AlephaCacheRedis implements Module {
-  readonly name = "alepha.cache.redis";
-  readonly $services: (alepha: Alepha) => Alepha;
-}
+ * Plugin for Alepha Cache that provides Redis caching capabilities.
+ *
+ * @see {@link RedisCacheProvider}
+ * @module alepha.cache.redis
+ */
+declare const AlephaCacheRedis: _alepha_core0.ModuleDescriptor;
+//# sourceMappingURL=index.d.ts.map
+
 //#endregion
 export { AlephaCacheRedis, RedisCacheProvider };
 //# sourceMappingURL=index.d.ts.map