@happyvertical/smrt-core 0.30.0

package/dist/class.d.ts

@@ -0,0 +1,313 @@
+import { AIClientOptions, AIClient } from '@happyvertical/ai';
+import { FilesystemAdapterOptions, FilesystemAdapter } from '@happyvertical/files';
+import { LoggerConfig } from '@happyvertical/logger';
+import { AiUsageListOptions, AiUsageSnapshot, AiUsageStats, AiUsageSummaryOptions, SignalAdapter, SmrtAiUsageRecord } from '@happyvertical/smrt-types';
+import { DatabaseInterface } from '@happyvertical/sql';
+import { AiUsageConfig, MetricsConfig, PubSubConfig } from './config.js';
+import { DatabaseConfig } from './database.js';
+import { SignalBus } from './signals/bus.js';
+/**
+ * Configuration options for the SmrtClass
+ */
+export interface SmrtClassOptions {
+    /**
+     * Optional custom class name override
+     */
+    _className?: string;
+    /**
+     * Database configuration - unified approach matching @happyvertical/sql
+     *
+     * Supports three formats:
+     * - String shortcut: 'products.db' (auto-detects database type)
+     * - Config object: { type: 'sqlite', url: 'products.db' }
+     * - DatabaseInterface instance: await getDatabase(...)
+     *
+     * @see DatabaseConfig for type definition
+     */
+    db?: DatabaseConfig;
+    /**
+     * Alias for db option - for backward compatibility with documentation
+     *
+     * @deprecated Use 'db' instead. This alias exists for backward compatibility.
+     */
+    persistence?: DatabaseConfig;
+    /**
+     * Filesystem adapter configuration options
+     */
+    fs?: FilesystemAdapterOptions;
+    /**
+     * AI client configuration options or instance
+     */
+    ai?: AIClientOptions | AIClient;
+    /**
+     * AI usage tracking configuration (overrides global defaults)
+     */
+    usage?: AiUsageConfig;
+    /**
+     * Logging configuration (overrides global default)
+     */
+    logging?: LoggerConfig;
+    /**
+     * Metrics configuration (overrides global default)
+     */
+    metrics?: MetricsConfig;
+    /**
+     * Pub/Sub configuration (overrides global default)
+     */
+    pubsub?: PubSubConfig;
+    /**
+     * Sanitization configuration (overrides global default)
+     */
+    sanitization?: import('./config.js').GlobalSignalConfig['sanitization'];
+    /**
+     * Custom signal configuration (overrides global default)
+     */
+    signals?: {
+        /** Shared signal bus instance */
+        bus?: SignalBus;
+        /** Additional custom adapters */
+        adapters?: SignalAdapter[];
+    };
+    /**
+     * Internal flag to reuse an already initialized DatabaseInterface instance.
+     *
+     * Skips database resolution and system-table setup during lightweight hydration.
+     * @internal
+     */
+    _reuseInitializedDb?: boolean;
+    /**
+     * Internal flag to defer runtime-only services such as signals and AI setup.
+     *
+     * Lightweight hydration paths set this so plain query reads avoid per-row
+     * runtime bootstrap costs.
+     * @internal
+     */
+    _deferRuntimeInitialization?: boolean;
+}
+/**
+ * Foundation class providing core functionality for the SMRT framework
+ *
+ * SmrtClass provides unified access to database, filesystem, and AI client
+ * interfaces. It serves as the foundation for all other classes in the
+ * SMRT framework.
+ */
+export declare class SmrtClass {
+    /**
+     * AI client instance for interacting with AI models
+     */
+    protected _ai: AIClient;
+    /**
+     * Filesystem adapter for file operations
+     */
+    protected _fs: FilesystemAdapter;
+    /**
+     * Database interface for data persistence
+     */
+    protected _db: DatabaseInterface;
+    private _dbEngineHint?;
+    /**
+     * Class name used for identification
+     */
+    protected _className: string;
+    /**
+     * Signal bus for method execution tracking
+     */
+    protected _signalBus?: SignalBus;
+    /**
+     * Adapters registered by this instance (for cleanup)
+     */
+    private _registeredAdapters;
+    /**
+     * In-memory AI usage collector for quick inspection.
+     */
+    private _aiUsageCollector?;
+    /**
+     * Registered AI usage handlers for this instance.
+     */
+    private _aiUsageHandlers;
+    /**
+     * Tracks whether optional runtime services (signals, AI, fs) are ready.
+     */
+    private _runtimeServicesInitialized;
+    /**
+     * Shared in-flight runtime initialization promise for single-flight setup.
+     */
+    private _runtimeServicesInitPromise?;
+    /**
+     * Configuration options provided to the class
+     */
+    options: SmrtClassOptions;
+    /**
+     * Track which databases have had system tables initialized
+     * - WeakSet for :memory: databases (URL not unique, track by instance)
+     * - Set<string> for all others (URL is unique identifier)
+     */
+    private static _systemTablesInitialized;
+    private static _systemTablesInitializedByUrl;
+    /**
+     * Creates a new SmrtClass instance
+     *
+     * @param options - Configuration options for database, filesystem, and AI clients
+     */
+    constructor(options?: SmrtClassOptions);
+    /**
+     * Determines whether this class requires a database to function
+     *
+     * Override this method in subclasses that require database access
+     * to enable early validation during initialization.
+     *
+     * @returns True if database is required, false otherwise
+     * @example
+     * ```typescript
+     * class MyDataModel extends SmrtClass {
+     *   protected requiresDatabase(): boolean {
+     *     return true; // This class needs database access
+     *   }
+     * }
+     * ```
+     */
+    protected requiresDatabase(): boolean;
+    /**
+     * Initializes database, filesystem, and AI client connections
+     *
+     * This method sets up all required services based on the provided options.
+     * It should be called before using any of the service interfaces.
+     *
+     * @returns Promise that resolves to this instance for chaining
+     * @throws {Error} If database is required but not provided in options
+     */
+    protected initialize(): Promise<this>;
+    /**
+     * Initialize core resources required for ORM behavior.
+     *
+     * This setup is shared by both full runtime initialization and lightweight
+     * query hydration. Hydrated objects reuse an existing DB connection and skip
+     * repeated system-table checks.
+     */
+    protected initializeCoreResources(): Promise<void>;
+    /**
+     * Initialize optional runtime services that are not required for plain ORM reads.
+     */
+    protected initializeRuntimeServices(): Promise<void>;
+    /**
+     * Ensure deferred runtime services are ready before using them.
+     */
+    protected ensureRuntimeServicesInitialized(): Promise<void>;
+    /**
+     * Resolve the AI client, initializing deferred runtime services on demand.
+     */
+    protected getAiClient(): Promise<AIClient>;
+    /**
+     * Resolve the AI client if one is configured, otherwise return undefined.
+     */
+    protected getOptionalAiClient(): Promise<AIClient | undefined>;
+    private isSystemSchemaVersionApplied;
+    /**
+     * Ensure SMRT system tables exist in the database
+     *
+     * System tables use _smrt_ prefix and store framework metadata:
+     * - _smrt_contexts: Context memory storage for remembered patterns
+     * - _smrt_migrations: Schema version tracking
+     * - _smrt_registry: Object registry persistence
+     * - _smrt_signals: Signal history/audit log
+     *
+     * This method is idempotent and safe to call multiple times.
+     * Tables are only created once per database connection.
+     */
+    private ensureSystemTables;
+    private withSystemTableBootstrapLock;
+    private rollbackSystemTableBootstrap;
+    private bootstrapSystemTables;
+    private ensureNativeVectorStorage;
+    /**
+     * Access system tables through standard database interface
+     * System tables use _smrt_ prefix to avoid conflicts with user tables
+     */
+    protected get systemDb(): DatabaseInterface;
+    /**
+     * Initialize signal bus and adapters
+     *
+     * Merges global configuration with instance-specific overrides.
+     * Registers built-in and custom adapters based on configuration.
+     */
+    private initializeSignals;
+    /**
+     * Merge global and instance signal configuration
+     *
+     * Instance configuration takes priority over global defaults.
+     *
+     * @param globalConfig - Global configuration from smrt.configure()
+     * @returns Merged configuration
+     */
+    private mergeSignalConfig;
+    /**
+     * Check if signals should be initialized
+     *
+     * Signals are initialized if any adapter is configured.
+     *
+     * @param config - Effective signal configuration
+     * @returns True if signals should be initialized
+     */
+    private shouldInitializeSignals;
+    /**
+     * Register signal adapters based on configuration
+     *
+     * @param config - Effective signal configuration
+     */
+    private registerAdapters;
+    /**
+     * Gets the filesystem adapter instance
+     */
+    get fs(): FilesystemAdapter;
+    /**
+     * Gets the database interface instance
+     */
+    get db(): DatabaseInterface;
+    /**
+     * Gets the AI client instance
+     */
+    get ai(): AIClient;
+    /**
+     * Get the in-memory AI usage snapshot for this instance.
+     */
+    getAiUsageSnapshot(): AiUsageSnapshot | undefined;
+    /**
+     * Reset the in-memory AI usage collector.
+     */
+    resetAiUsage(): void;
+    /**
+     * List persisted AI usage records.
+     */
+    listAiUsage(options?: AiUsageListOptions): Promise<SmrtAiUsageRecord[]>;
+    /**
+     * Summarize persisted AI usage records by a grouping dimension.
+     */
+    summarizeAiUsage(options?: AiUsageSummaryOptions): Promise<Record<string, AiUsageStats>>;
+    /**
+     * Gets the signal bus instance
+     *
+     * @returns Signal bus if signals are enabled, undefined otherwise
+     */
+    get signalBus(): SignalBus | undefined;
+    /**
+     * Cleanup method to prevent memory leaks
+     *
+     * Unregisters all adapters from the signal bus that were registered
+     * by this instance. Call this when the SmrtClass instance is no longer
+     * needed to prevent memory leaks.
+     *
+     * @example
+     * ```typescript
+     * const product = new Product({ name: 'Widget' });
+     * await product.initialize();
+     * // ... use product ...
+     * product.destroy(); // Clean up when done
+     * ```
+     */
+    destroy(): void;
+    private mergeAiUsageConfig;
+    private initializeAiUsageHandlers;
+    private handleAiUsageCallback;
+    private normalizeAiUsageEvent;
+}
+//# sourceMappingURL=class.d.ts.map

package/dist/class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,KAAK,QAAQ,EAAS,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAGV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,aAAa,EAEb,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EACV,aAAa,EAEb,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AA0R7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;OASG;IACH,EAAE,CAAC,EAAE,cAAc,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAE7B;;OAEG;IACH,EAAE,CAAC,EAAE,wBAAwB,CAAC;IAE9B;;OAEG;IACH,EAAE,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC;IAEhC;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,aAAa,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC;IAExE;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,iCAAiC;QACjC,GAAG,CAAC,EAAE,SAAS,CAAC;QAChB,iCAAiC;QACjC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;KAC5B,CAAC;IAEF;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAG,QAAQ,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAG,iBAAiB,CAAC;IAElC;;OAEG;IACH,SAAS,CAAC,GAAG,EAAG,iBAAiB,CAAC;IAClC,OAAO,CAAC,aAAa,CAAC,CAAS;IAE/B;;OAEG;IACH,SAAS,CAAC,UAAU,EAAG,MAAM,CAAC;IAE9B;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAEjC;;OAEG;IACH,OAAO,CAAC,mBAAmB,CAAuB;IAElD;;OAEG;IACH,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAE7C;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAwB;IAEhD;;OAEG;IACH,OAAO,CAAC,2BAA2B,CAAS;IAE5C;;OAEG;IACH,OAAO,CAAC,2BAA2B,CAAC,CAAgB;IAEpD;;OAEG;IACI,OAAO,EAAE,gBAAgB,CAAC;IAEjC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAoC;IAC3E,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAqB;IAEjE;;;;OAIG;gBACS,OAAO,GAAE,gBAAqB;IAK1C;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,gBAAgB,IAAI,OAAO;IAIrC;;;;;;;;OAQG;cACa,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3C;;;;;;OAMG;cACa,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IAuFxD;;OAEG;cACa,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmG1D;;OAEG;cACa,gCAAgC,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjE;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAahD;;OAEG;cACa,mBAAmB,IAAI,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;YAKtD,4BAA4B;IA6B1C;;;;;;;;;;;OAWG;YACW,kBAAkB;YAkDlB,4BAA4B;YAiD5B,4BAA4B;YAc5B,qBAAqB;YAiDrB,yBAAyB;IAgCvC;;;OAGG;IACH,SAAS,KAAK,QAAQ,IAAI,iBAAiB,CAE1C;IAED;;;;;OAKG;YACW,iBAAiB;IAqB/B;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;;OAIG;YACW,gBAAgB;IAuC9B;;OAEG;IACH,IAAI,EAAE,sBAEL;IAED;;OAEG;IACH,IAAI,EAAE,sBASL;IAED;;OAEG;IACH,IAAI,EAAE,aAEL;IAED;;OAEG;IACH,kBAAkB,IAAI,eAAe,GAAG,SAAS;IAIjD;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACG,WAAW,CACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAwD/B;;OAEG;IACG,gBAAgB,CACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IA6DxC;;;;OAIG;IACH,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAED;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,kBAAkB;IAsB1B,OAAO,CAAC,yBAAyB;YAkBnB,qBAAqB;IAwCnC,OAAO,CAAC,qBAAqB;CAoD9B"}