@rxova/journey-core 0.3.0 → 0.4.0

package/README.md

@@ -1,137 +1,79 @@
 # @rxova/journey-core
 
-The core Journey state machine for non-React environments. Use this package if you want the smallest, framework-agnostic runtime.
+<p>
+  <a href="https://www.npmjs.com/package/@rxova/journey-core">
+    <img src="https://img.shields.io/badge/npm-%40rxova%2Fjourney--core-CB3837?logo=npm&logoColor=white" alt="npm package @rxova/journey-core" />
+  </a>
+  <a href="https://rxova.org/docs/core/getting-started">
+    <img src="https://img.shields.io/badge/docs-core-0f8f6a" alt="Core docs" />
+  </a>
+  <a href="https://github.com/rxova/journey/actions/workflows/ci.yml">
+    <img src="https://github.com/rxova/journey/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" />
+  </a>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/coverage%20(core)-100%25-brightgreen" alt="Core coverage" />
+  <a href="https://www.npmjs.com/package/@rxova/journey-core">
+    <img src="https://img.shields.io/npm/v/@rxova/journey-core" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@rxova/journey-core">
+    <img src="https://img.shields.io/npm/dm/@rxova/journey-core" alt="npm downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/@rxova/journey-core">
+    <img src="https://img.shields.io/bundlephobia/minzip/%40rxova%2Fjourney-core" alt="Bundlephobia" />
+  </a>
+</p>
+
+Headless runtime for step journeys and non-linear flows.
+
+Use `@rxova/journey-core` when you want flow logic that is independent from UI frameworks.
+
+`[GETTING STARTED](https://rxova.org/docs/core/getting-started) | [ARCHITECTURE](https://rxova.org/docs/core/architecture) | [API](https://rxova.org/docs/core/api) | [HISTORY](https://rxova.org/docs/core/history) | [PERSISTENCE](https://rxova.org/docs/core/persistence) | [ASYNC](https://rxova.org/docs/core/async) | [EXAMPLES](https://rxova.org/docs/core/examples)`
 
 ## Install
 
 ```bash
-pnpm add @rxova/journey-core
-npm install @rxova/journey-core
-yarn add @rxova/journey-core
+npm i @rxova/journey-core
 ```
 
-## Basic usage
+## What You Get
 
-```ts
-import {
-  createJourneyMachine,
-  JOURNEY_TERMINAL,
-  type JourneyDefinition
-} from "@rxova/journey-core";
-
-type StepId = "one" | "two" | "three";
-type Event = "next" | "submit";
-type Ctx = { name: string };
-
-const journey: JourneyDefinition<Ctx, StepId, Event> = {
-  initial: "one",
-  context: { name: "" },
-  steps: {
-    one: {},
-    two: {},
-    three: {}
-  },
-  transitions: [
-    { from: "one", event: "next", to: "two" },
-    { from: "two", event: "next", to: "three" },
-    { from: "three", event: "submit", to: JOURNEY_TERMINAL.COMPLETE }
-  ]
-};
-
-const machine = createJourneyMachine<Ctx, StepId, Event>(journey);
-```
-
-## History behavior
-
-The machine tracks two related collections:
-
-- `history`: ordered list of prior steps. It grows when you move to a different step.
-- `visited`: list of steps you have reached (including current), with duplicates removed. It is not affected by history trimming.
-
-Why `visited` is a list (not a `Set`) for the following reasons:
-
-- JSON-friendly for snapshots, logs, and persistence.
-- Deterministic order for tests and UI rendering.
-- Easier to consume in TypeScript (`readonly TStepId[]`).
-- It is derived from `history + current` initially, then maintained independently so trimming history does not remove earlier entries.
-
-History is used when you target `HISTORY_TARGET` in a transition. It resolves to the most recent valid step in `history`. If history is empty (or contains invalid steps), the machine stays on the current step.
+- Strongly typed journey definition and events.
+- Deterministic transition matching.
+- Built-in history, persistence helpers, and async lifecycle hooks.
+- A reusable machine API you can run in frontend or backend code.
 
-### History retention
-
-You can cap history growth with `maxHistory`. When the history exceeds that limit, the oldest entries are trimmed.
-
-Defaults:
-
-- `maxHistory`: `50`
-- `maxHistory: null` disables trimming entirely.
-
-Automatic trimming happens:
-
-- After transitions (including `goTo`)
-- After persistence hydrate
-
-### Overflow callback
-
-`onOverflow` fires only when trimming actually happens. It receives:
-
-- `previous`: history before trimming
-- `next`: history after trimming
-- `trimmed`: entries removed
-- `maxHistory`: resolved limit (number or `null`)
-- `reason`: `"auto" | "hydrate" | "manual"`
-  - `auto`: trimming happened automatically during a transition (including `goTo`)
-  - `hydrate`: trimming happened right after loading persisted state
-  - `manual`: trimming happened because you called `trimHistory()`
-
-### Config example
+## Quickstart
 
 ```ts
-const machine = createJourneyMachine(journey, {
-  history: {
-    maxHistory: 20,
-    onOverflow: ({ trimmed, reason }) => {
-      console.warn("trimmed history", trimmed, "reason:", reason);
-    }
-  }
-});
-```
+import { createJourneyMachine, JOURNEY_TERMINAL } from "@rxova/journey-core";
 
-### History target example
+type StepId = "start" | "review";
+type Event = "next" | "submit";
 
-```ts
-import { HISTORY_TARGET } from "@rxova/journey-core";
+type Ctx = { name: string };
 
-const journey: JourneyDefinition<Ctx, StepId, Event> = {
-  initial: "one",
+// 1) Describe the flow as data.
+const journey = {
+  initial: "start",
   context: { name: "" },
-  steps: {
-    one: {},
-    two: {},
-    three: {}
-  },
+  steps: { start: {}, review: {} },
   transitions: [
-    { from: "one", event: "next", to: "two" },
-    { from: "two", event: "next", to: "three" },
-    { from: "*", event: "back", to: HISTORY_TARGET }
+    { from: "start", event: "next", to: "review" },
+    { from: "review", event: "submit", to: JOURNEY_TERMINAL.COMPLETE }
   ]
 };
-```
-
-### Manual history management
 
-```ts
-const machine = createJourneyMachine(journey, { history: { maxHistory: 5 } });
+// 2) Create a machine instance.
+const machine = createJourneyMachine<Ctx, StepId, Event>(journey);
 
-await machine.send({ type: "goTo", to: "two" });
-await machine.send({ type: "goTo", to: "three" });
+// 3) Drive the flow with typed events.
+await machine.send({ type: "next" });
 
-machine.trimHistory(1); // keep most recent entry only
-machine.clearHistory(); // reset history to []
+// 4) Read immutable runtime state at any time.
+const snapshot = machine.getSnapshot();
+console.log(snapshot.current);
 ```
 
-## Links
+## Coverage Notes
 
-- Docs: ../../docs/GETTING_STARTED.md
-- API: ../../docs/API.md
-- React bindings: ../react
+Coverage badge is package-specific (`packages/core/test` against `packages/core/src`), not monorepo-wide.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/journey-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Journey core state machine.",
   "keywords": [
     "journey",
@@ -19,7 +19,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rxova/journey.git"
+    "url": "git+https://github.com/rxova/journey.git",
+    "directory": "packages/core"
   },
   "publishConfig": {
     "access": "public"