harperdb 4.6.6 → 4.7.0-alpha.2

package/components/requestRestart.d.ts

@@ -0,0 +1,3 @@
+export declare function requestRestart(): void;
+export declare function restartNeeded(): boolean;
+export declare function resetRestartNeeded(): void;

package/components/status/ComponentStatus.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ComponentStatus Class
+ *
+ * This module contains the ComponentStatus class which represents an individual
+ * component's status with methods for status management.
+ */
+import { ComponentStatusLevel } from './types.ts';
+/**
+ * Component status information class
+ */
+export declare class ComponentStatus {
+    /** Last time this status was checked/updated */
+    lastChecked: Date;
+    /** Current status level */
+    status: ComponentStatusLevel;
+    /** Human-readable status message */
+    message?: string;
+    /** Error information if status is 'error' */
+    error?: Error | string;
+    constructor(status: ComponentStatusLevel, message?: string, error?: Error | string);
+    /**
+     * Update the status level and refresh the timestamp
+     */
+    updateStatus(status: ComponentStatusLevel, message?: string): void;
+    /**
+     * Set status to healthy
+     */
+    markHealthy(message?: string): void;
+    /**
+     * Set status to error
+     */
+    markError(error: Error | string, message?: string): void;
+    /**
+     * Set status to warning
+     */
+    markWarning(message: string): void;
+    /**
+     * Set status to loading
+     */
+    markLoading(message?: string): void;
+    /**
+     * Check if component is healthy
+     */
+    isHealthy(): boolean;
+    /**
+     * Check if component has an error
+     */
+    hasError(): boolean;
+    /**
+     * Check if component is loading
+     */
+    isLoading(): boolean;
+    /**
+     * Check if component has a warning
+     */
+    hasWarning(): boolean;
+    /**
+     * Get a summary string of the component status
+     */
+    getSummary(): string;
+}

package/components/status/ComponentStatusRegistry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ComponentStatusRegistry Class
+ *
+ * This module contains the ComponentStatusRegistry class which provides
+ * centralized management of component health status.
+ */
+import { ComponentStatus } from './ComponentStatus.ts';
+import { ComponentStatusLevel, AggregatedComponentStatus } from './types.ts';
+/**
+ * Map of component names to their status information
+ */
+export type ComponentStatusMap = Map<string, ComponentStatus>;
+/**
+ * Component Status Registry Class
+ * Provides a centralized registry for managing component health status
+ */
+export declare class ComponentStatusRegistry {
+    private statusMap;
+    /**
+     * Reset the component status registry, clearing all existing status data
+     * This should be called when the component system starts up
+     */
+    reset(): void;
+    /**
+     * Register or update component health status
+     * This function allows components to report their own health status
+     */
+    setStatus(componentName: string, status: ComponentStatusLevel, message?: string, error?: Error | string): void;
+    /**
+     * Get the current status of a component
+     */
+    getStatus(componentName: string): ComponentStatus | undefined;
+    /**
+     * Get all component statuses
+     */
+    getAllStatuses(): ComponentStatusMap;
+    /**
+     * Report component as healthy
+     */
+    reportHealthy(componentName: string, message?: string): void;
+    /**
+     * Report component error
+     */
+    reportError(componentName: string, error: Error | string, message?: string): void;
+    /**
+     * Report component warning
+     */
+    reportWarning(componentName: string, message: string): void;
+    /**
+     * Component Lifecycle Management
+     */
+    /**
+     * Initialize component as loading - call this when component loading begins
+     */
+    initializeLoading(componentName: string, message?: string): void;
+    /**
+     * Mark component as successfully loaded
+     */
+    markLoaded(componentName: string, message?: string): void;
+    /**
+     * Mark component as failed to load
+     */
+    markFailed(componentName: string, error: Error | string, message?: string): void;
+    /**
+     * Get all components with a specific status level
+     */
+    getComponentsByStatus(statusLevel: ComponentStatusLevel): Array<{
+        name: string;
+        status: ComponentStatus;
+    }>;
+    /**
+     * Get a summary of all component statuses
+     */
+    getStatusSummary(): Record<ComponentStatusLevel, number>;
+    /**
+     * Static method to get aggregated component statuses from all threads
+     * Returns a Map with one entry per component showing overall status and thread distribution
+     */
+    static getAggregatedFromAllThreads(registry: ComponentStatusRegistry): Promise<Map<string, AggregatedComponentStatus>>;
+}

package/components/status/api.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Component Status Public API
+ *
+ * This module provides the clean, simple public API for component status tracking.
+ * All internal implementation details are hidden behind this interface.
+ */
+import { ComponentStatus } from './ComponentStatus.ts';
+/**
+ * Component Status Builder
+ * Provides a fluent interface for reporting component status
+ */
+export declare class ComponentStatusBuilder {
+    private componentName;
+    constructor(componentName: string);
+    /**
+     * Report component as healthy
+     * @param message Optional status message
+     * @returns this for chaining
+     */
+    healthy(message?: string): this;
+    /**
+     * Report component warning
+     * @param message Warning message (required for warnings)
+     * @returns this for chaining
+     */
+    warning(message: string): this;
+    /**
+     * Report component error
+     * @param message Error message
+     * @param error Optional error object for additional context
+     * @returns this for chaining
+     */
+    error(message: string, error?: Error): this;
+    /**
+     * Report component as loading
+     * @param message Optional loading message
+     * @returns this for chaining
+     */
+    loading(message?: string): this;
+    /**
+     * Report component status as unknown
+     * @param message Optional message explaining why status is unknown
+     * @returns this for chaining
+     */
+    unknown(message?: string): this;
+    /**
+     * Get the current status of this component
+     * @returns Current component status or undefined if not set
+     */
+    get(): ComponentStatus | undefined;
+}
+/**
+ * Get a status builder for a component
+ * This is the primary API for reporting component status
+ *
+ * @example
+ * ```typescript
+ * // Report status
+ * statusForComponent('my-service').healthy('Service started');
+ * statusForComponent('database').error('Connection failed', err);
+ * statusForComponent('cache').warning('Memory usage high');
+ *
+ * // Get status
+ * const status = statusForComponent('my-service').get();
+ * ```
+ */
+export declare function statusForComponent(name: string): ComponentStatusBuilder;
+/**
+ * Component lifecycle hooks for internal use
+ * These are used by the component loader
+ */
+export declare const lifecycle: {
+    /**
+     * Mark component as starting to load
+     */
+    loading(componentName: string, message?: string): void;
+    /**
+     * Mark component as successfully loaded
+     */
+    loaded(componentName: string, message?: string): void;
+    /**
+     * Mark component as failed to load
+     */
+    failed(componentName: string, error: Error | string, message?: string): void;
+};
+/**
+ * Reset all component statuses (useful for testing)
+ */
+export declare function reset(): void;
+/**
+ * Status level constants for external use
+ */
+export declare const STATUS: {
+    readonly HEALTHY: "healthy";
+    readonly WARNING: "warning";
+    readonly ERROR: "error";
+    readonly UNKNOWN: "unknown";
+    readonly LOADING: "loading";
+};
+/**
+ * Re-export only the types that external users need
+ */
+export type { ComponentStatusLevel, AggregatedComponentStatus } from './types.ts';
+export type { ComponentStatus } from './ComponentStatus.ts';

package/components/status/crossThread.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Cross-Thread Component Status Collection
+ *
+ * This module handles collecting component status information from all worker threads
+ * and aggregating it into a unified view.
+ */
+import { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
+import { ComponentStatusSummary, AggregatedComponentStatus } from './types.ts';
+/**
+ * CrossThreadStatusCollector Class
+ * Handles collection of component status from all worker threads
+ */
+export declare class CrossThreadStatusCollector {
+    private awaitingResponses;
+    private responseCheckers;
+    private nextRequestId;
+    private listenerAttached;
+    private readonly timeout;
+    private cleanupTimer;
+    constructor(timeoutMs?: number);
+    /**
+     * Attach the message listener for cross-thread responses
+     * This is done once per collector instance to avoid duplicate listeners
+     */
+    private attachListener;
+    /**
+     * Schedule cleanup of stale requests if needed
+     */
+    private scheduleCleanup;
+    /**
+     * Collect component status information from all threads
+     * Returns a Map with component names namespaced by worker index
+     */
+    collect(registry: ComponentStatusRegistry): Promise<Map<string, ComponentStatusSummary>>;
+    /**
+     * Get status from local thread only (fallback when cross-thread collection fails)
+     */
+    private getLocalStatusOnly;
+    /**
+     * Clean up any pending requests and timers (useful for testing)
+     */
+    cleanup(): void;
+}
+/**
+ * StatusAggregator Class
+ * Handles aggregation of component statuses from multiple threads
+ */
+export declare class StatusAggregator {
+    /**
+     * Aggregate component statuses from multiple threads into aggregated view
+     */
+    static aggregate(allStatuses: Map<string, ComponentStatusSummary>): Map<string, AggregatedComponentStatus>;
+    /**
+     * Aggregate status entries for a single component across threads
+     */
+    private static aggregateComponentGroup;
+    /**
+     * Determine overall status based on priority
+     */
+    private static determineOverallStatus;
+}
+export declare const crossThreadCollector: CrossThreadStatusCollector;

package/components/status/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Component Status Error Types
+ *
+ * This module defines specific error types for the component status system,
+ * providing better diagnostics and error handling capabilities.
+ */
+/**
+ * Base error class for component status system
+ */
+export declare class ComponentStatusError extends Error {
+    readonly statusCode: number;
+    readonly timestamp: Date;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Error thrown when cross-thread status collection times out
+ */
+export declare class CrossThreadTimeoutError extends ComponentStatusError {
+    readonly requestId: number;
+    readonly timeoutMs: number;
+    readonly collectedCount: number;
+    constructor(requestId: number, timeoutMs: number, collectedCount: number);
+}
+/**
+ * Error thrown when ITC (Inter-Thread Communication) fails
+ */
+export declare class ITCError extends ComponentStatusError {
+    readonly operation: string;
+    readonly cause?: Error;
+    constructor(operation: string, cause?: Error);
+}
+/**
+ * Error thrown when component status aggregation fails
+ */
+export declare class AggregationError extends ComponentStatusError {
+    readonly componentCount: number;
+    readonly cause?: Error;
+    constructor(componentCount: number, cause?: Error);
+}
+/**
+ * Error thrown when a component status operation fails
+ */
+export declare class ComponentStatusOperationError extends ComponentStatusError {
+    readonly componentName: string;
+    readonly operation: string;
+    constructor(componentName: string, operation: string, message: string);
+}
+/**
+ * Information about cross-thread collection results
+ */
+export interface CrossThreadCollectionResult {
+    success: boolean;
+    collectedFromThreads: number;
+    expectedThreads?: number;
+    timedOutThreads: number[];
+    errors: Error[];
+}
+/**
+ * Error thrown with detailed cross-thread collection diagnostics
+ */
+export declare class CrossThreadCollectionError extends ComponentStatusError {
+    readonly result: CrossThreadCollectionResult;
+    constructor(result: CrossThreadCollectionResult);
+    /**
+     * Get detailed diagnostic information
+     */
+    getDiagnostics(): string;
+}

package/components/status/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Component Status System
+ *
+ * A simple, clean API for tracking component health across Harper's distributed architecture.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * import { statusForComponent, STATUS } from './components/status';
+ *
+ * // Report component status
+ * statusForComponent('my-service').healthy('Service initialized');
+ * statusForComponent('database').error('Connection timeout', error);
+ * statusForComponent('cache').warning('High memory usage');
+ *
+ * // Get component status
+ * const status = statusForComponent('my-service').get();
+ * ```
+ *
+ * @example Lifecycle usage (for component loader):
+ * ```typescript
+ * import { lifecycle } from './components/status';
+ *
+ * lifecycle.loading('my-component');
+ * // ... load component ...
+ * lifecycle.loaded('my-component', 'Successfully initialized');
+ * // or
+ * lifecycle.failed('my-component', error);
+ * ```
+ */
+export { statusForComponent, // Main API for reporting status
+lifecycle, // Component loader lifecycle hooks
+reset, // Reset all statuses (testing)
+STATUS } from './api.ts';
+export type { ComponentStatusLevel, AggregatedComponentStatus, ComponentStatus } from './api.ts';
+export * as internal from './internal.ts';

package/components/status/internal.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Internal Component Status Exports
+ *
+ * These exports are for Harper core internal use only.
+ * Components should use the public API from index.ts
+ */
+import type { ComponentStatusLevel } from './types.ts';
+export { ComponentStatus } from './ComponentStatus.ts';
+export { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
+export { CrossThreadStatusCollector, StatusAggregator, crossThreadCollector } from './crossThread.ts';
+export type { ComponentStatusMap } from './ComponentStatusRegistry.ts';
+export { componentStatusRegistry } from './registry.ts';
+export * from './errors.ts';
+export * from './types.ts';
+export declare const query: {
+    /**
+     * Get a single component's status
+     */
+    get(componentName: string): import("./ComponentStatus.ts").ComponentStatus;
+    /**
+     * Get all component statuses in the current thread
+     */
+    all(): import("./ComponentStatusRegistry.ts").ComponentStatusMap;
+    /**
+     * Get components by status level
+     */
+    byStatus(status: ComponentStatusLevel): {
+        name: string;
+        status: import("./ComponentStatus.ts").ComponentStatus;
+    }[];
+    /**
+     * Get a summary of component statuses
+     */
+    summary(): Record<ComponentStatusLevel, number>;
+    /**
+     * Get aggregated status from all threads
+     * This is an async operation that collects status from all worker threads
+     */
+    allThreads(): Promise<Map<string, import("./types.ts").AggregatedComponentStatus>>;
+};

package/components/status/registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Component Status Registry Singleton
+ *
+ * This module provides the global component status registry instance.
+ */
+import { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
+/**
+ * Global component status registry instance
+ */
+export declare const componentStatusRegistry: ComponentStatusRegistry;

package/components/status/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Component Status Type Definitions
+ *
+ * This module defines the core types, constants, and interfaces for the
+ * component status tracking system.
+ */
+/**
+ * Status levels for components
+ */
+export declare const COMPONENT_STATUS_LEVELS: {
+    readonly HEALTHY: "healthy";
+    readonly WARNING: "warning";
+    readonly ERROR: "error";
+    readonly UNKNOWN: "unknown";
+    readonly LOADING: "loading";
+};
+export type ComponentStatusLevel = typeof COMPONENT_STATUS_LEVELS[keyof typeof COMPONENT_STATUS_LEVELS];
+/**
+ * Component status information as a plain object
+ */
+export interface ComponentStatusSummary {
+    /** Last time this status was checked/updated */
+    lastChecked: Date;
+    /** Current status level */
+    status: ComponentStatusLevel;
+    /** Human-readable status message */
+    message?: string;
+    /** Error information if status is 'error' */
+    error?: Error | string;
+    /** Worker index for cross-thread tracking */
+    workerIndex?: number;
+}
+/**
+ * Abnormal component status information for a specific thread
+ */
+export interface ComponentStatusAbnormality {
+    /** Worker index for the thread with abnormal status */
+    workerIndex: number;
+    /** The abnormal status level */
+    status: ComponentStatusLevel;
+    /** Status message for this abnormal instance */
+    message?: string;
+    /** Error information if status is 'error' */
+    error?: Error | string;
+}
+/**
+ * Aggregated component status with thread information
+ */
+export interface AggregatedComponentStatus {
+    /** Component name (without thread suffix) */
+    componentName: string;
+    /** Overall status - error if any thread has error, warning if any has warning, etc */
+    status: ComponentStatusLevel;
+    /** Last checked times for each thread (ms since epoch) */
+    lastChecked: {
+        /** Main thread last checked time (if component runs on main) */
+        main?: number;
+        /** Worker thread last checked times indexed by worker number */
+        workers: Record<number, number>;
+    };
+    /** Map of thread-specific statuses if they differ (only populated when inconsistent) */
+    abnormalities?: Map<string, ComponentStatusAbnormality>;
+    /** Most recent message across all threads */
+    latestMessage?: string;
+    /** Any error from any thread */
+    error?: Error | string;
+}
+/**
+ * Component status information from a worker thread
+ */
+export interface WorkerComponentStatuses {
+    workerIndex: number | undefined;
+    isMainThread: boolean;
+    statuses: Array<[string, ComponentStatusSummary]>;
+}

package/json/systemSchema.json

@@ -98,21 +98,82 @@
 		]
 	},
 	"hdb_license": {
-		"hash_attribute": "license_key",
-		"name": "hdb_license",
-		"schema": "system",
+		"primaryKey": "id",
+		"table": "hdb_license",
+		"database": "system",
+		"audit": true,
 		"attributes": [
 			{
-				"attribute": "license_key"
+				"attribute": "id"
 			},
 			{
-				"attribute": "company"
+				"name": "level"
 			},
 			{
-				"attribute": "__createdtime__"
+				"name": "region",
+				"indexed": true
 			},
 			{
-				"attribute": "__updatedtime__"
+				"name": "reads"
+			},
+			{
+				"name": "writes"
+			},
+			{
+				"name": "readBytes"
+			},
+			{
+				"name": "writeBytes"
+			},
+			{
+				"name": "realTimeMessages"
+			},
+			{
+				"name": "realTimeBytes"
+			},
+			{
+				"name": "cpuTime"
+			},
+			{
+				"name": "storage"
+			},
+			{
+				"name": "usedReads"
+			},
+			{
+				"name": "usedWrites"
+			},
+			{
+				"name": "usedReadBytes"
+			},
+			{
+				"name": "usedWriteBytes"
+			},
+			{
+				"name": "usedRealTimeMessages"
+			},
+			{
+				"name": "usedRealTimeBytes"
+			},
+			{
+				"name": "usedCpuTime"
+			},
+			{
+				"name": "usedStorage"
+			},
+			{
+				"name": "expiration"
+			},
+			{
+				"name": "autoRenew"
+			},
+			{
+				"name": "__createdtime__",
+				"indexed": true
+			},
+			{
+				"name": "__updatedtime__",
+				"indexed": true
 			}
 		]
 	},