@nateabele/use-app-state

A React state management library using immutable event-based updates powered by Ramda.

Installation

npm install @nateabele/use-app-state

Usage

Basic Hook Usage

import { useAppState, Events } from '@nateabele/use-app-state';

function App() {
  const [state, emit] = useAppState({
    user: { name: '', email: '' },
    items: []
  });

  return (
    <div>
      <input
        value={state.user.name}
        onChange={e => emit(Events.set(['user', 'name'], e.target.value))}
      />
      <button onClick={() => emit(Events.append(['items'], { id: Date.now() }))}>
        Add Item
      </button>
    </div>
  );
}

Scoped Emitters

Emitters can be scoped to a path, making nested components cleaner:

function UserForm({ emit }) {
  const scopedEmit = emit.scope(['user']);

  return (
    <input onChange={e => scopedEmit(Events.set(['name'], e.target.value))} />
  );
}

Configuration Options

const [state, emit, controls] = useAppState(initialState, {
  log: true,           // Log all events to console
  expose: 'appState',  // Expose state to window.appState for debugging
  onEvent: (event, before, after) => {
    // Subscribe to all state changes
  }
});

Events

| Event | Description | Example | |-------|-------------|---------| | Events.set(path, value) | Set a value at path | Events.set(['user', 'name'], 'John') | | Events.merge(path, obj) | Merge object at path | Events.merge(['user'], { name: 'John' }) | | Events.append(path, value) | Append to array | Events.append(['items'], newItem) | | Events.push(path, index, value) | Insert at index | Events.push(['items'], 0, newItem) | | Events.pull(path, index, count?) | Remove from array/object | Events.pull(['items'], 2, 1) | | Events.drop(path, key) | Remove key from object | Events.drop(['user'], 'tempField') | | Events.batch(events[]) | Batch multiple events | Events.batch([...]) | | Events.noOp | No operation | Events.noOp |

Alternative: Non-Hook Initialization

For apps that need direct control over rendering:

import { init } from '@nateabele/use-app-state';

const app = init(App, document.getElementById('root'), initialData);

app.onEvent((event, before, after) => {
  console.log('State changed:', event.name);
});

app.render();

License

MIT