@elysiumjs/mnemosyne 0.1.0

package/dist/tenancy.d.ts

@@ -0,0 +1,180 @@
+import type { Context } from '@elysiumjs/core';
+import type { TenancyStrategy } from './interfaces';
+import { Middleware } from '@elysiumjs/core';
+/**
+ * The tenancy mode for the application.
+ * - `schema`: Each tenant has their own Postgres schema.
+ * - `rls`: Row-Level Security with a shared schema and a tenant column.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TenancyMode = 'schema' | 'rls';
+/**
+ * Global tenancy configuration for the application.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface TenancyConfig {
+    /**
+     * The tenancy mode to use.
+     */
+    mode: TenancyMode;
+    /**
+     * Configuration specific to RLS mode.
+     */
+    rls?: {
+        /**
+         * The PostgreSQL session variable used to store the current tenant.
+         * @default 'app.current_tenant'
+         */
+        sessionVariable?: string;
+        /**
+         * The default column name used for tenant isolation in RLS policies.
+         * @default 'tenant_id'
+         */
+        defaultColumn?: string;
+    };
+    /**
+     * Configuration specific to schema-based tenancy.
+     */
+    schema?: {
+        /**
+         * Whether to automatically create tenant schemas on first use.
+         */
+        autoCreate?: boolean;
+    };
+}
+/**
+ * Per-model tenancy configuration, used to control how a specific model
+ * interacts with the tenancy system.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface ModelTenancyConfig {
+    /**
+     * Whether tenancy is enabled for this model.
+     */
+    enabled: boolean;
+    /**
+     * Override the global tenancy mode for this model.
+     */
+    mode?: TenancyMode;
+    /**
+     * The column name used for RLS tenant isolation in this model.
+     */
+    column?: string;
+    /**
+     * Custom RLS policy name for this model.
+     */
+    policyName?: string;
+}
+/**
+ * Gets the current global tenancy configuration.
+ *
+ * Reads from the 'elysium:mnemosyne' app config key. Returns a default
+ * configuration if the app is not yet initialized or no tenancy config is set.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns The current tenancy configuration.
+ */
+export declare const getConfig: () => TenancyConfig;
+/**
+ * Registers the tenancy strategy to use for table resolution and isolation.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param strategy The tenancy strategy to register.
+ */
+export declare const registerTenancyStrategy: (strategy: TenancyStrategy<unknown, unknown>) => void;
+/**
+ * Gets the currently registered tenancy strategy.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns The current tenancy strategy, or `null` if none is registered.
+ */
+export declare const getTenancyStrategy: () => TenancyStrategy<unknown, unknown> | null;
+/**
+ * Gets the current tenant from the async context.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns The current tenant identifier, or `null` if not set.
+ */
+export declare const getCurrentTenant: () => string | null;
+/**
+ * Runs a callback within the context of a specific tenant.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier to set.
+ * @param callback The function to execute within the tenant context.
+ * @returns The return value of the callback.
+ */
+export declare const withTenant: <T>(tenant: string, callback: () => T) => T;
+/**
+ * Base class for tenant-aware middleware.
+ *
+ * The middleware extracts the tenant identifier from an HTTP header and
+ * sets `ctx.tenant`. For RLS mode, route handlers should use the driver's
+ * isolation mechanism to wrap their queries in a tenant-scoped transaction.
+ *
+ * @example
+ * ```typescript
+ * class OrganizationMiddleware extends TenantMiddleware {
+ *   protected header = 'x-organization-id';
+ *   protected allowPublic = false;
+ *
+ *   protected async validateTenant(orgId: string): Promise<boolean> {
+ *     return Organization.exists(orgId);
+ *   }
+ * }
+ * ```
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare abstract class TenantMiddleware extends Middleware {
+    /**
+     * The HTTP header name from which the tenant ID is read.
+     */
+    protected header: string;
+    /**
+     * Whether requests without a tenant ID are allowed (defaulting to 'public').
+     */
+    protected allowPublic: boolean;
+    /**
+     * The database connection name used for tenant operations.
+     */
+    protected connectionName: string;
+    /**
+     * Validates that a tenant identifier is legitimate.
+     * Override this to check against your data store.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param _tenant The tenant identifier to validate.
+     * @returns `true` if the tenant is valid, `false` otherwise.
+     */
+    protected validateTenant(_tenant: string): Promise<boolean>;
+    /**
+     * Hook called after a tenant has been successfully resolved.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param _tenant The resolved tenant identifier.
+     * @param _ctx The request context.
+     */
+    protected onTenantResolved(_tenant: string, _ctx: Context): Promise<void>;
+    /**
+     * Called when the tenant cannot be determined or is invalid.
+     * Throws an appropriate error by default.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param reason Whether the tenant is 'missing' or 'invalid'.
+     * @param _ctx The request context.
+     */
+    protected onTenantError(reason: 'missing' | 'invalid', _ctx: Context): never;
+    /**
+     * Extracts and validates the tenant from the incoming request.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param ctx The request context.
+     */
+    onRequest(ctx: Context): Promise<any>;
+}
+/**
+ * A simple tenant middleware that allows public access by default.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class SimpleTenantMiddleware extends TenantMiddleware {
+}
+/**
+ * A strict tenant middleware that rejects requests without a tenant ID.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class StrictTenantMiddleware extends TenantMiddleware {
+    protected allowPublic: boolean;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@elysiumjs/mnemosyne",
+	"version": "0.1.0",
+	"license": "Apache-2.0",
+	"description": "Database and caching for Elysium.js applications",
+	"private": false,
+	"author": "Workbud Technologies Inc.",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/workbud/elysium"
+	},
+	"homepage": "https://github.com/workbud/elysium",
+	"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:ts": "tsc",
+		"build": "bun run clean && bun run build:js && bun run build:ts",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "bun run build"
+	},
+	"keywords": [
+		"elysium",
+		"database",
+		"cache",
+		"orm"
+	],
+	"module": "dist/index.js",
+	"type": "module",
+	"types": "dist/index.d.ts",
+	"sideEffects": false,
+	"peerDependencies": {
+		"@elysiumjs/core": "^0.7.0"
+	},
+	"devDependencies": {
+		"@elysiumjs/core": "0.7.0"
+	},
+	"dependencies": {
+		"cache-manager": "^7.2.3",
+		"cacheable": "^2.0.3",
+		"keyv": "^5.0.0",
+		"radash": "^12.1.1",
+		"reflect-metadata": "^0.2.2"
+	}
+}

package/src/cache.ts

@@ -0,0 +1,218 @@
+// 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 { KeyvStoreAdapter } from 'keyv';
+
+import { createCache } from 'cache-manager';
+import { KeyvCacheableMemory } from 'cacheable';
+import { Keyv } from 'keyv';
+import { alphabetical } from 'radash';
+
+import { KeyvRedis } from './keyv-redis';
+
+/**
+ * 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 | undefined>;
+
+	/**
+	 * 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 | undefined>>;
+
+	/**
+	 * 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 `undefined` if the data does not exist.
+	 */
+	ttl(key: string): Promise<number | undefined>;
+
+	/**
+	 * 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'>;
+}
+
+/**
+ * Makes a cache interface wrapping the given store.
+ * @author Axel Nana <axel.nana@workburd.com>
+ * @param store The cache storage to use in the interface.
+ * @returns A new `CacheInterface`.
+ */
+const makeCacheInterface = (store: KeyvStoreAdapter): CacheInterface => {
+	const base = createCache({
+		stores: [
+			new Keyv({
+				store,
+				namespace: 'cache'
+			})
+		]
+	}) as Omit<CacheInterface, 'tags'>;
+
+	const tagsCache = new Map<string, Omit<CacheInterface, 'tags'>>();
+
+	return {
+		...base,
+		tags(...tags) {
+			const namespace = `cache__${alphabetical(tags, (item) => item).join('__')}`;
+			let cache = tagsCache.get(namespace);
+
+			if (!cache) {
+				cache = createCache({
+					stores: [
+						new Keyv({
+							store,
+							namespace
+						})
+					]
+				}) as Omit<CacheInterface, 'tags'>;
+
+				tagsCache.set(namespace, cache);
+			}
+
+			return cache;
+		}
+	};
+};
+
+export abstract class Cache {
+	static #redis: CacheInterface | undefined;
+	static #memory: CacheInterface | undefined;
+
+	/**
+	 * A weak cache storage for simple non-intrusive caching of data.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 */
+	public static readonly weak = Object.seal({
+		/**
+		 * INTERNAL USAGE ONLY.
+		 * @private
+		 */
+		map: new 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 {
+			if (!this.map.has(ctx)) this.map.set(ctx, {});
+			return this.map.get(ctx) as T;
+		},
+
+		/**
+		 * Deletes the cached data for a given context.
+		 * @param ctx The cache context.
+		 */
+		del(ctx: object): void {
+			this.map.delete(ctx);
+		}
+	});
+
+	/**
+	 * Redis-based cache storage.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 */
+	public static get redis(): CacheInterface {
+		if (!Cache.#redis) {
+			Cache.#redis = makeCacheInterface(
+				new KeyvRedis({
+					connection: 'cache'
+				})
+			);
+		}
+
+		return Cache.#redis;
+	}
+
+	/**
+	 * Memory-based cache storage.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 */
+	public static get memory(): CacheInterface {
+		if (!Cache.#memory) {
+			Cache.#memory = makeCacheInterface(new KeyvCacheableMemory({ ttl: 60000, lruSize: 5000 }));
+		}
+
+		return Cache.#memory;
+	}
+}

package/src/database.ts

@@ -0,0 +1,151 @@
+// 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 { CacheInterface } from './cache';
+import type { DatabaseCacheConfig, DatabaseDriver } from './interfaces';
+
+import { Application, Service } from '@elysiumjs/core';
+
+import { Cache } from './cache';
+
+/**
+ * Creates a cache storage instance tagged for database use.
+ * Drivers can use this to build their cache backends.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param config The database cache configuration.
+ * @returns A cache interface tagged with 'database'.
+ */
+export const createDatabaseCacheStorage = (
+	config: DatabaseCacheConfig
+): Omit<CacheInterface, 'tags'> => {
+	return Cache[config.storage ?? 'redis'].tags('database');
+};
+
+/**
+ * Abstract database manager.
+ *
+ * Manages named database connections using a driver. Connections are
+ * registered in the service container and can be retrieved by name.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TConnection The connection type managed by the driver.
+ * @template TConnectionConfig The configuration used to create a connection.
+ */
+export abstract class AbstractDatabase<TConnection, TConnectionConfig> {
+	/**
+	 * The database driver used to create and manage connections.
+	 */
+	protected abstract driver: DatabaseDriver<TConnection, TConnectionConfig>;
+
+	/**
+	 * Creates a service name for a database connection.
+	 * @param name The name of the connection.
+	 * @returns A service name for the connection.
+	 */
+	private getConnectionName(name: string): string {
+		return `db.connection.${name}`;
+	}
+
+	/**
+	 * Retrieves the connection with the given name.
+	 *
+	 * For the default connection, checks the async context for a
+	 * transaction handle (`db:tx`) before falling back to the service container.
+	 *
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The connection name.
+	 * @returns The connection with the given name.
+	 */
+	public getConnection(name: string = 'default'): TConnection {
+		if (name === 'default') {
+			const tx = Application.context.getStore()?.get('db:tx') as TConnection | undefined;
+			if (tx) return tx;
+		}
+
+		const serviceName = this.getConnectionName(name);
+		if (!Service.exists(serviceName)) {
+			// TODO: Use logger service here
+			console.error(
+				`No connection with name ${name} found. Please make sure to register the connection before using it.`
+			);
+			process.exit(1);
+		}
+
+		return Service.get<TConnection>(serviceName)!;
+	}
+
+	/**
+	 * Creates and registers a new connection.
+	 *
+	 * This will make the registered connection available for dependency injection with
+	 * the key `db.connection.{name}`, where `{name}` is replaced with the given name.
+	 *
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The connection name.
+	 * @param config The connection configuration.
+	 * @returns The newly created and registered connection.
+	 */
+	public registerConnection(name: string, config: TConnectionConfig): TConnection {
+		const serviceName = this.getConnectionName(name);
+		if (Service.exists(serviceName)) {
+			// TODO: Use logger service here
+			console.error(`A connection with the name ${name} has already been registered.`);
+			process.exit(1);
+		}
+
+		const connection = this.driver.createConnection(config);
+		return Service.instance(serviceName, connection);
+	}
+
+	/**
+	 * 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.
+	 */
+	public connectionExists(name: string): boolean {
+		return Service.exists(this.getConnectionName(name));
+	}
+
+	/**
+	 * Retrieves the default connection.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @returns The default connection.
+	 */
+	public getDefaultConnection(): TConnection {
+		return this.getConnection('default');
+	}
+
+	/**
+	 * 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.
+	 */
+	public setDefaultConnection(name: string): TConnection {
+		const serviceName = this.getConnectionName('default');
+		Service.remove(serviceName);
+		return Service.instance(serviceName, this.getConnection(name));
+	}
+
+	/**
+	 * Returns the raw underlying client for the given connection.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The connection name.
+	 * @returns The raw client instance.
+	 */
+	public getRawClient(name: string = 'default'): unknown {
+		return this.driver.getRawClient(this.getConnection(name));
+	}
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// Copyright (c) 2026-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 { TenancyConfig } from './tenancy';
+
+export type {
+	ColumnMetadata,
+	DatabaseCacheConfig,
+	DatabaseCacheStrategy,
+	DatabaseDriver,
+	IdType,
+	ModelAdapter,
+	ModelClass,
+	RepositoryClass,
+	RepositoryInterface,
+	TenancyStrategy
+} from './interfaces';
+
+export { AbstractDatabase, createDatabaseCacheStorage } from './database';
+export { createSchemaFromModel, AbstractModel } from './model';
+export { AbstractRepository } from './repository';
+
+export {
+	getConfig as getTenancyConfig,
+	getCurrentTenant,
+	withTenant,
+	registerTenancyStrategy,
+	getTenancyStrategy,
+	TenantMiddleware,
+	SimpleTenantMiddleware,
+	StrictTenantMiddleware
+} from './tenancy';
+export type { TenancyConfig, TenancyMode, ModelTenancyConfig } from './tenancy';
+
+export { Cache } from './cache';
+export type { CacheInterface } from './cache';
+export { KeyvRedis } from './keyv-redis';
+
+// Configuration types
+export interface MnemosyneConfig<TConnectionConfig = unknown> {
+	database?: {
+		default: string;
+		connections: Record<string, TConnectionConfig>;
+	};
+	tenancy?: TenancyConfig;
+}