@elysiumjs/core 0.1.0

package/src/job.ts

@@ -0,0 +1,196 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'reflect-metadata';
+
+import type { Class } from 'type-fest';
+
+import { assign, uid } from 'radash';
+
+import { InteractsWithConsole } from './console';
+import { Service } from './service';
+import { Symbols } from './utils';
+
+/**
+ * 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 abstract class Job extends InteractsWithConsole {
+	#startedAt?: Date;
+	#completedAt?: Date;
+	#status: JobStatus = JobStatus.PENDING;
+	#err?: Error;
+
+	/**
+	 * Marks a class as a job.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param options The decorator options.
+	 */
+	public static register(options: JobProps = {}) {
+		return function (target: Class<Job>) {
+			options = assign({ name: target.name, queue: 'default' }, options);
+
+			const name = `job.${options.name}`;
+
+			Service.instance(name, target);
+
+			Reflect.defineMetadata(Symbols.job, { name, queue: options.queue }, target);
+		};
+	}
+
+	/**
+	 * Unique identifier for the job.
+	 */
+	public readonly id: string;
+
+	/**
+	 * The timestamp when the job was created.
+	 */
+	public readonly createdAt: Date;
+
+	/**
+	 * The timestamp when the job started execution.
+	 */
+	public get startedAt(): Date | undefined {
+		return this.#startedAt;
+	}
+
+	/**
+	 * The timestamp when the job completed execution.
+	 */
+	public get completedAt(): Date | undefined {
+		return this.#completedAt;
+	}
+
+	/**
+	 * The current status of the job.
+	 */
+	public get status(): JobStatus {
+		return this.#status;
+	}
+
+	/**
+	 * Creates a new job instance.
+	 *
+	 * @param id Optional job ID. If not provided, a random ID will be generated.
+	 */
+	constructor(id?: string) {
+		super();
+		this.id = id || this.generateJobId();
+		this.createdAt = new Date();
+	}
+
+	/**
+	 * Run the job.
+	 * This method handles the job lifecycle and calls the execute method.
+	 */
+	public async run(): Promise<void> {
+		try {
+			this.#status = JobStatus.RUNNING;
+			this.#startedAt = new Date();
+
+			this.debug(`Job ${this.id} started at ${this.#startedAt.toISOString()}`);
+
+			// Execute the job implementation
+			await this.execute();
+
+			this.#status = JobStatus.COMPLETED;
+			this.#completedAt = new Date();
+
+			this.debug(`Job ${this.id} completed at ${this.#completedAt.toISOString()}`);
+		} catch (err) {
+			this.#err = err instanceof Error ? err : new Error(String(err));
+
+			if (this.#status !== JobStatus.CANCELLED) {
+				this.#status = JobStatus.FAILED;
+			}
+
+			this.#completedAt = new Date();
+
+			this.trace(this.#err);
+		}
+	}
+
+	/**
+	 * Cancels the job.
+	 */
+	public cancel(): void {
+		this.#status = JobStatus.CANCELLED;
+	}
+
+	/**
+	 * 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(): string {
+		return `job_${Date.now()}_${uid(8)}`;
+	}
+}
+
+/**
+ * Possible statuses for a job.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export 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/src/middleware.ts

@@ -0,0 +1,122 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Elysia } from 'elysia';
+import type { Class } from 'type-fest';
+import type { Context, Route } from './http';
+
+import { Application } from './app';
+import { Service } from './service';
+import { Symbols } from './utils';
+
+/**
+ * Execute a chain of middlewares, stopping on the first return or throw.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param middlewares The list of middleware instances to execute.
+ * @param context The context to pass to each middleware.
+ * @param method The method to call on each middleware.
+ */
+export const executeMiddlewareChain = <T extends Context>(
+	middlewares: Middleware[],
+	context: T,
+	method: keyof Middleware
+): Promise<any> => {
+	return Application.context.run(
+		new Map([
+			['tenant', context.tenant],
+			['http:context', context]
+		]),
+		async () => {
+			for (const middleware of middlewares) {
+				try {
+					const result = await middleware[method](context);
+					if (result !== undefined) {
+						return result; // Stop the chain if middleware returns a value
+					}
+				} catch (error) {
+					throw error; // Stop the chain and propagate the error
+				}
+			}
+		}
+	);
+};
+
+/**
+ * Apply a list of middlewares to an Elysia plugin.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param middlewares The list of middlewares to apply.
+ * @param plugin The Elysia plugin instance.
+ */
+export const applyMiddlewares = (middlewares: Class<Middleware>[], plugin: Elysia<Route>) => {
+	const mi = middlewares.map((middleware) => Service.make<Middleware>(middleware));
+
+	plugin.onBeforeHandle((c) => {
+		return executeMiddlewareChain(mi, c, 'onBeforeHandle');
+	});
+
+	plugin.onAfterHandle((c) => {
+		return executeMiddlewareChain(mi, c, 'onAfterHandle');
+	});
+
+	plugin.onAfterResponse((c) => {
+		return executeMiddlewareChain(mi, c, 'onAfterResponse');
+	});
+};
+
+/**
+ * Base class for middleware.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export abstract class Middleware {
+	/**
+	 * Registers a list of middlewares to be applied on a controller or endpoint.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param middlewares The list of middlewares to apply.
+	 */
+	public static register(...middlewares: Class<Middleware>[]): ClassDecorator & MethodDecorator {
+		return function (
+			target: Object,
+			propertyKey?: string | symbol,
+			descriptor?: PropertyDescriptor
+		) {
+			if (propertyKey === undefined && descriptor === undefined) {
+				const m = Reflect.getMetadata(Symbols.middlewares, target) ?? [];
+				m.push(...middlewares);
+				Reflect.defineMetadata(Symbols.middlewares, m, target);
+			} else {
+				const m = Reflect.getMetadata(Symbols.middlewares, target, propertyKey!) ?? [];
+				m.push(...middlewares);
+				Reflect.defineMetadata(Symbols.middlewares, m, target, propertyKey!);
+			}
+		};
+	}
+
+	/**
+	 * Called after the request has been handled, but before the response is sent.
+	 * @param ctx The request context.
+	 */
+	public onAfterHandle(ctx: Context): any {}
+
+	/**
+	 * Called before the request is handled.
+	 * @param ctx The request context.
+	 */
+	public onBeforeHandle(ctx: Context): any {}
+
+	/**
+	 * Called after the response has been sent.
+	 * @param ctx The request context.
+	 */
+	public onAfterResponse(ctx: Context): any {}
+}

package/src/model.ts

@@ -0,0 +1,312 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { PgColumn, PgColumnBuilderBase, PgSchema, PgTable } from 'drizzle-orm/pg-core';
+import type { TSchema } from 'elysia';
+
+import { getTableConfig, pgSchema, pgTable } from 'drizzle-orm/pg-core';
+import { t } from 'elysia';
+
+import { Application } from './app';
+
+/**
+ * Creates a validation schema from a Drizzle table.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param table The table to create the schema from.
+ * @param options The schema generation options.
+ * @returns A bew validation schema based on the given table.
+ */
+export const createSchemaFromDrizzle = (
+	table: PgTable,
+	{ mode = 'select' }: { mode?: 'create' | 'update' | 'select' } = {}
+) => {
+	const { columns } = getTableConfig(table);
+	if (columns === undefined) return t.Object({});
+
+	const properties: { [key: string]: TSchema } = {};
+
+	for (const element of columns) {
+		if (['create', 'update'].includes(mode) && element.primary) {
+			continue;
+		}
+
+		properties[element.name] = parseTypes(element);
+
+		if (!element.notNull) {
+			properties[element.name] = t.Nullable(properties[element.name]);
+		}
+
+		if (mode === 'update' || element.hasDefault) {
+			properties[element.name] = t.Optional(properties[element.name]);
+		}
+	}
+
+	return t.Object(properties);
+};
+
+/**
+ * Creates a validation schema from a Drizzle column.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param element The Drizzle column.
+ * @returns A validation schema based on the given column.
+ */
+const parseTypes = (element: PgColumn) => {
+	let type = (() => {
+		switch (element.dataType) {
+			case 'string':
+				return t.String();
+			case 'number':
+				return t.Number();
+			case 'boolean':
+				return t.Boolean();
+			case 'array':
+				return t.Array(t.Any());
+			case 'json':
+				return t.Object({});
+			case 'date':
+			case 'localDate':
+			case 'localDateTime':
+				return t.Date();
+			case 'bigint':
+				return t.BigInt();
+			case 'buffer':
+				return t.File();
+			default:
+				return t.Never();
+		}
+	})();
+
+	if (!element.notNull) {
+		type = t.Optional(type);
+	}
+
+	return type;
+};
+
+/**
+ * Type of a repository class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TColumnsMap The table columns config.
+ * @template TTable The drizzle's table schema wrapped by the repository.
+ */
+export type ModelClass<
+	TColumnsMap extends Record<string, PgColumnBuilderBase>,
+	TTable extends PgTable = ReturnType<typeof pgTable<string, TColumnsMap>>
+> = {
+	/**
+	 * The data type returned by the select queries.
+	 */
+	readonly $inferSelect: TTable['$inferSelect'];
+
+	/**
+	 * The data type needed by the insert queries.
+	 */
+	readonly $inferInsert: TTable['$inferInsert'];
+
+	/**
+	 * The data type needed by the update queries.
+	 */
+	readonly $inferUpdate: Partial<TTable['$inferSelect']>;
+
+	/**
+	 * The name of the table wrapped by the model.
+	 */
+	readonly tableName: string;
+
+	/**
+	 * The table columns configuration.
+	 */
+	readonly columns: TColumnsMap;
+
+	/**
+	 * The validation schema for creating records.
+	 */
+	readonly createSchema: TSchema;
+
+	/**
+	 * The validation schema for updating records.
+	 */
+	readonly updateSchema: TSchema;
+
+	/**
+	 * The validation schema for selecting records.
+	 */
+	readonly selectSchema: TSchema;
+
+	/**
+	 * Whether the model supports tenancy.
+	 *
+	 * Set it to `true` if the model supports tenancy. This means that the model will be
+	 * wrapped by the `Tenancy.withTenant()` function when the current tenant is not `public`.
+	 */
+	readonly supportTenancy: boolean;
+
+	/**
+	 * Creates a new instance of the model.
+	 * @param args The arguments to pass to the constructor.
+	 * @returns A new instance of the model.
+	 */
+	new (...args: unknown[]): unknown;
+};
+
+/**
+ * Mixin used to create a new model class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TColumnsMap The table columns config.
+ * @param tableName The name of the table.
+ * @param columns The table columns configuration.
+ */
+export const Model = <TColumnsMap extends Record<string, PgColumnBuilderBase>>(
+	tableName: string,
+	columns: TColumnsMap
+) => {
+	const table = pgTable(tableName, columns);
+
+	class M {
+		/**
+		 * The data type returned by the select queries.
+		 */
+		public static readonly $inferSelect = table.$inferSelect;
+
+		/**
+		 * The data type needed by the insert queries.
+		 */
+		public static readonly $inferInsert = table.$inferInsert;
+
+		/**
+		 * The data type needed by the update queries.
+		 */
+		public static readonly $inferUpdate: Partial<typeof table.$inferInsert> = table.$inferInsert;
+
+		/**
+		 * The name of the table wrapped by the model.
+		 */
+		public static readonly tableName: string = tableName;
+
+		/**
+		 * The table columns configuration.
+		 */
+		public static readonly columns: TColumnsMap = columns;
+
+		/**
+		 * The validation schema for creating records.
+		 */
+		public static readonly createSchema = createSchemaFromDrizzle(table, { mode: 'create' });
+
+		/**
+		 * The validation schema for updating records.
+		 */
+		public static readonly updateSchema = createSchemaFromDrizzle(table, { mode: 'update' });
+
+		/**
+		 * The validation schema for selecting records.
+		 */
+		public static readonly selectSchema = createSchemaFromDrizzle(table, { mode: 'select' });
+
+		/**
+		 * Whether the model supports tenancy.
+		 *
+		 * Set it to `true` if the model supports tenancy. This means that the model will be
+		 * wrapped by the `Tenancy.withTenant()` function when the current tenant is not `public`.
+		 */
+		public static readonly supportTenancy: boolean = false;
+	}
+
+	return M;
+};
+
+/**
+ * A map of tables registered for each tenant.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+const tenantSchemas: Map<string, PgTable> = new Map();
+
+/**
+ * A map of known tenant schemas.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+const schemaRegistry: Map<string, PgSchema> = new Map();
+
+export namespace Tenancy {
+	/**
+	 * Gets the schema for the given tenant.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param tenant The name of the tenant.
+	 * @returns The tenant schema for the given tenant.
+	 */
+	const getTenantSchema = (tenant: string) => {
+		return schemaRegistry.get(tenant) ?? registerTenant(tenant);
+	};
+
+	/**
+	 * Gets the name of the current tenant.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @returns The name of the current tenant, or `null` if no tenant is set.
+	 */
+	export const getCurrentTenant = (): string | null => {
+		const store = Application.context.getStore();
+		return (store?.get('tenant') ?? null) as string | null;
+	};
+
+	/**
+	 * Sets the current tenant.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @template T The type of the model class to wrap with the tenant.
+	 * @template TColumnsMap The table columns config.
+	 * @param tenant The name of the tenant.
+	 * @param model The model class that wraps the `PgTable`.
+	 * @returns The drizzle's table schema wrapped by the tenant.
+	 */
+	export const withTenant = <
+		T extends ModelClass<TColumnsMap>,
+		TColumnsMap extends Record<string, PgColumnBuilderBase> = T extends ModelClass<
+			infer TColumnsMap
+		>
+			? TColumnsMap
+			: Record<string, PgColumnBuilderBase>
+	>(
+		tenant: string,
+		model: T
+	) => {
+		if (tenant === 'public') {
+			return pgTable(model.tableName, model.columns);
+		}
+
+		const tableName = `${tenant}.${model.tableName}`;
+		if (tenantSchemas.has(tableName)) {
+			return tenantSchemas.get(tableName)!;
+		}
+
+		const tenantSchema = getTenantSchema(tenant);
+		const schemaTable = tenantSchema.table(model.tableName, model.columns);
+		tenantSchemas.set(tableName, schemaTable);
+
+		return schemaTable;
+	};
+
+	/**
+	 * Registers a new tenant schema.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param tenant The name of the tenant.
+	 * @returns A new schema for the given tenant.
+	 */
+	export const registerTenant = (tenant: string) => {
+		if (schemaRegistry.has(tenant)) return schemaRegistry.get(tenant)!;
+
+		const tenantSchema = pgSchema(tenant);
+		schemaRegistry.set(tenant, tenantSchema);
+
+		return tenantSchema;
+	};
+}