___ ___
/\ \ /\ \
/::\ \ /::\ \
/:/\:\ \ /:/\:\ \ CAUSALOOP
/:/ \:\ \ /:/ \:\ \ DETERMINISM = TRUE
/:/__/ \:\__\ /:/__/ \:\__\ ENTROPY = 0.0%
\:\ \ /:/ / \:\ \ /:/ / [LIVE-SRC]
\:\ /:/ / \:\ /:/ /
\:\/:/ / \:\/:/ /
\::/ / \::/ /
\/__/ \/__/
In modern web development, managing state and side effects often leads to unpredictable "butterfly effects" in your UI. Causaloop provides the architectural gravity to keep your app grounded.
By strictly enforcing The Elm Architecture (TEA) in TypeScript, Causaloop ensures that your business logic remains pure, your side effects are manageable data, and your bugs are 100% reproducible via time-travel replay.
- 📦 Effects & Subscriptions as Data: One-shot side effects (Fetch, Workers) are pure data structures. Ongoing processes (Timers, Animation Frames) are declarative subscriptions managed by the runtime.
- 📼 Deterministic Replay: Any UI state can be reconstructed exactly from a serializable message log. Non-deterministic operations (Time, Random) are provided via a managed context and recorded for perfect playback.
- 🛡️ Atomic Processing: Messages are processed one at a time via a FIFO queue, eliminating race conditions by design.
Causaloop is built on a unidirectional data flow with two managed side-effect channels: Effects for one-shot operations and Subscriptions for ongoing processes.
graph TD
UI[View/UI] -- dispatch Msg --> D[Dispatcher]
D -- Msg --> Q[FIFO Queue]
Q -- Msg --> U[Update Function]
U -- next Model --> D
U -- Effects --> D
D -- Commit --> S[Snapshot]
S --> UI
D -- Run Effects --> R[Platform Runners]
R -- result as Msg --> D
D -- Reconcile --> SUB[Subscriptions]
SUB -- subscribe/unsubscribe --> R
| Effects | Subscriptions | |
|---|---|---|
| Purpose | One-shot async operations | Ongoing processes |
| Lifecycle | Fire-and-forget | Runtime-managed start/stop |
| Examples | Fetch, Worker compute | Timer ticks, animation frames |
| Restore | Not restarted (state normalized) | Automatically resumed |
| Emitted by | update() return value |
subscriptions(model) function |
Causaloop is split into three primary layers, ensuring strict separation of concerns.
| Package | Description | Status |
|---|---|---|
| @causaloop/core | Platform-agnostic engine. Dispatcher, Subscriptions, Replay, and VDOM types. | Stable |
| @causaloop/platform-browser | Browser runners (Fetch, Workers, Timer, RAF) and Snabbdom renderer. | Stable |
| @causaloop/app-web | Demo application showcasing search, workers, subscriptions, and devtools. | Ready |
We don't just claim stability; we prove it. Causaloop is continuously benchmarked against extreme conditions:
- ⚡ High Throughput: The Core Dispatcher handles over 1,000,000 messages/sec in CPU-bound stress tests.
- 🕒 Timer Storms: The Browser Runner manages 1,000+ concurrent timers with zero starvation.
- 🐒 Monkey Testing: Chaotic E2E simulations verify resilience against rapid-fire user interactions and navigation spam.
- 📼 Replay Torture: Verified deterministic reconstruction of session state across 100,000+ log entries.
- 🔄 Session Restore: Subscriptions automatically resume after replay, eliminating stuck "phantom pending" states.
Causal Factory is a high-performance industrial logistics simulation built to stress test Causaloop.
It demonstrates:
- Massive Entity Scaling: 100,000+ autonomous bots moving in a single tick.
- Complex Logistics: Dynamic supply/demand re-routing and state transition bursts.
- The "Live-Link" Architecture: A developer setup that hard-wires the game directly to the engine source for zero-build, instant-feedback development.
To clone the engine and the showcase game in the required sister-folder structure:
git clone https://github.com/bitkojine/causal-factory.git causal-factory && git clone https://github.com/bitkojine/causaloop.git causaloop-repo && cd causaloop-repo && pnpm install && cd ../causal-factory && pnpm install && pnpm run devpnpm install
pnpm run build
pnpm run devpnpm test # Unit & Integration tests
pnpm test:stress # Performance & Race condition stress tests
pnpm test:e2e # Playwright E2E suite
pnpm lint # ESLint boundary enforcement- Monorepo Foundation: pnpm workspaces + TS Project References.
- Browser Runner: Robust Fetch, Timers, RAF, and Workers.
- Subscriptions: Declarative lifecycle for ongoing processes (Timer, Animation, Stress).
- Session Restore: Automatic subscription resumption + state normalization.
- Stress Suite: 1M+ throughput verification.
- Context Injection: Updates receive explicit
UpdateContextfor deterministicnow()andrandom(). - SSR Support: Node.js effect runners for server-side rendering.
- Worker Validation: Add
zodschema validation for worker messages. - CLI Tool:
create-causaloop-appscaffolder for easy setup.
This repository enforces a radical "No Comments" rule for all source code.
The codebase is intended to be purely functional and readable without inline narratives.
This rule is strictly enforced by both local and remote guardrails:
- Local Pre-Push Hook: A git hook runs
scripts/check-thinking-comments.shbefore you can push. - CI Pipeline: The GitHub Actions workflow fails if any comments (
//or/*) are detected inpackages/*/src.
If you are an AI coding assistant working on this repo, follow these instructions precisely:
- ❌ Low-Value Thoughts: "I think...", "Maybe...", "TODO:..." -> Do NOT write these.
- ✅ High-Value Insights: Architectural decisions, complex invariants, or critical "gotchas". -> Document these in
docs/notes/ideas.md.
Do not pollute the source code with your internal monologue.
Contributions are welcome! Please review our ARCHITECTURE.md to understand the project laws before submitting a PR.
MIT © bitkojine