Index

State Management

SynState provides simple, intuitive APIs for managing application state:

• createState: Create state with InitializedObservable and setter.
• createReducer: Create state by reducer and initial value.
• createBooleanState: Specialized state for boolean values.

Event System

Built-in event emitter for event-driven patterns:

• createValueEmitter: Create type-safe event emitters.
• createEventEmitter: Create event emitters without payload.

Observable APIs

For complex scenarios, SynState provides observable-based APIs:

Creation Functions

• source<T>(): Create a new observable source (almost equivalent to RxJS subject).
• just(value): Create an Observable that holds a single static value and immediately completes. Useful as a synchronous fallback inside switchMap.
• fromPromise(promise): Create observable from promise.
• fromSubscribable(): Create observable from any subscribable object.
• counter(ms): Emit values at intervals (almost equivalent to RxJS interval).
• timer(delay): Emit after delay.

Combination

• combine(observables): Combine latest values from multiple sources (alias: combineLatest).
• merge(observables): Merge multiple streams.
• zip(observables): Pair values by index.

Operators

map variants

• map(fn): Transform values.
• mapTo(value): Map all values to a constant.
• getKey(key): Extract property value from objects (alias: pluck).
• attachIndex(): Attach index to each value (alias: withIndex).

Result/Optional

• mapOptional(fn): Map over Optional values.
• mapResultOk(fn): Map over Result ok values.
• mapResultErr(fn): Map over Result error values.
• unwrapOptional(): Unwrap Optional values to undefined.
• unwrapResultOk(): Unwrap Result ok values to undefined.
• unwrapResultErr(): Unwrap Result error values to undefined.

Flat map

• mergeMap(fn): Map to observables and merge all (runs in parallel) (alias: flatMap).
• switchMap(fn): Map to observables and switch to latest (cancels previous).

Filtering

• filter(predicate): Filter values.
• skipIfNoChange(): Skip duplicate values (alias: distinctUntilChanged).
• skip(n): Skip first n emissions.
• take(n): Take first n emissions then complete.
• skipWhile(predicate): Skip values while predicate is true.
• takeWhile(predicate): Emit values while predicate is true, then complete.
• skipUntil(notifier): Skip values until notifier emits.
• takeUntil(notifier): Complete on notifier emission.

Time series processing

• audit(ms): Emit the last value after specified time window (almost equivalent to RxJS auditTime).
• debounce(ms): Debounce emissions (almost equivalent to RxJS debounceTime).
• throttle(ms): Throttle emissions (almost equivalent to RxJS throttleTime).

Others

• pairwise(): Emit previous and current values as pairs.
• scan(reducer, seed): Accumulate values.
• withBuffered(observable): Buffer values from observable and emit with parent (alias: withBufferedFrom).
• withCurrentValueFrom(observable): Sample current value from another observable (alias: withLatestFrom).
• withInitialValue(value): Provide an initial value for uninitialized observable.

Utilities

• isChildObservable(obs): Check if observable is a child observable.
• isManagerObservable(obs): Check if observable is a manager observable.
• isRootObservable(obs): Check if observable is a root observable.

Framework Integration

React / Preact Hooks (synstate-react-hooks / synstate-preact-hooks)

Both packages share the same API surface. Use synstate-react-hooks for React 18+ and synstate-preact-hooks for Preact.

Hooks

• useObservableValue(observable$): Subscribe to an observable and return its current value as component state. Uses useSyncExternalStore internally — the component re-renders when the observable emits.
• useObservableValue(observable$, fallback): Same as above, with a fallback value for observables without an initial value.
• useObservableEffect(observable$, fn): Run a side effect whenever the observable emits. Automatically unsubscribes on unmount.
• useValueAsObservable(value): Convert a component prop/state value into a synstate observable. Useful for bridging React/Preact state into the observable graph.

State Wrappers

These re-export core createState / createReducer / createBooleanState but return a hook (useCurrentValue) as the first tuple element instead of the raw observable:

• createState(initialValue): Returns [useCurrentValue, setState, { state, updateState, resetState, getSnapshot, initialState }].
• createReducer(reducer, initialState): Returns [useCurrentValue, dispatch, { state, getSnapshot, initialState }].
• createBooleanState(initialValue): Returns [useCurrentValue, { state, setTrue, setFalse, toggle, setState, updateState, resetState, getSnapshot, initialState }].

Preact Signals (synstate-preact-signals)

Bridges synstate observables with Preact Signals for fine-grained DOM updates without component re-renders. See the interactive demo to compare with the hooks approach.

Bridge Functions

• toSignal(observable$): Convert an Observable (or InitializedObservable) into a Preact ReadonlySignal. The signal stays in sync with the observable. Can be embedded directly in JSX — only the affected text node updates, not the entire component.
• toSignal(observable$, fallback): Same as above, with a fallback value for observables without an initial value.
• fromSignal(signal): Convert a Preact Signal into a synstate InitializedSourceObservable. Returns [observable, dispose]. The observable mirrors the signal’s value, enabling the full synstate operator chain (map, debounce, switchMap, etc.).

State Wrappers

Same as the hooks wrappers, but return a ReadonlySignal instead of a hook:

• createState(initialValue): Returns [signal, setState, { state, updateState, resetState, getSnapshot, initialState }].
• createReducer(reducer, initialState): Returns [signal, dispatch, { state, getSnapshot, initialState }].
• createBooleanState(initialValue): Returns [signal, { state, setTrue, setFalse, toggle, setState, updateState, resetState, getSnapshot, initialState }].