@elysiumjs/core 0.4.2 → 0.5.0

package/dist/console.d.ts

@@ -0,0 +1,167 @@
+import type { WriteStream } from 'node:tty';
+/**
+ * ANSI color codes and styles for console output.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare enum ConsoleFormat {
+    BLACK = 0,
+    RED = 1,
+    GREEN = 2,
+    YELLOW = 3,
+    BLUE = 4,
+    MAGENTA = 5,
+    CYAN = 6,
+    WHITE = 7,
+    GRAY = 8,
+    BOLD = 9,
+    UNDERLINE = 10,
+    ITALIC = 11,
+    INVERSE = 12
+}
+/**
+ * A utility class for console IO with various formatting options.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class InteractsWithConsole {
+    protected static readonly SPACE_WIDTH = 60;
+    /**
+     * Write a message to the console.
+     * @param message The message to write.
+     * @param newLine Whether to add a newline at the end (default: `true`).
+     * @param out The output stream to write to (default: `process.stdout`).
+     */
+    write(message: string, newLine?: boolean, out?: WriteStream): void;
+    /**
+     * Write a new line to the console.
+     */
+    newLine(): void;
+    /**
+     * Write an info message to the console (blue text).
+     * @param message The message to write.
+     */
+    info(message: string): void;
+    /**
+     * Write a success message to the console (green text).
+     * @param message The message to write.
+     */
+    success(message: string): void;
+    /**
+     * Write a warning message to the console (yellow text).
+     * @param message The message to write.
+     */
+    warning(message: string): void;
+    /**
+     * Write an error message to the console (red text).
+     * @param message The message to write.
+     */
+    error(message: string): void;
+    /**
+     * Write a debug message to the console (gray text).
+     * Only shown if the DEBUG environment variable is set.
+     * @param message The message to write.
+     */
+    debug(message: string): void;
+    /**
+     * Display a JavaScript error in the console with its message, stack trace,
+     * and any additional relevant information.
+     * @param error The error to display.
+     * @param title Optional title to display before the error message (default: '').
+     */
+    trace(error: Error & Record<string, any>, title?: string): void;
+    /**
+     * Write a title to the console (bold text with underline).
+     * @param title The title to write.
+     */
+    title(title: string): void;
+    /**
+     * Write a section header to the console (bold text).
+     * @param header The section header to write.
+     */
+    section(header: string): void;
+    /**
+     * Create a table from an array of objects and write it to the console.
+     * @param data The array of objects to display.
+     * @param columns Optional column configuration.
+     */
+    table<T extends Record<string, any>>(data: T[], columns?: {
+        [K in keyof T]?: {
+            header?: string;
+            width?: number;
+            format?: (value: T[K]) => string;
+        };
+    }): void;
+    /**
+     * Format text with multiple ANSI styles.
+     * @param text The text to format.
+     * @param styles The styles to apply.
+     * @returns The formatted text.
+     */
+    format(text: string, ...styles: ConsoleFormat[]): string;
+    /**
+     * Format text as bold.
+     * @param text The text to format.
+     * @returns The formatted text.
+     */
+    bold(text: string): string;
+    /**
+     * Format text as italic.
+     * @param text The text to format.
+     * @returns The formatted text.
+     */
+    italic(text: string): string;
+    /**
+     * Format text as underline.
+     * @param text The text to format.
+     * @returns The formatted text.
+     */
+    underline(text: string): string;
+    /**
+     * Clear the console screen.
+     */
+    clear(): void;
+    /**
+     * Move the cursor to a specific position.
+     * @param x The x coordinate (column).
+     * @param y The y coordinate (row).
+     */
+    moveCursor(x: number, y: number): void;
+    /**
+     * Clear the current line in the console.
+     */
+    clearLine(): void;
+    /**
+     * Prompt the user for input.
+     * @param question The question to ask.
+     * @param defaultValue Optional default value.
+     * @returns The user's input.
+     */
+    protected prompt(question: string, defaultValue?: string): Promise<string>;
+    /**
+     * Prompt the user for a password (input is hidden).
+     * @param question The question to ask.
+     * @returns The user's password.
+     */
+    protected promptPassword(question: string): Promise<string>;
+    /**
+     * Prompt the user for confirmation (yes/no).
+     * @param question The question to ask.
+     * @param defaultValue Optional default value (true for yes, false for no).
+     * @returns True if the user confirmed, false otherwise.
+     */
+    protected confirm(question: string, defaultValue?: boolean): Promise<boolean>;
+    /**
+     * Prompt the user to select from a list of options.
+     * @param question The question to ask.
+     * @param options The options to choose from.
+     * @param defaultIndex Optional default option index.
+     * @returns The selected option.
+     */
+    protected select<T extends string>(question: string, options: T[], defaultIndex?: number): Promise<T>;
+    /**
+     * Format a time value in seconds to a human-readable string.
+     * @param seconds The time value in seconds.
+     * @returns A formatted time string.
+     */
+    protected formatTime(seconds: number): string;
+}
+//# sourceMappingURL=console.d.ts.map

package/dist/database.d.ts

@@ -0,0 +1,113 @@
+import type { DrizzleConfig } from 'drizzle-orm';
+import type { BunSQLDatabase } from 'drizzle-orm/bun-sql';
+import type { CacheConfig } from 'drizzle-orm/cache/core/types';
+import { Table } from 'drizzle-orm';
+import { Cache as DrizzleCache } from 'drizzle-orm/cache/core';
+/**
+ * Properties used to create a new database connection.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type DatabaseConnectionProps<TSchema extends Record<string, unknown> = Record<string, never>> = Omit<DrizzleConfig<TSchema>, 'cache'> & ({
+    connection: string | ({
+        url?: string;
+    } & Bun.SQLOptions);
+} | {
+    client: Bun.SQL;
+}) & {
+    /**
+     * Configures caching behavior for the database connection.
+     * Set it to `true` to enable caching with default configurations.
+     */
+    cache?: true | {
+        /**
+         * Whether to enable caching.
+         */
+        enabled?: boolean;
+        /**
+         * The default TTL for cached data, in seconds.
+         * @default 1
+         */
+        ttl?: number;
+        /**
+         * The caching strategy.
+         * Set it to `all` to cache all queries automatically.
+         * Set it to `explicit` to cache queries manually.
+         * @default 'explicit'
+         */
+        strategy?: 'explicit' | 'all';
+        /**
+         * The storage engine to use.
+         * @default 'redis'
+         */
+        storage?: 'redis' | 'memory';
+    };
+};
+/**
+ * A database connection.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type DatabaseConnection = BunSQLDatabase<Record<string, never>> & {
+    $client: Bun.SQL;
+};
+/**
+ * Database cache implementation for Drizzle.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DatabaseCache extends DrizzleCache {
+    #private;
+    private readonly cacheStrategy;
+    private readonly globalTtl;
+    private usedTablesPerKey;
+    constructor(cacheStrategy?: 'explicit' | 'all', globalTtl?: number, storageEngine?: 'redis' | 'memory');
+    strategy(): 'explicit' | 'all';
+    get(key: string): Promise<any[] | undefined>;
+    put(key: string, response: any, tables: string[], _isTag: boolean, config?: CacheConfig): Promise<void>;
+    onMutate(params: {
+        tags: string | string[];
+        tables: string | string[] | Table<any> | Table<any>[];
+    }): Promise<void>;
+}
+export declare namespace Database {
+    /**
+     * Retrieves the connection with the given name.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The connection name.
+     * @returns The connection with the given name.
+     */
+    const getConnection: (name: string) => DatabaseConnection;
+    /**
+     * Creates and registers a new connection.
+     * @author Axel Nana <axel.nana@workbud.com>
+     *
+     * This will make the registered connection available for dependency injection with
+     * the key `db.connection.{name}`, where `{name}` is replaced with the given name.
+     *
+     * @param name The connection name.
+     * @param config The connection properties.
+     * @returns The newly created and registered connection.
+     */
+    const registerConnection: (name: string, config: DatabaseConnectionProps) => BunSQLDatabase<Record<string, never>> & {
+        $client: Bun.SQL;
+    };
+    /**
+     * Checks if a connection with the given name exists.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the connection to check.
+     * @returns `true` if the connection exists, `false` otherwise.
+     */
+    const connectionExists: (name: string) => boolean;
+    /**
+     * Retrieves the default connection.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @returns The default connection.
+     */
+    const getDefaultConnection: () => DatabaseConnection;
+    /**
+     * Sets the default connection.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the connection to set as default.
+     * @returns The default connection.
+     */
+    const setDefaultConnection: (name: string) => DatabaseConnection;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/env.d.ts

@@ -0,0 +1,30 @@
+import type { AppEnv } from '@elysiumjs/core';
+/**
+ * Initializes the environment variables.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param vars The environment variables to initialize.
+ */
+export declare const initEnv: (vars: Record<string, unknown>) => void;
+export declare namespace Env {
+    /**
+     * Gets the value of an environment variable.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the environment variable.
+     * @param defaultValue The default value to return if the environment variable is not set.
+     * @returns The value of the environment variable.
+     */
+    const get: <TKey extends keyof AppEnv>(name: TKey, defaultValue?: AppEnv[TKey]) => AppEnv[TKey];
+    /**
+     * Checks if an environment variable exists.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the environment variable.
+     * @returns `true` if the environment variable exists, `false` otherwise.
+     */
+    const exists: <TKey extends keyof AppEnv>(name: TKey) => boolean;
+    /**
+     * Clears the environment variables.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const clear: () => void;
+}
+//# sourceMappingURL=env.d.ts.map

package/dist/event.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Stores the event data with the source.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type EventData<TData, TSource = null> = {
+    /**
+     * The emitted data.
+     */
+    data: TData;
+    /**
+     * The source of the event.
+     */
+    source: TSource | null;
+};
+/**
+ * Event handler function.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type EventHandler<TData, TSource = any> = (event: EventData<TData, TSource>) => void | Promise<void>;
+/**
+ * Properties required when declaring a method as an event listener.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ListenProps = {
+    /**
+     * The listener mode.
+     *
+     * Set it to `on` to listen for the event every time it is emitted.
+     * Set it to `once` to listen for the event only once.
+     */
+    mode: 'on' | 'once';
+    /**
+     * The event name.
+     */
+    event: string;
+    /**
+     * Whether to prepend the listener to the event. Defaults to `false`.
+     * @default false
+     */
+    prepend?: boolean;
+};
+export declare namespace Event {
+    /**
+     * Emits an event with the provided data and source.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param event The event name.
+     * @param data The emitted data.
+     * @param source The source of the event. Defaults to `null`.
+     */
+    const emit: <TData, TSource = any>(event: string, data: TData, source?: TSource | null) => void;
+    /**
+     * Marks a method as an event listener.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param options The decorator options.
+     */
+    function on(options: Omit<ListenProps, 'mode'>): MethodDecorator;
+    /**
+     * Registers an event listener for the specified event.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param event The event name.
+     * @param handler The event handler function.
+     */
+    function on<TData, TSource = any>(event: string, handler: EventHandler<TData, TSource>): void;
+    /**
+     * Marks a method as an event listener that listens for the event only once.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param options The decorator options.
+     */
+    function once(options: Omit<ListenProps, 'mode'>): MethodDecorator;
+    /**
+     * Registers an event listener for the specified event that listens for the event only once.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param event The event name.
+     * @param handler The event handler function.
+     */
+    function once<TData, TSource = any>(event: string, handler: EventHandler<TData, TSource>): void;
+    /**
+     * Removes all event listeners for the specified event.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param event The event name.
+     */
+    const off: (event: string) => void;
+    /**
+     * Removes all event listeners.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const clear: () => void;
+    /**
+     * Marks a method as an event listener.
+     * @param options The decorator options.
+     */
+    const listen: (options: ListenProps) => MethodDecorator;
+}
+//# sourceMappingURL=event.d.ts.map

package/dist/http.d.ts

@@ -0,0 +1,242 @@
+import type { AppHttpContext } from '@elysiumjs/core';
+import type { Context as ElysiaContext, Handler, HTTPMethod, TSchema } from 'elysia';
+import type { Class, MergeDeep } from 'type-fest';
+import type { Module } from './module';
+import { Elysia } from 'elysia';
+/**
+ * A route is a string that starts with a forward slash.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type Route = `/${string}`;
+/**
+ * A class for validating data against a schema.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ValidatorClass<T extends TSchema = TSchema> = {
+    /**
+     * The validation schema. This schema is automatically checked against the input data during
+     * the validation stage of the HTTP request.
+     */
+    readonly schema: T;
+    /**
+     * Whether the request should be authorized before validation. If the request is not authorized,
+     * the validation will be skipped.
+     */
+    authorize(ctx: Context<T['static']>): Promise<boolean>;
+    /**
+     * Processes custom validation logic. This method is called after the validation schema is checked
+     * against the input data. So it's safe to assume that the schema is valid.
+     * @param data The input data to validate.
+     * @returns Whether the input data is valid.
+     */
+    validate(ctx: Context<T['static']>): Promise<boolean>;
+};
+/**
+ * Metadata for the HTTP context.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type Singleton<TController = unknown, TModule extends Module = Module> = MergeDeep<AppHttpContext, {
+    decorator: {
+        [key: string]: unknown;
+        /**
+         * The controller instance.
+         */
+        controller: () => TController;
+        /**
+         * The module instance.
+         */
+        module: TModule;
+    };
+    resolve: {
+        /**
+         * The tenant ID.
+         */
+        readonly tenant: string;
+    };
+}>;
+/**
+ * The Elysia context with the controller injected.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type Context<TBody = unknown, TController = unknown, TModule extends Module = Module> = ElysiaContext<{
+    body: TBody;
+}, Singleton<TController, TModule>>;
+export type ElysiaApp = Elysia<Route, Singleton>;
+/**
+ * The scope of an HTTP controller.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare enum HttpControllerScope {
+    /**
+     * The controller is instantiated once in the server and used for every request.
+     */
+    SERVER = 0,
+    /**
+     * A new instance of the controller is created for each request.
+     */
+    REQUEST = 1
+}
+/**
+ * Properties required when declaring an HTTP controller using the `@http()` decorator.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type HttpControllerProps = {
+    /**
+     * The path of the HTTP route.
+     */
+    path: Route;
+    /**
+     * The scope of the HTTP controller.
+     * @default HttpControllerScope.SERVER
+     */
+    scope?: HttpControllerScope;
+    /**
+     * The list of tags for the controller.
+     * Used in Swagger documentation.
+     */
+    tags?: Array<string>;
+    /**
+     * Whether to create a database transaction for all the queries executed
+     * for all the request handlers in this controller.
+     */
+    transactional?: boolean;
+};
+/**
+ * Properties required when declaring an HTTP request handler.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type RequestHandlerDecoratorProps = {
+    /**
+     * The HTTP method of the handler.
+     */
+    method?: HTTPMethod;
+    /**
+     * The path of the HTTP route.
+     */
+    path?: Route;
+    /**
+     * The schema of the response body.
+     */
+    response?: TSchema | Record<number, TSchema>;
+    /**
+     * The operation ID for the handler.
+     * Used in Swagger documentation.
+     */
+    operationId?: string;
+    /**
+     * The description for the handler.
+     * Used in Swagger documentation.
+     */
+    description?: string;
+    /**
+     * Whether to create a database transaction for all the queries executed
+     * for this request handler.
+     */
+    transactional?: boolean;
+};
+export declare namespace Http {
+    /**
+     * Marks a class as an HTTP controller.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The decorator options.
+     */
+    const controller: (props?: HttpControllerProps) => (target: Class<any>) => void;
+    /**
+     * Marks a method as an HTTP "server-sent events" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const sse: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "get" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const get: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "post" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const post: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "put" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const put: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "delete" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const del: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "patch" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const patch: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "head" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const head: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "options" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const options: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP "trace" request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const trace: (props?: RequestHandlerDecoratorProps) => MethodDecorator;
+    /**
+     * Marks a method as an HTTP request handler with a custom method.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The request handler properties.
+     */
+    const custom: ({ path, ...rest }: RequestHandlerDecoratorProps & {
+        method: HTTPMethod;
+    }) => MethodDecorator;
+    /**
+     * Marks a method as the callback for the request handler.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const onRequest: () => MethodDecorator;
+    /**
+     * Resolves the context for the current request in the annotated parameter.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const context: () => ParameterDecorator;
+    /**
+     * Resolves the value of a URL parameter in the annotated parameter.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param slug The slug of the parameter.
+     * @param schema The schema of the parameter.
+     */
+    const param: (slug: string, schema?: TSchema) => ParameterDecorator;
+    /**
+     * Resolves the value of a query parameter in the annotated parameter.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param schema The schema of the query parameter.
+     */
+    const query: (schema?: TSchema) => ParameterDecorator;
+    /**
+     * Resolves the value of the request body in the annotated parameter.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param schema The schema of the request body.
+     */
+    const body: (schema?: TSchema | ValidatorClass) => ParameterDecorator;
+    /**
+     * Executes a custom function to resolve the value of the parameter from the context.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param handler The custom function that will return the value for the parameter.
+     */
+    const decorate: (handler: Handler) => (() => ParameterDecorator);
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import './macros';
+export { type Elysia, type TSchema, type Static, t } from 'elysia';
+export { type AppContext, type ElysiumPlugin, Application } from './app';
+export { Cache } from './cache';
+export { type CommandArgumentProps, type CommandClass, Command, CommandArgumentType } from './command';
+export { ConsoleFormat, InteractsWithConsole } from './console';
+export { Database } from './database';
+export { Env } from './env';
+export { type EventData, type EventHandler, Event } from './event';
+export { type Context, type Route, HttpControllerScope, Http } from './http';
+export { Job } from './job';
+export { Middleware } from './middleware';
+export { type ModelClass, Model, Tenancy } from './model';
+export { type ModuleClass, Module } from './module';
+export { Redis } from './redis';
+export { type IdType, type RepositoryInterface, type RepositoryClass, Repository } from './repository';
+export { ServiceScope, Service } from './service';
+export { type WampRegistrationOptions, type WampSubscriptionOptions, type WampProps, type WampRegistrationHandlerArgs, type WampSubscriptionHandlerArgs, type WampRegistrationHandler, type WampSubscriptionHandler, Wamp } from './wamp';
+export { type WS, type WSError, Websocket } from './websocket';
+export { type QueueOptions, WorkerPool, Worker } from './worker';
+//# sourceMappingURL=index.d.ts.map