@owlmeans/flow 0.1.18-rc.13 → 0.1.18-rc.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/agent-meta/manifest.json +2 -2
- package/agent-meta/skills/flow/SKILL.md +51 -15
- package/build/errors.d.ts.map +1 -1
- package/build/errors.js.map +1 -1
- package/build/helper.d.ts.map +1 -1
- package/build/state.d.ts.map +1 -1
- package/build/utils/flow.d.ts.map +1 -1
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ State machine for multi-step user flows, primarily used for OIDC authentication
|
|
|
12
12
|
## Installation
|
|
13
13
|
|
|
14
14
|
```bash
|
|
15
|
-
bun add @owlmeans/flow
|
|
15
|
+
bun add @owlmeans/flow@^0.1.18-rc.13
|
|
16
16
|
```
|
|
17
17
|
|
|
18
18
|
## Usage
|
|
@@ -81,7 +81,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
|
|
|
81
81
|
your project's skill store (`.agents/skills/`):
|
|
82
82
|
|
|
83
83
|
```sh
|
|
84
|
-
npx @owlmeans/agent-skills
|
|
84
|
+
npx @owlmeans/agent-skills@^0.1.18-rc.12
|
|
85
85
|
```
|
|
86
86
|
|
|
87
87
|
The embedded files are version-matched to this package release. Do not edit them
|
package/agent-meta/manifest.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 2,
|
|
3
3
|
"package": "@owlmeans/flow",
|
|
4
|
-
"version": "0.1.18-rc.
|
|
5
|
-
"generatedAt": "2026-09-
|
|
4
|
+
"version": "0.1.18-rc.14",
|
|
5
|
+
"generatedAt": "2026-09-04T22:43:25.451Z",
|
|
6
6
|
"canonicalRepo": "https://github.com/owlmeans/common",
|
|
7
7
|
"entries": [
|
|
8
8
|
{
|
|
@@ -8,12 +8,12 @@ user-invocable: false
|
|
|
8
8
|
# @owlmeans/flow
|
|
9
9
|
|
|
10
10
|
**Layer:** Cross-cutting domain
|
|
11
|
-
**Install:** `"@owlmeans/flow": "^0.1.18-rc.
|
|
11
|
+
**Install:** `"@owlmeans/flow": "^0.1.18-rc.14"` in `dependencies`
|
|
12
12
|
|
|
13
13
|
A flow is a set of named **steps**, each offering named **transitions** to other steps. What makes
|
|
14
|
-
it worth using over a hand-rolled switch is that the whole live state — flow
|
|
15
|
-
|
|
16
|
-
what lets a workflow survive a redirect, a page load, or a process.
|
|
14
|
+
it worth using over a hand-rolled switch is that the whole live state — `flow`, `step`, `previous`,
|
|
15
|
+
`service`, `entityId`, `payload`, `message`, `ok` — serializes to a single compact string and
|
|
16
|
+
restores from it. That is what lets a workflow survive a redirect, a page load, or a process.
|
|
17
17
|
|
|
18
18
|
## Key exports
|
|
19
19
|
|
|
@@ -21,11 +21,15 @@ what lets a workflow survive a redirect, a page load, or a process.
|
|
|
21
21
|
|---|---|
|
|
22
22
|
| `makeFlowModel(flow, provider?)` | Build a driver. `flow` is a `ShallowFlow` **object** (no provider needed) or a **string** — tried as a flow name first, then as a serialized token. |
|
|
23
23
|
| `FlowModel` | `target` `entity` `enter` `steps` `state` `setState` `payload` `updatePayload` `step` `transitions` `transition` `next` `transit` `serialize` |
|
|
24
|
-
| `ShallowFlow` / `FlowStep` / `FlowTransition` / `FlowState` / `FlowPayload` | The definition
|
|
24
|
+
| `ShallowFlow` / `FlowStep` / `FlowTransition` / `FlowState` / `FlowPayload` / `SerializedFlow` | The definition, the live state, and the compact shape the token encodes |
|
|
25
|
+
| `Flow` | A `ShallowFlow` a provider resolved: it also carries the resolved `config` and the `prefabs` — one serialized entry state per initial step |
|
|
25
26
|
| `FlowProvider` | `(flow: string) => Promise<Flow>` — resolves a flow by name |
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
27
|
+
| `FlowConfig` / `WithFlowConfig` / `FlowConfigRecord` | `{ queryParam, services, modules, pathes, defaultFlow }`, the `flowConfig` field it sits on, and the config-record form of a definition |
|
|
28
|
+
| `flow(cfg, flow)` · `configureFlows(cfg, config)` | Register a definition as a `FLOW_RECORD` config record / set `FlowConfig` |
|
|
29
|
+
| `stdStabFlow`, `stdOidcFlow`, `stdOidpFlow`, `stdAuthFlow` (deprecated) | Built-in flows, with `StdAuthStep` / `OidcAuthStep` / `OidpAuthStep` naming their steps |
|
|
30
|
+
| `STD_STAB_FLOW` `STD_OIDC_FLOW` `STD_OIDP_FLOW` `STD_AUTH_FLOW` | Their names — deliberately short, because every one of them is spent inside a URL |
|
|
31
|
+
| `FLOW_RECORD` (`flow`) · `CFG_FLOW_PREFIX` (`flow`) · `TARGET_SERVICE` (`-`) · `FLOW_PLACEHOLDER` (`?`) · `FLOW_SEP` · `PAYLOAD_SEP` | Constants |
|
|
32
|
+
| `FlowError`, `FlowUnsupported`, `FlowTargetError`, `UnknownFlow`, `FlowStepError`, `FlowStepMissconfigured`, `UnknownFlowStep`, `UnknownTransition` | The error family, all registered with `ResilientError` |
|
|
29
33
|
|
|
30
34
|
## Defining a flow
|
|
31
35
|
|
|
@@ -87,22 +91,49 @@ returns `null`/`undefined` for an unknown name therefore breaks every restore
|
|
|
87
91
|
**Passing a `ShallowFlow` object needs no provider at all.** That is the server-friendly path: a
|
|
88
92
|
runtime whose flows are code it declares itself needs no registry to start one, only to restore one.
|
|
89
93
|
|
|
90
|
-
**`next()`
|
|
91
|
-
|
|
92
|
-
|
|
94
|
+
**`next()` answers with the first non-explicit outgoing transition**, and throws
|
|
95
|
+
`UnknownFlowStep('next')` when the step offers none. It is what lets a driver advance without
|
|
96
|
+
knowing the vocabulary, so mark every user-chosen or exceptional edge `explicit` — an unmarked
|
|
97
|
+
second edge silently becomes reachable as the automatic answer.
|
|
98
|
+
|
|
99
|
+
**`enter(step?)` only accepts a step marked `initial`**, and throws `FlowStepError('initial:<step>')`
|
|
100
|
+
otherwise. That is what makes a flow's entry points an explicit part of its definition rather than
|
|
101
|
+
whatever the caller happens to name.
|
|
93
102
|
|
|
94
103
|
**`FlowPayload` holds flat scalars only** — `string | number | boolean | null | undefined`. Anything
|
|
95
104
|
richer belongs in a record the payload points at. Payload is projected through the step's
|
|
96
|
-
`payloadMap` on serialization, so an unmapped key does not survive a round trip
|
|
105
|
+
`payloadMap` on serialization, so an unmapped key does not survive a round trip and a step with no
|
|
106
|
+
`payloadMap` at all carries no payload across.
|
|
107
|
+
|
|
108
|
+
**`updatePayload` merges; `transit` also merges.** Neither replaces the payload, so a key set early
|
|
109
|
+
in a flow keeps arriving at every later step whose `payloadMap` names it.
|
|
110
|
+
|
|
111
|
+
**The live state is `flow` `step` `previous` `entityId` `service` `payload` `message` `ok`.**
|
|
112
|
+
`service` is the target the flow is running *for*, set through `target()`; `entityId` is set through
|
|
113
|
+
`entity()` and survives serialization even when it is explicitly `null`.
|
|
97
114
|
|
|
98
115
|
**`reversible` is what keeps `previous`**, and is what a "back" transition needs to return to where
|
|
99
116
|
it came from.
|
|
100
117
|
|
|
101
118
|
## Where it runs
|
|
102
119
|
|
|
103
|
-
Client drivers are `@owlmeans/client-flow` (`
|
|
120
|
+
Client drivers are `@owlmeans/client-flow` (`makeBasicFlowService`) and `@owlmeans/web-flow`
|
|
121
|
+
(`makeFlowService`, which supplies the browser redirect the basic service refuses); they load
|
|
104
122
|
definitions from `FLOW_RECORD` config records through the config resource and carry the serialized
|
|
105
|
-
state in a query parameter (`FlowConfig.queryParam`).
|
|
123
|
+
state in a query parameter (`FlowConfig.queryParam`, defaulting to `flow`).
|
|
124
|
+
|
|
125
|
+
A step addresses its screen through `module` — the alias of the entrypoint the driver navigates to,
|
|
126
|
+
which is why a step is portable between apps that mount it at different paths. `service`, `module`
|
|
127
|
+
and `path` are plain strings, and a value prefixed with `$` is a reference resolved at load time
|
|
128
|
+
against `FlowConfig.services` / `modules` / `pathes` — which is how one definition is reused by
|
|
129
|
+
deployments that address different services. `TARGET_SERVICE` (`-`) in a step's `service` means
|
|
130
|
+
"whatever the state's own target is" rather than a named one.
|
|
131
|
+
|
|
132
|
+
A step with no `module` cannot be addressed, and the two client drivers raise
|
|
133
|
+
`FlowStepMissconfigured` at different moments: `FlowClient.proceed` in `@owlmeans/client-flow`
|
|
134
|
+
checks the step it is about to **enter**, before it transits; `FlowService.proceed` in
|
|
135
|
+
`@owlmeans/web-flow` checks the step the model is **standing on**. Either way the step named in the
|
|
136
|
+
error is the one missing the `module`.
|
|
106
137
|
|
|
107
138
|
There is **no server-side driver in this package**. A server or worker builds models directly from
|
|
108
139
|
`ShallowFlow` objects and supplies its own `FlowProvider` for restores — `@owlmeans/agent`'s
|
|
@@ -111,4 +142,9 @@ There is **no server-side driver in this package**. A server or worker builds mo
|
|
|
111
142
|
## Depends on
|
|
112
143
|
|
|
113
144
|
`@owlmeans/auth`, `@owlmeans/config`, `@owlmeans/error`, `@owlmeans/i18n`, `@owlmeans/resource`,
|
|
114
|
-
`@scure/base` (the token codec).
|
|
145
|
+
`@scure/base` (the token codec — base64url, no padding, over the JSON of `SerializedFlow`).
|
|
146
|
+
|
|
147
|
+
## Related
|
|
148
|
+
|
|
149
|
+
- [[client-flow]] — the client service and the runner a screen drives
|
|
150
|
+
- [[web-flow]] — the browser half: the `flow` query parameter and cross-service redirects
|
package/build/errors.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,SAAU,SAAQ,cAAc;IAC3C,OAAuB,QAAQ,EAAE,MAAM,CAAc;
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,SAAU,SAAQ,cAAc;IAC3C,OAAuB,QAAQ,EAAE,MAAM,CAAc;IAErD,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,OAAuB,QAAQ,EAAE,MAAM,CAAqC;IAE5E,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,OAAuB,QAAQ,EAAE,MAAM,CAAgC;IAEvE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,SAAS;IACxC,OAAuB,QAAQ,EAAE,MAAM,CAAiC;IAExE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,aAAc,SAAQ,SAAS;IAC1C,OAAuB,QAAQ,EAAE,MAAM,CAA8B;IAErE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,OAAuB,QAAQ,EAAE,MAAM,CAA4C;IAEnF,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,eAAgB,SAAQ,aAAa;IAChD,OAAuB,QAAQ,EAAE,MAAM,CAAqC;IAE5E,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,OAAuB,QAAQ,EAAE,MAAM,CAAwC;IAE/E,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF"}
|
package/build/errors.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,SAAU,SAAQ,cAAc;IACpC,MAAM,CAAU,QAAQ,GAAW,WAAW,CAAA;IAErD,YAAY,
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
|
package/build/helper.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGzE,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,YAAY,
|
|
1
|
+
{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGzE,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,YAAY,OAAO,CAAC,QAAQ,WAAW,KAAG,CAOxE,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,YAAY,OAAO,CAAC,GAAG,cAAc,UAAU,UAAU,KAAG,CAAC,GAAG,cAIxG,CAAA"}
|
package/build/state.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAa,WAAW,EAAE,MAAM,YAAY,CAAA;AAGjF,eAAO,MAAM,aAAa,
|
|
1
|
+
{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAa,WAAW,EAAE,MAAM,YAAY,CAAA;AAGjF,eAAO,MAAM,aAAa,SAAgB,MAAM,GAAG,WAAW,aAAa,YAAY,KAAG,OAAO,CAAC,SAAS,CAiJ1G,CAAA"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/utils/flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAkB,WAAW,EAAE,MAAM,aAAa,CAAA;AAKvF,eAAO,MAAM,cAAc,
|
|
1
|
+
{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/utils/flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAkB,WAAW,EAAE,MAAM,aAAa,CAAA;AAKvF,eAAO,MAAM,cAAc,SAAU,WAAW,SAAS,SAAS,KAAG,MAgCpE,CAAA;AAED,eAAO,MAAM,gBAAgB,UAAiB,MAAM,gBAAgB,YAAY,KAAG,OAAO,CAAC,SAAS,CAkCnG,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@owlmeans/flow",
|
|
3
|
-
"version": "0.1.18-rc.
|
|
3
|
+
"version": "0.1.18-rc.14",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -21,11 +21,11 @@
|
|
|
21
21
|
}
|
|
22
22
|
},
|
|
23
23
|
"dependencies": {
|
|
24
|
-
"@owlmeans/auth": "^0.1.18-rc.
|
|
25
|
-
"@owlmeans/config": "^0.1.18-rc.
|
|
26
|
-
"@owlmeans/error": "^0.1.18-rc.
|
|
27
|
-
"@owlmeans/i18n": "^0.1.18-rc.
|
|
28
|
-
"@owlmeans/resource": "^0.1.18-rc.
|
|
24
|
+
"@owlmeans/auth": "^0.1.18-rc.9",
|
|
25
|
+
"@owlmeans/config": "^0.1.18-rc.12",
|
|
26
|
+
"@owlmeans/error": "^0.1.18-rc.8",
|
|
27
|
+
"@owlmeans/i18n": "^0.1.18-rc.8",
|
|
28
|
+
"@owlmeans/resource": "^0.1.18-rc.9",
|
|
29
29
|
"@scure/base": "^2.3.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|