@state-flow/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Pirogov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# StateFlow
+
+Type-safe, immutable state management for TypeScript, built on **signals**, **flows**, and frozen **state snapshots**.
+
+[![npm version](https://img.shields.io/npm/v/@state-flow/core.svg)](https://www.npmjs.com/package/@state-flow/core)
+[![CI](https://github.com/ilya-pirogov/stateflow/actions/workflows/ci.yml/badge.svg)](https://github.com/ilya-pirogov/stateflow/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+StateFlow models your application state as a set of explicit, named variants and the
+transitions between them. Every change goes through a **signal**, every transition is
+described by a pure **flow** function, and every state instance is a frozen, immutable
+snapshot. The result is state logic that is predictable, traceable, and fully type-checked
+end to end.
+
+## Why StateFlow
+
+- **Signals are the only path to change.** State can never be mutated directly — you
+  dispatch a typed signal and the flow decides what happens. Every change is tracked.
+- **Immutable snapshots.** State instances are frozen with `Object.freeze()`; transitions
+  produce new snapshots rather than mutating existing ones.
+- **Pure, synchronous transitions.** `defineFlow` handlers are synchronous and return a
+  new state or a `Result` (`ok` / `ignore` / `reject` / `error`) — the right place to
+  validate input. Side effects and async work live in `applyFlow` handlers via
+  `Result.transition`.
+- **First-class type safety.** Signals, state variants, and flow handlers are all inferred
+  and checked. Illegal transitions are compile errors, not runtime surprises.
+- **Tiny footprint.** No framework lock-in; the only runtime dependency is `events`.
+
+## Installation
+
+```bash
+npm install @state-flow/core
+# or
+yarn add @state-flow/core
+# or
+pnpm add @state-flow/core
+```
+
+**Requirements.** The published package is downleveled to ES2020 and ships a `Symbol.dispose` /
+`Symbol.asyncDispose` polyfill, so it runs on Node.js 18+ and modern browsers with no special
+runtime support. The examples below use `await using` (explicit resource management) for
+ergonomic cleanup — that syntax is optional and requires TypeScript 5.2+ with an ES2022+
+target. You can always dispose manually instead (e.g. `observer[Symbol.dispose]()`).
+
+## Quick start
+
+```typescript
+import {
+  defineSignal,
+  defineState,
+  defineFlow,
+  applyFlow,
+  lock,
+  observe,
+  Result,
+  ResultKind,
+  type Infer,
+} from "@state-flow/core";
+
+// 1. Signals — the only way to request a state change.
+const signals = {
+  play: defineSignal("play"),
+  pause: defineSignal("pause"),
+  seek: defineSignal<{ position: number }>("seek"),
+};
+
+// 2. State — immutable, frozen snapshots with named variants.
+const playback = defineState<{ position: number; duration: number }>()
+  .name("playback")
+  .signals(signals)
+  .variant("paused", true) // the initial variant
+  .variant("playing")
+  .stringRepr((s) => `pos=${s.position}/${s.duration}`)
+  .build();
+
+// 3. Flow — how each variant responds to signals (must be synchronous).
+defineFlow(playback.paused, {
+  play: (state) => playback.playing(state),
+  seek: (state, signal) => {
+    if (signal.position < 0 || signal.position > state.duration) {
+      return Result.reject("Invalid seek position");
+    }
+    return { ...state, position: signal.position };
+  },
+});
+
+defineFlow(playback.playing, {
+  pause: (state) => playback.paused(state),
+});
+
+// 4. Bind the flow to an object and register side-effect handlers.
+type Player = { playback: Infer<typeof playback> };
+const player: Player = { playback: { position: 0, duration: 180 } };
+
+applyFlow(player, [playback], (sm) => {
+  sm.addEnterHandler(playback.playing, () => Result.ok());
+});
+
+// 5. Observe state changes (the only thing mutable after setup).
+const observer = observe(
+  player,
+  [playback.playing, playback.paused],
+  (state) => console.log("playback ->", String(state)),
+);
+
+// 6. Drive it: acquire a lock, then send signals — queued and type-safe.
+async function main() {
+  await using send = await lock(player);
+  await send(signals.play()).expect(ResultKind.OK, ResultKind.Ignored).done();
+  await send(signals.seek({ position: 30 })).done();
+
+  observer[Symbol.dispose]();
+}
+
+main();
+```
+
+For a full walkthrough — including asynchronous transitions, observers, result merging,
+testing, and architecture — see the [documentation](#documentation).
+
+## Core concepts
+
+| Concept | What it is |
+| --- | --- |
+| **Signal** | A typed message that requests a state change. Created with `defineSignal`. |
+| **State** | An immutable definition with one or more named variants. Created with `defineState`. |
+| **Flow** | The synchronous mapping from a variant + signal to a new state or `Result`. Created with `defineFlow`. |
+| **Result** | The outcome of a transition: `ok`, `ignore`, `reject`, `error`, or an async `transition`. |
+| **`applyFlow`** | Binds state definitions to a target object and registers enter/update/exit/rollback handlers. |
+| **`lock` / `send`** | Acquire an async-disposable lock, then dispatch signals so they queue safely instead of throwing during an active transition. |
+| **`observe`** | Subscribe to variant changes for UI updates and side effects. |
+
+## Documentation
+
+Full documentation lives at **[stateflow.dev](https://stateflow.dev)** — core concepts, the
+signal system, state consistency and visibility, the API reference, a complete media-player
+example, testing, and the architecture guide.
+
+The site's source is in [`docs/`](./docs) (a Next.js app). To run it locally:
+
+```bash
+cd docs
+yarn install
+yarn dev
+```
+
+## Development
+
+```bash
+npm install      # install dependencies
+npm test         # run the test suite (vitest)
+npm run build    # bundle (tsup) + emit type declarations (tsc)
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](./LICENSE) © Ilya Pirogov

package/dist/flow.d.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from "events";
+import { type StateFlowLogEntry, type StateFlowLogHandler } from "./logger";
+import { Result } from "./result";
+import type { Signal } from "./signal";
+import { type ArrayToRecord, type StateDefinition, type StateInstance, type StateVariant } from "./state";
+export type StateFlowMeta = {
+    emitter: EventEmitter;
+    transitioning: Promise<Result> | true | null;
+    lockHolder: symbol | null;
+    lockQueue: Array<{
+        id: symbol;
+        resolve: () => void;
+    }>;
+    states: Array<StateDefinition>;
+    name: string;
+    logHandlers: StateFlowLogHandler[];
+    logGroup: {
+        label: string;
+        pending: Array<Promise<StateFlowLogEntry>>;
+        context: string | null;
+    } | null;
+};
+export interface FlowConfig {
+    logHandlers?: StateFlowLogHandler[];
+}
+type StateHandler<TProps> = (state: StateInstance<TProps>, context: unknown) => Result;
+type ObserverHandler<TProps = unknown> = (state: StateInstance<TProps>) => void;
+type ObserverComparerFn<TProps = unknown> = (a: TProps, b: TProps) => boolean;
+type Disposer = {
+    [Symbol.dispose](): void;
+};
+export interface StateManager {
+    addEnterHandler<TProps>(state: StateVariant<TProps>, cb: StateHandler<TProps>, context?: unknown): void;
+    addExitHandler<TProps>(state: StateVariant<TProps>, cb: StateHandler<TProps>, context?: unknown): void;
+    addUpdateHandler<TProps>(state: StateVariant<TProps>, cb: StateHandler<TProps>, context?: unknown): void;
+    addRollbackHandler<TProps>(state: StateVariant<TProps>, cb: StateHandler<TProps>, context?: unknown): void;
+}
+type StateManagerCallback = (sm: StateManager) => void;
+export type DispatchFn = ((signal: Signal, mute?: boolean) => Result) & {
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export declare function applyFlow<TStates extends Array<object>>(target: ArrayToRecord<TStates>, states: TStates, initializer: StateManagerCallback, config?: FlowConfig): void;
+export declare function dispatch(target: object, signal: Signal, mute?: boolean): Result;
+export declare function lock(target: object, label?: string): Promise<DispatchFn>;
+export declare function sync(target: object): Promise<void>;
+export declare function observe<T>(target: object, stateVariants: StateVariant<T>[], handlerFn: ObserverHandler<T>, compareFn?: ObserverComparerFn<T>, ctx?: object): Disposer;
+export declare function disposeFlow(target: object): void;
+export {};
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { applyFlow, DispatchFn, dispatch, disposeFlow, lock, observe, StateManager, sync } from "./flow";
+export { addGlobalLogHandler, consoleLogHandler, StateFlowLogEntry, StateFlowLogHandler, setConsoleLogSilenced, setGlobalDispatchContextProvider, } from "./logger";
+export { Result, ResultCollector, ResultKind } from "./result";
+export { defineSignal, Signal, StateSignal } from "./signal";
+export { defineFlow, defineState, isState, StateResult, StateVariant, stateVar } from "./state";
+export { PARSER, SIGNALS, STRING_REPR, VARIANT } from "./symbols";
+export { Infer, StateFlowError, serializeDebug } from "./utils";
+declare global {
+    var __STATE_FLOW__: {
+        version: string;
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzG,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEhE,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC"}