@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/types/application/bootstrap.d.ts

@@ -0,0 +1,484 @@
+import { IWebServer, IWebServerPublic } from "@expressots/shared";
+/**
+ * Common environment names used in ExpressoTS applications.
+ * @public API
+ */
+export type EnvironmentName = "development" | "production" | "staging" | "test" | "local" | (string & NonNullable<unknown>);
+/**
+ * Mapping of environment names to their corresponding .env file names.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   development: ".env.dev",
+ *   production: ".env.prod",
+ *   staging: ".env.staging"
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface EnvironmentFileMap {
+    /** Environment name → .env file name mapping */
+    [environmentName: string]: string;
+}
+/**
+ * Configuration for environment file loading, validation, and auto-creation.
+ *
+ * @layer public
+ * @audience application-developers
+ *
+ * **Opt-in Feature**: If not provided, .env file loading is skipped entirely.
+ *
+ * @public API
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - auto-create template
+ * envFileConfig: {
+ *   autoCreateTemplate: true,
+ *   required: ["DATABASE_URL"]
+ * }
+ *
+ * // Production-ready with validation
+ * envFileConfig: {
+ *   files: {
+ *     development: ".env.dev",
+ *     production: ".env.prod"
+ *   },
+ *   required: ["DATABASE_URL", "JWT_SECRET"],
+ *   validateValues: true
+ * }
+ * ```
+ */
+export interface EnvironmentFileConfig {
+    /**
+     * Custom mapping of environment names to .env file names.
+     *
+     * @default `.env.{currentEnvironment}` (convention-based)
+     *
+     * **Runtime behavior:** Only the file for the CURRENT environment (from `currentEnvironment`)
+     * will be loaded at runtime. The mapping allows you to use custom file names.
+     *
+     * **Template creation:** If `autoCreateTemplate: true` and `files` mapping is provided,
+     * templates will be created for ALL mapped environments, not just the current one.
+     * This helps set up your project with all necessary .env files upfront.
+     *
+     * @example
+     * ```typescript
+     * // Runtime: When currentEnvironment="development", loads ".env.dev"
+     * // Template creation: If autoCreateTemplate: true, creates BOTH .env.dev AND .env.prod
+     * files: {
+     *   development: ".env.dev",
+     *   production: ".env.prod",
+     *   staging: ".env.staging"
+     * }
+     * ```
+     *
+     * **Default behavior:** If not provided, uses convention: `.env.{currentEnvironment}`
+     * - `currentEnvironment="development"` → loads `.env.development`
+     * - `currentEnvironment="production"` → loads `.env.production`
+     */
+    files?: EnvironmentFileMap;
+    /**
+     * Validate that the required .env file exists.
+     *
+     * @default `true` locally, `false` in CI
+     *
+     * **Behavior:**
+     * - `true`: Throws `EnvFileNotFoundError` if file is missing
+     * - `false`: Silently skips missing files (logs warning)
+     *
+     * @example
+     * ```typescript
+     * // Strict validation (recommended for production)
+     * validateFile: true
+     *
+     * // Lenient (allow missing files)
+     * validateFile: false
+     * ```
+     */
+    validateFile?: boolean;
+    /**
+     * Validate that all variables in the .env file have non-empty values.
+     *
+     * @default `true` in production/CI, `false` in development
+     *
+     * **Behavior:**
+     * - `true`: Throws `EnvValidationError` if any variable is empty
+     * - `false`: Allows empty values (except `required` array)
+     *
+     * **Note:** Variables in `required` array are always validated, regardless of this setting.
+     *
+     * @example
+     * ```typescript
+     * // Strict validation (production)
+     * validateValues: true
+     *
+     * // Lenient (development)
+     * validateValues: false
+     * ```
+     */
+    validateValues?: boolean;
+    /**
+     * Auto-create template .env file if missing.
+     *
+     * @default `false` (opt-in behavior)
+     *
+     * **Important:** File creation only happens if `envFileConfig` is provided.
+     * Set to `true` to enable auto-creation of template files.
+     *
+     * **Template creation behavior:**
+     * - If `files` mapping provided: Creates templates for ALL mapped environments
+     * - Otherwise: Creates template for current environment only
+     *
+     * **Template content:**
+     * - `PORT=3000`
+     * - `NODE_ENV={currentEnvironment}` (e.g., "development", "production")
+     * - Required variables (from `required` array) as empty placeholders
+     *
+     * @example
+     * ```typescript
+     * // Opt-in to .env file loading and auto-creation
+     * envFileConfig: {
+     *   autoCreateTemplate: true  // Explicitly enable
+     * }
+     * ```
+     */
+    autoCreateTemplate?: boolean;
+    /**
+     * Required environment variable names that must exist and have non-empty values.
+     *
+     * @default `[]` (no required variables)
+     *
+     * **Validation behavior:**
+     * - These are **always validated**, even if `validateValues` is `false`
+     * - Validated from `process.env` in CI mode
+     * - Validated from .env file in local mode
+     * - When auto-creating templates, these variables are added as empty placeholders
+     *
+     * @example
+     * ```typescript
+     * required: ["DATABASE_URL", "API_KEY", "JWT_SECRET"]
+     * ```
+     *
+     * Creates template with:
+     * ```
+     * PORT=3000
+     * NODE_ENV=development
+     * DATABASE_URL=
+     * API_KEY=
+     * JWT_SECRET=
+     * ```
+     */
+    required?: ReadonlyArray<string>;
+    /**
+     * Force CI/CD mode (auto-detected if not set).
+     *
+     * @default Auto-detected from `process.env.CI`, `GITHUB_ACTIONS`, etc.
+     *
+     * **When `true`:**
+     * - Skips .env file loading
+     * - Validates variables from `process.env` only
+     * - Never creates template files
+     * - Provides platform-specific error hints
+     *
+     * **Use case:** Explicitly force CI mode when auto-detection fails
+     *
+     * @example
+     * ```typescript
+     * // Explicit CI mode
+     * ciMode: true
+     * ```
+     */
+    ciMode?: boolean;
+    /**
+     * Skip .env file loading entirely (useful for CI/CD and containers).
+     *
+     * @default `false`
+     *
+     * **When `true`:**
+     * - Only uses `process.env` variables
+     * - Ignores all .env files
+     * - Still validates required variables from `process.env`
+     *
+     * **Use cases:**
+     * - Docker/Kubernetes deployments (variables from ConfigMaps/Secrets)
+     * - CI/CD pipelines (variables from platform secrets)
+     * - Testing with mock environment variables
+     *
+     * @example
+     * ```typescript
+     * // Containerized deployment
+     * skipFileLoading: true
+     * ```
+     */
+    skipFileLoading?: boolean;
+}
+/**
+ * Options for loadEnvSync().
+ * @public API
+ */
+export interface LoadEnvSyncOptions {
+    /**
+     * Custom mapping of environment names to .env file names.
+     * @default Uses convention: `.env.{currentEnvironment}`
+     */
+    files?: EnvironmentFileMap;
+    /**
+     * Force reload even if already loaded.
+     * Useful for hot reload scenarios.
+     * @default false
+     */
+    force?: boolean;
+}
+/**
+ * Synchronously load .env files BEFORE defineConfig() resolves.
+ *
+ * Call this at the top of your config file to ensure environment variables
+ * are available when defineConfig() runs.
+ *
+ * @param options - Environment file configuration
+ *
+ * @example
+ * ```typescript
+ * // config.ts
+ * import { defineConfig, Env, loadEnvSync } from "@expressots/core";
+ *
+ * // Load .env files first
+ * loadEnvSync({
+ *   files: {
+ *     development: ".env.dev",
+ *     production: ".env.prod",
+ *   },
+ * });
+ *
+ * // Now defineConfig() will read from loaded .env files
+ * export const appConfig = defineConfig({
+ *   server: {
+ *     port: Env.port("PORT", { default: 3000 }),
+ *   },
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare function loadEnvSync(options?: LoadEnvSyncOptions): void;
+/**
+ * Config object shape that can be passed directly to bootstrap().
+ * This allows config objects from defineConfig() to be used directly.
+ *
+ * The config object must have at least the required properties (app.name, app.version,
+ * app.environment, server.port), but can have additional properties (like logging,
+ * server.host, etc.) which will be ignored.
+ *
+ * @layer public
+ * @audience application-developers
+ *
+ * @example
+ * ```typescript
+ * const config = defineConfig({
+ *   app: {
+ *     name: Env.string("APP_NAME", { default: "My App" }),
+ *     version: Env.string("APP_VERSION", { default: "1.0.0" }),
+ *     environment: Env.enum("NODE_ENV", ["development", "production"])
+ *   },
+ *   server: {
+ *     port: Env.port("PORT", { default: 3000 })
+ *   },
+ *   bootstrap: {
+ *     envFileConfig: {
+ *       autoCreateTemplate: true,
+ *       files: {
+ *         development: ".env.dev",
+ *         production: ".env.prod"
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Pass config directly to bootstrap - extra properties are ignored!
+ * bootstrap(App, config.values);
+ * ```
+ *
+ * @public API
+ */
+export type BootstrapConfig = {
+    /**
+     * Application metadata (required).
+     */
+    app: {
+        /** Application name */
+        name: string;
+        /** Application version */
+        version: string;
+        /** Current environment */
+        environment: EnvironmentName;
+    };
+    /**
+     * Server configuration (required).
+     */
+    server: {
+        /** Server port */
+        port: number;
+        [key: string]: unknown;
+    };
+    /**
+     * Bootstrap-specific configuration (optional).
+     */
+    bootstrap?: {
+        /** Environment file configuration */
+        envFileConfig?: EnvironmentFileConfig;
+    };
+    [key: string]: unknown;
+};
+/**
+ * Bootstrap options for application startup.
+ *
+ * @layer public
+ * @audience application-developers
+ *
+ * @public API
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage - uses defaults
+ * bootstrap(App);
+ *
+ * // Custom environment and file mapping
+ * bootstrap(App, {
+ *   currentEnvironment: "development",
+ *   envFileConfig: {
+ *     files: {
+ *       development: ".env.dev",
+ *       production: ".env.prod"
+ *     },
+ *     required: ["DATABASE_URL", "API_KEY"]
+ *   }
+ * });
+ *
+ * // Custom port and app info
+ * bootstrap(App, {
+ *   port: 8080,
+ *   appName: "My API",
+ *   appVersion: "1.0.0",
+ *   currentEnvironment: "production"
+ * });
+ * ```
+ */
+export interface BootstrapOptions {
+    /**
+     * Port to listen on.
+     *
+     * @default process.env.PORT ?? 3000
+     * @smart-behavior
+     * - Use `0` for OS-assigned port (testing)
+     * - Reads PORT from .env if envFileConfig provided
+     *
+     * **Priority Chain**:
+     * 1. options.port (highest)
+     * 2. process.env.PORT
+     * 3. 3000 (fallback)
+     *
+     * @example
+     * ```typescript
+     * // Explicit port
+     * { port: 8080 }
+     *
+     * // From .env (if envFileConfig provided)
+     * envFileConfig: { ... } // Reads PORT from .env
+     *
+     * // Testing (OS-assigned)
+     * { port: 0 } // Auto-assign available port
+     * ```
+     */
+    port?: number;
+    /**
+     * Override application name (defaults to `package.json` name).
+     *
+     * @default package.json name ?? "ExpressoTS App"
+     *
+     * Used in startup banner and logs.
+     *
+     * @example
+     * ```typescript
+     * { appName: "My Production API" }
+     * ```
+     */
+    appName?: string;
+    /**
+     * Override application version (defaults to `package.json` version).
+     *
+     * @default package.json version ?? "1.0.0"
+     *
+     * Used in startup banner and logs.
+     *
+     * @example
+     * ```typescript
+     * { appVersion: "2.0.0" }
+     * ```
+     */
+    appVersion?: string;
+    /**
+     * Current environment name (defaults to `process.env.NODE_ENV` or `"development"`).
+     *
+     * @default process.env.NODE_ENV ?? "development"
+     *
+     * **This determines which .env file to load:**
+     * - If `envFileConfig.files` is provided, uses the mapping
+     * - Otherwise, uses convention: `.env.{currentEnvironment}`
+     *
+     * **Only ONE file is loaded** - the file corresponding to this environment.
+     *
+     * @example
+     * ```typescript
+     * // Loads .env.development (or .env.dev if mapped)
+     * currentEnvironment: "development"
+     *
+     * // Loads .env.production (or .env.prod if mapped)
+     * currentEnvironment: "production"
+     * ```
+     */
+    currentEnvironment?: EnvironmentName;
+    /**
+     * Environment file loading and validation configuration.
+     *
+     * **Important:** This is an opt-in feature. If not provided, .env file loading is skipped.
+     * Templates can configure this to enable .env file support for their projects.
+     *
+     * Controls how .env files are loaded, validated, and auto-created.
+     *
+     * @default undefined (skips .env file loading)
+     *
+     * @example
+     * ```typescript
+     * // Opt-in to .env file loading
+     * envFileConfig: {
+     *   // Custom file names per environment
+     *   files: {
+     *     development: ".env.dev",
+     *     production: ".env.prod"
+     *   },
+     *   // Required variables (always validated)
+     *   required: ["DATABASE_URL", "API_KEY"],
+     *   // Auto-create missing files (explicit opt-in)
+     *   autoCreateTemplate: true
+     * }
+     * ```
+     *
+     * @see {@link EnvironmentFileConfig} for detailed configuration options
+     */
+    envFileConfig?: EnvironmentFileConfig;
+}
+/**
+ * Bootstrap with BootstrapOptions (existing behavior).
+ */
+export declare function bootstrap(AppClass: new () => IWebServer, options: BootstrapOptions): Promise<IWebServerPublic>;
+/**
+ * Bootstrap with config object (new convenience overload).
+ */
+export declare function bootstrap(AppClass: new () => IWebServer, config: BootstrapConfig): Promise<IWebServerPublic>;
+/**
+ * Bootstrap with no options (zero-config).
+ */
+export declare function bootstrap(AppClass: new () => IWebServer): Promise<IWebServerPublic>;

package/lib/cjs/types/application/index.d.ts

@@ -1,3 +1,4 @@
-export { AppContainer } from "./application-container";
-export { AppFactory } from "./application-factory";
-export { ServerEnvironment } from "./application.types";
+export { AppContainer } from "./application-container.js";
+export { AppFactory } from "./application-factory.js";
+export { ServerEnvironment } from "./application.types.js";
+export { bootstrap, BootstrapOptions, BootstrapConfig, EnvironmentName, EnvironmentFileMap, EnvironmentFileConfig, loadEnvSync, LoadEnvSyncOptions, } from "./bootstrap.js";

package/lib/cjs/types/authorization/authorization-config.interface.d.ts

@@ -0,0 +1,45 @@
+import { Request } from "express";
+/**
+ * Configuration for authorization system
+ */
+export interface AuthorizationConfig {
+    /**
+     * Enable permission preloading middleware (default: true)
+     */
+    enablePreloading?: boolean;
+    /**
+     * Enable guard result caching (default: true)
+     */
+    enableCaching?: boolean;
+    /**
+     * Permission hierarchy configuration
+     * Maps roles to their inherited roles/permissions
+     *
+     * @example
+     * ```typescript
+     * {
+     *   "super-admin": ["admin", "moderator", "user"],
+     *   "admin": ["moderator", "user"],
+     *   "moderator": ["user"]
+     * }
+     * ```
+     */
+    permissionHierarchy?: Record<string, Array<string>>;
+    /**
+     * Custom scope extractors
+     */
+    scopeExtractors?: {
+        /**
+         * Custom tenant extractor
+         */
+        tenant?: (req: Request) => string | undefined;
+        /**
+         * Custom session extractor
+         */
+        session?: (req: Request) => string | undefined;
+    };
+    /**
+     * Default guard priority (default: 100)
+     */
+    defaultGuardPriority?: number;
+}

package/lib/cjs/types/authorization/decorators/convenience.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shorthand decorator for requiring authentication
+ * Equivalent to @UseGuards(RequireAuth())
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/users")
+ * export class UserController {
+ *   @Get("/profile")
+ *   @RequireAuthentication()
+ *   getProfile(@principal() principal: Principal) {
+ *     return principal.details;
+ *   }
+ * }
+ * ```
+ */
+export declare function RequireAuthentication(): MethodDecorator & ClassDecorator;
+/**
+ * Shorthand decorator for requiring specific roles
+ * Equivalent to @UseGuards(RequireRole(...roles))
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/admin")
+ * export class AdminController {
+ *   @Get("/users")
+ *   @RequireRoles("admin")
+ *   getUsers() {}
+ * }
+ * ```
+ */
+export declare function RequireRoles(...roles: Array<string>): MethodDecorator & ClassDecorator;
+/**
+ * Shorthand decorator for requiring specific permissions
+ * Equivalent to @UseGuards(RequirePermission(...permissions))
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/documents")
+ * export class DocumentController {
+ *   @Get("/")
+ *   @RequirePermissions("documents:read")
+ *   listDocuments() {}
+ * }
+ * ```
+ */
+export declare function RequirePermissions(...permissions: Array<string>): MethodDecorator & ClassDecorator;
+/**
+ * Shorthand decorator for requiring resource ownership
+ * Equivalent to @UseGuards(RequireResourceOwner(paramName))
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/documents")
+ * export class DocumentController {
+ *   @Delete("/:id")
+ *   @RequireOwnership("id")
+ *   deleteDocument(@param("id") id: string) {
+ *     // Only resource owner can delete
+ *   }
+ * }
+ * ```
+ */
+export declare function RequireOwnership(paramName?: string): MethodDecorator;

package/lib/cjs/types/authorization/guard-constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Metadata keys for guard system
+ * These are used by the guard decorators and registry
+ */
+export declare const GUARD_METADATA_KEY: {
+    guard: string;
+    controllerGuards: string;
+    methodGuards: string;
+};