Praxis

The full-stack declarative application framework — typed logic, reactive state, local-first data, and visual tooling for Svelte, Node, and the browser.

Praxis 2.0 gives you a single createApp() call that wires reactive state, constraint validation, rule evaluation, and an immutable timeline — zero boilerplate. When you need deeper control, drop down to the classic engine with registries, typed events/facts, and undo/redo history.

Install

Node 18+ recommended.

npm install @plures/praxis   # or: pnpm add @plures/praxis

API Reference

See docs/API.md for the exported public API surface.

Quick Start — Unified App (v2.0)

The fastest way to build with Praxis. Define paths (state), rules, and constraints — Praxis handles the rest.

import {
  createApp,
  definePath,
  defineRule,
  defineConstraint,
  RuleResult,
  fact,
} from '@plures/praxis/unified';

// 1. Declare your state shape
const Count = definePath<number>('count', 0);
const Max   = definePath<number>('max', 10);

// 2. Add constraints
const notNegative = defineConstraint({
  id: 'count.not-negative',
  description: 'Count must never go below zero',
  watch: ['count'],
  validate: (values) => values['count'] >= 0 || 'Count cannot be negative',
});

// 3. Add rules
const capAtMax = defineRule({
  id: 'count.cap',
  watch: ['count', 'max'],
  evaluate: (values) => {
    if (values['count'] > values['max']) {
      return RuleResult.emit([fact('count.capped', { at: values['max'] })]);
    }
    return RuleResult.noop();
  },
});

// 4. Create the app
const app = createApp({
  name: 'counter',
  schema: [Count, Max],
  rules: [capAtMax],
  constraints: [notNegative],
});

// 5. Query & mutate
const count = app.query<number>('count');
console.log(count.current); // 0

app.mutate('count', 5);
console.log(count.current); // 5

const result = app.mutate('count', -1);
console.log(result.accepted); // false — constraint rejected

Classic Engine (full control)

For complex scenarios that need typed events, facts, actors, and undo/redo:

import {
  createPraxisEngine,
  PraxisRegistry,
  defineFact,
  defineEvent,
  defineRule,
} from '@plures/praxis';

const UserLoggedIn = defineFact<'UserLoggedIn', { userId: string }>('UserLoggedIn');
const Login = defineEvent<'LOGIN', { username: string }>('LOGIN');

const loginRule = defineRule<{ currentUser: string | null }>({
  id: 'auth.login',
  description: 'Authenticate and emit fact',
  impl: (state, events) => {
    const evt = events.find(Login.is);
    if (!evt) return [];
    state.context.currentUser = evt.payload.username;
    return [UserLoggedIn.create({ userId: evt.payload.username })];
  },
});

const registry = new PraxisRegistry();
registry.registerRule(loginRule);

const engine = createPraxisEngine({ initialContext: { currentUser: null }, registry });
engine.step([Login.create({ username: 'alex' })]);
console.log(engine.getContext()); // { currentUser: 'alex' }

Svelte 5 Integration

Runes API

<script lang="ts">
  import { usePraxisEngine } from '@plures/praxis/svelte';
  import { createMyEngine, Login } from './my-engine';

  const engine = createMyEngine();
  const { context, dispatch, undo, redo, canUndo, canRedo } = usePraxisEngine(engine, {
    enableHistory: true,
    maxHistorySize: 50,
  });
</script>

<p>User: {context.currentUser || 'Guest'}</p>
<button onclick={() => dispatch([Login.create({ username: 'alice' })])}>Login</button>
<button onclick={undo} disabled={!canUndo}>⟲ Undo</button>
<button onclick={redo} disabled={!canRedo}>⟳ Redo</button>

Store API

import { createPraxisStore, createDerivedStore } from '@plures/praxis/svelte';

const stateStore = createPraxisStore(engine);
const userStore  = createDerivedStore(engine, (ctx) => ctx.currentUser);

See Svelte Integration Guide for the full API including reactive engine, history patterns, and keyboard shortcuts.

Decision Ledger (Behavior Contracts)

Attach explicit contracts to every rule and constraint — with Given/When/Then examples, invariants, and assumption tracking.

import { defineContract, defineRule } from '@plures/praxis';

const loginContract = defineContract({
  ruleId: 'auth.login',
  behavior: 'Process login events and create user session facts',
  examples: [
    { given: 'Valid credentials', when: 'LOGIN event', then: 'UserSessionCreated fact emitted' }
  ],
  invariants: ['Session must have unique ID'],
});

const loginRule = defineRule({
  id: 'auth.login',
  description: 'Process login events',
  impl: (state, events) => { /* ... */ },
  contract: loginContract,
});

npm run scan:rules           # Index all rules/constraints
npm run validate:contracts   # Validate all contracts
npx praxis validate --strict # CI/CD enforcement

See Decision Ledger Guide for the full dogfooding workflow.

PluresDB — Local-First Persistence

import { createInMemoryDB, createPluresDBAdapter } from '@plures/praxis';

const db = createInMemoryDB();
const adapter = createPluresDBAdapter({ db, registry });
adapter.attachEngine(engine); // auto-persist facts & events

For production, use the official @plures/pluresdb package with P2P sync and CRDT conflict resolution:

import { PluresNode } from '@plures/pluresdb';
import { createPluresDB } from '@plures/praxis';

const db = createPluresDB(new PluresNode({ config: { port: 34567, dataDir: './data' }, autoStart: true }));

CLI

npx praxis --help
npx praxis create app my-app
npx praxis generate --schema src/schemas/app.schema.ts
npx praxis canvas src/schemas/app.schema.ts

Exports

| Import path | Description | |---|---| | @plures/praxis | Core engine, DSL, protocol types, integrations | | @plures/praxis/unified | createApp() unified reactive layer | | @plures/praxis/svelte | Svelte 5 runes + store APIs | | @plures/praxis/schema | Schema types and loaders | | @plures/praxis/component | Svelte component generator | | @plures/praxis/cloud | Cloud relay sync | | @plures/praxis/components | Built-in Svelte components | | @plures/praxis/mcp | Model Context Protocol tools | | @plures/praxis/expectations | Behavior expectation DSL | | @plures/praxis/factory | Pre-built UI rule modules | | @plures/praxis/project | Project gates and lifecycle | | praxis (bin) | CLI entrypoint |

Core Protocol

All Praxis APIs build on a language-neutral, pure-function protocol:

interface PraxisFact  { tag: string; payload: unknown }
interface PraxisEvent { tag: string; payload: unknown }
interface PraxisState { context: unknown; facts: PraxisFact[]; meta?: Record<string, unknown> }

// The conceptual core — pure, deterministic, no side effects
type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;

Implemented in TypeScript (npm), C# (.NET 8+, NuGet: Plures.Praxis), and PowerShell. All share the same JSON wire format. See CROSS_LANGUAGE_SYNC.md and PROTOCOL_VERSIONING.md.

Examples

| Example | Description | Location | |---|---|---| | Hero E-Commerce | Full-stack: auth, cart, discounts, loyalty, actors | src/examples/hero-ecommerce/ | | Decision Ledger | Contracts, validation, SARIF output | examples/decision-ledger/ | | Offline Chat | Local-first messaging with PluresDB | examples/offline-chat/ | | Terminal Node | Command execution with YAML schemas | examples/terminal-node/ | | Unified App | createApp() + rules + Mermaid docs | examples/unified-app/ | | Cloud Sync | Real-time relay synchronization | examples/cloud-sync/ | | Simple App | Minimal schema usage | examples/simple-app/ | | Reactive Counter | Framework-agnostic reactive engine | examples/reactive-counter/ |

Browse all examples in examples/ and src/examples/.

Documentation

| Resource | Link | |---|---| | Getting Started | GETTING_STARTED.md | | Framework Architecture | FRAMEWORK.md | | Core API Reference | docs/core/praxis-core-api.md | | Extending Praxis | docs/core/extending-praxis-core.md | | Svelte Integration | docs/guides/svelte-integration.md | | CodeCanvas Guide | docs/guides/canvas.md | | Decision Ledger | docs/decision-ledger/DOGFOODING.md | | Tutorials | docs/tutorials/ | | Migration from 1.x | MIGRATION_GUIDE.md | | Roadmap | ROADMAP.md | | 1.x Archive | docs/archive/1.x/ |

Development

npm install          # Install dependencies
npm run build        # Build (ESM + CJS via tsup)
npm test             # Run tests (Vitest)
npm run typecheck    # Type-check

Contributing

PRs and discussions welcome! See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue

License

MIT

Praxis — practical, provable, portable application logic.

Built with ❤️ by the Plures team