alepha 0.7.7 → 0.8.0

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,114 @@
+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";
+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>;
+}
+/**
+* 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>;
+}
+//#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;
+}
+//#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,15 @@ 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
- */
+* 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;

package/cache.d.ts

@@ -1,43 +1,41 @@
-import * as _alepha_core0 from "@alepha/core";
-import * as _alepha_core5 from "@alepha/core";
-import { Alepha, KIND, Module, OPTIONS, Static } from "@alepha/core";
-import { DateTimeProvider, DurationLike, Timeout } from "@alepha/datetime";
-import * as _sinclair_typebox1 from "@sinclair/typebox";
+import { Alepha, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TBoolean, TNumber, TObject, TOptional, TString } from "alepha";
+import { DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
 
 //#region src/providers/CacheProvider.d.ts
+
 /**
- * Cache provider interface.
- *
- * All methods are asynchronous and return promises.
- * Values are stored as Uint8Array.
- */
+* Cache provider interface.
+*
+* All methods are asynchronous and return promises.
+* Values are stored as Uint8Array.
+*/
 declare abstract class CacheProvider {
   /**
-   * Get the value of a key.
-   *
-   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-   * @param key The key of the value to get.
-   *
-   * @return The value of the key, or undefined if the key does not exist.
-   */
+  * Get the value of a key.
+  *
+  * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+  * @param key The key of the value to get.
+  *
+  * @return The value of the key, or undefined if the key does not exist.
+  */
   abstract get(name: string, key: string): Promise<Uint8Array | undefined>;
   /**
-   * Set the string value of a key.
-   *
-   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-   * @param key The key of the value to set.
-   * @param value The value to set.
-   * @param ttl The time-to-live of the key, in milliseconds.
-   *
-   * @return The value of the key.
-   */
+  * Set the string value of a key.
+  *
+  * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+  * @param key The key of the value to set.
+  * @param value The value to set.
+  * @param ttl The time-to-live of the key, in milliseconds.
+  *
+  * @return The value of the key.
+  */
   abstract set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
   /**
-   * Remove the specified keys.
-   *
-   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-   * @param keys The keys to delete.
-   */
+  * Remove the specified keys.
+  *
+  * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+  * @param keys The keys to delete.
+  */
   abstract del(name: string, ...keys: string[]): Promise<void>;
   abstract has(name: string, key: string): Promise<boolean>;
   abstract keys(name: string): Promise<string[]>;
@@ -46,76 +44,77 @@ declare abstract class CacheProvider {
 //#region src/descriptors/$cache.d.ts
 declare const KEY = "CACHE";
 /**
- * Cache Descriptor
- */
+* Cache Descriptor
+*/
 declare const $cache: {
   <TReturn = string, TParameter extends any[] = any[]>(options?: CacheDescriptorOptions<TReturn, TParameter>): CacheDescriptor<TReturn, TParameter>;
   [KIND]: string;
 };
+// ---------------------------------------------------------------------------------------------------------------------
 interface CacheDescriptorOptions<TReturn, TParameter extends any[] = any[]> {
   /**
-   * The cache name. This is useful for invalidating multiple caches at once.
-   *
-   * Store key as `cache:$name:$key`.
-   *
-   * @default ClassName:methodName
-   */
+  * The cache name. This is useful for invalidating multiple caches at once.
+  *
+  * Store key as `cache:$name:$key`.
+  *
+  * @default ClassName:methodName
+  */
   name?: string;
   /**
-   * Function which returns cached data.
-   * @param args Arguments for handler.
-   */
+  * Function which returns cached data.
+  * @param args Arguments for handler.
+  */
   handler?: (...args: TParameter) => TReturn;
   /**
-   * The key generator for the cache.
-   * If not provided, the arguments will be json.stringify().
-   */
+  * The key generator for the cache.
+  * If not provided, the arguments will be json.stringify().
+  */
   key?: (...args: TParameter) => string;
   /**
-   * The store provider for the cache.
-   * If not provided, the default store provider will be used.
-   */
+  * The store provider for the cache.
+  * If not provided, the default store provider will be used.
+  */
   provider?: CacheProvider | (() => CacheProvider) | "memory";
   /**
-   * The time-to-live for the cache in seconds.
-   * Set 0 to skip expiration.
-   *
-   * @default 300 (5 minutes).
-   */
+  * The time-to-live for the cache in seconds.
+  * Set 0 to skip expiration.
+  *
+  * @default 300 (5 minutes).
+  */
   ttl?: DurationLike;
   /**
-   * If the cache is disabled.
-   */
+  * If the cache is disabled.
+  */
   disabled?: boolean;
 }
 interface CacheDescriptor<TReturn = any, TParameter extends any[] = any[]> {
   [KIND]: typeof KEY;
   [OPTIONS]: CacheDescriptorOptions<TReturn, TParameter>;
   /**
-   * Cache handler.
-   */
+  * Cache handler.
+  */
   (...args: TParameter): Promise<TReturn>;
   /**
-   * Cache key generator.
-   */
+  * Cache key generator.
+  */
   key: (...args: TParameter) => string;
   /**
-   * Invalidate cache by keys.
-   */
+  * Invalidate cache by keys.
+  */
   invalidate: (...keys: string[]) => Promise<void>;
   /**
-   * Set cache with key, value and ttl.
-   *
-   * @param key
-   * @param value
-   * @param ttl
-   */
+  * Set cache with key, value and ttl.
+  *
+  * @param key
+  * @param value
+  * @param ttl
+  */
   set: (key: string, value: TReturn, ttl?: DurationLike) => Promise<void>;
   /**
-   * Get cache by key.
-   *
-   * @param key
-   */
+  * Get cache by key.
+  *
+  * @param key
+  */
   get: (key: string) => Promise<TReturn | undefined>;
 }
 //#endregion
@@ -128,7 +127,7 @@ type CacheValue = {
 };
 declare class MemoryCacheProvider implements CacheProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _alepha_core0.Logger;
+  protected readonly log: Logger;
   protected store: Record<CacheName, Record<CacheKey, CacheValue>>;
   get(name: string, key: string): Promise<Uint8Array | undefined>;
   set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
@@ -138,10 +137,10 @@ declare class MemoryCacheProvider implements CacheProvider {
 }
 //#endregion
 //#region src/providers/CacheDescriptorProvider.d.ts
-declare const envSchema: _alepha_core5.TObject<{
-  CACHE_DEFAULT_TTL: _sinclair_typebox1.TNumber;
-  CACHE_PREFIX: _sinclair_typebox1.TOptional<_sinclair_typebox1.TString>;
-  CACHE_ENABLED: _sinclair_typebox1.TBoolean;
+declare const envSchema: TObject<{
+  CACHE_DEFAULT_TTL: TNumber;
+  CACHE_PREFIX: TOptional<TString>;
+  CACHE_ENABLED: TBoolean;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -151,57 +150,53 @@ declare class CacheDescriptorProvider {
   protected readonly cacheProvider: CacheProvider;
   protected readonly memoryCacheProvider: MemoryCacheProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly env: {
-    CACHE_PREFIX?: string | undefined;
-    CACHE_DEFAULT_TTL: number;
-    CACHE_ENABLED: boolean;
-  };
+  protected readonly env: Static<typeof envSchema>;
   protected readonly caches: Cache[];
-  protected readonly configure: _alepha_core5.HookDescriptor<"configure">;
-  register(cache: Cache): Cache<any, any[]>;
+  protected encoder: TextEncoder;
+  protected decoder: TextDecoder;
+  protected codes: {
+    BINARY: number;
+    JSON: number;
+    STRING: number;
+  };
+  protected readonly configure: HookDescriptor<"configure">;
+  register(cache: Cache): Cache;
   processDescriptors(): void;
   getCaches(): Cache[];
   /**
-   * Clear all cache entries.
-   */
+  * Clear all cache entries.
+  */
   clear(): Promise<void>;
   /**
-   * Get the store provider for the given cache options.
-   *
-   * @param options
-   */
+  * Get the store provider for the given cache options.
+  *
+  * @param options
+  */
   provider(options: Pick<CacheDescriptorOptions<any[], any>, "provider">): CacheProvider;
   /**
-   * Get the cache key for the given state and arguments.
-   */
+  * Get the cache key for the given state and arguments.
+  */
   key(cache: Cache, ...args: any[]): string;
   /**
-   * Invalidate the cache for the given state and arguments.
-   */
+  * Invalidate the cache for the given state and arguments.
+  */
   invalidate(cache: Cache, ...keys: string[]): Promise<void>;
   /**
-   * Run the cache handler with the given state and arguments.
-   * You must run on a $cache with a handler defined.
-   */
+  * Run the cache handler with the given state and arguments.
+  * You must run on a $cache with a handler defined.
+  */
   run<TReturn, TParameter extends any[]>(cache: Cache<TReturn, TParameter>, ...args: TParameter): Promise<TReturn>;
   get<TReturn>(cache: Cache<TReturn>, key: string): Promise<TReturn | undefined>;
   /**
-   * Manually set a value in the cache.
-   * It's used by .run() method, but you will need it when you don't have cache handler defined.
-   *
-   * @param cache Cache object with all configuration and options (even TTL).
-   * @param key Cache key, build with .key() method or manually.
-   * @param value Value to store in cache.
-   * @param ttl Override cache.ttl option.
-   */
+  * Manually set a value in the cache.
+  * It's used by .run() method, but you will need it when you don't have cache handler defined.
+  *
+  * @param cache Cache object with all configuration and options (even TTL).
+  * @param key Cache key, build with .key() method or manually.
+  * @param value Value to store in cache.
+  * @param ttl Override cache.ttl option.
+  */
   set<TReturn>(cache: Cache<TReturn>, key: string, value: TReturn, ttl?: DurationLike): Promise<void>;
-  protected encoder: TextEncoder;
-  protected decoder: TextDecoder;
-  protected codes: {
-    BINARY: number;
-    JSON: number;
-    STRING: number;
-  };
   protected serialize<TReturn>(value: TReturn): Uint8Array;
   protected deserialize<TReturn>(uint8Array: Uint8Array): Promise<TReturn>;
 }
@@ -211,15 +206,16 @@ interface Cache<TReturn = any, TParameter extends any[] = any[]> {
 }
 //#endregion
 //#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
 /**
- * Alepha Cache Module
- *
- * This module provides a caching mechanism for Alepha applications.
- *
- * @see {@link $cache}
- * @see {@link CacheProvider}
- * @module alepha.cache
- */
+* Alepha Cache Module
+*
+* This module provides a caching mechanism for Alepha applications.
+*
+* @see {@link $cache}
+* @see {@link CacheProvider}
+* @module alepha.cache
+*/
 declare class AlephaCache implements Module {
   readonly name = "alepha.cache";
   readonly $services: (alepha: Alepha) => Alepha;

package/command.cjs

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

@@ -0,0 +1,154 @@
+import { Alepha, AlephaError, Async, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TObject, TProperties, TSchema, TString } from "alepha";
+import * as fs from "node:fs/promises";
+import { glob } from "node:fs/promises";
+
+//#region src/helpers/Runner.d.ts
+type Task = {
+  name: string;
+  handler: () => any;
+};
+interface Timer {
+  name: string;
+  duration: string;
+}
+interface RunnerMethod {
+  (cmd: string | Array<string | Task>, fn?: () => any): Promise<string>;
+  rm: (glob: string | string[]) => Promise<string>;
+}
+declare class Runner {
+  protected readonly log: Logger;
+  protected readonly timers: Timer[];
+  protected readonly startTime: number;
+  readonly run: RunnerMethod;
+  constructor(log: Logger);
+  protected exec(cmd: string): Promise<string>;
+  /**
+  * Executes one or more tasks.
+  *
+  * @param task - A single task or an array of tasks to run in parallel.
+  */
+  protected execute(task: Task | Task[]): Promise<string>;
+  /**
+  * Prints a summary of all executed tasks and their durations.
+  */
+  summary(): void;
+  protected executeTask(task: Task): Promise<string>;
+  protected renderTable(data: string[][]): void;
+}
+//#endregion
+//#region src/descriptors/$command.d.ts
+declare const KEY = "COMMAND";
+interface CommandDescriptorOptions<T extends TObject> {
+  /**
+  * The handler function to execute when the command is matched.
+  */
+  handler: (args: {
+    flags: Static<T>;
+    run: RunnerMethod;
+    glob: typeof glob;
+    fs: typeof fs;
+  }) => Async<void>;
+  /**
+  * The name of the command. If omitted, the property key is used.
+  *
+  * An empty string "" denotes the root command.
+  */
+  name?: string;
+  /**
+  * A short description of the command, shown in the help message.
+  */
+  description?: string;
+  /**
+  * An array of alternative names for the command.
+  */
+  aliases?: string[];
+  /**
+  * A TypeBox object schema defining the flags for the command.
+  */
+  flags?: T;
+}
+interface CommandDescriptor<T extends TObject> {
+  [KIND]: typeof KEY;
+  [OPTIONS]: CommandDescriptorOptions<T>;
+  /**
+  * Executes the command. This is a placeholder and will be replaced by the provider.
+  */
+  (flags: Static<T>): Promise<void>;
+}
+/**
+* Declares a CLI command.
+*
+* This descriptor allows you to define a command, its flags, and its handler
+* within your Alepha application structure.
+*/
+declare const $command: {
+  <T extends TObject>(options: CommandDescriptorOptions<T>): CommandDescriptor<T>;
+  [KIND]: string;
+};
+//#endregion
+//#region src/errors/CommandError.d.ts
+declare class CommandError extends AlephaError {}
+//#endregion
+//#region src/providers/CommandDescriptorProvider.d.ts
+interface Command {
+  key: string;
+  name: string;
+  description?: string;
+  aliases: string[];
+  flags: TObject<TProperties>;
+  handler: (flags: any) => Promise<void>;
+}
+declare const envSchema: TObject<{
+  CLI_NAME: TString;
+  CLI_DESCRIPTION: TString;
+}>;
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
+declare class CommandDescriptorProvider {
+  protected readonly env: Static<typeof envSchema>;
+  protected readonly alepha: Alepha;
+  protected readonly log: Logger;
+  protected commands: Command[];
+  options: {
+    name: string;
+    description: string;
+    argv: string[];
+  };
+  protected readonly globalFlags: Record<string, {
+    aliases: string[];
+    description: string;
+    schema: TSchema;
+  }>;
+  protected readonly onConfigure: HookDescriptor<"configure">;
+  protected readonly onReady: HookDescriptor<"ready">;
+  private findCommand;
+  protected parseCommandFlags(argv: string[], schema: TObject): Record<string, any>;
+  protected parseFlags(argv: string[], flagDefs: {
+    key: string;
+    aliases: string[];
+    schema: TSchema;
+  }[]): Record<string, any>;
+  private printHelp;
+  private getMaxCmdLength;
+  private getMaxFlagLength;
+}
+//#endregion
+//#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
+/**
+* Alepha Command Module
+*
+* This module provides a powerful way to build command-line interfaces
+* directly within your Alepha application, using declarative descriptors.
+*
+* @see {@link $command}
+* @module alepha.command
+*/
+declare class AlephaCommand implements Module {
+  readonly name = "alepha.command";
+  readonly $services: (alepha: Alepha) => Alepha;
+}
+//#endregion
+export { $command, AlephaCommand, CommandDescriptor, CommandDescriptorOptions, CommandDescriptorProvider, CommandError, Runner, RunnerMethod, Task };
+//# sourceMappingURL=index.d.ts.map

package/command.js

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