@africode/core 5.0.0

package/core/config.js

@@ -0,0 +1,263 @@
+/**
+ * AfriCode Framework Configuration
+ *
+ * Centralized configuration for the entire framework.
+ * Provides createFramework() as the entry point for apps.
+ *
+ * Design:
+ * - Single config object controls all framework behavior
+ * - Defaults are strict and secure
+ * - Every opt-in behavior is explicit
+ * - Observability hooks are first-class
+ *
+ * @module core/config
+ */
+
+/**
+ * @typedef {Object} AfriCodeConfig
+ *
+ * @property {Object} [validation] - Validation configuration
+ * @property {boolean} [validation.trimStrings=false] - Trim whitespace from string inputs
+ * @property {boolean} [validation.emptyAsNullDefault=false] - Convert "" → null for nullable fields (NOT recommended)
+ *
+ * @property {Object} [security] - Security configuration
+ * @property {Object} [security.csrf] - CSRF configuration
+ * @property {boolean} [security.csrf.enabled=true] - Enable CSRF protection
+ * @property {string[]} [security.csrf.excludePaths=[]] - Paths to exclude from CSRF
+ * @property {string} [security.csrf.sameSite='Strict'] - SameSite cookie policy
+ * @property {boolean} [security.csrf.secure=false] - Require HTTPS for cookies
+ * @property {Object} [security.rateLimit] - Rate limit configuration
+ * @property {boolean} [security.rateLimit.enabled=true] - Enable rate limiting
+ * @property {number} [security.rateLimit.windowMs=60000] - Window in milliseconds
+ * @property {number} [security.rateLimit.maxRequests=60] - Max requests per window
+ * @property {string[]} [security.rateLimit.excludePaths=[]] - Paths to exclude
+ *
+ * @property {Object} [hooks] - Observability hooks
+ * @property {Function} [hooks.onValidationError] - Called on validation failure
+ * @property {Function} [hooks.onSecurityViolation] - Called on CSRF/security failure
+ * @property {Function} [hooks.onRateLimit] - Called when rate limit is hit
+ * @property {Function} [hooks.onDatabaseError] - Called on database error
+ * @property {Function} [hooks.onRequest] - Called on every incoming request
+ */
+
+/**
+ * Default configuration values.
+ * Strict by default. Secure by default.
+ */
+const DEFAULT_CONFIG = {
+  validation: {
+    trimStrings: false,
+    emptyAsNullDefault: false
+  },
+  security: {
+    csrf: {
+      enabled: true,
+      excludePaths: [],
+      sameSite: 'Strict',
+      secure: false
+    },
+    rateLimit: {
+      enabled: true,
+      windowMs: 60 * 1000,
+      maxRequests: 60,
+      excludePaths: []
+    }
+  },
+  hooks: {
+    onValidationError: null,
+    onSecurityViolation: null,
+    onRateLimit: null,
+    onDatabaseError: null,
+    onRequest: null
+  }
+};
+
+/** @type {AfriCodeConfig} */
+let _config = deepClone(DEFAULT_CONFIG);
+
+/** @type {boolean} */
+let _initialized = false;
+
+/**
+ * Deep clone a plain object.
+ * @param {Object} obj
+ * @returns {Object}
+ */
+function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') {return obj;}
+  if (Array.isArray(obj)) {return obj.map(deepClone);}
+  const cloned = {};
+  for (const key of Object.keys(obj)) {
+    cloned[key] = deepClone(obj[key]);
+  }
+  return cloned;
+}
+
+/**
+ * Deep merge source into target.
+ * @param {Object} target
+ * @param {Object} source
+ * @returns {Object}
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] !== null &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key] || {}, source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Initialize the AfriCode framework with configuration.
+ *
+ * This is the single entry point for framework configuration.
+ * Call once at app startup. All systems read from this config.
+ *
+ * @param {Partial<AfriCodeConfig>} [userConfig={}] - User overrides
+ * @returns {AfriCodeConfig} The resolved configuration
+ *
+ * @example
+ * import { createFramework } from 'africode/core/config';
+ *
+ * createFramework({
+ *   validation: {
+ *     trimStrings: true
+ *   },
+ *   security: {
+ *     csrf: { enabled: true, secure: true },
+ *     rateLimit: { maxRequests: 100 }
+ *   },
+ *   hooks: {
+ *     onValidationError: (error) => logger.warn('Validation:', error),
+ *     onSecurityViolation: (error) => logger.error('Security:', error),
+ *     onRateLimit: (key) => metrics.increment('rate_limit_hit')
+ *   }
+ * });
+ */
+export function createFramework(userConfig = {}) {
+  _config = deepMerge(DEFAULT_CONFIG, userConfig);
+  _initialized = true;
+  return getConfig();
+}
+
+/**
+ * Get the current framework configuration.
+ * Returns a frozen copy to prevent accidental mutation.
+ *
+ * @returns {AfriCodeConfig}
+ */
+export function getConfig() {
+  return Object.freeze(deepClone(_config));
+}
+
+/**
+ * Check if the framework has been initialized.
+ * @returns {boolean}
+ */
+export function isInitialized() {
+  return _initialized;
+}
+
+/**
+ * Reset configuration to defaults.
+ * Primarily for testing.
+ */
+export function resetConfig() {
+  _config = deepClone(DEFAULT_CONFIG);
+  _initialized = false;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Observability Hooks — fire-and-forget event emitters
+//
+// These are framework-level hooks for monitoring and logging.
+// They never throw — errors in hooks are caught and logged.
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Emit a validation error event.
+ * @param {import('./errors.js').ValidationError} error
+ */
+export function emitValidationError(error) {
+  const hook = _config.hooks?.onValidationError;
+  if (typeof hook === 'function') {
+    try { hook(error); } catch (e) {
+      console.error('[AfriCode] Hook error in onValidationError:', e);
+    }
+  }
+}
+
+/**
+ * Emit a security violation event.
+ * @param {import('./errors.js').SecurityError} error
+ */
+export function emitSecurityViolation(error) {
+  const hook = _config.hooks?.onSecurityViolation;
+  if (typeof hook === 'function') {
+    try { hook(error); } catch (e) {
+      console.error('[AfriCode] Hook error in onSecurityViolation:', e);
+    }
+  }
+}
+
+/**
+ * Emit a rate limit event.
+ * @param {string} key - The client identifier that was rate limited
+ * @param {Request} [request] - The request that triggered the limit
+ */
+export function emitRateLimit(key, request = null) {
+  const hook = _config.hooks?.onRateLimit;
+  if (typeof hook === 'function') {
+    try { hook(key, request); } catch (e) {
+      console.error('[AfriCode] Hook error in onRateLimit:', e);
+    }
+  }
+}
+
+/**
+ * Emit a database error event.
+ * @param {import('./errors.js').DatabaseError} error
+ */
+export function emitDatabaseError(error) {
+  const hook = _config.hooks?.onDatabaseError;
+  if (typeof hook === 'function') {
+    try { hook(error); } catch (e) {
+      console.error('[AfriCode] Hook error in onDatabaseError:', e);
+    }
+  }
+}
+
+/**
+ * Emit a request event.
+ * @param {Request} request
+ */
+export function emitRequest(request) {
+  const hook = _config.hooks?.onRequest;
+  if (typeof hook === 'function') {
+    try { hook(request); } catch (e) {
+      console.error('[AfriCode] Hook error in onRequest:', e);
+    }
+  }
+}
+
+export default {
+  createFramework,
+  getConfig,
+  isInitialized,
+  resetConfig,
+  emitValidationError,
+  emitSecurityViolation,
+  emitRateLimit,
+  emitDatabaseError,
+  emitRequest
+};