mycelia-kernel-plugin 1.2.0 → 1.4.0

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;
   }
 }
 
+
+
+

package/src/vue/builders.js

@@ -0,0 +1,40 @@
+/**
+ * Mycelia Plugin System - Vue Builder Helpers
+ * 
+ * Vue utilities for creating system builders.
+ */
+
+/**
+ * createVueSystemBuilder - Create a reusable system builder function
+ * 
+ * @param {string} name - System name
+ * @param {Function} configure - Configuration function: (builder) => builder
+ * @returns {Function} Build function: () => Promise<System>
+ * 
+ * @example
+ * ```js
+ * import { useBase } from 'mycelia-kernel-plugin';
+ * import { createVueSystemBuilder } from 'mycelia-kernel-plugin/vue';
+ * 
+ * const buildTodoSystem = createVueSystemBuilder('todo-app', (b) =>
+ *   b
+ *     .config('database', { host: 'localhost' })
+ *     .use(useDatabase)
+ *     .use(useListeners)
+ * );
+ * 
+ * // Then use in plugin
+ * app.use(MyceliaPlugin, { build: buildTodoSystem });
+ * ```
+ */
+export function createVueSystemBuilder(name, configure) {
+  return async function build() {
+    // Import useBase - users should have it available
+    // This avoids bundling issues by letting users import useBase themselves
+    const { useBase } = await import('../utils/use-base.js');
+    let builder = useBase(name);
+    builder = configure(builder);
+    return builder.build();
+  };
+}
+

package/src/vue/composables.js

@@ -0,0 +1,37 @@
+/**
+ * Mycelia Plugin System - Vue Composable Generator
+ * 
+ * Utility for generating custom composables for specific facets.
+ */
+
+import { useFacet } from './index.js';
+
+/**
+ * createFacetComposable - Generate a custom composable for a specific facet kind
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Function} Custom composable: () => import('vue').Ref<Object|null>
+ * 
+ * @example
+ * ```js
+ * // In composables/todo.js
+ * import { createFacetComposable } from 'mycelia-kernel-plugin/vue';
+ * 
+ * export const useTodos = createFacetComposable('todos');
+ * export const useAuth = createFacetComposable('auth');
+ * 
+ * // In component
+ * export default {
+ *   setup() {
+ *     const todos = useTodos();
+ *     // Use todos.value...
+ *   }
+ * }
+ * ```
+ */
+export function createFacetComposable(kind) {
+  return function useNamedFacet() {
+    return useFacet(kind);
+  };
+}
+

package/src/vue/index.js

@@ -0,0 +1,252 @@
+/**
+ * Mycelia Plugin System - Vue Bindings
+ * 
+ * Vue utilities that make the Mycelia Plugin System feel natural
+ * inside Vue 3 applications using the Composition API.
+ * 
+ * @example
+ * ```js
+ * import { MyceliaPlugin, useFacet, useListener } from 'mycelia-kernel-plugin/vue';
+ * import { createApp } from 'vue';
+ * 
+ * const buildSystem = () => useBase('app')
+ *   .use(useDatabase)
+ *   .build();
+ * 
+ * const app = createApp(App);
+ * app.use(MyceliaPlugin, { build: buildSystem });
+ * 
+ * // In component
+ * export default {
+ *   setup() {
+ *     const db = useFacet('database');
+ *     useListener('user:created', (msg) => console.log(msg));
+ *   }
+ * }
+ * ```
+ */
+
+import { provide, inject, ref, onUnmounted, watch, getCurrentInstance, onBeforeUnmount } from 'vue';
+
+// ============================================================================
+// Core Bindings: Plugin + Basic Composables
+// ============================================================================
+
+const MyceliaKey = Symbol('mycelia');
+
+/**
+ * MyceliaPlugin - Vue plugin that provides Mycelia system to the app
+ * 
+ * @param {Object} app - Vue app instance
+ * @param {Object} options - Plugin options
+ * @param {Function} options.build - Async function that returns a built system
+ * 
+ * @example
+ * ```js
+ * import { createApp } from 'vue';
+ * import { MyceliaPlugin } from 'mycelia-kernel-plugin/vue';
+ * 
+ * const buildSystem = () => useBase('app').use(useDatabase).build();
+ * 
+ * const app = createApp(App);
+ * app.use(MyceliaPlugin, { build: buildSystem });
+ * ```
+ */
+export const MyceliaPlugin = {
+  async install(app, options) {
+    const { build } = options;
+    const system = ref(null);
+    const error = ref(null);
+    const loading = ref(true);
+    let currentSystem = null;
+
+    try {
+      currentSystem = await build();
+      system.value = currentSystem;
+      loading.value = false;
+      error.value = null;
+    } catch (err) {
+      error.value = err;
+      loading.value = false;
+      system.value = null;
+      // Re-throw to let Vue handle it
+      throw err;
+    }
+
+    // Provide system to all components
+    const context = {
+      system,
+      loading,
+      error
+    };
+    
+    app.provide(MyceliaKey, context);
+
+    // Store cleanup function on app config for manual cleanup
+    // Vue 3 doesn't provide a plugin unmount hook, so cleanup should be
+    // handled manually when unmounting the app:
+    //   const dispose = app.config.globalProperties.$myceliaDispose;
+    //   if (dispose) await dispose();
+    //   app.unmount();
+    app.config.globalProperties.$myceliaDispose = async () => {
+      if (currentSystem && typeof currentSystem.dispose === 'function') {
+        await currentSystem.dispose().catch(() => {
+          // Ignore disposal errors
+        });
+      }
+    };
+  }
+};
+
+/**
+ * useMycelia - Get the Mycelia system from inject
+ * 
+ * @returns {Object} The Mycelia system instance
+ * @throws {Error} If used outside MyceliaPlugin
+ * 
+ * @example
+ * ```js
+ * import { useMycelia } from 'mycelia-kernel-plugin/vue';
+ * 
+ * export default {
+ *   setup() {
+ *     const system = useMycelia();
+ *     // Use system.find(), system.listeners, etc.
+ *   }
+ * }
+ * ```
+ */
+export function useMycelia() {
+  const context = inject(MyceliaKey);
+  if (!context) {
+    throw new Error('useMycelia must be used within MyceliaPlugin');
+  }
+  return context.system.value;
+}
+
+/**
+ * useMyceliaContext - Get the full Mycelia context (system, loading, error)
+ * 
+ * @returns {Object} Context object with system, loading, and error refs
+ * @throws {Error} If used outside MyceliaPlugin
+ * 
+ * @example
+ * ```js
+ * import { useMyceliaContext } from 'mycelia-kernel-plugin/vue';
+ * 
+ * export default {
+ *   setup() {
+ *     const { system, loading, error } = useMyceliaContext();
+ *     if (loading.value) return { loading: true };
+ *     if (error.value) return { error: error.value };
+ *     return { system: system.value };
+ *   }
+ * }
+ * ```
+ */
+export function useMyceliaContext() {
+  const context = inject(MyceliaKey);
+  if (!context) {
+    throw new Error('useMyceliaContext must be used within MyceliaPlugin');
+  }
+  return context;
+}
+
+/**
+ * useFacet - Get a facet by kind from the system with reactivity
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {import('vue').Ref<Object|null>} Reactive ref to the facet instance, or null if not found
+ * 
+ * @example
+ * ```js
+ * import { useFacet } from 'mycelia-kernel-plugin/vue';
+ * 
+ * export default {
+ *   setup() {
+ *     const db = useFacet('database');
+ *     // Use db.value.query(), etc.
+ *   }
+ * }
+ * ```
+ */
+export function useFacet(kind) {
+  const system = useMycelia();
+  const facet = ref(system?.find?.(kind) ?? null);
+
+  // Watch for system changes (e.g., after reload)
+  watch(() => system, (newSystem) => {
+    facet.value = newSystem?.find?.(kind) ?? null;
+  }, { immediate: true });
+
+  return facet;
+}
+
+/**
+ * useMyceliaCleanup - Automatically handle system cleanup on component unmount
+ * 
+ * This composable automatically disposes the Mycelia system when the component
+ * unmounts. It's useful for root components or components that manage app lifecycle.
+ * 
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.auto=true] - If true, automatically cleanup on unmount. If false, only return cleanup function.
+ * @returns {Function} Cleanup function that can be called manually
+ * 
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useMyceliaCleanup } from 'mycelia-kernel-plugin/vue';
+ * 
+ * // Automatic cleanup on component unmount
+ * useMyceliaCleanup();
+ * </script>
+ * ```
+ * 
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useMyceliaCleanup } from 'mycelia-kernel-plugin/vue';
+ * 
+ * // Get cleanup function for manual use
+ * const dispose = useMyceliaCleanup({ auto: false });
+ * 
+ * const handleLogout = async () => {
+ *   await dispose();
+ *   // Continue with logout logic
+ * };
+ * </script>
+ * ```
+ */
+export function useMyceliaCleanup(options = {}) {
+  const { auto = true } = options;
+  const instance = getCurrentInstance();
+  const app = instance?.appContext.app;
+  
+  const cleanup = async () => {
+    const dispose = app?.config.globalProperties.$myceliaDispose;
+    if (dispose) {
+      await dispose();
+    }
+  };
+  
+  if (auto) {
+    onBeforeUnmount(async () => {
+      await cleanup();
+    });
+  }
+  
+  return cleanup;
+}
+
+// Re-export listener helpers
+export { useListener, useEventStream } from './listeners.js';
+
+// Re-export queue helpers
+export { useQueueStatus, useQueueDrain } from './queues.js';
+
+// Re-export builder helpers
+export { createVueSystemBuilder } from './builders.js';
+
+// Re-export composable generator
+export { createFacetComposable } from './composables.js';
+