@elysiumjs/core 0.4.3 → 0.5.1

package/dist/wamp.d.ts

@@ -0,0 +1,272 @@
+import type { Class, Primitive } from 'type-fest';
+/**
+ * Options used to register a WAMP RPC for invocation.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampRegistrationOptions = {
+    /**
+     * The match policy to use for the registration.
+     * @default 'exact'
+     */
+    match?: 'prefix' | 'exact' | 'wildcard';
+    /**
+     * The invocation policy to use for the registration.
+     * @default 'single'
+     */
+    invoke?: 'single' | 'first' | 'last' | 'roundrobin' | 'random';
+};
+/**
+ * Options used to subscribe to a WAMP topic.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampSubscriptionOptions = Omit<WampRegistrationOptions, 'invoke'>;
+/**
+ * Properties required when declaring a WAMP controller using the `@wamp()` decorator.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampProps = {
+    /**
+     * The name of the connection to use. This connection must be registered in the application properties.
+     * @default 'default'
+     */
+    connection?: string;
+};
+/**
+ * Properties required when declaring a WAMP client in the application properties.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampClientProps = {
+    /**
+     * The URL to the WAMP server.
+     */
+    url: string;
+    /**
+     * The name of the realm to connect to.
+     */
+    realm: string;
+    /**
+     * Whether to automatically reconnect to the WAMP server on connection loss.
+     */
+    autoReconnect?: boolean;
+    /**
+     * The maximum number of times to retry connecting to the WAMP server.
+     */
+    maxRetries?: number;
+    /**
+     * The interval to wait between retries when connecting to the WAMP server.
+     */
+    retryInterval?: number;
+    /**
+     * The authentication ID to use in challenges.
+     */
+    authid?: string;
+    /**
+     * An array of supported authentication methods.
+     */
+    authmethods?: string[];
+    /**
+     * Callback for handling WAMP authentication challenges.
+     * @param method The authentication method.
+     * @param extra Authentication metadata.
+     */
+    onChallenge?(method: string, extra: any): string | null;
+    /**
+     * Callback for handling the WAMP connection open event.
+     */
+    onOpen?(): void;
+    /**
+     * Callback for handling the WAMP connection close event.
+     */
+    onClose?(): void;
+    /**
+     * Callback for handling the WAMP connection error event.
+     */
+    onError?(): void;
+    /**
+     * Callback for handling the WAMP connection reconnect event.
+     */
+    onReconnect?(): void;
+    /**
+     * 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;
+    }>;
+};
+/**
+ * Data sent to a WAMP RPC.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampRegistrationHandlerArgs<TList = any[], TDict = any> = {
+    /**
+     * The arguments passed to the RPC or subscription.
+     */
+    argsList: TList;
+    /**
+     * The keyword arguments passed to the RPC or subscription.
+     */
+    argsDict: TDict;
+    /**
+     * The WAMP details object.
+     */
+    details: {
+        receive_progress?: boolean;
+        trustlevel?: number;
+    };
+    /**
+     * The result handler for the RPC. Use this to send progressive results.
+     * @param value
+     */
+    result_handler: (value: any) => void;
+    /**
+     * The error handler for the RPC when working with progressive results.
+     * @param error The thrown error.
+     */
+    error_handler: (error: any) => void;
+};
+/**
+ * Data sent to a WAMP subscription.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampSubscriptionHandlerArgs = Omit<WampRegistrationHandlerArgs, 'result_handler' | 'error_handler'>;
+/**
+ * The WAMP RPC handler function.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param data The data sent to the handler.
+ */
+export type WampRegistrationHandler = <T = any>(data: WampRegistrationHandlerArgs) => T;
+/**
+ * The WAMP subscription handler function.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param data The data sent to the handler.
+ */
+export type WampSubscriptionHandler = <T = any>(data: WampSubscriptionHandlerArgs) => T;
+export declare namespace Wamp {
+    /**
+     * Retrieves the client 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.
+     */
+    const getConnection: (name: string) => WampClient;
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    const registerConnection: (name: string, config: WampClientProps) => WampClient;
+    /**
+     * Checks if a WAMP connection with the given name exists.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the connection.
+     * @returns `true` if the connection exists, `false` otherwise.
+     */
+    const connectionExists: (name: string) => boolean;
+    /**
+     * Retrieves the default WAMP connection.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @returns The default WAMP connection.
+     */
+    const getDefaultConnection: () => WampClient;
+    /**
+     * Sets the default WAMP connection.
+     * @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;
+    /**
+     * Marks a class as a WAMP controller.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param options The decorator options.
+     */
+    const controller: (options: WampProps) => (target: Class<any>) => void;
+    /**
+     * Registers a method as a WAMP RPC.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param topic The RPC topic to register.
+     * @param options The registration options.
+     */
+    const register: (topic: string, options?: WampRegistrationOptions) => MethodDecorator;
+    /**
+     * Subscribes to a WAMP topic.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param topic The topic to subscribe to.
+     * @param options The subscription options.
+     */
+    const subscribe: (topic: string, options?: WampSubscriptionOptions) => MethodDecorator;
+}

package/dist/websocket.d.ts

@@ -0,0 +1,91 @@
+import type { ServerWebSocket } from 'bun';
+import type { Context, ErrorContext, TSchema } from 'elysia';
+import type { Class, ConditionalPick, JsonObject, Primitive } from 'type-fest';
+import type { Route } from './http';
+/**
+ * Properties required when declaring a websocket controller using the `@websocket()` decorator.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WebsocketProps = {
+    /**
+     * The path of the websocket route.
+     */
+    path: Route;
+    /**
+     * The options for the websocket server.
+     */
+    options?: ConditionalPick<Bun.WebSocketHandler, Primitive | JsonObject>;
+};
+/**
+ * The websocket connection instance.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TData Additional data stored in the websocket connection.
+ */
+export type WS<TData = unknown> = ServerWebSocket<{
+    /**
+     * Unique identifier for the websocket connection.
+     */
+    id: string;
+} & Context & TData>;
+/**
+ * The data generated when an error occurs in a websocket connection.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WSError = ErrorContext & {
+    error: Readonly<Error>;
+};
+export declare namespace Websocket {
+    /**
+     * Marks a class as a websocket controller.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param props The websocket route properties.
+     */
+    const controller: (props: WebsocketProps) => (target: Class<any>) => void;
+    /**
+     * Marks a method as the websocket "open" event handler.
+     *
+     * This decorator should be used on a websocket controller method. Only one "open" event handler
+     * can be defined per websocket controller.
+     *
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const onOpen: () => MethodDecorator;
+    /**
+     * Marks a method as the websocket "close" event handler.
+     *
+     * This decorator should be used on a websocket controller method. Only one "close" event handler
+     * can be defined per websocket controller.
+     *
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const onClose: () => MethodDecorator;
+    /**
+     * Marks a method as the websocket "message" event handler.
+     *
+     * This decorator should be used on a websocket controller method. Only one "message" event handler
+     * can be defined per websocket controller.
+     *
+     * @author Axel Nana <axel.nana@workbud.com>
+     *
+     * @param schema The schema of the message body.
+     */
+    const onMessage: (schema?: TSchema) => MethodDecorator;
+    /**
+     * Marks a method as the websocket "drain" event handler.
+     *
+     * This decorator should be used on a websocket controller method. Only one "drain" event handler
+     * can be defined per websocket controller.
+     *
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const onDrain: () => MethodDecorator;
+    /**
+     * Marks a method as the websocket "error" event handler.
+     *
+     * This decorator should be used on a websocket controller method. Only one "error" event handler
+     * can be defined per websocket controller.
+     *
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    const onError: () => MethodDecorator;
+}

package/dist/worker.d.ts

@@ -0,0 +1,219 @@
+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 {};

package/package.json

@@ -1,17 +1,22 @@
 {
 	"name": "@elysiumjs/core",
-	"version": "0.4.3",
+	"version": "0.5.1",
 	"license": "Apache-2.0",
 	"description": "A super-charged web framework for Bun, built on top of ElysiaJS.",
 	"private": false,
 	"author": "Workbud Technologies Inc.",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/Workerly/elysium"
+		"url": "https://github.com/workbud/elysium"
 	},
-	"homepage": "https://github.com/Workerly/elysium",
+	"homepage": "https://github.com/workbud/elysium",
 	"scripts": {
-		"format": "prettier --write \"./src/**/*.ts\""
+		"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:ts": "tsc",
+		"build": "bun run clean && bun run build:js && bun run build:ts",
+		"prepublishOnly": "bun run build"
 	},
 	"keywords": [
 		"elysium",
@@ -20,22 +25,24 @@
 		"api",
 		"typescript"
 	],
-	"module": "index.ts",
+	"module": "dist/index.js",
 	"type": "module",
+	"types": "dist/index.d.ts",
 	"dependencies": {
 		"@elysiajs/swagger": "^1.3.0",
 		"cache-manager": "^6.4.3",
 		"cacheable": "^1.9.0",
-		"drizzle-orm": "0.43.1-4aa795a",
+		"drizzle-orm": "^0.44.2",
 		"elysia": "latest",
 		"radash": "^12.1.0",
 		"reflect-metadata": "^0.2.2",
 		"wampy": "^7.1.1"
 	},
 	"devDependencies": {
-		"@ianvs/prettier-plugin-sort-imports": "^4.4.1",
-		"type-fest": "^4.41.0",
-		"@types/bun": "latest"
+		"@ianvs/prettier-plugin-sort-imports": "^4.4.2",
+		"@types/bun": "latest",
+		"rimraf": "^6.0.1",
+		"type-fest": "^4.41.0"
 	},
 	"peerDependencies": {
 		"typescript": "^5.8.3"