@elysiumjs/core 0.5.4 → 0.6.0

package/dist/repository.d.ts

@@ -56,6 +56,12 @@ export interface RepositoryInterface<TModel extends ModelClass<TTableName, TColu
      * @returns All the records in the database.
      */
     deleteAll(): Promise<TModel['$inferSelect'][]>;
+    /**
+     * Checks if a record exists in the database.
+     * @param id The ID of the record to check.
+     * @returns True if the record exists, false otherwise.
+     */
+    exists(id: TId): Promise<boolean>;
 }
 /**
  * Type of a repository class.
@@ -89,7 +95,7 @@ export declare const Repository: <TModel extends ModelClass<TTableName, TColumns
         /**
          * The database connection used by this repository.
          */
-        readonly db: DatabaseConnection;
+        get db(): DatabaseConnection;
         /**
          * Retrieves all the records in the database.
          * @returns All the records in the database.
@@ -149,6 +155,12 @@ export declare const Repository: <TModel extends ModelClass<TTableName, TColumns
          * @returns All the records in the database.
          */
         deleteAll(): Promise<TModel["$inferSelect"][]>;
+        /**
+         * Checks if a record exists in the database.
+         * @param id The ID of the record to check.
+         * @returns True if the record exists, false otherwise.
+         */
+        exists(id: TId): Promise<boolean>;
     };
     /**
      * The drizzle's table schema wrapped by this repository.

package/dist/service.d.ts

@@ -65,11 +65,19 @@ export declare namespace Service {
     const inject: (service?: string | ServiceClass) => ParameterDecorator;
     /**
      * Retrieves a registered service's instance from the container.
+     * Resolves lazy services on first access and caches the result.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The name of the service, or its class.
      * @returns An instance of the registered service, or `null` if no service with that name/type was registered.
      */
     const get: <T>(service: string | TypedServiceClass<T>) => T | null;
+    /**
+     * Registers a lazy service that is only instantiated on first access.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param name The name of the service.
+     * @param resolver A factory function called on first access.
+     */
+    const registerLazy: <T>(name: string, resolver: () => T) => void;
     /**
      * Instantiates a service with its dependencies.
      *

package/dist/tenancy.d.ts

@@ -0,0 +1,244 @@
+import type { PgColumnBuilderBase, PgSchema, PgTable, PgTransaction } from 'drizzle-orm/pg-core';
+import type { Context } from './http';
+import { Middleware } from './middleware';
+/**
+ * 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;
+}
+/**
+ * Sets the global tenancy configuration.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param config The tenancy configuration to apply.
+ */
+export declare const configure: (config: TenancyConfig) => void;
+/**
+ * Gets the current global tenancy configuration.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns The current tenancy configuration.
+ */
+export declare const getConfig: () => TenancyConfig;
+/**
+ * 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;
+/**
+ * Gets the Drizzle `PgSchema` for the given tenant.
+ * Creates and registers the schema if it doesn't exist yet.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The name of the tenant.
+ * @returns The Postgres schema for the tenant.
+ */
+export declare const getTenantSchema: (tenant: string) => PgSchema;
+/**
+ * Registers a new Postgres schema for a tenant.
+ * If the schema is already registered, returns the existing one.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The name of the tenant.
+ * @returns The newly created or existing tenant schema.
+ */
+export declare const registerTenantSchema: (tenant: string) => PgSchema;
+/**
+ * Wraps a table definition within a tenant's Postgres schema.
+ * For the `public` tenant, returns a standard `pgTable`.
+ * Results are cached for performance.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier.
+ * @param tableName The name of the table.
+ * @param columns The table columns definition.
+ * @returns A `PgTable` scoped to the tenant's schema.
+ */
+export declare const wrapTenantSchema: <TTableName extends string, TColumnsMap extends Record<string, PgColumnBuilderBase>>(tenant: string, tableName: TTableName, columns: TColumnsMap) => PgTable;
+/**
+ * Execute a callback within a transaction that has the tenant context set
+ * via PostgreSQL session variable.
+ *
+ * Uses `set_config(varName, value, true)` which:
+ * - Sets the variable value as a proper GUC parameter (not an identifier)
+ * - The `true` flag makes it transaction-local (reverts on commit/rollback)
+ *
+ * The transaction handle (`tx`) is passed to the callback so all
+ * queries execute within the same transaction where `set_config` was called.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier, or `null` for the public tenant.
+ * @param callback A function receiving the transaction handle.
+ * @param connectionName The database connection to use.
+ * @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 tenant for the current database connection (session-level, not transaction-local).
+ * Useful for long-lived connections or connection pools.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tenant The tenant identifier, or `null` for the public tenant.
+ * @param connectionName The database connection to use.
+ */
+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 to use.
+ * @returns The current tenant identifier, or `null` if not set.
+ */
+export declare const getSessionTenant: (connectionName?: string) => Promise<string | null>;
+/**
+ * Create an RLS policy for tenant isolation.
+ *
+ * Always specifies `for` and `to` for deterministic behavior:
+ * - `for: 'all'` — policy applies to SELECT, INSERT, UPDATE, DELETE
+ * - `to: 'public'` — policy applies to all roles
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param tableName The name of the table to create the policy for.
+ * @param columnName The column that holds the tenant identifier. Defaults to the global config.
+ * @param policyName Custom name for the policy. Defaults to `{tableName}_tenant_isolation`.
+ * @returns A Drizzle `pgPolicy` definition.
+ */
+export declare const createRLSPolicy: (tableName: string, columnName?: string, policyName?: string) => import("drizzle-orm/pg-core").PgPolicy;
+/**
+ * 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 `withRLS()`
+ * 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/core",
-	"version": "0.5.4",
+	"version": "0.6.0",
 	"license": "Apache-2.0",
 	"description": "A super-charged web framework for Bun, built on top of ElysiaJS.",
 	"private": false,
@@ -16,6 +16,7 @@
 		"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": [
@@ -28,24 +29,16 @@
 	"module": "dist/index.js",
 	"type": "module",
 	"types": "dist/index.d.ts",
+	"sideEffects": ["./src/index.ts"],
 	"dependencies": {
-		"@elysiajs/swagger": "^1.3.0",
-		"cache-manager": "^6.4.3",
-		"cacheable": "^1.9.0",
-		"drizzle-orm": "^0.44.2",
-		"elysia": "latest",
-		"radash": "^12.1.0",
-		"reflect-metadata": "^0.2.2",
-		"wampy": "^7.1.1"
-	},
-	"devDependencies": {
-		"@ianvs/prettier-plugin-sort-imports": "^4.4.2",
-		"@types/bun": "latest",
-		"rimraf": "^6.0.1",
-		"type-fest": "^4.41.0"
-	},
-	"peerDependencies": {
-		"typescript": "^5.8.3"
+		"@elysiajs/swagger": "^1.3.1",
+		"cache-manager": "^7.2.3",
+		"cacheable": "^2.0.3",
+		"drizzle-orm": "^0.44.6",
+		"elysia": "^1.4.9",
+		"radash": "catalog:",
+		"reflect-metadata": "catalog:",
+		"wampy": "^7.2.0"
 	},
 	"trustedDependencies": [
 		"es5-ext"

package/tsconfig.json

@@ -1,48 +1,12 @@
-// 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.
 {
+	"extends": "../../tsconfig.base.json",
 	"compilerOptions": {
-		// Environment setup & latest features
-		"target": "ESNext",
-		"module": "ESNext",
-		"moduleDetection": "force",
-		"allowJs": true,
-		"types": ["bun-types", "type-fest"],
-		"experimentalDecorators": true,
-		"emitDecoratorMetadata": true,
-		// Compiler setup
 		"outDir": "dist",
 		"declaration": true,
 		"emitDeclarationOnly": true,
 		"declarationMap": false,
 		"declarationDir": "dist",
-		"rootDir": "src",
-		// Bundler mode
-		"moduleResolution": "bundler",
-		"allowImportingTsExtensions": true,
-		"verbatimModuleSyntax": true,
-		// Best practices
-		"strict": true,
-		"skipLibCheck": true,
-		"noFallthroughCasesInSwitch": true,
-		"noUncheckedIndexedAccess": false,
-		"forceConsistentCasingInFileNames": true,
-		// Some stricter flags (disabled by default)
-		"noUnusedLocals": true,
-		"noUnusedParameters": true,
-		"noPropertyAccessFromIndexSignature": false
+		"rootDir": "src"
 	},
-	"exclude": ["node_modules", "dist"],
 	"include": ["src"]
 }

package/dist/macros.d.ts

@@ -1,8 +0,0 @@
-declare global {
-    /**
-     * A macro indicating if the code is running from a build.
-     * @author Axel Nana <axel.nana@workbud.com>
-     */
-    var ELYSIUM_BUILD: boolean;
-}
-export {};