TripleG3.Cis 0.0.1

TripleG3.Cis

Asynchronously Request Change, Read Immutable State, Listen For State Changes - Clean, Simple, Safe

Command Immutable State Pattern: a tiny .NET library for services that need one clear state snapshot, one update pipeline, and simple change notifications.

Think of it as a calm little command center for async work: call a method, the service becomes Busy, it produces a value, then it becomes Ready. If something goes sideways, the state lands on Error with a message.

Install Or Reference

This repo currently contains the library project directly. Reference it from another project with a normal project reference:

<ItemGroup>
  <ProjectReference Include="..\TripleG3.Cis\TripleG3.Cis.csproj" />
</ItemGroup>

Build everything from the repository root:

dotnet build TripleG3.Cis.slnx

The Simple Idea

TripleG3.Cis gives you a pattern for command-driven state:

1. A public method represents the command, such as RefreshAsync or SetNextStepAsync.
2. The command calls SetAsync(...) with a StateValueFactory<T>.
3. StateService<T> serializes updates so one transition runs at a time.
4. Consumers read State or subscribe to StateChanged.

No mystery ceremony. Just immutable snapshots and predictable transitions.

API Tour

State Statuses

StateStatus.None means nothing has run yet.

StateStatus.Busy means a transition is running.

StateStatus.Ready means the latest value was produced successfully.

StateStatus.Error means the latest transition threw an exception. Check State<T>.ErrorMessage for the message.

Create A State Service

Derive from StateService<T> and expose command methods that call SetAsync.

using TripleG3.Cis;

public sealed record DownloadInfo(string FileName, int PercentComplete);

public sealed class DownloadStateService : StateService<DownloadInfo>
{
	public ValueTask<State<DownloadInfo>> RefreshAsync(CancellationToken cancellationToken)
	{
		return SetAsync(GetDownloadInfoAsync, cancellationToken);
	}

	private static async ValueTask<DownloadInfo> GetDownloadInfoAsync(CancellationToken cancellationToken)
	{
		await Task.Delay(250, cancellationToken);
		return new DownloadInfo("Guide.pdf", 100);
	}
}

Use it like this:

var service = new DownloadStateService();

service.StateChanged += (_, state) =>
{
	Console.WriteLine($"{state.Status}: {state.Value?.FileName} {state.Value?.PercentComplete}%");
};

State<DownloadInfo> result = await service.RefreshAsync(CancellationToken.None);

if (result.Status == StateStatus.Ready)
{
	Console.WriteLine($"Done: {result.Value.FileName}");
}

Examples Details

The src\TripleG3.Cis\Examples path contains a small console-friendly walkthrough. These types are examples, not required infrastructure for your own services.

Use The Example Service

The Examples folder contains a tiny workflow that walks through these values:

None -> Step1 -> Step2 -> Step3 -> Complete

using TripleG3.Cis.Examples;

var exampleApi = new ExampleApi();
var service = new ExampleService(exampleApi);
var watcher = new ExampleServiceWatcher(service);

await service.SetNextStepAsync(CancellationToken.None);
await service.SetNextStepAsync(CancellationToken.None);
await service.SetNextStepAsync(CancellationToken.None);
await service.SetNextStepAsync(CancellationToken.None);

Console.WriteLine(service.State.Status);
Console.WriteLine(service.State.Value);

ExampleService delegates step calculation to IExampleApi, then lets StateService<ExampleServiceSteps> handle the Busy, Ready, and Error transitions. ExampleServiceWatcher subscribes to StateChanged and writes each update to the console. It is intentionally simple so the state pattern is easy to see.

Console output from running src\TripleG3.Cis.ConsoleTest\TripleG3.Cis.ConsoleTest.csproj:

State changed: Busy - None
-----------------------------------------------------
State changed: Ready - Step1
-----------------------------------------------------
State changed: Busy - Step1
-----------------------------------------------------
State changed: Ready - Step2
-----------------------------------------------------
State changed: Busy - Step2
-----------------------------------------------------
State changed: Ready - Step3
-----------------------------------------------------
State changed: Busy - Step3
-----------------------------------------------------
State changed: Ready - Complete
-----------------------------------------------------

Use The Empty Service

IStateService<T>.Empty is handy when a caller needs an IStateService<T> but there is no real implementation yet.

IStateService<string> service = IStateService<string>.Empty;

State<string> state = await service.SetAsync(
	cancellationToken => new ValueTask<string>("This value is ignored."),
	CancellationToken.None);

Console.WriteLine(state.Status); // None

The empty service never invokes the factory and always returns State<T>.Empty.

Tips

• Keep state values small and meaningful. Records work nicely.
• Put business actions in command methods such as LoadAsync, SaveAsync, or SetNextStepAsync.
• Let SetAsync handle the transition state instead of setting status manually.
• Subscribe to StateChanged when a UI, console, or workflow needs to react.
• Inspect StateStatus.Error and ErrorMessage when a command fails.

AI Model Instructions

AI assistants working with this repository should follow these rules:

1. Treat State<T> as immutable. Use with expressions for changes inside library code.
2. Build new services by deriving from StateService<T> and exposing clear command methods.
3. Use SetAsync(StateValueFactory<T>, CancellationToken) for state transitions. Do not bypass the base class transition flow.
4. Depend on IStateService<T> when writing consumers that only need current state and change notifications.
5. Use StateChanged for observation, not polling loops.
6. Keep example code simple, async, and cancellation-token friendly.
7. Preserve the namespaces TripleG3.Cis and TripleG3.Cis.Examples unless the user explicitly asks for a namespace change.
8. Validate library changes with dotnet build TripleG3.Cis.slnx from the repository root.

Project Layout

src/
  TripleG3.Cis/
	Delegates.cs              StateValueFactory<T>
	IStateService.cs          IStateService<T>
	State.cs                  State<T>
	StateService.cs           StateService<T>
	StateStatus.cs            StateStatus
	Examples/
	  ExampleApi.cs           ExampleApi
	  ExampleService.cs       ExampleService
	  ExampleServiceSteps.cs  ExampleServiceSteps
	  ExampleServiceWatcher.cs
	  IExampleApi.cs          IExampleApi
	  IExampleService.cs