@jadermme/orus-core
Version:
ORUS Core Framework - Universal framework for 6 Pillars assessment, domain-agnostic
255 lines • 6.38 kB
TypeScript
/**
* ORUS Core - Configuration System
*
* Centralized configuration for customizing ORUS Core behavior.
* Allows verticals and shells to override defaults without modifying the core.
*
* @remarks
* Configuration hierarchy:
* 1. ORUS Core defaults (universal, domain-agnostic)
* 2. Vertical configuration (e.g., Finance overrides)
* 3. Shell configuration (e.g., Convexa360 branding)
* 4. Runtime configuration (user preferences)
*/
import type { PillarId } from '../types/pillar.js';
import type { PrioritizationWeights } from '../engine/prioritization.js';
import type { VerticalSchema } from '../validation/dataCompleteness.js';
import { DEFAULT_STATUS_THRESHOLDS } from './defaults.js';
/**
* ORUS Core configuration
*
* @remarks
* All fields are optional - defaults will be used if not provided.
* This allows partial configuration (override only what you need).
*/
export interface OrusCoreConfig {
/**
* Custom pillar labels
*
* @remarks
* **MUST be overridden by verticals/shells.**
* Core provides placeholder labels only.
*
* @example
* ```typescript
* // Finance vertical
* pillarLabels: {
* [PillarId.PILLAR_1]: "Organização & Fluxo",
* [PillarId.PILLAR_2]: "Proteção & Emergências",
* // ...
* }
* ```
*/
pillarLabels?: Record<PillarId, string>;
/**
* Status thresholds
*
* @remarks
* Override if your vertical has different health criteria.
*
* @default
* - critical: [0, 3.9]
* - attention: [4.0, 6.9]
* - healthy: [7.0, 10]
*/
statusThresholds?: typeof DEFAULT_STATUS_THRESHOLDS;
/**
* Prioritization weights
*
* @remarks
* Adjust to change how pillars are prioritized.
*
* @default
* - status: 0.40
* - score: 0.30
* - trend: 0.20
* - confidence: 0.10
*/
prioritizationWeights?: PrioritizationWeights;
/**
* Vertical schema for data completeness
*
* @remarks
* Define required fields for your vertical.
*/
verticalSchema?: VerticalSchema;
/**
* Vertical/Shell identification
*
* @remarks
* For debugging and telemetry.
*
* @example
* ```typescript
* vertical: {
* name: "ORUS Finance",
* version: "1.0.0",
* shell: "Convexa360"
* }
* ```
*/
vertical?: {
name: string;
version: string;
shell?: string;
};
/**
* Enable debug mode
*
* @remarks
* Adds extra logging and validation.
* Should be false in production.
*
* @default false
*/
debug?: boolean;
}
/**
* Resolved configuration type (all fields present)
*/
export interface ResolvedOrusCoreConfig {
pillarLabels: Record<PillarId, string>;
statusThresholds: typeof DEFAULT_STATUS_THRESHOLDS;
prioritizationWeights: PrioritizationWeights;
verticalSchema: VerticalSchema | undefined;
vertical: {
name: string;
version: string;
shell?: string;
};
debug: boolean;
}
/**
* ORUS Core instance
*
* @remarks
* Encapsulates configuration and provides configured utility functions.
* Create one instance per app/vertical.
*/
export declare class OrusCoreInstance {
/**
* Current configuration
*/
readonly config: ResolvedOrusCoreConfig;
/**
* Creates a new ORUS Core instance
*
* @param userConfig - User configuration (optional)
*
* @remarks
* Merges user config with defaults.
* Validates configuration on creation.
*
* @example
* ```typescript
* const orus = new OrusCoreInstance({
* pillarLabels: myFinanceLabels,
* vertical: {
* name: "ORUS Finance",
* version: "1.0.0"
* }
* });
* ```
*/
constructor(userConfig?: OrusCoreConfig);
/**
* Validates the configuration
*
* @throws Error if configuration is invalid
*/
private validateConfig;
/**
* Gets label for a pillar
*
* @param pillarId - Pillar ID
* @returns Human-readable label
*
* @example
* ```typescript
* const label = orus.getPillarLabel(PillarId.PILLAR_1);
* // => "Organização & Fluxo" (in Finance vertical)
* ```
*/
getPillarLabel(pillarId: PillarId): string;
/**
* Gets all pillar labels
*
* @returns Record of all labels
*/
getAllPillarLabels(): Record<PillarId, string>;
/**
* Gets status thresholds
*
* @returns Status thresholds
*/
getStatusThresholds(): typeof DEFAULT_STATUS_THRESHOLDS;
/**
* Gets prioritization weights
*
* @returns Prioritization weights
*/
getPrioritizationWeights(): PrioritizationWeights;
/**
* Gets vertical schema
*
* @returns Vertical schema (if configured)
*/
getVerticalSchema(): VerticalSchema | undefined;
/**
* Gets vertical info
*
* @returns Vertical identification
*/
getVerticalInfo(): ResolvedOrusCoreConfig['vertical'];
/**
* Checks if debug mode is enabled
*
* @returns Whether debug is enabled
*/
isDebugEnabled(): boolean;
/**
* Logs debug message (if debug enabled)
*
* @param message - Message to log
* @param data - Optional data to log
*/
log(message: string, data?: unknown): void;
/**
* Creates a new instance with updated config
*
* @param updates - Config updates
* @returns New instance
*
* @remarks
* Immutable update - original instance unchanged.
*
* @example
* ```typescript
* const orusWithDebug = orus.withConfig({ debug: true });
* ```
*/
withConfig(updates: Partial<OrusCoreConfig>): OrusCoreInstance;
}
/**
* Creates a new ORUS Core instance
*
* @param config - Configuration
* @returns ORUS Core instance
*
* @remarks
* Convenience factory function.
*
* @example
* ```typescript
* const orus = createOrusCore({
* pillarLabels: financeLabels,
* vertical: {
* name: "ORUS Finance",
* version: "1.0.0",
* shell: "Convexa360"
* }
* });
* ```
*/
export declare function createOrusCore(config?: OrusCoreConfig): OrusCoreInstance;
//# sourceMappingURL=core.d.ts.map