Skip to content

Latest commit

 

History

History
382 lines (305 loc) · 7.3 KB

ARCHITECTURE.md

File metadata and controls

382 lines (305 loc) · 7.3 KB

Stateless-JS Architecture

A universal state management library with NO wrappers, NO actions, NO reducers, NO complexity.

🎯 Core Philosophy

Simple. Universal. Direct.

  • ✅ No Wrappers - Direct framework integration
  • ✅ No Actions - Direct state updates
  • ✅ No Reducers - Functional state updates
  • ✅ No Providers - No context hell
  • ✅ No Boilerplate - Just create and use

🏗️ Architecture Overview

graph TB
    CR[Core Registry]
    SM[State Map]
    SS[State Setters]
    SV[State Values]

    AA[Angular Adapter]
    RA[React Adapter]
    SA[Svelte Adapter]
    VA[Vue Adapter]
    UA[Universal Adapter]

    AC[Angular Components]
    RC[React Components]
    SC[Svelte Components]
    VC[Vue Components]
    VJ[Vanilla JS]

    CR --> SM
    CR --> SS
    CR --> SV

    RA --> CR
    VA --> CR
    SA --> CR
    AA --> CR
    UA --> CR

    RC --> RA
    VC --> VA
    SC --> SA
    AC --> AA
    VJ --> UA

    style CR fill:#e1f5fe,color:#000
    style SM fill:#f3e5f5,color:#000
    style SS fill:#e8f5e8,color:#000
    style SV fill:#fff3e0,color:#000
Loading

🔄 State Lifecycle

sequenceDiagram
    participant App as Application
    participant CR as Core Registry
    participant SM as State Map
    participant Sub as Subscribers

    App->>CR: createStateless('counter', 0)
    CR->>SM: Check if 'counter' exists
    SM-->>CR: Not found
    CR->>SM: Create new state entry
    CR->>CR: Create setter & value
    CR-->>App: [setter, value]

    App->>CR: setter(current => current + 1)
    CR->>SM: Update state value
    CR->>Sub: Notify all subscribers
    Sub-->>App: Trigger re-render/update
Loading

🌐 Universal State Sharing

graph LR
    subgraph "React App"
        RC1[Component A]
        RC2[Component B]
    end

    subgraph "Vue App"
        VC1[Component C]
        VC2[Component D]
    end

    subgraph "Svelte App"
        SC1[Component E]
        SC2[Component F]
    end

    subgraph "Angular App"
        AC1[Component G]
        AC2[Component H]
    end

    subgraph "Vanilla JS"
        VJ1[Module X]
        VJ2[Module Y]
    end

    CR[Single Registry]
    SM[State Map]
    S1[State: 'user']
    S2[State: 'counter']

    RC1 --> S1
    RC2 --> S2
    VC1 --> S1
    VC2 --> S2
    SC1 --> S1
    SC2 --> S2
    AC1 --> S1
    AC2 --> S2
    VJ1 --> S1
    VJ2 --> S2

    S1 --> CR
    S2 --> CR
    CR --> SM

    style S1 fill:#e8f5e8,color:#000
    style S2 fill:#e8f5e8,color:#000
    style CR fill:#e1f5fe,color:#000
Loading

🔷 Angular Integration

graph TB
    subgraph "Angular Component"
        AC[useAngularStateless]
        AS[Angular Signal]
        AI[Injectable Service]
    end

    subgraph "Angular Adapter"
        AAS[Angular Subscribers Map]
        NS[notifyAngularSubscribers]
    end

    subgraph "Core Registry"
        CR[Core Registry]
        SM[State Map]
    end

    AC --> AS
    AC --> AI
    AC --> CR
    CR --> SM

    AC --> NS
    NS --> AAS
    AAS --> AS

    style AC fill:#dd0031,color:#fff
    style AAS fill:#dd0031,color:#fff
    style CR fill:#e1f5fe,color:#000
Loading

How it works:

  1. useAngularStateless calls useStateless (core)
  2. Creates Angular WritableSignal for reactivity
  3. Sets up subscriber to update signal value
  4. Supports both service injection and standalone function approaches

⚛️ React Integration

graph TB
    subgraph "React Component"
        RC[useReactStateless]
        FU[forceUpdate]
        EU[useEffect]
    end

    subgraph "React Adapter"
        RS[React Subscribers Map]
        NS[notifyReactSubscribers]
    end

    subgraph "Core Registry"
        CR[Core Registry]
        SM[State Map]
    end

    RC --> EU
    EU --> RS
    EU --> FU
    RC --> CR
    CR --> SM

    RC --> NS
    NS --> RS
    RS --> FU

    style RC fill:#61dafb,color:#000
    style RS fill:#61dafb,color:#000
    style CR fill:#e1f5fe,color:#000
Loading

How it works:

  1. useReactStateless calls useStateless (core)
  2. Sets up useEffect to subscribe to state changes
  3. Uses forceUpdate to trigger React re-renders

🟠 Svelte Integration

graph TB
    subgraph "Svelte Component"
        SC[useSvelteStateless]
        SW[Svelte Writable Store]
        SU[Store Subscription]
    end

    subgraph "Svelte Adapter"
        SS[Svelte Subscribers Map]
        NS[notifySvelteSubscribers]
    end

    subgraph "Core Registry"
        CR[Core Registry]
        SM[State Map]
    end

    SC --> SW
    SC --> SU
    SC --> CR
    CR --> SM

    SC --> NS
    NS --> SS
    SS --> SW

    style SC fill:#ff3e00,color:#fff
    style SS fill:#ff3e00,color:#fff
    style CR fill:#e1f5fe,color:#000
Loading

How it works:

  1. useSvelteStateless calls useStateless (core)
  2. Creates Svelte writable store for reactivity
  3. Sets up subscriber to update store value

🟢 Vue Integration

graph TB
    subgraph "Vue Component"
        VC[useVueStateless]
        VR[Vue Ref]
        OU[onUnmounted]
    end

    subgraph "Vue Adapter"
        VS[Vue Subscribers Map]
        NS[notifyVueSubscribers]
    end

    subgraph "Core Registry"
        CR[Core Registry]
        SM[State Map]
    end

    VC --> VR
    VC --> OU
    VC --> CR
    CR --> SM

    VC --> NS
    NS --> VS
    VS --> VR

    style VC fill:#4fc08d,color:#000
    style VS fill:#4fc08d,color:#000
    style CR fill:#e1f5fe,color:#000
Loading

How it works:

  1. useVueStateless calls useStateless (core)
  2. Creates Vue ref for reactivity
  3. Sets up subscriber to update ref value

🧠 Memory Management

graph LR
    SC[createStateless]
    SE[State Entry]
    SS[Subscribers Set]

    SU[useStateless]
    SV[State Value]
    SD[dispose method]

    CD[Component Unmount]
    CS[Clear Subscribers]
    CR[Remove from Registry]

    SC --> SE
    SE --> SS
    SU --> SV
    SV --> SD

    CD --> CS
    CS --> CR
    SD --> CS

    style SE fill:#e8f5e8,color:#000
    style SV fill:#fff3e0,color:#000
    style CS fill:#ffebee,color:#000
Loading

Automatic Cleanup:

  • Component unmounts → Subscribers cleared
  • State disposed → Registry cleaned

🔄 Data Flow (No Actions)

sequenceDiagram
    participant C as Component
    participant S as State Setter
    participant R as Registry
    participant M as State Map
    participant Sub as Subscribers

    C->>S: setCount(current => current + 1)
    S->>R: Update state
    R->>M: Get state entry
    M-->>R: Return entry
    R->>R: Execute updater function
    R->>M: Update state value
    R->>Sub: Notify all subscribers
    Sub-->>C: Trigger re-render

    Note over C,Sub: Direct update, no actions, no reducers!
Loading

🚀 Performance Characteristics

graph LR
    subgraph "O(1) Operations"
        GM[Map.get]
        SM[Map.set]
        HM[Map.has]
    end

    subgraph "O(n) Operations"
        NS[Notify Subscribers]
        CS[Clear Subscribers]
    end

    subgraph "Memory"
        SS[Single Registry]
        MS[Minimal Overhead]
        AC[Automatic Cleanup]
    end

    GM --> NS
    SM --> NS
    HM --> CS

    style GM fill:#e8f5e8,color:#000
    style SM fill:#e8f5e8,color:#000
    style HM fill:#e8f5e8,color:#000
    style NS fill:#fff3e0,color:#000
    style CS fill:#fff3e0,color:#000
Loading

Performance:

  • ✅ O(1) state access (Map lookup)
  • ✅ O(n) notifications (only active subscribers)