@directive-run/knowledge 0.2.0 → 0.4.2

package/examples/newsletter.ts

@@ -1,9 +1,9 @@
 // Example: newsletter
-// Source: examples/newsletter/src/main.ts
-// Extracted for AI rules — DOM wiring stripped
+// Source: examples/newsletter/src/module.ts
+// Pure module file — no DOM wiring
 
 /**
- * Newsletter Signup - Vanilla Directive Example
+ * Newsletter Signup — Directive Module
  *
  * Demonstrates all six primitives with the simplest possible module:
  * - Facts: email, touched, status, errorMessage, lastSubmittedAt
@@ -31,11 +31,22 @@ import { devtoolsPlugin } from "@directive-run/core/plugins";
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const RATE_LIMIT_MS = 10_000; // 10 seconds (shorter for demo)
 
+// ============================================================================
+// Logs (external mutable array, same pattern as fraud-analysis)
+// ============================================================================
+
+export const logs: string[] = [];
+
+export function addLog(msg: string): void {
+  console.log(`[newsletter] ${msg}`);
+  logs.push(`${new Date().toLocaleTimeString()}: ${msg}`);
+}
+
 // ============================================================================
 // Schema
 // ============================================================================
 
-const schema = {
+export const schema = {
   facts: {
     email: t.string(),
     touched: t.boolean(),
@@ -141,7 +152,7 @@ const newsletter = createModule("newsletter", {
     subscribe: {
       requirement: "SUBSCRIBE",
       resolve: async (req, context) => {
-        log(`Subscribing: ${context.facts.email}`);
+        addLog(`Subscribing: ${context.facts.email}`);
 
         // Simulate network delay
         await new Promise((resolve) => setTimeout(resolve, 1500));
@@ -151,27 +162,27 @@ const newsletter = createModule("newsletter", {
           context.facts.status = "error";
           context.facts.errorMessage =
             "Simulated error — try again (20% failure rate for demo).";
-          log("Subscription failed (simulated)");
+          addLog("Subscription failed (simulated)");
 
           return;
         }
 
         context.facts.status = "success";
         context.facts.lastSubmittedAt = Date.now();
-        log("Subscription succeeded");
+        addLog("Subscription succeeded");
       },
     },
 
     resetAfterDelay: {
       requirement: "RESET_AFTER_DELAY",
       resolve: async (req, context) => {
-        log("Auto-resetting in 5 seconds...");
+        addLog("Auto-resetting in 5 seconds...");
         await new Promise((resolve) => setTimeout(resolve, 5000));
         context.facts.email = "";
         context.facts.touched = false;
         context.facts.status = "idle";
         context.facts.errorMessage = "";
-        log("Form reset");
+        addLog("Form reset");
       },
     },
   },
@@ -185,7 +196,7 @@ const newsletter = createModule("newsletter", {
         }
 
         if (facts.status !== prev.status) {
-          log(`Status: ${prev.status} → ${facts.status}`);
+          addLog(`Status: ${prev.status} → ${facts.status}`);
         }
       },
     },
@@ -196,46 +207,8 @@ const newsletter = createModule("newsletter", {
 // System
 // ============================================================================
 
-const system = createSystem({
+export const system = createSystem({
   module: newsletter,
   debug: { runHistory: true },
   plugins: [devtoolsPlugin({ name: "newsletter" })],
 });
-system.start();
-
-// ============================================================================
-// Logging helper
-// ============================================================================
-
-function log(msg: string) {
-  console.log(`[newsletter] ${msg}`);
-}
-
-// ============================================================================
-// DOM Bindings
-// ============================================================================
-
-
-// ============================================================================
-// Render
-// ============================================================================
-
-
-// Subscribe to all relevant facts and derivations
-system.subscribe(
-  [
-    "email",
-    "touched",
-    "status",
-    "errorMessage",
-    "lastSubmittedAt",
-    "emailError",
-    "isValid",
-    "canSubmit",
-  ],
-  render,
-);
-
-// Initial render
-render();
-log("Newsletter signup ready. Enter an email and subscribe.");

package/examples/notifications.ts

@@ -30,13 +30,13 @@ export interface Notification {
 
 export const notificationsSchema = {
   facts: {
-    queue: t.object<Notification[]>(),
+    queue: t.array<Notification>(),
     maxVisible: t.number(),
     now: t.number(),
     idCounter: t.number(),
   },
   derivations: {
-    visibleNotifications: t.object<Notification[]>(),
+    visibleNotifications: t.array<Notification>(),
     hasNotifications: t.boolean(),
     oldestExpired: t.object<Notification | null>(),
   },
@@ -71,24 +71,20 @@ export const notificationsModule = createModule("notifications", {
 
   derive: {
     visibleNotifications: (facts) => {
-      return (facts.queue as Notification[]).slice(
-        0,
-        facts.maxVisible as number,
-      );
+      return facts.queue.slice(0, facts.maxVisible);
     },
 
     hasNotifications: (facts) => {
-      return (facts.queue as Notification[]).length > 0;
+      return facts.queue.length > 0;
     },
 
     oldestExpired: (facts) => {
-      const queue = facts.queue as Notification[];
-      const oldest = queue[0];
+      const oldest = facts.queue[0];
       if (!oldest) {
         return null;
       }
 
-      if ((facts.now as number) > oldest.createdAt + oldest.ttl) {
+      if (facts.now > oldest.createdAt + oldest.ttl) {
         return oldest;
       }
 
@@ -103,23 +99,28 @@ export const notificationsModule = createModule("notifications", {
   constraints: {
     autoDismiss: {
       priority: 50,
-      when: (_facts, derive) => derive.oldestExpired !== null,
-      require: (_facts, derive) => ({
+      when: (facts) => {
+        const oldest = facts.queue[0];
+        if (!oldest) {
+          return false;
+        }
+
+        return facts.now > oldest.createdAt + oldest.ttl;
+      },
+      require: (facts) => ({
         type: "DISMISS_NOTIFICATION" as const,
-        id: (derive.oldestExpired as Notification).id,
+        id: facts.queue[0].id,
       }),
     },
 
     overflow: {
       priority: 60,
       when: (facts) => {
-        const queue = facts.queue as Notification[];
-
-        return queue.length > (facts.maxVisible as number) + 5;
+        return facts.queue.length > facts.maxVisible + 5;
       },
       require: (facts) => ({
         type: "DISMISS_NOTIFICATION" as const,
-        id: (facts.queue as Notification[])[0].id,
+        id: facts.queue[0].id,
       }),
     },
   },
@@ -132,7 +133,7 @@ export const notificationsModule = createModule("notifications", {
     dismiss: {
       requirement: "DISMISS_NOTIFICATION",
       resolve: async (req, context) => {
-        context.facts.queue = (context.facts.queue as Notification[]).filter(
+        context.facts.queue = context.facts.queue.filter(
           (n) => n.id !== req.id,
         );
       },
@@ -154,7 +155,7 @@ export const notificationsModule = createModule("notifications", {
         warning: 6000,
         error: 10000,
       };
-      const counter = (facts.idCounter as number) + 1;
+      const counter = facts.idCounter + 1;
       facts.idCounter = counter;
 
       const notification: Notification = {
@@ -165,11 +166,11 @@ export const notificationsModule = createModule("notifications", {
         ttl: payload.ttl ?? ttlMap[payload.level] ?? 4000,
       };
 
-      facts.queue = [...(facts.queue as Notification[]), notification];
+      facts.queue = [...facts.queue, notification];
     },
 
     dismissNotification: (facts, { id }: { id: string }) => {
-      facts.queue = (facts.queue as Notification[]).filter((n) => n.id !== id);
+      facts.queue = facts.queue.filter((n) => n.id !== id);
     },
 
     tick: (facts) => {
@@ -188,7 +189,7 @@ export const notificationsModule = createModule("notifications", {
 
 export const appSchema = {
   facts: {
-    actionLog: t.object<string[]>(),
+    actionLog: t.array<string>(),
   },
   events: {
     simulateAction: { message: t.string(), level: t.string() },
@@ -204,7 +205,7 @@ export const appModule = createModule("app", {
 
   events: {
     simulateAction: (facts, { message }: { message: string }) => {
-      facts.actionLog = [...(facts.actionLog as string[]), message];
+      facts.actionLog = [...facts.actionLog, message];
     },
   },
 });

package/examples/optimistic-updates.ts

@@ -51,15 +51,15 @@ let nextOpId = 1;
 
 export const optimisticUpdatesSchema = {
   facts: {
-    items: t.object<TodoItem[]>(),
-    syncQueue: t.object<SyncQueueEntry[]>(),
+    items: t.array<TodoItem>(),
+    syncQueue: t.array<SyncQueueEntry>(),
     syncingOpId: t.string(),
     newItemText: t.string(),
     serverDelay: t.number(),
     failRate: t.number(),
     toastMessage: t.string(),
     toastType: t.string(),
-    eventLog: t.object<EventLogEntry[]>(),
+    eventLog: t.array<EventLogEntry>(),
   },
   derivations: {
     totalCount: t.number(),
@@ -127,16 +127,15 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
   // ============================================================================
 
   derive: {
-    totalCount: (facts) => (facts.items as TodoItem[]).length,
+    totalCount: (facts) => facts.items.length,
 
-    doneCount: (facts) =>
-      (facts.items as TodoItem[]).filter((i) => i.done).length,
+    doneCount: (facts) => facts.items.filter((i) => i.done).length,
 
-    pendingCount: (facts) => (facts.syncQueue as SyncQueueEntry[]).length,
+    pendingCount: (facts) => facts.syncQueue.length,
 
-    canAdd: (facts) => (facts.newItemText as string).trim() !== "",
+    canAdd: (facts) => facts.newItemText.trim() !== "",
 
-    isSyncing: (facts) => (facts.syncingOpId as string) !== "",
+    isSyncing: (facts) => facts.syncingOpId !== "",
   },
 
   // ============================================================================
@@ -145,15 +144,14 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
 
   events: {
     toggleItem: (facts, { id }) => {
-      const items = facts.items as TodoItem[];
-      const undoItems = items.map((i) => ({ ...i }));
+      const undoItems = facts.items.map((i) => ({ ...i }));
 
-      facts.items = items.map((i) =>
+      facts.items = facts.items.map((i) =>
         i.id === id ? { ...i, done: !i.done } : i,
       );
 
       const opId = String(nextOpId++);
-      const queue = [...(facts.syncQueue as SyncQueueEntry[])];
+      const queue = [...facts.syncQueue];
       queue.push({ opId, itemId: id, op: "toggle", undoItems });
       facts.syncQueue = queue;
 
@@ -161,13 +159,12 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
     },
 
     deleteItem: (facts, { id }) => {
-      const items = facts.items as TodoItem[];
-      const undoItems = items.map((i) => ({ ...i }));
+      const undoItems = facts.items.map((i) => ({ ...i }));
 
-      facts.items = items.filter((i) => i.id !== id);
+      facts.items = facts.items.filter((i) => i.id !== id);
 
       const opId = String(nextOpId++);
-      const queue = [...(facts.syncQueue as SyncQueueEntry[])];
+      const queue = [...facts.syncQueue];
       queue.push({ opId, itemId: id, op: "delete", undoItems });
       facts.syncQueue = queue;
 
@@ -175,20 +172,19 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
     },
 
     addItem: (facts) => {
-      const text = (facts.newItemText as string).trim();
+      const text = facts.newItemText.trim();
       if (!text) {
         return;
       }
 
-      const items = facts.items as TodoItem[];
-      const undoItems = items.map((i) => ({ ...i }));
+      const undoItems = facts.items.map((i) => ({ ...i }));
 
       const itemId = String(nextId++);
-      facts.items = [...items, { id: itemId, text, done: false }];
+      facts.items = [...facts.items, { id: itemId, text, done: false }];
       facts.newItemText = "";
 
       const opId = String(nextOpId++);
-      const queue = [...(facts.syncQueue as SyncQueueEntry[])];
+      const queue = [...facts.syncQueue];
       queue.push({ opId, itemId, op: "add", undoItems });
       facts.syncQueue = queue;
 
@@ -221,17 +217,12 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
     needsSync: {
       priority: 100,
       when: (facts) => {
-        const queue = facts.syncQueue as SyncQueueEntry[];
-        const syncingOpId = facts.syncingOpId as string;
-
-        return queue.length > 0 && syncingOpId === "";
+        return facts.syncQueue.length > 0 && facts.syncingOpId === "";
       },
       require: (facts) => {
-        const queue = facts.syncQueue as SyncQueueEntry[];
-
         return {
           type: "SYNC_TODO",
-          opId: queue[0].opId,
+          opId: facts.syncQueue[0].opId,
         };
       },
     },
@@ -247,8 +238,7 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
       key: (req) => `sync-${req.opId}`,
       timeout: 10000,
       resolve: async (req, context) => {
-        const queue = context.facts.syncQueue as SyncQueueEntry[];
-        const entry = queue.find((e) => e.opId === req.opId);
+        const entry = context.facts.syncQueue.find((e) => e.opId === req.opId);
         if (!entry) {
           return;
         }
@@ -260,8 +250,8 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
           `Syncing ${entry.op} for item ${entry.itemId}...`,
         );
 
-        const serverDelay = context.facts.serverDelay as number;
-        const failRate = context.facts.failRate as number;
+        const serverDelay = context.facts.serverDelay;
+        const failRate = context.facts.failRate;
 
         try {
           await mockServerSync(entry.op, entry.itemId, serverDelay, failRate);
@@ -285,8 +275,7 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
         }
 
         // Remove entry from queue
-        const currentQueue = context.facts.syncQueue as SyncQueueEntry[];
-        context.facts.syncQueue = currentQueue.filter(
+        context.facts.syncQueue = context.facts.syncQueue.filter(
           (e) => e.opId !== req.opId,
         );
         context.facts.syncingOpId = "";
@@ -303,12 +292,18 @@ export const optimisticUpdatesModule = createModule("optimistic-updates", {
       deps: ["syncingOpId"],
       run: (facts, prev) => {
         if (prev) {
-          const prevId = prev.syncingOpId as string;
-          const currId = facts.syncingOpId as string;
-          if (prevId === "" && currId !== "") {
-            addLogEntry(facts, "status", `Sync started: op ${currId}`);
-          } else if (prevId !== "" && currId === "") {
-            addLogEntry(facts, "status", `Sync completed: op ${prevId}`);
+          if (prev.syncingOpId === "" && facts.syncingOpId !== "") {
+            addLogEntry(
+              facts,
+              "status",
+              `Sync started: op ${facts.syncingOpId}`,
+            );
+          } else if (prev.syncingOpId !== "" && facts.syncingOpId === "") {
+            addLogEntry(
+              facts,
+              "status",
+              `Sync completed: op ${prev.syncingOpId}`,
+            );
           }
         }
       },

package/examples/pagination.ts

@@ -56,7 +56,7 @@ export const filtersModule = createModule("filters", {
       facts.search = value;
     },
     setSortBy: (facts, { value }) => {
-      facts.sortBy = value;
+      facts.sortBy = value as "newest" | "oldest" | "title";
     },
     setCategory: (facts, { value }) => {
       facts.category = value;
@@ -70,7 +70,7 @@ export const filtersModule = createModule("filters", {
 
 export const listSchema = {
   facts: {
-    items: t.object<ListItem[]>(),
+    items: t.array<ListItem>(),
     cursor: t.string(),
     hasMore: t.boolean(),
     isLoadingMore: t.boolean(),

package/examples/permissions.ts

@@ -101,7 +101,7 @@ export const authModule = createModule("auth", {
 
 export const permissionsSchema = {
   facts: {
-    permissions: t.object<string[]>(),
+    permissions: t.array<string>(),
     loaded: t.boolean(),
   },
   derivations: {
@@ -132,18 +132,14 @@ export const permissionsModule = createModule("permissions", {
   },
 
   derive: {
-    canEdit: (facts) =>
-      (facts.self.permissions as string[]).includes("content.edit"),
-    canPublish: (facts) =>
-      (facts.self.permissions as string[]).includes("content.publish"),
-    canDelete: (facts) =>
-      (facts.self.permissions as string[]).includes("content.delete"),
-    canManageUsers: (facts) =>
-      (facts.self.permissions as string[]).includes("users.manage"),
+    canEdit: (facts) => facts.self.permissions.includes("content.edit"),
+    canPublish: (facts) => facts.self.permissions.includes("content.publish"),
+    canDelete: (facts) => facts.self.permissions.includes("content.delete"),
+    canManageUsers: (facts) => facts.self.permissions.includes("users.manage"),
     canViewAnalytics: (facts) =>
-      (facts.self.permissions as string[]).includes("analytics.view"),
-    isAdmin: (_facts, derive) => derive.canManageUsers as boolean,
-    permissionCount: (facts) => (facts.self.permissions as string[]).length,
+      facts.self.permissions.includes("analytics.view"),
+    isAdmin: (_facts, derive) => derive.canManageUsers,
+    permissionCount: (facts) => facts.self.permissions.length,
   },
 
   events: {
@@ -156,13 +152,11 @@ export const permissionsModule = createModule("permissions", {
   constraints: {
     loadPermissions: {
       when: (facts) => {
-        return (
-          (facts.auth.token as string) !== "" && !(facts.self.loaded as boolean)
-        );
+        return facts.auth.token !== "" && !facts.self.loaded;
       },
       require: (facts) => ({
         type: "FETCH_PERMISSIONS",
-        role: facts.auth.role as string,
+        role: facts.auth.role,
       }),
     },
   },
@@ -186,7 +180,7 @@ export const permissionsModule = createModule("permissions", {
 
 export const contentSchema = {
   facts: {
-    articles: t.object<Article[]>(),
+    articles: t.array<Article>(),
     loaded: t.boolean(),
     publishRequested: t.string(),
     deleteRequested: t.string(),
@@ -221,9 +215,7 @@ export const contentModule = createModule("content", {
   constraints: {
     loadContent: {
       when: (facts) => {
-        return (
-          (facts.auth.token as string) !== "" && !(facts.self.loaded as boolean)
-        );
+        return facts.auth.token !== "" && !facts.self.loaded;
       },
       require: { type: "LOAD_CONTENT" },
     },
@@ -231,28 +223,26 @@ export const contentModule = createModule("content", {
     publishArticle: {
       when: (facts) => {
         return (
-          (facts.self.publishRequested as string) !== "" &&
-          (facts.permissions.permissions as string[]).includes(
-            "content.publish",
-          )
+          facts.self.publishRequested !== "" &&
+          facts.permissions.permissions.includes("content.publish")
         );
       },
       require: (facts) => ({
         type: "PUBLISH_ARTICLE",
-        articleId: facts.self.publishRequested as string,
+        articleId: facts.self.publishRequested,
       }),
     },
 
     deleteArticle: {
       when: (facts) => {
         return (
-          (facts.self.deleteRequested as string) !== "" &&
-          (facts.permissions.permissions as string[]).includes("content.delete")
+          facts.self.deleteRequested !== "" &&
+          facts.permissions.permissions.includes("content.delete")
         );
       },
       require: (facts) => ({
         type: "DELETE_ARTICLE",
-        articleId: facts.self.deleteRequested as string,
+        articleId: facts.self.deleteRequested,
       }),
     },
   },
@@ -275,8 +265,7 @@ export const contentModule = createModule("content", {
         context.facts.actionStatus = "publishing";
         await apiPublishArticle(req.articleId);
 
-        const articles = context.facts.articles as Article[];
-        context.facts.articles = articles.map((a) => {
+        context.facts.articles = context.facts.articles.map((a) => {
           if (a.id === req.articleId) {
             return { ...a, status: "published" as const };
           }
@@ -295,8 +284,9 @@ export const contentModule = createModule("content", {
         context.facts.actionStatus = "deleting";
         await apiDeleteArticle(req.articleId);
 
-        const articles = context.facts.articles as Article[];
-        context.facts.articles = articles.filter((a) => a.id !== req.articleId);
+        context.facts.articles = context.facts.articles.filter(
+          (a) => a.id !== req.articleId,
+        );
         context.facts.deleteRequested = "";
         context.facts.actionStatus = "done";
       },