mycelia-kernel-plugin 1.2.0 → 1.3.0

package/src/svelte/builders.js

@@ -0,0 +1,43 @@
+/**
+ * Mycelia Plugin System - Svelte Builder Helpers
+ * 
+ * Svelte utilities for creating system builders.
+ */
+
+/**
+ * createSvelteSystemBuilder - 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 { createSvelteSystemBuilder } from 'mycelia-kernel-plugin/svelte';
+ * 
+ * const buildTodoSystem = createSvelteSystemBuilder('todo-app', (b) =>
+ *   b
+ *     .config('database', { host: 'localhost' })
+ *     .use(useDatabase)
+ *     .use(useListeners)
+ * );
+ * 
+ * // Then use in component
+ * onMount(async () => {
+ *   const system = await buildTodoSystem();
+ *   setMyceliaSystem(system);
+ * });
+ * ```
+ */
+export function createSvelteSystemBuilder(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/svelte/index.js

@@ -0,0 +1,183 @@
+/**
+ * Mycelia Plugin System - Svelte Bindings
+ * 
+ * Svelte utilities that make the Mycelia Plugin System feel natural
+ * inside Svelte applications using stores and context.
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { setMyceliaSystem, useFacet, useListener } from 'mycelia-kernel-plugin/svelte';
+ *   import { buildSystem } from './system.js';
+ *   
+ *   let system;
+ *   buildSystem().then(s => {
+ *     system = s;
+ *     setMyceliaSystem(system);
+ *   });
+ * </script>
+ * ```
+ */
+
+import { writable, derived, get } from 'svelte/store';
+import { setContext, getContext } from 'svelte';
+
+// ============================================================================
+// Core Bindings: Context + Basic Stores
+// ============================================================================
+
+const MYCELIA_KEY = Symbol('mycelia');
+
+/**
+ * setMyceliaSystem - Provide Mycelia system to Svelte component tree
+ * 
+ * @param {Object} system - The Mycelia system instance
+ * @returns {Object} Context object with system, loading, and error stores
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { onMount } from 'svelte';
+ *   import { setMyceliaSystem } from 'mycelia-kernel-plugin/svelte';
+ *   import { buildSystem } from './system.js';
+ *   
+ *   let system;
+ *   
+ *   onMount(async () => {
+ *     system = await buildSystem();
+ *     setMyceliaSystem(system);
+ *   });
+ * </script>
+ * ```
+ */
+export function setMyceliaSystem(system) {
+  const systemStore = writable(system);
+  const loadingStore = writable(false);
+  const errorStore = writable(null);
+  
+  const context = {
+    system: systemStore,
+    loading: loadingStore,
+    error: errorStore
+  };
+  
+  setContext(MYCELIA_KEY, context);
+  
+  return context;
+}
+
+/**
+ * getMyceliaSystem - Get Mycelia system store from context
+ * 
+ * @returns {import('svelte/store').Writable} Writable store containing the system instance
+ * @throws {Error} If used outside setMyceliaSystem context
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getMyceliaSystem } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const systemStore = getMyceliaSystem();
+ *   $: system = $systemStore;
+ * </script>
+ * ```
+ */
+export function getMyceliaSystem() {
+  const context = getContext(MYCELIA_KEY);
+  if (!context) {
+    throw new Error('getMyceliaSystem must be used within setMyceliaSystem context');
+  }
+  return context.system;
+}
+
+/**
+ * getMyceliaContext - Get the full Mycelia context (system, loading, error stores)
+ * 
+ * @returns {Object} Context object with system, loading, and error stores
+ * @throws {Error} If used outside setMyceliaSystem context
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getMyceliaContext } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const { system, loading, error } = getMyceliaContext();
+ * </script>
+ * 
+ * {#if $loading}
+ *   <div>Loading...</div>
+ * {:else if $error}
+ *   <div>Error: {$error.message}</div>
+ * {:else}
+ *   <div>System ready: {$system.name}</div>
+ * {/if}
+ * ```
+ */
+export function getMyceliaContext() {
+  const context = getContext(MYCELIA_KEY);
+  if (!context) {
+    throw new Error('getMyceliaContext must be used within setMyceliaSystem context');
+  }
+  return context;
+}
+
+/**
+ * useMycelia - Get Mycelia system store (reactive)
+ * 
+ * @returns {import('svelte/store').Writable} Writable store containing the system instance
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMycelia } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const systemStore = useMycelia();
+ *   $: system = $systemStore;
+ *   $: db = system?.find('database');
+ * </script>
+ * ```
+ */
+export function useMycelia() {
+  return getMyceliaSystem();
+}
+
+/**
+ * useFacet - Get a facet by kind from the system (reactive store)
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {import('svelte/store').Readable} Readable store containing the facet instance, or null if not found
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFacet } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const dbStore = useFacet('database');
+ *   $: db = $dbStore;
+ * </script>
+ * 
+ * {#if db}
+ *   <div>Database ready</div>
+ * {/if}
+ * ```
+ */
+export function useFacet(kind) {
+  const systemStore = getMyceliaSystem();
+  
+  return derived(systemStore, ($system) => {
+    return $system?.find?.(kind) ?? null;
+  });
+}
+
+// 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 { createSvelteSystemBuilder } from './builders.js';
+
+// Re-export store generator
+export { createFacetStore } from './stores.js';
+

package/src/svelte/listeners.js

@@ -0,0 +1,96 @@
+/**
+ * Mycelia Plugin System - Svelte Listener Helpers
+ * 
+ * Svelte utilities for event listener management.
+ */
+
+import { writable, get } from 'svelte/store';
+import { onDestroy } from 'svelte';
+import { getMyceliaSystem } from './index.js';
+
+/**
+ * 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
+ * ```svelte
+ * <script>
+ *   import { useListener } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   useListener('user:created', (msg) => {
+ *     console.log('User created:', msg.body);
+ *   });
+ * </script>
+ * ```
+ */
+export function useListener(eventName, handler) {
+  const systemStore = getMyceliaSystem();
+  let listeners = null;
+  let unsubscribe = null;
+  
+  const setup = () => {
+    const system = get(systemStore);
+    if (!system) return;
+    
+    listeners = system?.listeners;
+    if (!listeners || !listeners.hasListeners?.()) return;
+    
+    listeners.on(eventName, handler);
+  };
+  
+  // Subscribe to system store to set up listener when system is available
+  unsubscribe = systemStore.subscribe(() => {
+    setup();
+  });
+  
+  // Initial setup
+  setup();
+  
+  onDestroy(() => {
+    if (listeners) {
+      listeners.off?.(eventName, handler);
+    }
+    if (unsubscribe) {
+      unsubscribe();
+    }
+  });
+}
+
+/**
+ * useEventStream - Subscribe to events and keep them in a reactive store
+ * 
+ * @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('svelte/store').Writable} Writable store containing latest event value, array of events, or null
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEventStream } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const events = useEventStream('todo:created', { accumulate: true });
+ * </script>
+ * 
+ * {#each $events as event}
+ *   <div>{event.text}</div>
+ * {/each}
+ * ```
+ */
+export function useEventStream(eventName, options = {}) {
+  const { accumulate = false } = options;
+  const store = writable(accumulate ? [] : null);
+  
+  useListener(eventName, (msg) => {
+    if (accumulate) {
+      store.update(events => [...events, msg.body]);
+    } else {
+      store.set(msg.body);
+    }
+  });
+  
+  return store;
+}
+

package/src/svelte/queues.js

@@ -0,0 +1,114 @@
+/**
+ * Mycelia Plugin System - Svelte Queue Helpers
+ * 
+ * Svelte utilities for queue management.
+ */
+
+import { writable, get } from 'svelte/store';
+import { onMount, onDestroy } from 'svelte';
+import { useFacet } from './index.js';
+
+/**
+ * useQueueStatus - Get queue status with reactive updates
+ * 
+ * @returns {import('svelte/store').Writable} Writable store containing queue status object
+ * @returns {number} size - Current queue size
+ * @returns {number} capacity - Maximum queue capacity
+ * @returns {number} utilization - Utilization ratio (0-1)
+ * @returns {boolean} isFull - Whether queue is full
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useQueueStatus } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const status = useQueueStatus();
+ * </script>
+ * 
+ * <div>Queue: {$status.size}/{$status.capacity}</div>
+ * ```
+ */
+export function useQueueStatus() {
+  const queueStore = useFacet('queue');
+  const statusStore = writable({
+    size: 0,
+    capacity: 0,
+    utilization: 0,
+    isFull: false
+  });
+  
+  let intervalId = null;
+  
+  const updateStatus = () => {
+    const queue = get(queueStore);
+    if (!queue?.getQueueStatus) return;
+    
+    const newStatus = queue.getQueueStatus();
+    statusStore.set({
+      size: newStatus.size || 0,
+      capacity: newStatus.maxSize || 0,
+      utilization: newStatus.utilization || 0,
+      isFull: newStatus.isFull || false
+    });
+  };
+  
+  onMount(() => {
+    updateStatus();
+    intervalId = setInterval(updateStatus, 100); // Poll every 100ms
+  });
+  
+  onDestroy(() => {
+    if (intervalId) {
+      clearInterval(intervalId);
+    }
+  });
+  
+  return statusStore;
+}
+
+/**
+ * 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
+ * ```svelte
+ * <script>
+ *   import { useQueueDrain } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   useQueueDrain({
+ *     interval: 50,
+ *     onMessage: (msg) => console.log('Processed:', msg)
+ *   });
+ * </script>
+ * ```
+ */
+export function useQueueDrain(options = {}) {
+  const { interval = 100, onMessage } = options;
+  const queueStore = useFacet('queue');
+  let processInterval = null;
+  
+  onMount(() => {
+    const queue = get(queueStore);
+    if (!queue || !queue.hasMessagesToProcess) return;
+    
+    processInterval = setInterval(() => {
+      const currentQueue = get(queueStore);
+      if (currentQueue?.hasMessagesToProcess()) {
+        const next = currentQueue.selectNextMessage();
+        if (next && onMessage) {
+          onMessage(next.msg, next.options);
+        }
+      }
+    }, interval);
+  });
+  
+  onDestroy(() => {
+    if (processInterval) {
+      clearInterval(processInterval);
+    }
+  });
+}
+

package/src/svelte/stores.js

@@ -0,0 +1,36 @@
+/**
+ * Mycelia Plugin System - Svelte Store Generator
+ * 
+ * Utility for generating custom stores for specific facets.
+ */
+
+import { useFacet } from './index.js';
+
+/**
+ * createFacetStore - Generate a custom store for a specific facet kind
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Function} Custom store function: () => import('svelte/store').Readable
+ * 
+ * @example
+ * ```js
+ * // stores/todos.js
+ * import { createFacetStore } from 'mycelia-kernel-plugin/svelte';
+ * 
+ * export const useTodos = createFacetStore('todos');
+ * 
+ * // In component
+ * <script>
+ *   import { useTodos } from './stores/todos.js';
+ *   
+ *   const todosStore = useTodos();
+ *   $: todos = $todosStore;
+ * </script>
+ * ```
+ */
+export function createFacetStore(kind) {
+  return function useNamedFacet() {
+    return useFacet(kind);
+  };
+}
+

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