Troubleshooting

constraints: {
  needsUser: {
    when: (facts) => {
      // Temporarily log to see why the constraint isn't activating
      const result = facts.userId > 0 && !facts.user;
      console.log('needsUser condition:', result, {
        userId: facts.userId,
        user: facts.user,
      });
      return result;
    },
    require: { type: "FETCH_USER" },
  },
},

constraints: {
  critical: {
    priority: 100,  // Higher number = evaluated first
    when: (facts) => true,
    require: { type: "CRITICAL_ACTION" },
  },

  normal: {
    priority: 50,  // Lower priority – may be blocked by the critical constraint
    when: (facts) => true,
    require: { type: "NORMAL_ACTION" },
  },
},

resolvers: {
  fetchUser: {
    requirement: "FETCH_USER",

    // A unique key per payload ensures each request runs independently
    key: (req) => `fetch-${req.payload?.id}`,

    resolve: async (req, context) => { /* ... */ },
  },
},

// BAD: constraint keeps firing because shouldLoad is never cleared
constraints: {
  loadData: {
    when: (facts) => facts.shouldLoad,
    require: { type: "LOAD_DATA" },
  },
},
resolvers: {
  loadData: {
    requirement: "LOAD_DATA",
    resolve: async (req, context) => {
      const data = await fetchData();
      context.facts.data = data;
      // Forgot to set shouldLoad = false – infinite loop!
    },
  },
},

// GOOD: clear the flag first to break the constraint cycle
resolvers: {
  loadData: {
    requirement: "LOAD_DATA",
    resolve: async (req, context) => {
      context.facts.shouldLoad = false;  // Disarm the constraint immediately
      const data = await fetchData();
      context.facts.data = data;
    },
  },
},

resolvers: {
  fetchUser: {
    requirement: "FETCH_USER",
    retry: { attempts: 3, backoff: "exponential" },  // Retry up to 3 times

    resolve: async (req, context) => {
      try {
        context.facts.user = await api.getUser(context.facts.userId);
      } catch (error) {
        // Store the error in facts so the UI can display it
        context.facts.error = error instanceof Error ? error.message : 'Unknown error';
        // Don't re-throw – swallowing the error marks it as handled
      }
    },
  },
},

// Centralized error handling – catches errors from any resolver or constraint
const system = createSystem({
  module: myModule,
  errorBoundary: {
    onResolverError: (error, resolver) => {
      console.error('Resolver error:', error, resolver);
    },

    onConstraintError: (error, constraint) => {
      console.error('Constraint error:', error, constraint);
    },

    // Catch-all for anything else
    onError: (error) => {
      console.error('System error:', error);
    },
  },
});

// BAD: mutating a local variable has no effect on the store
resolve: async (req, context) => {
  const facts = context.facts;
  facts.user = await api.getUser(); // This works – writing through the proxy

  const user = await api.getUser();
  user.name = "John"; // This does NOT update facts – it's a detached object
},

// GOOD: always assign through context.facts to trigger reactivity
resolve: async (req, context) => {
  context.facts.user = await api.getUser();
},

// BAD: nested mutation bypasses the proxy – no listeners fire
context.facts.user.name = "John";

// GOOD: replace the entire object so the proxy detects the change
context.facts.user = { ...context.facts.user, name: "John" };

resolvers: {
  fetchLargeData: {
    requirement: "FETCH_LARGE_DATA",
    timeout: 30000,  // Extend from the default to allow 30 seconds

    resolve: async (req, context) => {
      // Long-running operation
    },
  },
},

// BAD: closes over a constant – never recomputes when state changes
const userId = 123;
derive: {
  userDisplay: () => `User ${userId}`,  // Always shows "User 123"
},

// GOOD: read from facts so the derivation tracks the dependency
derive: {
  userDisplay: (facts) => `User ${facts.userId}`,
},

// BAD: a reads b, and b reads a – stack overflow
derive: {
  a: (facts, derive) => derive.b + 1,
  b: (facts, derive) => derive.a + 1,  // Circular!
},

// GOOD: root at least one derivation in facts to break the cycle
derive: {
  a: (facts) => facts.value + 1,
  b: (facts, derive) => derive.a + 1,
},

// BAD: passing undefined instead of a system crashes at runtime
function UserProfile() {
  const name = useFact(undefined, "name");  // Error!
}

// GOOD: import and pass a valid system reference
import { system } from './system';

function UserProfile() {
  const name = useFact(system, "name");
}

// BAD: any change to the user object triggers a re-render
const user = useFact(system, "user");

// GOOD: useSelector narrows the subscription to just the name property
const userName = useSelector(system, (state) => state.user?.name);

// BAD: empty deps array captures the initial count forever
useEffect(() => {
  const interval = setInterval(() => {
    console.log(count); // Always logs the initial value
  }, 1000);

  return () => clearInterval(interval);
}, []);

// GOOD: let the hook manage the subscription – always fresh
const count = useFact(system, "count");

// TypeScript catches the mismatch at compile time
context.facts.userId = "123";  // Error: Type 'string' is not assignable to type 'number'

// Fix: assign the correct type directly
context.facts.userId = 123;

// Or parse the string into a number first
context.facts.userId = parseInt(userId, 10);

// The schema defines the exact property names TypeScript will enforce
schema: {
  facts: {
    userId: t.number(),  // camelCase – this is the canonical name
  },
},

// Access must match the schema key exactly
context.facts.userId   // Correct
context.facts.user_id  // Error: property does not exist

npm install @directive-run/core
# or
pnpm add @directive-run/core
# or
yarn add directive

// Import from subpaths so the bundler can tree-shake unused exports
import { createModule, createSystem } from '@directive-run/core';
import { loggingPlugin } from '@directive-run/core/plugins';
import { useFact } from '@directive-run/react';

// Time-travel mode records every state transition for inspection
const system = createSystem({
  module: myModule,
  debug: { timeTravel: true },
});

import { devtoolsPlugin } from '@directive-run/core/plugins';

// DevTools shows live constraint evaluations, resolver activity, and facts
const system = createSystem({
  module: myModule,
  plugins: [devtoolsPlugin()],
});