mycelia-kernel-plugin 1.3.0 → 1.4.1

package/src/qwik/index.js

@@ -0,0 +1,178 @@
+/**
+ * Mycelia Plugin System - Qwik Bindings
+ * 
+ * Qwik utilities that make the Mycelia Plugin System feel natural
+ * inside Qwik applications using signals and context.
+ * 
+ * @example
+ * ```tsx
+ * import { MyceliaProvider, useFacet, useListener } from 'mycelia-kernel-plugin/qwik';
+ * 
+ * const buildSystem = () => useBase('app')
+ *   .use(useDatabase)
+ *   .build();
+ * 
+ * export default component$(() => {
+ *   return (
+ *     <MyceliaProvider build={buildSystem}>
+ *       <MyComponent />
+ *     </MyceliaProvider>
+ *   );
+ * });
+ * 
+ * export const MyComponent = component$(() => {
+ *   const db = useFacet('database');
+ *   useListener('user:created', (msg) => console.log(msg));
+ *   // ...
+ * });
+ * ```
+ */
+
+import { createContextId, useContextProvider, useContext, useSignal, useStore, useTask$, component$, Slot } from '@builder.io/qwik';
+
+// ============================================================================
+// Core Bindings: Provider + Basic Hooks
+// ============================================================================
+
+const MyceliaContextId = createContextId('mycelia');
+
+/**
+ * MyceliaProvider - Provides Mycelia system to Qwik component tree
+ * 
+ * @param {Object} props
+ * @param {Function} props.build - Async function that returns a built system
+ * @param {import('@builder.io/qwik').QRL} props.children - Child components
+ * @param {import('@builder.io/qwik').QRL} [props.fallback] - Optional loading/fallback component
+ * 
+ * @example
+ * ```tsx
+ * export default component$(() => {
+ *   return (
+ *     <MyceliaProvider build={buildSystem}>
+ *       <App />
+ *     </MyceliaProvider>
+ *   );
+ * });
+ * ```
+ */
+export const MyceliaProvider = component$(({ build, fallback = null }) => {
+  const system = useSignal(null);
+  const error = useSignal(null);
+  const loading = useSignal(true);
+
+  useTask$(async () => {
+    try {
+      const builtSystem = await build();
+      system.value = builtSystem;
+      error.value = null;
+    } catch (err) {
+      error.value = err;
+      system.value = null;
+    } finally {
+      loading.value = false;
+    }
+  });
+
+  const context = {
+    system,
+    error,
+    loading
+  };
+
+  useContextProvider(MyceliaContextId, context);
+
+  if (error.value) {
+    throw error.value; // Let error boundaries handle it
+  }
+
+  if (loading.value) {
+    return fallback || <div>Loading...</div>;
+  }
+
+  return <Slot />;
+});
+
+/**
+ * useMycelia - Get the Mycelia system from context
+ * 
+ * @returns {Object} The Mycelia system instance
+ * @throws {Error} If used outside MyceliaProvider
+ * 
+ * @example
+ * ```tsx
+ * export const MyComponent = component$(() => {
+ *   const system = useMycelia();
+ *   // Use system.find(), system.listeners, etc.
+ * });
+ * ```
+ */
+export function useMycelia() {
+  const context = useContext(MyceliaContextId);
+  if (!context) {
+    throw new Error('useMycelia must be used within a MyceliaProvider');
+  }
+  return context.system.value;
+}
+
+/**
+ * useMyceliaContext - Get the full Mycelia context (system, loading, error)
+ * 
+ * @returns {Object} Context object with system, loading, and error signals
+ * @throws {Error} If used outside MyceliaProvider
+ * 
+ * @example
+ * ```tsx
+ * export const MyComponent = component$(() => {
+ *   const { system, loading, error } = useMyceliaContext();
+ *   if (loading.value) return <div>Loading...</div>;
+ *   if (error.value) return <div>Error: {error.value.message}</div>;
+ *   return <div>System: {system.value.name}</div>;
+ * });
+ * ```
+ */
+export function useMyceliaContext() {
+  const context = useContext(MyceliaContextId);
+  if (!context) {
+    throw new Error('useMyceliaContext must be used within a MyceliaProvider');
+  }
+  return context;
+}
+
+/**
+ * useFacet - Get a facet by kind from the system (reactive signal)
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {import('@builder.io/qwik').Signal} Signal containing the facet instance, or null if not found
+ * 
+ * @example
+ * ```tsx
+ * export const UserList = component$(() => {
+ *   const db = useFacet('database');
+ *   // Use db.value.query(), etc.
+ * });
+ * ```
+ */
+export function useFacet(kind) {
+  const context = useMyceliaContext();
+  const facet = useSignal(null);
+
+  useTask$(({ track }) => {
+    const system = track(() => context.system.value);
+    facet.value = system?.find?.(kind) ?? null;
+  });
+
+  return facet;
+}
+
+// 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 { createQwikSystemBuilder } from './builders.js';
+
+// Re-export facet signal generator
+export { createFacetSignal } from './signals.js';
+

package/src/qwik/listeners.js

@@ -0,0 +1,96 @@
+/**
+ * Qwik Listener Helpers
+ */
+
+import { useTask$, useSignal } from '@builder.io/qwik';
+import { useMycelia } from './index.js';
+
+// Note: Qwik's useTask$ requires proper serialization
+// Event handlers should be QRL-wrapped for proper serialization
+
+/**
+ * useListener - Register an event listener with automatic cleanup
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Function} handler - Handler function: (message) => void
+ * 
+ * @example
+ * ```tsx
+ * export const AuditLog = component$(() => {
+ *   useListener('user:created', (msg) => {
+ *     console.log('User created:', msg.body);
+ *   });
+ *   // ...
+ * });
+ * ```
+ */
+export function useListener(eventName, handler) {
+  const system = useMycelia();
+  const listeners = system.listeners; // useListeners facet
+
+  useTask$(({ cleanup }) => {
+    if (!listeners || !listeners.hasListeners?.()) {
+      return;
+    }
+
+    const wrappedHandler = (msg) => {
+      handler(msg);
+    };
+
+    listeners.on(eventName, wrappedHandler);
+
+    cleanup(() => {
+      listeners.off?.(eventName, wrappedHandler);
+    });
+  });
+}
+
+/**
+ * useEventStream - Subscribe to events and keep them in Qwik signal
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.accumulate=false] - If true, accumulate events in array
+ * @returns {import('@builder.io/qwik').Signal} Signal containing latest event value, array of events, or null
+ * 
+ * @example
+ * ```tsx
+ * export const EventList = component$(() => {
+ *   const events = useEventStream('todo:created', { accumulate: true });
+ *   return (
+ *     <ul>
+ *       {events.value?.map(e => <li key={e.id}>{e.text}</li>)}
+ *     </ul>
+ *   );
+ * });
+ * ```
+ */
+export function useEventStream(eventName, options = {}) {
+  const { accumulate = false } = options;
+  const value = useSignal(accumulate ? [] : null);
+  const system = useMycelia();
+  const listeners = system.listeners;
+
+  useTask$(({ cleanup }) => {
+    if (!listeners || !listeners.hasListeners?.()) {
+      return;
+    }
+
+    const handler = (msg) => {
+      if (accumulate) {
+        value.value = [...value.value, msg.body];
+      } else {
+        value.value = msg.body;
+      }
+    };
+
+    listeners.on(eventName, handler);
+
+    cleanup(() => {
+      listeners.off?.(eventName, handler);
+    });
+  });
+
+  return value;
+}
+

package/src/qwik/queues.js

@@ -0,0 +1,87 @@
+/**
+ * Qwik Queue Helpers
+ */
+
+import { useTask$, useSignal } from '@builder.io/qwik';
+import { useFacet } from './index.js';
+
+/**
+ * useQueueStatus - Get queue status with reactive updates
+ * 
+ * @returns {import('@builder.io/qwik').Signal} Signal containing queue status object
+ * 
+ * @example
+ * ```tsx
+ * export const QueueStatus = component$(() => {
+ *   const status = useQueueStatus();
+ *   return <div>Queue: {status.value.size}/{status.value.capacity}</div>;
+ * });
+ * ```
+ */
+export function useQueueStatus() {
+  const queue = useFacet('queue');
+  const status = useSignal({ size: 0, capacity: 0, utilization: 0, isFull: false });
+
+  useTask$(({ track }) => {
+    const queueInstance = track(() => queue.value);
+    if (!queueInstance || !queueInstance.getQueueStatus) return;
+
+    const updateStatus = () => {
+      const newStatus = queueInstance.getQueueStatus();
+      status.value = {
+        size: newStatus.size || 0,
+        capacity: newStatus.maxSize || 0,
+        utilization: newStatus.utilization || 0,
+        isFull: newStatus.isFull || false
+      };
+    };
+
+    updateStatus();
+    const interval = setInterval(updateStatus, 100); // Poll every 100ms
+
+    return () => clearInterval(interval);
+  });
+
+  return status;
+}
+
+/**
+ * useQueueDrain - Automatically drain queue on mount
+ * 
+ * @param {Object} [options={}] - Options
+ * @param {number} [options.interval=100] - Polling interval in ms
+ * @param {Function} [options.onMessage] - Callback for each message: (msg, options) => void
+ * 
+ * @example
+ * ```tsx
+ * export const QueueProcessor = component$(() => {
+ *   useQueueDrain({
+ *     interval: 50,
+ *     onMessage: (msg) => console.log('Processed:', msg)
+ *   });
+ *   return null;
+ * });
+ * ```
+ */
+export function useQueueDrain(options = {}) {
+  const { interval = 100, onMessage } = options;
+  const queue = useFacet('queue');
+
+  useTask$(({ track, cleanup }) => {
+    const queueInstance = track(() => queue.value);
+    if (!queueInstance || !queueInstance.hasMessagesToProcess) return;
+
+    const processInterval = setInterval(() => {
+      if (queueInstance.hasMessagesToProcess()) {
+        const next = queueInstance.selectNextMessage();
+        if (next && onMessage) {
+          onMessage(next.msg, next.options);
+        }
+      }
+    }, interval);
+
+    cleanup(() => clearInterval(processInterval));
+  });
+}
+
+

package/src/qwik/signals.js

@@ -0,0 +1,32 @@
+/**
+ * Qwik Signal Generators
+ */
+
+import { useFacet } from './index.js';
+
+/**
+ * createFacetSignal - Generate a signal for a specific facet kind
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Function} Hook function: () => Signal<Facet | null>
+ * 
+ * @example
+ * ```ts
+ * // In bindings/todo-signals.ts
+ * export const useTodoStore = createFacetSignal('todoStore');
+ * export const useAuth = createFacetSignal('auth');
+ * 
+ * // In component
+ * export const TodoList = component$(() => {
+ *   const todoStore = useTodoStore();
+ *   // Use todoStore.value...
+ * });
+ * ```
+ */
+export function createFacetSignal(kind) {
+  return function useNamedFacet() {
+    return useFacet(kind);
+  };
+}
+
+

package/src/react/README.md

@@ -172,3 +172,6 @@ See the main [README.md](../../README.md) and [examples](../../examples/) direct
 - React >= 16.8.0 (for hooks support)
 - Mycelia Plugin System (included)
 
+
+
+

package/src/solid/README.md

@@ -0,0 +1,69 @@
+# Solid.js Bindings
+
+Solid.js utilities that make the Mycelia Plugin System feel natural inside Solid.js applications using signals and context.
+
+## Overview
+
+The Solid.js bindings provide a set of components and hooks that integrate the Mycelia Plugin System seamlessly with Solid.js. They handle lifecycle management, context provisioning, and automatic cleanup, making the plugin system feel like a native Solid.js data layer.
+
+## Installation
+
+```bash
+npm install mycelia-kernel-plugin solid-js
+```
+
+**Requirements:**
+- Solid.js >= 1.0.0
+- Mycelia Plugin System (included in package)
+
+## Quick Start
+
+```jsx
+import { MyceliaProvider, useFacet, useListener } from 'mycelia-kernel-plugin/solid';
+import { useBase, useListeners, useDatabase } from 'mycelia-kernel-plugin';
+
+// Create system builder
+const buildSystem = () =>
+  useBase('my-app')
+    .config('database', { host: 'localhost' })
+    .use(useDatabase)
+    .use(useListeners)
+    .build();
+
+// Bootstrap your app
+export default function App() {
+  return (
+    <MyceliaProvider build={buildSystem}>
+      <MyComponent />
+    </MyceliaProvider>
+  );
+}
+
+// Use in components
+function MyComponent() {
+  const db = useFacet('database');
+  const system = useMycelia();
+  
+  useListener('user:created', (msg) => {
+    console.log('User created:', msg.body);
+  });
+  
+  // Use db(), system(), etc.
+}
+```
+
+## Documentation
+
+- **[Core Bindings](./CORE-BINDINGS.md)** - Provider and basic hooks
+- **[Listener Helpers](./LISTENER-HELPERS.md)** - Event listener utilities
+- **[Queue Helpers](./QUEUE-HELPERS.md)** - Queue management utilities
+- **[Builder Helpers](./BUILDER-HELPERS.md)** - System builder utilities
+- **[Signal Generator](./SIGNAL-GENERATOR.md)** - Custom signal generation
+
+## Features
+
+- **Automatic Lifecycle Management** - System is built on mount and disposed on unmount
+- **Context-Based Access** - System available throughout component tree
+- **Automatic Cleanup** - Listeners and effects cleaned up automatically
+- **Solid Signals** - Reactive state with Solid.js signals
+