### Complete RxBeach Example

Source: https://github.com/ardoq/rxbeach/blob/master/docs/README.md

This example demonstrates a full RxBeach application flow, including action creation, state reduction, side-effect handling, and UI connection. It requires understanding of RxJs, state management patterns, and component-based UI development.

```javascript
enum Module { DASHBOARD, … }
// action creator
const showModule = actionCreator<Module>("[navigation] show module");
/* When invoked , will produce st. like:
const action = {
  type: Symbol("[navigation] show module"),
  payload: Module.DASHBOARD,
  meta: {
    dispatchedAt: new Date(),
    dispatchedBy: new Error()
  }
};
*/

// state
type NavigationState = { selectedModule: Module; };
const defaultNavigationState: NavigationState = {  selectedModule: Module.DASHBOARD };

// reducer
const handleShowModule = reducer(
  showModule,  // could also be another stream
  (state: NavigationState, selectedModule) => ({
    ...state,
    selectedModule // could also do some calculations / transformations on it
}));

// reduced state stream
const reducers = [handleShowModule];
const navigation$ = persistentReducedStream(
  'navigation$',
  defaultNavigationState,
  reducers
);
// persistent reduced streams are started by the state stream registry
stateStreamRegistry.startReducing();
// (Side-)effects via routines:
const logModuleChange = routine(
  ofType(showModule), // filter
  extractPayload(),
  tap(module => console.log(`Showing module ${module}`))
);
subscribeRoutine(navigation$, logModuleChange)

// UI
type ViewModel = NavigationState;
const View = ({ selectedModule }: ViewModel) => 
  <p>Navigating to: {selectedModule} 
     <button onClick={dispatchAction(showModule(DASHBOARD))} />
  </p>;
const ConnectedView = connect(View, navigation$);
```

--------------------------------

### Start Reduced State Stream

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/state-streams/reduced-state-streams.md

Initiate the reduction process for a state stream. This can be done via the stream's `.startReducing` method or through the global `stateStreamRegistry`.

```typescript
import { stateStreamRegistry } from 'rxbeach';

stateStreamRegistry.startReducing(action$);
```

--------------------------------

### Define a Routine with RxJs Operators

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/routines.md

Define a routine by piping RxJs operators. This example filters for a specific action type and logs its payload. Routines are technically RxJs pipes, and `routine` can be thought of as a wrapper around `action$.pipe`.

```typescript
const logModuleChange = routine(
  ofType(showModule),
  extractPayload(),
  tap(module => console.log(`Showing module ${module}`)) 
);
```

--------------------------------

### ObservableState wrapper with synchronous state access

Source: https://context7.com/ardoq/rxbeach/llms.txt

The `ObservableState` class wraps a source Observable in a `BehaviorSubject`, providing synchronous `.state` access, `.connect()` to start subscription, and `.unsubscribe()` to tear down.

```typescript
import { ObservableState } from 'rxbeach';
import { interval } from 'rxjs';
import { map } from 'rxjs/operators';

const source$ = interval(1000).pipe(map(n => ({ tick: n })));

const clock$ = new ObservableState('clock$', source$, { tick: -1 });

console.log(clock$.state); // { tick: -1 }  — synchronous before connect

clock$.connect(); // starts consuming source$

// Subscribe as a normal Observable
const sub = clock$.subscribe(v => console.log('Tick:', v.tick));

setTimeout(() => {
  console.log('Current tick:', clock$.state.tick); // synchronous read
  clock$.unsubscribe(); // tears down; further access throws
}, 3500);
```

--------------------------------

### Verify and Build RxBeach Package

Source: https://github.com/ardoq/rxbeach/blob/master/README.md

Before publishing, verify that the package works by running linting, building, and testing. This ensures the code is clean and functional.

```bash
yarn lint && yarn build && yarn test
```

--------------------------------

### Configure Docsify for RxBeach

Source: https://github.com/ardoq/rxbeach/blob/master/docs/index.html

This snippet shows how to configure Docsify, a documentation generator, for the RxBeach project. It sets the repository URL and enables the sidebar.

```javascript
window.$docsify = {
  name: "🏖️ RxBeach",
  repo: "https://github.com/ardoq/rxbeach",
  loadSidebar: true,
  // subMaxLevel: 2 // Show sub headings for current article in sidebar
};
```

--------------------------------

### Using an Action Creator

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/actions.md

Demonstrates how to invoke an action creator with a payload to generate a complete action object.

```typescript
showModule(Module.DASHBOARD);
```

--------------------------------

### Bump Version with Standard Version

Source: https://github.com/ardoq/rxbeach/blob/master/README.md

Bump the package version using the 'standard-version' tool. This command automates version bumping and changelog generation.

```bash
yarn standard-version
```

--------------------------------

### connect / connectInstance

Source: https://context7.com/ardoq/rxbeach/llms.txt

Higher-order components for connecting React components to RxBeach streams. `connect` subscribes a component to a shared stream, feeding values as props. `connectInstance` creates a new stream per component mount using a factory, enabling per-instance state.

```APIDOC
## `connect` / `connectInstance` — Connect React components to streams (rxbeach/react)

`connect` is a higher-order component that subscribes a React component to a stream and feeds the emitted values as props, re-rendering on each emission. `connectInstance` creates a new stream per component mount using a factory, enabling per-instance state.

```typescript
import React from 'react';
import { connect, connectInstance } from 'rxbeach/react';
import { user$, createItemStream } from './streams';

// --- connect: global shared stream ---
type UserBadgeProps = { id: string; name: string; avatar: string };

const UserBadge = ({ id, name, avatar }: UserBadgeProps) => (
  <div className="badge">
    <img src={avatar} alt={name} />
    <span>{name}</span>
  </div>
);

// user$ must emit Partial<UserBadgeProps>
export const ConnectedUserBadge = connect(UserBadge, user$);
// Usage: <ConnectedUserBadge /> — no props needed, all come from user$

// --- connectInstance: per-mount stream factory ---
type ItemProps = { title: string; status: string };

const ItemCard = ({ title, status }: ItemProps) => (
  <div>{title}: {status}</div>
);

// createItemStream receives a unique instance name per mount
export const ConnectedItemCard = connectInstance(
  ItemCard,
  (instance) => createItemStream(instance)
);
// Usage: <ConnectedItemCard /> — each mount gets its own stream
```
```

--------------------------------

### Create per-instance streams with connectInstance

Source: https://context7.com/ardoq/rxbeach/llms.txt

Utilize `connectInstance` to create a new stream for each component mount using a factory function. This enables per-instance state management. The factory receives a unique instance name.

```typescript
import React from 'react';
import { connect, connectInstance } from 'rxbeach/react';
import { user$, createItemStream } from './streams';

// --- connectInstance: per-mount stream factory ---
type ItemProps = { title: string; status: string };

const ItemCard = ({ title, status }: ItemProps) => (
  <div>{title}: {status}</div>
);

// createItemStream receives a unique instance name per mount
export const ConnectedItemCard = connectInstance(
  ItemCard,
  (instance) => createItemStream(instance)
);
// Usage: <ConnectedItemCard /> — each mount gets its own stream
```

--------------------------------

### Push Changes with Tags

Source: https://github.com/ardoq/rxbeach/blob/master/README.md

Push your local changes to the remote repository, including any new tags created during the version bumping process. Use '--follow-tags' to ensure tags are pushed.

```bash
git push --follow-tags
```

--------------------------------

### Publish RxBeach Package to NPM

Source: https://github.com/ardoq/rxbeach/blob/master/README.md

Publish the new version of the RxBeach package to NPM. When prompted, simply hit enter to use the version number already determined by 'standard-version'.

```bash
yarn publish
```

--------------------------------

### Defining an Action Creator

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/actions.md

Illustrates how to define an action creator using a generic function to generate action objects with a specific type and payload.

```typescript
enum Module {
  DASHBOARD
}
const showModule = actionCreator<Module>("[navigation] show module");
```

--------------------------------

### Type Utilities

Source: https://context7.com/ardoq/rxbeach/llms.txt

Compile-time type helpers for working with RxBeach's type system, including `ExtractPayload`, `InferPayloadFromActionCreator`, and `Observed`, without needing to import or duplicate payload types.

```APIDOC
## Type Utilities — `ExtractPayload`, `InferPayloadFromActionCreator`, `Observed`

Compile-time helpers for working with RxBeach's type system without importing or duplicating payload types.

```typescript
import type {
  ExtractPayload,
  InferPayloadFromActionCreator,
  Observed,
} from 'rxbeach';
import { actionCreator, persistentReducedStream } from 'rxbeach';

const setItems = actionCreator<string[]>('[list] set items');
const user$    = persistentReducedStream('user$', { name: '' }, []);

// Extract payload type from an action creator
type ItemsPayload = ExtractPayload<typeof setItems>;
// => string[]

// Infer payload (preferred — handles both void and payload actions)
type InferredPayload = InferPayloadFromActionCreator<typeof setItems>;
// => string[]

// Infer the emitted type from an Observable or ObservableState
type UserState = Observed<typeof user$>;
// => { name: string }

// Practical usage: typed reducer without importing the state type
function handleSetItems(state: { items: ItemsPayload }, items: ItemsPayload) {
  return { ...state, items };
}
```
```

--------------------------------

### Create a Reducer for Show Module Action

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/reducers.md

Creates a reducer function that updates the selected module in the navigation state when a showModule action is dispatched. The reducer is a pure function that takes the current state and payload to return the new state.

```typescript
const handleShowModule = reducer(showModule, (state: NavigationState, payload) => {
  return {
    ...state,
    selectedModule: payload
  };
});
```

--------------------------------

### RxBeach Type Utilities for compile-time safety

Source: https://context7.com/ardoq/rxbeach/llms.txt

Utilize compile-time helpers like `ExtractPayload`, `InferPayloadFromActionCreator`, and `Observed` to work with RxBeach's type system without duplicating payload types. `InferPayloadFromActionCreator` is preferred for its ability to handle both void and payload actions.

```typescript
import type {
  ExtractPayload,
  InferPayloadFromActionCreator,
  Observed,
} from 'rxbeach';
import { actionCreator, persistentReducedStream } from 'rxbeach';

const setItems = actionCreator<string[]>('[list] set items');
const user$    = persistentReducedStream('user$', { name: '' }, []);

// Extract payload type from an action creator
type ItemsPayload = ExtractPayload<typeof setItems>;
// => string[]

// Infer payload (preferred — handles both void and payload actions)
type InferredPayload = InferPayloadFromActionCreator<typeof setItems>;
// => string[]

// Infer the emitted type from an Observable or ObservableState
type UserState = Observed<typeof user$>;
// => { name: string }

// Practical usage: typed reducer without importing the state type
function handleSetItems(state: { items: ItemsPayload }, items: ItemsPayload) {
  return { ...state, items };
}
```

--------------------------------

### Connect React components to streams with connect

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use the `connect` higher-order component to subscribe a React component to a stream, feeding emitted values as props. The component re-renders on each emission. The stream must emit values compatible with the component's props.

```typescript
import React from 'react';
import { connect, connectInstance } from 'rxbeach/react';
import { user$, createItemStream } from './streams';

// --- connect: global shared stream ---
type UserBadgeProps = { id: string; name: string; avatar: string };

const UserBadge = ({ id, name, avatar }: UserBadgeProps) => (
  <div className="badge">
    <img src={avatar} alt={name} />
    <span>{name}</span>
  </div>
);

// user$ must emit Partial<UserBadgeProps>
export const ConnectedUserBadge = connect(UserBadge, user$);
// Usage: <ConnectedUserBadge /> — no props needed, all come from user$
```

--------------------------------

### Collect and Subscribe Multiple Routines

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/routines.md

When subscribing multiple routines, collect them using `collectRoutines` before passing them to `subscribeRoutine`. This allows for efficient subscription management.

```typescript
const routines = collectRoutines(logModuleChange, someRoutine, someOtherRoutine);
subscribeRoutine(action$, routines);
```

--------------------------------

### Create Tap Handlers with `tapRoutine`

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `tapRoutine` as a shorthand for creating routines that filter actions by creator, extract the payload, and execute a side-effect function. It simplifies common tap handler patterns without boilerplate.

```typescript
import { actionCreator, tapRoutine, subscribeRoutine, action$, dispatchAction } from 'rxbeach';

const showNotification = actionCreator<{ message: string; level: 'info' | 'error' }>(
  '[ui] show notification'
);
const closeDialog = actionCreator('[ui] close dialog');

// With payload
const notifyRoutine = tapRoutine(
  showNotification,
  ({ message, level }) => console.log(`[${level.toUpperCase()}] ${message}`)
);

// Without payload
const closeRoutine = tapRoutine(closeDialog, () => console.log('Dialog closed'));

subscribeRoutine(action$, notifyRoutine);
subscribeRoutine(action$, closeRoutine);

dispatchAction(showNotification({ message: 'Saved!', level: 'info' }));
// => [INFO] Saved!
dispatchAction(closeDialog());
// => Dialog closed
```

--------------------------------

### Shorter Reducer Definition

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/reducers.md

A more concise way to define the same reducer by leveraging object shorthand for the selectedModule property.

```typescript
const handleShowModule = reducer(showModule, (state: NavigationState, selectedModule) => ({
  ...state,
  selectedModule
}));
```

--------------------------------

### Configure Git to Ignore Style Changes

Source: https://github.com/ardoq/rxbeach/blob/master/README.md

Configure Git to use the .git-blame-ignore-revs file to ignore commits with style changes in git blame. This helps maintain a cleaner blame history.

```bash
git config blame.ignoreRevsFile .git-blame-ignore-revs
```

--------------------------------

### Merge Dependabot PRs

Source: https://github.com/ardoq/rxbeach/blob/master/README.md

To satisfy Ardoq's review policy, merge Dependabot PRs by approving the PR with the message '@dependabot merge'. This is used to keep dependencies up to date.

```bash
@dependabot merge
```

--------------------------------

### Global Action Bus with action$ and dispatchAction

Source: https://context7.com/ardoq/rxbeach/llms.txt

Subscribe to the shared `action$` Observable to observe all dispatched actions. Use `dispatchAction` to push new actions onto the stream, optionally providing a namespace to scope the action for component isolation.

```typescript
import { action$, dispatchAction, actionCreator } from 'rxbeach';
import { tap } from 'rxjs/operators';

const navigate = actionCreator<string>('[router] navigate');

// Subscribe directly to the raw action stream
const sub = action$.pipe(
  tap(action => console.log('Action dispatched:', action.type))
).subscribe();

// Dispatch a plain action
dispatchAction(navigate('/dashboard'));
// => Action dispatched: [router] navigate

// Dispatch with a namespace (scopes the action for component isolation)
dispatchAction(navigate('/settings'), 'sidebar-instance-1');
// => action.meta.namespace === 'sidebar-instance-1'

sub.unsubscribe();
```

--------------------------------

### Create a ref-counted state stream with `reducedStream`

Source: https://context7.com/ardoq/rxbeach/llms.txt

Builds a hot, ref-counted Observable that scans the global `action$` with the provided reducers and replays the latest state to new subscribers. Resets to `initialState` when the subscriber count drops to zero.

```typescript
import { actionCreator, reducer, reducedStream, dispatchAction } from 'rxbeach';

type FilterState = { query: string; page: number };
const initial: FilterState = { query: '', page: 1 };

const setQuery = actionCreator<string>('[filter] set query');
const setPage  = actionCreator<number>('[filter] set page');

const handleQuery = reducer(setQuery, (s: FilterState, query) => ({ ...s, query, page: 1 }));
const handlePage  = reducer(setPage,  (s: FilterState, page)  => ({ ...s, page }));

// Stream resets when all subscribers unsubscribe
const filter$ = reducedStream('filter$', initial, [handleQuery, handlePage]);

const sub = filter$.subscribe(state => console.log('Filter state:', state));
// => Filter state: { query: '', page: 1 }  (emits initial immediately)

dispatchAction(setQuery('rxbeach'));
// => Filter state: { query: 'rxbeach', page: 1 }

dispatchAction(setPage(2));
// => Filter state: { query: 'rxbeach', page: 2 }

sub.unsubscribe(); // stream resets
```

--------------------------------

### Assemble Reducers into a Reduced Stream

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/reducers.md

Combines an array of reducers with a default state and a stream name to create a persistent reduced state stream. This stream listens to actions and applies the reducers to update its state.

```typescript
const reducers = [handleShowModule];

const navigation$ = persistentReducedStream(
  'navigation$',
  defaultNavigationState,
  reducers
);
```

--------------------------------

### Connect React Component to Stream

Source: https://github.com/ardoq/rxbeach/blob/master/docs/recipes/connected-components.md

Use the `connect` higher-order component to connect React components to streams. This ensures the view depends on a viewModel$ stream, not directly on application streams.

```typescript
type ViewModel = {
  number: number;
};

const View = ({ number }: ViewModel) => {
  return <p>Value: {number}</p>;
};

const ConnectedView = connect(View, viewModel$);
```

--------------------------------

### Scope Action Creators and Dispatchers with Namespaces

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `namespaceActionCreator` to wrap an action creator, ensuring all produced actions include a namespace in their `meta`. `namespaceActionDispatcher` wraps `dispatchAction` for automatic namespace stamping before dispatching.

```typescript
import {
  actionCreator, namespaceActionCreator, namespaceActionDispatcher,
  dispatchAction, action$
} from 'rxbeach';
import { tap } from 'rxjs/operators';

const selectItem = actionCreator<string>('[list] select item');

// Namespace-scoped creator (useful in component factories)
const sidebarSelectItem = namespaceActionCreator('sidebar', selectItem);
const action = sidebarSelectItem('item-42');
// => { type: '[list] select item', payload: 'item-42', meta: { namespace: 'sidebar' } }

// Namespace-scoped dispatcher
const sidebarDispatch = namespaceActionDispatcher('sidebar', dispatchAction);
sidebarDispatch(selectItem('item-99'));
// dispatches with meta.namespace === 'sidebar'

action$.pipe(
  tap(a => console.log(a.type, a.meta.namespace))
).subscribe();
```

--------------------------------

### Action Object Structure

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/actions.md

Defines the standard structure for an action object, including type, payload, and meta information.

```typescript
const action = {
  type: "[navigation] show module",
  payload: Module.DASHBOARD,
  meta: {
    dispatchedAt: new Date(),
    dispatchedBy: new Error()
  }
};
```

--------------------------------

### Define Stream Reducers

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/state-streams/reduced-state-streams.md

Use the `reducer` function to define how the stream state changes in response to other streams. Be mindful of initial emissions from the source stream.

```typescript
import { of } from 'rxjs';

type MyStreamState = { counter: number };
const increment$ = of([1, 2, 3]);
const otherState$ = null as any; // Imported from somewhere

const handleIncrementOf = reducer(
  increment$,
  ({ counter }: MyStreamState, count) => ({ counter: counter + count})
);

const handleIncrementByState = reducer(
  otherState$,
  (ourState: MyStreamState, otherState) => ({ ...ourState, ...otherState })
)
```

--------------------------------

### Define and Wire Side Effects with `routine` and `subscribeRoutine`

Source: https://context7.com/ardoq/rxbeach/llms.txt

Define side effects using `routine` and combine them with `collectRoutines`. Wire them to an action stream using `subscribeRoutine` for automatic error recovery. Routines are RxJS pipe compositions that react to actions.

```typescript
import {
  actionCreator, routine, subscribeRoutine, collectRoutines,
  action$, dispatchAction
} from 'rxbeach';
import { ofType, extractPayload } from 'rxbeach/operators';
import { switchMap, tap } from 'rxjs/operators';
import { from } from 'rxjs';

const fetchUser   = actionCreator<string>('[user] fetch');
const setUser     = actionCreator<{ id: string; name: string }>('[user] set');
const logAction   = actionCreator<string>('[log] log');

// Async fetch routine
const fetchUserRoutine = routine(
  ofType(fetchUser),
  extractPayload(),
  switchMap(id =>
    from(fetch(`/api/users/${id}`).then(r => r.json()))
  ),
  tap(user => dispatchAction(setUser(user)))
);

// Simple logging routine
const loggingRoutine = routine(
  ofType(logAction),
  extractPayload(),
  tap(msg => console.log('[LOG]', msg))
);

// Combine and subscribe all routines with a single subscription
const allRoutines = collectRoutines(fetchUserRoutine, loggingRoutine);
const sub = subscribeRoutine(action$, allRoutines);

dispatchAction(fetchUser('u1'));
dispatchAction(logAction('Application started'));

// To unsubscribe later:
// sub.unsubscribe();
```

--------------------------------

### Manage Persistent Streams with `stateStreamRegistry`

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `stateStreamRegistry` to manage the lifecycle of `ObservableState` instances created by `persistentReducedStream` or `persistentDerivedStream`. Call `.startReducing()` to connect all registered streams and `.stopReducing()` to unsubscribe them.

```typescript
import { stateStreamRegistry, persistentReducedStream } from 'rxbeach';

// Streams self-register on creation
const counter$ = persistentReducedStream('counter$', 0, [handleIncrement]);
const user$    = persistentReducedStream('user$', null, [handleSetUser]);

// At application boot:
stateStreamRegistry.startReducing();
// Both counter$ and user$ are now connected and reducing

// Access all registered stream names
for (const [name] of stateStreamRegistry.streams) {
  console.log('Registered:', name);
}

// On hot-module replacement or test teardown:
stateStreamRegistry.stopReducing();
// All streams unsubscribed; .state access will throw
```

--------------------------------

### Build Reduced State Stream

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/state-streams/reduced-state-streams.md

Create a reduced state stream using `persistentReducedStream`, providing a unique name, default state, and an array of reducers.

```typescript
import { persistentReducedStream } from 'rxbeach';

const reducers = [
  handleIncrement,
  handleIncrementBy,
  handleIncrementOf,
  handleIncrementByState
];
const defaultState: MyStreamState = { counter: 1 };

const myStream$ = persistentReducedStream('myStream$', defaultState, reducers);
```

--------------------------------

### Subscribe a Single Routine to the Action Stream

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/routines.md

Subscribe a defined routine to the action stream to enable its execution. The `subscribeRoutine` function connects the routine to the stream of actions.

```typescript
const subscription = subscribeRoutine(action$, logModuleChange)
```

--------------------------------

### Create a persistent reduced stream with RxBeach

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `persistentReducedStream` to create an ObservableState that persists for the application lifecycle and automatically registers with `stateStreamRegistry`. It exposes the current value synchronously via `.state`.

```typescript
import {
  actionCreator,
  reducer,
  persistentReducedStream,
  stateStreamRegistry,
  dispatchAction,
  action$
} from 'rxbeach';

type UserState = { id: string | null; name: string };
const initialUser: UserState = { id: null, name: '' };

const setUser  = actionCreator<UserState>('[user] set');
const clearUser = actionCreator('[user] clear');

const handleSet   = reducer(setUser,   (_s: UserState, user)  => user);
const handleClear = reducer(clearUser, (_s: UserState)        => initialUser);

export const user$ = persistentReducedStream('user$', initialUser, [handleSet, handleClear]);

// Start all registered streams at app boot
stateStreamRegistry.startReducing();

// Synchronous state read — always available after startReducing
console.log(user$.state); // { id: null, name: '' }

dispatchAction(setUser({ id: 'u1', name: 'Alice' }));
console.log(user$.state); // { id: 'u1', name: 'Alice' }

// Subscribe like a normal Observable
user$.subscribe(u => console.log('User changed:', u.name));

dispatchAction(clearUser());
console.log(user$.state); // { id: null, name: '' }
```

--------------------------------

### Create a persistent derived stream with RxBeach

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `persistentDerivedStream` to wrap any `ObservableInput` in an `ObservableState`, registering it with `stateStreamRegistry`. This is useful for persistent derived streams with synchronously readable current values.

```typescript
import { persistentDerivedStream, derivedStream, stateStreamRegistry } from 'rxbeach';
import { map } from 'rxjs/operators';

const raw$ = derivedStream('raw$', userList$, filter$);

// Maps the tuple to a view model object and makes it persistent
export const viewModel$ = persistentDerivedStream(
  'viewModel$',
  raw$.pipe(
    map(([users, filter]) => ({
      users: users.filter(u => u.name.includes(filter)),
      count: users.length,
    }))
  ),
  { users: [], count: 0 } // initial state
);

stateStreamRegistry.startReducing();
console.log(viewModel$.state); // { users: [], count: 0 }
```

--------------------------------

### Define Navigation State Shape

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/reducers.md

Defines the structure for navigation state, including the selected module and its default value.

```typescript
enum Module {
  DASHBOARD
}
type NavigationState = {
  selectedModule: Module;
};
const defaultNavigationState: NavigationState = {
  selectedModule: Module.DASHBOARD
};
```

--------------------------------

### Define Typed Action Creator with actionCreator

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `actionCreator` to create frozen, reusable functions for immutable action objects with a `{ type, payload, meta }` shape. Ensure action types follow the `[qualifier] action name` convention. Actions can be dispatched using `dispatchAction`.

```typescript
import { actionCreator, dispatchAction, action$ } from 'rxbeach';

// Action without payload
const increment = actionCreator('[counter] increment');

// Action with payload
const setCount = actionCreator<number>('[counter] set count');

// Actions with complex payload
const loadUser = actionCreator<{ id: string; name: string }>('[user] load user');

// Produce an action object
const action = setCount(42);
// => { type: '[counter] set count', payload: 42, meta: {} }

// Dispatch to the global action stream
dispatchAction(increment());
dispatchAction(setCount(100));
dispatchAction(loadUser({ id: 'u1', name: 'Alice' }));

// Access the static type string
console.log(setCount.type); // '[counter] set count'
```

--------------------------------

### Define Action Reducers

Source: https://github.com/ardoq/rxbeach/blob/master/docs/fundamentals/state-streams/reduced-state-streams.md

Use the `reducer` function to define how the stream state changes in response to actions. Handles actions with and without payloads.

```typescript
import { actionCreator, reducer } from 'rxbeach';

type MyStreamState = { counter: 1 };
const increment = actionCreator('increment');
const incrementBy = actionCreator<number>('increment by');

const handleIncrement = reducer(
  increment,
  ({ counter }: MyStreamState) => ({ counter: counter + 1 })
);
const handleIncrementBy = reducer(
  incrementBy,
  ({ counter }: MyStreamState, count) => ({ counter: counter + count})
)
```

--------------------------------

### Combine streams with RxBeach's derivedStream

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `derivedStream` as a typed, named wrapper around RxJS `combineLatest`. It accepts multiple source observables and emits a typed tuple when any source emits. Tagged for rxjs-spy debugging.

```typescript
import { derivedStream, persistentReducedStream } from 'rxbeach';

const userList$   = persistentReducedStream('userList$',   [],    [...]);
const activeFilter$ = persistentReducedStream('filter$',   '',    [...]);

// Emits [User[], string] whenever either source emits
const viewModel$ = derivedStream(
  'userListViewModel$',
  userList$,
  activeFilter$
);

viewModel$.subscribe(([users, filter]) => {
  const visible = users.filter(u => u.name.includes(filter));
  console.log('Visible users:', visible.length);
});
```

--------------------------------

### Register a pure state reducer with `reducer`

Source: https://context7.com/ardoq/rxbeach/llms.txt

Binds a pure reducer function to action creators or Observable sources. The payload type is automatically inferred from the action creator. Use for single actions, multiple actions, actions with payloads, or stream-based state updates.

```typescript
import { actionCreator, reducer } from 'rxbeach';
import { interval } from 'rxjs';

type CounterState = { count: number; lastUpdated: number };
const initialState: CounterState = { count: 0, lastUpdated: 0 };

const increment = actionCreator('[counter] increment');
const decrement = actionCreator('[counter] decrement');
const setCount  = actionCreator<number>('[counter] set count');

// Single action reducer
const handleIncrement = reducer(increment, (state: CounterState) => ({
  ...state,
  count: state.count + 1,
  lastUpdated: Date.now(),
}));

// Multiple actions sharing the same reducer
const handleIncrDecr = reducer(
  [increment, decrement],
  (state: CounterState, _payload, namespace) => {
    console.log('Namespace:', namespace);
    return { ...state, count: state.count + 1 };
  }
);

// Action with payload
const handleSetCount = reducer(setCount, (state: CounterState, count) => ({
  ...state,
  count,
  lastUpdated: Date.now(),
}));

// Stream-based reducer (advanced: react to any Observable)
const tick$ = interval(1000);
const handleTick = reducer(tick$, (state: CounterState, tickNumber) => ({
  ...state,
  lastUpdated: tickNumber,
}));
```

--------------------------------

### mergeOperators / coldMergeOperators

Source: https://context7.com/ardoq/rxbeach/llms.txt

These operators allow fanning out a single stream to multiple operators, running them in parallel and merging their results. `mergeOperators` shares the upstream (making it hot), while `coldMergeOperators` re-subscribes the source for each operator.

```APIDOC
## `mergeOperators` / `coldMergeOperators` — Fan out one stream to multiple operators

`mergeOperators` shares the upstream (making it hot) and runs multiple operators in parallel, merging their results. `coldMergeOperators` does the same without the `share`, re-subscribing the source for each operator.

```typescript
import { mergeOperators, coldMergeOperators } from 'rxbeach/operators';
import { ofType, extractPayload } from 'rxbeach/operators';
import { tap } from 'rxjs/operators';
import { action$, actionCreator, dispatchAction } from 'rxbeach';

const tick = actionCreator('[timer] tick');

// Run two handlers for the same action type simultaneously
// upstream (action$) is shared — only subscribed once
const combined = action$.pipe(
  mergeOperators(
    pipe(ofType(tick), tap(() => console.log('Handler A'))),
    pipe(ofType(tick), tap(() => console.log('Handler B')))
  )
);
combined.subscribe();

dispatchAction(tick());
// => Handler A
// => Handler B
```
```

--------------------------------

### `actionCreator` — Define a typed action creator

Source: https://context7.com/ardoq/rxbeach/llms.txt

Creates a frozen, reusable function that produces immutable action objects with a guaranteed `{ type, payload, meta }` shape. The `type` argument must follow the `[qualifier] action name` convention enforced by the `ActionName` type.

```APIDOC
## `actionCreator` — Define a typed action creator

Creates a frozen, reusable function that produces immutable action objects with a guaranteed `{ type, payload, meta }` shape. The `type` argument must follow the `[qualifier] action name` convention enforced by the `ActionName` type.

```typescript
import { actionCreator, dispatchAction, action$ } from 'rxbeach';

// Action without payload
const increment = actionCreator('[counter] increment');

// Action with payload
const setCount = actionCreator<number>('[counter] set count');

// Actions with complex payload
const loadUser = actionCreator<{ id: string; name: string }>('[user] load user');

// Produce an action object
const action = setCount(42);
// => { type: '[counter] set count', payload: 42, meta: {} }

// Dispatch to the global action stream
dispatchAction(increment());
dispatchAction(setCount(100));
dispatchAction(loadUser({ id: 'u1', name: 'Alice' }));

// Access the static type string
console.log(setCount.type); // '[counter] set count'
```
```

--------------------------------

### `action$` and `dispatchAction` — The global action bus

Source: https://context7.com/ardoq/rxbeach/llms.txt

`action$` is the single shared RxJS Observable that all actions flow through. `dispatchAction` is the function used to push new actions onto this stream. Optionally accepts a namespace string to scope the action.

```APIDOC
## `action$` and `dispatchAction` — The global action bus

`action$` is the single shared RxJS Observable that all actions flow through. `dispatchAction` is the function used to push new actions onto this stream. Optionally accepts a namespace string to scope the action.

```typescript
import { action$, dispatchAction, actionCreator } from 'rxbeach';
import { tap } from 'rxjs/operators';

const navigate = actionCreator<string>('[router] navigate');

// Subscribe directly to the raw action stream
const sub = action$.pipe(
  tap(action => console.log('Action dispatched:', action.type))
).subscribe();

// Dispatch a plain action
dispatchAction(navigate('/dashboard'));
// => Action dispatched: [router] navigate

// Dispatch with a namespace (scopes the action for component isolation)
dispatchAction(navigate('/settings'), 'sidebar-instance-1');
// => action.meta.namespace === 'sidebar-instance-1'

sub.unsubscribe();
```
```

--------------------------------

### Runtime Action Type Guards: isValidRxBeachAction and isActionOfType

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `isValidRxBeachAction` to check if a value is a valid RxBeach action object. Employ `isActionOfType` to narrow an unknown value to a specific typed action by combining structural checks with type string comparison.

```typescript
import { actionCreator, isValidRxBeachAction, isActionOfType } from 'rxbeach';

const saveItem = actionCreator<{ id: string }>('[items] save item');

function handleUnknown(value: unknown) {
  if (!isValidRxBeachAction(value)) {
    console.log('Not a valid action');
    return;
  }
  // value is now Action<unknown>
  console.log('Valid action type:', value.type);

  if (isActionOfType(saveItem, value)) {
    // value is now Action<{ id: string }>
    console.log('Saving item with id:', value.payload.id);
  }
}

handleUnknown({ type: '[items] save item', payload: { id: '42' }, meta: {} });
// => Valid action type: [items] save item
// => Saving item with id: 42
```

--------------------------------

### Filter Actions by Namespace with RxJS

Source: https://context7.com/ardoq/rxbeach/llms.txt

Utilize `withNamespace` to retain actions with no namespace or a specific namespace, and `withoutNamespace` to exclude namespaced actions. Both are `MonoTypeOperatorFunction<Action>`.

```typescript
import { action$, actionCreator, dispatchAction } from 'rxbeach';
import { withNamespace, withoutNamespace } from 'rxbeach/operators';
import { tap } from 'rxjs/operators';

const toggle = actionCreator('[item] toggle');

// Only handle toggle actions for 'sidebar' instance
action$.pipe(
  withNamespace('sidebar'),
  tap(a => console.log('Sidebar action:', a.type))
).subscribe();

// Ignore all namespaced actions (global-only)
action$.pipe(
  withoutNamespace(),
  tap(a => console.log('Global action:', a.type))
).subscribe();

dispatchAction(toggle(), 'sidebar');   // => Sidebar action: [item] toggle
dispatchAction(toggle());              // => Global action: [item] toggle
dispatchAction(toggle(), 'main-nav');  // (neither handler logs — sidebar filter skips it, withoutNamespace skips it)
```

--------------------------------

### `isValidRxBeachAction` / `isActionOfType` — Runtime action type guards

Source: https://context7.com/ardoq/rxbeach/llms.txt

`isValidRxBeachAction` checks whether an unknown value is a valid RxBeach action object. `isActionOfType` narrows an unknown value to a specific typed action, combining the structural check with a type string comparison.

```APIDOC
## `isValidRxBeachAction` / `isActionOfType` — Runtime action type guards

`isValidRxBeachAction` checks whether an unknown value is a valid RxBeach action object. `isActionOfType` narrows an unknown value to a specific typed action, combining the structural check with a type string comparison.

```typescript
import { actionCreator, isValidRxBeachAction, isActionOfType } from 'rxbeach';

const saveItem = actionCreator<{ id: string }>('[items] save item');

function handleUnknown(value: unknown) {
  if (!isValidRxBeachAction(value)) {
    console.log('Not a valid action');
    return;
  }
  // value is now Action<unknown>
  console.log('Valid action type:', value.type);

  if (isActionOfType(saveItem, value)) {
    // value is now Action<{ id: string }>
    console.log('Saving item with id:', value.payload.id);
  }
}

handleUnknown({ type: '[items] save item', payload: { id: '42' }, meta: {} });
// => Valid action type: [items] save item
// => Saving item with id: 42
```
```

--------------------------------

### useStream

Source: https://context7.com/ardoq/rxbeach/llms.txt

A React hook that subscribes to any `ObservableInput` and returns the latest emitted value. It returns a `NOT_YET_EMITTED` Symbol until the first emission or a provided `defaultValue`.

```APIDOC
## `useStream` — React hook for subscribing to a stream

Subscribes to any `ObservableInput` and returns the latest emitted value. Returns `NOT_YET_EMITTED` (a Symbol) until the first emission, or a provided `defaultValue`.

```typescript
import React from 'react';
import { useStream, NOT_YET_EMITTED } from 'rxbeach/react';
import { user$ } from './streams';

function UserHeader() {
  const user = useStream(user$, { id: null, name: 'Loading...' });

  if (user === NOT_YET_EMITTED) return <div>Waiting…</div>;

  return <h1>Hello, {user.name}</h1>;
}

// With default value, NOT_YET_EMITTED is never returned
function UserName() {
  const user = useStream(user$, { id: null, name: '' });
  // user is always { id: string | null, name: string }
  return <span>{user.name}</span>;
}
```
```

--------------------------------

### Compose reducers into an RxJS operator with `combineReducers`

Source: https://context7.com/ardoq/rxbeach/llms.txt

Merges multiple `RegisteredReducer` entries into a single `OperatorFunction<Action, State>`. Handles both action-triggered and stream-triggered reducers. Errors are caught and forwarded to the optional `errorSubject` without terminating the stream.

```typescript
import {
  actionCreator, reducer, combineReducers, action$
} from 'rxbeach';
import { Subject } from 'rxjs';

type TodoState = { items: string[]; loading: boolean };
const initial: TodoState = { items: [], loading: false };

const addTodo   = actionCreator<string>('[todos] add');
const setLoading = actionCreator<boolean>('[todos] set loading');

const handleAdd = reducer(addTodo, (state: TodoState, item) => ({
  ...state,
  items: [...state.items, item],
}));
const handleLoading = reducer(setLoading, (state: TodoState, loading) => ({
  ...state, loading,
}));

const errorSubject = new Subject<any>();
errorSubject.subscribe(err => console.error('Reducer error:', err));

// Compose into an operator and apply to the action stream
const todoState$ = action$.pipe(
  combineReducers(initial, [handleAdd, handleLoading], { errorSubject })
);

todoState$.subscribe(state => console.log(state));

dispatchAction(addTodo('Buy milk'));
// => { items: ['Buy milk'], loading: false }
dispatchAction(setLoading(true));
// => { items: ['Buy milk'], loading: true }
```

--------------------------------

### Subscribe to streams in React with useStream hook

Source: https://context7.com/ardoq/rxbeach/llms.txt

The `useStream` hook subscribes to an `ObservableInput` and returns the latest emitted value. It returns `NOT_YET_EMITTED` until the first emission, or a provided `defaultValue` can be used to avoid this.

```typescript
import React from 'react';
import { useStream, NOT_YET_EMITTED } from 'rxbeach/react';
import { user$ } from './streams';

function UserHeader() {
  const user = useStream(user$, { id: null, name: 'Loading...' });

  if (user === NOT_YET_EMITTED) return <div>Waiting…</div>;

  return <h1>Hello, {user.name}</h1>;
}

// With default value, NOT_YET_EMITTED is never returned
function UserName() {
  const user = useStream(user$, { id: null, name: '' });
  // user is always { id: string | null, name: string }
  return <span>{user.name}</span>;
}
```

--------------------------------

### Provide Per-Value Context to CatchError

Source: https://context7.com/ardoq/rxbeach/llms.txt

The `apply` operator wraps each emitted value in its own `of(value).pipe(operator(value))` scope, granting `catchError` access to the original value via closure. Use `carry` when possible; `apply` is intended for scenarios where `catchError` context is specifically required.

```typescript
import { routine, actionCreator, action$ } from 'rxbeach';
import { ofType, extractPayload, apply } from 'rxbeach/operators';
import { map, tap, catchError } from 'rxjs/operators';
import { EMPTY } from 'rxjs';

const processItem = actionCreator<{ id: string }>('[item] process');

const processRoutine = routine(
  ofType(processItem),
  extractPayload(),
  apply(({ id }) => map(payload => {
    if (!payload.id) throw new Error('Missing id');
    return payload;
  })),
  tap(item => console.log('Processed:', item.id))
);

```

--------------------------------

### Fan out one stream to multiple operators with mergeOperators

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use mergeOperators to share an upstream stream and run multiple operators in parallel, merging their results. Ensure the upstream stream is subscribed to only once.

```typescript
import { mergeOperators, coldMergeOperators } from 'rxbeach/operators';
import { ofType, extractPayload } from 'rxbeach/operators';
import { tap, map } from 'rxjs/operators';
import { action$, actionCreator, dispatchAction } from 'rxbeach';

const tick = actionCreator('[timer] tick');

// Run two handlers for the same action type simultaneously
// upstream (action$) is shared — only subscribed once
const combined = action$.pipe(
  mergeOperators(
    pipe(ofType(tick), tap(() => console.log('Handler A'))),
    pipe(ofType(tick), tap(() => console.log('Handler B')))
  )
);
combined.subscribe();

dispatchAction(tick());
// => Handler A
// => Handler B
```

--------------------------------

### Extract Payload from Action with RxJS

Source: https://context7.com/ardoq/rxbeach/llms.txt

Use `extractPayload` to transform an `Observable<Action<Payload>>` into an `Observable<Payload>`. This is useful within routines and `combineReducers` pipelines after an `ofType` operator.

```typescript
import { action$, actionCreator } from 'rxbeach';
import { ofType, extractPayload } from 'rxbeach/operators';
import { map, tap } from 'rxjs/operators';

const search = actionCreator<{ query: string; page: number }>('[search] execute');

action$.pipe(
  ofType(search),
  extractPayload(),         // Observable<{ query: string; page: number }>
  map(({ query, page }) => `q=${query}&page=${page}`),
  tap(qs => console.log('Search params:', qs))
).subscribe();

dispatchAction(search({ query: 'rxbeach', page: 1 }));
// => Search params: q=rxbeach&page=1
```

--------------------------------

### Filter Actions by Creator with `ofType`

Source: https://context7.com/ardoq/rxbeach/llms.txt

The `ofType` operator filters an action stream to emit only actions matching specified action creators, providing full TypeScript payload narrowing. It can filter single or multiple action types.

```typescript
import { action$, actionCreator } from 'rxbeach';
import { ofType, extractPayload } from 'rxbeach/operators';
import { tap } from 'rxjs/operators';

const setTitle  = actionCreator<string>('[page] set title');
const setBody   = actionCreator<string>('[page] set body');
const save      = actionCreator('[page] save');

// Filter single action type with full payload typing
action$.pipe(
  ofType(setTitle),
  extractPayload(),      // Observable<string>
  tap(title => document.title = title)
).subscribe();

// Filter multiple actions with overlapping payload type
action$.pipe(
  ofType(setTitle, setBody),  // Observable<Action<string>>
  extractPayload(),
  tap(text => console.log('Text changed:', text))
).subscribe();

// Filter void action
action$.pipe(
  ofType(save),
  tap(() => console.log('Saving...'))
).subscribe();
```

--------------------------------

### Carry Original Value with Operator Result

Source: https://context7.com/ardoq/rxbeach/llms.txt

The `carry` operator makes the upstream observable hot with `share()`. It pairs each emitted value with the result of an inner operator, yielding `[original, result]` tuples. This is useful when the original payload is needed alongside an asynchronous result.

```typescript
import { routine, actionCreator, dispatchAction, action$ } from 'rxbeach';
import { ofType, extractPayload, carry } from 'rxbeach/operators';
import { switchMap, tap } from 'rxjs/operators';
import { from } from 'rxjs';

const submitForm = actionCreator<{ id: string; data: object }>('[form] submit');
const formSaved  = actionCreator<{ id: string; result: object }>('[form] saved');

const submitRoutine = routine(
  ofType(submitForm),
  extractPayload(),
  carry(switchMap(({ id, data }) => from(fetch(`/api/items/${id}`, {
    method: 'POST', body: JSON.stringify(data)
  }).then(r => r.json())))),
  tap(([original, result]) => {
    console.log('Submitted id:', original.id);
    dispatchAction(formSaved({ id: original.id, result }));
  })
);

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.