@dcupl/common 1.11.10 → 2.0.0-beta.0

package/dist/esm/attribute-dependency-graph.d.ts

@@ -0,0 +1,119 @@
+export type AttributeNode = {
+    modelKey: string;
+    attributeKey: string;
+    type: 'property' | 'reference';
+    processingStep: 1 | 2 | 3 | 4;
+};
+export type AttributeNodeId = string;
+export type ProcessingPlan = Map<string, Map<number, Set<string>>>;
+/**
+ * AttributeDependencyGraph tracks attribute-level dependencies between models.
+ *
+ * This graph is item-agnostic: when ModelA.price depends on ModelB.cost,
+ * any change to ModelB.cost triggers reprocessing of ALL ModelA items
+ * that have the price derivation.
+ *
+ * The graph ensures:
+ * - Correct processing order based on dependencies
+ * - Impact analysis when attributes change
+ * - Efficient batch processing by grouping attributes by model and step
+ */
+export declare class AttributeDependencyGraph {
+    private graph;
+    private nodeIndex;
+    constructor();
+    /**
+     * Creates a unique ID for an attribute node
+     */
+    private getNodeId;
+    /**
+     * Parses a node ID back into components
+     */
+    private parseNodeId;
+    /**
+     * Adds an attribute node to the graph
+     */
+    addAttribute(node: AttributeNode): void;
+    /**
+     * Adds a dependency between two attributes
+     * @param from - The dependent attribute (e.g., ModelA.derivedPrice)
+     * @param to - The source attribute it depends on (e.g., ModelB.baseCost)
+     */
+    addAttributeDependency(from: AttributeNode, to: AttributeNode): void;
+    /**
+     * Gets all attributes impacted by changes to the given attributes
+     * @param changed - Array of changed attribute nodes
+     * @returns Array of all impacted attribute nodes (including the changed ones)
+     */
+    getImpactedAttributes(changed: AttributeNode[]): AttributeNode[];
+    /**
+     * Generates a processing plan for the given attributes
+     * Groups attributes by model and processing step for efficient batch processing
+     *
+     * @param attributes - Array of attributes to process
+     * @returns Map<modelKey, Map<processingStep, Set<attributeKeys>>>
+     */
+    getProcessingOrder(attributes: AttributeNode[]): ProcessingPlan;
+    /**
+     * Gets all attributes for a specific model
+     */
+    getAttributesForModel(modelKey: string): AttributeNode[];
+    /**
+     * Gets dependencies for a specific attribute
+     */
+    getDependencies(node: AttributeNode): AttributeNode[];
+    /**
+     * Gets dependents for a specific attribute (attributes that depend on this one)
+     */
+    getDependents(node: AttributeNode): AttributeNode[];
+    /**
+     * Checks if an attribute has any dependencies
+     */
+    hasDependencies(node: AttributeNode): boolean;
+    /**
+     * Checks if a node exists in the graph
+     */
+    hasNode(nodeId: AttributeNodeId): boolean;
+    /**
+     * Gets all attribute nodes in the graph
+     */
+    getAllAttributes(): AttributeNode[];
+    /**
+     * Gets the maximum dependency depth in the graph
+     * Useful for determining if full update might be more efficient
+     */
+    getMaxDepth(): number;
+    /**
+     * Validates that all expected attributes are present in the graph.
+     * This helps catch silent failures during graph building where attributes
+     * with expressions or derivations might not be properly added.
+     *
+     * @param expectedAttributes - Map of modelKey to array of attribute keys that should exist
+     * @returns Object with validation result and any missing attributes
+     */
+    validateCompleteness(expectedAttributes: Map<string, string[]>): {
+        isComplete: boolean;
+        missing: Array<{
+            modelKey: string;
+            attributeKey: string;
+        }>;
+    };
+    /**
+     * Clears the entire graph
+     */
+    clear(): void;
+    /**
+     * Gets statistics about the graph
+     */
+    getStats(): {
+        totalAttributes: number;
+        totalDependencies: number;
+        maxDepth: number;
+        attributesByModel: Map<string, number>;
+        attributesByStep: Map<number, number>;
+    };
+    /**
+     * Exports the graph to JSON for debugging
+     */
+    toJSON(): any;
+}

package/dist/esm/cache.controller.d.ts

@@ -1,11 +1,66 @@
 export declare class CacheController {
     enabled: boolean;
     private cache;
+    private cacheDependencies;
+    private hitCount;
+    private missCount;
+    private log;
     constructor(enabled: boolean);
     get(key: string, context: any): any;
-    set(key: string, context: any, value: any): void;
+    set(key: string, context: any, value: any, dependencies?: CacheDependencyInfo): void;
     has(key: string, context: any): boolean;
     clear(): void;
+    /**
+     * Invalidates cache entries that depend on the specified models and attributes
+     * @param changedModels - Map of modelKey → Set of changed attributeKeys
+     */
+    invalidateByDependencies(changedModels: Map<string, Set<string>>): void;
+    /**
+     * Invalidates all cache entries for specific models
+     * @param modelKeys - Array of model keys to invalidate
+     */
+    invalidateByModels(modelKeys: string[]): void;
+    /**
+     * Invalidates cache entries by key prefix (e.g., 'query', 'facets')
+     * @param keyPrefix - The key prefix to match
+     */
+    invalidateByKeyPrefix(keyPrefix: string): void;
+    /**
+     * Invalidates all cache entries for a specific model
+     * @param modelKey - The model key to invalidate
+     */
+    invalidateForModel(modelKey: string): void;
+    /**
+     * Invalidates cache entries that depend on a specific attribute of a model
+     * @param modelKey - The model key
+     * @param attributeKey - The attribute key to invalidate
+     */
+    invalidateForAttribute(modelKey: string, attributeKey: string): void;
+    /**
+     * Invalidates cache entries matching a custom predicate
+     * @param predicate - Function that returns true for cache keys to invalidate
+     */
+    invalidateMatching(predicate: (key: string) => boolean): void;
     generateContext(constext: any): any;
     getCacheName(key: string, context: any): string;
+    /**
+     * Gets cache statistics including hit rate
+     */
+    getStats(): {
+        size: number;
+        hitRate: number;
+        totalEntries: number;
+        entriesWithDependencies: number;
+        hits: number;
+        misses: number;
+    };
+}
+/**
+ * Information about which models and attributes a cache entry depends on
+ */
+export interface CacheDependencyInfo {
+    /** Set of model keys this cache entry depends on */
+    models: Set<string>;
+    /** Map of modelKey → Set of attribute keys (if specific attributes matter) */
+    modelAttributes: Map<string, Set<string>>;
 }

package/dist/esm/changeDetection.d.ts

@@ -2,7 +2,7 @@ import { CallbackFunction, DcuplInitOptions } from './types';
 import { AnalyticsController } from './analytics.controller';
 export type DcuplUpdateScope = 'all' | 'global' | 'list' | 'list$';
 export type DcuplUpdateTrigger = 'user' | 'loader';
-export type DcuplUpdateType = 'data_change' | 'dcupl_destroyed' | 'dcupl_handle_datacontainer' | 'dcupl_initialized' | 'dcupl_updated_manually' | 'filter_many' | 'filter_one' | 'fn_aggregate' | 'fn_facets' | 'fn_groupBy' | 'fn_metadata' | 'fn_pivot' | 'fn_suggest' | 'list_created' | 'list_destroyed' | 'list_updated' | 'loader_added' | 'loader_config_fetched' | 'loader_data_fetched' | 'loader_models_fetched' | 'loader_scripts_fetched' | 'loader_processed' | 'loader_removed' | 'model_add' | 'query_apply_options' | 'query_apply' | 'query_execute' | 'query_get' | 'query_has' | 'query_many' | 'query_one' | 'query_remove' | 'query_reset' | 'result_updated' | 'view_add';
+export type DcuplUpdateType = 'data_change' | 'dcupl_destroyed' | 'dcupl_handle_datacontainer' | 'dcupl_initialized' | 'dcupl_updated_manually' | 'dcupl_partial_update' | 'filter_many' | 'filter_one' | 'fn_aggregate' | 'fn_facets' | 'fn_groupBy' | 'fn_metadata' | 'fn_pivot' | 'fn_suggest' | 'list_created' | 'list_destroyed' | 'list_updated' | 'loader_added' | 'loader_config_fetched' | 'loader_data_fetched' | 'loader_models_fetched' | 'loader_scripts_fetched' | 'loader_processed' | 'loader_removed' | 'model_add' | 'query_apply_options' | 'query_apply' | 'query_execute' | 'query_get' | 'query_has' | 'query_many' | 'query_one' | 'query_remove' | 'query_reset' | 'result_updated' | 'view_add';
 export type DcuplUpdateAction = 'update';
 export type DcuplUpdateMessage = {
     key?: number;

package/dist/esm/date-utils.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Custom date utilities to replace date-fns
+ * Supports custom format patterns for date parsing
+ */
+/**
+ * Check if a value is a Date instance
+ * @param value - Value to check
+ * @returns true if value is a Date instance (valid or invalid), false otherwise
+ */
+export declare function isDateInstance(value: any): value is Date;
+/**
+ * Check if a Date object represents a valid date
+ * @param date - Date object to validate
+ * @returns true if date is valid, false otherwise
+ */
+export declare function isValidDate(date: Date): boolean;
+/**
+ * Parse a date string according to a format pattern
+ *
+ * Supported format tokens:
+ * - yyyy: 4-digit year
+ * - yy: 2-digit year (00-99 → 2000-2099)
+ * - MM: 2-digit month (01-12)
+ * - M: 1-2 digit month (1-12)
+ * - dd: 2-digit day (01-31)
+ * - d: 1-2 digit day (1-31)
+ * - HH: 2-digit hour (00-23)
+ * - H: 1-2 digit hour (0-23)
+ * - mm: 2-digit minute (00-59)
+ * - m: 1-2 digit minute (0-59)
+ * - ss: 2-digit second (00-59)
+ * - s: 1-2 digit second (0-59)
+ * - SSS: 3-digit millisecond (000-999)
+ *
+ * Special formats:
+ * - 't': Unix timestamp in seconds
+ * - 'T': Unix timestamp in milliseconds
+ *
+ * @param value - The date string to parse
+ * @param format - Format pattern (e.g., 'yyyy-MM-dd', 'dd.MM.yyyy', 't', 'T')
+ * @param referenceDate - Optional reference date (reserved for future use, currently unused)
+ * @returns Parsed Date object or Invalid Date (NaN)
+ *
+ * @example
+ * parseDate('2023-12-25', 'yyyy-MM-dd') // Dec 25, 2023
+ * parseDate('25.12.2023', 'dd.MM.yyyy') // Dec 25, 2023
+ * parseDate('1640000000', 't')          // Unix seconds
+ * parseDate('2023-02-31', 'yyyy-MM-dd') // Invalid Date (Feb only has 28/29 days)
+ */
+export declare function parseDate(value: string, format: string, _referenceDate?: Date): Date;

package/dist/esm/deep-query.service.d.ts

@@ -0,0 +1,133 @@
+import { QueryAttributeEntry } from './query-builder';
+/**
+ * Result of path validation
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+/**
+ * DeepQueryService - Centralized service for parsing, validating, and caching deep query attributes
+ *
+ * This service provides:
+ * - LRU caching for parsed attribute paths (1000 entries, targeting >80% hit rate)
+ * - Circular reference detection
+ * - Multi-level nesting support (3+ levels)
+ * - Path validation with descriptive errors
+ */
+export declare class DeepQueryService {
+    private parseCache;
+    private circularRefDetector;
+    private cacheHits;
+    private cacheMisses;
+    constructor(cacheSize?: number);
+    /**
+     * Parse an attribute string into its components
+     *
+     * Supports:
+     * - Dot notation: `customer.name`
+     * - Bracket notation: `items[0].price`, `items[*].price`
+     * - Multi-level: `order.customer.address.city`
+     *
+     * @param attribute - The attribute path to parse
+     * @returns QueryAttributeEntry with isDeepQuery, reference, referenceAttribute
+     *
+     * @example
+     * ```typescript
+     * const service = new DeepQueryService();
+     * const entry = service.parse('customer.name');
+     * // Returns: { attribute: 'customer.name', isDeepQuery: true, reference: 'customer', referenceAttribute: 'name' }
+     * ```
+     */
+    parse(attribute: string): QueryAttributeEntry;
+    /**
+     * Detect circular references in a path
+     *
+     * Checks for:
+     * - Direct circular: A→B→A
+     * - Indirect circular: A→B→C→A
+     * - Self-referential: A→A
+     *
+     * @param path - Array of model/reference keys in the dependency chain
+     * @returns true if circular reference detected
+     *
+     * @example
+     * ```typescript
+     * const service = new DeepQueryService();
+     * const hasCircular = service.detectCircular(['Order', 'Customer', 'Order']);
+     * // Returns: true
+     * ```
+     */
+    detectCircular(path: string[]): boolean;
+    /**
+     * Validate attribute path syntax
+     *
+     * Checks for:
+     * - Empty strings
+     * - Malformed bracket notation
+     * - Invalid characters
+     * - Excessive nesting depth
+     *
+     * @param attribute - The attribute path to validate
+     * @param maxDepth - Maximum allowed nesting depth (default: 10)
+     * @returns ValidationResult with errors if invalid
+     *
+     * @example
+     * ```typescript
+     * const service = new DeepQueryService();
+     * const result = service.validatePath('customer.name');
+     * // Returns: { valid: true }
+     *
+     * const badResult = service.validatePath('customer.[invalid]');
+     * // Returns: { valid: false, errors: ['Invalid bracket notation: customer.[invalid]'] }
+     * ```
+     */
+    validatePath(attribute: string, maxDepth?: number): ValidationResult;
+    /**
+     * Clear the parse cache
+     * Should be called when models are updated or removed
+     */
+    clearCache(): void;
+    /**
+     * Clear the circular reference detector
+     */
+    clearCircularDetector(): void;
+    /**
+     * Get cache statistics for monitoring and debugging
+     *
+     * @returns Object containing cache size, hit rate, and other metrics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * Extract path segments from an attribute string
+     * Useful for analyzing deep query structure
+     *
+     * @param attribute - The attribute path
+     * @returns Array of path segments
+     *
+     * @example
+     * ```typescript
+     * const service = new DeepQueryService();
+     * const segments = service.getPathSegments('order.customer.name');
+     * // Returns: ['order', 'customer', 'name']
+     * ```
+     */
+    getPathSegments(attribute: string): string[];
+    /**
+     * Get the depth of a deep query path
+     *
+     * @param attribute - The attribute path
+     * @returns Depth of the path (1 for shallow, 2+ for deep)
+     */
+    getPathDepth(attribute: string): number;
+}
+/**
+ * Singleton instance for global use
+ */
+export declare const deepQueryService: DeepQueryService;

package/dist/esm/dependency-graph.d.ts

@@ -1,9 +1,31 @@
-export declare class DependencyGraph {
+export declare class DependencyGraph<K extends string = string, M = any> {
     private nodes;
     private edges;
+    private nodeKinds;
+    private nodeMeta;
+    private edgePolicy?;
     constructor();
-    addNode(name: string): void;
+    addNode(name: string, options?: {
+        kind?: K;
+        meta?: M;
+    }): void;
     addDependency(from: string, to: string): void;
+    /** Configure an optional policy to validate edges before they are added */
+    setEdgePolicy(policy?: (from: {
+        name: string;
+        kind?: K;
+    }, to: {
+        name: string;
+        kind?: K;
+    }) => boolean): void;
+    /** Assign or change a node's kind */
+    setNodeKind(name: string, kind?: K): void;
+    /** Get a node's kind */
+    getNodeKind(name: string): K | undefined;
+    /** Set arbitrary metadata for a node */
+    setNodeMeta(name: string, meta: M): void;
+    /** Get metadata for a node */
+    getNodeMeta<T = M>(name: string): T | undefined;
     removeNode(name: string): void;
     removeDependency(from: string, to: string): void;
     hasNode(name: string): boolean;
@@ -11,8 +33,85 @@ export declare class DependencyGraph {
     getDependencies(name: string): string[];
     getDependents(name: string): string[];
     isCyclic(): boolean;
-    order(): string[];
+    /**
+     * Validates that the graph has no cycles.
+     * Returns an object with hasCycle boolean and the cycle path if found.
+     * @returns {hasCycle: boolean, path?: string[]} - hasCycle is true if a cycle exists, path contains the cycle nodes
+     */
+    validateNoCycles(): {
+        hasCycle: boolean;
+        path?: string[];
+    };
+    order(options?: {
+        allowCycles?: boolean;
+    }): string[];
     clear(): void;
     getNodes(): string[];
     getAllEdges(): [string, string][];
+    /**
+     * Returns all nodes that have no dependants (i.e., no other node depends on them).
+     * In graph terms, nodes with zero incoming edges.
+     */
+    getNodesWithNoDependants(): string[];
+    /** Return nodes filtered by kind */
+    getNodesByKind(kind: K): string[];
+    /** Roots by kind (zero incoming) */
+    getRootsByKind(kind?: K): string[];
+    /** Leaves by kind (zero outgoing) */
+    getLeavesByKind(kind?: K): string[];
+    /** Filter dependencies of a node by kind */
+    getDependenciesOfKind(name: string, kind: K): string[];
+    /** Filter dependents of a node by kind */
+    getDependentsOfKind(name: string, kind: K): string[];
+    /**
+     * Create execution batches (topological levels). Throws if the graph has a cycle.
+     * If filterKinds is provided, batches contain only nodes of these kinds, but readiness
+     * is evaluated against the complete graph.
+     */
+    plan(options?: {
+        filterKinds?: K[];
+    }): {
+        batches: string[][];
+    };
+    /**
+     * Impact analysis: return nodes impacted by a set of changed nodes.
+     * direction:
+     *  - 'downstream': nodes that depend (directly/indirectly) on changed
+     *  - 'upstream': nodes that changed depends on
+     *  - 'both': union of upstream and downstream
+     */
+    getImpactedNodes(changed: string[] | Set<string>, direction?: 'downstream' | 'upstream' | 'both', filterKinds?: K[]): string[];
+    toJSON(): {
+        nodes: Array<{
+            name: string;
+            kind?: K;
+            meta?: M;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+        }>;
+    };
+    static fromJSON<KK extends string, MM = any>(data: {
+        nodes: Array<{
+            name: string;
+            kind?: KK;
+            meta?: MM;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+        }>;
+    }): DependencyGraph<KK, MM>;
+    diff(other: DependencyGraph<K, any>): {
+        addedNodes: string[];
+        removedNodes: string[];
+        addedEdges: [string, string][];
+        removedEdges: [string, string][];
+        kindChanges: Array<{
+            name: string;
+            from?: K;
+            to?: K;
+        }>;
+    };
 }

package/dist/esm/index.d.ts

@@ -1,12 +1,16 @@
 export * from './analytics.controller';
+export * from './attribute-dependency-graph';
 export * from './cache.controller';
 export * from './changeDetection';
 export * from './computeSuggestions';
+export * from './date-utils';
+export * from './deep-query.service';
 export * from './dependency-graph';
 export * from './getAggregation';
 export * from './getFacets';
 export * from './helper';
 export * from './indices.controller';
+export * from './logger';
 export * from './performance';
 export * from './pivot';
 export * from './property-parser';