mycelia-kernel-plugin 1.3.0 → 1.4.0

package/src/utils/instrumentation.js

@@ -0,0 +1,204 @@
+/**
+ * Instrumentation Utilities
+ * 
+ * Provides timing instrumentation for debugging build, initialization, and disposal phases.
+ * Helps identify slow hooks and facets when debugging performance issues.
+ */
+
+import { createSubsystemLogger } from './logger.js';
+
+/**
+ * Default thresholds for timing warnings (in milliseconds)
+ */
+const DEFAULT_THRESHOLDS = {
+  hookExecution: 50,    // Warn if hook execution takes > 50ms
+  facetInit: 100,       // Warn if facet init takes > 100ms
+  facetDispose: 50,      // Warn if facet dispose takes > 50ms
+};
+
+/**
+ * Check if instrumentation is enabled
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {boolean} True if instrumentation is enabled
+ */
+export function isInstrumentationEnabled(subsystem) {
+  // Enable if debug is on, or if instrumentation is explicitly enabled
+  return subsystem?.debug === true || subsystem?.ctx?.instrumentation === true;
+}
+
+/**
+ * Get timing thresholds from config or use defaults
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Object} Thresholds object
+ */
+function getThresholds(subsystem) {
+  const config = subsystem?.ctx?.config?.instrumentation || {};
+  return {
+    hookExecution: config.hookExecutionThreshold ?? DEFAULT_THRESHOLDS.hookExecution,
+    facetInit: config.facetInitThreshold ?? DEFAULT_THRESHOLDS.facetInit,
+    facetDispose: config.facetDisposeThreshold ?? DEFAULT_THRESHOLDS.facetDispose,
+  };
+}
+
+/**
+ * Time a hook execution and log if it exceeds threshold
+ * 
+ * @param {Function} hook - Hook function to execute
+ * @param {Object} resolvedCtx - Resolved context
+ * @param {Object} api - Subsystem API
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {*} Result of hook execution
+ */
+export function instrumentHookExecution(hook, resolvedCtx, api, subsystem) {
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - just execute
+    return hook(resolvedCtx, api, subsystem);
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const hookKind = hook.kind || '<unknown>';
+  const hookSource = hook.source || '<unknown>';
+  const thresholds = getThresholds(subsystem);
+
+  const start = performance.now();
+  let result;
+  try {
+    result = hook(resolvedCtx, api, subsystem);
+  } finally {
+    const duration = performance.now() - start;
+    
+    if (duration > thresholds.hookExecution) {
+      logger.warn(
+        `⚠️  Slow hook execution: '${hookKind}' took ${duration.toFixed(2)}ms ` +
+        `(threshold: ${thresholds.hookExecution}ms) [${hookSource}]`
+      );
+    } else {
+      logger.log(`✓ Hook '${hookKind}' executed in ${duration.toFixed(2)}ms [${hookSource}]`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Time a facet initialization callback and log if it exceeds threshold
+ * 
+ * @param {Facet} facet - Facet instance
+ * @param {Object} ctx - Context object
+ * @param {Object} api - Subsystem API
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Function} initCallback - The init callback to execute
+ * @returns {Promise<void>}
+ */
+export async function instrumentFacetInit(facet, ctx, api, subsystem, initCallback) {
+  if (!initCallback) {
+    return;
+  }
+
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - call callback directly
+    return initCallback({ ctx, api, subsystem, facet });
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const facetKind = facet.getKind?.() || '<unknown>';
+  const facetSource = facet.getSource?.() || '<unknown>';
+  const thresholds = getThresholds(subsystem);
+
+  const start = performance.now();
+  try {
+    await initCallback({ ctx, api, subsystem, facet });
+  } finally {
+    const duration = performance.now() - start;
+    
+    if (duration > thresholds.facetInit) {
+      logger.warn(
+        `⚠️  Slow facet initialization: '${facetKind}' took ${duration.toFixed(2)}ms ` +
+        `(threshold: ${thresholds.facetInit}ms) [${facetSource}]`
+      );
+    } else {
+      logger.log(`✓ Facet '${facetKind}' initialized in ${duration.toFixed(2)}ms [${facetSource}]`);
+    }
+  }
+}
+
+/**
+ * Time a facet disposal callback and warn if it exceeds threshold
+ * 
+ * @param {Facet} facet - Facet instance
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Function} disposeCallback - The dispose callback to execute
+ * @returns {Promise<void>}
+ */
+export async function instrumentDisposeCallback(facet, subsystem, disposeCallback) {
+  if (!disposeCallback) {
+    return;
+  }
+
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - call callback directly
+    return disposeCallback(facet);
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const facetKind = facet.getKind?.() || '<unknown>';
+  const facetSource = facet.getSource?.() || '<unknown>';
+  const thresholds = getThresholds(subsystem);
+
+  const start = performance.now();
+  let errorOccurred = false;
+  try {
+    await disposeCallback(facet);
+    const duration = performance.now() - start;
+    
+    if (duration > thresholds.facetDispose) {
+      logger.warn(
+        `⚠️  Slow facet disposal: '${facetKind}' took ${duration.toFixed(2)}ms ` +
+        `(threshold: ${thresholds.facetDispose}ms) [${facetSource}]`
+      );
+    } else {
+      logger.log(`✓ Facet '${facetKind}' disposed in ${duration.toFixed(2)}ms [${facetSource}]`);
+    }
+  } catch (error) {
+    errorOccurred = true;
+    const duration = performance.now() - start;
+    logger.warn(
+      `⚠️  Facet disposal error: '${facetKind}' failed after ${duration.toFixed(2)}ms ` +
+      `[${facetSource}]: ${error.message}`
+    );
+    // Re-throw so disposeAll can catch and handle it
+    throw error;
+  } finally {
+    // Ensure timing is logged even if error occurred
+    if (!errorOccurred) {
+      // Already logged in try block
+    }
+  }
+}
+
+/**
+ * Time the entire build phase and log summary
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Function} buildFn - Build function to execute
+ * @returns {Promise<void>}
+ */
+export async function instrumentBuildPhase(subsystem, buildFn) {
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - just build
+    return buildFn();
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const start = performance.now();
+  
+  try {
+    await buildFn();
+  } finally {
+    const duration = performance.now() - start;
+    logger.log(`📦 Build phase completed in ${duration.toFixed(2)}ms`);
+  }
+}
+

package/src/utils/use-base.js

@@ -1,11 +1,12 @@
 import { StandalonePluginSystem } from '../system/standalone-plugin-system.js';
+import { BaseSubsystem } from '../system/base-subsystem.js';
 import { deepMerge } from '../builder/context-resolver.js';
 
 /**
- * useBase - Fluent API Builder for StandalonePluginSystem
+ * useBase - Fluent API Builder for StandalonePluginSystem / BaseSubsystem
  * 
  * Provides a convenient, chainable API for creating and configuring
- * StandalonePluginSystem instances.
+ * StandalonePluginSystem or BaseSubsystem instances via a fluent API.
  * 
  * @param {string} name - Unique name for the plugin system
  * @param {Object} [options={}] - Initial configuration options
@@ -14,6 +15,9 @@ import { deepMerge } from '../builder/context-resolver.js';
  * @param {Array} [options.defaultHooks=[]] - Optional default hooks to install
  * @returns {UseBaseBuilder} Builder instance with fluent API
  * 
+ * By default it uses StandalonePluginSystem; call .setBase(BaseSubsystem)
+ * to build a subsystem instead.
+ * 
  * @example
  * ```javascript
  * import { useBase } from 'mycelia-kernel-plugin';
@@ -35,24 +39,73 @@ export function useBase(name, options = {}) {
     throw new Error('useBase: name must be a non-empty string');
   }
 
-  // Create the system instance
-  const system = new StandalonePluginSystem(name, options);
-
-  // Create builder with fluent API
-  return new UseBaseBuilder(system);
+  // Create builder with fluent API (system will be created lazily)
+  return new UseBaseBuilder(name, options);
 }
 
 /**
- * UseBaseBuilder - Fluent API builder for StandalonePluginSystem
+ * UseBaseBuilder - Fluent API builder for StandalonePluginSystem or BaseSubsystem
  * 
  * Provides chainable methods for configuring and building the system.
  */
 class UseBaseBuilder {
-  #system;
+  #name;
+  #options;
+  #BaseClass = StandalonePluginSystem; // Default to StandalonePluginSystem
+  #system = null; // Lazy initialization
   #pendingConfig = {};
 
-  constructor(system) {
-    this.#system = system;
+  constructor(name, options) {
+    this.#name = name;
+    this.#options = options;
+  }
+
+  /**
+   * Get or create the system instance (lazy initialization)
+   * @private
+   */
+  #getSystem() {
+    if (!this.#system) {
+      this.#system = new this.#BaseClass(this.#name, this.#options);
+    }
+    return this.#system;
+  }
+
+  /**
+   * Set the base class for the system
+   * 
+   * @param {Function} BaseClass - The base class to use. Must be BaseSubsystem or any class that extends BaseSubsystem
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * import { BaseSubsystem } from 'mycelia-kernel-plugin';
+   * 
+   * builder.setBase(BaseSubsystem);
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // Must be called before any methods that use the system
+   * const system = await useBase('my-app')
+   *   .setBase(BaseSubsystem)
+   *   .use(useDatabase)
+   *   .build();
+   * ```
+   */
+  setBase(BaseClass) {
+    if (this.#system) {
+      throw new Error('useBase.setBase: cannot change base class after system is created');
+    }
+    if (typeof BaseClass !== 'function') {
+      throw new Error('useBase.setBase: BaseClass must be a constructor function');
+    }
+    // Validate it's a subclass of BaseSubsystem
+    if (BaseClass !== BaseSubsystem && !(BaseClass.prototype instanceof BaseSubsystem)) {
+      throw new Error('useBase.setBase: BaseClass must be BaseSubsystem or a subclass of BaseSubsystem');
+    }
+    this.#BaseClass = BaseClass;
+    return this;
   }
 
   /**
@@ -70,7 +123,7 @@ class UseBaseBuilder {
     if (typeof hook !== 'function') {
       throw new Error('useBase.use: hook must be a function');
     }
-    this.#system.use(hook);
+    this.#getSystem().use(hook);
     return this;
   }
 
@@ -93,6 +146,75 @@ class UseBaseBuilder {
     return this;
   }
 
+  /**
+   * Register multiple hooks at once
+   * 
+   * @param {Array<Function>} hooks - Array of hook functions to register
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.useMultiple([useDatabase, useCache, useAuth]);
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // Can be combined with other methods
+   * builder
+   *   .use(useLogger)
+   *   .useMultiple([useDatabase, useCache])
+   *   .use(useAuth);
+   * ```
+   */
+  useMultiple(hooks) {
+    if (!Array.isArray(hooks)) {
+      throw new Error('useBase.useMultiple: hooks must be an array');
+    }
+    
+    const system = this.#getSystem();
+    for (const hook of hooks) {
+      if (typeof hook !== 'function') {
+        throw new Error('useBase.useMultiple: all hooks must be functions');
+      }
+      system.use(hook);
+    }
+    
+    return this;
+  }
+
+  /**
+   * Conditionally register multiple hooks
+   * 
+   * @param {boolean} condition - Whether to register the hooks
+   * @param {Array<Function>} hooks - Array of hook functions to register if condition is true
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.useIfMultiple(process.env.NODE_ENV === 'development', [
+   *   useDebugTools,
+   *   useDevLogger
+   * ]);
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * const optionalHooks = [];
+   * if (enableCache) optionalHooks.push(useCache);
+   * if (enableAuth) optionalHooks.push(useAuth);
+   * 
+   * builder
+   *   .use(useDatabase)
+   *   .useIfMultiple(optionalHooks.length > 0, optionalHooks);
+   * ```
+   */
+  useIfMultiple(condition, hooks) {
+    if (condition) {
+      return this.useMultiple(hooks);
+    }
+    return this;
+  }
+
   /**
    * Add or update configuration for a specific facet kind
    * 
@@ -122,13 +244,18 @@ class UseBaseBuilder {
       throw new Error('useBase.config: kind must be a non-empty string');
     }
 
-    // Initialize config object if needed
-    if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
-      this.#system.ctx.config = {};
+    // Get existing config for this kind (from pending or system if created)
+    let existingConfig;
+    if (this.#system) {
+      if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
+        this.#system.ctx.config = {};
+      }
+      existingConfig = this.#system.ctx.config[kind];
+    } else {
+      // System not created yet, check pending config
+      existingConfig = this.#pendingConfig[kind];
     }
 
-    // Get existing config for this kind
-    const existingConfig = this.#system.ctx.config[kind];
     const pendingConfig = this.#pendingConfig[kind];
 
     // Determine the base config (existing or pending)
@@ -153,6 +280,49 @@ class UseBaseBuilder {
     return this;
   }
 
+  /**
+   * Add or update configurations for multiple facet kinds at once
+   * 
+   * Configurations are merged when possible (deep merge for objects).
+   * 
+   * @param {Object} configs - Object where keys are facet kinds and values are configurations
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.configMultiple({
+   *   database: { host: 'localhost', port: 5432 },
+   *   cache: { ttl: 3600 },
+   *   auth: { secret: 'abc123' }
+   * });
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // Merge configurations
+   * builder
+   *   .configMultiple({
+   *     database: { host: 'localhost' },
+   *     cache: { ttl: 3600 }
+   *   })
+   *   .configMultiple({
+   *     database: { port: 5432 }, // Merges with existing
+   *     auth: { secret: 'abc123' }
+   *   });
+   * ```
+   */
+  configMultiple(configs) {
+    if (!configs || typeof configs !== 'object' || Array.isArray(configs)) {
+      throw new Error('useBase.configMultiple: configs must be an object');
+    }
+
+    for (const [kind, config] of Object.entries(configs)) {
+      this.config(kind, config);
+    }
+
+    return this;
+  }
+
   /**
    * Add an initialization callback
    * 
@@ -170,7 +340,7 @@ class UseBaseBuilder {
     if (typeof callback !== 'function') {
       throw new Error('useBase.onInit: callback must be a function');
     }
-    this.#system.onInit(callback);
+    this.#getSystem().onInit(callback);
     return this;
   }
 
@@ -191,7 +361,7 @@ class UseBaseBuilder {
     if (typeof callback !== 'function') {
       throw new Error('useBase.onDispose: callback must be a function');
     }
-    this.#system.onDispose(callback);
+    this.#getSystem().onDispose(callback);
     return this;
   }
 
@@ -212,16 +382,18 @@ class UseBaseBuilder {
    * ```
    */
   async build(ctx = {}) {
+    const system = this.#getSystem();
+
     // Apply pending configurations
     if (Object.keys(this.#pendingConfig).length > 0) {
       // Merge pending config into system config
-      if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
-        this.#system.ctx.config = {};
+      if (!system.ctx.config || typeof system.ctx.config !== 'object') {
+        system.ctx.config = {};
       }
 
       // Deep merge pending configs
       for (const [kind, config] of Object.entries(this.#pendingConfig)) {
-        const existing = this.#system.ctx.config[kind];
+        const existing = system.ctx.config[kind];
         if (
           existing &&
           typeof existing === 'object' &&
@@ -230,9 +402,9 @@ class UseBaseBuilder {
           typeof config === 'object' &&
           !Array.isArray(config)
         ) {
-          this.#system.ctx.config[kind] = deepMerge(existing, config);
+          system.ctx.config[kind] = deepMerge(existing, config);
         } else {
-          this.#system.ctx.config[kind] = config;
+          system.ctx.config[kind] = config;
         }
       }
 
@@ -243,20 +415,23 @@ class UseBaseBuilder {
     // Merge any additional context
     if (ctx && typeof ctx === 'object' && !Array.isArray(ctx)) {
       if (ctx.config && typeof ctx.config === 'object' && !Array.isArray(ctx.config)) {
-        if (!this.#system.ctx.config) {
-          this.#system.ctx.config = {};
+        if (!system.ctx.config) {
+          system.ctx.config = {};
         }
-        this.#system.ctx.config = deepMerge(this.#system.ctx.config, ctx.config);
+        system.ctx.config = deepMerge(system.ctx.config, ctx.config);
       }
       // Merge other ctx properties (shallow)
-      Object.assign(this.#system.ctx, ctx);
+      Object.assign(system.ctx, ctx);
     }
 
     // Build the system
-    await this.#system.build(ctx);
+    await system.build(ctx);
 
     // Return the system instance
-    return this.#system;
+    return system;
   }
 }
 
+
+
+