@elysiumjs/mnemosyne-drizzle 0.1.0

package/dist/tenancy.d.ts

@@ -0,0 +1,88 @@
+import type { TenancyStrategy } from '@elysiumjs/mnemosyne';
+import type { PgColumnBuilderBase, PgSchema, PgTable, PgTransaction } from 'drizzle-orm/pg-core';
+import type { DrizzleConnection } from './database';
+/**
+ * Returns the Drizzle `PgSchema` for the given tenant, creating it if needed.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier.
+ * @returns The tenant's PostgreSQL schema.
+ */
+export declare const getTenantSchema: (tenant: string) => PgSchema;
+/**
+ * Registers a new tenant schema in the registry.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier.
+ * @returns The newly registered (or existing) `PgSchema`.
+ */
+export declare const registerTenantSchema: (tenant: string) => PgSchema;
+/**
+ * Wraps a table definition in a tenant-specific schema.
+ *
+ * For the `'public'` tenant, returns a standard `pgTable`.
+ * For other tenants, creates a schema-qualified table and caches it.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier.
+ * @param tableName The table name.
+ * @param columns The column definitions.
+ * @returns A tenant-scoped `PgTable`.
+ */
+export declare const wrapTenantSchema: <TTableName extends string, TColumnsMap extends Record<string, PgColumnBuilderBase>>(tenant: string, tableName: TTableName, columns: TColumnsMap) => PgTable;
+/**
+ * Executes a callback within an RLS-scoped transaction for the given tenant.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier (or `null` for 'public').
+ * @param callback The function to execute within the transaction.
+ * @param connectionName The database connection name.
+ * @returns The return value of the callback.
+ */
+export declare const withRLS: <T>(tenant: string | null, callback: (tx: PgTransaction<any, any, any>) => Promise<T>, connectionName?: string) => Promise<T>;
+/**
+ * Sets the current tenant on a persistent database connection (session-level).
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier (or `null` for 'public').
+ * @param connectionName The database connection name.
+ */
+export declare const setConnectionTenant: (tenant: string | null, connectionName?: string) => Promise<void>;
+/**
+ * Reads the current tenant from the PostgreSQL session variable.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param connectionName The database connection name.
+ * @returns The current tenant identifier, or `null`.
+ */
+export declare const getSessionTenant: (connectionName?: string) => Promise<string | null>;
+/**
+ * Creates an RLS policy for tenant isolation on a table.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tableName The table name.
+ * @param columnName The tenant column name (defaults to config or 'tenant_id').
+ * @param policyName The policy name (defaults to `{tableName}_tenant_isolation`).
+ * @returns A Drizzle `PgPolicy` instance.
+ */
+export declare const createRLSPolicy: (tableName: string, columnName?: string, policyName?: string) => import("drizzle-orm/pg-core").PgPolicy;
+/**
+ * Schema-based tenancy strategy for Drizzle.
+ *
+ * Each tenant gets its own PostgreSQL schema. Table resolution maps
+ * the base table to a schema-qualified equivalent.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DrizzleSchemaTenancy implements TenancyStrategy<PgTable, DrizzleConnection> {
+    readonly mode = "schema";
+    resolveTable(table: PgTable, tenant: string): PgTable;
+    withIsolation<T>(_connection: DrizzleConnection, _tenant: string, callback: () => Promise<T>): Promise<T>;
+}
+/**
+ * Row-Level Security tenancy strategy for Drizzle.
+ *
+ * All tenants share the same schema. Isolation is achieved via
+ * PostgreSQL RLS policies and a session variable set in each transaction.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DrizzleRLSTenancy implements TenancyStrategy<PgTable, DrizzleConnection> {
+    readonly mode = "rls";
+    resolveTable(table: PgTable, _tenant: string): PgTable;
+    withIsolation<T>(connection: DrizzleConnection, tenant: string, callback: () => Promise<T>): Promise<T>;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@elysiumjs/mnemosyne-drizzle",
+	"version": "0.1.0",
+	"license": "Apache-2.0",
+	"description": "Drizzle ORM driver for @elysiumjs/mnemosyne",
+	"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", "orm", "drizzle", "postgresql"],
+	"module": "dist/index.js",
+	"type": "module",
+	"types": "dist/index.d.ts",
+	"sideEffects": false,
+	"peerDependencies": {
+		"@elysiumjs/core": "^0.7.0",
+		"@elysiumjs/mnemosyne": "^0.1.0"
+	},
+	"dependencies": {
+		"drizzle-orm": "^0.44.6"
+	},
+	"devDependencies": {
+		"@elysiumjs/core": "0.7.0",
+		"@elysiumjs/mnemosyne": "0.1.0"
+	}
+}

package/src/database.ts

@@ -0,0 +1,175 @@
+// 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 { CacheInterface, DatabaseCacheConfig, DatabaseDriver } from '@elysiumjs/mnemosyne';
+import type { DrizzleConfig } from 'drizzle-orm';
+import type { BunSQLDatabase } from 'drizzle-orm/bun-sql';
+import type { CacheConfig } from 'drizzle-orm/cache/core/types';
+
+import { AbstractDatabase, createDatabaseCacheStorage } from '@elysiumjs/mnemosyne';
+import { getTableName, is, Table } from 'drizzle-orm';
+import { drizzle } from 'drizzle-orm/bun-sql';
+import { Cache as DrizzleCache } from 'drizzle-orm/cache/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Connection configuration for Drizzle ORM.
+ *
+ * Extends `DrizzleConfig` with connection details and optional caching.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TSchema The Drizzle schema type.
+ */
+export type DrizzleConnectionProps<
+	TSchema extends Record<string, unknown> = Record<string, never>
+> = Omit<DrizzleConfig<TSchema>, 'cache'> &
+	({ connection: string | ({ url?: string } & Bun.SQLOptions) } | { client: Bun.SQL }) & {
+		cache?: true | DatabaseCacheConfig;
+	};
+
+/**
+ * A Drizzle database connection backed by Bun's SQL driver.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type DrizzleConnection = BunSQLDatabase<Record<string, never>> & { $client: Bun.SQL };
+
+// ============================================================================
+// DrizzleDatabaseCache
+// ============================================================================
+
+/**
+ * Drizzle query cache backed by the framework's cache storage.
+ *
+ * Extends the Drizzle `Cache` base class and implements the
+ * framework's `DatabaseCacheStrategy` interface so that query
+ * results can be transparently cached and invalidated.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export class DrizzleDatabaseCache extends DrizzleCache {
+	#cache: Omit<CacheInterface, 'tags'>;
+	private usedTablesPerKey: Record<string, string[]> = {};
+
+	constructor(
+		private readonly cacheStrategy: 'explicit' | 'all' = 'explicit',
+		private readonly globalTtl: number = 1,
+		storageEngine: 'redis' | 'memory' = 'redis'
+	) {
+		super();
+		this.#cache = createDatabaseCacheStorage({ storage: storageEngine });
+	}
+
+	public override strategy(): 'explicit' | 'all' {
+		return this.cacheStrategy;
+	}
+
+	public override async get(key: string): Promise<any[] | undefined> {
+		return (await this.#cache.get<any[]>(key)) ?? undefined;
+	}
+
+	public override async put(
+		key: string,
+		response: any,
+		tables: string[],
+		_isTag: boolean,
+		config?: CacheConfig
+	): Promise<void> {
+		await this.#cache.set(key, response, (config?.ex ?? this.globalTtl) * 1000);
+		for (const table of tables) {
+			const keys = this.usedTablesPerKey[table];
+			if (keys === undefined) {
+				this.usedTablesPerKey[table] = [key];
+			} else {
+				keys.push(key);
+			}
+		}
+	}
+
+	public override async onMutate(params: {
+		tags?: string | string[];
+		tables?: string | string[] | Table<any> | Table<any>[];
+	}): Promise<void> {
+		const tagsArray = params.tags ? (Array.isArray(params.tags) ? params.tags : [params.tags]) : [];
+		const tablesArray = params.tables
+			? Array.isArray(params.tables)
+				? params.tables
+				: [params.tables]
+			: [];
+		const keysToDelete = new Set<string>();
+
+		for (const table of tablesArray) {
+			const tableName = is(table, Table) ? getTableName(table as Table) : (table as string);
+			const keys = this.usedTablesPerKey[tableName] ?? [];
+			for (const key of keys) keysToDelete.add(key);
+		}
+
+		if (keysToDelete.size > 0 || tagsArray.length > 0) {
+			await this.#cache.mdel(tagsArray);
+			await this.#cache.mdel([...keysToDelete]);
+			for (const table of tablesArray) {
+				const tableName = is(table, Table) ? getTableName(table as Table) : (table as string);
+				this.usedTablesPerKey[tableName] = [];
+			}
+		}
+	}
+}
+
+// ============================================================================
+// DrizzleDatabase
+// ============================================================================
+
+/**
+ * Drizzle-specific database manager.
+ *
+ * Implements the abstract database class with a driver that creates
+ * Drizzle connections using Bun's built-in SQL client.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+class DrizzleDatabase extends AbstractDatabase<DrizzleConnection, DrizzleConnectionProps> {
+	protected driver: DatabaseDriver<DrizzleConnection, DrizzleConnectionProps> = {
+		createConnection(config) {
+			const cache =
+				config.cache === undefined
+					? undefined
+					: config.cache === true
+						? new DrizzleDatabaseCache()
+						: config.cache.enabled !== false
+							? new DrizzleDatabaseCache(
+									config.cache.strategy,
+									config.cache.ttl,
+									config.cache.storage
+								)
+							: undefined;
+			return drizzle({ ...config, cache }) as DrizzleConnection;
+		},
+
+		withTransaction(connection, callback) {
+			return (connection as any).transaction((tx: any) => callback(tx));
+		},
+
+		getRawClient(connection) {
+			return connection.$client;
+		}
+	};
+}
+
+/**
+ * Singleton Drizzle database manager.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export const Database = new DrizzleDatabase();

package/src/index.ts

@@ -0,0 +1,69 @@
+// 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 { MnemosyneConfig } from '@elysiumjs/mnemosyne';
+import type { DrizzleConnectionProps } from './database';
+
+import { Application, Event } from '@elysiumjs/core';
+import { registerTenancyStrategy } from '@elysiumjs/mnemosyne';
+
+import { Database } from './database';
+import { DrizzleRLSTenancy, DrizzleSchemaTenancy } from './tenancy';
+
+// Re-export drizzle-orm/pg-core with enhanced pgTable
+export * from 'drizzle-orm/pg-core';
+export { pgTable, getTableBuilders } from './table';
+
+// Re-exports
+export { Database, DrizzleDatabaseCache } from './database';
+export type { DrizzleConnectionProps, DrizzleConnection } from './database';
+export {
+	DrizzleModel,
+	createSchemaFromDrizzle,
+	drizzleAdapter,
+	type DrizzleModelOptions
+} from './model';
+export { DrizzleRepository } from './repository';
+export {
+	DrizzleSchemaTenancy,
+	DrizzleRLSTenancy,
+	wrapTenantSchema,
+	registerTenantSchema,
+	getTenantSchema,
+	withRLS,
+	setConnectionTenant,
+	getSessionTenant,
+	createRLSPolicy
+} from './tenancy';
+
+// Auto-initialize on app launch
+Event.once('elysium:app:launched', () => {
+	const app = Application.instance;
+	const config = app.getConfig<MnemosyneConfig<DrizzleConnectionProps>>('elysium:mnemosyne' as any);
+
+	if (config?.database) {
+		for (const [name, props] of Object.entries(config.database.connections)) {
+			Database.registerConnection(name, props);
+		}
+		if (Database.connectionExists(config.database.default)) {
+			Database.setDefaultConnection(config.database.default);
+		}
+	}
+
+	if (config?.tenancy) {
+		const strategy =
+			config.tenancy.mode === 'rls' ? new DrizzleRLSTenancy() : new DrizzleSchemaTenancy();
+		registerTenancyStrategy(strategy);
+	}
+});

package/src/model.ts

@@ -0,0 +1,171 @@
+// 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 { ColumnMetadata, ModelAdapter } from '@elysiumjs/mnemosyne';
+import type { PgColumn, PgTableWithColumns } from 'drizzle-orm/pg-core';
+
+import { AbstractModel, createSchemaFromModel } from '@elysiumjs/mnemosyne';
+import { getTableConfig } from 'drizzle-orm/pg-core';
+
+import { getTableBuilders } from './table';
+import { wrapTenantSchema } from './tenancy';
+
+// ============================================================================
+// Column Type Mapping
+// ============================================================================
+
+/**
+ * Maps a Drizzle column to a normalized data type.
+ * @param col The Drizzle column to inspect.
+ * @returns A normalized data type string.
+ */
+const mapDrizzleDataType = (col: PgColumn): ColumnMetadata['dataType'] => {
+	if (col.columnType === 'PgUUID') return 'uuid';
+	switch (col.dataType) {
+		case 'string':
+			return 'string';
+		case 'number':
+			return 'number';
+		case 'boolean':
+			return 'boolean';
+		case 'array':
+			return 'array';
+		case 'json':
+			return 'json';
+		case 'date':
+			return 'date';
+		case 'bigint':
+			return 'bigint';
+		case 'buffer':
+			return 'buffer';
+		default:
+			return 'string';
+	}
+};
+
+// ============================================================================
+// Drizzle Model Adapter
+// ============================================================================
+
+/**
+ * Drizzle-specific model adapter.
+ *
+ * Bridges Drizzle's `PgTableWithColumns` to the framework's
+ * normalized model metadata.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export const drizzleAdapter: ModelAdapter<PgTableWithColumns<any>> = {
+	getTableName(table) {
+		return getTableConfig(table).name;
+	},
+
+	getColumns(table): ColumnMetadata[] {
+		const config = getTableConfig(table);
+		return config.columns.map((col: PgColumn) => ({
+			name: col.name,
+			dataType: mapDrizzleDataType(col),
+			nullable: !col.notNull,
+			hasDefault: col.hasDefault,
+			isPrimaryKey:
+				col.primary || config.primaryKeys.some((pk) => pk.columns.some((c) => c.name === col.name))
+		}));
+	},
+
+	createTenantTable(table, tenant) {
+		const builders = getTableBuilders(table);
+		if (!builders) {
+			throw new Error(
+				`No column builders registered for table. ` +
+					`Use pgTable() from '@elysiumjs/mnemosyne-drizzle' for tenant support.`
+			);
+		}
+		const config = getTableConfig(table);
+		return wrapTenantSchema(tenant, config.name, builders) as PgTableWithColumns<any>;
+	}
+};
+
+// ============================================================================
+// Schema Helper
+// ============================================================================
+
+/**
+ * Creates Elysia validation schemas from a Drizzle table.
+ *
+ * This is a convenience wrapper around `createSchemaFromModel` that
+ * automatically extracts column metadata via the `drizzleAdapter`.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param table The Drizzle table to generate schemas for.
+ * @param opts Schema generation options.
+ * @returns An Elysia validation schema.
+ */
+export const createSchemaFromDrizzle = (
+	table: PgTableWithColumns<any>,
+	opts?: { mode?: 'create' | 'update' | 'select' }
+) => {
+	return createSchemaFromModel(drizzleAdapter.getColumns(table), opts);
+};
+
+// ============================================================================
+// DrizzleModel Options
+// ============================================================================
+
+/**
+ * Options for creating a DrizzleModel.
+ */
+export interface DrizzleModelOptions {
+	/**
+	 * Enable tenant schema support for this model.
+	 * @default false
+	 */
+	supportTenancy?: boolean;
+}
+
+// ============================================================================
+// DrizzleModel Function
+// ============================================================================
+
+/**
+ * Creates a model class backed by a Drizzle pgTable.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param table The Drizzle table (created with enhanced pgTable).
+ * @param options Model configuration options.
+ * @returns A model class with Drizzle-backed static metadata.
+ */
+export const DrizzleModel = <TTable extends PgTableWithColumns<any>>(
+	table: TTable,
+	options?: DrizzleModelOptions
+) => {
+	const config = getTableConfig(table);
+	const builders = getTableBuilders(table);
+
+	type TSelect = TTable['$inferSelect'];
+	type TInsert = TTable['$inferInsert'];
+
+	const Base = AbstractModel(config.name, builders ?? {}, drizzleAdapter, table);
+
+	// Override supportTenancy if specified
+	if (options?.supportTenancy !== undefined) {
+		(Base as any).supportTenancy = options.supportTenancy;
+	}
+
+	return Base as typeof Base & {
+		readonly $inferSelect: TSelect;
+		readonly $inferInsert: TInsert;
+		readonly $inferUpdate: Partial<TInsert>;
+		readonly table: TTable;
+	};
+};

package/src/repository.ts

@@ -0,0 +1,113 @@
+// 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 { IdType, ModelClass } from '@elysiumjs/mnemosyne';
+import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
+import type { DrizzleConnection } from './database';
+
+import { AbstractRepository } from '@elysiumjs/mnemosyne';
+import { eq } from 'drizzle-orm';
+
+import { Database } from './database';
+
+// ============================================================================
+// DrizzleRepository Mixin
+// ============================================================================
+
+/**
+ * Drizzle-specific repository mixin with concrete CRUD operations.
+ *
+ * Extends the abstract repository with Drizzle query builder calls
+ * for all standard CRUD methods.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TModel The model class type.
+ * @param model The model class to create the repository for.
+ * @returns A concrete repository class with CRUD methods.
+ */
+export const DrizzleRepository = <
+	TModel extends ModelClass<any, any, any, PgTableWithColumns<any>>
+>(
+	model: TModel
+) => {
+	type TSelect = TModel['$inferSelect'];
+	type TInsert = TModel['$inferInsert'];
+	type TUpdate = TModel['$inferUpdate'];
+
+	class R extends AbstractRepository<TModel, DrizzleConnection>(model, Database) {
+		public async all(): Promise<TSelect[]> {
+			return await this.db.select().from(model.table);
+		}
+
+		public async paginate(
+			count: number,
+			page: number = 1
+		): Promise<{ page: number; data: TSelect[]; total: number }> {
+			const total = await this.db.$count(model.table);
+			const offset = Math.max(page - 1, 0) * count;
+			return {
+				page,
+				total,
+				data: await this.db.select().from(model.table).offset(offset).limit(count)
+			};
+		}
+
+		public async find(id: IdType): Promise<TSelect | null> {
+			const [row] = await this.db.select().from(model.table).where(eq(model.table.id, id));
+			return (row ?? null) as TSelect | null;
+		}
+
+		public async findBy<TKey extends keyof TSelect>(
+			column: TKey,
+			value: TSelect[TKey]
+		): Promise<TSelect | null> {
+			const [row] = await this.db.select().from(model.table).where(eq(model.table[column], value));
+			return (row ?? null) as TSelect | null;
+		}
+
+		public async insert(data: TInsert): Promise<TSelect> {
+			const [row] = await this.db.insert(model.table).values(data).returning();
+			return row as TSelect;
+		}
+
+		public async update(id: IdType, data: TUpdate): Promise<TSelect> {
+			const [row] = await this.db
+				.update(model.table)
+				.set(data)
+				.where(eq(model.table.id, id))
+				.returning();
+			return row as TSelect;
+		}
+
+		public async updateAll(data: TUpdate): Promise<TSelect[]> {
+			return await this.db.update(model.table).set(data).returning();
+		}
+
+		public async delete(id: IdType): Promise<TSelect> {
+			const [row] = await this.db.delete(model.table).where(eq(model.table.id, id)).returning();
+			return row as TSelect;
+		}
+
+		public async deleteAll(): Promise<TSelect[]> {
+			return await this.db.delete(model.table).returning();
+		}
+
+		public async exists(id: IdType): Promise<boolean> {
+			const count = await this.db.$count(model.table, eq(model.table.id, id));
+			return count > 0;
+		}
+	}
+
+	return R;
+};