Cuel-X

A lightweight state management library that combines Phinix store, RootReducer, action registry, dispatcher factory, and cuel framework into a unified API. In ~250 lines of code (plus cuel for a total of ~1200 lines).

Quick Start

import {connect} from 'cuel-x';

const {store, dispatch, registerReducer} = connect({
    users: [],
    posts: [],
    settings: {theme: 'light'}
});

To make that import work in your browser without any build step, put this in your html:

<script type="importmap">
    {"imports": {
        "cuel/": "./node_modules/cuel/",
        "cuel-x": "./node_modules/cuel-x/index.mjs"
    }}
</script>

Core Components

• Phinix - Predictable state management with immutable updates
• RootReducer - Dependency-aware reducer management system
• Action Registry - Centralized action and dispatcher management
• Dispatcher Factory - Automatic dispatcher generation
• Connect - Unified API combining all components

API Reference

connect(rootReducerOrInitialState, dispatch?, initialState?)

Creates a connected state management system with two usage patterns.

Pattern 1: Custom Root Reducer

const {cuel, store} = connect(myReducer, myDispatch, initialState);

Pattern 2: Built-in RootReducer

const {
    cuel,

    action, 
    dispatch, 

    dispatcher, 
    dataDispatcher, 
    formDataDispatcher,
    srcDispatcher, 

    registerDispatcher,
    registerReducer,
 
    store,
} = connect(initialState);

Parameters

rootReducerOrInitialState (Function | Object)

• Function: Custom reducer function - returns {cuel, store}
• Object: Initial state - returns full API object

dispatch (Function, optional)

Custom dispatch function for use with custom root reducer. Ignored for initial state objects.

initialState (any, optional)

Initial state for the store.

Return Values

Custom Reducer Mode

{
    cuel: Function,   // Connected cuel instance
    store: Phinix     // Phinix store instance
}

Built-in Mode

{
    cuel: Function,                  // Connected cuel instance

    action: Object,                  // Action registry
    dispatch: Object,                // Dispatcher registry

    dispatcher: Function,            // Basic dispatcher
    srcDispatcher: Function,         // Source-parsing dispatcher
    dataDispatcher: Function,        // Data-parsing dispatcher
    formDataDispatcher: Function,    // FormData-parsing dispatcher

    registerDispatcher: Function,    // Register new actions
    registerReducer: Function,       // RootReducer.register()

    store: Phinix,                   // Phinix store
}

Usage Patterns

Custom Root Reducer

For complete control over state logic:

const myReducer = (state = {count: 0}, action) => {
    switch(action.type) {
        case 'INCREMENT': return {...state, count: state.count + 1};
        case 'DECREMENT': return {...state, count: state.count - 1};
        default: return state;
    }
};

myDispatch = (action) => {
    console.log('Dispatching:', action);
    // Custom dispatch logic
};

const {cuel, store} = connect(myReducer, myDispatch, {count: 0});

Built-in RootReducer

For quick setup with automatic reducer management:

const {
    store,
    registerReducer,
    dispatcher,
    action,
    dispatch,
    registerDispatcher
} = connect({
    users: [],
    posts: [],
    settings: {theme: 'light'}
});

// Register reducers
registerReducer('posts', 'ADD_POST', (state, {payload}) => [...state, payload]);
registerReducer('posts', 'RM_POST',  (state, {payload}) =>
    state.filter(p => p.id !== payload)
);

// Register actions
registerDispatcher({
    'ADD_POST': dispatcher,
    'REMOVE_POST': dispatcher
});

// Use dispatchers
dispatch.addPost({id: 1, title: 'Hello'});
dispatch.removePost(1);

... or have the dispatchers automatically called by cuel's connect.

Integration Features

Action Registry

Automatic action naming and dispatcher management:

registerDispatcher({
    SET_USER:        dataDispatcher(tranformData),
    UPDATE_SETTINGS: srcDispatcher,
    justDispatch, // /^A-Z_]+$/ is interpreted as action name, else dispatcher
});
registerDispatcher('JUST_AN_ACTION');

function tranformData(dispatch, data) {
    dispatch({
        givenName: data.name,
        personalEmail: data.email,
    });
}

function justDispatch(data) {
    store.dispatch({type: action.JUST_AN_ACTION, payload: data});
}

// Actions: {SET_USER: 'SET_USER', UPDATE_SETTINGS: 'UPDATE_SETTINGS', JUST_AN_ACTION: 'JUST_AN_ACTION'}
// Dispatch: {setUser: fn, updateSettings: fn, justDispatch: fn}

Dispatcher Factory

Cuel's connect will always pass a dispatch's source element and the data provided with the dispatch, if any. In many cases, the data will be an Event-object, if the event is directly connected from the DOM to a dispatcher. An elegant pattern is dispatching an SubmitEvent.

Since cuel elements have proxy properties that reach directly into the DOM, a reducer may want to read data directly from e.g. input elements in the DOM. In that case you may want to use the srcDispatcher function, which will extract the source element from the payload.

A cleaner pattern would be using the formDataDispatcher function, which will extract the form data from the SubmitEvent object. Then the reducer will not interact directly with the DOM, but with a plain object extracted from the form data.

When a reducer should parse an Event object, it should use the dataDispatcher function, which will extract the data from the payload. Another use case is when a method in the cuel element triggers the dispatch with custom data generated there.

Payload parsing strategies:

dispatcher('ACTION')({payload: {src: element, data: any}}); // Direct payload
srcDispatcher('ACTION')({payload: element});                // Extracts src
dataDispatcher('ACTION')({payload: any});                   // Extracts data
formDataDispatcher('ACTION')({payload: {...formData}});     // Extracts form data

To each of these you can also pass a function that will be called with a callback for dispatching the configured action and with the extracted data. See transformData example above.

Use cases:

• Transforming data before dispatching
• Validating data before dispatching
• Combining multiple dispatchers
• Any side effects (keep reducers pure)

Cuel Integration

Connected to cuel framework for data binding:

cuel('my-component', {}, {
    connect: [
        'givenName',
        'personalEmail:email',
        'setUser()', // Automatic data binding
    ],
    template: `
        <form !submit=setUser>
            <input .value=givenName name="name" />
            <input .value=email name="email" />
            <button type="submit">Update</button>
        </form>
    `,
});