@elysiumjs/core 0.7.0 → 0.8.0

package/dist/wamp.d.ts

@@ -1,4 +1,6 @@
-import type { Class, Primitive } from 'type-fest';
+import type { Class } from 'type-fest';
+import { Elysia } from 'elysia';
+import Wampy from 'wampy';
 /**
  * Options used to register a WAMP RPC for invocation.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -69,11 +71,11 @@ export type WampClientProps = {
      * @param method The authentication method.
      * @param extra Authentication metadata.
      */
-    onChallenge?(method: string, extra: any): string | null;
+    onChallenge?(method: string, extra: Record<string, unknown>): string | Promise<string>;
     /**
-     * Callback for handling the WAMP connection open event.
+     * Called once the first connection is established; not on wampy reconnects.
      */
-    onOpen?(): void;
+    onOpen?(): void | Promise<void>;
     /**
      * Callback for handling the WAMP connection close event.
      */
@@ -81,7 +83,7 @@ export type WampClientProps = {
     /**
      * Callback for handling the WAMP connection error event.
      */
-    onError?(): void;
+    onError?(error: Error): void;
     /**
      * Callback for handling the WAMP connection reconnect event.
      */
@@ -89,77 +91,13 @@ export type WampClientProps = {
     /**
      * Callback for handling the WAMP connection reconnect success event.
      */
-    onReconnectSuccess?(): void;
-};
-export type WampClient = {
-    /**
-     * Disconnects from WAMP server. Clears all queues, subscriptions and calls.
-     * @author Axel Nana <axel.nana@workbud.com>
-     */
-    disconnect(): Promise<void>;
-    subscribe(topic: string, handler: WampSubscriptionHandler, options?: WampSubscriptionOptions): Promise<{
-        topic: string;
-        requestId: string;
-        subscriptionId: string;
-        subscriptionKey: string;
-    }>;
-    unsubscribe(subscriptionIdOrKey: string, handler?: WampSubscriptionHandler): Promise<{
-        topic: string;
-        requestId: string;
-    }>;
-    publish(topic: string, params?: Primitive | Array<any> | Record<string, Primitive | Array<any>> | {
-        argsList: Array<any>;
-        argsDict: Record<string, any>;
-    }, options?: {
-        exclude?: number | number[];
-        exclude_authid?: string | string[];
-        exclude_authrole?: string | string[];
-        eligible?: number | number[];
-        eligible_authid?: string | string[];
-        eligible_authrole?: string | string[];
-        exclude_me?: boolean;
-        disclose_me?: boolean;
-        ppt_scheme?: string;
-        ppt_serializer?: string;
-        ppt_cipher?: string;
-        ppt_keyid?: string;
-    }): Promise<{
-        topic: string;
-        requestId: string;
-        publicationId: string;
-    }>;
-    call(procedure: string, params?: Primitive | Array<any> | Record<string, Primitive | Array<any>> | {
-        argsList: Array<any>;
-        argsDict: Record<string, any>;
-    }, options?: {
-        disclose_me?: boolean;
-        progress_callback?(args: {
-            argsList: Array<any>;
-            argsDict: Record<string, any>;
-        }): void;
-        timeout?: number;
-        ppt_scheme?: string;
-        ppt_serializer?: string;
-        ppt_cipher?: string;
-        ppt_keyid?: string;
-    }): Promise<{
-        details: Record<string, any>;
-        argsList?: Array<any>;
-        argsDict?: Record<string, any>;
-    }>;
-    cancel(requestId: string, options?: {
-        mode?: 'kill' | 'killnowait' | 'skip';
-    }): true;
-    register(topic: string, handler: WampRegistrationHandler, options?: WampRegistrationOptions): Promise<{
-        topic: string;
-        requestId: string;
-        registrationId: string;
-    }>;
-    unregister(registrationId: string): Promise<{
-        topic: string;
-        requestId: string;
-    }>;
+    onReconnectSuccess?(details: Record<string, unknown>): void;
 };
+/**
+ * The WAMP client, as provided by Wampy.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampClient = Wampy;
 /**
  * Data sent to a WAMP RPC.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -210,25 +148,20 @@ export type WampRegistrationHandler = <T = any>(data: WampRegistrationHandlerArg
 export type WampSubscriptionHandler = <T = any>(data: WampSubscriptionHandlerArgs) => T;
 export declare namespace Wamp {
     /**
-     * Retrieves the client for a WAMP connection.
+     * Creates a service name for a WAMP connection.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param name The name of the connection.
-     * @returns The Wampy client for the connection with the given name.
+     * @returns A service name for the connection.
      */
-    const getConnection: (name: string) => WampClient;
+    const getConnectionName: (name: string) => string;
     /**
-     * Creates and registers a new WAMP client.
-     *
-     * This will make the registered connection available for dependency injection with
-     * the key `wamp.connection.{name}`, where `{name}` is replaced with the given name.
-     *
+     * Retrieves the client for a WAMP connection declared by the {@link WampModule}.
      * @author Axel Nana <axel.nana@workbud.com>
-     *
      * @param name The name of the connection.
-     * @param config The configuration for the WAMP client.
-     * @returns The newly created and configured WAMP client for the given connection.
+     * @returns The Wampy client for the connection with the given name.
+     * @throws {ServiceNotFoundError} If no connection with that name is declared.
      */
-    const registerConnection: (name: string, config: WampClientProps) => WampClient;
+    const getConnection: (name?: string) => Wampy;
     /**
      * Checks if a WAMP connection with the given name exists.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -241,14 +174,12 @@ export declare namespace Wamp {
      * @author Axel Nana <axel.nana@workbud.com>
      * @returns The default WAMP connection.
      */
-    const getDefaultConnection: () => WampClient;
+    const getDefaultConnection: () => Wampy;
     /**
-     * Sets the default WAMP connection.
+     * Creates a WAMP client and starts connecting it, retrying on failure.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param name The name of the connection to set as default.
-     * @returns The default WAMP connection.
      */
-    const setDefaultConnection: (name: string) => WampClient;
+    const createClient: (name: string, config: WampClientProps) => WampClient;
     /**
      * Marks a class as a WAMP controller.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -270,3 +201,52 @@ export declare namespace Wamp {
      */
     const subscribe: (topic: string, options?: WampSubscriptionOptions) => MethodDecorator;
 }
+/**
+ * Configuration of the {@link WampModule}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampModuleConfig = {
+    /** The name of the connection that `default` resolves to. */
+    default: string;
+    /** The connections to declare, by name. */
+    connections: Record<string, WampClientProps>;
+};
+declare const WampModule_base: (abstract new () => {
+    get config(): WampModuleConfig;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
+    onServe(_app: Elysia<any>): Promise<void> | void;
+}) & {
+    get config(): string;
+    with(config: Partial<WampModuleConfig> | (() => Partial<WampModuleConfig> | Promise<Partial<WampModuleConfig>>)): import("./module").ConfiguredModule<WampModuleConfig>;
+    resolveConfig(input?: Partial<WampModuleConfig>): WampModuleConfig;
+    register<TConfig = any>(props?: import("./module").ModuleProps<TConfig>): (target: import("./module").ModuleClass) => void;
+    configurable<TConfig extends object>(options?: {
+        defaults?: Partial<TConfig>;
+        required?: (keyof TConfig)[];
+    }): (abstract new () => {
+        get config(): TConfig;
+        onInit(): Promise<void> | void;
+        onDestroy(): Promise<void> | void;
+        onServe(_app: Elysia<any>): Promise<void> | void;
+    }) & {
+        get config(): string;
+        with(config: Partial<TConfig> | (() => Partial<TConfig> | Promise<Partial<TConfig>>)): import("./module").ConfiguredModule<TConfig>;
+        resolveConfig(input?: Partial<TConfig>): TConfig;
+        register<TConfig_1 = any>(props?: import("./module").ModuleProps<TConfig_1>): (target: import("./module").ModuleClass) => void;
+        configurable<TConfig extends object>(options?: {
+            defaults?: Partial<TConfig>;
+            required?: (keyof TConfig)[];
+        }): /*elided*/ any;
+    };
+};
+/**
+ * Declares WAMP connections as global services named `wamp.connection.{name}`, plus
+ * `wamp.connection.default` aliasing the configured default. Clients are created on first use.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class WampModule extends WampModule_base {
+    /** Disconnects the clients that were created. */
+    onDestroy(): Promise<void>;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elysiumjs/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "description": "A super-charged web framework for Bun, built on top of ElysiaJS.",
   "private": false,
@@ -13,7 +13,7 @@
   "scripts": {
     "format": "prettier --write \"./src/**/*.ts\"",
     "clean": "rimraf dist",
-    "build:js": "bun build ./src/index.ts --outdir ./dist --target bun --packages external --root ./src --minify",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --target bun --packages external --root ./src --minify-syntax --minify-whitespace",
     "build:ts": "tsc",
     "build": "bun run clean && bun run build:js && bun run build:ts",
     "typecheck": "tsc --noEmit",
@@ -33,11 +33,10 @@
     "./src/index.ts"
   ],
   "dependencies": {
-    "@elysiajs/swagger": "^1.3.1",
-    "elysia": "^1.4.9",
+    "@elysiajs/openapi": "^1.4.16",
+    "elysia": "^1.4.30",
     "radash": "^12.1.1",
-    "reflect-metadata": "^0.2.2",
-    "wampy": "^7.2.0"
+    "wampy": "^8.0.2"
   },
   "trustedDependencies": [
     "es5-ext"

package/dist/job.d.ts

@@ -1,105 +0,0 @@
-import 'reflect-metadata';
-import type { Class } from 'type-fest';
-import { InteractsWithConsole } from './console';
-/**
- * Properties required when declaring a job using the `@job()` decorator.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export type JobProps = {
-    /**
-     * The name of the job.
-     */
-    name?: string;
-    /**
-     * The queue on which the job should be processed.
-     */
-    queue?: string;
-};
-/**
- * Base class for background jobs.
- *
- * Jobs are classes that can be executed in the background. They provide
- * an abstract execute method that serves as the entry point for the job.
- *
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export declare abstract class Job extends InteractsWithConsole {
-    #private;
-    /**
-     * Marks a class as a job.
-     * @author Axel Nana <axel.nana@workbud.com>
-     * @param options The decorator options.
-     */
-    static register(options?: JobProps): (target: Class<Job>) => void;
-    /**
-     * Unique identifier for the job.
-     */
-    readonly id: string;
-    /**
-     * The timestamp when the job was created.
-     */
-    readonly createdAt: Date;
-    /**
-     * The timestamp when the job started execution.
-     */
-    get startedAt(): Date | undefined;
-    /**
-     * The timestamp when the job completed execution.
-     */
-    get completedAt(): Date | undefined;
-    /**
-     * The current status of the job.
-     */
-    get status(): JobStatus;
-    /**
-     * Creates a new job instance.
-     *
-     * @param id Optional job ID. If not provided, a random ID will be generated.
-     */
-    constructor(id?: string);
-    /**
-     * Run the job.
-     * This method handles the job lifecycle and calls the execute method.
-     */
-    run(): Promise<void>;
-    /**
-     * Cancels the job.
-     */
-    cancel(): void;
-    /**
-     * The main execution method for the job.
-     * This must be implemented by all job classes.
-     */
-    protected abstract execute(): Promise<void>;
-    /**
-     * Generate a random job ID.
-     * @returns A random job ID.
-     */
-    private generateJobId;
-}
-/**
- * Possible statuses for a job.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export declare enum JobStatus {
-    /**
-     * The job is in pending state, meaning it has been added to the queue but has not yet been processed.
-     */
-    PENDING = "pending",
-    /**
-     * The job is in running state, meaning it is currently being processed.
-     */
-    RUNNING = "running",
-    /**
-     * The job has completed successfully.
-     */
-    COMPLETED = "completed",
-    /**
-     * The job has failed to complete successfully. If there are enough retries left, the job will be restarted.
-     */
-    FAILED = "failed",
-    /**
-     * The job has been cancelled by the user or another job.
-     */
-    CANCELLED = "cancelled"
-}

package/dist/worker.d.ts

@@ -1,219 +0,0 @@
-import type { Class } from 'type-fest';
-import type { Job } from './job';
-import { InteractsWithConsole } from './console';
-declare const BunWorker: {
-    new (scriptURL: string | URL, options?: WorkerOptions): globalThis.Worker;
-    prototype: globalThis.Worker;
-};
-type BunWorker = InstanceType<typeof BunWorker>;
-/**
- * Configuration options for a job queue.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export interface QueueOptions {
-    /**
-     * The name of the queue.
-     */
-    name: string;
-    /**
-     * The maximum number of concurrent jobs to process in this queue.
-     * @default 1
-     */
-    concurrency?: number;
-    /**
-     * The maximum number of retries for failed jobs.
-     * @default 0
-     */
-    maxRetries?: number;
-    /**
-     * The delay in milliseconds between retries.
-     * @default 1000
-     */
-    retryDelay?: number;
-    /**
-     * Whether to pause processing when an error occurs.
-     * @default false
-     */
-    pauseOnError?: boolean;
-}
-/**
- * Worker class that manages multiple job queues and processes them in parallel.
- * Each queue processes its jobs sequentially by default, but can be configured for concurrency.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export declare class Worker extends InteractsWithConsole {
-    #private;
-    /**
-     * The queues managed by this worker.
-     */
-    private queues;
-    /**
-     * The default queue name.
-     */
-    private defaultQueueName;
-    static spawn(thread: BunWorker, queues?: string[], options?: Omit<QueueOptions, 'name'>): Worker;
-    /**
-     * Creates a new Worker instance.
-     */
-    constructor();
-    /**
-     * Gets the worker ID.
-     * @returns The worker ID.
-     */
-    get id(): string;
-    /**
-     * Creates a new queue with the specified options.
-     *
-     * @param options The queue configuration options.
-     * @returns The Worker instance for method chaining.
-     */
-    createQueue(options: QueueOptions): Worker;
-    /**
-     * Adds a job to the specified queue or the default queue if not specified.
-     *
-     * @param job The job to add to the queue.
-     * @param queueName Optional name of the queue to add the job to. Defaults to the default queue.
-     * @returns The Worker instance for method chaining.
-     * @throws Error if the specified queue does not exist.
-     */
-    addJob(job: Job, queueName?: string): Worker;
-    /**
-     * Pauses a queue, preventing it from processing new jobs.
-     *
-     * @param queueName The name of the queue to pause. If not specified, pauses all queues.
-     * @returns The Worker instance for method chaining.
-     */
-    pause(queueName?: string): Worker;
-    /**
-     * Resumes a paused queue.
-     *
-     * @param queueName The name of the queue to resume. If not specified, resumes all queues.
-     * @returns The Worker instance for method chaining.
-     */
-    resume(queueName?: string): Worker;
-    /**
-     * Drains a queue, completing all current jobs but not accepting new ones.
-     *
-     * @param queueName The name of the queue to drain. If not specified, drains all queues.
-     * @returns The Worker instance for method chaining.
-     */
-    drain(queueName?: string): Worker;
-    /**
-     * Clears all jobs from a queue.
-     *
-     * @param queueName The name of the queue to clear. If not specified, clears all queues.
-     * @returns The Worker instance for method chaining.
-     */
-    clear(queueName?: string): Worker;
-    /**
-     * Gets the number of jobs in a queue.
-     *
-     * @param queueName The name of the queue to get the size of.
-     * @returns The number of jobs in the queue.
-     * @throws Error if the specified queue does not exist.
-     */
-    size(queueName?: string): number;
-    /**
-     * Gets the total number of jobs across all queues.
-     *
-     * @returns The total number of jobs.
-     */
-    totalSize(): number;
-    /**
-     * Processes the next job in the specified queue.
-     *
-     * @param queueName The name of the queue to process.
-     */
-    private processNextJob;
-    /**
-     * Processes jobs in a queue up to the concurrency limit.
-     *
-     * @param queueName The name of the queue to process.
-     */
-    private processQueueJobs;
-    /**
-     * Gets statistics about all queues.
-     *
-     * @returns An object containing statistics about each queue.
-     */
-    getStats(): Record<string, {
-        waiting: number;
-        processing: number;
-        paused: boolean;
-        draining: boolean;
-    }>;
-    /**
-     * Cancels a job by its ID.
-     *
-     * @param jobId The ID of the job to cancel.
-     * @param queueName Optional queue name to search in. If not provided, searches all queues.
-     * @returns `true` if the job was found and canceled, false otherwise.
-     */
-    cancelJob(jobId: string, queueName?: string): boolean;
-    /**
-     * Cancels a job in a specific queue.
-     *
-     * @param jobId The ID of the job to cancel.
-     * @param queueName The name of the queue to search in.
-     * @returns `true` if the job was found and canceled, false otherwise.
-     */
-    private cancelJobInQueue;
-    /**
-     * Cancels all jobs in a queue.
-     *
-     * @param queueName The name of the queue to cancel jobs from. If not provided, cancels jobs in all queues.
-     * @returns The number of jobs canceled.
-     */
-    cancelAllJobs(queueName?: string): number;
-}
-/**
- * A pool of worker threads.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export declare class WorkerPool extends InteractsWithConsole {
-    private workers;
-    private currentWorkerIndex;
-    private queueWorkerMap;
-    static readonly instance: WorkerPool;
-    private constructor();
-    /**
-     * Initialize the worker pool.
-     */
-    init(): Promise<void>;
-    /**
-     * Add a new worker to the pool.
-     * @param queues The queues to listen from the worker.
-     */
-    addWorker(queues?: string[]): Promise<void>;
-    /**
-     * Removes a worker from the pool.
-     * @param w The worker to be removed. If not provided, the last worker will be removed.
-     */
-    removeWorker(w?: BunWorker): void;
-    /**
-     * Terminates all workers in the pool.
-     */
-    terminate(): void;
-    /**
-     * Runs a job in a worker.
-     * @param job The job class to run.
-     * @param args The class constructor arguments to pass to the job.
-     */
-    runJob<T extends Job, TClass extends Class<T>>(job: TClass, ...args: ConstructorParameters<TClass>): void;
-    /**
-     * Cancels a job in the worker pool.
-     *
-     * @param jobId The ID of the job to cancel.
-     * @param queue Optional queue name to search in.
-     * @returns `true` if a cancellation message was sent to workers.
-     */
-    cancelJob(jobId: string, queue?: string): boolean;
-    /**
-     * Cancels all jobs in a queue.
-     *
-     * @param queue Optional queue name to cancel jobs from. If not provided, cancels jobs in all queues.
-     * @returns `true` if a cancellation message was sent to workers.
-     */
-    cancelAllJobs(queue?: string): boolean;
-}
-export {};