How mlanza/atomic works
Project type and purpose
• This is a JavaScript library (“Atomic”) that brings Clojure-style protocols and functional programming facilities to JavaScript without a transpilation step.
• Its purpose is to supply a “functional core / imperative shell” architecture, offering:
• a core of pure functions and protocols in src/core
• integrations with the DOM in src/dom
• a shell for side-effects, FRP signals, and command buses in src/shell
• optional immutable-data helpers in src/immutables
• a thin CLI/command registry in agents and dist/cmd.js
• The README shows how library consumers write application‐specific code on top of these pieces.
File structure
• Top-level:
• src/ contains the module source broken into four sub-packages: core, dom, immutables, shell
• dist/ holds production bundles: atomic_/core.js, dom.js, shell.js, plus cmd.js and immutable.js
• agents/ and docs/ provide supplemental guidance and examples of usage, testing, and advanced patterns
• build config: rollup.config.js, .babelrc, package.json
• tests/ contains a minimal browser‐based smoke test
• Patterns & architectural cues:
• Layered modular design—foundation protocols/types → core behaviors → shell (effects) & dom (rendering)
• Protocol–based extension points (a microkernel style)
• Transducers, signals, atoms, command registry as core primitives
• No server, database, or network layer—pure library for front-end and CLI use
README for additional insights
• Emphasis on FCIS (Functional Core Imperative Shell) pattern
• Core modules are purely functional; shell modules orchestrate real‐world effects
• Consumers write a “domain” module (their own pure functions) and a “main” module (their shell)
• Shows how modules interconnect: import core, shell, dom, then wire up $.atom, $.sub, $.on
a. Main components
• Core Layer (src/core)
• Immutables Layer (src/immutables)
• Shell Layer (src/shell)
• DOM Layer (src/dom)
• Command Layer (dist/cmd.js + agents)
• Bundles (dist/atomic_/*, dist/immutable.js)
• Consumer Domain (illustrated in README as user code: sokoban.js, main.js)
b. Relationships & data flow
• Core defines protocols and pure behaviors → consumed by Immutables, DOM, and Shell
• Shell uses Core to create atoms, signals, event buses → exposes side-effects API
• DOM uses Core and Shell signals to render and patch the browser view
• Command layer (cmd.js) sits on top of Shell, wires domain code into the system
• Dist folder outputs are packaged ES modules for direct browser import
• Consumer code calls into these bundles, driving state and rendering
c. Architectural patterns & principles
• Layered abstraction: protocols/types → behaviors → effects → rendering
• Functional core / imperative shell (FCIS)
• Protocol‐based dynamic extension (microkernel/pluggable)
• Point-free pipelines and transducers as composition primitives
• Signal/atom/event bus as FRP backbone
d. Key technologies & libraries
• Native ES modules, Rollup for bundling
• No transpiler—relies on modern browsers’ module support
• Transducers (in Core)
• Clojure-inspired protocols API (custom implementation)
• DOM patching & event subscription primitives
• Immutable-data adapters but optional