@directive-run/knowledge 0.2.0

package/examples/pagination.ts

@@ -0,0 +1,260 @@
+// Example: pagination
+// Source: examples/pagination/src/pagination.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Pagination & Infinite Scroll — Directive Modules
+ *
+ * Two modules: `filters` owns search/sort/category,
+ * `list` owns items and pagination state with crossModuleDeps.
+ *
+ * Constraints:
+ * - loadMore: appends next page when scrollNearBottom
+ * - filterChanged: resets and re-fetches when filters change
+ *
+ * Effects:
+ * - observeScroll: IntersectionObserver on sentinel element
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin, loggingPlugin } from "@directive-run/core/plugins";
+import { type ListItem, fetchPage } from "./mock-api.js";
+
+// ============================================================================
+// Filters Module
+// ============================================================================
+
+export const filtersSchema = {
+  facts: {
+    search: t.string(),
+    sortBy: t.string<"newest" | "oldest" | "title">(),
+    category: t.string(),
+  },
+  events: {
+    setSearch: { value: t.string() },
+    setSortBy: { value: t.string() },
+    setCategory: { value: t.string() },
+  },
+} satisfies ModuleSchema;
+
+export const filtersModule = createModule("filters", {
+  schema: filtersSchema,
+
+  init: (facts) => {
+    facts.search = "";
+    facts.sortBy = "newest";
+    facts.category = "all";
+  },
+
+  events: {
+    setSearch: (facts, { value }) => {
+      facts.search = value;
+    },
+    setSortBy: (facts, { value }) => {
+      facts.sortBy = value;
+    },
+    setCategory: (facts, { value }) => {
+      facts.category = value;
+    },
+  },
+});
+
+// ============================================================================
+// List Module
+// ============================================================================
+
+export const listSchema = {
+  facts: {
+    items: t.object<ListItem[]>(),
+    cursor: t.string(),
+    hasMore: t.boolean(),
+    isLoadingMore: t.boolean(),
+    scrollNearBottom: t.boolean(),
+    lastFilterHash: t.string(),
+  },
+  derivations: {
+    totalLoaded: t.number(),
+    isEmpty: t.boolean(),
+  },
+  events: {
+    setScrollNearBottom: { value: t.boolean() },
+  },
+  requirements: {
+    LOAD_PAGE: {
+      cursor: t.string(),
+      search: t.string(),
+      sortBy: t.string(),
+      category: t.string(),
+    },
+    RESET_AND_LOAD: {
+      search: t.string(),
+      sortBy: t.string(),
+      category: t.string(),
+    },
+  },
+} satisfies ModuleSchema;
+
+export const listModule = createModule("list", {
+  schema: listSchema,
+
+  crossModuleDeps: { filters: filtersSchema },
+
+  init: (facts) => {
+    facts.items = [];
+    facts.cursor = "";
+    facts.hasMore = true;
+    facts.isLoadingMore = false;
+    facts.scrollNearBottom = false;
+    facts.lastFilterHash = "";
+  },
+
+  // ============================================================================
+  // Derivations
+  // ============================================================================
+
+  derive: {
+    totalLoaded: (facts) => facts.self.items.length,
+    isEmpty: (facts) => facts.self.items.length === 0 && !facts.self.hasMore,
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    setScrollNearBottom: (facts, { value }) => {
+      facts.scrollNearBottom = value;
+    },
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+
+  constraints: {
+    loadMore: {
+      when: (facts) => {
+        return (
+          facts.self.hasMore &&
+          !facts.self.isLoadingMore &&
+          facts.self.scrollNearBottom
+        );
+      },
+      require: (facts) => ({
+        type: "LOAD_PAGE",
+        cursor: facts.self.cursor,
+        search: facts.filters.search,
+        sortBy: facts.filters.sortBy,
+        category: facts.filters.category,
+      }),
+    },
+
+    filterChanged: {
+      when: (facts) => {
+        const hash = `${facts.filters.search}|${facts.filters.sortBy}|${facts.filters.category}`;
+
+        return hash !== facts.self.lastFilterHash;
+      },
+      require: (facts) => ({
+        type: "RESET_AND_LOAD",
+        search: facts.filters.search,
+        sortBy: facts.filters.sortBy,
+        category: facts.filters.category,
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+
+  resolvers: {
+    loadPage: {
+      requirement: "LOAD_PAGE",
+      resolve: async (req, context) => {
+        context.facts.isLoadingMore = true;
+
+        try {
+          const data = await fetchPage(req.cursor, 20, {
+            search: req.search,
+            sortBy: req.sortBy,
+            category: req.category,
+          });
+
+          context.facts.items = [...context.facts.items, ...data.items];
+          context.facts.cursor = data.nextCursor;
+          context.facts.hasMore = data.hasMore;
+        } finally {
+          context.facts.isLoadingMore = false;
+        }
+      },
+    },
+
+    resetAndLoad: {
+      requirement: "RESET_AND_LOAD",
+      resolve: async (req, context) => {
+        const hash = `${req.search}|${req.sortBy}|${req.category}`;
+
+        context.facts.items = [];
+        context.facts.cursor = "";
+        context.facts.hasMore = true;
+        context.facts.isLoadingMore = true;
+        context.facts.lastFilterHash = hash;
+
+        try {
+          const data = await fetchPage("", 20, {
+            search: req.search,
+            sortBy: req.sortBy,
+            category: req.category,
+          });
+
+          context.facts.items = data.items;
+          context.facts.cursor = data.nextCursor;
+          context.facts.hasMore = data.hasMore;
+        } finally {
+          context.facts.isLoadingMore = false;
+        }
+      },
+    },
+  },
+
+  // ============================================================================
+  // Effects
+  // ============================================================================
+
+  effects: {
+    observeScroll: {
+      run: (facts) => {
+        const sentinel = document.getElementById("pg-scroll-sentinel");
+        if (!sentinel) {
+          return;
+        }
+
+        const observer = new IntersectionObserver(
+          ([entry]) => {
+            facts.self.scrollNearBottom = entry.isIntersecting;
+          },
+          { rootMargin: "200px" },
+        );
+        observer.observe(sentinel);
+
+        return () => observer.disconnect();
+      },
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+export const system = createSystem({
+  modules: { filters: filtersModule, list: listModule },
+  debug: { runHistory: true },
+  plugins: [loggingPlugin(), devtoolsPlugin({ name: "pagination" })],
+});

package/examples/permissions.ts

@@ -0,0 +1,337 @@
+// Example: permissions
+// Source: examples/permissions/src/permissions.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Role-Based Permissions — Directive Modules
+ *
+ * Three modules demonstrate cross-module constraint resolution:
+ * - auth: manages login state (role, userName, token)
+ * - permissions: loads permissions based on auth role, derives capability flags
+ * - content: manages articles with permission-gated actions
+ *
+ * The system uses `crossModuleDeps` so constraints in one module
+ * can react to derivations/facts from another module.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+import {
+  type Article,
+  deleteArticle as apiDeleteArticle,
+  fetchArticles as apiFetchArticles,
+  fetchPermissions as apiFetchPermissions,
+  publishArticle as apiPublishArticle,
+} from "./mock-api.js";
+
+// ============================================================================
+// Preset Users
+// ============================================================================
+
+const presetUsers: Record<
+  string,
+  { userName: string; role: string; token: string }
+> = {
+  alice: { userName: "Alice", role: "admin", token: "tok-alice-admin" },
+  bob: { userName: "Bob", role: "editor", token: "tok-bob-editor" },
+  carol: { userName: "Carol", role: "viewer", token: "tok-carol-viewer" },
+};
+
+// ============================================================================
+// Auth Module
+// ============================================================================
+
+export const authSchema = {
+  facts: {
+    role: t.string(),
+    userName: t.string(),
+    token: t.string(),
+  },
+  derivations: {
+    isAuthenticated: t.boolean(),
+  },
+  events: {
+    login: { userId: t.string() },
+    logout: {},
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+export const authModule = createModule("auth", {
+  schema: authSchema,
+
+  init: (facts) => {
+    facts.role = "";
+    facts.userName = "";
+    facts.token = "";
+  },
+
+  derive: {
+    isAuthenticated: (facts) => facts.token !== "",
+  },
+
+  events: {
+    login: (facts, { userId }) => {
+      const preset = presetUsers[userId];
+      if (!preset) {
+        return;
+      }
+
+      facts.token = preset.token;
+      facts.userName = preset.userName;
+      facts.role = preset.role;
+    },
+
+    logout: (facts) => {
+      facts.token = "";
+      facts.userName = "";
+      facts.role = "";
+    },
+  },
+});
+
+// ============================================================================
+// Permissions Module
+// ============================================================================
+
+export const permissionsSchema = {
+  facts: {
+    permissions: t.object<string[]>(),
+    loaded: t.boolean(),
+  },
+  derivations: {
+    canEdit: t.boolean(),
+    canPublish: t.boolean(),
+    canDelete: t.boolean(),
+    canManageUsers: t.boolean(),
+    canViewAnalytics: t.boolean(),
+    isAdmin: t.boolean(),
+    permissionCount: t.number(),
+  },
+  events: {
+    reset: {},
+  },
+  requirements: {
+    FETCH_PERMISSIONS: { role: t.string() },
+  },
+} satisfies ModuleSchema;
+
+export const permissionsModule = createModule("permissions", {
+  schema: permissionsSchema,
+
+  crossModuleDeps: { auth: authSchema },
+
+  init: (facts) => {
+    facts.permissions = [];
+    facts.loaded = false;
+  },
+
+  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"),
+    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,
+  },
+
+  events: {
+    reset: (facts) => {
+      facts.permissions = [];
+      facts.loaded = false;
+    },
+  },
+
+  constraints: {
+    loadPermissions: {
+      when: (facts) => {
+        return (
+          (facts.auth.token as string) !== "" && !(facts.self.loaded as boolean)
+        );
+      },
+      require: (facts) => ({
+        type: "FETCH_PERMISSIONS",
+        role: facts.auth.role as string,
+      }),
+    },
+  },
+
+  resolvers: {
+    fetchPermissions: {
+      requirement: "FETCH_PERMISSIONS",
+      timeout: 5000,
+      resolve: async (req, context) => {
+        const perms = await apiFetchPermissions(req.role);
+        context.facts.permissions = perms;
+        context.facts.loaded = true;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Content Module
+// ============================================================================
+
+export const contentSchema = {
+  facts: {
+    articles: t.object<Article[]>(),
+    loaded: t.boolean(),
+    publishRequested: t.string(),
+    deleteRequested: t.string(),
+    actionStatus: t.string(),
+  },
+  derivations: {},
+  events: {
+    requestPublish: { articleId: t.string() },
+    requestDelete: { articleId: t.string() },
+    clearAction: {},
+  },
+  requirements: {
+    LOAD_CONTENT: {},
+    PUBLISH_ARTICLE: { articleId: t.string() },
+    DELETE_ARTICLE: { articleId: t.string() },
+  },
+} satisfies ModuleSchema;
+
+export const contentModule = createModule("content", {
+  schema: contentSchema,
+
+  crossModuleDeps: { auth: authSchema, permissions: permissionsSchema },
+
+  init: (facts) => {
+    facts.articles = [];
+    facts.loaded = false;
+    facts.publishRequested = "";
+    facts.deleteRequested = "";
+    facts.actionStatus = "idle";
+  },
+
+  constraints: {
+    loadContent: {
+      when: (facts) => {
+        return (
+          (facts.auth.token as string) !== "" && !(facts.self.loaded as boolean)
+        );
+      },
+      require: { type: "LOAD_CONTENT" },
+    },
+
+    publishArticle: {
+      when: (facts) => {
+        return (
+          (facts.self.publishRequested as string) !== "" &&
+          (facts.permissions.permissions as string[]).includes(
+            "content.publish",
+          )
+        );
+      },
+      require: (facts) => ({
+        type: "PUBLISH_ARTICLE",
+        articleId: facts.self.publishRequested as string,
+      }),
+    },
+
+    deleteArticle: {
+      when: (facts) => {
+        return (
+          (facts.self.deleteRequested as string) !== "" &&
+          (facts.permissions.permissions as string[]).includes("content.delete")
+        );
+      },
+      require: (facts) => ({
+        type: "DELETE_ARTICLE",
+        articleId: facts.self.deleteRequested as string,
+      }),
+    },
+  },
+
+  resolvers: {
+    loadContent: {
+      requirement: "LOAD_CONTENT",
+      timeout: 5000,
+      resolve: async (_req, context) => {
+        const articles = await apiFetchArticles();
+        context.facts.articles = articles;
+        context.facts.loaded = true;
+      },
+    },
+
+    publishArticle: {
+      requirement: "PUBLISH_ARTICLE",
+      timeout: 5000,
+      resolve: async (req, context) => {
+        context.facts.actionStatus = "publishing";
+        await apiPublishArticle(req.articleId);
+
+        const articles = context.facts.articles as Article[];
+        context.facts.articles = articles.map((a) => {
+          if (a.id === req.articleId) {
+            return { ...a, status: "published" as const };
+          }
+
+          return a;
+        });
+        context.facts.publishRequested = "";
+        context.facts.actionStatus = "done";
+      },
+    },
+
+    deleteArticle: {
+      requirement: "DELETE_ARTICLE",
+      timeout: 5000,
+      resolve: async (req, context) => {
+        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.deleteRequested = "";
+        context.facts.actionStatus = "done";
+      },
+    },
+  },
+
+  events: {
+    requestPublish: (facts, { articleId }) => {
+      facts.publishRequested = articleId;
+      facts.actionStatus = "idle";
+    },
+
+    requestDelete: (facts, { articleId }) => {
+      facts.deleteRequested = articleId;
+      facts.actionStatus = "idle";
+    },
+
+    clearAction: (facts) => {
+      facts.publishRequested = "";
+      facts.deleteRequested = "";
+      facts.actionStatus = "idle";
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+export const system = createSystem({
+  modules: {
+    auth: authModule,
+    permissions: permissionsModule,
+    content: contentModule,
+  },
+  debug: { runHistory: true },
+  plugins: [devtoolsPlugin({ name: "permissions" })],
+});