mycelia-kernel-plugin 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Mycelia Plugin System
 
-A sophisticated, **framework-agnostic** plugin system with transaction safety, lifecycle management, and official bindings for React and Vue 3.
+A sophisticated, **framework-agnostic** plugin system with transaction safety, lifecycle management, and official bindings for React, Vue 3, Svelte, Angular, Qwik, and Solid.js.
 
 ## Overview
 
@@ -15,7 +15,7 @@ Mycelia Plugin System is a **framework-agnostic**, standalone plugin architectur
 - **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`
-- **Framework bindings** - Official bindings for [React](#react-bindings), [Vue 3](#vue-bindings), and [Svelte](#svelte-bindings) with more coming soon
+- **Framework bindings** - Official bindings for [React](#react-bindings), [Vue 3](#vue-bindings), [Svelte](#svelte-bindings), [Angular](#angular-bindings), [Qwik](#qwik-bindings), and [Solid.js](#solidjs-bindings)
 
 **Facets** are the concrete runtime capabilities produced by hooks and attached to the system.
 
@@ -26,9 +26,12 @@ The system is designed to be framework-agnostic. Your domain logic lives in Myce
 - **React** - Use `MyceliaProvider` and React hooks (`useFacet`, `useListener`)
 - **Vue 3** - Use `MyceliaPlugin` and Vue composables (`useFacet`, `useListener`)
 - **Svelte** - Use `setMyceliaSystem` and Svelte stores (`useFacet`, `useListener`)
+- **Angular** - Use `MyceliaService` and RxJS observables (`useFacet`, `useListener`)
+- **Qwik** - Use `MyceliaProvider` and Qwik signals (`useFacet`, `useListener`)
+- **Solid.js** - Use `MyceliaProvider` and Solid.js signals (`useFacet`, `useListener`)
 - **Vanilla JS/Node.js** - Use the system directly without any framework bindings
 
-See the [React Todo App](./examples/react-todo/README.md), [Vue Todo App](./examples/vue-todo/README.md), and [Svelte Todo App](./examples/svelte-todo/README.md) examples - they all use the **exact same plugin code**, demonstrating true framework independence.
+See the [React Todo App](./examples/react-todo/README.md), [Vue Todo App](./examples/vue-todo/README.md), [Svelte Todo App](./examples/svelte-todo/README.md), and [Solid.js Todo App](./examples/solid-todo/README.md) examples - they all use the **exact same plugin code**, demonstrating true framework independence.
 
 ## Quick Start
 
@@ -75,6 +78,15 @@ const system = await useBase('my-app')
   .use(useDatabase)
   .build();
 
+// Or configure multiple facets and hooks at once
+const system = await useBase('my-app')
+  .configMultiple({
+    database: { host: 'localhost', port: 5432 },
+    cache: { ttl: 3600 }
+  })
+  .useMultiple([useDatabase, useCache])
+  .build();
+
 // Use the plugin
 const db = system.find('database');
 await db.query('SELECT * FROM users');
@@ -284,7 +296,7 @@ StandalonePluginSystem
 
 - **`createHook()`** - Create a plugin hook
 - **`createFacetContract()`** - Create a facet contract
-- **`useBase()`** - Fluent API builder for StandalonePluginSystem
+- **`useBase()`** - Fluent API builder for StandalonePluginSystem (see [useBase Documentation](./docs/utils/USE-BASE.md))
 
 ### Utilities
 
@@ -295,12 +307,19 @@ StandalonePluginSystem
 
 Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 
+### Quick Links
+- **[useBase Guide](./docs/utils/USE-BASE.md)** - Complete guide to the fluent API builder with all methods
+- **[Instrumentation](./docs/instrumentation.md)** - Debugging and performance instrumentation
+
+### Full Documentation
 - **[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`
 - **[React Bindings](./docs/react/README.md)** - React integration utilities (`MyceliaProvider`, `useFacet`, `useListener`)
 - **[Vue Bindings](./docs/vue/README.md)** - Vue 3 integration utilities (`MyceliaPlugin`, `useFacet`, `useListener`) ⭐
 - **[Svelte Bindings](./docs/svelte/README.md)** - Svelte integration utilities (`setMyceliaSystem`, `useFacet`, `useListener`) ⭐
+- **[Angular Bindings](./docs/angular/README.md)** - Angular integration utilities (`MyceliaService`, `useFacet`, `useListener`) ⭐
+- **[Qwik Bindings](./docs/qwik/README.md)** - Qwik integration utilities (`MyceliaProvider`, `useFacet`, `useListener`) ⭐
 - **[Standalone Plugin System](./docs/standalone/STANDALONE-PLUGIN-SYSTEM.md)** - Complete usage guide
 - **[Documentation Index](./docs/README.md)** - Full documentation index
 
@@ -328,12 +347,25 @@ See the `examples/` directory for:
   - Composition API integration with reactive state management
 
 - **[Svelte Todo App](./examples/svelte-todo/README.md)** ⭐ – A complete Svelte example demonstrating:
-  - **Framework-agnostic plugins** - Uses the same shared plugin code as React and Vue examples
+- **[Solid.js Todo App](./examples/solid-todo/README.md)** ⭐ – A complete Solid.js example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as React, Vue, and Svelte examples
   - Event-driven state synchronization (`todos:changed` events)
-  - Svelte bindings (`setMyceliaSystem`, `useFacet`, `useListener`)
-  - Store-based reactivity with automatic subscription
+  - Solid.js bindings (`MyceliaProvider`, `useFacet`, `useListener`)
+  - Signal-based reactivity with automatic updates
 
-All three examples use the **exact same Mycelia plugin code** from `examples/todo-shared/`, proving that plugins are truly framework-independent. Write your domain logic once, use it everywhere!
+- **[Angular Todo App](./examples/angular-todo/README.md)** ⭐ – A complete Angular example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as React, Vue, and Svelte examples
+  - Event-driven state synchronization (`todos:changed` events)
+  - Angular bindings (`MyceliaService`, `useFacet`, `useListener`)
+  - RxJS observables for reactive state management
+
+- **[Qwik Todo App](./examples/qwik-todo/README.md)** ⭐ – A complete Qwik example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as all other framework examples
+  - Event-driven state synchronization (`todos:changed` events)
+  - Qwik bindings (`MyceliaProvider`, `useFacet`, `useListener`)
+  - Qwik signals for reactive state management
+
+All six examples use the **exact same Mycelia plugin code** from `examples/todo-shared/`, proving that plugins are truly framework-independent. Write your domain logic once, use it everywhere!
 
 ## CLI Tool
 
@@ -357,6 +389,15 @@ npx mycelia-kernel-plugin init vue my-vue-app
 
 # Initialize a Svelte project with Mycelia bindings
 npx mycelia-kernel-plugin init svelte my-svelte-app
+
+# Initialize an Angular project with Mycelia bindings
+npx mycelia-kernel-plugin init angular my-angular-app
+
+# Initialize a Qwik project with Mycelia bindings
+npx mycelia-kernel-plugin init qwik my-qwik-app
+
+# Initialize a Solid.js project with Mycelia bindings
+npx mycelia-kernel-plugin init solid my-solid-app
 ```
 
 Or install globally:

package/bin/cli.js

@@ -74,6 +74,12 @@ function handleInit(args) {
   } else if (args[0] === 'svelte') {
     const projectName = args[1] || 'my-svelte-app';
     initSvelteProject(projectName);
+  } else if (args[0] === 'angular') {
+    const projectName = args[1] || 'my-angular-app';
+    initAngularProject(projectName);
+  } else if (args[0] === 'qwik') {
+    const projectName = args[1] || 'my-qwik-app';
+    initQwikProject(projectName);
   } else {
     const projectName = args[0];
     initProject(projectName);
@@ -867,6 +873,257 @@ dist/
   console.log(`  npm run dev`);
 }
 
+/**
+ * Initialize an Angular project with Mycelia bindings
+ */
+function initAngularProject(projectName) {
+  const projectDir = projectName;
+  
+  if (existsSync(projectDir)) {
+    console.error(`Error: Directory already exists: ${projectDir}`);
+    process.exit(1);
+  }
+
+  console.log(`Creating Angular project: ${projectName}...`);
+  console.log(`\nNote: This creates a basic Angular project structure.`);
+  console.log(`You may need to run 'ng new' separately for a full Angular CLI setup.`);
+
+  // Create directory structure
+  mkdirSync(projectDir, { recursive: true });
+  mkdirSync(join(projectDir, 'src'), { recursive: true });
+  mkdirSync(join(projectDir, 'src/app'), { recursive: true });
+  mkdirSync(join(projectDir, 'src/app/services'), { recursive: true });
+  mkdirSync(join(projectDir, 'src/app/components'), { recursive: true });
+  mkdirSync(join(projectDir, 'src/mycelia'), { recursive: true });
+
+  // Create package.json
+  const packageJson = {
+    name: projectName,
+    version: '1.0.0',
+    type: 'module',
+    scripts: {
+      start: 'ng serve',
+      build: 'ng build',
+      test: 'ng test'
+    },
+    dependencies: {
+      'mycelia-kernel-plugin': '^1.3.0',
+      '@angular/core': '^17.0.0',
+      '@angular/common': '^17.0.0',
+      'rxjs': '^7.8.0'
+    },
+    devDependencies: {
+      '@angular/cli': '^17.0.0',
+      '@angular/compiler-cli': '^17.0.0',
+      'typescript': '^5.0.0'
+    }
+  };
+
+  writeFileSync(
+    join(projectDir, 'package.json'),
+    JSON.stringify(packageJson, null, 2),
+    'utf8'
+  );
+
+  // Create Mycelia service
+  const myceliaService = `import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable } from 'rxjs';
+import { createMyceliaService } from 'mycelia-kernel-plugin/angular';
+import { buildSystem } from '../mycelia/system.builder.js';
+
+@Injectable({ providedIn: 'root' })
+export class MyceliaService {
+  private service = createMyceliaService(buildSystem);
+
+  get system$(): Observable<any> {
+    return this.service.system$;
+  }
+
+  getSystem() {
+    return this.service.getSystem();
+  }
+
+  useFacet(kind: string) {
+    return this.service.useFacet(kind);
+  }
+
+  useListener(eventName: string, handler: Function) {
+    return this.service.useListener(eventName, handler);
+  }
+
+  async dispose() {
+    await this.service.dispose();
+  }
+}
+`;
+
+  writeFileSync(join(projectDir, 'src/app/services/mycelia.service.ts'), myceliaService, 'utf8');
+
+  // Create system builder
+  const systemBuilder = `import { useBase } from 'mycelia-kernel-plugin';
+import { useListeners } from 'mycelia-kernel-plugin';
+
+export async function buildSystem() {
+  return useBase('${projectName}')
+    .use(useListeners)
+    .build();
+}
+`;
+
+  writeFileSync(join(projectDir, 'src/mycelia/system.builder.ts'), systemBuilder, 'utf8');
+
+  // Create README
+  const readme = `# ${projectName}
+
+An Angular application built with Mycelia Plugin System.
+
+## Getting Started
+
+\`\`\`bash
+npm install
+ng serve
+\`\`\`
+
+## Structure
+
+- \`src/app/services/\` - Angular services (including MyceliaService)
+- \`src/app/components/\` - Angular components
+- \`src/mycelia/\` - Mycelia plugin code (framework-agnostic)
+`;
+
+  writeFileSync(join(projectDir, 'README.md'), readme, 'utf8');
+
+  console.log(`✅ Angular project created: ${projectDir}`);
+  console.log(`\nNext steps:`);
+  console.log(`  cd ${projectDir}`);
+  console.log(`  npm install`);
+  console.log(`  ng serve`);
+}
+
+/**
+ * Initialize a Qwik project with Mycelia bindings
+ */
+function initQwikProject(projectName) {
+  const projectDir = projectName;
+  
+  if (existsSync(projectDir)) {
+    console.error(`Error: Directory already exists: ${projectDir}`);
+    process.exit(1);
+  }
+
+  console.log(`Creating Qwik project: ${projectName}...`);
+
+  // Create directory structure
+  mkdirSync(projectDir, { recursive: true });
+  mkdirSync(join(projectDir, 'src'), { recursive: true });
+  mkdirSync(join(projectDir, 'src/components'), { recursive: true });
+  mkdirSync(join(projectDir, 'src/mycelia'), { recursive: true });
+
+  // Create package.json
+  const packageJson = {
+    name: projectName,
+    version: '1.0.0',
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'vite build',
+      preview: 'vite preview'
+    },
+    dependencies: {
+      'mycelia-kernel-plugin': '^1.3.0',
+      '@builder.io/qwik': '^1.0.0',
+      '@builder.io/qwik-city': '^1.0.0'
+    },
+    devDependencies: {
+      'vite': '^5.0.0',
+      '@vitejs/plugin-qwik': '^1.0.0'
+    }
+  };
+
+  writeFileSync(
+    join(projectDir, 'package.json'),
+    JSON.stringify(packageJson, null, 2),
+    'utf8'
+  );
+
+  // Create App component
+  const appComponent = `import { component$ } from '@builder.io/qwik';
+import { MyceliaProvider } from 'mycelia-kernel-plugin/qwik';
+import { buildSystem } from './mycelia/system.builder.js';
+import { TodoApp } from './components/TodoApp';
+
+export default component$(() => {
+  return (
+    <MyceliaProvider build={buildSystem}>
+      <TodoApp />
+    </MyceliaProvider>
+  );
+});
+`;
+
+  writeFileSync(join(projectDir, 'src/App.tsx'), appComponent, 'utf8');
+
+  // Create system builder
+  const systemBuilder = `import { useBase } from 'mycelia-kernel-plugin';
+import { useListeners } from 'mycelia-kernel-plugin';
+
+export async function buildSystem() {
+  return useBase('${projectName}')
+    .use(useListeners)
+    .build();
+}
+`;
+
+  writeFileSync(join(projectDir, 'src/mycelia/system.builder.ts'), systemBuilder, 'utf8');
+
+  // Create example component
+  const todoComponent = `import { component$ } from '@builder.io/qwik';
+import { useFacet, useListener } from 'mycelia-kernel-plugin/qwik';
+
+export const TodoApp = component$(() => {
+  const todos = useFacet('todos');
+  useListener('todos:changed', (msg) => {
+    console.log('Todos changed:', msg.body);
+  });
+
+  return (
+    <div>
+      <h1>Todo App</h1>
+      {todos.value && <p>Todos facet loaded</p>}
+    </div>
+  );
+});
+`;
+
+  writeFileSync(join(projectDir, 'src/components/TodoApp.tsx'), todoComponent, 'utf8');
+
+  // Create README
+  const readme = `# ${projectName}
+
+A Qwik application built with Mycelia Plugin System.
+
+## Getting Started
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Structure
+
+- \`src/components/\` - Qwik components
+- \`src/mycelia/\` - Mycelia plugin code (framework-agnostic)
+`;
+
+  writeFileSync(join(projectDir, 'README.md'), readme, 'utf8');
+
+  console.log(`✅ Qwik project created: ${projectDir}`);
+  console.log(`\nNext steps:`);
+  console.log(`  cd ${projectDir}`);
+  console.log(`  npm install`);
+  console.log(`  npm run dev`);
+}
+
 /**
  * Show help message
  */
@@ -884,6 +1141,8 @@ Commands:
   init react [name]       Initialize a React project with Mycelia bindings
   init vue [name]         Initialize a Vue 3 project with Mycelia bindings
   init svelte [name]      Initialize a Svelte project with Mycelia bindings
+  init angular [name]     Initialize an Angular project with Mycelia bindings
+  init qwik [name]        Initialize a Qwik project with Mycelia bindings
   help                    Show this help message
 
 Examples:
@@ -893,6 +1152,8 @@ Examples:
   mycelia-kernel-plugin init react my-react-app
   mycelia-kernel-plugin init vue my-vue-app
   mycelia-kernel-plugin init svelte my-svelte-app
+  mycelia-kernel-plugin init angular my-angular-app
+  mycelia-kernel-plugin init qwik my-qwik-app
 
 For more information, visit:
   https://github.com/lesfleursdelanuitdev/mycelia-kernel-plugin-system

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mycelia-kernel-plugin",
-  "version": "1.3.0",
-  "description": "A sophisticated, dependency-aware plugin system with transaction safety and lifecycle management",
+  "version": "1.4.0",
+  "description": "A sophisticated, framework-agnostic plugin system with transaction safety, lifecycle management, and official bindings for React, Vue 3, Svelte, Angular, Qwik, and Solid.js",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -37,7 +37,10 @@
     "./contract/contracts": "./src/contract/contracts/index.js",
     "./react": "./src/react/index.js",
     "./vue": "./src/vue/index.js",
-    "./svelte": "./src/svelte/index.js"
+    "./svelte": "./src/svelte/index.js",
+    "./angular": "./src/angular/index.js",
+    "./qwik": "./src/qwik/index.js",
+    "./solid": "./src/solid/index.js"
   },
   "files": [
     "src/",
@@ -56,7 +59,11 @@
   "peerDependencies": {
     "react": ">=16.8.0",
     "vue": ">=3.0.0",
-    "svelte": ">=3.0.0"
+    "svelte": ">=3.0.0",
+    "@angular/core": ">=15.0.0",
+    "@builder.io/qwik": ">=1.0.0",
+    "solid-js": ">=1.0.0",
+    "rxjs": ">=7.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",

package/src/angular/builders.js

@@ -0,0 +1,37 @@
+/**
+ * Angular Builder Helpers
+ */
+
+/**
+ * createAngularSystemBuilder - Create a reusable system builder function for Angular
+ * 
+ * @param {string} name - System name
+ * @param {Function} configure - Configuration function: (builder) => builder
+ * @returns {Function} Build function: () => Promise<System>
+ * 
+ * @example
+ * ```ts
+ * import { useBase } from 'mycelia-kernel-plugin';
+ * 
+ * const buildTodoSystem = createAngularSystemBuilder('todo-app', (b) =>
+ *   b
+ *     .config('database', { host: 'localhost' })
+ *     .use(useDatabase)
+ *     .use(useListeners)
+ * );
+ * 
+ * // Then use in MyceliaModule
+ * MyceliaModule.forRoot({ build: buildTodoSystem })
+ * ```
+ */
+export function createAngularSystemBuilder(name, configure) {
+  return async function build() {
+    // Import useBase - users should have it available
+    const { useBase } = await import('../utils/use-base.js');
+    let builder = useBase(name);
+    builder = configure(builder);
+    return builder.build();
+  };
+}
+
+

package/src/angular/helpers.js

@@ -0,0 +1,102 @@
+/**
+ * Angular Helper Functions
+ * 
+ * Helper functions for working with Mycelia in Angular components
+ */
+
+/**
+ * useFacet - Get a facet by kind (for use in Angular components)
+ * 
+ * @param {Object} myceliaService - MyceliaService instance
+ * @param {string} kind - Facet kind identifier
+ * @returns {import('rxjs').Observable} Observable that emits the facet
+ * 
+ * @example
+ * ```ts
+ * @Component({...})
+ * export class MyComponent {
+ *   db$ = useFacet(this.mycelia, 'database');
+ * }
+ * ```
+ */
+export function useFacet(myceliaService, kind) {
+  const { map } = require('rxjs/operators');
+  return myceliaService.system$.pipe(
+    map(system => system?.find?.(kind) ?? null)
+  );
+}
+
+/**
+ * useListener - Register an event listener in Angular component
+ * 
+ * @param {Object} myceliaService - MyceliaService instance
+ * @param {string} eventName - Event name/path
+ * @param {Function} handler - Handler function
+ * @returns {Function} Unsubscribe function
+ * 
+ * @example
+ * ```ts
+ * @Component({...})
+ * export class MyComponent implements OnInit, OnDestroy {
+ *   private unsubscribe: Function;
+ *   
+ *   ngOnInit() {
+ *     this.unsubscribe = useListener(this.mycelia, 'user:created', (msg) => {
+ *       console.log('User created:', msg.body);
+ *     });
+ *   }
+ *   
+ *   ngOnDestroy() {
+ *     this.unsubscribe();
+ *   }
+ * }
+ * ```
+ */
+export function useListener(myceliaService, eventName, handler) {
+  return myceliaService.useListener(eventName, handler);
+}
+
+/**
+ * useEventStream - Subscribe to events as an RxJS observable
+ * 
+ * @param {Object} myceliaService - MyceliaService instance
+ * @param {string} eventName - Event name/path
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.accumulate=false] - If true, accumulate events
+ * @returns {import('rxjs').Observable} Observable that emits event messages
+ * 
+ * @example
+ * ```ts
+ * @Component({...})
+ * export class EventListComponent {
+ *   events$ = useEventStream(this.mycelia, 'todo:created', { accumulate: true });
+ * }
+ * ```
+ */
+export function useEventStream(myceliaService, eventName, options = {}) {
+  const { Subject } = require('rxjs');
+  const { scan, startWith } = require('rxjs/operators');
+  const { accumulate = false } = options;
+  
+  const subject = new Subject();
+  
+  const unsubscribe = myceliaService.useListener(eventName, (msg) => {
+    subject.next(msg.body);
+  });
+  
+  let stream$ = subject.asObservable();
+  
+  if (accumulate) {
+    stream$ = stream$.pipe(
+      scan((acc, value) => [...acc, value], []),
+      startWith([])
+    );
+  }
+  
+  // Note: In Angular, you'd typically handle unsubscription in ngOnDestroy
+  // This is a simplified version - real implementation would need proper cleanup
+  
+  return stream$;
+}
+
+