docs: update readmes

Author: pancsta

.github/BUMP

@@ -1 +1 @@
-30
+31

.github/workflows/go.yml

@@ -118,12 +118,13 @@ jobs:
           message: ${{ env.TESTS }}
           color: blue
 
-      - name: Badge - tests /pkg
-        uses: schneegans/[email protected]
-        with:
-          auth: ${{ secrets.GIST_SECRET }}
-          gistID: c6032233dc1d632732ecdc1a4c119850
-          filename: tests-pkg.json
-          label: tests /pkg
-          message: ${{ env.TESTS_PKG }}
-          color: blue
+# TODO fix
+#      - name: Badge - tests /pkg
+#        uses: schneegans/[email protected]
+#        with:
+#          auth: ${{ secrets.GIST_SECRET }}
+#          gistID: c6032233dc1d632732ecdc1a4c119850
+#          filename: tests-pkg.json
+#          label: tests /pkg
+#          message: ${{ env.TESTS_PKG }}
+#          color: blue

.github/workflows/linter.yml

@@ -5,7 +5,8 @@ on: [push]
 jobs:
   build:
 
-#    if: false  # Disable this job
+    # TODO fix timeouts
+    if: false  # Disable this job
 
     runs-on: ubuntu-latest
     strategy:

BREAKING.md

@@ -2,6 +2,26 @@
 
 Only `pkg/machine` and `pkg/states` adhere to semver. Semver of other packages is not guaranteed at the moment.
 
+## v0.13
+
+- `LogSteps` has been removed
+- `LogChanges` is now `2`
+- `Opts.DontLogID` is now `DontLogId`
+- `Transition.ID` is now `Id`
+- `SetLogId` is now `SemLogger.EnableId`
+- `GetLogId` is now `SemLogger.IsId`
+- `SetLogArgs` is now `SemLogger.SetArgs`
+- `GetLogArgs` is now `SemLogger.Args`
+- `SetLogger` is now `SemLogger.SetLogger`
+- `GetLogger` is now `SemLogger.Logger`
+- `SetLogLevel` is now `SemLogger.SetLevel`
+- `GetLogLevel` is now `SemLogger.Level`
+- `SetLoggerEmpty` is now `SemLogger.SetEmpty`
+- `SetLoggerSimple` is now `SemLogger.SetSimple`
+- `Tracer.MutationQueued` added
+- `AddBreakpoint` has `strict` added
+- `Logger` is now `LoggerFn`
+
 ## v0.12
 
 - `Opts.ID` and `Opts.ParentID` are now `Opts.Id`, `Opts.ParentId`

CHANGELOG.md

@@ -1,7 +1,7 @@
 [![](https://goreportcard.com/badge/github.com/pancsta/asyncmachine-go)](https://goreportcard.com/report/github.com/pancsta/asyncmachine-go)
 [![](https://pkg.go.dev/badge/github.com/pancsta/asyncmachine-go.svg)](https://pkg.go.dev/github.com/pancsta/asyncmachine-go)
-![](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/pancsta/c6032233dc1d632732ecdc1a4c119850/raw/loc.json)
 ![](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/pancsta/c6032233dc1d632732ecdc1a4c119850/raw/loc-pkg.json)
+![](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/pancsta/c6032233dc1d632732ecdc1a4c119850/raw/loc-tools.json)
 ![](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/pancsta/c6032233dc1d632732ecdc1a4c119850/raw/tests.json)
 ![](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/pancsta/c6032233dc1d632732ecdc1a4c119850/raw/tests-pkg.json)
 ![](https://img.shields.io/github/v/release/pancsta/asyncmachine-go)
@@ -17,7 +17,6 @@
     <a href="#documentation">Docs</a> .
     <a href="#development">Dev</a> .
     <a href="#faq">FAQ</a> .
-    <a href="#changes">Changes</a>
     <br />
 </div>
 
@@ -43,24 +42,25 @@ and [diagrams](https://github.com/pancsta/asyncmachine-go/pull/216).
 As a control flow library, it decides about running of predefined bits of code (transition handlers) - their order and
 which ones to run, according to currently active states (flags). Thanks to a [novel state machine](/pkg/machine/README.md),
 the number of handlers can be minimized while maximizing scenario coverage. It's lightweight, fault-tolerant by design,
-has rule-based mutations, and can be used to target virtually *any* step-in-time, in *any* workflow.
+has rule-based mutations, and can be used to target virtually *any* step-in-time, in *any* workflow. It's a low-level
+tool and provides acceptable performance.
 
 **asyncmachine-go** takes care of `context`, `select`, and `panic`, while allowing for graph-structured concurrency
-with [goroutine cancellation](https://github.com/pancsta/asyncmachine-go/pull/261). The history log and relations have
+with [goroutine cancelation](https://github.com/pancsta/asyncmachine-go/pull/261). The history log and relations have
 vector formats.
 
 It aims to create **autonomous** workflows with **organic** control flow and **stateful** APIs:
 
 - **autonomous** - automatic states, relations, context-based decisions
-- **organic** - relations, negotiation, cancellation
+- **organic** - relations, negotiation, cancelation
 - **stateful** - maintaining context, responsive, atomic
 
 <div align="center">
     <a href="https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/am-dbg/README.md">
     <img src="https://github.com/pancsta/assets/blob/main/asyncmachine-go/video-mouse.gif?raw=true" alt="TUI Debugger" /></a>
 </div>
 
-Each state represents:
+#### Each state represents
 
 - binary flag
 - node with relations
@@ -73,7 +73,7 @@ Each state represents:
 - lock
 - breakpoint
 
-Besides workflows, it can be used for **stateful applications** of any size - daemons, UIs, configs, bots, firewalls,
+Besides workflows, it can be used for **stateful applications of any size** - daemons, UIs, configs, bots, firewalls,
 synchronization consensus, games, smart graphs, microservice orchestration, robots, contracts, streams, DI containers,
 test scenarios, simulators, as well as **"real-time" systems** which rely on instant cancelation.
 
@@ -137,7 +137,7 @@ The top layers depend on the bottom ones.
   <tr>
     <td>.</td>
     <td>.</td>
-    <td colspan="9" align=center>🐇 <a href="pkg/machine">Machine API</a></td>
+    <td colspan="9" align=center>🐇 <a href="pkg/machine">Machine pkg</a></td>
     <td>.</td>
     <td>.</td>
   </tr>
@@ -189,13 +189,13 @@ err := amhelp.WaitForAll(ctx, time.Second,
     mach.When1(ss.BasicStatesDef.Ready, nil),
     // pre-mutation subscription
     whenPayload)
-// check cancellation
+// check cancelation
 if ctx.Err() != nil {
     return // state ctx expired
 }
 // check error
 if err != nil {
-    // err state mutation
+    // error state mutation
     client.Mach.AddErr(err, nil)
     return // no err required
 }
@@ -291,11 +291,11 @@ This monorepo offers the following importable packages, especially:
 
 Other packages:
 
-- [`/pkg/graph`](/pkg/graph) Multigraph of interconnected state machines.
+- [`/pkg/rpc`](/pkg/rpc) Remote state machines, with the same API as local ones.
 - [`/pkg/history`](/pkg/history) History tracking and traversal.
 - [`/pkg/integrations`](/pkg/integrations) NATS and other JSON integrations.
+- [`/pkg/graph`](/pkg/graph) Multigraph of interconnected state machines.
 - [`/pkg/node`](/pkg/node) Distributed worker pools with supervisors.
-- [`/pkg/rpc`](/pkg/rpc) Remote state machines, with the same API as local ones.
 - [`/pkg/pubsub`](/pkg/pubsub) Decentralized PubSub based on libp2p gossipsub.
 
 ## [Devtools](/tools)

README.md

@@ -1,13 +1,9 @@
 # Roadmap
 
-- negotiation testers (eg `CanAdd`)
-- more helpers for queue and history traversal
 - handlers for RPC workers
-- DB-based scheduler
-- NATS integration
+- handler loop based scheduler
 - go1.22 traces
 - inference
-- dynamic state schemas
 - optimizations
 - tutorials
 

ROADMAP.md

@@ -366,7 +366,7 @@ tasks:
 
   lint-go:
     cmds:
-      - $(go env GOPATH)/bin/golangci-lint run --fix --timeout 5m
+      - $(go env GOPATH)/bin/golangci-lint run --fix --timeout 15m
 
   lint-md:
     cmds:

Taskfile.yml

@@ -36,10 +36,18 @@ AM_DBG_ADDR=localhost:6831
 # defaults to ""
 AM_HEALTHCHECK=1
 
-# set the log level 0-6
+# machine text log level 0-5
 # defaults to "0"
 AM_LOG=2
 
+# log transition steps
+# defaults to ""
+AM_LOG_STEPS=1
+
+# log graph structure (mut traces, pipes, etc)
+# defaults to ""
+AM_LOG_GRAPH=1
+
 # enable file logging (use machine ID as name)
 # defaults to ""
 AM_LOG_FILE=1

docs/env-configs.md

@@ -92,7 +92,7 @@ am.Schema{
 }
 ```
 
-State names have a predefined **naming convention** which is `CamelCase`.
+State names have a predefined [naming convention](#naming-convention) which is `CamelCase`.
 
 **Example** - synchronous state
 
@@ -548,8 +548,9 @@ Once a transition begins to execute, it goes through the following steps:
 
 ### Transition Handlers
 
-**Asyncmachine** implements **AOP** ([Aspect Oriented Programming](https://en.wikipedia.org/wiki/Aspect-oriented_programming))
-through a handler naming convention. Use [`LogEverything`](#logging) to see a full list of each transition's handlers.
+The **asyncmachine** implements **AOP** ([Aspect Oriented Programming](https://en.wikipedia.org/wiki/Aspect-oriented_programming))
+through a handler naming convention (either via a suffix or concatenation). Use [`LogEverything`](#logging) to see a
+full list of each transition's handlers.
 
 **State handler** is a struct method with a predefined suffix or prefix, which receives an [Event struct](#event-struct).
 There are [negotiation handlers](#negotiation-handlers) (returning a `bool`) and [final handlers](#final-handlers) (with
@@ -598,6 +599,20 @@ List of handlers during a transition from `Foo` to `Foo Bar`, in the order of ex
 
 Self handlers provide a simple alternative to [`Multi` states](#multi-states), while fully maintaining [state clocks](#clock-and-context).
 
+#### Transition Sub-handler
+
+**State sub-handler** is a struct method which does not get called directly via the event loop, but also lacks locking,
+because of which, they can only be called by other handlers (either top level or sub-handlers). There is a [naming convention](#naming-convention)
+for these handlers, but no conventions for either parameters not return values.
+
+Example:
+
+- `hListProcesses(name string) ([]string, error)`
+- `hDoFoo() error`
+
+Sub-handlers are useful when combined with `EvalToGetter` from `pkg/helpers`, as well as for sharing code between
+handlers, without worrying about calling it from a non-handler code-path.
+
 ### Defining Handlers
 
 Handlers are defined as struct methods. Each machine can have many handler structs bound to itself using
@@ -1789,13 +1804,22 @@ func Msg(msgTx *Msg) {
 - wait contexts
 - Dispose
 - WhenDisposed
-- RegisterDisposalHandler
+- HandleDispose
 
 ### Dynamically Generating States
 
 // TODO
 
-- Machine.SetStrcut
+- Machine.SetSchema
+- schema versions
+
+### Naming Convention
+
+- states: CamelCase, eg `ProcessRunning`
+- handlers: CamelCase, eg `ProcessRunningState`
+- sub-handlers: CamelCase, eg `hListRunning`
+  - TODO dedicated section with examples
+- regular methods: none, eg `privMethod`, `PubMethod`
 
 ## Cheatsheet