@adminide-stack/core 12.0.4-alpha.321 → 12.0.4-alpha.322

package/lib/core/configurations/examples/configuration-wrapper-example.d.ts

@@ -0,0 +1,67 @@
+import { ConfigurationModel } from '../models/ConfigurationModel';
+/**
+ * Example: Creating a ConfigurationModel from your complex configuration data
+ *
+ * This demonstrates how to:
+ * 1. Parse raw JSON configuration with override identifiers
+ * 2. Create a ConfigurationModel instance
+ * 3. Apply overrides for specific routes/contexts
+ * 4. Access configuration values with proper merging
+ */
+declare const rawConfigurationJSON = "{\n  \"headerBgColor\": \"#000000\",\n  \"textColor\": \"#a19c9c\",\n  \"project\": {\n    \"templates\": {\n      \"default\": {\n        \"id\": \"default\",\n        \"name\": \"Default Project\",\n        \"templateType\": \"default\",\n        \"description\": \"Basic project template with essential fields\",\n        \"isDefault\": true,\n        \"component\": \"DefaultProjectSlotFill\",\n        \"fields\": [\n          {\n            \"id\": \"budget\",\n            \"type\": \"text\",\n            \"label\": \"Budget\",\n            \"placeholder\": \"Enter project budget\",\n            \"required\": true\n          },\n          {\n            \"id\": \"deadline\",\n            \"type\": \"date\",\n            \"label\": \"Deadline\",\n            \"required\": true\n          },\n          {\n            \"id\": \"priority\",\n            \"type\": \"select\",\n            \"label\": \"Priority\",\n            \"required\": true,\n            \"options\": [\"Low\", \"Medium\", \"High\", \"Critical\"]\n          },\n          {\n            \"id\": \"description\",\n            \"type\": \"textarea\",\n            \"label\": \"Project Description\",\n            \"placeholder\": \"Describe the project objectives and scope\",\n            \"required\": false\n          }\n        ],\n        \"isActive\": true,\n        \"order\": 1\n      },\n      \"software\": {\n        \"id\": \"software\",\n        \"name\": \"Software Development\",\n        \"templateType\": \"software\",\n        \"description\": \"Template for software development projects\",\n        \"component\": \"SoftwareProjectSlotFill\",\n        \"fields\": [\n          {\n            \"id\": \"technology_stack\",\n            \"type\": \"select\",\n            \"label\": \"Technology Stack\",\n            \"required\": true,\n            \"options\": [\"React/Node.js\", \"Vue/Express\", \"Angular/NestJS\", \"Python/Django\", \"Other\"]\n          },\n          {\n            \"id\": \"project_type\",\n            \"type\": \"select\",\n            \"label\": \"Project Type\",\n            \"required\": true,\n            \"options\": [\"Web Application\", \"Mobile App\", \"Desktop Application\", \"API/Backend\"]\n          },\n          {\n            \"id\": \"estimated_hours\",\n            \"type\": \"number\",\n            \"label\": \"Estimated Hours\",\n            \"placeholder\": \"Enter estimated development hours\",\n            \"required\": true\n          },\n          {\n            \"id\": \"client_contact\",\n            \"type\": \"email\",\n            \"label\": \"Client Contact Email\",\n            \"required\": false\n          }\n        ],\n        \"isActive\": true,\n        \"order\": 2\n      },\n      \"marketing\": {\n        \"id\": \"marketing\",\n        \"name\": \"Marketing Campaign\",\n        \"templateType\": \"marketing\",\n        \"description\": \"Template for marketing and advertising projects\",\n        \"component\": \"MarketingProjectSlotFill\",\n        \"fields\": [\n          {\n            \"id\": \"campaign_type\",\n            \"type\": \"select\",\n            \"label\": \"Campaign Type\",\n            \"required\": true,\n            \"options\": [\"Social Media\", \"Email Marketing\", \"Content Marketing\", \"PPC\", \"SEO\"]\n          },\n          {\n            \"id\": \"target_audience\",\n            \"type\": \"text\",\n            \"label\": \"Target Audience\",\n            \"placeholder\": \"Describe the target demographic\",\n            \"required\": true\n          },\n          {\n            \"id\": \"campaign_duration\",\n            \"type\": \"number\",\n            \"label\": \"Campaign Duration (weeks)\",\n            \"required\": true\n          },\n          {\n            \"id\": \"kpis\",\n            \"type\": \"textarea\",\n            \"label\": \"Key Performance Indicators\",\n            \"placeholder\": \"List the KPIs to track campaign success\",\n            \"required\": false\n          }\n        ],\n        \"isActive\": true,\n        \"order\": 3\n      },\n      \"database\": {\n        \"id\": \"database\",\n        \"name\": \"Database Project\",\n        \"templateType\": \"database\",\n        \"description\": \"Template for database creation and management projects\",\n        \"component\": \"DatabaseProjectSlotFill\",\n        \"fields\": [\n          {\n            \"id\": \"organization\",\n            \"type\": \"select\",\n            \"label\": \"Organization\",\n            \"required\": true,\n            \"options\": [\"stackflow1@gmail.com's Org (Free)\", \"Personal Account\", \"Enterprise Account\"]\n          },\n          {\n            \"id\": \"project_name\",\n            \"type\": \"text\",\n            \"label\": \"Project Name\",\n            \"placeholder\": \"Enter unique project identifier\",\n            \"required\": true\n          },\n          {\n            \"id\": \"database_password\",\n            \"type\": \"text\",\n            \"label\": \"Database Password\",\n            \"placeholder\": \"Auto-generated secure password\",\n            \"required\": true\n          },\n          {\n            \"id\": \"region\",\n            \"type\": \"select\",\n            \"label\": \"Region\",\n            \"required\": true,\n            \"options\": [\"Southeast Asia (Singapore)\", \"US East (N. Virginia)\", \"US West (Oregon)\", \"Europe (Frankfurt)\", \"Asia Pacific (Tokyo)\", \"Canada (Central)\", \"Australia (Sydney)\"]\n          },\n          {\n            \"id\": \"connection_type\",\n            \"type\": \"select\",\n            \"label\": \"Connection Type\",\n            \"required\": true,\n            \"options\": [\"Data API + Connection String\", \"Only Connection String\"]\n          },\n          {\n            \"id\": \"api_schema\",\n            \"type\": \"select\",\n            \"label\": \"Data API Configuration\",\n            \"required\": true,\n            \"options\": [\"Use public schema for Data API (Default)\", \"Use dedicated API schema for Data API\"]\n          },\n          {\n            \"id\": \"postgres_type\",\n            \"type\": \"select\",\n            \"label\": \"PostgreSQL Type\",\n            \"required\": true,\n            \"options\": [\"PostgreSQL (Default)\", \"PostgreSQL with OrioleDB (Alpha)\"]\n          },\n          {\n            \"id\": \"performance_tier\",\n            \"type\": \"select\",\n            \"label\": \"Performance Tier\",\n            \"required\": false,\n            \"options\": [\"Free Tier\", \"Pro\", \"Team\", \"Enterprise\"]\n          },\n          {\n            \"id\": \"backup_enabled\",\n            \"type\": \"checkbox\",\n            \"label\": \"Enable Automated Backups\",\n            \"required\": false\n          },\n          {\n            \"id\": \"ssl_enforcement\",\n            \"type\": \"checkbox\",\n            \"label\": \"Enforce SSL Connections\",\n            \"required\": false\n          },\n          {\n            \"id\": \"description\",\n            \"type\": \"textarea\",\n            \"label\": \"Project Description\",\n            \"placeholder\": \"Describe the database purpose and expected usage patterns\",\n            \"required\": false\n          }\n        ],\n        \"isActive\": true,\n        \"order\": 4\n      },\n      \"enabled\": true\n    }\n  },\n  \"[/o/:orgName/vault]\": {\n    \"navTheme\": \"realDark\",\n    \"primaryColor\": \"#1890ff\",\n    \"theme\": \"airbnb\",\n    \"footer\": {\n      \"showFooter\": false\n    }\n  },\n  \"[/o/:orgName/pref/settings]\": {\n    \"header\": {\n      \"menuHeaderRender\": false\n    }\n  }\n}";
+/**
+ * Wrapper class for working with configuration models
+ */
+export declare class ConfigurationWrapper {
+    private rawJSON;
+    private baseModel;
+    constructor(rawJSON: string);
+    /**
+     * Parse the configuration and create the base model
+     */
+    initialize(configurationProperties?: any): Promise<void>;
+    /**
+     * Get the base configuration model
+     */
+    getBaseModel(): ConfigurationModel;
+    /**
+     * Get a value from the base configuration (no overrides applied)
+     */
+    getBaseValue<T = any>(section?: string): T;
+    /**
+     * Get configuration with overrides applied for a specific route
+     *
+     * @param routeIdentifier - e.g., "/o/:orgName/vault"
+     * @param strict - If true, only exact matches; if false, includes compound overrides
+     */
+    getConfigForRoute<T = any>(routeIdentifier: string, strict?: boolean): T;
+    /**
+     * Get a specific section with route overrides applied
+     */
+    getSectionForRoute<T = any>(section: string, routeIdentifier: string, strict?: boolean): T;
+    /**
+     * Get all available override identifiers
+     */
+    getOverrideIdentifiers(): string[][];
+    /**
+     * Check if a specific override exists
+     */
+    hasOverride(identifier: string): boolean;
+    /**
+     * Merge multiple configuration models
+     */
+    merge(other: ConfigurationModel): void;
+    /**
+     * Get all keys in the configuration
+     */
+    getKeys(): string[];
+    /**
+     * Print debug information
+     */
+    debug(): void;
+}
+/**
+ * Example usage demonstrating the wrapper
+ */
+export declare function exampleUsage(): Promise<void>;
+export { rawConfigurationJSON };

package/lib/core/configurations/models/ConfigurationModelWrapper.d.ts

@@ -22,6 +22,10 @@ export declare class EnhancedConfigurationModel {
      * @returns Value merged with base + identifier, and compound overrides as additional keys
      */
     getValue<T>(section?: string): T;
+    /**
+     * Filter out bracket-notation keys from an object
+     */
+    private filterBracketKeys;
     /**
      * Get all available compound override keys (without the current identifier)
      */

package/lib/core/configurations/models/ConfigurationModelWrapper.js

@@ -47,13 +47,19 @@ class EnhancedConfigurationModel {
   getValue(section) {
     // Get the merged value (base + identifier override)
     const mergedValue = section ? this.overrideModel.getValue(section) : this.overrideModel.contents;
-    // If no compound overrides, return as-is
+    // If no compound overrides, return as-is (but filter out bracket keys if no section)
     if (this.compoundOverrides.size === 0) {
+      if (!section) {
+        // Filter out any bracket-notation keys from the result
+        return this.filterBracketKeys(mergedValue);
+      }
       return mergedValue;
     }
     // Create result object with merged value and compound overrides
+    // When no section is specified, filter out bracket keys from base contents
+    const baseResult = section ? mergedValue : this.filterBracketKeys(mergedValue);
     const result = {
-      ...(mergedValue || {})
+      ...(baseResult || {})
     };
     // Add compound overrides as separate keys
     for (const [key, contents] of this.compoundOverrides.entries()) {
@@ -66,6 +72,22 @@ class EnhancedConfigurationModel {
     }
     return result;
   }
+  /**
+   * Filter out bracket-notation keys from an object
+   */
+  filterBracketKeys(obj) {
+    if (!obj || typeof obj !== 'object') {
+      return obj;
+    }
+    const filtered = {};
+    for (const key of Object.keys(obj)) {
+      // Skip keys that start with '[' (bracket notation)
+      if (!key.startsWith('[')) {
+        filtered[key] = obj[key];
+      }
+    }
+    return filtered;
+  }
   /**
    * Get all available compound override keys (without the current identifier)
    */

package/lib/core/configurations/models/ConfigurationModelWrapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConfigurationModelWrapper.js","sources":["../../../../src/core/configurations/models/ConfigurationModelWrapper.ts"],"sourcesContent":[null],"names":[],"mappings":"AAIA;;AAEG;MACU,0BAA0B,CAAA;AAMvB,EAAA,SAAA;AACA,EAAA,UAAA;AACA,EAAA,OAAA;AAPJ,EAAA,aAAA;AAEA,EAAA,iBAAA;AAER,EAAA,WAAA,CAAA,SACY,EAA6B,UAC7B,EAAkB,OAClB,EAA8B;QAF9B,CAAA,SAAA,GAAA;QACA,CAAA,UAAA,GAAA;QACA,CAAA,OAAA,GAAA;;QAGR,CAAA,aAAK,GAAA,SAAgB,CAAA,QAAU,CAAA,UAAS,EAAA,OAAY,CAAA;;AAGpD,IAAA,IAAA,CAAA,iBAAK,GAAA,IAAoB,yBAAK,EAAA;;AAGlC;;;AAGG;0BACK,GAAwB;AAC5B,IAAA,MAAA,SAAM,GAAA,IAAY,GAAA,EAAI;SAEtB,MAAK,YAAc,IAAI,CAAA,SAAK,CAAA,SAAU,EAAA;;AAElC,MAAA,IAAA,CAAA,QAAK,CAAA,WAAS,IAAA,QAAe,CAAA,WAAS,CAAA,MAAY,IAAA,CAAA,EAAM;;;;;kBAMpD,CAAA,WAAS,CAAA,QAAY,CAAA,IAAA,CAAQ,UAAM,CAAA,EAAA;;AAEnC,QAAA,MAAA,2BAAyB,CAAA,WAAS,CAAA,MAAA,CAAW,QAAQ,KAAK,IAAG,CAAE,UAAU,CAAA;;iBAGzE,GAAA,gBAAY,CAAA,GAAA,CAAA,EAAA,KAAoB,CAAC,IAAG,CAAE,CAAA,CAAE,CAAC,CAAA,IAAI,CAAE,GAAG;iBAElD,CAAA,GAAA,CAAA,GAAS,UAAU,CAAA,QAAS,CAAA;;;AAIpC,IAAA,OAAA;;AAGJ;;;;AAIG;AACH,EAAA,QAAA,CAAA,OAAY,EAAgB;;UAExB,WAAM,GAAA,OAAc,GAAA,IAAO,CAAA,aAAA,CAAA,QAAA,CAAA,OAAA,CAAA,GAAA,IAAA,CAAA,aAAA,CAAA,QAAA;;AAEvB,IAAA,IAAA,IAAA,CAAC,iBAAM,CAAA,UAAsB,EAAC;aAElC,WAAA;;AAEI;UACH,MAAA,GAAA;UAED,WAAA,IAAA,EAAA;;;AAIA,IAAA,KAAA,MAAK,CAAA,GAAM,EAAC,aAAc,IAAI,CAAA,iBAAK,CAAA,OAAkB,EAAA,EAAO;;;AAGxD,MAAA,MAAA,uBAAsB,GAAA,IAAQ,CAAC,oBAAM,CAAA,QAAqB,EAAA,OAAU,CAAA,GAAA;AAEpE,MAAA,IAAA,aAAI,KAAA,SAAkB,EAAA;AAClB,QAAA,MAAA,CAAA,GAAA,CAAA,GAAM;;;AAId,IAAA,OAAA;;AAGJ;;AAEG;yBACH,GAAuB;WACnB,KAAO,CAAA,IAAM,CAAA,IAAK,CAAA,iBAAK,CAAA,IAAkB,EAAA,CAAA;;AAG7C;;;;AAIG;qBACH,CAAA,WAAuB,EAAmB,OAAE,EAAgB;UACxD,QAAM,GAAA,IAAW,CAAA,iBAAK,CAAA,GAAiB,CAAC,WAAI,CAAA;QAC5C,CAAA,QAAK,EAAA;AACD,MAAA,OAAA;;AAGJ,IAAA,OAAA,cAAkB,CAAA,oBAAK,CAAA,QAAqB,EAAA,WAAiB;;AAGjE;;AAEG;sBACK,CAAA,QAAqB,EAAoC,OAAE,EAAe;UAC9E,KAAM,GAAA,OAAQ,CAAA,SAAa,CAAC;QAC5B,KAAI,GAAA,QAAiB;AAErB,IAAA,KAAA,MAAK,IAAM,IAAI,KAAI,EAAA;eACf,IAAI,OAAS,KAAA,KAAO,QAAU,IAAA,IAAQ,IAAI,KAAI,EAAI;AAC9C,QAAA,KAAA,GAAA,KAAK,CAAA,IAAI,CAAA;aACZ;wBAAO;AACJ,MAAA;;WAEP,KAAA;AAED,EAAA;;AAGJ;;AAEG,EAAA,gBAAA,GAAA;IACH,OAAA,IAAA,CAAA,aAAgB;;"}
+{"version":3,"file":"ConfigurationModelWrapper.js","sources":["../../../../src/core/configurations/models/ConfigurationModelWrapper.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/lib/core/configurations/models/ConfigurationModelWrapper.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/core/configurations/models/override.compound.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/core/configurations/models/override.edgecase.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/core/configurations/models/override.keys.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/core/configurations/models/override.strict.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/core/configurations/utils/QUICK_REFERENCE.d.ts

@@ -0,0 +1,103 @@
+/**
+ * QUICK REFERENCE: Configuration Extractor Utilities
+ * ==================================================
+ *
+ * Import:
+ * import { extractConfiguration, ... } from '@adminide/core/configurations/utils';
+ *
+ * REUSES EXISTING CODE:
+ * - OVERRIDE_PROPERTY_REGEX from configuration.ts
+ * - overrideIdentifiersFromKey from configuration.ts
+ *
+ * ==================================================
+ * MAIN FUNCTION
+ * ==================================================
+ *
+ * extractConfiguration(settings)
+ * Returns: { baseContents, baseKeys, overrides }
+ *
+ * Example:
+ * const { baseContents, baseKeys, overrides } = extractConfiguration({
+ *   theme: "light",
+ *   "[desktop]": { theme: "dark" }
+ * });
+ *
+ * ==================================================
+ * HELPER FUNCTIONS
+ * ==================================================
+ *
+ * isBracketKey(key: string): boolean
+ *   Check if key is bracket notation: [desktop], [/route]
+ *
+ * extractIdentifiersFromKey(key: string): string[]
+ *   Parse identifiers from key: "[/route][desktop]" => ["/route", "desktop"]
+ *
+ * getOverrideKeys(settings): string[]
+ *   Get all bracket keys: ["[desktop]", "[mobile]"]
+ *
+ * getBaseKeys(settings): string[]
+ *   Get all non-bracket keys: ["theme", "color"]
+ *
+ * removeOverrideKeys(settings): object
+ *   Return new object without bracket keys
+ *
+ * hasOverrides(settings): boolean
+ *   Check if settings has any overrides
+ *
+ * getOverrideByIdentifier(settings, identifier): contents | undefined
+ *   Get specific override: getOverrideByIdentifier(settings, "desktop")
+ *
+ * ==================================================
+ * COMMON PATTERNS
+ * ==================================================
+ *
+ * 1. EXTRACT AND SEPARATE
+ * ------------------------
+ * const { baseContents, overrides } = extractConfiguration(settings);
+ *
+ * 2. GET ROUTE CONFIG
+ * -------------------
+ * const override = overrides.find(o => o.identifiers.includes(route));
+ * const config = override ? { ...baseContents, ...override.contents } : baseContents;
+ *
+ * 3. CLEAN CONFIG
+ * ---------------
+ * const cleanConfig = removeOverrideKeys(settings);
+ *
+ * 4. CHECK FOR OVERRIDES
+ * ----------------------
+ * if (hasOverrides(settings)) { ... }
+ *
+ * 5. GET SPECIFIC OVERRIDE
+ * ------------------------
+ * const desktopConfig = getOverrideByIdentifier(settings, "desktop");
+ *
+ * ==================================================
+ * TYPES
+ * ==================================================
+ *
+ * interface ExtractedConfiguration {
+ *   baseContents: any;
+ *   baseKeys: string[];
+ *   overrides: ConfigurationOverride[];
+ * }
+ *
+ * interface ConfigurationOverride {
+ *   identifiers: string[];  // e.g., ["/o/:orgName/vault"]
+ *   contents: any;          // Override data
+ *   keys: string[];         // Keys in override
+ * }
+ *
+ * ==================================================
+ * WHEN TO USE
+ * ==================================================
+ *
+ * ✅ Parsing server responses
+ * ✅ Client-side route handling
+ * ✅ Data transformation
+ * ✅ Testing configuration structure
+ * ✅ API response formatting
+ *
+ * ==================================================
+ */
+export {};

package/lib/core/configurations/utils/configurationExtractor.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Utility to extract overrides and keys from configuration data
+ *
+ * This handles bracket-notation override identifiers like:
+ * - [desktop]
+ * - [/o/:orgName/vault]
+ * - [/o/:orgName/vault][desktop]
+ *
+ * Reuses existing utilities from configuration.ts:
+ * - OVERRIDE_PROPERTY_REGEX: Pattern to match bracket keys
+ * - overrideIdentifiersFromKey: Parse identifiers from bracket notation
+ */
+export interface ConfigurationOverride {
+    identifiers: string[];
+    contents: any;
+    keys: string[];
+}
+export interface ExtractedConfiguration {
+    baseContents: any;
+    baseKeys: string[];
+    overrides: ConfigurationOverride[];
+}
+/**
+ * Check if a key is a bracket-notation override identifier
+ * Uses OVERRIDE_PROPERTY_REGEX from configuration.ts
+ *
+ * @param key - The key to check
+ * @returns True if the key matches the override pattern
+ *
+ * @example
+ * ```typescript
+ * isBracketKey('[desktop]') // true
+ * isBracketKey('[/o/:orgName/vault]') // true
+ * isBracketKey('[/route][desktop]') // true
+ * isBracketKey('headerBgColor') // false
+ * ```
+ */
+export declare function isBracketKey(key: string): boolean;
+/**
+ * Extract individual identifiers from a bracket key
+ * Reuses overrideIdentifiersFromKey from configuration.ts
+ * Handles compound identifiers like [/route][desktop]
+ *
+ * @param key - The bracket key to parse
+ * @returns Array of identifiers without brackets
+ *
+ * @example
+ * ```typescript
+ * extractIdentifiersFromKey('[desktop]')
+ * // Returns: ['desktop']
+ *
+ * extractIdentifiersFromKey('[/o/:orgName/vault]')
+ * // Returns: ['/o/:orgName/vault']
+ *
+ * extractIdentifiersFromKey('[/o/:orgName/vault][desktop]')
+ * // Returns: ['/o/:orgName/vault', 'desktop']
+ * ```
+ */
+export declare function extractIdentifiersFromKey(key: string): string[];
+/**
+ * Extract overrides and base configuration from settings object
+ *
+ * @param settings - Configuration object that may contain bracket-notation overrides
+ * @returns Extracted base contents, keys, and overrides array
+ *
+ * @example
+ * ```typescript
+ * const settings = {
+ *   headerBgColor: "#000000",
+ *   textColor: "#a19c9c",
+ *   "[/o/:orgName/vault]": {
+ *     navTheme: "realDark",
+ *     primaryColor: "#1890ff"
+ *   },
+ *   "[/o/:orgName/pref/settings]": {
+ *     header: { menuHeaderRender: false }
+ *   }
+ * };
+ *
+ * const { baseContents, baseKeys, overrides } = extractConfiguration(settings);
+ * // baseContents: { headerBgColor: "#000000", textColor: "#a19c9c" }
+ * // baseKeys: ["headerBgColor", "textColor"]
+ * // overrides: [
+ * //   { identifiers: ["/o/:orgName/vault"], contents: {...}, keys: [...] },
+ * //   { identifiers: ["/o/:orgName/pref/settings"], contents: {...}, keys: [...] }
+ * // ]
+ * ```
+ */
+export declare function extractConfiguration(settings: any): ExtractedConfiguration;
+/**
+ * Get only the override keys (bracket-notation keys) from settings
+ *
+ * @param settings - Configuration object
+ * @returns Array of bracket keys
+ *
+ * @example
+ * ```typescript
+ * const settings = {
+ *   headerBgColor: "#000000",
+ *   "[/o/:orgName/vault]": {...},
+ *   "[desktop]": {...}
+ * };
+ *
+ * getOverrideKeys(settings)
+ * // Returns: ['[/o/:orgName/vault]', '[desktop]']
+ * ```
+ */
+export declare function getOverrideKeys(settings: any): string[];
+/**
+ * Get only the base keys (non-bracket keys) from settings
+ *
+ * @param settings - Configuration object
+ * @returns Array of base keys
+ *
+ * @example
+ * ```typescript
+ * const settings = {
+ *   headerBgColor: "#000000",
+ *   textColor: "#a19c9c",
+ *   "[/o/:orgName/vault]": {...}
+ * };
+ *
+ * getBaseKeys(settings)
+ * // Returns: ['headerBgColor', 'textColor']
+ * ```
+ */
+export declare function getBaseKeys(settings: any): string[];
+/**
+ * Remove all bracket-notation keys from an object
+ * Returns a new object with only base properties
+ *
+ * @param settings - Configuration object
+ * @returns New object without bracket keys
+ *
+ * @example
+ * ```typescript
+ * const settings = {
+ *   headerBgColor: "#000000",
+ *   "[/o/:orgName/vault]": {...},
+ *   textColor: "#a19c9c"
+ * };
+ *
+ * removeOverrideKeys(settings)
+ * // Returns: { headerBgColor: "#000000", textColor: "#a19c9c" }
+ * ```
+ */
+export declare function removeOverrideKeys(settings: any): any;
+/**
+ * Check if settings object has any override identifiers
+ *
+ * @param settings - Configuration object
+ * @returns True if any bracket keys exist
+ *
+ * @example
+ * ```typescript
+ * hasOverrides({ headerBgColor: "#000" }) // false
+ * hasOverrides({ "[desktop]": {...} }) // true
+ * ```
+ */
+export declare function hasOverrides(settings: any): boolean;
+/**
+ * Get a specific override by identifier
+ *
+ * @param settings - Configuration object
+ * @param identifier - The identifier to search for (without brackets)
+ * @returns The override contents or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const settings = {
+ *   "[/o/:orgName/vault]": { navTheme: "realDark" },
+ *   "[desktop]": { theme: "dark" }
+ * };
+ *
+ * getOverrideByIdentifier(settings, '/o/:orgName/vault')
+ * // Returns: { navTheme: "realDark" }
+ *
+ * getOverrideByIdentifier(settings, 'desktop')
+ * // Returns: { theme: "dark" }
+ * ```
+ */
+export declare function getOverrideByIdentifier(settings: any, identifier: string): any | undefined;

package/lib/core/configurations/utils/configurationExtractor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/core/configurations/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Configuration utilities index
+ * Exports all utility functions for working with configuration data
+ */
+export { ConfigurationOverride, ExtractedConfiguration, extractConfiguration, isBracketKey, extractIdentifiersFromKey, getOverrideKeys, getBaseKeys, removeOverrideKeys, hasOverrides, getOverrideByIdentifier, } from './configurationExtractor';

package/lib/core/configurations/utils/preferences-service-integration.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Integration Example: In your preferences-service.ts
+ */
+export declare function getPageSettings(_configKey: string, _overrideIdentifier: string, _strict: boolean): Promise<any>;
+/**
+ * Benefits of using the utility:
+ *
+ * 1. ✅ Reuses existing OVERRIDE_PROPERTY_REGEX (consistent with parser)
+ * 2. ✅ Reuses existing overrideIdentifiersFromKey (handles compound keys properly)
+ * 3. ✅ One line instead of ~20 lines of inline logic
+ * 4. ✅ Tested and documented
+ * 5. ✅ Can be reused across your codebase
+ * 6. ✅ Properly handles edge cases (null, empty, compound identifiers)
+ * 7. ✅ TypeScript typed
+ * 8. ✅ Maintains same output structure
+ */
+/**
+ * Your original commented code vs utility:
+ */
+export declare function comparison(): void;
+/**
+ * Complete integration example for preferences-service.ts
+ */
+export declare class PreferencesServiceExample {
+    getPageSettings(targets: string[], configKey?: string, overrideIdentifier?: string, strict?: boolean): Promise<{
+        contents: any;
+        keys: string[];
+        overrides: {
+            identifiers: string[];
+            contents: any;
+        }[];
+    }>;
+}
+/**
+ * Quick reference for your use case:
+ *
+ * REPLACE THIS:
+ * -------------
+ * const baseContents: any = {};
+ * const overrides: any[] = [];
+ * Object.keys(cleanedSettings).forEach((key) => {
+ *   if (key.startsWith('[') && key.endsWith(']')) {
+ *     const overrideData = cleanedSettings[key];
+ *     overrides.push({ identifiers: [key], contents: overrideData, keys: Object.keys(overrideData) });
+ *   } else {
+ *     baseContents[key] = cleanedSettings[key];
+ *   }
+ * });
+ *
+ * WITH THIS:
+ * ----------
+ * import { extractConfiguration } from '@adminide/core/configurations/utils';
+ * const { baseContents, overrides } = extractConfiguration(cleanedSettings);
+ */

package/lib/core/configurations/utils/usage-examples.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Example 1: Basic Extraction
+ * Extract base configuration and overrides
+ */
+export declare function example1_BasicExtraction(): void;
+/**
+ * Example 2: Working with Base Configuration
+ * Get and manipulate base configuration
+ */
+export declare function example2_BaseConfiguration(): void;
+/**
+ * Example 3: Route-Specific Configuration
+ * Get configuration for a specific route
+ */
+export declare function example3_RouteConfiguration(): void;
+/**
+ * Example 4: Checking and Filtering
+ * Various utility functions
+ */
+export declare function example4_CheckingFiltering(): void;
+/**
+ * Example 5: Parsing Identifiers
+ * Extract identifiers from bracket keys
+ */
+export declare function example5_ParsingIdentifiers(): void;
+/**
+ * Example 6: Lazy Loading Pattern
+ * Load configuration once, apply overrides as needed
+ */
+export declare function example6_LazyLoadingPattern(): void;
+/**
+ * Example 7: Configuration Merging
+ * Merge multiple configuration sources
+ */
+export declare function example7_ConfigurationMerging(): void;
+/**
+ * Run all examples
+ */
+export declare function runAllExamples(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@adminide-stack/core",
-    "version": "12.0.4-alpha.321",
+    "version": "12.0.4-alpha.322",
     "description": "AdminIDE core for higher packages to depend on",
     "license": "UNLICENSED",
     "author": "CDMBase LLC",
@@ -30,7 +30,7 @@
         "vscode-uri": "^3.0.8"
     },
     "devDependencies": {
-        "common": "12.0.4-alpha.318"
+        "common": "12.0.4-alpha.322"
     },
     "peerDependencies": {
         "@common-stack/server-core": ">=0.5.21",
@@ -42,5 +42,5 @@
     "typescript": {
         "definition": "lib/index.d.ts"
     },
-    "gitHead": "b8a942a3dff9bc3ccf418633fd2b87326596a47a"
+    "gitHead": "c627a82df2d971c085eb29e575e121b003e3507d"
 }