mycelia-kernel-plugin 1.0.0 → 1.1.0

package/README.md

@@ -13,11 +13,16 @@ Mycelia Plugin System is a standalone plugin architecture extracted from [Myceli
 - **Hot reloading** - Reload and extend plugins without full teardown
 - **Facet contracts** - Runtime validation of plugin interfaces
 - **Standalone mode** - Works without message system or other dependencies
+- **Built-in hooks** - Ships with `useListeners` for event-driven architectures (see [Simple Event System Example](#simple-event-system-example)), plus `useQueue` and `useSpeak`
+
+**Facets** are the concrete runtime capabilities produced by hooks and attached to the system.
 
 ## Quick Start
 
+### Using useBase (Recommended)
+
 ```javascript
-import { StandalonePluginSystem, createHook, Facet } from 'mycelia-kernel-plugin';
+import { useBase, createHook, Facet } from 'mycelia-kernel-plugin';
 
 // Create a hook
 const useDatabase = createHook({
@@ -51,6 +56,25 @@ const useDatabase = createHook({
   }
 });
 
+// Create and use the system with fluent API
+const system = await useBase('my-app')
+  .config('database', { host: 'localhost' })
+  .use(useDatabase)
+  .build();
+
+// Use the plugin
+const db = system.find('database');
+await db.query('SELECT * FROM users');
+```
+
+### Using StandalonePluginSystem Directly
+
+```javascript
+import { StandalonePluginSystem, createHook, Facet } from 'mycelia-kernel-plugin';
+
+// Create a hook (same as above)
+const useDatabase = createHook({ /* ... */ });
+
 // Create and use the system
 const system = new StandalonePluginSystem('my-app', {
   config: {
@@ -67,12 +91,71 @@ const db = system.find('database');
 await db.query('SELECT * FROM users');
 ```
 
+### Simple Event System Example
+
+Create an event-driven system with `useBase` and `useListeners`:
+
+```javascript
+import { useBase, useListeners } from 'mycelia-kernel-plugin';
+
+// Create an event system
+const eventSystem = await useBase('event-system')
+  .config('listeners', { registrationPolicy: 'multiple' })
+  .use(useListeners)
+  .build();
+
+// Enable listeners
+eventSystem.listeners.enableListeners();
+
+// Register event handlers
+eventSystem.listeners.on('user:created', (message) => {
+  console.log('User created:', message.body);
+});
+
+eventSystem.listeners.on('user:updated', (message) => {
+  console.log('User updated:', message.body);
+});
+
+// Emit events
+eventSystem.listeners.emit('user:created', {
+  type: 'user:created',
+  body: { id: 1, name: 'John Doe' }
+});
+
+eventSystem.listeners.emit('user:updated', {
+  type: 'user:updated',
+  body: { id: 1, name: 'Jane Doe' }
+});
+
+// Multiple handlers for the same event
+eventSystem.listeners.on('order:placed', (message) => {
+  console.log('Order notification:', message.body);
+});
+
+eventSystem.listeners.on('order:placed', (message) => {
+  console.log('Order logging:', message.body);
+});
+
+// Both handlers will be called
+eventSystem.listeners.emit('order:placed', {
+  type: 'order:placed',
+  body: { orderId: 123, total: 99.99 }
+});
+
+// Cleanup
+await eventSystem.dispose();
+```
+
 ## Installation
 
 ```bash
 npm install mycelia-kernel-plugin
 ```
 
+## What This System Is Not
+
+This system intentionally does not provide dependency injection containers, service locators, or global mutable state. It focuses on explicit lifecycle management and composable plugin architecture rather than implicit dependency resolution or shared global state.
+
 ## Features
 
 ### Hook System
@@ -141,6 +224,8 @@ The `reload()` method:
 - Allows adding more hooks and rebuilding
 - Perfect for development and hot-reload scenarios
 
+**Note:** Persistent external state (e.g., database contents, file system state) is not automatically reverted. The `reload()` method only manages the plugin system's internal state.
+
 ### Facet Contracts
 Validate plugin interfaces at build time:
 
@@ -156,6 +241,11 @@ const databaseContract = createFacetContract({
 // Contract is automatically enforced during build
 ```
 
+If a facet doesn't satisfy its contract, build fails with a clear error:
+```
+Error: FacetContract 'database': facet is missing required methods: close
+```
+
 ## Architecture
 
 ```
@@ -181,6 +271,7 @@ StandalonePluginSystem
 
 - **`createHook()`** - Create a plugin hook
 - **`createFacetContract()`** - Create a facet contract
+- **`useBase()`** - Fluent API builder for StandalonePluginSystem
 
 ### Utilities
 
@@ -193,6 +284,7 @@ Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 
 - **[Getting Started Guide](./docs/getting-started/README.md)** - Quick start with examples
 - **[Hooks and Facets Overview](./docs/core-concepts/HOOKS-AND-FACETS-OVERVIEW.md)** - Core concepts
+- **[Built-in Hooks](./docs/hooks/README.md)** - Documentation for `useListeners`, `useQueue`, and `useSpeak`
 - **[Standalone Plugin System](./docs/standalone/STANDALONE-PLUGIN-SYSTEM.md)** - Complete usage guide
 - **[Documentation Index](./docs/README.md)** - Full documentation index
 
@@ -204,6 +296,7 @@ See the `examples/` directory for:
 - Lifecycle management
 - Contract validation
 - Hot reloading
+- useBase fluent API
 
 ## CLI Tool
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mycelia-kernel-plugin",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A sophisticated, dependency-aware plugin system with transaction safety and lifecycle management",
   "license": "MIT",
   "type": "module",

package/src/index.js

@@ -38,6 +38,7 @@ export { useSpeak } from './hooks/speak/use-speak.js';
 export { createLogger, createSubsystemLogger } from './utils/logger.js';
 export { getDebugFlag } from './utils/debug-flag.js';
 export { findFacet } from './utils/find-facet.js';
+export { useBase } from './utils/use-base.js';
 export { 
   parseVersion, 
   isValidSemver, 

package/src/utils/use-base.js

@@ -0,0 +1,262 @@
+import { StandalonePluginSystem } from '../system/standalone-plugin-system.js';
+import { deepMerge } from '../builder/context-resolver.js';
+
+/**
+ * useBase - Fluent API Builder for StandalonePluginSystem
+ * 
+ * Provides a convenient, chainable API for creating and configuring
+ * StandalonePluginSystem instances.
+ * 
+ * @param {string} name - Unique name for the plugin system
+ * @param {Object} [options={}] - Initial configuration options
+ * @param {Object} [options.config={}] - Initial configuration object keyed by facet kind
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @param {Array} [options.defaultHooks=[]] - Optional default hooks to install
+ * @returns {UseBaseBuilder} Builder instance with fluent API
+ * 
+ * @example
+ * ```javascript
+ * import { useBase } from 'mycelia-kernel-plugin';
+ * import { useDatabase, useCache } from './hooks';
+ * 
+ * const system = await useBase('my-app')
+ *   .config('database', { host: 'localhost' })
+ *   .config('cache', { ttl: 3600 })
+ *   .use(useDatabase)
+ *   .use(useCache)
+ *   .onInit(async (api, ctx) => {
+ *     console.log('System initialized');
+ *   })
+ *   .build();
+ * ```
+ */
+export function useBase(name, options = {}) {
+  if (!name || typeof name !== 'string') {
+    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);
+}
+
+/**
+ * UseBaseBuilder - Fluent API builder for StandalonePluginSystem
+ * 
+ * Provides chainable methods for configuring and building the system.
+ */
+class UseBaseBuilder {
+  #system;
+  #pendingConfig = {};
+
+  constructor(system) {
+    this.#system = system;
+  }
+
+  /**
+   * Register a hook
+   * 
+   * @param {Function} hook - Hook function to register
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.use(useDatabase).use(useCache);
+   * ```
+   */
+  use(hook) {
+    if (typeof hook !== 'function') {
+      throw new Error('useBase.use: hook must be a function');
+    }
+    this.#system.use(hook);
+    return this;
+  }
+
+  /**
+   * Conditionally register a hook
+   * 
+   * @param {boolean} condition - Whether to register the hook
+   * @param {Function} hook - Hook function to register if condition is true
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.useIf(process.env.ENABLE_CACHE === 'true', useCache);
+   * ```
+   */
+  useIf(condition, hook) {
+    if (condition) {
+      return this.use(hook);
+    }
+    return this;
+  }
+
+  /**
+   * Add or update configuration for a specific facet kind
+   * 
+   * Configurations are merged when possible (deep merge for objects).
+   * 
+   * @param {string} kind - Facet kind identifier (e.g., 'database', 'cache')
+   * @param {*} config - Configuration value for this facet kind
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder
+   *   .config('database', { host: 'localhost', port: 5432 })
+   *   .config('cache', { ttl: 3600 });
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // Merge configurations
+   * builder
+   *   .config('database', { host: 'localhost' })
+   *   .config('database', { port: 5432 }); // Merges with existing
+   * ```
+   */
+  config(kind, config) {
+    if (!kind || typeof kind !== 'string') {
+      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
+    const existingConfig = this.#system.ctx.config[kind];
+    const pendingConfig = this.#pendingConfig[kind];
+
+    // Determine the base config (existing or pending)
+    const baseConfig = pendingConfig !== undefined ? pendingConfig : existingConfig;
+
+    // Merge if both are objects
+    if (
+      baseConfig &&
+      typeof baseConfig === 'object' &&
+      !Array.isArray(baseConfig) &&
+      config &&
+      typeof config === 'object' &&
+      !Array.isArray(config)
+    ) {
+      // Deep merge
+      this.#pendingConfig[kind] = deepMerge(baseConfig, config);
+    } else {
+      // Override
+      this.#pendingConfig[kind] = config;
+    }
+
+    return this;
+  }
+
+  /**
+   * Add an initialization callback
+   * 
+   * @param {Function} callback - Callback function: (api, ctx) => Promise<void> | void
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.onInit(async (api, ctx) => {
+   *   console.log('System initialized:', api.name);
+   * });
+   * ```
+   */
+  onInit(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('useBase.onInit: callback must be a function');
+    }
+    this.#system.onInit(callback);
+    return this;
+  }
+
+  /**
+   * Add a disposal callback
+   * 
+   * @param {Function} callback - Callback function: () => Promise<void> | void
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.onDispose(async () => {
+   *   console.log('System disposed');
+   * });
+   * ```
+   */
+  onDispose(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('useBase.onDispose: callback must be a function');
+    }
+    this.#system.onDispose(callback);
+    return this;
+  }
+
+  /**
+   * Build the system
+   * 
+   * This method is required and must be called to build the system.
+   * It applies any pending configurations and builds the system.
+   * 
+   * @param {Object} [ctx={}] - Additional context to pass to build
+   * @returns {Promise<StandalonePluginSystem>} The built system instance
+   * 
+   * @example
+   * ```javascript
+   * const system = await useBase('my-app')
+   *   .use(useDatabase)
+   *   .build();
+   * ```
+   */
+  async build(ctx = {}) {
+    // 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 = {};
+      }
+
+      // Deep merge pending configs
+      for (const [kind, config] of Object.entries(this.#pendingConfig)) {
+        const existing = this.#system.ctx.config[kind];
+        if (
+          existing &&
+          typeof existing === 'object' &&
+          !Array.isArray(existing) &&
+          config &&
+          typeof config === 'object' &&
+          !Array.isArray(config)
+        ) {
+          this.#system.ctx.config[kind] = deepMerge(existing, config);
+        } else {
+          this.#system.ctx.config[kind] = config;
+        }
+      }
+
+      // Clear pending configs
+      this.#pendingConfig = {};
+    }
+
+    // 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 = {};
+        }
+        this.#system.ctx.config = deepMerge(this.#system.ctx.config, ctx.config);
+      }
+      // Merge other ctx properties (shallow)
+      Object.assign(this.#system.ctx, ctx);
+    }
+
+    // Build the system
+    await this.#system.build(ctx);
+
+    // Return the system instance
+    return this.#system;
+  }
+}
+