@directive-run/knowledge 0.2.0

package/examples/async-chains.ts

@@ -0,0 +1,287 @@
+// Example: async-chains
+// Source: examples/async-chains/src/async-chains.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Async Chains — Three Directive Modules
+ *
+ * Demonstrates cross-module constraint chaining with `after` ordering:
+ *   Auth → Permissions → Dashboard
+ *
+ * Each step only fires after the previous step's resolver completes.
+ * Cross-module derivations drive the `when()` conditions.
+ */
+
+import { type ModuleSchema, createModule, t } from "@directive-run/core";
+import {
+  type DashboardWidget,
+  fetchDashboard,
+  fetchPermissions,
+  validateSession,
+} from "./mock-api.js";
+
+// ============================================================================
+// Auth Module
+// ============================================================================
+
+export const authSchema = {
+  facts: {
+    token: t.string(),
+    status: t.string<"idle" | "validating" | "valid" | "expired">(),
+    userId: t.string(),
+    failRate: t.number(),
+  },
+  derivations: {
+    isValid: t.boolean(),
+  },
+  events: {
+    setToken: { value: t.string() },
+    setFailRate: { value: t.number() },
+    reset: {},
+  },
+  requirements: {
+    VALIDATE_SESSION: { token: t.string() },
+  },
+} satisfies ModuleSchema;
+
+export const authModule = createModule("auth", {
+  schema: authSchema,
+
+  init: (facts) => {
+    facts.token = "";
+    facts.status = "idle";
+    facts.userId = "";
+    facts.failRate = 0;
+  },
+
+  derive: {
+    isValid: (facts) => facts.status === "valid",
+  },
+
+  events: {
+    setToken: (facts, { value }) => {
+      facts.token = value;
+      facts.status = "idle";
+      facts.userId = "";
+    },
+    setFailRate: (facts, { value }) => {
+      facts.failRate = value;
+    },
+    reset: (facts) => {
+      facts.token = "";
+      facts.status = "idle";
+      facts.userId = "";
+    },
+  },
+
+  constraints: {
+    validateSession: {
+      when: (facts) => facts.token !== "" && facts.status === "idle",
+      require: (facts) => ({
+        type: "VALIDATE_SESSION",
+        token: facts.token,
+      }),
+    },
+  },
+
+  resolvers: {
+    validateSession: {
+      requirement: "VALIDATE_SESSION",
+      key: (req) => `validate-${req.token}`,
+      retry: {
+        attempts: 2,
+        backoff: "exponential",
+        initialDelay: 300,
+      },
+      resolve: async (req, context) => {
+        context.facts.status = "validating";
+
+        try {
+          const result = await validateSession(
+            req.token,
+            context.facts.failRate,
+          );
+          if (result.valid) {
+            context.facts.status = "valid";
+            context.facts.userId = result.userId;
+          } else {
+            context.facts.status = "expired";
+          }
+        } catch {
+          context.facts.status = "expired";
+        }
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Permissions Module
+// ============================================================================
+
+export const permissionsSchema = {
+  facts: {
+    role: t.string(),
+    permissions: t.array<string>(),
+    loaded: t.boolean(),
+    failRate: t.number(),
+  },
+  derivations: {
+    canEdit: t.boolean(),
+    canPublish: t.boolean(),
+    canManageUsers: t.boolean(),
+  },
+  events: {
+    setFailRate: { value: t.number() },
+    reset: {},
+  },
+  requirements: {
+    LOAD_PERMISSIONS: {},
+  },
+} satisfies ModuleSchema;
+
+export const permissionsModule = createModule("permissions", {
+  schema: permissionsSchema,
+
+  crossModuleDeps: { auth: authSchema },
+
+  init: (facts) => {
+    facts.role = "";
+    facts.permissions = [];
+    facts.loaded = false;
+    facts.failRate = 0;
+  },
+
+  derive: {
+    canEdit: (facts) => facts.self.permissions.includes("write"),
+    canPublish: (facts) =>
+      facts.self.permissions.includes("write") && facts.self.role !== "viewer",
+    canManageUsers: (facts) => facts.self.permissions.includes("manage-users"),
+  },
+
+  events: {
+    setFailRate: (facts, { value }) => {
+      facts.failRate = value;
+    },
+    reset: (facts) => {
+      facts.role = "";
+      facts.permissions = [];
+      facts.loaded = false;
+    },
+  },
+
+  constraints: {
+    loadPermissions: {
+      after: ["auth::validateSession"],
+      when: (facts) => {
+        // Use the fact directly — derivation values aren't available in the
+        // facts proxy passed to constraints (they live in the derive layer).
+        return facts.auth.status === "valid" && !facts.self.loaded;
+      },
+      require: { type: "LOAD_PERMISSIONS" },
+    },
+  },
+
+  resolvers: {
+    loadPermissions: {
+      requirement: "LOAD_PERMISSIONS",
+      retry: {
+        attempts: 2,
+        backoff: "exponential",
+        initialDelay: 200,
+      },
+      resolve: async (_req, context) => {
+        try {
+          const result = await fetchPermissions(context.facts.failRate);
+          context.facts.role = result.role;
+          context.facts.permissions = result.permissions;
+          context.facts.loaded = true;
+        } catch {
+          context.facts.loaded = false;
+        }
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Dashboard Module
+// ============================================================================
+
+export const dashboardSchema = {
+  facts: {
+    widgets: t.array<DashboardWidget>(),
+    loaded: t.boolean(),
+    failRate: t.number(),
+  },
+  derivations: {
+    widgetCount: t.number(),
+  },
+  events: {
+    setFailRate: { value: t.number() },
+    reset: {},
+  },
+  requirements: {
+    LOAD_DASHBOARD: { role: t.string() },
+  },
+} satisfies ModuleSchema;
+
+export const dashboardModule = createModule("dashboard", {
+  schema: dashboardSchema,
+
+  crossModuleDeps: { permissions: permissionsSchema },
+
+  init: (facts) => {
+    facts.widgets = [];
+    facts.loaded = false;
+    facts.failRate = 0;
+  },
+
+  derive: {
+    widgetCount: (facts) => facts.self.widgets.length,
+  },
+
+  events: {
+    setFailRate: (facts, { value }) => {
+      facts.failRate = value;
+    },
+    reset: (facts) => {
+      facts.widgets = [];
+      facts.loaded = false;
+    },
+  },
+
+  constraints: {
+    loadDashboard: {
+      after: ["permissions::loadPermissions"],
+      when: (facts) => {
+        return facts.permissions.role !== "" && !facts.self.loaded;
+      },
+      require: (facts) => ({
+        type: "LOAD_DASHBOARD",
+        role: facts.permissions.role,
+      }),
+    },
+  },
+
+  resolvers: {
+    loadDashboard: {
+      requirement: "LOAD_DASHBOARD",
+      key: (req) => `dashboard-${req.role}`,
+      retry: {
+        attempts: 2,
+        backoff: "exponential",
+        initialDelay: 300,
+      },
+      resolve: async (req, context) => {
+        try {
+          const result = await fetchDashboard(req.role, context.facts.failRate);
+          context.facts.widgets = result.widgets;
+          context.facts.loaded = true;
+        } catch {
+          context.facts.loaded = false;
+        }
+      },
+    },
+  },
+});

package/examples/auth-flow.ts

@@ -0,0 +1,371 @@
+// Example: auth-flow
+// Source: examples/auth-flow/src/auth-flow.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Auth Flow — Directive Module
+ *
+ * Demonstrates constraint `after` ordering, auto-tracked derivations
+ * driving constraints, resolvers with retry, effects for cleanup,
+ * and time-based reactivity (token expiry countdown).
+ */
+
+import { type ModuleSchema, createModule, t } from "@directive-run/core";
+import {
+  type User,
+  mockFetchUser,
+  mockLogin,
+  mockRefresh,
+} from "./mock-auth.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type AuthStatus =
+  | "idle"
+  | "authenticating"
+  | "authenticated"
+  | "refreshing"
+  | "expired";
+
+export interface EventLogEntry {
+  timestamp: number;
+  event: string;
+  detail: string;
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const authFlowSchema = {
+  facts: {
+    email: t.string(),
+    password: t.string(),
+    token: t.string(),
+    refreshToken: t.string(),
+    expiresAt: t.number(),
+    user: t.object<User | null>(),
+    status: t.string<AuthStatus>(),
+    loginRequested: t.boolean(),
+    now: t.number(),
+    tokenTTL: t.number(),
+    refreshBuffer: t.number(),
+    loginFailRate: t.number(),
+    refreshFailRate: t.number(),
+    eventLog: t.object<EventLogEntry[]>(),
+  },
+  derivations: {
+    isAuthenticated: t.boolean(),
+    isExpiringSoon: t.boolean(),
+    canRefresh: t.boolean(),
+    tokenTimeRemaining: t.number(),
+    canLogin: t.boolean(),
+  },
+  events: {
+    setEmail: { value: t.string() },
+    setPassword: { value: t.string() },
+    requestLogin: {},
+    logout: {},
+    forceExpire: {},
+    setTokenTTL: { value: t.number() },
+    setRefreshBuffer: { value: t.number() },
+    setLoginFailRate: { value: t.number() },
+    setRefreshFailRate: { value: t.number() },
+    tick: {},
+  },
+  requirements: {
+    LOGIN: { email: t.string(), password: t.string() },
+    REFRESH_TOKEN: { refreshToken: t.string() },
+    FETCH_USER: { token: t.string() },
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function addLogEntry(facts: any, event: string, detail: string): void {
+  const log = [...(facts.eventLog as EventLogEntry[])];
+  log.push({ timestamp: Date.now(), event, detail });
+  facts.eventLog = log;
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export const authFlowModule = createModule("auth-flow", {
+  schema: authFlowSchema,
+
+  init: (facts) => {
+    facts.email = "alice@test.com";
+    facts.password = "password";
+    facts.token = "";
+    facts.refreshToken = "";
+    facts.expiresAt = 0;
+    facts.user = null;
+    facts.status = "idle";
+    facts.loginRequested = false;
+    facts.now = Date.now();
+    facts.tokenTTL = 30;
+    facts.refreshBuffer = 5;
+    facts.loginFailRate = 0;
+    facts.refreshFailRate = 0;
+    facts.eventLog = [];
+  },
+
+  // ============================================================================
+  // Derivations
+  // ============================================================================
+
+  derive: {
+    isAuthenticated: (facts) => facts.status === "authenticated",
+
+    isExpiringSoon: (facts) => {
+      if (facts.token === "") {
+        return false;
+      }
+
+      return facts.now > facts.expiresAt - facts.refreshBuffer * 1000;
+    },
+
+    canRefresh: (facts) => {
+      return facts.refreshToken !== "" && facts.status !== "refreshing";
+    },
+
+    tokenTimeRemaining: (facts) => {
+      if (facts.token === "") {
+        return 0;
+      }
+
+      return Math.max(0, Math.round((facts.expiresAt - facts.now) / 1000));
+    },
+
+    canLogin: (facts) => {
+      return (
+        facts.email.trim() !== "" &&
+        facts.password.trim() !== "" &&
+        (facts.status === "idle" || facts.status === "expired")
+      );
+    },
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    setEmail: (facts, { value }) => {
+      facts.email = value;
+    },
+
+    setPassword: (facts, { value }) => {
+      facts.password = value;
+    },
+
+    requestLogin: (facts) => {
+      facts.loginRequested = true;
+      facts.status = "authenticating";
+      facts.token = "";
+      facts.refreshToken = "";
+      facts.expiresAt = 0;
+      facts.user = null;
+      facts.eventLog = [];
+    },
+
+    logout: (facts) => {
+      facts.token = "";
+      facts.refreshToken = "";
+      facts.expiresAt = 0;
+      facts.user = null;
+      facts.status = "idle";
+      facts.loginRequested = false;
+    },
+
+    forceExpire: (facts) => {
+      facts.expiresAt = 0;
+    },
+
+    setTokenTTL: (facts, { value }) => {
+      facts.tokenTTL = value;
+    },
+
+    setRefreshBuffer: (facts, { value }) => {
+      facts.refreshBuffer = value;
+    },
+
+    setLoginFailRate: (facts, { value }) => {
+      facts.loginFailRate = value;
+    },
+
+    setRefreshFailRate: (facts, { value }) => {
+      facts.refreshFailRate = value;
+    },
+
+    tick: (facts) => {
+      facts.now = Date.now();
+    },
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+
+  constraints: {
+    needsLogin: {
+      priority: 100,
+      when: (facts) => {
+        return facts.loginRequested && facts.status === "authenticating";
+      },
+      require: (facts) => ({
+        type: "LOGIN",
+        email: facts.email,
+        password: facts.password,
+      }),
+    },
+
+    refreshNeeded: {
+      priority: 90,
+      when: (facts) => {
+        const isExpiringSoon =
+          facts.token !== "" &&
+          facts.now > facts.expiresAt - facts.refreshBuffer * 1000;
+        const canRefresh =
+          facts.refreshToken !== "" && facts.status !== "refreshing";
+
+        return isExpiringSoon && canRefresh && facts.status === "authenticated";
+      },
+      require: (facts) => ({
+        type: "REFRESH_TOKEN",
+        refreshToken: facts.refreshToken,
+      }),
+    },
+
+    needsUser: {
+      priority: 80,
+      after: ["refreshNeeded"],
+      when: (facts) => {
+        return (
+          facts.token !== "" &&
+          facts.user === null &&
+          facts.status !== "authenticating"
+        );
+      },
+      require: (facts) => ({
+        type: "FETCH_USER",
+        token: facts.token,
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+
+  resolvers: {
+    login: {
+      requirement: "LOGIN",
+      timeout: 10000,
+      resolve: async (req, context) => {
+        addLogEntry(context.facts, "login", "Authenticating...");
+
+        try {
+          const tokens = await mockLogin(
+            req.email,
+            req.password,
+            context.facts.loginFailRate,
+            context.facts.tokenTTL,
+          );
+          context.facts.token = tokens.token;
+          context.facts.refreshToken = tokens.refreshToken;
+          context.facts.expiresAt = Date.now() + tokens.expiresIn * 1000;
+          context.facts.status = "authenticated";
+          context.facts.user = null; // trigger needsUser constraint
+          addLogEntry(
+            context.facts,
+            "login-success",
+            `Token: ${tokens.token.slice(0, 12)}...`,
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : "Unknown error";
+          context.facts.status = "idle";
+          context.facts.loginRequested = false;
+          addLogEntry(context.facts, "login-error", msg);
+          throw err;
+        }
+      },
+    },
+
+    refreshToken: {
+      requirement: "REFRESH_TOKEN",
+      retry: { attempts: 2, backoff: "exponential" },
+      timeout: 10000,
+      resolve: async (req, context) => {
+        context.facts.status = "refreshing";
+        addLogEntry(context.facts, "refresh", "Refreshing token...");
+
+        try {
+          const tokens = await mockRefresh(
+            req.refreshToken,
+            context.facts.refreshFailRate,
+            context.facts.tokenTTL,
+          );
+          context.facts.token = tokens.token;
+          context.facts.refreshToken = tokens.refreshToken;
+          context.facts.expiresAt = Date.now() + tokens.expiresIn * 1000;
+          context.facts.status = "authenticated";
+          addLogEntry(
+            context.facts,
+            "refresh-success",
+            `New token: ${tokens.token.slice(0, 12)}...`,
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : "Unknown error";
+          context.facts.token = "";
+          context.facts.refreshToken = "";
+          context.facts.expiresAt = 0;
+          context.facts.status = "expired";
+          addLogEntry(context.facts, "refresh-error", msg);
+          throw err;
+        }
+      },
+    },
+
+    fetchUser: {
+      requirement: "FETCH_USER",
+      resolve: async (req, context) => {
+        addLogEntry(context.facts, "fetch-user", "Fetching user profile...");
+
+        try {
+          const user = await mockFetchUser(req.token);
+          context.facts.user = user;
+          addLogEntry(
+            context.facts,
+            "fetch-user-success",
+            `${user.name} (${user.role})`,
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : "Unknown error";
+          addLogEntry(context.facts, "fetch-user-error", msg);
+        }
+      },
+    },
+  },
+
+  // ============================================================================
+  // Effects
+  // ============================================================================
+
+  effects: {
+    logStatusChange: {
+      deps: ["status"],
+      run: (facts, prev) => {
+        if (prev && prev.status !== facts.status) {
+          addLogEntry(facts, "status", `${prev.status} → ${facts.status}`);
+        }
+      },
+    },
+  },
+});