@elysiumjs/core 0.4.3 → 0.5.0

package/README.md

@@ -1,6 +1,10 @@
 # @elysiumjs/core
 
-Core functionality for the Elysium framework.
+Core functionalities for the Elysium.js framework.
+
+> **NOTE**
+>
+> This package is part of the Elysium.js framework, which is built exclusively for Bun runtime.
 
 ## Installation
 
@@ -8,6 +12,20 @@ Core functionality for the Elysium framework.
 bun install @elysiumjs/core
 ```
 
+## Features
+
+- Dependency Injection
+- HTTP Controllers
+- WebSocket support
+- WAMP protocol integration
+- Command-line interface (`@elysiumjs/styx`), with support for custom commands
+- Event system
+- Caching (memory and Redis)
+- PostgreSQL database support with Drizzle ORM
+- Model classes and repositories for database interactions
+- Multi-tenancy support enabled
+- Swagger documentation
+
 ## Usage
 
 Create a controller class:
@@ -39,11 +57,11 @@ export class MainModule extends Module {
 		super();
 	}
 
-	public beforeRegister() {
+	public async beforeRegister(): Promise<void> {
 		console.log('Module is being registered');
 	}
 
-	public afterRegister() {
+	public async afterRegister(): Promise<void> {
 		console.log('Module registered successfully');
 	}
 }
@@ -82,20 +100,11 @@ Start the server:
 bun run index.ts serve
 ```
 
-## Features
+Or, if using `styx`, run:
 
-- Dependency Injection
-- HTTP Controllers
-- WebSocket support
-- WAMP protocol integration
-- Command-line interface (`styx`), with support for custom commands
-- Event system
-- Caching (memory and Redis)
-- Worker pool with queues for background jobs (using Bun's Worker API, Redis-based implementation planned)
-- PostgreSQL database support with Drizzle ORM
-- Model classes and repositories for database interactions
-- Multi-tenancy support enabled
-- Swagger documentation
+```bash
+bun styx serve
+```
 
 ## Documentation
 
@@ -109,4 +118,4 @@ Feel free to open issues for any bugs or questions you may have. Pull requests a
 
 ## License
 
-This project is licensed under the Apache License, Version 2.0. See the [LICENSE](../../LICENSE) file for more information.
+This project is licensed under the Apache License, Version 2.0. See the [LICENSE](https://github.com/workbud/elysium/blob/main/LICENSE) file for more information.

package/dist/app.d.ts

@@ -0,0 +1,180 @@
+import type { ElysiaSwaggerConfig } from '@elysiajs/swagger';
+import type { AnyElysia, ElysiaConfig, ErrorContext, TSchema } from 'elysia';
+import type { CommandClass } from './command';
+import type { DatabaseConnectionProps } from './database';
+import type { Route } from './http';
+import type { ModuleClass } from './module';
+import type { RedisConnectionProps } from './redis';
+import type { WampClientProps } from './wamp';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Elysia } from 'elysia';
+import { InteractsWithConsole } from './console';
+/**
+ * An application plugin, consisting of a function that returns an Elysia instance.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ElysiumPlugin = (app: Application) => Promise<AnyElysia>;
+/**
+ * Properties required when declaring an app using the `@app()` decorator.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type AppProps = {
+    [key: string]: any;
+    /**
+     * Enables or disables debug mode.
+     */
+    debug?: boolean;
+    /**
+     * The Elysia server configuration.
+     */
+    server?: ElysiaConfig<Route> & {
+        /**
+         * The port to listen on.
+         */
+        port?: number;
+    };
+    /**
+     * The wamp client configuration for the app.
+     */
+    wamp?: {
+        /**
+         * The default connection name.
+         */
+        default: string;
+        /**
+         * The list of connections.
+         */
+        connections: Record<string, WampClientProps>;
+    };
+    /**
+     * The list of modules provided the app.
+     */
+    modules?: ModuleClass[];
+    /**
+     * The list of CLI commands provided the app.
+     */
+    commands?: CommandClass[];
+    /**
+     * The database configuration for the app.
+     */
+    database?: {
+        /**
+         * The default connection name.
+         */
+        default: string;
+        /**
+         * The list of connections.
+         */
+        connections: Record<string, DatabaseConnectionProps>;
+    };
+    /**
+     * The redis configuration for the app.
+     */
+    redis?: {
+        /**
+         * The default connection name.
+         */
+        default: string;
+        /**
+         * The list of connections.
+         */
+        connections: Record<string, RedisConnectionProps>;
+    };
+    /**
+     * Swagger documentation configuration.
+     *
+     * Set it to `false` to disable Swagger documentation.
+     */
+    swagger?: ElysiaSwaggerConfig<Route> | false;
+    /**
+     * The validation schema for the application environment.
+     */
+    env?: TSchema;
+    /**
+     * The list of plugins to load.
+     */
+    plugins?: ElysiumPlugin[];
+};
+/**
+ * Type for the application context.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:tx', unknown>>;
+/**
+ * Base class for the application main entry.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare abstract class Application extends InteractsWithConsole {
+    #private;
+    private readonly _appContextStorage;
+    /**
+     * Gets the running application instance.
+     */
+    static get instance(): Application;
+    /**
+     * Gets the application context shared between asynchronous operations.
+     */
+    static get context(): AppContext;
+    /**
+     * Marks a class as the application main entry.
+     * @param props The decorator options.
+     */
+    static register(props?: AppProps): ClassDecorator;
+    /**
+     * Creates a new instance of the application.
+     */
+    constructor();
+    /**
+     * Gets the Elysia instance.
+     */
+    get elysia(): Elysia<Route>;
+    /**
+     * Gets the debug mode flag.
+     */
+    get isDebug(): boolean;
+    /**
+     * Sets the debug mode flag.
+     * @param debug The debug mode flag.
+     */
+    set isDebug(debug: boolean);
+    /**
+     * Hook that is executed when an error occurs.
+     * @param _error The error context.
+     * @returns Whether to continue the error propagation.
+     */
+    protected onError(_error: ErrorContext): Promise<boolean>;
+    /**
+     * Hook that is executed when the application starts.
+     * @param _elysia The Elysia instance.
+     */
+    protected onStart(_elysia: Elysia<Route>): Promise<void>;
+    /**
+     * Hook that is executed when the application stops.
+     * @param _elysia The Elysia instance.
+     */
+    protected onStop(_elysia: Elysia<Route>): Promise<void>;
+    protected run(): Promise<void>;
+    /**
+     * Retrieves the configuration value for the given key.
+     * @param key The key to retrieve the configuration value for.
+     * @returns The configuration value for the given key, or `null` if not found.
+     */
+    getConfig<T>(key: keyof AppProps): T | null;
+    /**
+     * Executes a command.
+     * @param command The command to execute.
+     * @param argv The command line arguments.
+     */
+    private commandExec;
+    /**
+     * Starts the server on the specified port.
+     */
+    private commandServe;
+    /**
+     * Describes the CLI and available commands.
+     */
+    private commandDescribe;
+    private commandList;
+    private commandDescription;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/cache.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Interface for a cache storage.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface CacheInterface {
+    /**
+     * Retrieves the cached data for a given key.
+     * @typeParam T The type of the cached data.
+     *
+     * @param key The key of the cached data.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Retrieves the cached data for a given list of keys.
+     * @typeParam T The type of the cached data.
+     *
+     * @param keys The list of cached data keys.
+     */
+    mget<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Gets the TTL of the cached data with the given key.
+     * @param key The key of the cached data.
+     * @returns The TTL of the cached data, or `null` if the data does not exist.
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * Caches data under the given key and an optional TTL.
+     * @typeParam T The type of the data to cache.
+     *
+     * @param key The key of the cached data.
+     * @param data The data to cache.
+     * @param ttl The optional TTL of the cached data. If not defined, the data is cached forever.
+     * @returns The cached data.
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<T>;
+    /**
+     * Caches data under the given list of keys and an optional TTL.
+     * @typeParam T The type of the data to cache.
+     *
+     * @param data The list of data to cache.
+     * @returns The list of cached data.
+     */
+    mset<T>(data: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+    }>): Promise<Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+    }>>;
+    /**
+     * Deletes the cached data with the given key.
+     * @typeParam T The type of the data to cache.
+     *
+     * @param key The key of the cached data.
+     * @returns `true` if the data was deleted, `false` otherwise.
+     */
+    del(key: string): Promise<boolean>;
+    /**
+     * Deletes the cached data with the given list of keys.
+     * @typeParam T The type of the data to cache.
+     *
+     * @param keys The list of cached data keys.
+     * @returns `true` if the data was deleted, `false` otherwise.
+     */
+    mdel(keys: string[]): Promise<boolean>;
+    /**
+     * Deletes all cached data.
+     * @returns `true` if the data was deleted, `false` otherwise.
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Creates a sub-cache with the given tags.
+     * @param tags The list of tags for the sub-cache.
+     */
+    tags(...tags: string[]): Omit<CacheInterface, 'tags'>;
+}
+export declare abstract class Cache {
+    #private;
+    /**
+     * A weak cache storage for simple non-intrusive caching of data.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static readonly weak: {
+        /**
+         * INTERNAL USAGE ONLY.
+         * @private
+         */
+        map: WeakMap<object, unknown>;
+        /**
+         * Gets the cached data for a given context.
+         * @param ctx The cache context.
+         * @returns The cached data.
+         */
+        get<T extends object>(ctx: object): T;
+        /**
+         * Deletes the cached data for a given context.
+         * @param ctx The cache context.
+         */
+        del(ctx: object): void;
+    };
+    /**
+     * Redis-based cache storage.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static get redis(): CacheInterface;
+    /**
+     * Memory-based cache storage.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static get memory(): CacheInterface;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/command.d.ts

@@ -0,0 +1,273 @@
+import type { Class } from 'type-fest';
+import { InteractsWithConsole } from './console';
+/**
+ * Supported command argument types.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare enum CommandArgumentType {
+    /**
+     * String argument.
+     */
+    STRING = "string",
+    /**
+     * Number argument.
+     */
+    NUMBER = "number",
+    /**
+     * Boolean argument.
+     */
+    BOOLEAN = "boolean",
+    /**
+     * Enum argument.
+     */
+    ENUM = "enum",
+    /**
+     * Array argument.
+     */
+    ARRAY = "array"
+}
+/**
+ * Properties required when declaring a command argument.
+ * @author Axel Nana <axel.nana@workbud.com>
+ *
+ * These properties are used to define command arguments using the `@arg()` decorator. The
+ * values of these properties are used to generate the help message for the command.
+ */
+export type CommandArgumentProps = {
+    /**
+     * The name of the argument.
+     */
+    name: string;
+    /**
+     * The description of the argument.
+     */
+    description?: string;
+    /**
+     * Whether the argument is required.
+     */
+    required?: boolean;
+    /**
+     * The default value for the argument.
+     */
+    default?: any;
+    /**
+     * The type of the argument.
+     */
+    type?: CommandArgumentType;
+    /**
+     * The list of allowed values for the argument.
+     */
+    enum?: string[];
+    /**
+     * The type of elements in the array.
+     */
+    arrayType?: CommandArgumentType;
+};
+/**
+ * Metadata for storing command arguments.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+type CommandArgumentMetadata = CommandArgumentProps & {
+    /**
+     * The name of the class property that the argument is associated with.
+     */
+    propertyKey: string;
+};
+/**
+ * Type for a command class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type CommandClass = Class<Command> & {
+    /**
+     * The name of the command.
+     */
+    readonly command: string;
+    /**
+     * The description of the command.
+     */
+    readonly description: string;
+};
+/**
+ * Base class for commands.
+ *
+ * Commands are classes that can be executed through the CLI. They can have arguments
+ * that can be passed to them using the `--` syntax.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare abstract class Command extends InteractsWithConsole {
+    /**
+     * The name of the command.
+     *
+     * This is used to identify the command in the CLI when using the `exec` command.
+     */
+    static readonly command: string;
+    /**
+     * The description of the command.
+     *
+     * This is displayed when displaying help messages for the command.
+     */
+    static readonly description: string;
+    /**
+     * Decorator for registering a command argument.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the argument.
+     * @param props Additional options for the argument.
+     */
+    static arg(props?: Partial<CommandArgumentProps>): PropertyDecorator;
+    /**
+     * The command entry point. This method is called when the command is executed using the CLI.
+     */
+    abstract run(): Promise<void>;
+    /**
+     * Initialize the command before it is executed. This method is called before the `run()` method.
+     * and is used to validate the arguments and initialize the command.
+     * @param argv The command line arguments.
+     * @returns Whether the command was initialized successfully.
+     */
+    init(...argv: string[]): Promise<boolean>;
+    /**
+     * Get all registered arguments for this command.
+     * @returns The list of registered arguments.
+     */
+    protected getArguments(): CommandArgumentMetadata[];
+    /**
+     * Generate help text for the command.
+     * @returns Formatted help text.
+     */
+    help(): Promise<string>;
+    /**
+     * Validate provided arguments against registered arguments.
+     * @param args Arguments to validate.
+     * @returns Object with validation result and missing required args if any.
+     */
+    protected validateArgs(args: Record<string, any>): {
+        valid: boolean;
+        missing: string[];
+    };
+    /**
+     * Process command line arguments and apply default values.
+     * @param argv The command line arguments.
+     * @returns Processed arguments with defaults applied.
+     */
+    protected processArgs(argv: string[]): Record<string, any>;
+    /**
+     * Start a progress bar in the console.
+     * @param total The total number of items to process.
+     * @param title Optional title for the progress bar.
+     */
+    protected progress(total: number, title?: string): CommandProgressBar;
+    /**
+     * Start a spinner in the console.
+     * @param title Optional title for the spinner.
+     * @param frames Optional custom frames for the spinner animation.
+     * @param frameDelay Optional delay between frames in milliseconds.
+     */
+    protected spinner(title?: string, frames?: string[], frameDelay?: number): CommandSpinner;
+    /**
+     * Infer the type of an argument based on its default value.
+     * @param defaultValue The default value.
+     * @returns The inferred argument type.
+     */
+    private inferType;
+}
+/**
+ * A class for managing and displaying a progress bar in the console.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+declare class CommandProgressBar extends InteractsWithConsole {
+    #private;
+    /**
+     * Create a new progress bar instance.
+     * @param total The total number of items to process.
+     * @param title Optional title for the progress bar.
+     */
+    constructor(total?: number, title?: string);
+    /**
+     * Update the progress bar with a new value.
+     * @param increment The number of items to increment by (default: 1).
+     * @param newTitle Optional new title for the progress bar.
+     */
+    update(increment?: number, newTitle?: string): void;
+    /**
+     * Complete the progress bar and reset its state.
+     * @param message Optional completion message to display.
+     */
+    complete(message?: string): void;
+    /**
+     * Pause the progress bar temporarily to display a message.
+     * @param message The message to display.
+     */
+    pause(message: string): void;
+    /**
+     * Check if the progress bar is currently active.
+     * @returns True if the progress bar is active, false otherwise.
+     */
+    isActive(): boolean;
+    /**
+     * Get the current progress value.
+     * @returns The current progress value.
+     */
+    getCurrent(): number;
+    /**
+     * Get the total progress value.
+     * @returns The total progress value.
+     */
+    getTotal(): number;
+    /**
+     * Get the current progress percentage.
+     * @returns The current progress percentage (0-100).
+     */
+    getPercentage(): number;
+}
+/**
+ * A class for displaying a spinner in the console for indeterminate operations.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class CommandSpinner extends InteractsWithConsole {
+    #private;
+    /**
+     * Create a new spinner instance.
+     * @param title Optional title for the spinner.
+     * @param frames Optional custom frames for the spinner animation.
+     * @param frameDelay Optional delay between frames in milliseconds.
+     */
+    constructor(title?: string, frames?: string[], frameDelay?: number);
+    /**
+     * Update the spinner with a new title.
+     * @param newTitle New title for the spinner.
+     */
+    update(newTitle: string): void;
+    /**
+     * Complete the spinner and reset its state.
+     * @param message Optional completion message to display.
+     * @param success Whether the operation was successful (affects the symbol shown).
+     */
+    complete(message?: string, success?: boolean): void;
+    /**
+     * Fail the spinner and reset its state.
+     * @param message Optional failure message to display.
+     */
+    fail(message?: string): void;
+    /**
+     * Pause the spinner temporarily to display a message.
+     * @param message The message to display.
+     */
+    pause(message: string): void;
+    /**
+     * Check if the spinner is currently active.
+     * @returns True if the spinner is active, false otherwise.
+     */
+    isActive(): boolean;
+    /**
+     * Get the elapsed time since the spinner started.
+     * @returns The elapsed time in seconds.
+     */
+    getElapsedTime(): number;
+    /**
+     * Render the current frame of the spinner.
+     */
+    private render;
+}
+export {};
+//# sourceMappingURL=command.d.ts.map