@elysiumjs/mnemosyne 0.1.2 → 0.2.0

package/dist/tenancy.d.ts

@@ -0,0 +1,179 @@
+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;
+}
+/** Name of the global service holding the {@link TenancyConfig}, registered by driver modules. */
+export declare const TENANCY_CONFIG_SERVICE = "mnemosyne.tenancy.config";
+/** Name of the global service holding the {@link TenancyStrategy}, registered by driver modules. */
+export declare const TENANCY_STRATEGY_SERVICE = "mnemosyne.tenancy.strategy";
+/**
+ * Gets the current global tenancy configuration.
+ *
+ * Reads the global service `mnemosyne.tenancy.config`. Returns a default
+ * configuration if none is registered.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns The current tenancy configuration.
+ */
+export declare const getTenancyConfig: () => TenancyConfig;
+/**
+ * Gets the tenancy strategy registered by the driver module as the global service
+ * `mnemosyne.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

@@ -1,6 +1,6 @@
 {
 	"name": "@elysiumjs/mnemosyne",
-	"version": "0.1.2",
+	"version": "0.2.0",
 	"license": "Apache-2.0",
 	"description": "Database and caching for Elysium.js applications",
 	"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",
@@ -30,16 +30,15 @@
 	"types": "dist/index.d.ts",
 	"sideEffects": false,
 	"peerDependencies": {
-		"@elysiumjs/core": "workspace:^"
+		"@elysiumjs/core": "^0.8.0"
 	},
 	"devDependencies": {
-		"@elysiumjs/core": "workspace:*"
+		"@elysiumjs/core": "0.8.0"
 	},
 	"dependencies": {
-		"cache-manager": "^7.2.3",
-		"cacheable": "^2.0.3",
-		"keyv": "^5.0.0",
-		"radash": "catalog:",
-		"reflect-metadata": "catalog:"
+		"cache-manager": "^7.2.9",
+		"cacheable": "^2.5.0",
+		"keyv": "^5.6.0",
+		"radash": "^12.1.1"
 	}
 }

package/src/cache.ts

@@ -14,12 +14,16 @@
 
 import type { KeyvStoreAdapter } from 'keyv';
 
+import { Service, ServiceNotFoundError } from '@elysiumjs/core';
 import { createCache } from 'cache-manager';
-import { KeyvCacheableMemory } from 'cacheable';
 import { Keyv } from 'keyv';
 import { alphabetical } from 'radash';
 
-import { KeyvRedis } from './keyv-redis';
+/** Name of the global service backing `Cache.redis`. */
+export const REDIS_CACHE_SERVICE = 'mnemosyne.cache.redis';
+
+/** Name of the global service backing `Cache.memory`. */
+export const MEMORY_CACHE_SERVICE = 'mnemosyne.cache.memory';
 
 /**
  * Interface for a cache storage.
@@ -118,7 +122,7 @@ export interface CacheInterface {
  * @param store The cache storage to use in the interface.
  * @returns A new `CacheInterface`.
  */
-const makeCacheInterface = (store: KeyvStoreAdapter): CacheInterface => {
+export const makeCacheInterface = (store: KeyvStoreAdapter): CacheInterface => {
 	const base = createCache({
 		stores: [
 			new Keyv({
@@ -154,10 +158,17 @@ const makeCacheInterface = (store: KeyvStoreAdapter): CacheInterface => {
 	};
 };
 
-export abstract class Cache {
-	static #redis: CacheInterface | undefined;
-	static #memory: CacheInterface | undefined;
+const getCache = (name: string): CacheInterface => {
+	const cache = Service.get<CacheInterface>(name);
+	if (!cache) throw new ServiceNotFoundError(name);
+	return cache;
+};
 
+/**
+ * Static access to the caches provided by the `MnemosyneModule`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export abstract class Cache {
 	/**
 	 * A weak cache storage for simple non-intrusive caching of data.
 	 * @author Axel Nana <axel.nana@workbud.com>
@@ -191,28 +202,18 @@ export abstract class Cache {
 	/**
 	 * Redis-based cache storage.
 	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @throws {ServiceNotFoundError} If the `MnemosyneModule` is not loaded or has no redis cache.
 	 */
 	public static get redis(): CacheInterface {
-		if (!Cache.#redis) {
-			Cache.#redis = makeCacheInterface(
-				new KeyvRedis({
-					connection: 'cache'
-				})
-			);
-		}
-
-		return Cache.#redis;
+		return getCache(REDIS_CACHE_SERVICE);
 	}
 
 	/**
 	 * Memory-based cache storage.
 	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @throws {ServiceNotFoundError} If the `MnemosyneModule` is not loaded or has no memory cache.
 	 */
 	public static get memory(): CacheInterface {
-		if (!Cache.#memory) {
-			Cache.#memory = makeCacheInterface(new KeyvCacheableMemory({ ttl: 60000, lruSize: 5000 }));
-		}
-
-		return Cache.#memory;
+		return getCache(MEMORY_CACHE_SERVICE);
 	}
 }

package/src/database.ts

@@ -15,7 +15,7 @@
 import type { CacheInterface } from './cache';
 import type { DatabaseCacheConfig, DatabaseDriver } from './interfaces';
 
-import { Application, Service } from '@elysiumjs/core';
+import { Application, Service, ServiceNotFoundError } from '@elysiumjs/core';
 
 import { Cache } from './cache';
 
@@ -35,8 +35,8 @@ export const createDatabaseCacheStorage = (
 /**
  * Abstract database manager.
  *
- * Manages named database connections using a driver. Connections are
- * registered in the service container and can be retrieved by name.
+ * Retrieves named database connections using a driver. Connections are registered as
+ * global services `db.connection.{name}` by the driver modules.
  *
  * @author Axel Nana <axel.nana@workbud.com>
  * @template TConnection The connection type managed by the driver.
@@ -49,11 +49,13 @@ export abstract class AbstractDatabase<TConnection, TConnectionConfig> {
 	protected abstract driver: DatabaseDriver<TConnection, TConnectionConfig>;
 
 	/**
-	 * Creates a service name for a database connection.
+	 * Creates a service name for a database connection. Driver modules register their
+	 * connections (and the `default` alias) under this name.
+	 * @author Axel Nana <axel.nana@workbud.com>
 	 * @param name The name of the connection.
 	 * @returns A service name for the connection.
 	 */
-	private getConnectionName(name: string): string {
+	public static getConnectionName(name: string): string {
 		return `db.connection.${name}`;
 	}
 
@@ -62,6 +64,7 @@ export abstract class AbstractDatabase<TConnection, TConnectionConfig> {
 	 *
 	 * For the default connection, checks the async context for a
 	 * transaction handle (`db:tx`) before falling back to the service container.
+	 * @throws {ServiceNotFoundError} If no connection with that name is registered.
 	 *
 	 * @author Axel Nana <axel.nana@workbud.com>
 	 * @param name The connection name.
@@ -73,39 +76,11 @@ export abstract class AbstractDatabase<TConnection, TConnectionConfig> {
 			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 serviceName = AbstractDatabase.getConnectionName(name);
+		const connection = Service.get<TConnection>(serviceName);
+		if (connection === null) throw new ServiceNotFoundError(serviceName);
 
-		const connection = this.driver.createConnection(config);
-		return Service.instance(serviceName, connection);
+		return connection;
 	}
 
 	/**
@@ -115,7 +90,7 @@ export abstract class AbstractDatabase<TConnection, TConnectionConfig> {
 	 * @returns `true` if the connection exists, `false` otherwise.
 	 */
 	public connectionExists(name: string): boolean {
-		return Service.exists(this.getConnectionName(name));
+		return Service.exists(AbstractDatabase.getConnectionName(name));
 	}
 
 	/**
@@ -127,18 +102,6 @@ export abstract class AbstractDatabase<TConnection, TConnectionConfig> {
 		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>

package/src/index.ts

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { TenancyConfig } from './tenancy';
-
 export type {
 	ColumnMetadata,
 	DatabaseCacheConfig,
@@ -34,14 +32,6 @@ export * from './repository';
 export * from './tenancy';
 export type { TenancyConfig, TenancyMode, ModelTenancyConfig } from './tenancy';
 
-export * from './cache';
+export { Cache, type CacheInterface, MEMORY_CACHE_SERVICE, REDIS_CACHE_SERVICE } from './cache';
+export * from './mnemosyne.module';
 export * from './keyv-redis';
-
-// Configuration types
-export interface MnemosyneConfig<TConnectionConfig = unknown> {
-	database?: {
-		default: string;
-		connections: Record<string, TConnectionConfig>;
-	};
-	tenancy?: TenancyConfig;
-}

package/src/keyv-redis.ts

@@ -17,7 +17,7 @@ import type { KeyvEntry, StoredData } from 'keyv';
 
 import { EventEmitter } from 'node:events';
 
-import { Event, Redis } from '@elysiumjs/core';
+import { Event, Redis, Service } from '@elysiumjs/core';
 
 /**
  * Keyv adapter for redis. This adapter is based on the Bun's Redis client.
@@ -68,10 +68,6 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 	}) {
 		super();
 
-		Event.once('elysium:app:launched', () => {
-			this.#client = Redis.getConnection(props.connection);
-		});
-
 		this.#connection = props.connection;
 		this.#namespace = props.namespace;
 		this.#keyPrefixSeparator = props.keyPrefixSeparator ?? '::';
@@ -84,8 +80,15 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 		});
 	}
 
-	public get client() {
-		return this.#client!;
+	/**
+	 * Resolves the Redis client on first use. The async path is always safe, even when the
+	 * Redis module has not been initialised yet (lazy boot).
+	 */
+	protected async getClient(): Promise<Bun.RedisClient> {
+		this.#client ??= await Service.resolve<Bun.RedisClient>(
+			Redis.getConnectionName(this.#connection)
+		);
+		return this.#client;
 	}
 
 	/**
@@ -118,23 +121,26 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 	}
 
 	public async get<Value>(key: string): Promise<StoredData<Value> | undefined> {
+		const client = await this.getClient();
 		key = this.createKeyPrefix(key, this.#namespace);
-		const value = await this.client.get(key);
+		const value = await client.get(key);
 
 		return value === null ? undefined : (value as Value);
 	}
 
 	public async set(key: string, value: any, ttl?: number) {
+		const client = await this.getClient();
 		key = this.createKeyPrefix(key, this.#namespace);
 
 		if (ttl) {
-			await this.client.set(key, value, 'PX', ttl);
+			await client.set(key, value, 'PX', ttl);
 		} else {
-			await this.client.set(key, value);
+			await client.set(key, value);
 		}
 	}
 
 	public async setMany(values: Array<KeyvEntry>): Promise<void> {
+		const client = await this.getClient();
 		// TODO: Use MULTI when available in Bun
 		const multi = [];
 
@@ -142,10 +148,10 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 			const prefixedKey = this.createKeyPrefix(key, this.#namespace);
 			if (ttl) {
 				// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-unsafe-argument
-				multi.push(this.client.set(prefixedKey, value, 'PX', ttl));
+				multi.push(client.set(prefixedKey, value, 'PX', ttl));
 			} else {
 				// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-				multi.push(this.client.set(prefixedKey, value));
+				multi.push(client.set(prefixedKey, value));
 			}
 		}
 
@@ -153,19 +159,20 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 	}
 
 	public async delete(key: string): Promise<boolean> {
+		const client = await this.getClient();
 		key = this.createKeyPrefix(key, this.#namespace);
 		// TODO: Use UNLINK when available in Bun
-		const deleted = await (this.#useUnlink
-			? this.client.send('UNLINK', [key])
-			: this.client.del(key));
+		const deleted = await (this.#useUnlink ? client.send('UNLINK', [key]) : client.del(key));
 
 		return deleted > 0;
 	}
 
 	public async clear(): Promise<void> {
 		try {
+			const client = await this.getClient();
+
 			if (!this.#namespace && this.#noNamespaceAffectsAll) {
-				await this.client.send('FLUSHDB', []);
+				await client.send('FLUSHDB', []);
 				return;
 			}
 
@@ -175,7 +182,7 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 			const deletePromises = [];
 
 			do {
-				const result = await this.client.send('SCAN', [
+				const result = await client.send('SCAN', [
 					cursor,
 					'MATCH',
 					match,
@@ -197,7 +204,7 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 					keys = keys.filter((key: string) => !key.includes(this.#keyPrefixSeparator));
 				}
 
-				deletePromises.push(keys.map((key: string) => this.client.del(key)));
+				deletePromises.push(keys.map((key: string) => client.del(key)));
 			} while (cursor !== '0');
 
 			await Promise.all(deletePromises);
@@ -207,37 +214,42 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 	}
 
 	public async has(key: string): Promise<boolean> {
+		const client = await this.getClient();
 		key = this.createKeyPrefix(key, this.#namespace);
-		return this.client.exists(key);
+		return client.exists(key);
 	}
 
 	public async hasMany(keys: string[]): Promise<boolean[]> {
+		const client = await this.getClient();
 		const multi = [];
 
 		for (const key of keys) {
 			const prefixedKey = this.createKeyPrefix(key, this.#namespace);
-			multi.push(this.client.exists(prefixedKey));
+			multi.push(client.exists(prefixedKey));
 		}
 
 		return Promise.all(multi);
 	}
 
 	public async getMany<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>> {
+		const client = await this.getClient();
 		if (keys.length === 0) {
 			return [];
 		}
 
 		keys = keys.map((key) => this.createKeyPrefix(key, this.#namespace));
-		const values = await this.client.mget(...keys);
+		const values = await client.mget(...keys);
 
 		return values as Value[];
 	}
 
 	public async disconnect(): Promise<void> {
-		this.client.close();
+		// The connection is owned by the Redis module; only drop our reference to it.
+		this.#client = undefined;
 	}
 
 	public async deleteMany(keys: string[]): Promise<boolean> {
+		const client = await this.getClient();
 		let result = false;
 
 		// TODO: Use MULTI when available in Bun
@@ -246,9 +258,9 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 		for (const key of keys) {
 			const prefixedKey = this.createKeyPrefix(key, this.#namespace);
 			if (this.#useUnlink) {
-				multi.push(this.client.send('UNLINK', [prefixedKey]));
+				multi.push(client.send('UNLINK', [prefixedKey]));
 			} else {
-				multi.push(this.client.del(prefixedKey));
+				multi.push(client.del(prefixedKey));
 			}
 		}
 
@@ -266,11 +278,12 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 	public async *iterator<Value>(
 		namespace?: string
 	): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void> {
+		const client = await this.getClient();
 		const match = namespace ? `${namespace}${this.#keyPrefixSeparator}*` : '*';
 		let cursor = '0';
 
 		do {
-			const result = await this.client.send('SCAN', [cursor, 'MATCH', match, 'TYPE', 'string']);
+			const result = await client.send('SCAN', [cursor, 'MATCH', match, 'TYPE', 'string']);
 
 			// Parse the result
 			let [newCursor, keys] = result;
@@ -281,7 +294,7 @@ export class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 			}
 
 			if (keys.length > 0) {
-				const values = await this.client.mget(...keys);
+				const values = await client.mget(...keys);
 				for (const i of keys.keys()) {
 					const key = this.getKeyWithoutPrefix(keys[i], namespace);
 					const value = values[i];