@directive-run/knowledge 0.2.0

package/examples/dynamic-modules.ts

@@ -0,0 +1,293 @@
+// Example: dynamic-modules
+// Source: examples/dynamic-modules/src/modules.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Dynamic Modules — Directive Module Definitions
+ *
+ * Dashboard module (always loaded) + 3 dynamic modules (Counter, Weather, Dice).
+ * Demonstrates runtime module registration, namespaced fact access,
+ * constraints, resolvers, and derivations across independent modules.
+ */
+
+import { type ModuleSchema, createModule, t } from "@directive-run/core";
+import { mockFetchWeather } from "./mock-weather.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface EventLogEntry {
+  timestamp: number;
+  event: string;
+  detail: string;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function addLogEntry(facts: any, event: string, detail: string): void {
+  const log = [...(facts.eventLog as EventLogEntry[])];
+  log.push({ timestamp: Date.now(), event, detail });
+  if (log.length > 50) {
+    log.splice(0, log.length - 50);
+  }
+  facts.eventLog = log;
+}
+
+// ============================================================================
+// Dashboard Module (core, always loaded)
+// ============================================================================
+
+export const dashboardSchema = {
+  facts: {
+    loadedModules: t.object<string[]>(),
+    eventLog: t.object<EventLogEntry[]>(),
+  },
+  derivations: {
+    loadedCount: t.number(),
+  },
+  events: {
+    moduleLoaded: { name: t.string() },
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+export const dashboardModule = createModule("dashboard", {
+  schema: dashboardSchema,
+
+  init: (facts) => {
+    facts.loadedModules = [];
+    facts.eventLog = [];
+  },
+
+  derive: {
+    loadedCount: (facts) => (facts.loadedModules as string[]).length,
+  },
+
+  events: {
+    moduleLoaded: (facts, { name }) => {
+      facts.loadedModules = [...(facts.loadedModules as string[]), name];
+      addLogEntry(facts, "loaded", `Loaded "${name}" module`);
+    },
+  },
+});
+
+// ============================================================================
+// Counter Module (dynamic)
+// ============================================================================
+
+export const counterSchema = {
+  facts: {
+    count: t.number(),
+    step: t.number(),
+  },
+  derivations: {
+    isNearMax: t.boolean(),
+  },
+  events: {
+    increment: {},
+    decrement: {},
+    setStep: { value: t.number() },
+  },
+  requirements: {
+    COUNTER_RESET: {},
+  },
+} satisfies ModuleSchema;
+
+export const counterModule = createModule("counter", {
+  schema: counterSchema,
+
+  init: (facts) => {
+    facts.count = 0;
+    facts.step = 1;
+  },
+
+  derive: {
+    isNearMax: (facts) => (facts.count as number) >= 90,
+  },
+
+  events: {
+    increment: (facts) => {
+      facts.count = (facts.count as number) + (facts.step as number);
+    },
+    decrement: (facts) => {
+      facts.count = Math.max(
+        0,
+        (facts.count as number) - (facts.step as number),
+      );
+    },
+    setStep: (facts, { value }) => {
+      facts.step = value;
+    },
+  },
+
+  constraints: {
+    overflow: {
+      priority: 100,
+      when: (facts) => (facts.count as number) >= 100,
+      require: () => ({ type: "COUNTER_RESET" }),
+    },
+  },
+
+  resolvers: {
+    counterReset: {
+      requirement: "COUNTER_RESET",
+      resolve: async (_req, context) => {
+        context.facts.count = 0;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Weather Module (dynamic)
+// ============================================================================
+
+export const weatherSchema = {
+  facts: {
+    city: t.string(),
+    temperature: t.number(),
+    condition: t.string(),
+    humidity: t.number(),
+    isLoading: t.boolean(),
+    lastFetchedCity: t.string(),
+  },
+  derivations: {
+    summary: t.string(),
+    hasFetched: t.boolean(),
+  },
+  events: {
+    setCity: { value: t.string() },
+    refresh: {},
+  },
+  requirements: {
+    FETCH_WEATHER: {
+      city: t.string(),
+    },
+  },
+} satisfies ModuleSchema;
+
+export const weatherModule = createModule("weather", {
+  schema: weatherSchema,
+
+  init: (facts) => {
+    facts.city = "";
+    facts.temperature = 0;
+    facts.condition = "";
+    facts.humidity = 0;
+    facts.isLoading = false;
+    facts.lastFetchedCity = "";
+  },
+
+  derive: {
+    summary: (facts) => {
+      if ((facts.city as string) === "") {
+        return "";
+      }
+
+      return `${facts.temperature}\u00B0F, ${facts.condition}`;
+    },
+    hasFetched: (facts) => (facts.lastFetchedCity as string) !== "",
+  },
+
+  events: {
+    setCity: (facts, { value }) => {
+      facts.city = value;
+    },
+    refresh: (facts) => {
+      facts.lastFetchedCity = "";
+    },
+  },
+
+  constraints: {
+    needsFetch: {
+      priority: 100,
+      when: (facts) =>
+        (facts.city as string).length >= 2 &&
+        facts.city !== facts.lastFetchedCity &&
+        !(facts.isLoading as boolean),
+      require: (facts) => ({
+        type: "FETCH_WEATHER",
+        city: facts.city as string,
+      }),
+    },
+  },
+
+  resolvers: {
+    fetchWeather: {
+      requirement: "FETCH_WEATHER",
+      key: (req) => `weather-${req.city}`,
+      timeout: 10000,
+      resolve: async (req, context) => {
+        context.facts.isLoading = true;
+
+        const data = await mockFetchWeather(req.city, 800);
+
+        // Stale check: only apply if city still matches
+        if ((context.facts.city as string) === req.city) {
+          context.facts.temperature = data.temperature;
+          context.facts.condition = data.condition;
+          context.facts.humidity = data.humidity;
+          context.facts.lastFetchedCity = req.city;
+        }
+
+        context.facts.isLoading = false;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Dice Module (dynamic)
+// ============================================================================
+
+export const diceSchema = {
+  facts: {
+    die1: t.number(),
+    die2: t.number(),
+    rollCount: t.number(),
+  },
+  derivations: {
+    total: t.number(),
+    isDoubles: t.boolean(),
+  },
+  events: {
+    roll: {},
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+export const diceModule = createModule("dice", {
+  schema: diceSchema,
+
+  init: (facts) => {
+    facts.die1 = 1;
+    facts.die2 = 1;
+    facts.rollCount = 0;
+  },
+
+  derive: {
+    total: (facts) => (facts.die1 as number) + (facts.die2 as number),
+    isDoubles: (facts) => facts.die1 === facts.die2,
+  },
+
+  events: {
+    roll: (facts) => {
+      facts.die1 = Math.floor(Math.random() * 6) + 1;
+      facts.die2 = Math.floor(Math.random() * 6) + 1;
+      facts.rollCount = (facts.rollCount as number) + 1;
+    },
+  },
+});
+
+// ============================================================================
+// Module Registry
+// ============================================================================
+
+export const moduleRegistry: Record<string, { module: any; label: string }> = {
+  counter: { module: counterModule, label: "Counter" },
+  weather: { module: weatherModule, label: "Weather" },
+  dice: { module: diceModule, label: "Dice" },
+};

package/examples/error-boundaries.ts

@@ -0,0 +1,430 @@
+// Example: error-boundaries
+// Source: examples/error-boundaries/src/main.ts
+// Extracted for AI rules — DOM wiring stripped
+
+/**
+ * Resilient API Dashboard — Error Boundaries, Retry, Circuit Breaker, Performance
+ *
+ * 3 simulated API services with configurable failure rates. Users inject errors
+ * and watch recovery strategies, circuit breaker state transitions, retry-later
+ * backoff, and performance metrics.
+ */
+
+import {
+  type ModuleSchema,
+  type RecoveryStrategy,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin, performancePlugin } from "@directive-run/core/plugins";
+import {
+  type CircuitState,
+  createCircuitBreaker,
+} from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface ServiceState {
+  name: string;
+  status: "idle" | "loading" | "success" | "error";
+  lastResult: string;
+  errorCount: number;
+  successCount: number;
+  lastError: string;
+}
+
+interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type: "info" | "error" | "retry" | "circuit" | "recovery" | "success";
+}
+
+// ============================================================================
+// Circuit Breakers (one per service)
+// ============================================================================
+
+const timeline: TimelineEntry[] = [];
+
+function addTimeline(
+  event: string,
+  detail: string,
+  type: TimelineEntry["type"],
+) {
+  timeline.unshift({ time: Date.now(), event, detail, type });
+  if (timeline.length > 50) {
+    timeline.length = 50;
+  }
+}
+
+const circuitBreakers = {
+  users: createCircuitBreaker({
+    name: "users-api",
+    failureThreshold: 3,
+    recoveryTimeMs: 5000,
+    halfOpenMaxRequests: 2,
+    onStateChange: (from, to) => {
+    },
+  }),
+  orders: createCircuitBreaker({
+    name: "orders-api",
+    failureThreshold: 3,
+    recoveryTimeMs: 5000,
+    halfOpenMaxRequests: 2,
+    onStateChange: (from, to) => {
+    },
+  }),
+  analytics: createCircuitBreaker({
+    name: "analytics-api",
+    failureThreshold: 3,
+    recoveryTimeMs: 5000,
+    halfOpenMaxRequests: 2,
+    onStateChange: (from, to) => {
+    },
+  }),
+};
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+const schema = {
+  facts: {
+    usersService: t.object<ServiceState>(),
+    ordersService: t.object<ServiceState>(),
+    analyticsService: t.object<ServiceState>(),
+    strategy: t.string<RecoveryStrategy>(),
+    usersFailRate: t.number(),
+    ordersFailRate: t.number(),
+    analyticsFailRate: t.number(),
+    retryQueueCount: t.number(),
+    totalErrors: t.number(),
+    totalRecoveries: t.number(),
+  },
+  derivations: {
+    usersCircuitState: t.string<CircuitState>(),
+    ordersCircuitState: t.string<CircuitState>(),
+    analyticsCircuitState: t.string<CircuitState>(),
+    errorRate: t.number(),
+    allServicesHealthy: t.boolean(),
+  },
+  events: {
+    fetchUsers: {},
+    fetchOrders: {},
+    fetchAnalytics: {},
+    fetchAll: {},
+    setStrategy: { value: t.string<RecoveryStrategy>() },
+    setUsersFailRate: { value: t.number() },
+    setOrdersFailRate: { value: t.number() },
+    setAnalyticsFailRate: { value: t.number() },
+    resetAll: {},
+  },
+  requirements: {
+    FETCH_SERVICE: { service: t.string(), failRate: t.number() },
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+const dashboardModule = createModule("dashboard", {
+  schema,
+
+  init: (facts) => {
+    const defaultService: ServiceState = {
+      name: "",
+      status: "idle",
+      lastResult: "",
+      errorCount: 0,
+      successCount: 0,
+      lastError: "",
+    };
+    facts.usersService = { ...defaultService, name: "Users API" };
+    facts.ordersService = { ...defaultService, name: "Orders API" };
+    facts.analyticsService = { ...defaultService, name: "Analytics API" };
+    facts.strategy = "retry-later";
+    facts.usersFailRate = 0;
+    facts.ordersFailRate = 0;
+    facts.analyticsFailRate = 0;
+    facts.retryQueueCount = 0;
+    facts.totalErrors = 0;
+    facts.totalRecoveries = 0;
+  },
+
+  derive: {
+    usersCircuitState: () => circuitBreakers.users.getState(),
+    ordersCircuitState: () => circuitBreakers.orders.getState(),
+    analyticsCircuitState: () => circuitBreakers.analytics.getState(),
+    errorRate: (facts) => {
+      const total =
+        facts.usersService.errorCount +
+        facts.usersService.successCount +
+        facts.ordersService.errorCount +
+        facts.ordersService.successCount +
+        facts.analyticsService.errorCount +
+        facts.analyticsService.successCount;
+
+      if (total === 0) {
+        return 0;
+      }
+
+      const errors =
+        facts.usersService.errorCount +
+        facts.ordersService.errorCount +
+        facts.analyticsService.errorCount;
+
+      return Math.round((errors / total) * 100);
+    },
+    allServicesHealthy: (facts) =>
+      facts.usersService.status !== "error" &&
+      facts.ordersService.status !== "error" &&
+      facts.analyticsService.status !== "error",
+  },
+
+  events: {
+    fetchUsers: (facts) => {
+      facts.usersService = { ...facts.usersService, status: "loading" };
+    },
+    fetchOrders: (facts) => {
+      facts.ordersService = { ...facts.ordersService, status: "loading" };
+    },
+    fetchAnalytics: (facts) => {
+      facts.analyticsService = { ...facts.analyticsService, status: "loading" };
+    },
+    fetchAll: (facts) => {
+      facts.usersService = { ...facts.usersService, status: "loading" };
+      facts.ordersService = { ...facts.ordersService, status: "loading" };
+      facts.analyticsService = { ...facts.analyticsService, status: "loading" };
+    },
+    setStrategy: (facts, { value }) => {
+      facts.strategy = value;
+    },
+    setUsersFailRate: (facts, { value }) => {
+      facts.usersFailRate = value;
+    },
+    setOrdersFailRate: (facts, { value }) => {
+      facts.ordersFailRate = value;
+    },
+    setAnalyticsFailRate: (facts, { value }) => {
+      facts.analyticsFailRate = value;
+    },
+    resetAll: (facts) => {
+      const defaultService: ServiceState = {
+        name: "",
+        status: "idle",
+        lastResult: "",
+        errorCount: 0,
+        successCount: 0,
+        lastError: "",
+      };
+      facts.usersService = { ...defaultService, name: "Users API" };
+      facts.ordersService = { ...defaultService, name: "Orders API" };
+      facts.analyticsService = { ...defaultService, name: "Analytics API" };
+      facts.retryQueueCount = 0;
+      facts.totalErrors = 0;
+      facts.totalRecoveries = 0;
+      circuitBreakers.users.reset();
+      circuitBreakers.orders.reset();
+      circuitBreakers.analytics.reset();
+      timeline.length = 0;
+    },
+  },
+
+  constraints: {
+    usersNeedsLoad: {
+      priority: 50,
+      when: (facts) => facts.usersService.status === "loading",
+      require: (facts) => ({
+        type: "FETCH_SERVICE",
+        service: "users",
+        failRate: facts.usersFailRate,
+      }),
+    },
+    ordersNeedsLoad: {
+      priority: 50,
+      when: (facts) => facts.ordersService.status === "loading",
+      require: (facts) => ({
+        type: "FETCH_SERVICE",
+        service: "orders",
+        failRate: facts.ordersFailRate,
+      }),
+    },
+    analyticsNeedsLoad: {
+      priority: 50,
+      when: (facts) => facts.analyticsService.status === "loading",
+      require: (facts) => ({
+        type: "FETCH_SERVICE",
+        service: "analytics",
+        failRate: facts.analyticsFailRate,
+      }),
+    },
+  },
+
+  resolvers: {
+    fetchService: {
+      requirement: "FETCH_SERVICE",
+      retry: { attempts: 2, backoff: "exponential", initialDelay: 200 },
+      resolve: async (req, context) => {
+        const { service, failRate } = req;
+        const breaker =
+          circuitBreakers[service as keyof typeof circuitBreakers];
+        const serviceKey = `${service}Service` as
+          | "usersService"
+          | "ordersService"
+          | "analyticsService";
+
+        try {
+          await breaker.execute(async () => {
+            // Simulate API call
+            await new Promise((resolve) =>
+              setTimeout(resolve, 200 + Math.random() * 300),
+            );
+
+            if (Math.random() * 100 < failRate) {
+              throw new Error(`${service} API: simulated failure`);
+            }
+          });
+
+          // Success
+          const current = context.facts[serviceKey] as ServiceState;
+          context.facts[serviceKey] = {
+            ...current,
+            status: "success",
+            lastResult: `Loaded at ${new Date().toLocaleTimeString()}`,
+            successCount: current.successCount + 1,
+          };
+        } catch (error) {
+          const current = context.facts[serviceKey] as ServiceState;
+          const msg = error instanceof Error ? error.message : String(error);
+          context.facts[serviceKey] = {
+            ...current,
+            status: "error",
+            lastError: msg,
+            errorCount: current.errorCount + 1,
+          };
+          context.facts.totalErrors = context.facts.totalErrors + 1;
+
+          // Re-throw so the error boundary handles recovery
+          throw error;
+        }
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Performance Plugin
+// ============================================================================
+
+const perf = performancePlugin({
+  onSlowResolver: (id, ms) => {
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+let currentStrategy: RecoveryStrategy = "retry-later";
+
+const system = createSystem({
+  module: dashboardModule,
+  debug: { runHistory: true },
+  plugins: [perf, devtoolsPlugin({ name: "error-boundaries" })],
+  errorBoundary: {
+    onResolverError: (_error, resolver) => {
+        "recovery",
+        `${resolver}: strategy=${currentStrategy}`,
+        "recovery",
+      );
+
+      return currentStrategy;
+    },
+    onConstraintError: "skip",
+    onEffectError: "skip",
+    retryLater: {
+      delayMs: 1000,
+      maxRetries: 3,
+      backoffMultiplier: 2,
+    },
+    onError: (error) => {
+    },
+  },
+});
+system.start();
+
+// Track strategy changes to update error boundary (via re-dispatch)
+system.subscribe(["strategy"], () => {
+  const newStrategy = system.facts.strategy as RecoveryStrategy;
+  if (newStrategy !== currentStrategy) {
+    currentStrategy = newStrategy;
+  }
+});
+
+// ============================================================================
+// DOM References
+// ============================================================================
+
+// Service cards
+
+// Sliders
+  "eb-users-failrate",
+  "eb-orders-failrate",
+  "eb-analytics-failrate",
+
+// Strategy dropdown
+  "eb-strategy",
+
+// Timeline
+
+// ============================================================================
+// Render
+// ============================================================================
+
+function escapeHtml(text: string): string {
+
+  return div.innerHTML;
+}
+
+  service: ServiceState,
+): void {
+  if (service.lastError) {
+  } else {
+  }
+}
+
+
+// ============================================================================
+// Subscribe
+// ============================================================================
+
+const allKeys = [
+  ...Object.keys(schema.facts),
+  ...Object.keys(schema.derivations),
+];
+system.subscribe(allKeys, render);
+
+// Periodic refresh for circuit breaker state transitions + retry queue
+setInterval(() => {
+  render();
+}, 1000);
+
+// ============================================================================
+// Controls
+// ============================================================================
+
+// Fetch buttons
+
+// Strategy selector
+
+// Sliders
+
+// ============================================================================
+// Initial Render
+// ============================================================================
+
+render();