DEV Community: Can Burak Sofyalioglu

Road to State Machines VI - But What If Independent Work Finishes in a Different Order?

Can Burak Sofyalioglu — Sat, 24 Oct 2026 18:56:51 +0000

Our order can now wait for a shipping inquiry without pretending that shipping has already succeeded.

The request receives an identifier. The order enters CHECKING_SHIPPING. A matching response may move it to READY_TO_SHIP, while a timeout or unsuccessful result returns it to PAID.

But Part V ended with another requirement:

Before proceeding, the system must obtain both a carrier response and an inventory result.

Those operations may finish in either order.

The carrier might answer first. The inventory system might answer first. One might fail while the other is still working.

How do we combine their results without depending on a particular sequence?

Start with the smallest solution

We could simply perform the checks one after another:

carrier_available = await check_carrier(request)

if carrier_available:
    inventory_available = await check_inventory(request)

This is a reasonable design.

It has an obvious execution order. If the carrier rejects the destination, we avoid the inventory lookup entirely. There is little coordination logic to maintain.

We should preserve that option when the work is cheap, the second operation depends on the first, or avoiding unnecessary requests matters more than overlapping their execution.

But suppose both checks can begin from information we already possess. Neither needs the other’s result.

The serial implementation imposes a dependency that the business rule does not require:

Carrier finishes
        ↓
Inventory may begin

What we actually require is different:

Carrier succeeds
        +
Inventory succeeds
        ↓
The combined check succeeds

Both must finish successfully. Neither must finish first.

Separate checking inventory from reserving it

Before introducing concurrent execution, we need to settle what the inventory operation does.

Checking whether stock is available is not the same as reserving it.

Operation	What it establishes
Check inventory	The inventory service reports whether the order’s items are currently available.
Reserve inventory	The inventory service commits stock to this order under its reservation policy.
Release inventory	The service removes an earlier reservation.

The end of Part V raised inventory reservation as a future requirement. We will reach its failure consequences later in this part.

First, we will implement two read-only availability checks. Neither books a shipment nor reserves stock.

This lets us establish the coordination rule without quietly introducing external changes that would need to be undone.

Our inventory adapter will look up the order’s item requirements using its identifier. We are not adding an item model in this lesson. As with the destination in Part V, those requirements remain fixed during one check.

READY_TO_SHIP therefore remains a state in our local simulation. It does not promise that stock is reserved or that carrier capacity will remain available indefinitely.

Fork the work, then join the results

Starting independent branches from one request is commonly described as a fork. Combining their results before continuing is a join.

Our intended flow is:

                    Shipping check
                          │
                         fork
                     ┌────┴────┐
                     ▼         ▼
                 Carrier    Inventory
                  check       check
                     │         │
                     └────┬────┘
                         join
                          │
                          ▼
                  Combined result

The join is not simply the point where two lines meet in a diagram.

It must answer a precise question:

Have all the required branches for this particular request succeeded?

These are two valid execution sequences:

First result	Second result	Combined outcome
Carrier available	Inventory available	Available
Inventory available	Carrier available	Available

After the first successful result, the combined answer is still incomplete.

Starting both operations is not enough. Finishing either operation is not enough.

Readiness requires a successful result from every required branch of the current check.

Why a completion counter is insufficient

We might begin with:

completed_checks = 0

Then increment it whenever a successful result arrives:

completed_checks += 1

if completed_checks == 2:
    report_available()

Now deliver these messages:

Carrier available
Carrier available again

The counter reaches two.

The inventory system has not answered.

We counted messages when the rule required distinct prerequisites.

A duplicate result must not satisfy another branch’s obligation. We need to remember which branch answered, not merely how many messages arrived.

We also need to retain the request identifier from Part V. A carrier answer from yesterday must not combine with an inventory answer for today’s request.

The group of results belongs to:

order identifier
+
check request identifier

Within that group, each result belongs to a named branch.

This is the coordination problem described by the Aggregator pattern in Enterprise Integration Patterns: collect related messages, determine when enough information has arrived, and produce one combined result. The pattern separates correlation, completeness, and the rule used to combine results.[2]

For our case, those decisions are:

Keep the order’s lifecycle intact

We do not need to expose every partial combination as another OrderState.

The order can remain in:

CHECKING_SHIPPING

while a smaller coordination component tracks the branch results.

This preserves the lifecycle from Part V:

PAID
    ↓ CHECK_SHIPPING
CHECKING_SHIPPING
    ↓ combined positive result
READY_TO_SHIP
    ↓ SHIP_ORDER
SHIPPED

The meaning of the positive result is now broader.

Previously, SHIPPING_AVAILABLE meant that the carrier inquiry succeeded. In this version, it means that both required availability checks succeeded.

That is an intentional change in the operation’s contract. A raw carrier response must no longer go directly to the order as SHIPPING_AVAILABLE. It must first pass through the component that combines the results.

The outer ShippingCheckResult envelope can remain unchanged:

@dataclass(frozen=True)
class ShippingCheckResult:
    order_id: str
    request_id: str
    event: OrderEvent

The order receives one combined answer through the same interface.

Partial progress belongs inside the check, not in the order’s public lifecycle vocabulary.

Give branch results their own vocabulary

Let’s distinguish where a reply came from and what it reports:

from dataclasses import dataclass, replace
from enum import Enum


class CheckBranch(Enum):
    CARRIER = "carrier"
    INVENTORY = "inventory"


class CheckOutcome(Enum):
    AVAILABLE = "available"
    UNAVAILABLE = "unavailable"
    FAILED = "failed"


@dataclass(frozen=True)
class BranchResult:
    order_id: str
    request_id: str
    branch: CheckBranch
    outcome: CheckOutcome

UNAVAILABLE means that the lookup completed and returned a negative answer.

FAILED means that an expected service failure prevented us from obtaining an answer.

Those outcomes both prevent readiness under our current policy, but they do not say the same thing.

We can now retain partial progress:

@dataclass(frozen=True)
class CheckProgress:
    request: ShippingCheck
    carrier: CheckOutcome | None = None
    inventory: CheckOutcome | None = None
    conclusion: OrderEvent | None = None

The existing ShippingCheck contains the order identifier, request identifier, and copied delivery address.

The two branch fields initially contain None, meaning no result has been accepted for that branch.

conclusion is also initially absent. Once set, this check is closed.

For example:

request = check-A
carrier = AVAILABLE
inventory = None
conclusion = None

means that one prerequisite has succeeded and the check is still waiting.

This is not “half an order transition.” It is a complete, valid configuration of the coordination process.

Decide what failure means before writing the handler

There are several reasonable completion policies.

We could wait for every result, even after one branch fails. That would collect more diagnostic information.

We could stop once success becomes impossible. That would avoid waiting for an answer that can no longer change the overall decision.

For these read-only checks, we will choose the second policy:

Accepted branch result	Coordinator action
First positive result	Record it and continue waiting
Second distinct positive result	Conclude `SHIPPING_AVAILABLE`
Any negative result	Conclude `SHIPPING_UNAVAILABLE`
Any expected lookup failure	Conclude `SHIPPING_CHECK_FAILED`
Duplicate of an accepted result	Do not count it again
Result for another request	Do not apply it

Once a conclusion exists, later replies cannot reopen the check.

If different failures compete, the first decisive result processed by the coordinator determines the reported outcome. This is an ordering policy, not a claim that the same failure detail will win under every possible schedule.

For successful checks, however, the completion order must not matter.

Apply one branch result at a time

The following function receives the current progress and one reply. It returns updated progress and, only when the check first concludes, a combined result.

def accept_branch_result(
    progress: CheckProgress,
    reply: BranchResult,
) -> tuple[CheckProgress, ShippingCheckResult | None]:
    request = progress.request

    if reply.order_id != request.order_id:
        raise ValueError(
            "Result belongs to a different order."
        )

    if not isinstance(reply.branch, CheckBranch):
        raise TypeError("Unknown check branch.")

    if not isinstance(reply.outcome, CheckOutcome):
        raise TypeError("Unknown check outcome.")

    if reply.request_id != request.request_id:
        return progress, None

    if progress.conclusion is not None:
        return progress, None

    previous = (
        progress.carrier
        if reply.branch is CheckBranch.CARRIER
        else progress.inventory
    )

    if previous is not None:
        if previous is not reply.outcome:
            raise ValueError(
                "Conflicting result for one branch."
            )

        return progress, None

    if reply.branch is CheckBranch.CARRIER:
        updated = replace(
            progress,
            carrier=reply.outcome,
        )
    else:
        updated = replace(
            progress,
            inventory=reply.outcome,
        )

    if reply.outcome is CheckOutcome.FAILED:
        event = OrderEvent.SHIPPING_CHECK_FAILED

    elif reply.outcome is CheckOutcome.UNAVAILABLE:
        event = OrderEvent.SHIPPING_UNAVAILABLE

    elif (
        updated.carrier is CheckOutcome.AVAILABLE
        and updated.inventory is CheckOutcome.AVAILABLE
    ):
        event = OrderEvent.SHIPPING_AVAILABLE

    else:
        return updated, None

    updated = replace(updated, conclusion=event)

    return updated, ShippingCheckResult(
        order_id=request.order_id,
        request_id=request.request_id,
        event=event,
    )

The function does not call either service. It does not change the order. It calculates the consequence of receiving one result.

An identical duplicate leaves progress unchanged.

A contradictory second answer for an already recorded branch raises an error while the group is still open. Our protocol expects one final answer per branch. It does not support silently revising an earlier answer.

After the group closes, subsequent replies are irrelevant to its decision. A production diagnostic path could still record them, but they cannot authorize another transition.

We now have a small stateful process inside the larger workflow.

Its control condition is whether it has concluded. Its supporting data identifies the request and the accepted branch outcomes.

Test the join without relying on task scheduling

Let’s construct a request and its two successful replies:

request = ShippingCheck(
    order_id="order-66",
    request_id="check-A",
    delivery_address="Istanbul",
)

carrier_available = BranchResult(
    order_id=request.order_id,
    request_id=request.request_id,
    branch=CheckBranch.CARRIER,
    outcome=CheckOutcome.AVAILABLE,
)

inventory_available = replace(
    carrier_available,
    branch=CheckBranch.INVENTORY,
)

Now test both possible success orders:

for first, second in (
    (carrier_available, inventory_available),
    (inventory_available, carrier_available),
):
    progress = CheckProgress(request)

    progress, result = accept_branch_result(
        progress,
        first,
    )

    assert result is None
    assert progress.conclusion is None

    progress, result = accept_branch_result(
        progress,
        second,
    )

    assert result is not None
    assert result.event is OrderEvent.SHIPPING_AVAILABLE

    closed = progress

    progress, repeated = accept_branch_result(
        progress,
        second,
    )

    assert progress == closed
    assert repeated is None

Neither branch can complete the join alone. Either can complete it when its counterpart has already succeeded.

The last assertions verify another property: a closed check does not produce a second combined result when a reply repeats.

That is a local property of this coordinator instance. It is not an exactly-once delivery guarantee across crashes or restarts.

Now test the counter mistake directly:

progress = CheckProgress(request)

progress, _ = accept_branch_result(
    progress,
    carrier_available,
)

after_first = progress

progress, result = accept_branch_result(
    progress,
    carrier_available,
)

assert progress == after_first
assert progress.inventory is None
assert result is None

Two carrier messages still satisfy only the carrier prerequisite.

An inventory result from an older request must also remain irrelevant:

stale_inventory = replace(
    inventory_available,
    request_id="older-check",
)

progress, result = accept_branch_result(
    progress,
    stale_inventory,
)

assert progress == after_first
assert progress.inventory is None
assert result is None

Finally, a negative answer closes the current check:

inventory_unavailable = replace(
    inventory_available,
    outcome=CheckOutcome.UNAVAILABLE,
)

progress, result = accept_branch_result(
    progress,
    inventory_unavailable,
)

assert result is not None
assert result.event is OrderEvent.SHIPPING_UNAVAILABLE

If a later positive reply arrives, it does not reverse this conclusion. Starting another inquiry requires a new request identifier and a new CheckProgress.

An older model for independent conditions

Carl Adam Petri’s 1962 dissertation, Kommunikation mit Automaten, investigated the foundations of communication between computational mechanisms.[3]

Petri nets provide a way to model concurrent processes using places, transitions, and tokens. Places describe conditions, tokens mark which conditions currently hold, and transitions consume and produce tokens. The token distribution is called a marking.[4]

The successful path of our check can be sketched as:

                 (check requested)
                         │
                       [fork]
                    ┌────┴────┐
                    ▼         ▼
          (carrier pending) (inventory pending)
                    │         │
          [carrier succeeds] [inventory succeeds]
                    │         │
                    ▼         ▼
           (carrier passed) (inventory passed)
                    └────┬────┘
                       [join]
                         │
                         ▼
                   (checks passed)

Parentheses represent places; brackets represent transitions.

The join requires a token from both successful branches. Firing it consumes those prerequisites and produces the combined completion condition.[4]

This drawing shows only the successful path. Negative results and abandonment need additional paths.

Our Python coordinator is not a general Petri-net engine. But it applies the same useful distinction: independent conditions can become true in either order, while a later action requires their conjunction.

The diagram does not make network calls atomic. It describes when the modeled continuation becomes eligible.

Did we escape state machines?

No.

A bounded set of branch outcomes can still be represented by a finite machine with a state for every combination.

For two branches, that may even be manageable.

The problem is not that a flat FSM is incapable of describing the behavior. The problem is that manually naming every combination makes the independent structure harder to see.

Our representation keeps that structure visible:

Carrier progress
+
Inventory progress
+
Completion rule

The full configuration still has combinations. We have organized them rather than eliminated them.

This is also why the join is more precise than another large lifecycle label. It states which conditions must coexist before the process continues.

Run the branches concurrently without letting them mutate the order

We can now connect the decision logic to asynchronous work.

Python’s TaskGroup starts and owns related tasks, waits for their completion, and propagates unexpected failures. Its task management does not decide whether our business prerequisites passed; that remains the coordinator’s responsibility.[1]

The following executor replaces the single-carrier executor from Part V.

Both adapters receive the immutable ShippingCheck. The carrier adapter uses its destination. The inventory adapter resolves the fixed item requirements using its order identifier.

Expected service failures are translated into AvailabilityLookupError:

import asyncio
from typing import Awaitable, Callable


class AvailabilityLookupError(Exception):
    pass


AvailabilityLookup = Callable[
    [ShippingCheck],
    Awaitable[bool],
]

Now execute and combine the two branches:

async def execute_check(
    request: ShippingCheck,
    carrier: AvailabilityLookup,
    inventory: AvailabilityLookup,
    inbox: asyncio.Queue[ShippingCheckResult],
) -> None:
    progress = CheckProgress(request)

    replies: asyncio.Queue[BranchResult] = (
        asyncio.Queue(maxsize=2)
    )

    async def run_branch(
        branch: CheckBranch,
        lookup: AvailabilityLookup,
    ) -> None:
        try:
            available = await lookup(request)

        except AvailabilityLookupError:
            outcome = CheckOutcome.FAILED

        else:
            if type(available) is not bool:
                raise TypeError(
                    "Availability lookup must return bool."
                )

            outcome = (
                CheckOutcome.AVAILABLE
                if available
                else CheckOutcome.UNAVAILABLE
            )

        await replies.put(
            BranchResult(
                order_id=request.order_id,
                request_id=request.request_id,
                branch=branch,
                outcome=outcome,
            )
        )

    result: ShippingCheckResult | None = None

    async with asyncio.TaskGroup() as group:
        workers = (
            group.create_task(
                run_branch(CheckBranch.CARRIER, carrier)
            ),
            group.create_task(
                run_branch(CheckBranch.INVENTORY, inventory)
            ),
        )

        while result is None:
            reply = await replies.get()

            try:
                progress, result = accept_branch_result(
                    progress,
                    reply,
                )
            finally:
                replies.task_done()

        for worker in workers:
            if not worker.done():
                worker.cancel()

    await inbox.put(result)

The scheduling callback from Part V now supplies both adapters when it starts this executor.

Neither branch receives the mutable order. Each produces a BranchResult.

One coordinator processes those results sequentially and updates its own local CheckProgress. Only the combined result enters the order’s inbox.

The private queue has room for the two messages these adapters can produce. Its FIFO behavior orders arrivals to this coordinator; it does not impose an order on events in remote services.[5]

We have separated two forms of activity:

External work overlaps. Local decisions about the collected results remain sequential.

A finished task is not necessarily a successful prerequisite

An inventory adapter returning False has completed normally as a Python task.

It has not satisfied the inventory prerequisite.

That distinction is why we translate the return value into an explicit outcome rather than treating task completion as business success.

The executor catches only the expected AvailabilityLookupError. An invalid return type or another programming error is not silently converted into “unavailable.”

On a decisive negative result or expected lookup failure, the coordinator requests cancellation of unfinished sibling tasks. The task group waits for them to finish their cleanup before the executor publishes the combined result.[1]

The adapters must use bounded I/O waits and cooperate with cancellation. A task that blocks the event loop or suppresses cancellation can still delay cleanup.

The task group gives the asynchronous work a lifetime boundary. It does not make arbitrary adapter code reliable.

For a simple case with no need to inspect partial results, a task group followed by an all() check could be enough. Our explicit coordinator earns its place when branch identity, duplicates, stale messages, and early completion rules need to be examined and tested separately.

What happens to the timeout from Part V?

The order’s existing timeout still applies to the entire ShippingCheck.

It is associated with the same request identifier, not separately with “the first branch” or “the second branch.”

Consider:

Step	What happens	Order behavior
1	Check A begins	Enter `CHECKING_SHIPPING`
2	Carrier A succeeds	No aggregate result yet
3	The overall timeout for A is handled	Return to `PAID`
4	Inventory A succeeds	Coordinator may produce a result for A
5	That result reaches the order	Ignore it because A is no longer outstanding

The outer handler from Part V still checks both the order’s state and the request identifier.

Even a correctly combined result can arrive too late to affect the order.

An overall timeout does not automatically cancel the executor. The surrounding runtime may cancel that task to stop unnecessary work, but the correlation check remains necessary because completion and cancellation can race.

Nor does returning to PAID restore or remove anything in another service. That is safe here because both branches were explicitly defined as read-only inquiries.

We have preserved Part V’s distinction:

Stopping our wait is not proof that remote work stopped.

Both positive replies are not a distributed transaction

Suppose the carrier answers at one moment and inventory answers slightly later.

Our join records two positive observations. It does not prove that both conditions will remain true when another operation eventually tries to book a shipment or reserve stock.

It also does not create one simultaneous snapshot across two services.

For this lesson, the combined result authorizes the next step of our local simulation under the fixed-input assumptions. A production policy might additionally require quotation expiry, inventory holds, or revalidation when committing the real operation.

Those requirements should be introduced explicitly.

Otherwise, the reassuring word READY can claim more than the system actually established.

Now replace the stock check with a reservation

We can now see why the earlier distinction mattered.

Imagine that the inventory branch actually reserves stock:

Inventory reservation succeeds.
Carrier check fails.
The combined operation cannot proceed.

Discarding CheckProgress would not release the reservation.

Cancelling a local task would not necessarily release it either. The inventory service may already have committed the change.

We need another operation:

ReserveInventory
        ↓ later failure
ReleaseReservation

A compensating action counteracts a completed business operation when a larger process cannot finish. It is application-specific, may fail itself, and does not necessarily restore the exact earlier world.[6]

For this example, a release operation would need the reservation identifier. If release fails, the system must retain enough information to continue recovery rather than quietly return to an ordinary state.

An even harder case is:

Reservation succeeds remotely.
Its response is lost.
The local request times out.

Now the system does not know whether a reservation exists.

That requires durable request identity, a way to reconcile the remote outcome, and safe retry or compensation rules. A join condition alone does not supply those mechanisms.

This is why our current executor must not be renamed reserve_inventory without changing its contract and recovery design.

We have implemented concurrent observations. We have not implemented a distributed transaction.

What must remain true as we add more branches?

The code is small, but its correctness depends on several explicit rules.

Each run has one order identifier and one request identifier. Each required branch contributes at most one accepted final result. Success is produced only after every required branch succeeds. A closed run cannot be reopened by a duplicate or late reply.

These rules are independent of which branch happens to finish first.

They also determine what should be tested. Beyond the success permutations, useful cases include a failure before any success, a failure after one success, conflicting replies while a run is open, a reply for another order, and a result arriving after the outer order has timed out.

The runtime tests should separately check that unexpected exceptions propagate and that cancelling the executor cleans up its child tasks. Neither concern should be hidden inside the pure combination logic.

The current implementation still stores its progress in memory. A process crash loses the partial results and the queued output. Producing at most one result during one invocation is not durable exactly-once execution.

That limitation has not changed.

The order and the concurrent work now have different responsibilities

The order’s state machine answers:

Is this combined outcome applicable to the request the order is currently waiting for?

The coordinator answers:

Do the results of the required branches justify producing that combined outcome?

The adapters answer their own service questions.

The coordinator is stateful, but it does not own the order’s lifecycle.

The adapters perform work, but they do not decide when the order becomes ready.

That division keeps independent work from becoming independent mutation of the same record.

But who protects that ownership boundary?

Our order consumer processes its inbox sequentially.

Yet the code that created the mutable Order may still hold a reference to it. Another component could assign its status without sending a message. A queued command could also contain a mutable object that its sender changes after submission.

More queues would not automatically prevent either problem.

We have learned how to collect independent results into one decision. The next problem is making sure that one authority actually controls the state affected by that decision.

When many orders are active, who owns each order’s record, who may change it, and how should every other component communicate with that owner?

References

[1] Python Software Foundation, Coroutines and Tasks. Concurrent task execution, task groups, exception propagation, and cancellation. The example uses APIs available in Python 3.11 and later.

[2] Gregor Hohpe and Bobby Woolf, “Aggregator”, Enterprise Integration Patterns. Correlation, completeness conditions, and combining related messages.

[3] Carl Adam Petri, Kommunikation mit Automaten, doctoral dissertation, 1962. University of Hamburg archival record.

[4] Carl Adam Petri and Wolfgang Reisig, “Petri Net”, Scholarpedia, 3(4):6477, 2008. Places, transitions, tokens, and the modeling of concurrent processes.

[5] Python Software Foundation, asyncio Queues. FIFO behavior, bounded queues, and task bookkeeping.

[6] Microsoft, Compensating Transaction Pattern, Azure Architecture Center. Application-specific compensation, recovery information, and failures during compensating work.

Part V - But How Does the Machine Wait for Something That Happens Later?

Can Burak Sofyalioglu — Sat, 03 Oct 2026 15:21:31 +0000

Our shipping transition now considers more than the order’s status.

It requires a valid paid order and a supported delivery address. The operation that changes the order and the function that lists available actions consult the same transition definition.

That works because the address guard can answer from information already available in the program.

But Part IV ended with a different requirement:

The carrier must confirm whether it can accept a shipment to this destination.

That answer may arrive later. The request may fail. Another command may arrive while we wait.

How do we represent the order during that interval?

Start by making the external question explicit

We should first distinguish three operations that are easy to collapse into one:

Operation	What it establishes
Check availability	The carrier reports whether it currently supports the proposed shipment.
Book a shipment	The carrier accepts a request to arrange a shipment.
Confirm dispatch	There is evidence that the package has actually been dispatched.

For this part, we will implement only a read-only availability inquiry. It reserves nothing and dispatches nothing. Our existing ship_order() operation will remain a local simulation.

This boundary matters when handling failures. Repeating a read-only inquiry is different from potentially booking the same package twice.

We will also keep the example’s availability policy fixed for an unchanged destination. Real bookings may require fresh validation, expiring quotations, or capacity reservations. Those are additional requirements, not guarantees we get from recording an availability response.

Why not just wait inside the shipping function?

We could call the carrier, wait for an answer, and then continue:

For a small request that has no other work to handle while waiting, this may be sufficient. A state machine does not require a message queue merely because a network call exists.

But our current order would remain PAID throughout the wait.

Another caller could not distinguish:

Paid, with no availability inquiry started

from:

Paid, with an inquiry already in progress

Both could attempt to start the operation.

Making the function asynchronous does not resolve that modeling problem. In Python, an await can suspend a task while the event loop runs other tasks. It does not, by itself, establish which task owns the order or prevent another task from acting on the same record.[1]

We need to represent the unfinished work.

Give waiting a place in the lifecycle

Let’s separate asking the question from using its answer.

We add a CHECK_SHIPPING command. An accepted command starts an availability inquiry and moves the order into CHECKING_SHIPPING.

A positive response moves it to READY_TO_SHIP. Only then does our simulated SHIP_ORDER command become eligible.

This deliberately changes the rule from Part IV. PAID + SHIP_ORDER is no longer sufficient.

The new states represent different behavior:

State	What the machine should accept next
`PAID`	A request to check shipping availability
`CHECKING_SHIPPING`	A result for the outstanding inquiry
`READY_TO_SHIP`	The simulated shipping command
`SHIPPED`	No further command in our current lifecycle

We are not adding states merely because an operation takes time. We are adding them because the set of eligible inputs changes while that operation is outstanding.

Replace the state and command definitions with:

class OrderState(Enum):
    CREATED = "created"
    PAID = "paid"
    CHECKING_SHIPPING = "checking_shipping"
    READY_TO_SHIP = "ready_to_ship"
    SHIPPED = "shipped"


class OrderCommand(Enum):
    CAPTURE_PAYMENT = "capture_payment"
    CHECK_SHIPPING = "check_shipping"
    SHIP_ORDER = "ship_order"

READY_TO_SHIP does not claim that a package has been booked or dispatched. It records that our prerequisite inquiry succeeded.

An answer to a question is not the completion of the entire workflow.

Remember what we are waiting for

A waiting state alone is insufficient.

Suppose the carrier returns an answer. Which order does it concern? Which inquiry? Which destination did we submit?

Let’s retain the request:

@dataclass(frozen=True)
class ShippingCheck:
    order_id: str
    request_id: str
    delivery_address: str

The request contains a copy of the destination, not a reference to the mutable order.

We then extend Order:

@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: OrderState = OrderState.CREATED
    payment: Optional[Payment] = None
    shipping_check: Optional[ShippingCheck] = None

Payment remains unchanged.

While checking availability, shipping_check identifies the outstanding request. After a successful response, we retain it to identify the destination that was checked.

This is an example of a correlation identifier: a value carried from a request into its reply so the receiver can connect the two. Enterprise Integration Patterns describes this request–reply relationship explicitly.[2]

The order identifier answers:

Which order?

The request identifier answers:

Which particular inquiry for that order?

Those are not interchangeable.

Extend the invariants with the new states

The payment rule still applies: every state after CREATED requires the captured payment record.

We also need rules for the shipping inquiry:

Lifecycle state	Required shipping-check data
`CREATED`, `PAID`	No active or accepted check
`CHECKING_SHIPPING`	The request currently awaiting a result
`READY_TO_SHIP`, `SHIPPED`	The request whose positive result was accepted

For this model, the recorded destination must match the order’s destination. We have not introduced an address-editing operation that invalidates and restarts a check.

Replace the validator with:

def validate_order(order: Order) -> None:
    if not isinstance(order.status, OrderState):
        raise InvalidOrderState(
            "status must be an OrderState member."
        )

    if order.status is OrderState.CREATED:
        if order.payment is not None:
            raise InvalidOrderState(
                "A created order cannot contain a captured payment."
            )
    elif not isinstance(order.payment, Payment):
        raise InvalidOrderState(
            "This state requires a Payment record."
        )

    needs_check = order.status in (
        OrderState.CHECKING_SHIPPING,
        OrderState.READY_TO_SHIP,
        OrderState.SHIPPED,
    )

    check = order.shipping_check

    if needs_check:
        if not isinstance(check, ShippingCheck):
            raise InvalidOrderState(
                "This state requires a ShippingCheck."
            )

        if (
            not check.request_id
            or check.order_id != order.id
            or check.delivery_address != order.delivery_address
        ):
            raise InvalidOrderState(
                "Shipping check does not match the order."
            )

    elif check is not None:
        raise InvalidOrderState(
            "No shipping check belongs in this state."
        )

This prevents a result for one destination from being silently used after someone changes the order to another destination.

It does not prove that the carrier sent a positive response. That depends on how we control the transition into READY_TO_SHIP.

As before, validating a snapshot and validating the path into that snapshot are separate responsibilities.

A reply is an event, not another shipping command

The user requests a check. The carrier reports an outcome.

Let’s give those outcomes names:

class OrderEvent(Enum):
    SHIPPING_AVAILABLE = "shipping_available"
    SHIPPING_UNAVAILABLE = "shipping_unavailable"
    SHIPPING_CHECK_FAILED = "shipping_check_failed"
    SHIPPING_CHECK_TIMED_OUT = "shipping_check_timed_out"

They have different meanings.

SHIPPING_UNAVAILABLE means the inquiry completed and returned a negative answer.

SHIPPING_CHECK_FAILED means an expected lookup failure prevented us from obtaining an answer.

SHIPPING_CHECK_TIMED_OUT means our application stopped waiting for that inquiry. It does not mean the carrier answered negatively.

The last event comes from our timer, not the carrier.

All four can use the same envelope:

@dataclass(frozen=True)
class ShippingCheckResult:
    order_id: str
    request_id: str
    event: OrderEvent

For this part, a negative answer, a lookup failure, or a timeout returns the order to PAID. That means no usable availability confirmation is retained, and another check may be requested.

This policy is safe for our read-only inquiry. We must not generalize it to a shipment-booking request: a lost booking response could leave an actual booking in the external system.

Keep the new behavior in the transition table

We retain the Transition class and the local has_supported_address() guard from Part IV.

The local guard remains useful as an initial filter. It can reject a destination before we contact the carrier. Passing it no longer claims that all shipping conditions have been satisfied.

Replace the transition table with:

TRANSITIONS: Mapping[
    tuple[OrderState, OrderCommand | OrderEvent],
    Transition,
] = MappingProxyType({
    (
        OrderState.CREATED,
        OrderCommand.CAPTURE_PAYMENT,
    ): Transition(
        target=OrderState.PAID,
    ),

    (
        OrderState.PAID,
        OrderCommand.CHECK_SHIPPING,
    ): Transition(
        target=OrderState.CHECKING_SHIPPING,
        guard=has_supported_address,
        rejection_reason="The delivery address is not supported.",
    ),

    (
        OrderState.READY_TO_SHIP,
        OrderCommand.SHIP_ORDER,
    ): Transition(
        target=OrderState.SHIPPED,
    ),

    (
        OrderState.CHECKING_SHIPPING,
        OrderEvent.SHIPPING_AVAILABLE,
    ): Transition(
        target=OrderState.READY_TO_SHIP,
    ),

    (
        OrderState.CHECKING_SHIPPING,
        OrderEvent.SHIPPING_UNAVAILABLE,
    ): Transition(
        target=OrderState.PAID,
    ),

    (
        OrderState.CHECKING_SHIPPING,
        OrderEvent.SHIPPING_CHECK_FAILED,
    ): Transition(
        target=OrderState.PAID,
    ),

    (
        OrderState.CHECKING_SHIPPING,
        OrderEvent.SHIPPING_CHECK_TIMED_OUT,
    ): Transition(
        target=OrderState.PAID,
    ),
})

Commands and events are now both inputs to the machine. We keep their types separate because requesting an operation and reporting a result are different responsibilities.

Update the selector accordingly:

def next_state(
    order: Order,
    trigger: OrderCommand | OrderEvent,
) -> OrderState:
    validate_order(order)

    if not isinstance(trigger, (OrderCommand, OrderEvent)):
        raise TypeError(
            "trigger must be an OrderCommand or OrderEvent."
        )

    transition = TRANSITIONS.get((order.status, trigger))

    if transition is None:
        raise InvalidOrderOperation(
            f"Cannot handle {trigger.value} "
            f"while the order is {order.status.value!r}."
        )

    if not transition.is_enabled(order):
        raise InvalidOrderOperation(
            transition.rejection_reason
        )

    return transition.target

capture_payment() and ship_order() from Part IV can remain unchanged. Their destinations and eligibility now come from this table.

The previous available_actions() implementation also continues to work: it iterates over OrderCommand, not OrderEvent. Carrier outcomes therefore do not appear as buttons a user may press.

Start the check before starting the external work

The new operation prepares a request and records that the machine is waiting:

from uuid import uuid4


def check_shipping(order: Order) -> ShippingCheck:
    target = next_state(
        order,
        OrderCommand.CHECK_SHIPPING,
    )

    request = ShippingCheck(
        order_id=order.id,
        request_id=uuid4().hex,
        delivery_address=order.delivery_address,
    )

    order.shipping_check = request
    order.status = target

    return request

The returned value describes work to perform. The function does not contact the carrier.

After it returns:

status = CHECKING_SHIPPING
shipping_check = the request we prepared

Only then should another component submit the inquiry.

Why this order?

If the external component can produce a result before we record the pending request, the result handler could receive an answer the order does not yet recognize.

We are establishing local state before allowing external work to respond.

This is still an in-memory sequence of assignments. It does not survive a crash between recording the request and submitting it. We will need a durable boundary later.

For now, it makes the normal execution order explicit.

Accept a result only for the current inquiry

Receiving SHIPPING_AVAILABLE is not enough.

A late answer for an older request must not complete a newer request.

Our handler therefore checks both the lifecycle state and request identifier:

def apply_shipping_result(
    order: Order,
    result: ShippingCheckResult,
) -> bool:
    validate_order(order)

    if result.order_id != order.id:
        raise ValueError(
            "Result was routed to the wrong order."
        )

    if not isinstance(result.event, OrderEvent):
        raise TypeError(
            "Unknown shipping result event."
        )

    if order.status is not OrderState.CHECKING_SHIPPING:
        return False

    request = order.shipping_check

    if request is None or result.request_id != request.request_id:
        return False

    target = next_state(order, result.event)

    if target is OrderState.PAID:
        order.shipping_check = None

    order.status = target
    return True

True means that the result was applied.

False means that this well-formed result no longer belongs to the active inquiry. It does not mean shipping failed.

We treat a wrong order identifier differently: that is a routing error, not an obsolete reply.

On success, the request remains attached to the order and the state becomes READY_TO_SHIP. On an unsuccessful outcome, the request is cleared and the order returns to PAID.

The handler does not perform shipment as a side effect of receiving availability. That remains a separate command.

A late answer can be valid and still be irrelevant

Consider this sequence:

Step	Input or action	Current condition afterward
1	Start inquiry A	Waiting for A
2	A times out locally	`PAID`, no accepted check
3	Start inquiry B	Waiting for B
4	Positive response for A arrives	Still waiting for B
5	Positive response for B arrives	`READY_TO_SHIP`

The answer for A may accurately describe the carrier’s response to A. It is nevertheless irrelevant to the inquiry we are now waiting for.

Checking only the order identifier would accept it.

Checking only CHECKING_SHIPPING would also accept it.

We need the request identifier because the machine may revisit the same waiting state many times.

Being in the right state is necessary. Receiving the right result is necessary too.

Who calls the result handler?

So far, our domain functions are synchronous. They inspect the order, decide, update it, and return.

The network interaction can run separately and produce a message:

import asyncio
from typing import Awaitable, Callable


class CarrierLookupError(Exception):
    pass


async def execute_check(
    request: ShippingCheck,
    carrier: Callable[[str], Awaitable[bool]],
    inbox: asyncio.Queue,
) -> None:
    try:
        available = await carrier(request.delivery_address)
    except CarrierLookupError:
        event = OrderEvent.SHIPPING_CHECK_FAILED
    else:
        if type(available) is not bool:
            raise TypeError(
                "Carrier lookup must return a bool."
            )

        event = (
            OrderEvent.SHIPPING_AVAILABLE
            if available
            else OrderEvent.SHIPPING_UNAVAILABLE
        )

    await inbox.put(
        ShippingCheckResult(
            order_id=request.order_id,
            request_id=request.request_id,
            event=event,
        )
    )

The supplied carrier adapter performs the actual lookup. Its contract is to return a Boolean or translate an expected carrier or transport failure into CarrierLookupError.

We do not catch every exception. A programming error is not automatically a negative availability answer.

More importantly, this function receives a frozen request not the mutable order. It can wait, fail, or finish without directly changing lifecycle state.

Its output goes into a queue.

The component processing that queue decides whether the result still applies.

Process one local reaction at a time

We now need an execution rule:

For this order, finish handling one input before beginning the next local state-machine reaction.

This is run-to-completion behavior.

SCXML formalizes this boundary: processing an external event finishes its resulting internal steps before the next external event is handled. Its interpreter separately describes waiting for events and invoking external processes.[3]

The useful lesson is not that we need XML. It is that a transition’s local work and an external operation’s lifetime are different intervals.

For our order:

Handle CHECK_SHIPPING:
    validate
    create request
    enter CHECKING_SHIPPING
    schedule external work
    return

Later, handle ShippingCheckResult:
    validate
    check request identity
    apply the permitted result
    return

We do not hold the first reaction open until the carrier answers.

That allows the machine to inspect another incoming command while the inquiry is outstanding. A duplicate check request is rejected because CHECKING_SHIPPING has no CHECK_SHIPPING transition.

A small event-processing loop

Python’s asyncio.Queue provides FIFO ordering and allows a consumer to wait when the queue is empty. It is intended for asynchronous code, not unsynchronized access from arbitrary threads.[4]

We will use one consumer for one order. Commands and results enter the same queue.

Payment capture needs its argument, so it gets a small message wrapper:

@dataclass(frozen=True)
class CapturePaymentRequested:
    payment: Payment


Message = (
    CapturePaymentRequested
    | OrderCommand
    | ShippingCheckResult
)

The consumer delegates to the domain operations:

async def run_order(
    order: Order,
    inbox: asyncio.Queue[Message | None],
    start_check: Callable[[ShippingCheck], None],
    report_rejection: Callable[
        [Message, InvalidOrderOperation],
        None,
    ],
) -> None:
    while True:
        message = await inbox.get()

        try:
            if message is None:
                return

            if isinstance(message, CapturePaymentRequested):
                capture_payment(order, message.payment)

            elif message is OrderCommand.CHECK_SHIPPING:
                request = check_shipping(order)
                start_check(request)

            elif message is OrderCommand.SHIP_ORDER:
                ship_order(order)

            elif isinstance(message, ShippingCheckResult):
                apply_shipping_result(order, message)

            else:
                raise TypeError(
                    "Unsupported message or missing command arguments."
                )

        except InvalidOrderOperation as exc:
            report_rejection(message, exc)

        finally:
            inbox.task_done()

start_check is an injected scheduling function. It schedules execute_check() and a timeout; it must return without waiting for the carrier. The surrounding application owns those tasks and their shutdown. Python task groups are one way to manage related asynchronous tasks.[1]

report_rejection reports an expected command rejection without changing the order. Invalid records and unexpected implementation errors are not swallowed.

There is deliberately no await inside the local handlers. The consumer waits for the next message only after the current handler returns.

Under our single-event-loop assumption, and provided all order mutations go through this consumer, another coroutine cannot interleave its own mutation into those synchronous handlers.[1]

That is a local execution guarantee not database atomicity, thread safety, or crash recovery.

task_done() is queue bookkeeping. It does not mean that an external inquiry has finished or that anything was durably committed.[4]

The None message is an orderly stop signal, intended to be sent after message producers have been stopped or drained. This loop is not a complete service-lifecycle implementation.

Waiting for a result is not the same as blocking the consumer

A tempting implementation would put this inside run_order():

available = await carrier(order.delivery_address)

Python could run other tasks during that wait. But this particular consumer would remain inside the handler and would not inspect its next queued message until the lookup finished.

Alternatively, we could create a separate task for every message handler. That would allow handlers for the same mutable order to interleave.

Our design chooses a different boundary:

External work may overlap. Decisions that mutate this order do not.

The event loop runs asynchronous work. The order consumer serializes local reactions. The state machine defines what each reaction may do.

Those are three related responsibilities, not three names for the same mechanism.

A timeout is another input

Suppose the carrier never answers.

We need a local policy for ending the wait.

A timer can enqueue the same kind of result envelope, using the request identifier it was created for. For example, a scheduler using our unbounded, same-event-loop queue could arrange:

loop = asyncio.get_running_loop()

loop.call_later(
    5.0,
    inbox.put_nowait,
    ShippingCheckResult(
        order_id=request.order_id,
        request_id=request.request_id,
        event=OrderEvent.SHIPPING_CHECK_TIMED_OUT,
    ),
)

call_later() schedules a callback using the event loop’s clock. It does not guarantee an exact wall-clock execution instant.[5]

The timer does not mutate the order. It produces an input that the owner will process.

If the carrier response is processed first, the order leaves CHECKING_SHIPPING. The later timeout becomes obsolete.

If the timeout is processed first, that inquiry is abandoned. A later response for it becomes obsolete.

This is an explicit policy: the first applicable outcome processed by the owner settles that inquiry. It is not a rule based on the carrier’s remote timestamp.

A hard deadline based on timestamps would require additional recorded timing information and a different acceptance rule.

We could cancel the timer after accepting a response to avoid unnecessary work. But cancellation cannot be our only protection against stale timeout events. SCXML’s cancellation semantics acknowledge the same issue: a delayed event may already have been delivered when cancellation is attempted.[3]

The request check remains the correctness boundary.

Test event sequences, not network timing

We can test these rules without making a network call or waiting five seconds.

Begin with a paid order:

payment = Payment(
    method="credit_card",
    provider="stripe",
    payment_id="payment-81",
    captured_amount=Decimal("120.00"),
)

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
)

capture_payment(order, payment)

Start inquiry A, then deliver its timeout:

first = check_shipping(order)

assert order.status is OrderState.CHECKING_SHIPPING
assert available_actions(order) == ()

applied = apply_shipping_result(
    order,
    ShippingCheckResult(
        order.id,
        first.request_id,
        OrderEvent.SHIPPING_CHECK_TIMED_OUT,
    ),
)

assert applied
assert order.status is OrderState.PAID
assert order.shipping_check is None

Start inquiry B. The old positive response must not complete it:

second = check_shipping(order)

applied = apply_shipping_result(
    order,
    ShippingCheckResult(
        order.id,
        first.request_id,
        OrderEvent.SHIPPING_AVAILABLE,
    ),
)

assert not applied
assert order.status is OrderState.CHECKING_SHIPPING
assert order.shipping_check is second

Now deliver the result that actually belongs to B:

assert apply_shipping_result(
    order,
    ShippingCheckResult(
        order.id,
        second.request_id,
        OrderEvent.SHIPPING_AVAILABLE,
    ),
)

assert order.status is OrderState.READY_TO_SHIP
assert available_actions(order) == (
    OrderCommand.SHIP_ORDER,
)

Even B’s own timeout is now too late:

assert not apply_shipping_result(
    order,
    ShippingCheckResult(
        order.id,
        second.request_id,
        OrderEvent.SHIPPING_CHECK_TIMED_OUT,
    ),
)

assert order.status is OrderState.READY_TO_SHIP

ship_order(order)

assert order.status is OrderState.SHIPPED
assert order.payment is payment
validate_order(order)

The tests control the input order directly. They verify the behavior we chose rather than depending on a convenient scheduler race.

Other important sequences include duplicate check commands while waiting, duplicate replies, negative answers, lookup failures, results routed to the wrong order, and attempted shipping before confirmation.

What ordering does the queue actually provide?

FIFO ordering means the consumer receives messages in the order they enter this queue.[4]

It does not establish the order in which remote events occurred.

A carrier may generate a response before our deadline, yet network delay may cause its message to arrive after the timeout message. Our current policy accepts the timeout in that case.

We must distinguish:

When something happened elsewhere

from:

When this machine received and processed information about it

The queue gives us a local sequence. The state and request checks give that sequence a defined interpretation.

Neither mechanism makes the outside world globally ordered.

What have we gained?

The order can now represent an unfinished interaction without pretending it has already succeeded.

Its lifecycle records whether a check may begin, whether a result is expected, and whether shipping is eligible. Its supporting data identifies the exact request and destination. External work produces messages instead of mutating the order. One consumer applies those messages in a local sequence.

This is a reactive execution model: the machine progresses by handling inputs as they arrive, rather than requiring one uninterrupted call to complete the entire process.

The central guarantee is now:

Only a result for the currently outstanding inquiry may advance the waiting order.

That does not provide general event deduplication or exactly-once execution. It prevents obsolete results from completing the wrong inquiry under our current, controlled execution path.

Nor is the waiting durable. A process crash still loses this queue, its timers, and the in-memory order. Failed scheduling after a local update still needs recovery we have not implemented.

The read-only inquiry also matters. Returning to PAID after a timeout means we discarded an unanswered check. It would not prove that a timed-out booking or payment request had no external effect.

We have made waiting explicit. We have not yet made external effects recoverable.

But what if the order is waiting for more than one thing?

Our model allows one shipping inquiry at a time.

Now suppose preparation requires both carrier availability and an inventory reservation. Either result may arrive first. Both must succeed before the order can proceed.

We could add:

WAITING_FOR_CARRIER_AND_INVENTORY
CARRIER_READY_WAITING_FOR_INVENTORY
INVENTORY_READY_WAITING_FOR_CARRIER

Then introduce one more independent check.

The lifecycle begins accumulating combinations again.

How do we represent independent work that can run concurrently, finish in either order, and then join into one permitted next step?

References

[1] Python Software Foundation, Coroutines and Tasks. Cooperative scheduling, task suspension, and task groups.

[2] Gregor Hohpe and Bobby Woolf, “Correlation Identifier”, Enterprise Integration Patterns. Associating a reply with the request that produced it.

[3] World Wide Web Consortium, State Chart XML: State Machine Notation for Control Abstraction, W3C Recommendation, 2015. See Appendix D for run-to-completion execution and §6.3 for cancellation of delayed events.

[4] Python Software Foundation, Queues. FIFO behavior, asynchronous queue operations, task bookkeeping, and thread-safety limitations.

[5] Python Software Foundation, Event Loop - Scheduling Delayed Callbacks. Timer scheduling and the event loop’s monotonic clock.

Road to State Machines IV - But How Do We Let Data Influence Transitions Without Turning Every Value into Another State?

Can Burak Sofyalioglu — Fri, 02 Oct 2026 14:59:16 +0000

Our lifecycle now has one explicit transition table. For a valid order, it tells us:

The operations consult that table before making a change. The code that lists available actions consults it too.

But Part III ended with another requirement:

Consider two orders. Both are paid, and both retain their captured payment records:

Order	Status	Payment record	Delivery address
A	`PAID`	Present	Supported
B	`PAID`	Present	Unsupported

Both records satisfy our existing invariants. Both reach the same transition-table entry.

Yet the shipping request should succeed for only one of them.

The table knows where an order is in its lifecycle. It does not yet consider all the information needed to decide whether shipping is permitted.

How do we extend it without losing the clarity we just gained?

Start with the smallest additional check

We already have a delivery_address field. We do not need to change the order model to inspect it.

For this example, let’s use a deliberately small, fixed rule: "Istanbul" and "Izmir" are supported destination labels. Every other string is unsupported.

This is an illustrative policy, not a statement about real carrier coverage. We are also treating the existing strings as destination labels, not implementing postal-address parsing.

def has_supported_address(order: Order) -> bool:
    return order.delivery_address in {"Istanbul", "Izmir"}

We could call this function from the shipping operation:

def ship_order(order: Order) -> None:
    validate_order(order)

    target = next_state(
        order.status,
        OrderCommand.SHIP_ORDER,
    )

    if not has_supported_address(order):
        raise InvalidOrderOperation(
            "The delivery address is not supported."
        )

    order.status = target

This is a reasonable first change. The function still rejects invalid records and invalid lifecycle movements. It now also rejects unsupported destinations before changing the order.

But what does available_actions() report?

Its implementation from Part III checks whether the transition table contains an entry. For both paid orders, it finds:

PAID + SHIP_ORDER → SHIPPED

It therefore offers shipping for both.

The shipping function has acquired a rule that the action listing does not know about. We could copy the address check into the listing, but that would recreate the duplication we just removed.

The new condition belongs with the transition it controls.

A condition that enables a transition

A condition that determines whether a transition is eligible is called a guard. State-machine notations commonly distinguish the triggering input from the Boolean condition that must also hold.[1]

For our shipping transition:

PAID
    -- SHIP_ORDER [has_supported_address] -->
SHIPPED

The command asks for the change. The guard decides whether this particular order may take that transition.

Our rule now has three separate requirements:

The existing order must satisfy its invariants.
Its current state must permit the requested command.
The transition’s guard must pass.

Only then may the operation proceed.

Notice that the address check did not replace the payment checks. A supported address does not make an unpaid order eligible for shipping.

An unsupported destination does not make the order inconsistent

Should we put has_supported_address() into validate_order() instead?

Not for the rule we have chosen.

A paid order with an unsupported destination can still be a consistent record. The customer paid; the captured payment is recorded; the delivery destination is known. What the order cannot do is take the shipping transition under our current policy.

Compare the cases:

Current record	Interpretation	Shipping outcome
`PAID`, no payment record	Inconsistent order	Raise `InvalidOrderState`
`CREATED`, no payment record	Consistent, but shipping is not permitted	Raise `InvalidOrderOperation`
`PAID`, payment present, unsupported destination	Consistent, but the shipping guard fails	Raise `InvalidOrderOperation`
`PAID`, payment present, supported destination	Consistent and eligible	Move to `SHIPPED`

The invariant asks whether the record makes sense.

The guard asks whether a particular transition is allowed now.

There is another reason not to confuse them. If shipping coverage later changes, that does not necessarily make an already shipped order invalid. A condition checked when an operation begins is not automatically a condition that must remain true forever.

For this part, coverage stays fixed. The distinction is still useful.

Do we need two kinds of paid state?

Another possible solution would be to split PAID:

PAID_WITH_SUPPORTED_ADDRESS
PAID_WITH_UNSUPPORTED_ADDRESS

This can represent the distinction, but it makes the lifecycle responsible for carrying a fact already available in the supporting data.

Now suppose we also distinguish three payment providers. We could start creating combinations such as:

PAID_WITH_SUPPORTED_ADDRESS_PROVIDER_A
PAID_WITH_UNSUPPORTED_ADDRESS_PROVIDER_A
PAID_WITH_SUPPORTED_ADDRESS_PROVIDER_B

Then add another condition.

Each independent dimension multiplies the combinations we might have to name. Most of those names would describe data combinations rather than useful lifecycle stages.

More states are not inherently wrong. A separate state can be useful when it represents a different phase with its own permitted operations. But our present requirement does not introduce another phase. It adds a condition to an existing transition.

Both orders remain paid.

Their supporting data determines whether they may ship.

Keep the condition with the transition

Our table currently maps a state–command pair directly to a target state. Let’s give each entry room to describe an optional guard as well.

The OrderState, OrderCommand, Order, and Payment definitions remain unchanged.

We add:

from dataclasses import dataclass
from typing import Callable, Optional


@dataclass(frozen=True)
class Transition:
    target: OrderState
    guard: Optional[Callable[[Order], bool]] = None
    rejection_reason: str = "Transition conditions are not satisfied."

    def is_enabled(self, order: Order) -> bool:
        return self.guard is None or self.guard(order)

guard is either absent or a function that receives an order and returns a Boolean result.

An absent guard means this entry has no additional data-dependent condition. It does not mean that record validation or command-argument validation should be skipped.

The frozen=True setting prevents ordinary assignment to the transition definition’s fields after construction. It does not make the orders passed to its guard immutable.[2]

Now replace the earlier table:

from types import MappingProxyType
from typing import Mapping


TRANSITIONS: Mapping[
    tuple[OrderState, OrderCommand],
    Transition,
] = MappingProxyType({
    (
        OrderState.CREATED,
        OrderCommand.CAPTURE_PAYMENT,
    ): Transition(
        target=OrderState.PAID,
    ),

    (
        OrderState.PAID,
        OrderCommand.SHIP_ORDER,
    ): Transition(
        target=OrderState.SHIPPED,
        guard=has_supported_address,
        rejection_reason="The delivery address is not supported.",
    ),
})

The lifecycle is still small:

Source	Command	Additional guard	Target
`CREATED`	`CAPTURE_PAYMENT`	None	`PAID`
`PAID`	`SHIP_ORDER`	Supported address	`SHIPPED`

We have not added another order state.

We have made one transition more precise.

Select the next state using the order

The selection function needs access to the supporting data, so its signature must change.

Previously, it received only a state:

next_state(order.status, command)

It will now receive the order:

next_state(order, command)

The following definition replaces the version from Part III:

def next_state(
    order: Order,
    command: OrderCommand,
) -> OrderState:
    validate_order(order)

    if not isinstance(command, OrderCommand):
        raise TypeError(
            "command must be an OrderCommand member."
        )

    try:
        transition = TRANSITIONS[(order.status, command)]
    except KeyError:
        raise InvalidOrderOperation(
            f"Cannot {command.value} "
            f"while the order is {order.status.value!r}."
        ) from None

    if not transition.is_enabled(order):
        raise InvalidOrderOperation(
            transition.rejection_reason
        )

    return transition.target

The sequence is deliberate.

First, validate the record using the unchanged validator from Part III. A created order must have no captured payment, while a paid or shipped order must contain a Payment record.

Then find a transition for the current state and command.

Finally, evaluate that transition’s optional guard.

The function returns a target or raises an exception. It still does not change the order.

A missing transition and a failed guard both reject the operation, but they explain different failures:

The lifecycle contains no such movement.
The movement exists, but this order does not currently satisfy its condition.

We keep those explanations separate without inventing extra lifecycle states.

Update the operations to use the new selector

Because next_state() now validates the order itself, the operations do not need to repeat that call.

Replace both operations with:

def capture_payment(order: Order, payment: Payment) -> None:
    target = next_state(
        order,
        OrderCommand.CAPTURE_PAYMENT,
    )

    if not isinstance(payment, Payment):
        raise TypeError("payment must be a Payment record.")

    order.payment = payment
    order.status = target


def ship_order(order: Order) -> None:
    target = next_state(
        order,
        OrderCommand.SHIP_ORDER,
    )

    order.status = target

The address condition no longer appears inside ship_order(). It is attached to the shipping transition.

Payment capture still checks its supplied argument and stores it. We have not made shipping coverage a prerequisite for recording a payment. That would be another business rule, not a consequence we should introduce accidentally.

The expected rejection checks still run before mutation.

These operations also retain their earlier scope: payment capture records the supplied Payment, and shipping changes the local lifecycle status. Neither calls an external service.

Let the read path evaluate the same guard

Now update the action listing:

def available_actions(order: Order) -> tuple[OrderCommand, ...]:
    validate_order(order)

    actions: list[OrderCommand] = []

    for command in OrderCommand:
        transition = TRANSITIONS.get(
            (order.status, command)
        )

        if transition is not None:
            if transition.is_enabled(order):
                actions.append(command)

    return tuple(actions)

The listing and the write path now use the same transition definitions and the same guard evaluation.

For a valid paid order with an unsupported address, shipping is neither advertised nor executed.

This is a stronger agreement than sharing the state–command table alone. Both readers now consider the supporting data that controls the transition.

The listing remains an eligibility report, not permission to bypass the operation. It does not validate a payment argument that has not yet been supplied, establish user authorization, or reserve the order against future changes.

The operation must still check when it is called.

A guard should inspect, not perform work

Because both the read path and the write path evaluate guards, their behavior must be predictable.

Our address guard reads one field and returns a result:

def has_supported_address(order: Order) -> bool:
    return order.delivery_address in {"Istanbul", "Izmir"}

Calling it again with the same address produces the same answer. It does not change the order or contact another system.

This is the contract we want for our guards: evaluate the condition without changing the condition or the world around it. SCXML similarly specifies side-effect-free conditional expressions for its data-model language.[1]

Suppose the guard instead booked a shipment to discover whether shipping was possible.

Simply displaying available actions could then book a shipment. Calling ship_order() would evaluate the guard again and potentially book another.

The question “May I do this?” would perform the thing being asked about.

Likewise, a guard should not update the address to make its own condition pass. Address correction would be a separate operation with its own rules.

Our callable annotation cannot prove that a guard is pure. That remains an implementation contract we must maintain and test. The small address predicate satisfies it; an arbitrary replacement might not.

A guard failure also differs from a guard error. Returning False means the condition was evaluated and was not satisfied. An exception means the evaluation failed. Our code does not catch arbitrary exceptions and pretend that the business simply rejected the request.

Where do command arguments and actions fit?

Not all data used by an operation is already stored on the order.

Consider:

capture_payment(order, payment)

The order is the existing record. The payment argument is input data supplied with the command. It becomes supporting data on the order only after the operation accepts it.

That gives us three distinct inputs to the overall decision:

![[lifecycle-command-execution-inputs.png]]

Our current guard interface receives only the order because the new shipping condition needs only stored data. The payment-argument check remains in capture_payment().

We should not claim that every condition has moved into the transition table. Lifecycle movement and the shipping guard have moved there. Command-specific input validation has not.

After the checks pass, the operation performs its actions.

For payment capture, those actions are:

order.payment = payment
order.status = target

For shipping:

order.status = target

These are local data updates. A fuller state-machine notation may associate updates or other executable actions with transitions; SCXML, for example, separates transition conditions from executable content and data assignments.[1]

We do not need an action registry to demonstrate that distinction. Our domain functions already show where checking ends and updating begins.

What have we extended?

We started with a finite control model:

state + command → next state

We now allow supporting data to influence whether a transition can occur, and our operations update both lifecycle state and supporting data.

This is the central idea of an extended finite state machine, or EFSM: finite control states combined with variables, conditions that enable transitions, and updates associated with accepted inputs.[3]

In our model:

EFSM role	Existing implementation
Control state	`Order.status`
Supporting data, or extended state	Address, payment, and other relevant order fields
Input	Command and its arguments
Guard	`has_supported_address()`
Update	Changes performed by the accepted operation

The term context is often used for the supporting data consulted by the machine. Here, it names a responsibility, not a new class we must create.

We already have an Order that contains that information. Moving every field into an OrderContext object would not, by itself, improve this example.

There is also an important qualification to the word finite. The set of control states remains finite, but the complete configurations include data values. General EFSM definitions can permit unbounded data domains and therefore need not describe a finite total state space.[3]

For our order, PAID is a control state. PAID together with a particular address and payment record is a more complete configuration.

Keeping the diagram small does not make those data-dependent distinctions disappear.

Why keep values outside the state names?

This separation was useful well before application workflow libraries.

In their 1996 paper Automatic Generation of Functional Vectors Using the Extended Finite State Machine Model, Kwang-Ting Cheng and A. S. Krishnakumar used EFSMs to derive tests from descriptions of sequential circuits. They kept data variables and their operations in a compact model rather than explicitly naming every combination as a control state.[3]

Their problem was circuit testing, not shipping orders. The relevant connection is the representation: preserve explicit control flow while expressing value-dependent behavior through conditions and updates.

The later SCXML standard makes a related separation visible through its data model, transition conditions, and executable content.[1]

Neither reference requires us to adopt a particular framework. They help explain why extending the transition model is different from endlessly expanding the list of state names.

Test the data-dependent cases

Part III tested the six combinations formed by three states and two commands.

Those cases still matter. But testing shipping once from PAID is no longer enough.

The address now divides valid paid orders into at least two relevant groups:

Valid starting record	Command	Expected result
`CREATED`, supported address	`CAPTURE_PAYMENT` with valid payment	Become `PAID`
`CREATED`, unsupported address	`CAPTURE_PAYMENT` with valid payment	Become `PAID`
`CREATED`, either address category	`SHIP_ORDER`	Reject
`PAID`, supported address	`SHIP_ORDER`	Become `SHIPPED`
`PAID`, unsupported address	`SHIP_ORDER`	Reject
`SHIPPED`, either address category	`SHIP_ORDER`	Reject

The second row is worth noticing. It confirms that we added a shipping restriction, not a payment restriction.

Let’s exercise the new rejection path:

from copy import deepcopy


payment = Payment(
    method="credit_card",
    provider="stripe",
    payment_id="payment-81",
    captured_amount=Decimal("120.00"),
)

blocked_order = Order(
    id="order-68",
    customer_name="Alice",
    delivery_address="Ankara",
    status=OrderState.PAID,
    payment=payment,
)

validate_order(blocked_order)

before = deepcopy(blocked_order)

assert available_actions(blocked_order) == ()
assert available_actions(blocked_order) == ()

try:
    ship_order(blocked_order)
except InvalidOrderOperation:
    pass
else:
    raise AssertionError(
        "An unsupported destination was allowed to ship."
    )

assert blocked_order == before
assert blocked_order.payment is payment

Validation succeeds because the order is internally consistent.

The action listing offers nothing: payment capture is no longer permitted, and shipping is blocked by the guard.

The shipping request raises an exception without changing the record.

Calling the action listing twice also leaves it unchanged. That check would help expose a guard that mutates the order while answering an eligibility question.

Now verify the accepted path using a separate order:

supported_order = Order(
    id="order-69",
    customer_name="Alice",
    delivery_address="Istanbul",
    status=OrderState.PAID,
    payment=payment,
)

assert available_actions(supported_order) == (
    OrderCommand.SHIP_ORDER,
)

ship_order(supported_order)

assert supported_order.status is OrderState.SHIPPED
assert supported_order.payment is payment
assert available_actions(supported_order) == ()

validate_order(supported_order)

The existing invalid-record tests remain necessary. A paid order with no payment must still fail before any shipping guard is considered.

We have added another dimension to the tests, not replaced the earlier ones.

The machine is still deterministic

Two paid orders can now produce different outcomes for the same command. Does that make the machine nondeterministic?

No. We are considering more input to the decision.

For the same valid order data, command, and fixed address policy, our selector produces the same target or rejection.

There is still at most one transition definition for each state–command pair. Its guard either enables that transition or blocks it.

If we later allow multiple candidate transitions for the same pair, we will need another explicit rule: their guards must distinguish the cases unambiguously, or the model must define how competing matches are resolved.

We have not introduced that branching here.

A rejected shipping request also does not mean that the order successfully transitioned from PAID back to PAID. No transition was taken. The request was refused, and the original configuration remained unchanged.

That difference matters when we eventually attach work to transitions.

What the richer model does—and does not—protect

Our three-state lifecycle remains intact. The payment model, its consistency rules, and the simulated nature of both operations remain intact too.

The change is that a declared transition can now inspect supporting data before it is taken. The write path and the action listing share that condition.

We still rely on controlled operations. Directly assigning a status or changing the address can bypass those operations, just as it could in Part III.

We also still assume one uninterrupted local decision. next_state() does not lock an order, reserve a carrier, or commit a database transaction. Its returned target is not a reusable authorization token.

The improvement is specific:

A valid order may take a declared transition only when that transition’s current data conditions also pass.

We have moved beyond asking only where the order is. We can now ask whether the rest of the record permits the proposed movement.

But what if the condition cannot be answered locally?

Our shipping guard can answer immediately because coverage is a fixed rule in the program.

Now suppose the carrier must confirm whether it can accept a particular shipment. The answer might arrive later. The request might fail. The customer might send another command while we wait.

Putting that interaction inside has_supported_address() would break the boundary we established: inspecting available actions would perform external work.

It would also expose a larger problem.

The system would no longer make one immediate decision from information already available. It would need to request information, retain what it was waiting for, and continue when a result arrived.

A sent request is not a confirmed shipment.

But how does the machine wait for something that happens later without losing track of what it is allowed to do in the meantime?

References

[1] World Wide Web Consortium, State Chart XML: State Machine Notation for Control Abstraction, W3C Recommendation, 2015. See §3.5, “Transition”; §4, “Executable Content”; and §5, “Data Model and Data Manipulation.”

[2] Python Software Foundation, dataclasses — Data Classes. Documentation for dataclass fields and the limitations of frozen=True.

[3] Kwang-Ting Cheng and A. S. Krishnakumar, “Automatic Generation of Functional Vectors Using the Extended Finite State Machine Model”, ACM Transactions on Design Automation of Electronic Systems, vol. 1, no. 1, pp. 57–79, 1996. An author-uploaded manuscript includes the model’s enabling conditions, updates, and distinction between symbolic states and full configurations.

Road to State Machines Part III - But How Do We Represent the Entire Lifecycle as One Behavioral Contract?

Can Burak Sofyalioglu — Thu, 01 Oct 2026 09:03:58 +0000

Our operations now reject invalid changes.

capture_payment() requires a valid created order and a payment record. ship_order() requires a valid paid order. Both inspect the existing record before changing it.

But suppose we ask:

What operations are available to a paid order?

We still have to inspect the functions.

One function says that payment capture requires created. Another says that shipping requires paid. Their assignments tell us where the order goes afterward.

The lifecycle exists, but we must reconstruct it from the implementation.

How do we make that lifecycle explicit and make the operations use it?

Start by writing down the rules we already have

We do not need more states yet. Our model still has three:

created → paid → shipped

It also has two operations:

capture_payment(order, payment)
ship_order(order)

For a valid order, the status-based rules are:

Current status	Capture payment	Ship order
`created`	Move to `paid`	Reject
`paid`	Reject	Move to `shipped`
`shipped`	Reject	Reject

This table contains six combinations. Only two permit a change.

The payment argument still needs validation. The table does not claim that every call to capture_payment() from created is valid, regardless of its arguments. It describes which operations are eligible from each lifecycle state.

That distinction preserves the separation we established in Part II:

The current record must be consistent. The requested movement must also be permitted.

Until now, this table was a summary we produced by reading the code. Let’s reverse that relationship.

The table should define the lifecycle. The operations should consult it.

Give the vocabulary explicit names

First, let’s replace the unrestricted status vocabulary with named values:

from enum import Enum


class OrderState(Enum):
    CREATED = "created"
    PAID = "paid"
    SHIPPED = "shipped"

An enumeration defines a set of named members. Each member here retains the lowercase string we already use to represent the status.[1]

We can distinguish the member from its external representation:

OrderState.PAID
OrderState.PAID.value  # "paid"

We also need names for the inputs that request a change:

class OrderCommand(Enum):
    CAPTURE_PAYMENT = "capture_payment"
    SHIP_ORDER = "ship_order"

We will call these commands because they request operations. They do not announce that the operations have already succeeded.

SHIP_ORDER means “attempt the shipping operation.” It does not mean that a carrier has confirmed shipment.

Likewise, CAPTURE_PAYMENT identifies our existing simulated operation, which records a supplied Payment. We have not added a payment-provider call.

These names give the lifecycle two distinct vocabularies:

States:
    Where is the order?

Commands:
    What operation is being requested?

Update the model without changing its supporting data

The Payment class remains unchanged. In Order, only the status representation changes:

from dataclasses import dataclass
from decimal import Decimal
from typing import Optional


@dataclass
class Payment:
    method: str
    provider: str
    payment_id: str
    captured_amount: Decimal


@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: OrderState = OrderState.CREATED
    payment: Optional[Payment] = None

A newly constructed order now starts with OrderState.CREATED.

When loading a status from an external representation, we can convert it explicitly:

state = OrderState("paid")

assert state is OrderState.PAID

Unknown spellings are rejected by the enum lookup:

OrderState("shiped")  # Raises ValueError.
OrderState("PAID")    # Raises ValueError.

We have not introduced case normalization or guessed what an unknown value means.[1]

However, changing the annotation does not make arbitrary assignment impossible:

order.status = "something_else"

A normal dataclass does not enforce field annotations at runtime.[2] The operation boundary must still validate incoming records.

The enum gives us a defined vocabulary. Validation determines whether a particular record uses it correctly.

Turn the transition table into executable data

Each permitted transition needs three pieces of information:

current state
requested command
next state

We can represent the first two as a dictionary key and the third as its value:

from types import MappingProxyType
from typing import Mapping


TRANSITIONS: Mapping[
    tuple[OrderState, OrderCommand],
    OrderState,
] = MappingProxyType({
    (
        OrderState.CREATED,
        OrderCommand.CAPTURE_PAYMENT,
    ): OrderState.PAID,

    (
        OrderState.PAID,
        OrderCommand.SHIP_ORDER,
    ): OrderState.SHIPPED,
})

MappingProxyType provides a read-only view of the mapping. Ordinary callers cannot insert another transition through TRANSITIONS.[3]

We have stored only the permitted changes. The rejected combinations remain absent.

Now we need a function that interprets the table. We keep the exception types from Part II:

class InvalidOrderOperation(ValueError):
    pass


class InvalidOrderState(ValueError):
    pass


def next_state(
    state: OrderState,
    command: OrderCommand,
) -> OrderState:
    if not isinstance(state, OrderState):
        raise InvalidOrderState(
            "status must be an OrderState member."
        )

    if not isinstance(command, OrderCommand):
        raise TypeError(
            "command must be an OrderCommand member."
        )

    try:
        return TRANSITIONS[(state, command)]
    except KeyError:
        raise InvalidOrderOperation(
            f"Cannot {command.value} "
            f"while the order is {state.value!r}."
        ) from None

The function answers one question:

Given this lifecycle state and this command, which next state is permitted?

For example:

assert next_state(
    OrderState.CREATED,
    OrderCommand.CAPTURE_PAYMENT,
) is OrderState.PAID

assert next_state(
    OrderState.PAID,
    OrderCommand.SHIP_ORDER,
) is OrderState.SHIPPED

But this is rejected:

next_state(
    OrderState.CREATED,
    OrderCommand.SHIP_ORDER,
)

The missing entry is not an implementation omission. It expresses the business rule that an unpaid order must not be shipped.

Notice what next_state() does not do.

It does not modify an order. It does not store payment information. It does not call a provider or create a shipment.

It selects a permitted destination or rejects the request.

We now have an explicit finite state machine

A finite state machine describes a finite set of states, an initial state, inputs, and rules that determine the next state from the current state and input.[4]

Our example has each of those elements:

States:
    CREATED, PAID, SHIPPED

Initial state:
    CREATED

Inputs:
    CAPTURE_PAYMENT, SHIP_ORDER

Permitted transitions:
    CREATED + CAPTURE_PAYMENT → PAID
    PAID + SHIP_ORDER → SHIPPED

The same relationship can be written as:

next_state(current_state, command)

or, using conventional mathematical notation:

δ(current_state, command) = next_state

The symbol δ names the transition function. It does not introduce another mechanism.

Our transition model is deterministic: for a particular state and command, there is one declared destination or a defined rejection.

Mathematical treatments sometimes define a transition for every state–input pair. Our application uses a partial transition table: an absent pair means “reject without changing the order.” We do not silently treat rejection as success, nor move the order into a newly invented failure state.

SHIPPED is terminal within this model, because no supported command leaves it. That does not mean the real order can never be delivered or returned. Those processes are outside the lifecycle we have implemented.

“Finite” describes this control model. It does not mean that every possible customer name, delivery address, or payment record has been enumerated.

But the table does not replace the invariants

Consider:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status=OrderState.PAID,
    payment=None,
)

The transition table contains:

PAID + SHIP_ORDER → SHIPPED

But this particular order is inconsistent. Its payment record is missing.

The table cannot detect that because it receives only the lifecycle state and command.

Let’s update the validator to use our enum while preserving both payment rules:

def validate_order(order: Order) -> None:
    if not isinstance(order.status, OrderState):
        raise InvalidOrderState(
            "status must be an OrderState member."
        )

    if order.status is OrderState.CREATED:
        if order.payment is not None:
            raise InvalidOrderState(
                "A created order cannot contain a captured payment."
            )

    if order.status in (
        OrderState.PAID,
        OrderState.SHIPPED,
    ):
        if not isinstance(order.payment, Payment):
            raise InvalidOrderState(
                f"An order marked {order.status.value!r} "
                "must contain a Payment record."
            )

A created order must still have no payment record. A paid or shipped order must still retain one.

We are not adding validation of payment amounts, currencies, or provider-side capture. The scope remains the same as in Part II.

We now have two deliberately separate functions:

validate_order(order):
    Is the existing configuration consistent?

next_state(state, command):
    Is this lifecycle movement permitted?

Both are necessary.

Make the operations consult the table

We can now replace their status-specific conditions with calls to next_state():

def capture_payment(order: Order, payment: Payment) -> None:
    validate_order(order)

    target = next_state(
        order.status,
        OrderCommand.CAPTURE_PAYMENT,
    )

    if not isinstance(payment, Payment):
        raise TypeError("payment must be a Payment record.")

    order.payment = payment
    order.status = target


def ship_order(order: Order) -> None:
    validate_order(order)

    target = next_state(
        order.status,
        OrderCommand.SHIP_ORDER,
    )

    order.status = target

Compare the new shipping operation with the previous version.

It no longer contains its own declaration that shipping requires paid, followed by an independent assignment to shipped. Both facts come from the transition table.

The same is true of payment capture. Its lifecycle rule comes from the table; the function remains responsible for checking and storing the payment argument.

This is the separation we wanted:

Existing-record consistency → validator

Lifecycle eligibility and destination → transition table

Operation-specific work → domain function

We have not removed the domain functions. They still provide the meaningful interface:

capture_payment(order, payment)
ship_order(order)

Nor have we introduced a generic function with several optional arguments whose meanings depend on which command was passed. For two operations, the explicit functions remain clearer.

All expected rejection checks still happen before mutation.

Payment capture still makes two assignments. As in Part II, this is a local, single-writer example not an atomic transaction or a crash-recovery mechanism.

Let the read path use the same lifecycle

Previously, code displaying available operations could repeat the status checks.

Now it can consult the same table:

def available_actions(order: Order) -> tuple[OrderCommand, ...]:
    validate_order(order)

    return tuple(
        command
        for command in OrderCommand
        if (order.status, command) in TRANSITIONS
    )

The function validates the record first. An inconsistent order is not presented as though it were ready for normal processing.

Let’s follow one order through the complete sequence:

payment = Payment(
    method="credit_card",
    provider="stripe",
    payment_id="payment-81",
    captured_amount=Decimal("120.00"),
)

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
)

assert available_actions(order) == (
    OrderCommand.CAPTURE_PAYMENT,
)

capture_payment(order, payment)

assert order.status is OrderState.PAID
assert order.payment is payment
assert available_actions(order) == (
    OrderCommand.SHIP_ORDER,
)

ship_order(order)

assert order.status is OrderState.SHIPPED
assert order.payment is payment
assert available_actions(order) == ()

validate_order(order)

The write path and the action listing now agree because they read the same lifecycle definition.

But an available action is not a promise that a later call will succeed.

The listing describes eligibility for the current record. It does not supply a valid Payment argument, grant a user permission, or reserve the order against another change. The operation must still perform its checks when invoked.

Displaying an action does not replace enforcing it.

Test the whole transition surface

We now have a small, explicit surface to test: three states and two commands.

Let’s write expected outcomes independently of TRANSITIONS:

expected_transitions = {
    (
        OrderState.CREATED,
        OrderCommand.CAPTURE_PAYMENT,
    ): OrderState.PAID,

    (
        OrderState.PAID,
        OrderCommand.SHIP_ORDER,
    ): OrderState.SHIPPED,
}

for state in OrderState:
    for command in OrderCommand:
        expected = expected_transitions.get((state, command))

        try:
            actual = next_state(state, command)
        except InvalidOrderOperation:
            assert expected is None, (state, command)
        else:
            assert expected is not None, (state, command)
            assert actual is expected, (state, command)

These assertions are test code, not production validation.

The test exercises all six combinations, including the four that must be rejected. Its expected outcomes describe our business specification rather than being calculated from the implementation table.

Simply iterating over TRANSITIONS and asserting that the lookup returns its stored values would be much weaker. That could confirm that the dictionary works while overlooking an incorrectly permitted transition.

We must also keep the record-level tests from Part II.

For example, rejecting an unpaid shipment must preserve the order:

unpaid_order = Order(
    id="order-67",
    customer_name="Alice",
    delivery_address="Istanbul",
)

try:
    ship_order(unpaid_order)
except InvalidOrderOperation:
    pass
else:
    raise AssertionError("An unpaid order was allowed to ship.")

assert unpaid_order.status is OrderState.CREATED
assert unpaid_order.payment is None

The matrix test does not replace tests for missing payments, captured payments on created orders, invalid payment arguments, or raw strings assigned to status.

They test different obligations.

Choosing a state is not the same as producing an output

Our implementation now makes another distinction visible.

The transition function selects a destination. The domain operation performs the work needed to reach it. A reader may then display information derived from the resulting state.

These are related responsibilities, but they are not identical.

This distinction also appears in early sequential-machine research. George Mealy’s 1955 paper developed systematic methods for synthesizing sequential circuits. The model bearing his name associates output with the current state and input the transition being taken.[4, 5]

Edward Moore’s 1956 paper examined what could be inferred about finite machines through external experiments. In the machines he defined, the next state depended on the previous state and input, while observable output depended on the current state.[6]

The conventional distinction is:

Mealy:
    output = f(state, input)

Moore:
    output = f(state)

For our application, consider two different outputs.

A message reporting that a payment was just recorded belongs to the occurrence of that operation. A status label displaying “Paid” can be derived whenever someone reads the order.

Reading the label must not record the payment again.

These are application-level parallels, not a claim that our complete Order object is a literal Mealy or Moore machine. Payment records and other supporting data remain outside the small control table.

The useful historical lesson is to ask where an observable result belongs: to handling an input, or to occupying a state.

A state-derived display is also not automatically a one-time action executed on entry. Showing “Paid” repeatedly and capturing money repeatedly are very different behaviors.

What became authoritative?

We can now point to one structure for the status-dependent lifecycle:

TRANSITIONS

Changing its shipping entry changes both the destination selected by ship_order() and the eligibility reported by available_actions().

That is a meaningful improvement.

It does not make the table the sole source of every business rule. Payment consistency still lives in validation. Payment-argument checks still live in the operation. A future change to the lifecycle must remain compatible with both.

A transition table can also contain the wrong rule. Adding:

CREATED + SHIP_ORDER → SHIPPED

would not become correct merely because it was expressed declaratively.

The benefit is that the rule is visible, shared, and directly testable.

We also retain the mutation limitation from Part II. A caller can still assign OrderState.SHIPPED directly and bypass the transition function. Using enum members does not establish an exclusive write boundary.

For this implementation, the guarantee remains:

Through the controlled operations, a valid order follows a declared lifecycle transition or the request is rejected without changing it.

That is narrower than “the system can never be wrong.” It is also a guarantee we can inspect and test.

Was the dictionary necessary?

For three states and two operations, the earlier guarded functions remain a reasonable alternative.

They may even be easier to read when no other component needs to inspect the lifecycle.

The table becomes useful because we now have several consumers of the same rule: operations that change the order, code that reports available actions, and tests that examine the entire state–command surface.

We have not replaced conditional logic because conditionals are bad. We have given shared lifecycle rules an explicit representation.

The earlier functions already implemented state-machine behavior. This version makes that behavior a separate model.

But what happens when the next decision depends on more than status?

Our table currently answers:

PAID + SHIP_ORDER → SHIPPED

Now suppose the business introduces a new requirement:

Ship only to supported delivery addresses.

This is a proposed extension, not a rule our current code already enforces.

Consider two internally consistent orders:

Order A:
    status = PAID
    payment = captured payment
    delivery_address = supported destination

Order B:
    status = PAID
    payment = captured payment
    delivery_address = unsupported destination

Both reach the same table entry.

Yet the new rule requires different outcomes.

We could create more states:

PAID_WITH_SUPPORTED_ADDRESS
PAID_WITH_UNSUPPORTED_ADDRESS

Then another rule arrives about a payment provider, a retry limit, or a customer restriction. Should each combination become another state?

The lifecycle table has solved the visibility problem. It has not removed the need for supporting data to influence decisions.

We can now see the next boundary:

A lifecycle state identifies a behavioral mode. It does not necessarily contain every value needed to choose a transition.

But how do we let those values influence the decision without turning every combination into another lifecycle state?

References

[1] Python Software Foundation, enum - Support for enumerations. Named members, values, and enum lookup behavior.

[2] Python Software Foundation, dataclasses - Data Classes. Dataclass fields, generated methods, and the treatment of type annotations.

[3] Python Software Foundation, types.MappingProxyType. Read-only access to a mapping.

[4] Paul E. Black, “Finite State Machine”, NIST Dictionary of Algorithms and Data Structures. State-machine components and the distinction between transition-associated and state-associated outputs.

[5] George H. Mealy, “A Method for Synthesizing Sequential Circuits”, Bell System Technical Journal, 1955.

[6] Edward F. Moore, “Gedanken-Experiments on Sequential Machines”, in Automata Studies, edited by Claude E. Shannon and John McCarthy, Princeton University Press, 1956.

Road to State Machines Part II - How Do We Prevent Impossible Changes?

Can Burak Sofyalioglu — Wed, 30 Sep 2026 12:47:16 +0000

Our model can now describe an order’s lifecycle state and retain the payment information that supports it. What it cannot do is enforce the rules we established.

The status must be created, paid, or shipped. Payment capture may move an order from created to paid; shipping may move it from paid to shipped. The status and payment record must also agree. These were the unresolved requirements at the end of Part 1.

How do we move those rules from the explanation into the implementation?

Let’s continue with the model we already have:

from dataclasses import dataclass
from decimal import Decimal
from typing import Optional


@dataclass
class Payment:
    method: str
    provider: str
    payment_id: str
    captured_amount: Decimal


@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: str = "created"
    payment: Optional[Payment] = None

The operations are still simple assignments:

def capture_payment(order: Order, payment: Payment) -> None:
    order.payment = payment
    order.status = "paid"


def ship_order(order: Order) -> None:
    order.status = "shipped"

Both functions change the record without checking whether the change makes sense.
We do not need a new framework to improve this. We need to make the first decision explicit.

Start by protecting the shipping operation

Our shipping rule is:

Only a paid order may be shipped.

The smallest change is to check the current status before assigning the next one:

class InvalidOrderOperation(ValueError):
    pass


def ship_order(order: Order) -> None:
    if order.status != "paid":
        raise InvalidOrderOperation(
            f"Cannot ship an order while it is {order.status!r}."
        )

    order.status = "shipped"

Now consider a newly created order:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
)

ship_order(order)

The function raises InvalidOrderOperation. The assignment never runs, so the order remains in the created state.

We have changed more than just the amount of code. The operation now has two possible outcomes: perform the permitted change, or reject the request without changing the order.

The condition order.status == "paid" is a precondition: something that must hold for this operation to complete successfully. The check in the function enforces it.[2]

This protects one path. But does it protect the whole model?

A valid status can belong to an invalid order

Let’s construct the inconsistent order we encountered in Part 1:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="paid",
    payment=None,
)

ship_order(order)

print(order.status, order.payment)
# shipped None

The function accepts it.

Its condition asks whether the status is paid, and the answer is yes. It never asks whether a payment record exists.

Our first check is correct but insufficient. The order is eligible by its label, yet inconsistent with our business rules.

These are two different questions:

Is the current order a valid record?
Is this operation allowed from that valid record?

Checking the second does not automatically answer the first.

Make valid configurations explicit

In Part 1, we required a captured payment record for every paid or shipped order, and no captured payment record for a created order.

That gives us a small set of combinations to consider:

Status	No payment record	Captured payment record
`created`	Valid	Invalid
`paid`	Invalid	Valid
`shipped`	Invalid	Valid

An unknown status is invalid regardless of the payment field.

Let’s put those checks in one function:

class InvalidOrderState(ValueError):
    pass


def validate_order(order: Order) -> None:
    if order.status not in ("created", "paid", "shipped"):
        raise InvalidOrderState(
            f"Unknown order status: {order.status!r}."
        )

    if order.status == "created" and order.payment is not None:
        raise InvalidOrderState(
            "A created order cannot contain a captured payment."
        )

    if order.status in ("paid", "shipped"):
        if not isinstance(order.payment, Payment):
            raise InvalidOrderState(
                f"An order marked {order.status!r} "
                "must contain a Payment record."
            )

The first check enforces our vocabulary. In this implementation, the actual values are lowercase strings. PAID is not silently converted to paid.

The other checks enforce agreement between lifecycle state and supporting data.

The isinstance() check also prevents a string such as "payment-81" from being accepted in place of a Payment object. The annotation Optional[Payment] describes the intended type, but a plain dataclass does not enforce that annotation at runtime.

These checks have a deliberately limited scope. They validate the relationship between the order’s status and its payment record. They do not validate every field inside Payment, compare the captured amount with an order total, or prove that a provider captured money.

Our model still assumes one full payment in one currency. We haven't added an order total or a provider integration, so we shouldn't claim to verify either.

These consistency rules are invariants

The rules in validate_order() are not specific to shipping. They describe what we consider a valid order.

Let’s call that kind of rule an invariant.

For this implementation, an invariant is a condition that must hold whenever an order is accepted for processing and after a successful operation returns.

For example:

A created order has no captured payment record.

And:

A paid or shipped order retains its captured payment record.

The distinction from a precondition is useful:

Question	Kind of rule	Example
Is this order valid?	Invariant	A paid order contains a payment record.
May this operation run now?	Precondition	Shipping requires a paid order.
What must successful execution establish?	Postcondition	Shipping leaves the order shipped and retains its payment.

A postcondition describes what must hold after successful execution.

The payment record’s continued presence matters. Shipping should change the lifecycle state, not erase the supporting information that made the operation valid.

Valid endpoints do not prove a valid transition

Our validator has a subtle limit.

These two configurations both satisfy it:

Before:
    status = created
    payment = None

After:
    status = shipped
    payment = a Payment record

Nevertheless, moving directly between them would skip the payment transition we defined.

The destination is valid in isolation. Our lifecycle does not permit the move.

validate_order() cannot determine whether the previous state was created, paid, or something else. It receives one record, not a record of how it reached that condition.

We therefore need both kinds of checks:

Configuration checks determine whether the fields describe an allowed condition.

Transition checks determine whether a particular operation may move the order from its current condition to another.

Neither replaces the other.

Put the checks before the changes

Let’s revise both operations.

First, we validate the existing order. Then we will check whether the requested operation is permitted. Only after those checks pass will we change any fields.

def capture_payment(order: Order, payment: Payment) -> None:
    validate_order(order)

    if order.status != "created":
        raise InvalidOrderOperation(
            "Cannot record a captured payment "
            f"while the order is {order.status!r}."
        )

    if not isinstance(payment, Payment):
        raise TypeError("payment must be a Payment record.")

    order.payment = payment
    order.status = "paid"


def ship_order(order: Order) -> None:
    validate_order(order)

    if order.status != "paid":
        raise InvalidOrderOperation(
            f"Cannot ship an order while it is {order.status!r}."
        )

    order.status = "shipped"

These definitions replace the earlier unguarded functions.

The distinction between the exceptions is intentional.

InvalidOrderState means the existing record contradicts our model. A paid order with no payment record belongs in this category.

InvalidOrderOperation means the order is valid, but the requested operation is not permitted. A correctly formed created order receiving a shipping request belongs in this category.

Neither case should be repaired by inventing missing information.

If payment is absent, shipping must not construct a placeholder payment to satisfy the validator. If the status is unknown, the operation must not guess which known status was intended.

The request stops at the failed check.

Why check the current record first?

Suppose we receive:

status = created
payment = an existing captured payment

Without validating the current record, capture_payment() could accept another payment, overwrite the existing record, and change the status to paid.

The result would look consistent. But the operation would have hidden an inconsistent input by replacing information.

Our revised function rejects the order before that happens.

This gives us a useful rule:

Do not use a normal lifecycle operation to silently repair a record that already violates the lifecycle.

A repair process may eventually be necessary. It should make its purpose explicit. We have not designed one here.

What successful operations now establish

For capture_payment(), the reasoning is:

A valid created order has no payment. The function accepts a Payment record, stores it, and marks the order as paid. The resulting combination satisfies our consistency rules.

For ship_order(), the reasoning is:

A valid paid order already contains a payment. The function changes only the status to shipped. The payment remains attached, so the resulting combination also satisfies the rules.

All expected rejection conditions occur before either operation mutates the order.

That placement matters. Changing fields and then raising an exception does not, by itself, undo the assignments.

Our payment function still performs two separate assignments:

order.payment = payment
order.status = "paid"

Between them, the object temporarily contains a payment while its status is still being created. Under our current assumptions, no other writer, callback, or reader observes the object during that operation. The invariant applies at the operation boundary.

This is not an atomic transaction or a concurrency guarantee. If another process can observe intermediate writes, or an external operation can fail between them, we will need a stronger boundary.

For now, we are solving the local problem we actually have.

An older way of asking the same correctness question

Once we describe what must be true before and after an operation, we are using a form of reasoning that has a long history.

In his 1969 paper An Axiomatic Basis for Computer Programming, C. A. R. Hoare developed an approach to reasoning about programs through assertions about their initial and resulting conditions. A common notation is:

{precondition} command {postcondition}

For partial correctness, the claim is that when the precondition holds, a terminating execution establishes the postcondition.[2]

Applied to our example, the intended contract is:

{valid order, status is paid}
    ship_order(order)
{valid order, status is shipped, payment is retained}

This specifies what we want, not a formal proof of our Python implementation.

Dijkstra’s later work on guarded commands made another relevant idea explicit: a command’s eligibility can depend on a Boolean condition placed before it.

Our shipping check serves that limited purpose. It does not implement Dijkstra’s full calculus, but it follows the same useful discipline: describe when an action is eligible, rather than writing the action alone.

The historical connection is practical. The important unit is not just the assignment. It is the assignment together with the conditions that make it correct.

Check the behavior, including rejection

Let’s run the intended sequence using the same kind of payment record as before:

payment = Payment(
    method="credit_card",
    provider="stripe",
    payment_id="payment-81",
    captured_amount=Decimal("120.00"),
)

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
)

capture_payment(order, payment)

assert order.status == "paid"
assert order.payment is payment
validate_order(order)

ship_order(order)

assert order.status == "shipped"
assert order.payment is payment
validate_order(order)

The assertions check more than the final label. They also check that both operations retain the supplied payment record.

Now test rejection:

unpaid_order = Order(
    id="order-67",
    customer_name="Alice",
    delivery_address="Istanbul",
)

try:
    ship_order(unpaid_order)
except InvalidOrderOperation:
    pass
else:
    raise AssertionError("An unpaid order was allowed to ship.")

assert unpaid_order.status == "created"
assert unpaid_order.payment is None

The final assertions matter.

An operation that raises the expected exception after partially changing the record would still be wrong for this contract.

For valid starting records, our two functions should behave as follows:

Starting status	capture_payment()	ship_order()
created	Record payment; become paid	Reject without changing the order
paid	Reject without replacing the payment	Become shipped ; retain payment
shipped	Reject without replacing the payment	Reject without changing the order

Reject without replacing the payment

Reject without changing the order

For duplicate shipping, this implementation chooses the rejection policy discussed in Part 1

. Returning an existing shipment would require a shipment result we do not yet store.

Similarly, capture_payment() remains a simulation that records the supplied payment. It does not call Stripe, despite the provider name in the example. Rejecting a second call protects this local record; it does not guarantee against external charges.

But can another caller still bypass the rules?

Yes.

Our functions have improved. The dataclasses remain mutable, and their fields are still public.

A caller can bypass both operations:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
)

order.status = "shipped"

No validation runs automatically on that assignment. Nothing in our class definition invokes validate_order(), either during construction or during later field changes.

Calling the validator afterward will detect the missing payment:

validate_order(order)
# Raises InvalidOrderState.

But detection is not prevention.

There is a second bypass that configuration validation cannot detect:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
)

order.payment = payment
order.status = "shipped"

validate_order(order)
# Passes: the resulting configuration is internally valid.

The record is valid, but the writer skipped the required transition through paid.

This is the difference between protecting an operation and protecting every possible write.

Our guarantee must therefore remain specific:

Through these two functions, a valid order either makes a permitted change or the request is rejected without changing it.

We have not made arbitrary mutation impossible.

To rely on that guarantee, application writes must pass through the controlled operations. Restricting field assignment or introducing immutable records can help establish that boundary, but neither technique alone decides which lifecycle transitions are legal.

The rules and the write boundary are separate responsibilities.

What has improved and what is still implicit?

We have now placed all three categories of rules into executable code.

validate_order() checks recognized status values and consistent data. capture_payment() and ship_order() check the allowed changes.
The operations keep their original names, work with the same Order and Payment models, and still need no external service or framework.

This is manageable for two operations.

But look at where the lifecycle is described.

The valid statuses appear in the validator. The permitted source state for payment capture appears in one function. The permitted source state for shipping appears in another. Their target states appear in assignments.

To answer “What can happen while an order is paid?”, a reader must inspect the operations.

A user interface deciding whether to display a shipping action might write another check:

can_ship = order.status == "paid"

That check describes only status-based eligibility; it does not establish that the record is valid. The actual operation must still validate and reject when necessary.

More importantly, the interface has begun repeating part of the lifecycle rule. If the shipping rule changes, the write path and the displayed action can drift apart.

This is not a reason to add a framework immediately. Our current design is small, readable, and already contains state-machine behavior.

It does reveal the next question.

The behavior exists, but its complete description is distributed across validation checks, operation checks, and assignments. We reconstructed the table above by reading the functions; the table does not yet govern them.

We have made individual changes conditional. We have not yet made the entire lifecycle one explicit contract.

But how do we express that lifecycle in one place so the operations, their tests, and the code displaying available actions don't each maintain their own version of it?

Road to State Machines Part I

Can Burak Sofyalioglu — Wed, 23 Sep 2026 18:56:44 +0000

Let's begin with a very fundamental question whose answer is not so obvious.

How to design software that always takes the correct action?

Part 1 — Designing Systems When the Past Determines What Is Allowed Next

Let's assume we are developing an e-commerce store and are just implementing the shipping feature.

A single operation that acts on a specific order.

ship_order(order)

What should it do?

That depends on what has already happened:

If the order has just been created, shipping should be rejected because the customer has not paid.
Once payment has been captured, the system should create a shipment.
If the order has already shipped, it should return the existing shipment or reject the duplicate request rather than create another one.
If the customer has canceled the order, shipping must not happen at all.

The ship_order command remains the same, but its correct interpretation changes over time.

This brings us to a situation where the command alone is therefore insufficient to determine the correct behavior. The system must also know something about what happened before.

That is the basic problem from which state machines emerge.

Start with the smallest model

Suppose we are building a basic order-fulfillment application.

Let's start with the most basic implementation; Our very first model contains only an identifier:

from dataclasses import dataclass


@dataclass
class Order:
    id: str

And we can create an order:

order = Order(id="order-66")

Now the application receives:

ship_order(order)

Can it proceed?

The object cannot answer because it tells us only which order we are discussing. It does not tell us whether the order was paid, canceled, shipped, or delivered.

The smallest useful improvement is to retain the order’s current condition.\
Let's improve our model a bit by adding a status field so that our basic system can distinguish several stages.

@dataclass
class Order:
    id: str
    status: str = "created"

Their intended progression is straightforward:

CREATED → PAID → SHIPPED

We can implement that progression directly:

def capture_payment(order: Order) -> None:
    order.status = "paid"


def ship_order(order: Order) -> None:
    order.status = "shipped"

We never captured payment, yet the order is marked as shipped.

The status field records the order’s current stage. It does not enforce the rules for reaching that stage.

What code does not show?

The model now has two fields. However, they do not do the same work.

id names the order. Change it, and you are talking about a different order. It does not change what ship_order may do.
status sits next to it, as if it were the same kind of value. It is not. It bears a role the field does not show. Change created to paid, and the system is allowed to ship. Change it to shipped, and the same command must stop.

That role is invisible in the class.

Both fields are strings, but our business rules give them different responsibilities. The status should influence whether shipping is allowed; our current code does not check it.

Both fields actually store data, but one of them has a different responsibility.

Let's call that role state, for now. That is the role that changes how the system acts next.

Let's improve the model a bit by adding a customer_name field.

@dataclass
class Order:
    id: str
    customer_name: str
    status: str = "created"

Three fields. Two of them still haven't decided what happens next.

Changing the customer_name from Alice to Alice Russel does not necessarily affect whether the order may be shipped. However, changing the status from created to shipped does.

Change status from created to shipped, and shipping does care. That field is still doing the other job. That is still state.

The status changes the set of valid future operations. That makes it a behavioral state.

A useful distinction is:

Ordinary data: describes the entity
Behavioral state: changes how the entity may respond

But... Although it is useful, the boundaries of this distinction are not so rigid.

Let me add one more field, delivery_address, to our model to make my point clear.

@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: str = "created"

A delivery address may initially be ordinary data. Once the package has been handed to a carrier, changing that address may become forbidden or require a separate process. The field itself has not changed, but its role in the system’s behavior has.

State is therefore not an intrinsic property of a database column. It is a role information plays in deciding what may happen next.

So the distinction is contextual.

A short name for a longer past

The record says status = "paid". That is where the order is. It is not how the order got there.

One order can be paid by card, while another can be paid by bank transfer.

The paths differ, but both orders are marked as PAID

For shipping, the path may not matter. Paid is enough. The state hides the difference.

Let's call the events we left behind history.

The state summarizes a relevant consequence of the past. It does not preserve everything that happened.

We’ll use history to mean the sequence of events that led to the current situation, whether or not we store that sequence explicitly.

Whether a summary is sufficient depends on the decision we need to make. Consider a future refund operation. A paid label alone would not give us the payment reference or amount needed to issue the refund.

So, improve our system a bit more by adding a Payment class:

from decimal import Decimal
from typing import Optional


@dataclass
class Payment:
    method: str
    provider: str
    payment_id: str
    captured_amount: Decimal


@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: str = "created"
    payment: Optional[Payment] = None

For this example, each order has at most one payment that covers the full amount, and all amounts use the same currency. We use Decimal to represent monetary values.

A paid order might look like this:


payment = Payment(
    method="credit_card",
    provider="stripe",
    payment_id="payment-81",
    captured_amount=Decimal("120.00"),
)

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="paid",
    payment=payment,
)

Now that the model includes payment details, our simulated payment function should store them too:

def capture_payment(order: Order, payment: Payment) -> None:
    order.payment = payment
    order.status = "paid"

We now have three related concepts:

Lifecycle state helps determine which operations are eligible.
Supporting data supplies details for those operations and may impose additional conditions.
History describes the events that produced the current situation.

What the model still allows

We have already shown an invalid change: shipping an unpaid order. Adding more fields leaves two further problems unresolved.

Inconsistent combinations

For this simplified lifecycle, let’s require a captured payment record for every paid or shipped order, and no captured payment record for a created order.

The model does not enforce those rules. It accepts an order marked as paid without a payment record:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="paid",
    payment=None,
)

It also accepts an order marked as created with the captured payment we constructed earlier:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="created",
    payment=payment,
)

These combinations contradict our stated rules. The additional fields give us a richer record, but no checks ensure that their values agree.

Unknown status values

Because status is an unrestricted string, the model also accepts values outside our intended lifecycle:

order.status = "shiped"
order.status = "some_unknown_status"

Python accepts both assignments. Neither value belongs to the vocabulary we intended to use.

The record is our model of reality

There is another boundary to keep in mind. A record marked paid tells us what the application has stored. By itself, it does not prove that a payment provider captured the money.

In a real integration, payment could succeed while the local update fails. Our records could then disagree with the provider.

Those failures belong to later parts of the tutorial. Here, we are examining a simpler problem that already exists with one writer and no external services: the model accepts changes that violate our own rules.

Remembering a condition and enforcing its rules

The status field can tell us where the order claims to be.

It cannot say:

Which values are valid? (such as "created" or "CREATED")
Which changes are allowed? (such as changing from "paid" to "shipped" requires a payment)
Which condition must come first? (such as changing from "created" to "paid" is allowed)
Which operations must be rejected? (such as changing from "created" to "shipped" must be forbidden)

Let's call this the difference between the memory problem and the correctness problem.

We can now distinguish two problems:

The memory problem: retain enough information from the past to inform the next decision.
The correctness problem: enforce the business rules governing valid conditions and changes.

We still need to enforce three kinds of rules:

Valid values: the status must be created, paid, or shipped.
Allowed transitions: a simulated successful payment moves an order from created to paid; shipping moves it from paid to shipped. Shipping directly from created must be rejected.
Consistent data: a paid or shipped order must retain its captured payment record.

A transition is a change from one state to another. Recording the current state does not tell our code which transitions to allow.

Our intended status values give us a vocabulary. Transition rules give us a grammar.

We can name the stages an order may occupy, but our implementation still accepts paths that the business forbids. The rules exist in our explanation; they are not yet enforced by the code.

The next step is to make those rules explicit and enforce them whenever the order changes.

That is where we begin building a state machine.

Python Decorators: A Comprehensive Guide

Can Burak Sofyalioglu — Fri, 03 Jan 2025 07:55:37 +0000

When I started programming with Python, if I am not mistaken, the version was 3.3. Therefore, when I started programming, decorators had been available to the Python community for a long time.

Function decorators came to Python with version 2.2 and Class decorators came to Python with version 2.6.

Personally, I see Python's Decorator feature as a very powerful feature of the language.

Actually, my aim is to make a series of articles about the most difficult to understand topics in Python. I plan to cover these topics, which are a little more than ten, one by one.

In this article, I will try to touch on every part of the Decorators topic as much as I can.

1. Historical Context

Early Days (Pre-Python 2.2): Before decorators, modifying functions or classes often involved manual wrapping or monkey-patching, which was cumbersome and less readable.
Metaclasses (Python 2.2): Metaclasses provided a way to control class creation, offering some of the functionality that decorators would later provide, but they were complex for simple modifications.
PEP 318 (Python 2.4): Decorators were formally introduced in Python 2.4 through PEP 318. The proposal was inspired by annotations in Java and aimed to provide a cleaner, more declarative way to modify functions and methods.
Class Decorators (Python 2.6): Python 2.6 extended decorator support to classes, further enhancing their versatility.
Widespread Adoption: Decorators quickly became a popular feature, used extensively in frameworks like Flask and Django for routing, authentication, and more.

2. What are Decorators?

In essence, a decorator is a design pattern in Python that allows you to modify the behavior of a function or a class without changing its core structure. Decorators are a form of metaprogramming, where you're essentially writing code that manipulates other code.

You know Python resolve names using the scope given in order below:

Local
Enclosing
Global
Built-in

Decorators are sit Enclosing scope, which is closely related to the Closure concept.

Key Idea: A decorator takes a function as input, adds some functionality to it, and returns a modified function.

Analogy: Think of a decorator as a gift wrapper. You have a gift (the original function), and you wrap it with decorative paper (the decorator) to make it look nicer or add extra features (like a bow or a card). The gift inside remains the same, but its presentation or associated actions are enhanced.

A) Decorator Variations: Function-based vs. Class-based

Most decorators in Python are implemented using functions, but you can also create decorators using classes.
Function-based decorators are more common and simpler, while class-based decorators offer additional flexibility.

Function-based Basic Decorator Syntax

def my_decorator(func):
    def wrapper(*args, **kwargs):
        # Do something before calling the decorated function
        print("Before function call")
        result = func(*args, **kwargs)
        # Do something after calling the decorated function
        print("After function call")
        return result
    return wrapper

@my_decorator
def say_hello(name):
    print(f"Hello, {name}!")

say_hello("World")

Explanation:

my_decorator is the decorator function. It takes the function func to be decorated as input.
wrapper is an inner function that wraps the original function's call. It can execute code before and after the original function.
@my_decorator is the decorator syntax. It's equivalent to say_hello = my_decorator(say_hello).

Class-based Basic Decorator Syntax

These use classes instead of functions to define decorators.

class MyDecorator:
    def __init__(self, func):
        self.func = func

    def __call__(self, *args, **kwargs):
        # Do something before calling the decorated function
        print("Before function call")
        result = self.func(*args, **kwargs)
        # Do something after calling the decorated function
        print("After function call")
        return result

@MyDecorator
def say_hello(name):
    print(f"Hello, {name}!")

say_hello("World")

Explanation:

MyDecorator is a class that acts as a decorator.
The __init__ method stores the function to be decorated.
The __call__ method makes the class instance callable, allowing it to be used like a function.

B) Implementing a Simple Decorator

The fundamental concept of decorators is that they are functions that take another function as an argument and extend its behavior without explicitly modifying it.
Here's the simplest form:

def my_decorator(func):
    def wrapper():
        print("Something is happening before the function is called.")
        func()
        print("Something is happening after the function is called.")
    return wrapper

# Using the decorator with @ syntax
@my_decorator
def say_hello():
    print("Hello!")

# When we call say_hello()
say_hello()

# This is equivalent to:
# say_hello = my_decorator(say_hello)

C) Implementing a Decorator with Arguments

Let's create a decorator that logs the execution time of a function:

def decorator_with_args(func):
    def wrapper(*args, **kwargs):    # Accept any number of arguments
        print(f"Arguments received: {args}, {kwargs}")
        return func(*args, **kwargs)  # Pass arguments to the original function
    return wrapper

@decorator_with_args
def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

greet("Alice", greeting="Hi")  # Prints arguments then "Hi, Alice!"

D) Implementing a Parameterized Decorator

These are decorators that can accept their own parameters:

def repeat(times):
    def decorator(func):
        def wrapper(*args, **kwargs):
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(times=3)
def greet(name):
    print(f"Hello {name}")
    return "Done"

greet("Bob")  # Prints "Hello Bob" three times

E) Implementing a Class Decorator

def singleton(cls):
    instances = {}
    def get_instance(*args, **kwargs):
        if cls not in instances:
            instances[cls] = cls(*args, **kwargs)
        return instances[cls]
    return get_instance

@singleton
class DatabaseConnection:
    def __init__(self):
        print("Initializing database connection")

# Creating multiple instances actually returns the same instance
db1 = DatabaseConnection()  # Prints initialization
db2 = DatabaseConnection()  # No initialization printed
print(db1 is db2)  # True

F) Implementing Method Decorators

These are specifically designed for class methods:

def debug_method(func):
    def wrapper(self, *args, **kwargs):
        print(f"Calling method {func.__name__} of {self.__class__.__name__}")
        return func(self, *args, **kwargs)
    return wrapper

class MyClass:
    @debug_method
    def my_method(self, x, y):
        return x + y

obj = MyClass()
print(obj.my_method(5, 3))

G) Implementing Decorator Chaining

Multiple decorators can be applied to a single function:

def bold(func):
    def wrapper():
        return "<b>" + func() + "</b>"
    return wrapper

def italic(func):
    def wrapper():
        return "<i>" + func() + "</i>"
    return wrapper

@bold
@italic
def greet():
    return "Hello!"

print(greet())  # Outputs: <b><i>Hello!</i></b>

Explanation:

Decorators are applied from bottom to top.
It is more like in what we do in math: f(g(x)).
italic is applied first, then bold.

H) What happens if we don't use @functools.wraps ?

The functools.wraps decorator, See docs, is a helper function that preserves the metadata of the original function (like its name, docstring, and signature) when you wrap it with a decorator. If you don't use it, you'll lose this important information.

Example:

def my_decorator(func):
    def wrapper(*args, **kwargs):
        """Wrapper docstring"""
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def my_function():
    """My function docstring"""
    pass

print(my_function.__name__)
print(my_function.__doc__)

Output:

wrapper
Wrapper docstring

Problem:

The original function's name (my_function) and docstring ("My function docstring") are lost.
This can make debugging and introspection difficult.

Solution: Use functools.wraps):

import functools

def my_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        """Wrapper docstring"""
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def my_function():
    """My function docstring"""
    pass

print(my_function.__name__)
print(my_function.__doc__)

Output:

my_function
My function docstring

Benefits of `functools.wraps`:

Preserves function metadata.
Improves code readability and maintainability.
Makes debugging easier.
Helps with introspection tools and documentation generators.

I) Decorators with State

Decorators can also maintain state between function calls. This is particularly useful for scenarios like caching or counting function calls.

python
def count_calls(func):
    def wrapper(*args, **kwargs):
        wrapper.calls += 1
        print(f"Call {wrapper.calls} of {func.__name__}")
        return func(*args, **kwargs)
    wrapper.calls = 0
    return wrapper

@count_calls
def say_hello():
    print("Hello!")

say_hello()  # Call 1 of say_hello
say_hello()  # Call 2 of say_hello

Output:

Call 1 of say_hello
Hello!
Call 2 of say_hello
Hello!

Explanation:

The wrapper function maintains a counter (calls) that increments each time the decorated function is called.
This is a simple example of how decorators can be used to maintain state.

J) Best Practices for Python Decorators

Use functools.wraps: Always use @functools.wraps in your decorators to preserve the original function's metadata.
Keep Decorators Simple: Decorators should ideally do one specific thing and do it well. This makes them more reusable and easier to understand.
Document Your Decorators: Explain what your decorator does, what arguments it takes, and what it returns.
Test Your Decorators: Write unit tests to ensure your decorators work as expected in various scenarios.
Consider the Order of Chaining: Be mindful of the order when chaining multiple decorators, as it affects the execution flow.

K) Bad Implementations (Anti-Patterns)

Overly Complex Decorators: Avoid creating decorators that are too complex or try to do too many things. This makes them hard to understand, maintain, and debug.
Ignoring functools.wraps: Forgetting to use @functools.wraps leads to loss of function metadata, which can cause issues with introspection and debugging.
Side Effects: Decorators should ideally not have unintended side effects outside of modifying the decorated function.
Hardcoding Values: Avoid hardcoding values within decorators. Instead, use decorator factories to make them configurable.
Not Handling Arguments Properly: Ensure your wrapper function can handle any number of positional and keyword arguments using *args and **kwargs if the decorator is meant to be used with a variety of functions.

L) 10. Real-World Use Cases

Logging: Recording function calls, arguments, and return values for debugging or auditing.
Timing: Measuring the execution time of functions for performance analysis.
Caching: Storing the results of expensive function calls to avoid redundant computations (memoization).
Authentication and Authorization: Verifying user credentials or permissions before executing a function.
Input Validation: Checking if the arguments passed to a function meet certain criteria.
Rate Limiting: Controlling the number of times a function can be called within a specific time period.
Retry Logic: Automatically retrying a function call if it fails due to a temporary error.
Framework-Specific Tasks: Frameworks like Flask and Django use decorators for routing (mapping URLs to functions), registering plugins, and more.

M) Curated Lists of Python Decorators

You can find a curated lists of Python decorators below:

N) 11. Conclusion

Decorators are a powerful and elegant feature in Python that allows you to enhance functions and classes in a clean and declarative way.
By understanding the principles, best practices, and potential pitfalls, you can effectively leverage decorators to write more modular, maintainable, and expressive code.
They are a valuable tool in any Python programmer's arsenal, especially when working with frameworks or building reusable components.

A Beginner's Guide to Structure SEO-friendly URLs

Can Burak Sofyalioglu — Thu, 28 Dec 2023 13:05:38 +0000

A Beginner's Guide to Structure Blog Post URLs

Before sharing your first blog post, one of the things you should definitely pay attention to is how your blog posts and their URLs should be organized. I will talk about how you should structure your blog posts URLs, best practices and the things you should avoid.

Please do not skip this article if your intent is ranking on search engines. I have learned these lessons in a hard way. I wasted a great deal of time to fix my mistakes.

Therefore, I definitely recommend reading this article before writing your first blog post.

A Beginner’s Guide for an SEO-Friendly URL Structure

Let's get started with the essential questions that clarify the importance of having a proper URL structure.

What happens when you don't have a proper URL structure?

If you don't follow the practices here, it may be possible for Google to index a page differently than you thought. (We’ll discuss that later)

You link to another article in one of your posts. Later, you realize the link targets a URL other than Google has indexed.

If rankings on search engines are your concern, you should either change the link’s address to the address of what Google indexed or manually remove that page from Google search results. If you are dealing with many pages, such as an e-commerce website, it would take you many hours to fix that.

You can watch the official answer of Google that mentions the potential adverse effects when you change your URL structure later on.

An Analogy to Understand a URL and a Domain Name

Maybe an analogy explains better what a URL and a domain name are.

URL is the abbreviation of Uniform Resource Locator (URL), colloquially known as a web page’s unique address.

A URL has different parts, such as protocol, domain, TLD, subdirectory, slug, and URL parameters.

The part after the TLD (Top Level Domain) is customizable by you (if you are the registrant of that domain) and the main topic of this article is how you should customize that.

Almost all of us have mobile phones. A mobile phone has a unique phone number similar to a website’s URL. It is difficult to remember phone numbers; thus, we save a phone number with a proper name, such as whose it belongs. After, when we try to call a friend in the contact list, the mobile device calls the number of that friend.

This is similar to a website such as the one you are reading. A website's actual address consists of several numbers that we call IP numbers. IP numbers are also difficult to remember, like mobile phone numbers.

Wouldn’t it be nice if we could save those IP numbers with a proper name?

Yes, and we are doing that. Browsers do that for us in the background.

The main difference between those two situations is to whom those records are available and accessible.

A contact with a name and a phone number exists only on the registered device.

On the other hand, when you buy (!) a domain name, you actually rent it for a limited time. More specifically, you become the domain holder and have the right to which IP address that domain name should point out.

Moreover, the record that holds the domain name and the IP number it points out is globally available.

How browsers know the IP number of any domain is the topic of public DNS (Domain Name System) resolver and it is out of the scope of this article.

Part I: Make A Blog URL structure as SEO-friendly

The first thing to understand is the ideal pattern for a blog post URL.

Which URL structure is Better: Flat or Hierarchical?

At a higher level, you have two options to structure your blog post URLs:

Flat URL structure
Hierarchical URL structure (Top-down or Pyramid)

According to an official answer from Google, using a hierarchical URL rather than a flat one seems more beneficial.

What are the Benefits of Using a Hierarchical URL structure

It helps you to keep semantically related content together. By doing that, you signal a message to the crawlers. This helps search engines understand the context of the post better.

Moreover, separating blog posts according to their categories allows you to create different content silos for different topics. Even free blogging platforms support that feature.

But what that means? Let me explain.

What is a Content Silo?

A content silo is a method of grouping related content together on your website to establish the site's keyword-based topical areas or themes. Think of it as organizing your website into different sections or "silos," each dedicated to a specific topic.

This structure helps search engines understand the themes of your site, and it also enhances user experience by making navigation easier.

In other words, content silos may play a role in being an authority on different topics.

Another question is coming.

What does being an authority on a topic means?

One of the four pillars of search engine optimization (E-E-A-T) is being an authority (A) on the topic you want to rank for. It means more than just knowledge. People with authority on a specific topic are trusted and influential people on that topic. They consistently provide value to others through their expertise.

This concept is also known as topical authority.

What does topical authority mean?

The term refers to the level of expertise or credibility a website or content creator has on a specific subject matter. It's like being the go-to source for information on that particular topic. The concept is rooted in the idea that search engines, like Google, favor sites that provide comprehensive and reliable information on specific topics.

By consistently grouping related content under specific category slugs, you're showing search engines that you have multiple pieces of content revolving around this topic. This can help to establish your site as an authoritative source on that subject.

If you need a deeper knowledge about that, I can suggest you to read these two articles:

Considering the benefits I mentioned above, I can say that using a hierarchical URL structure is better.

This means you should categorize your blog posts and insert the category’s slug between a post slug and the domain, separated by a slash.

Preventing Duplicate Content

However, if you are using the URL structure that follows /category/post-slug, it is possible that you will have duplicate content issues. Let me clarify.

It is not a rare scenario for a post with multiple categories.

This causes content duplication.

To prevent this, you must use the canonical address method.

For a given post with multiple categories, you choose one of them as the canonical address and use that one in all versions of that post. By doing that, you tell Google to index only the canonical address and ignore others.

Now, we can proceed to the next part.

Part II: Making Blog Post URLs as SEO-friendly

Keyword research is the first step in search engine optimization. However, it is not the scope of this article.

For the sake of the continuity of this article, I’ll assume that you did keyword research and decided to rank one of those keywords from the research.

So, we have a keyword that we want to rank for.

Before proceeding, I must mention one very important term: slug.

What is a slug?

Slug is a part of the URL and makes a page distinct from another. The human-readable and URL-normalized version of the given text can be a category name or a post title. The blogging platform you choose generally automates this text process but can be changed manually.

For instance, in www.example.com/books/fiction, the slug, 'books/fiction', is composed of the slugified version of category and the product names.

This is the most important part of structuring your blog post URLs, and it must be applied to both the category and the post part of a URL.

We have already decided which keyword we want to rank for.

One of the best practices for search engine optimization is using the keyword in the URL. But why?

Does using keywords in URLs Affect Rankings?

Yes, using keywords in URLs is a ranking factor. On the other hand, according to Google Search Advocate John Mueller, it has a very lightweight effect.

This means we will mention the keyword in the slug.

In general, the post slug is auto-generated by your blogging platform. If it is auto-generated, you’ll see that the slug of the post is based on the title of the post. It is a common practice also.

The more important part is how you customize that slug, either based on the title or not.

The Best Practices for Structuring Blog Post URLs

When structuring the URLs of your blog posts for optimal performance in search engine optimization (SEO), it is important to follow a set of best practices that make your URLs more readable and relevant to both users and search engines.

To apply these practices, your blogging platform must support a category and tag system. Otherwise, you can check the blogging platforms that support the category system.

Here are some guidelines to structure your blog post URLs effectively:

Use Descriptive Keywords: Incorporate the primary keyword related to your blog post into the URL to explain what the post is about. This helps with SEO and gives users an idea of what to expect before they click the link.
Keep it Simple and Specific: Aim to keep your URL structure simple, short, and precise. Although the URL length does not affect rankings, it would be nice to avoid long and complex URLs. By following this practice, you can focus on the most important keywords that capture the essence of your blog post.
Use Hyphens to Separate Words: Even though it doesn't affect rankings which one do you prefer, to enhance readability, use hyphens rather than underscores to separate words within your URL. You
Avoid Unnecessary Words: Trim stop words like "and," "or," "but," "the," etc., as they add unnecessary length and don't contribute much to search engine understanding.
Utilize Lowercase Letters: URLs are case-sensitive by definition. Although it is possible to use all upper case, all lowercase, or maybe mixed case, it's a standard practice to use all lowercase letters in URLs to avoid confusion. Google says its crawler can handle those variations, but it needs to be figured out first. Therefore, please follow all lowercase practice.
Omit Special Characters: Special characters and symbols can make URLs look cluttered and can cause issues with some browsers and servers. Use letters without the diacritical version. Stick to letters and numbers only if that number makes sense where possible.
Exclude Dates and Numbers: Unless they're integral to the content, avoid including dates and excessive numbers, which can make your URL unnecessarily long and less evergreen.
Avoid Keyword Repetition: Don't overuse keywords in the URL as this can look spammy and may not be beneficial for SEO.

The image above shows an example slug of a post with a title "What types of Kyber Crystals Exists?" located under "Star Wars" category.

You can also read the official guideline: URL structure best practices for Google

By adhering to these practices, your blog post URLs will be well-optimized for search engines, contributing to a better user experience and potentially improving the visibility and ranking of your content in search results.

How to Generate Income from Your Blog

Can Burak Sofyalioglu — Mon, 01 May 2023 22:10:37 +0000

In this article, I shared my findings and personal experiences about generating income with your blog from a general perspective. I mentioned different monetization strategies and different useful tools that make your blogging journey easier.

Suppose you have no idea how to generate revenue from your blog. In that case, this article gives you a general understanding of monetization methods which are also independent of the type of blog.

If you have decided which platforms to use for your publishing, it is time to create remarkable content and generate revenue.

If you didn't decide on the blogging platform, I suggest you check these options: Best Blog Building Sites

Part 1: Quality Content Creation

The value you realize from your published content depends on several variables, the most important of which is blog traffic. The more traffic your blog receives, the more value you realize. Consider it like having a billboard on a busy street.

It can be said that it will be a billboard in the desert when you publish your first post. Therefore, it is vital to promote your content through Twitter, Facebook groups, Reddit, Medium etc.

But… Even though promoting your content through social media is a necessary condition, it is not a sufficient one.

The most critical factor that determines your income is providing good value to your audiences. In the year 2023, content is still king.

In the long run, quality always beats quantity, and blogging is a long-run process.

But…

What does quality content mean?

Valuable, or quality content, is content that provides significant benefits to readers by addressing their needs, solving their problems, answering their questions, or entertaining them in a meaningful way.

Creating valuable content should be a priority for bloggers and content creators, as it helps build trust, credibility, and loyalty among readers, leading to increased engagement, social shares, and return visits.

It is a fact that all of these returns will eventually comprise your income.

To provide valuable content to your readers, consider the following tips:

Understand your audience

Research and identify your target audience's needs, preferences, and pain points

Create reader personas to help you better understand and address their needs through your content.

Contrary to average practice, Prioritize creating high-quality, well-researched, and in-depth content rather than churning out a large volume of superficial articles.

Although this strategy consumes more time, it will put you in front of thousands of bloggers in the long-run. This may grow the size of your loyal readers.

One of the best ways to understand your audience is by creating user personas.

What is a user persona?

A persona is a fictional representation of your ideal customers. They give a clue about how they look, what they need, and what they want.
A user persona is a combination of all the characteristics your audiences would possess.

For instance, you can clone this Notion template to see a very basic representation of a simple user persona.

In different words, It helps you to create empathy for the real people and help you to put yourself in the shoes of your readers.

You can use Answer The Public to know which questions your audience asks.

Be informative and educational and create easily consumable content

Sharing your knowledge and expertise in your niche topic is not an easy task. It can be improved with lots of practice.

Moreover, providing insights, tips, and actionable advice that helps your readers solve problems or improve their lives is the key point of a successful blog.

Use short paragraphs and concise sentences to make your content more readable and scannable. Include visuals such as images, infographics, and videos to break up text and enhance your content's appeal.

Offer step-by-step guides, tutorials, or case studies to illustrate your points.

Google Trends and Exploding Topics are useful for trendy topics. Analyze the competition of your keywords and their monthly search volume.

Research Rabbit is another useful tool for research papers if your niche is an academic topic.

You may also find useful browser extensions to create step-by-step guides like Tango

Be original, authentic and create novel content

Create unique content that showcases your voice, perspective, and experiences. Avoiding grammatical errors is also critical for your users. Avoid rehashing or duplicating content found elsewhere.

Share personal stories and anecdotes to connect with your readers and make your content relatable.

If you are not a native English writer, using tools like LanguageTool could help a lot.

Promote your content through social media and optimize it for search engines

Hyperlinks are great. It navigates your audiences to where you want. Share a tweet and navigate your users to your money page.

Implementing search engine optimization best practices is crucial for successful bloggers. Organic search traffic is the most significant source of traffic for most blogs.

It brings users without marketing such as keyword research, proper use of title tags and meta descriptions, and internal and external linking, to make your content more discoverable and accessible to potential readers.

Google Ads has a very useful tool called Keywords Planner. Extensively use it for your keyword research.
Buffer like tools allow you to publish your work to multiple channels.

If you are interested, you may check the list of content creation tools

Part 2: Generating Revenue

What are the ways of earning from your blog?

Ads
Affiliations
Subscriptions

Income from Ads

Ad revenue depends on site traffic, and site traffic depends on making the blog visible. Numerous platforms are eager to show ads on your blog site if your site has a considerable amount of traffic. In other words, at the very beginning of your blogging days, it is difficult to be accepted as a publisher on those ad platforms.

Even though you get income for impressions, the real income comes with user interactions for ads you show. In other words, you mostly earn by the number of clicks your ads get.

The income by click depends on many factors such as purchasing power, a product that appears in ads etc… It is reasonable to get more when you show an ad to a U.S. citizen rather than a citizen of a country where its citizens have much lower income.

Here, the most popular ad platforms you can apply with your blog:

Affiliate Income

What is affiliate marketing?

One of the most used ways to get income from your content is affiliations. Basically, you review some products and link to those products.

The links have special fragments which detect new coming users that are acquired from your platform.

In this way, honest reviews will be rewarded as growing audiences. Growing audiences increase your visibility and so your income.

YouTube video reviews and other product reviews are examples of affiliation type of income. Those video links generally include Amazon affiliate links.

In this type of income, in other words, partnership, the affiliate (you) earns a commission for generating sales, leads, or other desired actions for the merchant through their unique referral link.

Let me draw a sample process for an affiliate marketing process.

How does affiliate marketing work?

Affiliates sign up for an affiliate program: Affiliates join an affiliate network or an individual company's affiliate program that offers products or services relevant to their niche.
Affiliates receive unique referral links: Once they've joined the program, affiliates receive unique referral links, which they can use to promote the merchant's products or services on their websites, blogs, social media platforms, or email campaigns.
Affiliates promote the products or services: Affiliates create content, such as blog posts, reviews, tutorials, or social media posts, to promote the merchant's products or services using their referral links.
Customers click on the referral links: When potential customers click on an affiliate's referral link and make a purchase or complete another desired action (e.g., signing up for a newsletter), the transaction is tracked and attributed to the affiliate.
Affiliates earn a commission: Based on the agreed-upon commission structure, affiliates earn a percentage of the sale or a fixed amount for each lead or action generated through their referral links.

Affiliate marketing benefits both the merchant and the affiliate. Merchants gain access to a wider audience and only pay for results, while affiliates can generate passive income by promoting products or services they believe in.

The most popular affiliate marketing program, affiliation platform, and curated lists are as follows:

Income from Subscriptions

We are living in a micro-creators era. If you believe that you have novel things to share, then subscription-based income would be a suitable option.

When you specialize in your niche, you'll have a laser-targeted audience. This not only allows you to earn by subscriptions, but also with targeted ads.

Furthermore, if you are writing on a profitable niche, then it means you'll have predictable income streams which is a must for full-time blogging.

Putting your content behind a paywall is getting more popular in these days.

Moreover, there are platforms to provide you with all the things you need, and they just cut a small portion of your monthly subscription income.

If you are planning to earn by this way, the content you create would generally be blog posts or email newsletters.

The most popular platforms to earn income by paywall are:

When you charge your audience with a relatively low price, it would be important to treat them well and provide them with unique and valuable content.

As a bonus, here is another tool to add a membership feature to your blog.

As I said before, generating revenue is a long-run process. It is better to improve it iteratively.

Typically, it is unclear that which action causes what due to the nature of abundance of factors. Thus, the iterative process makes you aware of your decisions.

Exploring SolidJS - The Reactive Primitives (1)

Can Burak Sofyalioglu — Wed, 06 Oct 2021 15:14:37 +0000

SolidJS is a true reactive library that allows you to use JSX for your frontend projects. In this blog post, I'll share my first impressions on the SolidJS UI library and its reactive primitives. The original article can be found here: "Introduction to SolidJS"

I like the concept of reactivity when building frontend projects. Despite its name, React is not a truly reactive library. I also like the Svelte because of its reactivity. I previously wrote a tutorial about Django and Svelte. However, I realized that writing projects with Svelte are not so scalable like React projects because React and JSX provide great modularity.

However, SolidJS offers the best of both worlds.

Shameless promotion

I'm currently not planning to do a real project with SolidJS until I become fluent in it. Currently, I'm building an e-commerce store, İzmir Güvenlik Kamerası (Security Camera Systems) and Fine Art Print Store, and I would work with SolidJS for small projects. You can also check the list of blogging sites

Introduction

OK, let's dive into the topic. Before reviewing SolidJS, it is better to get familiar with the concepts. I'll shortly talk about What are reactive systems? and what are those reactive primitives?.

What are reactive systems?

According to The Reactive Manifesto, reactive systems are responsive, resilient, elastic, and message-driven. We call these Reactive Systems.

Systems built as Reactive Systems are more flexible, loosely coupled, and scalable. This makes them easier to develop and amenable to change.

They are significantly more tolerant of failure, and when failure does occur they meet it with elegance rather than a disaster.

What Reactive Systems do

There are numerous reactive libraries in many programming languages like SolidJS in JS.

Reactive systems must react to data changes. Generally, these changes occur when new data is received or the old one is updated.

Characteristics of Reactive Programming

The reactive manifesto defines the key characteristics of it, like that:

Responsive: Those systems respond on time. Here, of course, timely will differ depending upon the application and domain.
Resilient. Reactive systems stay responsive in the face of failure.
Elastic. As the workload grows, the system should continue to be responsive.
Message Driven. Information is exchanged between elements of a reactive system using messages. This ensures loose coupling, isolation, and location transparency between these components.

What are the reactive primitives of SolidJS?

In SolidJS, the author of the library Ryan Carniato defines them as much like network primitives rather than JavaScript's primitives. As you will see later, Signals are basically observables.

Installation of SolidJS Template

You can easily install a starter SolidJS template with degit. You can also check other official templates from here: SolidJS Official Templates. I prefer a JS template rather than a TypeScript.

# Javascript template
npx degit solidjs/templates/js solid
cd solid

# install the dependencies
yarn install

The template uses Vite as a development tool. Also, this is the first time I have used Vite. Vite is so super fast that I had to check twice that if it reloaded the rendered page. When the installation is done, the project directory looks like that:

It is very similar to React in many cases. I will check some component rendering processes'.

In this post, I am going to explore SolidJS in an introductory manner. I'll also create a Counter component first and check its re-render process.

A Reactive JavaScript Library: SolidJS

A) Reactive primitives: createSignal

SolidJS has some basic reactive primitives, and Signals are one of them. It looks like it is a "useState" alternative of React Hooks. One difference to the "useState" hook is that a Signal returns two functions: a getter and a setter. Here is the official example of creating a signal:

createSignal function takes an initial value and returns an array with an access and update function.
You should execute the getter function (access) in order to get the value.
You can pass function to update function (set function). In this function, you can access the previous state also.

const [getValue, setValue] = createSignal(initialValue);

// read value
getValue();

// set value
setValue(nextValue);

// set value with a function setter
setValue((prev) => prev + next);

import { createSignal } from "solid-js";

function Counter({ initial }) {
    const [count, setCount] = createSignal(initial || 0);

    return (
        <div>
        {/* Notice the usage of count! It is a function*/}
            <h2>Count: {count()}</h2>
        </div>
    );
}

1) Component State Access and Update

SolidJS call the state elements as signals. However, I prefer to use state rather than signal. Let's make a Counter component within the App component. Fill the App.jsx file as follows:

import logo from "./logo.svg";
import styles from "./App.module.css";
import { createSignal } from "solid-js";

function App() {
    /**
     * CHECKPOINT
     * if the App component renders
     * it will print to console
     */
    //
    console.log("App component rendered.");

    return (
        <div class={styles.App}>
            <header class={styles.header}>
                <img src={logo} class={styles.logo} alt="logo" />
                <p>
                    Edit <code>src/App.jsx</code> and save to reload.
                </p>
                <a
                    class={styles.link}
                    href="https://github.com/solidjs/solid"
                    target="_blank"
                    rel="noopener noreferrer"
                >
                    Learn Solid
                </a>
                <Counter />
            </header>
        </div>
    );
}

function Counter({ initial }) {
    const [count, setCount] = createSignal(initial || 0);

    /**
     * CHECKPOINT
     * if the Counter component renders. it will print to console.
     * Also, I put another print statement for the count function.
     */
    //
    console.log("Counter component rendered.");
    console.log("Counter component count value: ", count());

    return (
        <div style={{ width: "100%", height: "auto" }}>
            {/* Notice the usage of count! It is a function*/}
            <h2>Count: {count()}</h2>
            <button onClick={() => setCount((c) => c + 1)}>Increase</button>
            <button onClick={() => setCount((c) => c - 1)}>Decrease</button>
        </div>
    );
}

export default App;

Let's check the browser and the first render of SolidJS. As you see, there is no extra component render. If it were React, we should have seen many times "Counter component rendered" text on the console.

2) Parent Component State Access and Update

Let's make it further and pass the signal setter to the child component and use it from there. Change both App and Counter components like that:

function App() {
    /**
     * CHECKPOINT
     * if the App component renders
     * it will print to console
     */
    //
    const [appCount, setAppCount] = createSignal(0);
    console.log("App: count: ", appCount());
    console.log("App component rendered.");

    return (
        <div class={styles.App}>
            <header class={styles.header}>
                <img src={logo} class={styles.logo} alt="logo" />
                <p>
                    Edit <code>src/App.jsx</code> and save to reload.
                </p>
                <a
                    class={styles.link}
                    href="https://github.com/solidjs/solid"
                    target="_blank"
                    rel="noopener noreferrer"
                >
                    Learn Solid
                </a>

                {/* NEW */}
                <h2>App Count: {appCount()}</h2>

                <Counter
                    initial={appCount()}
                    setAppCount={setAppCount} // NEW
                />
            </header>
        </div>
    );
}
function Counter({ initial, setAppCount }) {
    const [count, setCount] = createSignal(initial || 0);

    /**
     * CHECKPOINT
     * if the Counter component renders. it will print to console.
     * Also, I put another print statement for the count function.
     */
    //
    console.log("Counter component rendered.");
    console.log("Counter component count value: ", count());

    return (
        <div style={{ width: "100%", height: "auto" }}>

            {/* Notice the usage of count! It is a function*/}
            <h2>Count: {count()}</h2>
            <button onClick={() => setCount((c) => c + 1)}>Increase</button>
            <button onClick={() => setCount((c) => c - 1)}>Decrease</button>
            <hr />

            {/* Buttons changes the signal value of its parent component */}
            <button onClick={() => setAppCount((c) => c + 1)}>
                AppCount Increase
            </button>
            <button onClick={() => setAppCount((c) => c - 1)}>
                AppCount Decrease
            </button>
        </div>
    );
}

As you can see, there is not any component re-rendering. It's awesome.🥳

B) Reactive primitives: createEffect

As you might expect, createEffect is the equivalent of the useEffect hook in React. The official explanation and example are as follows:

Creates a new computation that automatically tracks dependencies and runs after each render where a dependency has changed. Ideal for using refs and managing other side effects.

const [a, setA] = createSignal(initialValue);

// effect that depends on signal `a`
createEffect(() => doSideEffect(a()));

It's time to play with this function. The official example returns a function (doSideEffect) that takes state value as its argument. Even if the returning function doesn't take the state value as its argument but as an inner value, the createEffect function successfully makes a side-effect.

Let's add those to the App component.

    // The function creates side-effect
    const changeTitle = (val) => (window.document.title = `#App: ${val}`);

    // effect that depends on signal `a`
    createEffect(() => changeTitle(appCount()));

We created a function (changeTitle) responsible for the side-effect. It takes a value and changes the document title according to that. It also takes the state value of the App component which is appCount. Your app component should look like this.

function App() {
    const [appCount, setAppCount] = createSignal(0);
    console.log("App: count: ", appCount());
    console.log("App component rendered.");

    // The function creates side-effect
    const changeTitle = (val) => (window.document.title = `#App: ${val}`);

    // effect that depends on signal `a`
    createEffect(() => changeTitle(appCount()));

    return (
        <div class={styles.App}>
            <header class={styles.header}>
                <img src={logo} class={styles.logo} alt="logo" />
                <p>
                    Edit <code>src/App.jsx</code> and save to reload.
                </p>
                <a
                    class={styles.link}
                    href="https://github.com/solidjs/solid"
                    target="_blank"
                    rel="noopener noreferrer"
                >
                    Learn Solid
                </a>

                {/* NEW */}
                <h2>App Count: {appCount()}</h2>

                <Counter
                    initial={appCount()}
                    setAppCount={setAppCount} // NEW
                />
            </header>
        </div>
    );
}

You'll easily differentiate that when the app renders the first time, the document title was App: 0

After, when I clicked and increased the appCount value, the document title also changed to the corresponding value. You'll also notice that there will be no component re-render.

C) Reactive primitives: createMemo

This reactive primitive returns a function that returns a read-only derived signal. Its value is recalculated whenever dependencies are updated. createMemo primitive is the equivalent of useMemo hook.

Edt the App component according to those:

    // Add those to the App component
    // It recalculate the value whenever the dependencies are updates.
    const makeDouble = (val) => val * 2
    const doubleCount = createMemo(() => makeDouble(appCount()))
    console.log("doubleCount ", doubleCount());

Also, update the content of the App component. By doing this, we can see the doubleCount signal in work. You can also check the code location from the image below.

<h2>Double Count: {doubleCount()}</h2>

D) Reactive primitives: createResource

This function creates a signal that is responsible for async requests. The official explanation and example are here:

Creates a signal that can manage async requests. The fetcher is an async function that accepts the return value of the source if provided, and returns a Promise whose resolved value is set in the resource. The fetcher is not reactive, so use the optional first argument if you want it to run more than once. If the source resolves to false, null, or undefined will not fetch. Also, loading and error are reactive getters and can be tracked.

const [data, { mutate, refetch }] = createResource(getQuery, fetchData);

// read value
data();

// check if loading
data.loading;

// check if errored
data.error;

// directly set value without creating promise
mutate(optimisticValue);

// refetch last request just because
refetch();

My first impressions of SolidJS are amazing. Up to this point, there is no overhead that you always face with React. I will be watching the development of SolidJS with interest.

Awesome Content Creation Tools

Can Burak Sofyalioglu — Sun, 19 Sep 2021 19:00:13 +0000

(Note: This post was updated on 15 December 2021)

Creating quality content is a demanding and complex process. It is better to have a wide range of applications in your toolbox. Even though there is no one solution to fix it all, one can increase your productivity and save you time. Considering this, I will share my favorite content creation tools. These are both written content and visual content.

You can also check the original post for updated resources: Content creation tools

Great Content Creation Tools

Using the appropriate tools can make content creation so much easier and more successful. After the introduction, it is time to share the useful content marketers tools. I hope those tools will make you more productive during your content creation process. Here are the super-useful content development tools. You may also want to check the ultimate list of blogging sites which includes more than 50 publishing sites.

Content Research Tools

Research plays a huge role in what your readers think of your business, products, services, and website. Content creation can be as easy as digging up information or digging around on the internet.

In this section, I’ll take you through some of the most useful tools out there so that you can get started on creating great content for your blog or website.

Content research tools are essential when creating content because the internet is vast, and there’s hardly any limit to what you can find out about a subject matter.

Carrot: The short demo you watched above is from Carrot. It organizes your search results into topics. It clusters, categorizes and show them in different formats.
Occamm: Occam is another SERP organizer. It refines your search result and allows you to select based on the tags.
Entity Explorer: Entity explorer finds related entities in a graph map. It makes easier to see connections between entities.
Research Rabbit: This is one of my favorite research tools. A research and relationship visualization tool.
Semantic Scholar: A free, AI-powered research tool for scientific literature.
Paper Panda and
Unpaywall: They both allow you to access millions of academic papers and researches for free.
Google Trends: You probably know this tool. Google Trends shows the popularity of a term among Google Searchers.
Answer The Public: Another useful tool to research people’s questions.
Miro: Miro is actually a whiteboard app. It allows collaboratively working on your content ideas. There are plenty of project management frameworks that make your ideation process easier.

Content Management Tools

You need comprehensive document and knowledge management tools to get the most out of your content research. You can clip, capture, and annotate the content with these creation tools. There are a bunch of apps that you can use for this purpose. Most of those tools have browser extensions.

Annotating is an excellent way to get your creative juices flowing. It allows you to take notes on what you’re reading or thinking, making it easy to revise later.

I love using various notes apps or knowledge-saving tools and would recommend them to anyone looking to improve their writing skills.

These content creation tools allow anyone to collect ideas, quotes, share knowledge and other content in an easy and intuitive way. These content saving/management tools save you time looking for relevant information while creating your blog posts and videos.

Free Blogging Platforms: An article that mentions the best free blogging platforms.
Polar: You can manage and save your content from PDFs, EPUBs, and web pages in one place. It allows tagging, shows reading progress, and shows detailed document information.
Weava: You can highlight, annotate, and organize the content in one place.
Memex: It is a bookmark manager. It is an open-source tool that allows you to annotate, organize and share.
JustClip: A tool for collecting content that is suitable for individuals and teams. You can capture information and annotate content. You can easily build your knowledge connections and stay organized.
Wakelet: Wakelet is a tool for collecting and curating content. It is particularly used by the education industry.It is one of my favorite tools. You can create a Wakelet profile and a collection and publish your curated lists in various formats.
Liner: Liner is another productivity tool that helps you find and learn reliable information faster. You can highlight web pages and PDF files. It suggests trusted content from other Liner users.
Obsidian MD: It is also my favorite tool that I dumped every piece of note into it. It is offline-first meaning that your notes stay on your PC. It is a markdown editor and has a wiki-style backlink feature with built-in graph view options. There are other popular options for an alternative to Obsidian are Notion, Nimbus Note, and Roam Research and Notesnook.
Raindrop: Raindrop is one of the best bookmark manager in the market. It has cross-platform apps/extensions, intuitive user-interface and a generous plan.

Readability Score Tools

Readability is the ease with which a reader can understand a written text.

It is an essential parameter for the user as well as for SEO.

It is also known that artificial intelligence, and thus the Google crawler, is better at distinguishing short sentences than long ones.

As a result, short sentences are easier to understand for both the reader and the Googlebot. Of course, you have to consider your readers.

There will be no problem for them in writing complex articles on relatively tricky subjects if your readers are experts on your case.

The content creation software in this section are applications that measure at least which age group can understand your articles. It is called the readability score.

There are some popular formulas and metrics calculating the readability score of your text.

However, creating short and concise content can be hard to create. With the tools below, you can make your copy more readable and quickly shorten sentences. Run your written copy through the web app and you’ll see the opportunities to make it better for your readers in seconds.

It should also be noted that most of them are either free or freemium with a generous plan.

Hemingway Editor: It is one of the most well-known content readability improvers. This popular readability tool judges the “grade level” of your text using the Automated Readability Index.
Typewipe: This helpful content creation program offers both readability analysis and helps you improve your content according to your keyword.
Twinword Writer: Twinword Writer is a tool that analyzes the tone of your content. It highlights the words that have negative and positive impacts on the tone of your text.

Grammar and Punctuation Checker Tools

The content creation tools in this section are handy for creating content in English. Those can be classified as grammar correction and punctuation checker tools. Using these tools will help you write better content about topics that matter to you.
The tools in this section are awesome grammar and punctuation checker tools. Those will help you finish your sentences, spot typos, and get the words right no matter how much time you have.
The most popular grammar tool on this list is Grammarly. It offers a good user experience along with rich suggestions.

However, it should also be noted that Grammarly doesn’t improve its tool and features. There are various alternatives to that provide different writing features that Grammarly doesn’t provide.

You can also read The Best Grammar Tools article, which reviews different tools for this purpose.

Here are the best grammar and punctuation checker tools.

Grammarly: It is one of the most well-known grammar tools. Grammarly is the best tool for this task. It has a really intuitive interface and a lot of fun features. It has a desktop and mobile application. Those apps exist both for macOS and Windows.
Linguix: Another Grammarly alternative, this English content creation assistant also stands out with its paraphrase feature.
ProWritingAid: Although this content creation software does not offer as good a user experience as Grammarly and Linguix, it has much more advanced features.
Atomic Editor: It is an AI-assisted editor that boosts your writing productivity.
SlickWrite: A tool that shows grammatical corrections and useful statistics.
Ludwig: A search engine for sentences. You can find your sentence in the best contexts, get definitions, synonyms, and examples. Also, you can paraphrase your sentence.
Ginger: Another Grammarly alternative tool that helps you correct grammar and punctuation.
Writer: I just discovered the app. First, it has a great design. Moreover, Writer provides many useful features comparing its competitors like a more customizable style guide and a bunch of many other things. It also has a free plan. You can use its web app, browser extension, or outlook app.

Search Engine Optimized Content Creation Tools

It is not easy to find both budget-friendly and skilled tools. Of course, I’m speaking particularly about marketing tools. Anyway, I’ll share my relatively budget-friendly and search-engine-optimized content creation tools.

SEO Content Analyzer: It has a bunch of tools for copywriting.
Frase: This is one of my favorite tools. An AI-based content creation tool. Moreover, advanced paraphrasing and question-based features.
CanIRank: My other favorite SEO content tool that optimizes your content for search engines. When the first analysis is complete, it shows pretty useful keyword opportunities.
Ink: Another SEO web content writing editing tool that you can download.

Visual Content Creation Tools

I don’t remember who said it but it is true: “If content is king, then design is queen”. Whether you are creating visual content or written content, visually appealing content is preferable to the other. You can easily find the visual content creation tools you need such as:

Image Creation Tools/ Social Media Tools
Video Creation Tools
Infographic Creation Tools
Presentation Creation Tools

If you are more interested in visual design resources, you can check my other curated list:

Free design resources.

Let’s start our list of digital content creation with some tools focused on creating and editing visual content elements.

Image creation/editing tools

There are a lot of free image editing tools out there. Some offer advanced editing features and others are more casual apps. But if you’re looking for a basic set of image editing tools that can help you get your job done, then here are some of our favorites.

Figma: Oh great Figma. It is one of the greatest apps of the decade.
Canva: Canva is the most popular and the most used image creation tool. It has both free and premium plans. If you need quick visual content for your social media marketing operations, Canva is one of the best design tools.

There are also many image tools similar to Canva. Those are- Crello,- Artify,- Projector,- Taler,- Design AI, etc.

Photopea is one of my favorite tools. It is a minified version of photoshop and it is working on a browser.
Remove.bg and- Erase.bg: A well-known background remover. You can extract people from an image.

Presentation tools

Presentations are the core engine of any persuasive speaker. They establish credibility, inspire others, and move audiences emotionally. That’s why the first step in any persuasive presentation is to select the right tools.

Presentations are a fundamental tool for any professional, whether they want to build a reputation or just sell products.

Pitch: This presentation creation tool allows you to collaboratively create your design asset.
Ludus: It is a collaborative presentation tool for creative teams
Premast Plus: You can use its professional templates to design better presentations and with a faster way. Even if you don’t have any design experience.

Infographic tools

A well-designed infographic can go a long way towards convincing people to click through from a website or social media channel. Infographics are powerful, flexible, and can be used to achieve a wide range of results.

They’re an effective tool for getting immediate attention – without creating an overwhelming feeling. If it is done correctly, infographics can be a backlink magnet.

Visme: Visme is an online tool that allows you to easily create infographics. Those are very useful for visual explanations and building backlinks.
Infogram: Infogram is a visual creation tool that allows you to create infographics and visual stories with data.
Piktochart: Piktochart is another super functional tool for the visual content creation process. It helps you to make gorgeous infographics, presentations, and reports.
Venngage: An infographic design solution.
Graficto: Graficto is an infographic maker tool that is recently launched

Video creation tools

Video content is consumed super-fast compared to written one. Therefore, it is widely popular among the mass. Having a useful instrument will definitely make your life easier.

Animoto: Animoto is a video creation tool with a drag-and-drop interface. It has templates that allows you start with pre-made graphics.
Biteable: One of the favorite video creation tools of content marketers. Express any concept. Personalize colors to match your brand.
RenderForest: Another tools for creating video content.
Runway ML: This tool is literally amazing. However, it has a steep learning curve because Runway has many features that use machine learning.
Powtoon: A suit of video creation tools. You can crop, rotate your videos. Powtoon also has a unique feature that removes watermarks from videos.

Miscellaneous Tools

Buyer Persona: You should know who you are speaking if you have an intention to make your reader comfortable. This tool allows you to create a buyer persona.
Otter: A tool for generating notes from audio records.
Giphy: Who doesn’t love GIFs. You can search and use millions of GIFs.

As I said before, this post is a growing list of content creation tools. I’m trying to add great content development and content creation tools to here. Therefore, it is better to bookmark and come back later.

Exploring the Nx Framework: Next JS Development

Can Burak Sofyalioglu — Mon, 30 Aug 2021 05:22:11 +0000

NX Workspace Introduction

In this blog post series, I am going to explore the features that NX workspace that provides. The original post can be found on NextJS Tutorial with Nx Framework .

In this blog post series, I am going to explore the features that NX workspace provides. I'm going to build a simple Next JS web app with Tailwind CSS styling within the Nx workspace.

Shameless promototion

This post was written during the research process of Alarm systems guide (Alarm sistemleri in Turkish). You can also check the list of blogging sites

NX is an advanced set of extensible dev tools for mono repositories, with a strong emphasis on modern full-stack web technologies.

1) Setup NextJS App on Nx Workspace

npm install -g nx

# Install and create workspace
npx create-nx-workspace nx-tutorial

# Choose project types
✔ Workspace name (e.g., org name)     · nx-tutorial
? What to create in the new workspace … 
❯ empty             [an empty workspace with a layout that works best for building apps]
  react             [a workspace with a single React application]
  angular           [a workspace with a single Angular application]
  next.js           [a workspace with a single Next.js application]
  gatsby            [a workspace with a single Gatsby application]
  nest              [a workspace with a single Nest application]
  express           [a workspace with a single Express application]
  web components    [a workspace with a single app built using web components]
  react-express     [a workspace with a full stack application (React + Express)]
  angular-nest      [a workspace with a full stack application (Angular + Nest)]
  oss               [an empty workspace with a layout that works best for open-source projects]

# Choose whether you'll use Nx Cloud or not
✔ Use Nx Cloud? (It's free and doesn't require registration.) · Yes
>  NX  Nx is creating your workspace.

# get into the workspace
cd nx-tutorial

Nx Workspace directory structure

1.1) See the available plugins

You can see all of the available plugins with nx list command

# See the available plugins
nx list

>  NX  Installed plugins:

  @nrwl/jest (builders,generators)
  @nrwl/linter (builders)
  @nrwl/workspace (builders,generators)

>  NX  Also available:

  @nrwl/angular (generators)
  @nrwl/cypress (executors,generators)
  @nrwl/express (executors,generators)
  @nrwl/nest (executors,generators)
  @nrwl/next (executors,generators)
  @nrwl/node (executors,generators)
  @nrwl/nx-plugin (executors,generators)
  @nrwl/react (executors,generators)
  @nrwl/storybook (executors,generators)
  @nrwl/web (executors,generators)

>  NX  Community plugins:

1.2) Installation of the Next plugin

Now, install the Next plugin and see the options of it.

# Install the plugin
yarn add @nrwl/next

1.3) See the plugin options

Let's see what we can do with the plugin. You'll see the available options for the plugin you choose. I am going to generate an application but first I need to see all options. We have options four options to generate and 3 to execute.

# See the options for the plugin
# nx list [plugin]
nx list @nrwl/next

>  NX  Capabilities in @nrwl/next:

  GENERATORS

  init : Initialize the @nrwl/next plugin
  application : Create a Next.js application
  page : Create a Next.js page component
  component : Create a React component

  EXECUTORS/BUILDERS

  build : Build a Next.js app
  server : Serve a Next.js app
  export : Export a Next.js app. The exported application is located at dist/$outputPath/exported.

1.4) See the options for generating a Next application

Before generating the Next application, It will be better to see initial configuration options for generating an app. To do this, I must append help flag to the end of the command.

# See the options for generating a Next application
nx generate @nrwl/next:application --help

nx generate @nrwl/next:application [name] [options,...]

Options:
  --name                  The name of the application.
  --directory             The directory of the new application.
  --style                 The file extension to be used for style files. (default: css)
  --server                The server script path to be used with next.
  --linter                The tool to use for running lint checks. (default: eslint)
  --skipFormat            Skip formatting files
  --skipWorkspaceJson     Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style)
  --unitTestRunner        Test runner to use for unit tests (default: jest)
  --e2eTestRunner         Test runner to use for end to end (e2e) tests (default: cypress)
  --tags                  Add tags to the application (used for linting)
  --js                    Generate JavaScript files rather than TypeScript files.
  --setParserOptionsProjecWhether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons.
  --standaloneConfig      Split the project configuration into <projectRoot>/project.json rather than including it inside workspace.json
  --dryRun                Runs through and reports activity without writing to disk.
  --skip-nx-cache         Skip the use of Nx cache.
  --help                  Show available options for project target.

1.5) Generating a Next JS application

It is better to use —dryRun flag on generating an application. Also, I need to give a name to my app. When I execute the command, some configuration options will be available to me. I'll stick with CSS styling option

# I'll also choose the name of the app as "store"
nx generate @nrwl/next:application store

? Which stylesheet format would you like to use? … 
❯ CSS
  SASS(.scss)       [ http://sass-lang.com          ]
  Stylus(.styl)     [ http://stylus-lang.com        ]
  LESS              [ http://lesscss.org            ]
  styled-components [ https://styled-components.com ]
  emotion           [ https://emotion.sh            ]
  styled-jsx        [ https://www.npmjs.com/package/styled-jsx ]

1.6) Start Next JS Application

After setting up the Next application, let's open workspace.json file. In the file, you will see the target list under the store application. Those are the actions that I can do with the Next JS application.

{
  "version": 2,
  "projects": {
    "store": {
      "root": "apps/store",
            --- --- --- --- --- ---
      "targets": {
        "build": {
                    --- --- --- --- --- ---
        },
        "serve": {
                    --- --- --- --- --- ---
        },
        "export": {
                    --- --- --- --- --- ---
        },
        "lint": {
                    --- --- --- --- --- ---
        }
      }
    },
    --- --- --- --- --- ---
    --- --- --- --- --- ---

Now, I can start serving the app by the run command.

# Serving the app
# nx run [project]:[target]
nx run store:serve

Now, open your browser and navigate to http://localhost:4200/

2) Installing Dependencies

2.1) TailwindCSS Setup

I am going to style the web app with Tailwind CSS. Let's add the dependencies of it.

# Tailwind CSS dependencies
yarn add -D tailwindcss@latest postcss@latest autoprefixer@latest

# Other styling libs
yarn add @heroicons/react @headlessui/react

# Put tailwind config file in the app dir
cd apps/store
npx tailwindcss init -p

// apps/store/postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: { config: './apps/store/tailwind.config.js' },
    autoprefixer: {},
  },
};

According to the docs, Nx utility function should be used for purge property. This eliminates additional manual maintenance as your workspace progresses. Also, it should be noted that Nx only purges on production build.

// apps/site/tailwind.config.js
const { join } = require('path');

// available since Nx v 12.5
const { createGlobPatternsForDependencies } = require('@nrwl/next/tailwind');

module.exports = {
  mode: 'jit',
  purge: [
    join(__dirname, 'pages/**/*.{js,ts,jsx,tsx}'),
    ...createGlobPatternsForDependencies(__dirname),
  ],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

2.2) Import TailwindCSS Styles

When I'm in the root folder, I'll create separate style file for tailwind.

# create tailwind.css file on pages dir
touch apps/store/pages/tailwind.css

/* apps/store/pages/tailwind.css */
@tailwind components;
@tailwind base;
@tailwind utilities;

/* apps/store/pages/styles.css */
@import "./tailwind.css";

/* The rest of styles.css file */
/* ----------------------------*/

3) Create a library

Nx framework allows you to structure your project with apps and libs. In other words, we don't need to create app libraries specifically in the app directory. We can also create separate and publishable libraries.

There are different types of libraries you can create:

Nx Library types

You can easily move the libraries using the @nrwl/workspace:move generator command

We have two options for building libraries either —buildable or —publishable. Those are valid for Angular, React, NestJS and Node. Therefore, I am going to use React libraries as a separate standalone publishable library.

You will also find useful options flag that you can pass to the CLI command. You can find the full list of the react:library options.

@nrwl/react:library flags

# Create a library wiht @nrwl/react package
# See which files will be written to the disk 
# (output is not produced)
nx g @nrwl/react:lib tailwind-ui --dry-run 

# Now create the library as publishable
# publishable flag requires importPath=npmusername/libraryname 
nx g @nrwl/react:lib tailwind-ui  --publishable --importPath=@canburaks/tailwind-ui --globalCss=true --component=false

# Also you can remove the library as like this
# nx g remove tailwind-ui

# You'll see the ouput like that
✔ Which stylesheet format would you like to use? · css
UPDATE workspace.json
UPDATE nx.json
CREATE libs/tailwind-ui/.eslintrc.json
CREATE libs/tailwind-ui/.babelrc
CREATE libs/tailwind-ui/README.md
CREATE libs/tailwind-ui/package.json
CREATE libs/tailwind-ui/src/index.ts
CREATE libs/tailwind-ui/tsconfig.json
CREATE libs/tailwind-ui/tsconfig.lib.json
UPDATE tsconfig.base.json
CREATE libs/tailwind-ui/jest.config.js
CREATE libs/tailwind-ui/tsconfig.spec.json

4) Create a components

Now, I generated a publishable user interface component library. I'm planning to populate this library with tailwind components.

Additionally, style=none flag is added because components styling will be done by tailwind classes and there is no need to create extra style file.

Also, the library will not include tailwindcss library, meaning that the library has a peer dependency of tailwindcss.

@nrwl/react:components flags

4.1) Generate components for the library

# Navbar component
nx g @nrwl/next:component Navbar --project=tailwind-ui --style=none --export=true  

# Footer component
nx g @nrwl/next:component Footer --project=tailwind-ui --style=none --export=true

4.2) Generate components for the app

I generated the required files for the library components. It is a good practice to create Layou component for the NextJS apps. Let's create it.

nx g @nrwl/next:component Layout --project=store --style=none

Now, fill those files likes these:

// apps/store/components/layout/layout.tsx

import Navbar from './navbar'
import Footer from './footer'

export default function Layout({ children }) {
  return (
    <>
      <Navbar />
      <main>{children}</main>
      <Footer />
    </>
  )
}

// libs/tailwind-ui/src/lib/navbar/navbar.tsx
export function Navbar() {
  return (
    <section className="w-full px-8 text-gray-700 bg-white ">
      <div className="container flex flex-col flex-wrap items-center justify-between py-5 mx-auto md:flex-row max-w-7xl">
        <div className="relative flex flex-col md:flex-row">
          <a
            href="/"
            className="flex items-center mb-5 font-medium text-gray-900 lg:w-auto lg:items-center lg:justify-center md:mb-0"
          >
            <span className="mx-auto text-xl font-black leading-none text-gray-900 select-none">
              cbsofyalioglu<span className="text-indigo-600">.</span>
            </span>
          </a>
          <nav className="flex flex-wrap items-center mb-5 text-base md:mb-0 md:pl-8 md:ml-8 md:border-l md:border-gray-200">
            <a
              className="mr-5 font-medium leading-6 text-gray-600 hover:text-gray-900"
              href="/contact"
            >
              Contact
            </a>
          </nav>
        </div>

        <div className="inline-flex items-center ml-5 space-x-6 lg:justify-end">
          <a
            href="/login"
            className="text-teal-600 px-8 py-2 border-teal-600  font-medium leading-6 border-2 rounded-lg transition ease-out duration-300 hover:text-blueGray-100 hover:bg-teal-600"
          >
            Login
          </a>
        </div>
      </div>
    </section>
  );
}

// libs/tailwind-ui/src/lib/footer/footer.tsx
export function Footer() {
  return (
    <section className="text-gray-700 bg-white body-font border-t-4 border-teal-800">
      <div className="container flex flex-col items-center px-8 py-8 mx-auto max-w-7xl sm:flex-row">
        <a
          href="https://www.filizguvenlik.com.tr"
          className="text-xl font-black leading-none text-gray-900 select-none logo"
        >
          cbsofyalioglu<span className="text-indigo-600">.</span>
        </a>
        <p className="mt-4 text-sm text-gray-500 sm:ml-4 sm:pl-4 sm:border-l sm:border-gray-200 sm:mt-0">
          © 2021 -{' '}
          <a href="https://webmeister.org" target="_blank" className="text-xs" rel="noreferrer">
            Webmeister
          </a>
        </p>
      </div>
    </section>
  );
}

// libs/tailwind-ui/src/index.tsx
export * from "./lib/navbar/navbar"
export * from './lib/footer/footer';

Now, I must build the library. By doing this, I'll be able to import the components to the app.

# build library
nx run tailwind-ui:build

// apps/store/pages/_app.tsx
import { AppProps } from 'next/app';
import Head from 'next/head';
import './styles.css';
import Layout from '../components/layout/layout';

function MyApp({ Component, pageProps }) {
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  );
}

export default MyApp;

// // apps/store/pages/index.ts
export default function Index() {
  return (
    <div className="min-h-screen">

    </div>
  );
}

Now, restart the server.

4) Generate pages

// Generate a contact page
nx generate page Contact

// apps/store/pages/contact.tsx
/* eslint-disable react/no-unescaped-entities */
/* eslint-disable @next/next/no-img-element */

export default function Contact(props) {
  return (
    <div className="container mx-auto mt-8 md:mt-0 md:space-x-10 md:grid grid-cols-3 justify-center md:py-40">
      <div className="grid justify-center items-center order-1 col-span-1">
        <img
          className="lg:h-80 md:h-64 h-40 rounded-full"
          src="https://cbsofyalioglu.fra1.cdn.digitaloceanspaces.com/cbs/cbsofyalioglu-black.png"
          alt=""
        />
      </div>
      <div className="mt-8 md:mt-0 lg:justify-end col-span-2">
        <h1 className="text-4xl text-gray-800 text-center md:text-left font-bold mb-6">
          Hi, I am Can Burak Sofyalioglu.
        </h1>
        <p className="text-xl text-gray-800 text-center md:text-left">
          I'm an engineer.
        </p>
      </div>
    </div>
  );
}