@servlyadmin/runtime-core 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -449,14 +449,19 @@ declare function resolveBindingPath(path: string, context: BindingContext): any;
  *
  * @param template - The template string containing {{path}} bindings
  * @param context - The binding context
+ * @param componentId - Optional component ID for error tracking
  * @returns The resolved string
  */
-declare function resolveTemplate(template: string, context: BindingContext): string;
+declare function resolveTemplate(template: string, context: BindingContext, componentId?: string): string;
 /**
  * Resolve a template and return the raw value (not stringified)
  * Useful for non-string values like objects, arrays, booleans
+ *
+ * @param template - The template string
+ * @param context - The binding context
+ * @param componentId - Optional component ID for error tracking
  */
-declare function resolveTemplateValue(template: string, context: BindingContext): any;
+declare function resolveTemplateValue(template: string, context: BindingContext, componentId?: string): any;
 /**
  * Recursively resolve all template bindings in an object or array
  *
@@ -772,4 +777,428 @@ declare function collectAllDependencies(rootId: string, rootVersion: string, fet
  */
 declare function detectCircularDependencies(manifest: DependencyManifest): string[] | null;
 
-export { type Assertion$1 as Assertion, type AssertionResult$1 as AssertionResult, type BindingContext, type BundleStrategy, type BundledComponent, type CacheConfig, type CacheEntry, type CacheStrategy, type ComponentBundle, type ComponentData, type ComponentRegistry, DEFAULT_CACHE_CONFIG, DEFAULT_RETRY_CONFIG, type DependencyEntry, type DependencyManifest, type DependencyType, type ElementConfig, type FetchOptions, type FetchResult, type LayoutElement, type ParsedVersion, type PropDefinition, type RenderOptions, type RenderResult, type RetryConfig, type AssertionResult as TestAssertionResult, type TestCase$1 as TestCase, type TestCase as TestCaseInput, type TestCaseResult, type TestResult, type TestSummary as TestRunSummary, type TestSummary$1 as TestSummary, applyStyles, batchFetchComponents, buildClassName, buildElementStyles, buildRegistryFromBundle, bumpVersion, camelToKebab, clearAllCaches, clearLocalStorageCache, clearMemoryCache, clearStyles, collectAllDependencies, compareVersions, createRegistry, detectCircularDependencies, extractBindingKeys, extractDependencies, extractDependenciesFromCode, fetchComponent, fetchComponentWithDependencies, formatStyleValue, formatVersion, generateTestCases, getCacheKey, getDependencyTree, getFromCache, getMemoryCacheSize, getRegistryUrl, hasTemplateSyntax, invalidateCache, isComponentAvailable, isValidSpecifier, parseVersion, prefetchComponents, processStyles, render, renderDynamicList, resolveBindingPath, resolveTemplate, resolveTemplateValue, resolveTemplatesDeep, resolveVersion, runAllTests, runTestCase, satisfiesVersion, setInCache, setRegistryUrl, updateStyles, validateAssertion, validateProps };
+/**
+ * Component Analytics Types
+ * Type definitions for analytics event collection and transmission
+ */
+/**
+ * Analytics configuration options
+ */
+interface AnalyticsConfig {
+    /** Enable/disable analytics collection */
+    enabled: boolean;
+    /** Analytics API endpoint */
+    endpoint: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Application ID to include in all events */
+    appId?: string;
+    /** Batch size before auto-flush */
+    batchSize: number;
+    /** Flush interval in milliseconds */
+    flushInterval: number;
+    /** Sample rate (0-1) for high-volume events */
+    sampleRate: number;
+    /** Environment identifier */
+    environment: 'development' | 'staging' | 'production';
+    /** Enable debug logging */
+    debug: boolean;
+}
+/**
+ * Analytics event types
+ */
+type AnalyticsEventType = 'render' | 'fetch' | 'error';
+/**
+ * Base analytics event
+ */
+interface AnalyticsEvent {
+    /** Event type */
+    type: AnalyticsEventType;
+    /** Component identifier */
+    componentId: string;
+    /** Component version */
+    version: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Anonymous session ID */
+    sessionId?: string;
+    /** Application ID */
+    appId?: string;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Event-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata for render events
+ */
+interface RenderMetadata {
+    /** Number of DOM elements rendered */
+    elementCount?: number;
+    /** Whether component was served from cache */
+    fromCache?: boolean;
+    /** Memory heap change in KB (Chrome only) */
+    heapDeltaKB?: number;
+    /** Number of DOM nodes created */
+    domNodesCreated?: number;
+    /** Number of long tasks (>50ms) during render */
+    longTaskCount?: number;
+    /** Whether component has event handlers */
+    hasEventHandlers?: boolean;
+    /** Whether component has dependencies */
+    hasDependencies?: boolean;
+}
+/**
+ * Metadata for fetch events
+ */
+interface FetchMetadata {
+    /** Whether fetch was a cache hit */
+    cacheHit: boolean;
+    /** Fetch duration in milliseconds */
+    fetchDuration: number;
+    /** Bundle size in bytes */
+    bundleSize?: number;
+    /** Number of dependencies */
+    dependencyCount?: number;
+}
+/**
+ * Error types for error events
+ */
+type ErrorType = 'render' | 'fetch' | 'binding';
+/**
+ * Metadata for error events
+ */
+interface ErrorMetadata {
+    /** Type of error */
+    errorType: ErrorType;
+    /** Error message (max 1000 chars) */
+    errorMessage: string;
+    /** Stack trace (truncated to 500 chars) */
+    stackTrace?: string;
+    /** Failed binding path (for binding errors) */
+    bindingPath?: string;
+    /** Element ID where error occurred */
+    elementId?: string;
+}
+/**
+ * Client info included in batch requests
+ */
+interface ClientInfo {
+    /** SDK version */
+    sdkVersion: string;
+    /** Environment */
+    environment: string;
+}
+/**
+ * Batch events request body
+ */
+interface BatchEventsRequest {
+    /** Array of analytics events */
+    events: AnalyticsEvent[];
+    /** Client information */
+    clientInfo: ClientInfo;
+}
+/**
+ * Batch events response
+ */
+interface BatchEventsResponse {
+    /** Whether request was successful */
+    success: boolean;
+    /** Number of events accepted */
+    accepted: number;
+    /** Number of events rejected */
+    rejected: number;
+    /** Error messages for rejected events */
+    errors?: string[];
+    /** Retry-After header value (for rate limiting) */
+    retryAfter?: number;
+}
+/**
+ * Session information
+ */
+interface SessionInfo {
+    /** Session ID */
+    id: string;
+    /** Timestamp when session was created */
+    createdAt: number;
+    /** Timestamp of last activity */
+    lastActivityAt: number;
+}
+
+/**
+ * Component Analytics
+ * Collects and transmits component usage, performance, and error metrics
+ */
+
+/**
+ * Analytics Collector class
+ * Manages event collection, batching, and transmission
+ */
+declare class AnalyticsCollector {
+    private config;
+    private eventQueue;
+    private flushTimer;
+    private isEnabled;
+    private isFlushing;
+    private retryDelay;
+    constructor(config?: Partial<AnalyticsConfig>);
+    /**
+     * Configure analytics
+     */
+    configure(config: Partial<AnalyticsConfig>): void;
+    /**
+     * Disable analytics collection
+     */
+    disable(): void;
+    /**
+     * Enable analytics collection
+     */
+    enable(): void;
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+    /**
+     * Track component render
+     */
+    trackRender(componentId: string, version: string, duration: number, metadata?: RenderMetadata): void;
+    /**
+     * Track component fetch
+     */
+    trackFetch(componentId: string, version: string, duration: number, fromCache: boolean, metadata?: Partial<FetchMetadata>): void;
+    /**
+     * Track error
+     */
+    trackError(componentId: string, version: string, error: Error, context?: Partial<ErrorMetadata>): void;
+    /**
+     * Check if event should be tracked (sampling + enabled)
+     */
+    private shouldTrack;
+    /**
+     * Add event to queue
+     */
+    private queueEvent;
+    /**
+     * Get current queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Start the flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Stop the flush timer
+     */
+    private stopFlushTimer;
+    /**
+     * Flush events to server
+     */
+    flush(): Promise<void>;
+    /**
+     * Perform the actual flush
+     */
+    private doFlush;
+    /**
+     * Send events to the API
+     */
+    private sendEvents;
+    /**
+     * Handle failed events (partial success)
+     */
+    private handleFailedEvents;
+    /**
+     * Handle network error
+     */
+    private handleNetworkError;
+    /**
+     * Schedule a retry flush
+     */
+    private scheduleRetry;
+    /**
+     * Truncate string to max length
+     */
+    private truncateString;
+    /**
+     * Log debug message
+     */
+    private log;
+}
+/**
+ * Get the analytics collector singleton
+ */
+declare function getAnalytics(): AnalyticsCollector;
+/**
+ * Configure analytics (convenience function)
+ */
+declare function configureAnalytics(config: Partial<AnalyticsConfig>): void;
+/**
+ * Reset analytics (for testing)
+ */
+declare function resetAnalytics(): void;
+declare const analytics: {
+    readonly instance: AnalyticsCollector;
+    configure: typeof configureAnalytics;
+    trackRender: (componentId: string, version: string, duration: number, metadata?: RenderMetadata) => void;
+    trackFetch: (componentId: string, version: string, duration: number, fromCache: boolean, metadata?: Partial<FetchMetadata>) => void;
+    trackError: (componentId: string, version: string, error: Error, context?: Partial<ErrorMetadata>) => void;
+    flush: () => Promise<void>;
+    disable: () => void;
+    enable: () => void;
+};
+
+/**
+ * Session Manager
+ * Manages anonymous session IDs for analytics tracking
+ */
+
+/**
+ * Session Manager class
+ * Manages anonymous session IDs with automatic rotation
+ */
+declare class SessionManager {
+    private session;
+    constructor();
+    /**
+     * Initialize session manager
+     */
+    private initialize;
+    /**
+     * Create a new session
+     */
+    private createNewSession;
+    /**
+     * Get current session ID
+     * Creates new session if expired
+     */
+    getSessionId(): string;
+    /**
+     * Update last activity timestamp
+     */
+    touch(): void;
+    /**
+     * Force create a new session
+     */
+    rotate(): void;
+    /**
+     * Clear current session
+     */
+    clear(): void;
+    /**
+     * Get session info (for debugging)
+     */
+    getSessionInfo(): SessionInfo | null;
+}
+/**
+ * Get the session manager singleton
+ */
+declare function getSessionManager(): SessionManager;
+/**
+ * Reset the session manager (for testing)
+ */
+declare function resetSessionManager(): void;
+
+/**
+ * Memory Sampler
+ * Samples memory usage using Chrome's performance.memory API
+ * Gracefully degrades on unsupported browsers
+ */
+/**
+ * Memory sample data
+ */
+interface MemorySample {
+    /** Used JS heap size in KB */
+    heapUsedKB: number;
+    /** Total JS heap size in KB */
+    heapTotalKB: number;
+    /** Timestamp when sample was taken */
+    timestamp: number;
+}
+/**
+ * Memory Sampler class
+ * Provides memory sampling functionality for Chrome browsers
+ */
+declare class MemorySampler {
+    private isSupported;
+    constructor();
+    /**
+     * Check if memory API is available
+     */
+    private checkSupport;
+    /**
+     * Check if memory sampling is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Take a memory sample
+     * Returns null if memory API is not available
+     */
+    sample(): MemorySample | null;
+    /**
+     * Calculate heap delta between two samples
+     * Returns the difference in KB (positive = memory increased)
+     */
+    calculateDelta(before: MemorySample | null, after: MemorySample | null): number | null;
+}
+/**
+ * Get the memory sampler singleton
+ */
+declare function getMemorySampler(): MemorySampler;
+/**
+ * Reset the memory sampler (for testing)
+ */
+declare function resetMemorySampler(): void;
+
+/**
+ * Long Task Observer
+ * Observes long tasks (>50ms) using PerformanceObserver API
+ * Gracefully degrades on unsupported browsers
+ */
+/**
+ * Long Task Observer class
+ * Counts tasks that take longer than 50ms during a measurement period
+ */
+declare class LongTaskObserver {
+    private observer;
+    private longTaskCount;
+    private isSupported;
+    private isObserving;
+    constructor();
+    /**
+     * Check if PerformanceObserver with longtask support is available
+     */
+    private checkSupport;
+    /**
+     * Check if long task observation is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Start observing long tasks
+     */
+    start(): void;
+    /**
+     * Stop observing and return the count of long tasks
+     */
+    stop(): number;
+    /**
+     * Reset the long task counter
+     */
+    reset(): void;
+    /**
+     * Get current count without stopping observation
+     */
+    getCount(): number;
+    /**
+     * Check if currently observing
+     */
+    isActive(): boolean;
+}
+/**
+ * Get the long task observer singleton
+ */
+declare function getLongTaskObserver(): LongTaskObserver;
+/**
+ * Reset the long task observer (for testing)
+ */
+declare function resetLongTaskObserver(): void;
+
+export { AnalyticsCollector, type AnalyticsConfig, type AnalyticsEvent, type AnalyticsEventType, type Assertion$1 as Assertion, type AssertionResult$1 as AssertionResult, type BatchEventsRequest, type BatchEventsResponse, type BindingContext, type BundleStrategy, type BundledComponent, type CacheConfig, type CacheEntry, type CacheStrategy, type ClientInfo, type ComponentBundle, type ComponentData, type ComponentRegistry, DEFAULT_CACHE_CONFIG, DEFAULT_RETRY_CONFIG, type DependencyEntry, type DependencyManifest, type DependencyType, type ElementConfig, type ErrorMetadata, type ErrorType, type FetchMetadata, type FetchOptions, type FetchResult, type LayoutElement, LongTaskObserver, MemorySampler, type ParsedVersion, type PropDefinition, type RenderMetadata, type RenderOptions, type RenderResult, type RetryConfig, type SessionInfo, SessionManager, type AssertionResult as TestAssertionResult, type TestCase$1 as TestCase, type TestCase as TestCaseInput, type TestCaseResult, type TestResult, type TestSummary as TestRunSummary, type TestSummary$1 as TestSummary, analytics, applyStyles, batchFetchComponents, buildClassName, buildElementStyles, buildRegistryFromBundle, bumpVersion, camelToKebab, clearAllCaches, clearLocalStorageCache, clearMemoryCache, clearStyles, collectAllDependencies, compareVersions, configureAnalytics, createRegistry, detectCircularDependencies, extractBindingKeys, extractDependencies, extractDependenciesFromCode, fetchComponent, fetchComponentWithDependencies, formatStyleValue, formatVersion, generateTestCases, getAnalytics, getCacheKey, getDependencyTree, getFromCache, getLongTaskObserver, getMemoryCacheSize, getMemorySampler, getRegistryUrl, getSessionManager, hasTemplateSyntax, invalidateCache, isComponentAvailable, isValidSpecifier, parseVersion, prefetchComponents, processStyles, render, renderDynamicList, resetAnalytics, resetLongTaskObserver, resetMemorySampler, resetSessionManager, resolveBindingPath, resolveTemplate, resolveTemplateValue, resolveTemplatesDeep, resolveVersion, runAllTests, runTestCase, satisfiesVersion, setInCache, setRegistryUrl, updateStyles, validateAssertion, validateProps };