alepha 0.11.3 → 0.11.5

package/batch.d.ts

@@ -533,6 +533,9 @@ declare class BatchDescriptor<TItem extends TSchema, TResponse = any> extends De
   protected readonly dateTime: DateTimeProvider;
   protected readonly partitions: Map<any, any>;
   protected activeHandlers: PromiseWithResolvers<void>[];
+  protected get maxSize(): number;
+  protected get concurrency(): number;
+  protected get maxDuration(): DurationLike;
   protected retry: _alepha_retry0.RetryDescriptorFn<(items: typebox0.StaticType<[], "Decode", {}, {}, TItem>[]) => TResponse>;
   /**
    * Pushes an item into the batch. The item will be processed

package/bucket.d.ts

@@ -1,5 +1,6 @@
 import * as _alepha_core1 from "alepha";
 import { Alepha, AlephaError, Descriptor, FileLike, KIND, Service } from "alepha";
+import { FileSystem } from "alepha/file";
 import * as fs from "node:fs";
 import * as _alepha_logger0 from "alepha/logger";
 import * as typebox0 from "typebox";
@@ -43,6 +44,7 @@ declare abstract class FileStorageProvider {
 //#region src/providers/MemoryFileStorageProvider.d.ts
 declare class MemoryFileStorageProvider implements FileStorageProvider {
   readonly files: Record<string, FileLike>;
+  private readonly fileSystem;
   upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
   download(bucketName: string, fileId: string): Promise<FileLike>;
   exists(bucketName: string, fileId: string): Promise<boolean>;
@@ -326,6 +328,7 @@ interface BucketFileOptions {
 }
 declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
   readonly provider: FileStorageProvider | MemoryFileStorageProvider;
+  private readonly fileSystem;
   get name(): string;
   /**
    * Uploads a file to the bucket.
@@ -449,6 +452,7 @@ declare class LocalFileStorageProvider implements FileStorageProvider {
   protected readonly alepha: Alepha;
   protected readonly log: _alepha_logger0.Logger;
   protected readonly metadataService: FileMetadataService;
+  protected readonly fileSystem: FileSystem;
   options: {
     storagePath: string;
   };

package/command.d.ts

@@ -141,8 +141,14 @@ interface CommandDescriptorOptions<T extends TObject, A extends TSchema> {
   args?: A;
   /**
    * If false, skip summary message at the end of the command execution.
+   * Summary will display only if ({ run }) method calls were made.
    */
   summary?: boolean;
+  /**
+   * Marks this command as the root command.
+   * Equivalent to setting name to an empty string "".
+   */
+  root?: boolean;
 }
 declare class CommandDescriptor<T extends TObject = TObject, A extends TSchema = TSchema> extends Descriptor<CommandDescriptorOptions<T, A>> {
   readonly flags: TObject<{}>;
@@ -195,6 +201,14 @@ declare class CliProvider {
   protected readonly onReady: _alepha_core1.HookDescriptor<"ready">;
   get commands(): CommandDescriptor<any>[];
   private findCommand;
+  /**
+   * Get all global flags including those from the root command (name === "")
+   */
+  protected getAllGlobalFlags(): Record<string, {
+    aliases: string[];
+    description?: string;
+    schema: TSchema;
+  }>;
   protected parseCommandFlags(argv: string[], schema: TObject): Record<string, any>;
   protected parseFlags(argv: string[], flagDefs: {
     key: string;

package/core.d.ts

@@ -804,27 +804,31 @@ declare class EventManager {
 }
 //#endregion
 //#region src/providers/StateManager.d.ts
-declare class StateManager<S extends Record<string, any> = State> {
+declare class StateManager<State$1 extends object = State> {
   protected readonly als: AlsProvider;
   protected readonly events: EventManager;
-  protected store: Partial<S>;
-  constructor(store?: Partial<S>);
+  protected store: Partial<State$1>;
+  constructor(store?: Partial<State$1>);
   /**
    * Get a value from the state with proper typing
    */
-  get<Key extends keyof S>(key: Key): S[Key] | undefined;
+  get<Key extends keyof State$1>(key: Key): State$1[Key] | undefined;
   /**
    * Set a value in the state
    */
-  set<Key extends keyof S>(key: Key, value: S[Key] | undefined): this;
+  set<Key extends keyof State$1>(key: Key, value: State$1[Key] | undefined): this;
   /**
    * Check if a key exists in the state
    */
-  has<Key extends keyof S>(key: Key): boolean;
+  has<Key extends keyof State$1>(key: Key): boolean;
   /**
    * Delete a key from the state (set to undefined)
    */
-  del<Key extends keyof S>(key: Key): this;
+  del<Key extends keyof State$1>(key: Key): this;
+  /**
+   * Push a value to an array in the state
+   */
+  push<Key extends keyof OnlyArray<State$1>>(key: Key, value: NonNullable<State$1[Key]> extends Array<infer U> ? U : never): this;
   /**
    * Clear all state
    */
@@ -832,8 +836,9 @@ declare class StateManager<S extends Record<string, any> = State> {
   /**
    * Get all keys that exist in the state
    */
-  keys(): (keyof S)[];
+  keys(): (keyof State$1)[];
 }
+type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends Array<any> ? K : never };
 //#endregion
 //#region src/Alepha.d.ts
 /**
@@ -1049,7 +1054,7 @@ declare class Alepha {
   /**
    * State manager to store arbitrary values.
    */
-  get state(): StateManager<Record<string, any>>;
+  get state(): StateManager<State>;
   /**
    * Codec manager for encoding and decoding data with different formats.
    *
@@ -1294,9 +1299,16 @@ interface State {
   afterAll?: (run: any) => any;
   afterEach?: (run: any) => any;
   onTestFinished?: (run: any) => any;
+  /**
+   * List of static assets to be copied to the output directory.
+   */
+  assets?: Array<string>;
 }
 interface Hooks {
-  echo: any;
+  /**
+   * Used for testing purposes.
+   */
+  echo: unknown;
   /**
    * Triggered during the configuration phase. Before the start phase.
    */
@@ -1365,6 +1377,12 @@ interface RunOptions {
   cluster?: boolean;
 }
 //#endregion
+//#region src/helpers/boot.d.ts
+declare const boot: {
+  getClientEntry: (root?: string) => Promise<string | undefined>;
+  getServerEntry: (root?: string, explicitEntry?: string) => Promise<string>;
+};
+//#endregion
 //#region src/constants/OPTIONS.d.ts
 /**
  * Used for descriptors options.
@@ -1543,6 +1561,251 @@ declare class TooLateSubstitutionError extends AlephaError {
   constructor(original: string, substitution: string);
 }
 //#endregion
+//#region src/schemas/pageSchema.d.ts
+/**
+ * Create a pagination schema for the given object schema.
+ *
+ * Provides a standardized pagination response format compatible with Spring Data's Page interface.
+ * This schema can be used across any data source (databases, APIs, caches, etc.).
+ *
+ * @example
+ * ```ts
+ * const userSchema = t.object({ id: t.int(), name: t.text() });
+ * const userPageSchema = pageSchema(userSchema);
+ * ```
+ *
+ * @example In an API endpoint
+ * ```ts
+ * $action({
+ *   output: pageSchema(UserSchema),
+ *   handler: async () => {
+ *     return await userRepo.paginate();
+ *   }
+ * })
+ * ```
+ */
+declare const pageSchema: <T extends TObject | TRecord>(objectSchema: T, options?: TObjectOptions) => TPage<T>;
+type TPage<T extends TObject | TRecord> = TObject<{
+  content: TArray<T>;
+  page: TObject<{
+    number: TInteger;
+    size: TInteger;
+    offset: TInteger;
+    numberOfElements: TInteger;
+    totalElements: TOptionalAdd<TInteger>;
+    totalPages: TOptionalAdd<TInteger>;
+    isEmpty: TBoolean;
+    isFirst: TBoolean;
+    isLast: TBoolean;
+    sort: TOptionalAdd<TObject<{
+      sorted: TBoolean;
+      fields: TArray<TObject<{
+        field: TString;
+        direction: TSchema;
+      }>>;
+    }>>;
+  }>;
+}>;
+/**
+ * Opinionated type definition for a paginated response.
+ *
+ * Inspired by Spring Data's Page interface with all essential pagination metadata.
+ * This generic type can be used with any data source.
+ *
+ * @example
+ * ```ts
+ * const page: Page<User> = {
+ *   content: [user1, user2, ...],
+ *   page: {
+ *     number: 0,
+ *     size: 10,
+ *     offset: 0,
+ *     numberOfElements: 10,
+ *     totalElements: 1200,
+ *     totalPages: 120,
+ *     isEmpty: false,
+ *     isFirst: true,
+ *     isLast: false,
+ *     sort: {
+ *       sorted: true,
+ *       fields: [
+ *         { field: "name", direction: "asc" }
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type Page<T> = {
+  /**
+   * Array of items on the current page.
+   */
+  content: T[];
+  page: {
+    /**
+     * Page number, starting from 0.
+     */
+    number: number;
+    /**
+     * Number of items per page (requested page size).
+     */
+    size: number;
+    /**
+     * Offset in the dataset (page × size).
+     */
+    offset: number;
+    /**
+     * Number of elements in THIS page (content.length).
+     * Different from totalElements which is the total across all pages.
+     */
+    numberOfElements: number;
+    /**
+     * Total number of elements across all pages.
+     * Only available when counting is enabled.
+     */
+    totalElements?: number;
+    /**
+     * Total number of pages.
+     * Only available when `totalElements` is present.
+     */
+    totalPages?: number;
+    /**
+     * Indicates if the current page has no items (numberOfElements === 0).
+     */
+    isEmpty: boolean;
+    /**
+     * Indicates if this is the first page (number === 0).
+     */
+    isFirst: boolean;
+    /**
+     * Indicates if this is the last page (no more pages after this).
+     */
+    isLast: boolean;
+    /**
+     * Sort metadata indicating what sorting was applied.
+     * Only present when sorting is applied.
+     */
+    sort?: {
+      /**
+       * Whether the results are sorted.
+       */
+      sorted: boolean;
+      /**
+       * The fields and directions used for sorting.
+       */
+      fields: Array<{
+        field: string;
+        direction: "asc" | "desc";
+      }>;
+    };
+  };
+};
+//#endregion
+//#region src/helpers/createPagination.d.ts
+/**
+ * Create a pagination object from an array of entities.
+ *
+ * This is a pure function that works with any data source (databases, APIs, caches, arrays, etc.).
+ * It handles the core pagination logic including:
+ * - Slicing the content to the requested page size
+ * - Calculating pagination metadata (offset, page number, etc.)
+ * - Determining navigation state (isFirst, isLast)
+ * - Including sort metadata when provided
+ *
+ * @param entities - The entities to paginate (should include one extra item to detect if there's a next page)
+ * @param limit - The limit of the pagination (page size)
+ * @param offset - The offset of the pagination (starting position)
+ * @param sort - Optional sort metadata to include in response
+ * @returns A complete Page object with content and metadata
+ *
+ * @example Basic pagination
+ * ```ts
+ * const users = await fetchUsers({ limit: 11, offset: 0 }); // Fetch limit + 1
+ * const page = createPagination(users, 10, 0);
+ * // page.content has max 10 items
+ * // page.page.isLast tells us if there are more pages
+ * ```
+ *
+ * @example With sorting
+ * ```ts
+ * const page = createPagination(
+ *   entities,
+ *   10,
+ *   0,
+ *   [{ column: "name", direction: "asc" }]
+ * );
+ * ```
+ *
+ * @example In a custom service
+ * ```ts
+ * class MyService {
+ *   async listItems(page: number, size: number) {
+ *     const items = await this.fetchItems({ limit: size + 1, offset: page * size });
+ *     return createPagination(items, size, page * size);
+ *   }
+ * }
+ * ```
+ */
+declare function createPagination<T>(entities: T[], limit?: number, offset?: number, sort?: Array<{
+  column: string;
+  direction: "asc" | "desc";
+}>): Page<T>;
+//#endregion
+//#region src/interfaces/Pagination.d.ts
+/**
+ * Generic pagination request parameters.
+ *
+ * This interface defines the common structure for pagination queries
+ * across all data sources. Individual packages can extend or adapt this
+ * interface for their specific needs.
+ *
+ * @example Basic usage
+ * ```ts
+ * const query: PageRequest = {
+ *   page: 0,
+ *   size: 20
+ * };
+ * ```
+ *
+ * @example With all parameters
+ * ```ts
+ * const query: PageRequest = {
+ *   page: 2,
+ *   size: 50
+ * };
+ * ```
+ */
+interface PageRequest {
+  /**
+   * The page number to retrieve (0-indexed).
+   * @default 0
+   */
+  page?: number;
+  /**
+   * The number of items per page.
+   * @default 10
+   */
+  size?: number;
+}
+/**
+ * Sort direction for ordering results.
+ */
+type SortDirection = "asc" | "desc";
+/**
+ * Sort field specification.
+ */
+interface SortField {
+  /**
+   * The field/column name to sort by.
+   */
+  field: string;
+  /**
+   * The sort direction.
+   * @default "asc"
+   */
+  direction: SortDirection;
+}
+//#endregion
 //#region src/index.d.ts
 /**
  * Run Alepha application, trigger start lifecycle.
@@ -1560,5 +1823,5 @@ declare class TooLateSubstitutionError extends AlephaError {
  */
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
 //#endregion
-export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, CodecManager, Configurable, ContainerLockedError, CursorDescriptor, DecodeOptions, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, EncodeOptions, EncodeResult, Encoding, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, JsonSchemaCodec, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, RunFunction, SchemaCodec, Service, ServiceEntry, ServiceSubstitution, State, StateManager, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, type TBigInt, type TBoolean, TFile, type TInteger, type TKeysToIndexer, type TNull, type TNumber, type TNumberOptions, type TObject, type TObjectOptions, type TOptional, type TOptionalAdd, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, TTextOptions, type TTuple, type TUnion, type TUnsafe, type TVoid, TextLength, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxErrorParams, TypeBoxFormat, TypeBoxValue, TypeGuard, TypeProvider, WithModule, __alephaRef, createDescriptor, isClass, isEmail, isFileLike, isTypeFile, isURL, isUUID, run, t };
+export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, CodecManager, Configurable, ContainerLockedError, CursorDescriptor, DecodeOptions, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, EncodeOptions, EncodeResult, Encoding, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, JsonSchemaCodec, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, Page, PageRequest, RunFunction, SchemaCodec, Service, ServiceEntry, ServiceSubstitution, SortDirection, SortField, State, StateManager, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, type TBigInt, type TBoolean, TFile, type TInteger, type TKeysToIndexer, type TNull, type TNumber, type TNumberOptions, type TObject, type TObjectOptions, type TOptional, type TOptionalAdd, TPage, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, TTextOptions, type TTuple, type TUnion, type TUnsafe, type TVoid, TextLength, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxErrorParams, TypeBoxFormat, TypeBoxValue, TypeGuard, TypeProvider, WithModule, __alephaRef, boot, createDescriptor, createPagination, isClass, isEmail, isFileLike, isTypeFile, isURL, isUUID, pageSchema, run, t };
 //# sourceMappingURL=index.d.ts.map

package/datetime.d.ts

@@ -85,12 +85,13 @@ declare class DateTimeProvider {
     signal?: AbortSignal;
     now?: number;
   }): Promise<void>;
-  createInterval(run: () => unknown, distance: DurationLike): Interval;
+  createInterval(run: () => unknown, distance: DurationLike, start?: boolean): Interval;
   /**
    * Run a callback after a certain duration.
    */
   createTimeout(callback: () => void, duration: DurationLike, now?: number): Timeout;
   clearTimeout(timeout: Timeout): void;
+  clearInterval(interval: Interval): void;
   /**
    * Run a function with a deadline.
    */