alepha 0.7.7 → 0.8.1

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,17 @@
-<div align="center">
+# Alepha Alepha
 
-<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>
+TypeScript framework for building full-stack apps with strict conventions, and React-based SPA or SSR without filesystem-based routing.
 
 ## Installation
 
+This package is part of the Alepha framework and can be installed via the all-in-one package:
+
 ```bash
 npm install alepha
 ```
 
-## Usage
-
-Minimalist http server with a single endpoint.
-
-```ts
-import { run } from "alepha";
-import { $action } from "alepha/server";
+Alternatively, you can install it individually:
 
-class App {
-  hello = $action({
-    handler: () => "Hello world!",
-  })
-}
-
-run(App);
+```bash
+npm install @alepha/core alepha
 ```

package/batch.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/batch');
+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/batch.d.ts

@@ -0,0 +1,147 @@
+import { Alepha, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TSchema } from "alepha";
+import { DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
+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]: string;
+};
+// ---------------------------------------------------------------------------------------------------------------------
+interface BatchDescriptorOptions<TItem extends TSchema, TResponse = any> {
+  /**
+  * A TypeBox schema to validate each item pushed to the batch.
+  */
+  schema: TItem;
+  /**
+  * 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
+  */
+  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"]
+  */
+  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.
+  */
+  partitionBy?: (item: Static<TItem>) => string;
+  /**
+  * 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?: Omit<RetryDescriptorOptions<() => Array<Static<TItem>>>, "handler">;
+}
+interface BatchDescriptor<TItem extends TSchema, TResponse = any> {
+  [KIND]: typeof KEY;
+  [OPTIONS]: BatchDescriptorOptions<TItem, 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>;
+}
+//#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>;
+}
+/**
+* Process every $batch.
+*/
+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>;
+}
+//#endregion
+//#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
+/**
+* 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.
+*
+* ### Basic Example: A Simple Event Logger
+*
+* Let's create a batch processor that collects log messages and prints them to the console every 5 seconds or whenever 10 messages have been collected.
+*
+* ```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 class AlephaBatch implements Module {
+  readonly name = "alepha.batch";
+  readonly $services: (alepha: Alepha) => Alepha;
+}
+//#endregion
+export { $batch, AlephaBatch, BatchDescriptor, BatchDescriptorOptions, BatchDescriptorProvider };
+//# sourceMappingURL=index.d.ts.map

package/batch.js

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

package/cache/redis.d.ts

@@ -1,22 +1,18 @@
-import { CacheProvider } from "@alepha/cache";
-import * as _alepha_core2 from "@alepha/core";
-import { Alepha, Module, Static } from "@alepha/core";
-import { RedisProvider } from "@alepha/redis";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import { CacheProvider } from "alepha/cache";
+import { Alepha, Logger, Module, Static, TObject, TOptional, TString } from "alepha";
+import { RedisProvider } from "alepha/redis";
 
 //#region src/providers/RedisCacheProvider.d.ts
-declare const envSchema: _alepha_core2.TObject<{
-  REDIS_CACHE_PREFIX: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+declare const envSchema: TObject<{
+  REDIS_CACHE_PREFIX: TOptional<TString>;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
 declare class RedisCacheProvider implements CacheProvider {
-  protected readonly log: _alepha_core2.Logger;
+  protected readonly log: Logger;
   protected readonly redisProvider: RedisProvider;
-  protected readonly env: {
-    REDIS_CACHE_PREFIX?: string | undefined;
-  };
+  protected readonly env: Static<typeof envSchema>;
   protected readonly alepha: Alepha;
   get(name: string, key: string): Promise<Uint8Array | undefined>;
   set(name: string, key: string, value: Uint8Array | string, ttl?: number): Promise<Uint8Array>;
@@ -27,14 +23,13 @@ declare class RedisCacheProvider implements CacheProvider {
 }
 //#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
- */
+* 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;