@elysiumjs/mnemosyne 0.1.2 → 0.3.1

package/dist/tenancy.d.ts

@@ -0,0 +1,201 @@
+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;
+/**
+ * The pattern a tenant identifier must match: 1 to 63 ASCII letters, digits, underscores or dashes,
+ * not starting with `pg_` and other than `information_schema` (in any case).
+ *
+ * Tenant identifiers become PostgreSQL schema names in schema mode, and 63 bytes is the PostgreSQL
+ * identifier limit. The pattern leaves out quotes, dots, spaces and other characters that would
+ * need escaping or change how an identifier is read, and the names of PostgreSQL system schemas.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const TENANT_ID_PATTERN: RegExp;
+/**
+ * Checks that a tenant identifier is well-formed (see {@link TENANT_ID_PATTERN}). This does not
+ * check that the tenant exists.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier.
+ * @returns `true` if the identifier is well-formed, `false` otherwise.
+ */
+export declare const isValidTenantId: (tenant: string) => boolean;
+/**
+ * Base class for tenant-aware middleware.
+ *
+ * The middleware extracts the tenant identifier from an HTTP header and
+ * sets `ctx.tenant`. Identifiers must match {@link TENANT_ID_PATTERN} and be accepted by
+ * `validateTenant`, which rejects every tenant unless overridden. 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.
+     *
+     * Rejects every tenant by default: override it to check the tenant against your data store.
+     * Only identifiers matching {@link TENANT_ID_PATTERN} reach this method.
+     * @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. Requests naming a tenant are
+ * rejected until `validateTenant` is overridden.
+ * @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,23 +1,29 @@
 {
 	"name": "@elysiumjs/mnemosyne",
-	"version": "0.1.2",
+	"version": "0.3.1",
 	"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"
+		"url": "git+https://github.com/na2axl/elysiumjs.git",
+		"directory": "@elysiumjs/mnemosyne"
+	},
+	"homepage": "https://github.com/na2axl/elysiumjs/tree/main/@elysiumjs/mnemosyne#readme",
+	"bugs": {
+		"url": "https://github.com/na2axl/elysiumjs/issues"
 	},
-	"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: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",
-		"prepublishOnly": "bun run build"
+		"prepublishOnly": "bun run build",
+		"test": "bun test",
+		"test:coverage": "bun test --coverage"
 	},
 	"keywords": [
 		"elysium",
@@ -28,18 +34,21 @@
 	"module": "dist/index.js",
 	"type": "module",
 	"types": "dist/index.d.ts",
+	"files": [
+		"dist",
+		"CHANGELOG.md"
+	],
 	"sideEffects": false,
 	"peerDependencies": {
-		"@elysiumjs/core": "workspace:^"
+		"@elysiumjs/core": "^0.10.0"
 	},
 	"devDependencies": {
-		"@elysiumjs/core": "workspace:*"
+		"@elysiumjs/core": "0.10.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/bunfig.toml

@@ -1,19 +0,0 @@
-[test]
-# The root directory of all unit tests
-root = "./tests"
-# A file loaded right before running `bun test`
-preload = ["./tests/setup.ts"]
-# Enable code coverage by default
-coverage = true
-# Requires 90% line coverage, 70% function coverage, and 80% statement coverage
-coverageThreshold = { line = 0.9, function = 0.7, statement = 0.8 }
-# Tests files are included in the coverage statistics
-coverageSkipTestFiles = true
-# Use lcov as the coverage reporter
-coverageReporter = ["lcov", "text"]
-# Path the output coverage results
-coverageDir = "./coverage"
-
-[run]
-# Always use bun runtime for every `bun run` commands
-bun = true

package/src/cache.ts

@@ -1,218 +0,0 @@
-// 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

@@ -1,151 +0,0 @@
-// 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

@@ -1,47 +0,0 @@
-// 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 * from './database';
-export * from './model';
-export * from './repository';
-
-export * from './tenancy';
-export type { TenancyConfig, TenancyMode, ModelTenancyConfig } from './tenancy';
-
-export * from './cache';
-export * from './keyv-redis';
-
-// Configuration types
-export interface MnemosyneConfig<TConnectionConfig = unknown> {
-	database?: {
-		default: string;
-		connections: Record<string, TConnectionConfig>;
-	};
-	tenancy?: TenancyConfig;
-}