@arikajs/config 0.0.5

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @arikajs/config
+
+## 0.0.5
+
+### Patch Changes
+
+- feat: implement CSRF protection and standardized middleware architecture
+
+  - Added session-based CSRF protection middleware.
+  - Refactored middleware into project-level stubs for better customization.
+  - Standardized auth controller stubs.
+  - Enhanced CLI project scaffolding.
+  - Added session and localization packages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArikaJs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+
+## Arika Config
+
+`@arikajs/config` is a powerful, lightweight, and framework-agnostic configuration management library for Node.js.
+
+It provides a unified way to manage environment variables and application configurations using fluent dot-notation access, type safety, schema validation, and automatic environment loading.
+
+---
+
+## ✨ Features
+
+- **🎯 Dot-notation access**: Access nested configurations easily (e.g., `app.name`)
+- **🚀 O(1) Config Caching**: Flat cache built on boot for maximum performance
+- **🛡️ Schema Validation**: Validate config types, required fields, enums, and patterns before boot
+- **🌍 Environment Integration**: Built-in `.env` file support with intelligent type casting
+- **🔀 Environment Merging**: Auto-load `database.production.js` on top of `database.js`
+- **📡 Change Listeners**: React to config changes in real-time during setup
+- **🧊 Deep Freeze**: Immutable config after boot — no accidental mutations
+- **🔑 Encrypted Values**: Auto-decrypt `enc:` prefixed secrets using `@arikajs/encryption`
+- **🟦 TypeScript-first**: Full type safety and intellisense out of the box
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @arikajs/config
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1️⃣ Basic Usage
+
+```ts
+import { Repository } from '@arikajs/config';
+
+const config = new Repository({
+    app: {
+        name: 'ArikaJS',
+        env: 'production'
+    },
+    database: {
+        connection: 'mysql',
+        port: 3306
+    }
+});
+
+// Access values using dot-notation
+const appName = config.get('app.name'); // 'ArikaJS'
+const dbPort = config.get('database.port', 5432); // 3306
+```
+
+### 2️⃣ Environment Variables
+
+```ts
+import { env } from '@arikajs/config';
+
+// Automatically casts 'true'/'false' strings to booleans
+const debug = env('APP_DEBUG', false); 
+
+// Automatically casts 'null' string to null type
+const key = env('APP_KEY');
+```
+
+---
+
+## 🚀 O(1) Config Caching (Feature 1)
+
+When `markAsBooted()` is called, the entire nested config tree is flattened into a `Map<string, any>`. All subsequent `get()` calls use this flat cache for **O(1)** lookup instead of traversing the object tree.
+
+```ts
+const config = new Repository({ app: { name: 'Arika' } });
+
+// Pre-boot: walks nested objects (O(depth))
+config.get('app.name');
+
+config.markAsBooted();
+
+// Post-boot: instant Map lookup (O(1))
+config.get('app.name'); // ⚡ Blazing fast
+```
+
+This makes a measurable difference in high-traffic applications where `config.get()` is called thousands of times per second.
+
+---
+
+## 🛡️ Schema Validation (Feature 2)
+
+Define a schema to validate your config before boot. If validation fails, the app crashes immediately with clear error messages — not deep inside a service.
+
+```ts
+config.defineSchema({
+    'app.name': { type: 'string', required: true },
+    'app.env': { 
+        type: 'string', 
+        enum: ['development', 'production', 'testing'] 
+    },
+    'app.key': { 
+        type: 'string', 
+        required: true, 
+        min: 32,
+        pattern: /^base64:[A-Za-z0-9+/=]+$/,
+        message: 'APP_KEY must be a valid base64 string of at least 32 characters.'
+    },
+    'server.port': { type: 'number', min: 1, max: 65535 },
+});
+
+// This will throw if validation fails
+config.markAsBooted();
+```
+
+### Supported Validation Rules
+
+| Rule | Description |
+| :--- | :--- |
+| `type` | `'string'`, `'number'`, `'boolean'`, `'object'`, `'array'` |
+| `required` | Fail if value is `undefined` or `null` |
+| `enum` | Value must be one of the listed options |
+| `min` / `max` | For numbers: value range. For strings: character length |
+| `pattern` | RegExp that strings must match |
+| `message` | Custom error message |
+| `children` | Nested schema for objects |
+
+---
+
+## 🔀 Environment Merging (Feature 3)
+
+Automatically load environment-specific config overrides without any manual `env()` calls.
+
+```
+config/
+├── database.js          # Base config (loaded first)
+├── database.production.js  # Production overrides (deep-merged on top)
+├── database.testing.js     # Testing overrides
+└── app.js
+```
+
+```ts
+config.loadConfigDirectory('./config');
+// If NODE_ENV=production:
+//   1. Loads database.js
+//   2. Deep-merges database.production.js on top
+```
+
+Supported environment suffixes: `.development.`, `.production.`, `.staging.`, `.testing.`, `.local.`
+
+---
+
+## 📡 Change Listeners (Feature 4)
+
+React to config changes in real-time during the setup phase.
+
+```ts
+// Listen to a specific key
+config.onChange('database.host', (key, newValue, oldValue) => {
+    console.log(`Database host changed from ${oldValue} to ${newValue}`);
+});
+
+// Listen to any child of a parent key
+config.onChange('database', (key, newValue, oldValue) => {
+    console.log(`Database config changed: ${key}`);
+});
+
+// Listen to ALL changes globally
+config.onAnyChange((key, newValue, oldValue) => {
+    console.log(`Config changed: ${key} = ${newValue}`);
+});
+```
+
+---
+
+## 🧊 Deep Freeze (Feature 5)
+
+After boot, the entire config tree is recursively frozen using `Object.freeze()`. Any accidental mutation will throw an error in strict mode.
+
+```ts
+config.markAsBooted();
+
+const db = config.get('database');
+db.host = 'hacked'; // ❌ TypeError: Cannot assign to read only property
+```
+
+This prevents subtle bugs where a service accidentally mutates shared config objects.
+
+---
+
+## 🔑 Encrypted Config Values (Feature 6)
+
+Store sensitive values as encrypted strings prefixed with `enc:`. They are automatically decrypted when accessed via `get()`.
+
+```ts
+const config = new Repository({
+    secrets: {
+        api_key: 'enc:aGVsbG8td29ybGQ=',
+        db_password: 'enc:c2VjcmV0LXBhc3N3b3Jk'
+    }
+});
+
+// Set a decrypter (e.g., using @arikajs/encryption)
+config.setDecrypter((encrypted) => {
+    return Encrypter.decrypt(encrypted);
+});
+
+config.get('secrets.api_key'); // Returns decrypted value
+```
+
+This works both before and after boot, and integrates seamlessly with `@arikajs/encryption`.
+
+---
+
+## 📅 Advanced Usage
+
+### Loading from a Directory
+```ts
+config.loadConfigDirectory(path.join(__dirname, 'config'));
+```
+
+### Global Helpers
+```ts
+import { config, env } from '@arikajs/config';
+
+const timezone = config('app.timezone', 'UTC');
+const debug = env('APP_DEBUG', false);
+```
+
+---
+
+## 🏗 Architecture
+
+```text
+config/
+├── src/
+│   ├── EnvLoader.ts
+│   ├── helpers.ts
+│   ├── index.ts
+│   └── Repository.ts
+├── tests/
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 📄 License
+
+`@arikajs/config` is open-source software licensed under the **MIT License**.
+
+---
+
+## 🧭 Philosophy
+
+> "Configuration should be simple to define and impossible to break."

package/dist/EnvLoader.d.ts

@@ -0,0 +1,10 @@
+export declare class EnvLoader {
+    /**
+     * Load environment variables from the given path.
+     */
+    static load(basePath: string): void;
+    /**
+     * Get an environment variable with intelligent type casting.
+     */
+    static get<T = any>(key: string, defaultValue?: T): T;
+}

package/dist/EnvLoader.js

@@ -0,0 +1,44 @@
+import * as dotenv from 'dotenv';
+import * as fs from 'fs';
+import * as path from 'path';
+export class EnvLoader {
+    /**
+     * Load environment variables from the given path.
+     */
+    static load(basePath) {
+        const envPath = path.join(basePath, '.env');
+        if (fs.existsSync(envPath)) {
+            dotenv.config({ path: envPath, override: true });
+        }
+        // Load .env.example if .env doesn't exist (optional, mostly for local dev)
+        const examplePath = path.join(basePath, '.env.example');
+        if (!fs.existsSync(envPath) && fs.existsSync(examplePath)) {
+            dotenv.config({ path: examplePath, override: true });
+        }
+    }
+    /**
+     * Get an environment variable with intelligent type casting.
+     */
+    static get(key, defaultValue) {
+        const value = process.env[key];
+        if (value === undefined) {
+            return defaultValue;
+        }
+        switch (value.toLowerCase()) {
+            case 'true':
+            case '(true)':
+                return true;
+            case 'false':
+            case '(false)':
+                return false;
+            case 'empty':
+            case '(empty)':
+                return '';
+            case 'null':
+            case '(null)':
+                return null;
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=EnvLoader.js.map

package/dist/EnvLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvLoader.js","sourceRoot":"","sources":["../src/EnvLoader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,OAAO,SAAS;IAClB;;OAEG;IACI,MAAM,CAAC,IAAI,CAAC,QAAgB;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE5C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;QAED,2EAA2E;QAC3E,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QACxD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;IACL,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,GAAG,CAAU,GAAW,EAAE,YAAgB;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,YAAiB,CAAC;QAC7B,CAAC;QAED,QAAQ,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YAC1B,KAAK,MAAM,CAAC;YACZ,KAAK,QAAQ;gBACT,OAAO,IAAW,CAAC;YACvB,KAAK,OAAO,CAAC;YACb,KAAK,SAAS;gBACV,OAAO,KAAY,CAAC;YACxB,KAAK,OAAO,CAAC;YACb,KAAK,SAAS;gBACV,OAAO,EAAS,CAAC;YACrB,KAAK,MAAM,CAAC;YACZ,KAAK,QAAQ;gBACT,OAAO,IAAW,CAAC;QAC3B,CAAC;QAED,OAAO,KAAY,CAAC;IACxB,CAAC;CACJ"}

package/dist/Repository.d.ts

@@ -0,0 +1,96 @@
+export type SchemaRule = {
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required?: boolean;
+    default?: any;
+    enum?: any[];
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+    message?: string;
+    children?: Record<string, SchemaRule>;
+};
+export type ConfigSchema = Record<string, SchemaRule | Record<string, SchemaRule>>;
+export interface ValidationError {
+    key: string;
+    message: string;
+}
+export type ConfigChangeListener = (key: string, newValue: any, oldValue: any) => void;
+export declare class Repository {
+    private config;
+    private booted;
+    private flatCache;
+    private cacheBuilt;
+    private schema;
+    private listeners;
+    private globalListeners;
+    private decrypter;
+    constructor(initialConfig?: Record<string, any>);
+    /**
+     * Load configuration files from the config directory.
+     */
+    loadConfigDirectory(configPath: string, environment?: string): void;
+    private isConfigFile;
+    private isEnvSpecificFile;
+    private loadFile;
+    /**
+     * Get a configuration value using dot notation.
+     * Uses flat cache for O(1) lookup when booted.
+     */
+    get<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * Check if a configuration key exists.
+     */
+    has(key: string): boolean;
+    /**
+     * Set a configuration value using dot notation.
+     */
+    set(key: string, value: any): void;
+    /**
+     * Get all configuration.
+     */
+    all(): Record<string, any>;
+    /**
+     * Mark the repository as booted (read-only).
+     * Builds the flat cache and deep-freezes the config for immutability.
+     */
+    markAsBooted(): void;
+    /**
+     * Check if the repository has been booted.
+     */
+    isBooted(): boolean;
+    /**
+     * Build a flat Map of all dot-notation keys for O(1) lookups.
+     */
+    private buildFlatCache;
+    /**
+     * Define a validation schema for the configuration.
+     */
+    defineSchema(schema: ConfigSchema): this;
+    /**
+     * Validate the current config against the defined schema.
+     */
+    validate(): ValidationError[];
+    private validateSchema;
+    /**
+     * Register a listener for changes to a specific config key.
+     */
+    onChange(key: string, listener: ConfigChangeListener): this;
+    /**
+     * Register a global listener for ALL config changes.
+     */
+    onAnyChange(listener: ConfigChangeListener): this;
+    private notifyListeners;
+    /**
+     * Recursively freeze an object to prevent any mutations.
+     */
+    private deepFreeze;
+    /**
+     * Set a decrypter function for auto-decrypting `enc:` prefixed values.
+     */
+    setDecrypter(fn: (encryptedValue: string) => string): this;
+    private decrypt;
+    /**
+     * Deep merge two objects. Source values override target values.
+     */
+    private deepMerge;
+}