Cratis.Fundamentals
7.34.2
Prefix Reserved
dotnet add package Cratis.Fundamentals --version 7.34.2
NuGet\Install-Package Cratis.Fundamentals -Version 7.34.2
<PackageReference Include="Cratis.Fundamentals" Version="7.34.2" />
<PackageVersion Include="Cratis.Fundamentals" Version="7.34.2" />
<PackageReference Include="Cratis.Fundamentals" />
paket add Cratis.Fundamentals --version 7.34.2
#r "nuget: Cratis.Fundamentals, 7.34.2"
#:package Cratis.Fundamentals@7.34.2
#addin nuget:?package=Cratis.Fundamentals&version=7.34.2
#tool nuget:?package=Cratis.Fundamentals&version=7.34.2
Fundamentals
The shared building blocks beneath the Cratis stack — concepts, serialization, dependency injection, and type discovery for .NET and TypeScript, with typed concepts and codecs for Go.
Packages
Builds
Description
The Cratis Fundamentals holds generic reusable helpers, utilities and tools that aims at solving common problems and help developers be more productive. Fundamentals offers functionality for .NET and JavaScript environments. It is not a goal to have parity, as the different environments offer different building blocks.
You should look at it as a convenience layer on top of the existing base environment you're running in.
Fundamentals underpins the rest of the Cratis stack: Chronicle (the event-sourcing database and runtime), Arc (the CQRS application framework for ASP.NET Core), and Components (the React component library) all build on it — and you can use it on its own.
Start with your platform
- C# / .NET: give domain values distinct types with
ConceptAs<T>, discover services by convention, or represent absence and failure explicitly. - TypeScript: use GUIDs, serialization, property-path helpers, and decorators.
- Go: use typed concepts and scalar codecs, correlation, naming, and optional dependency injection.
The APIs differ by platform; a feature in the .NET package is not a promise of a TypeScript or Go equivalent. You can use Fundamentals without Arc or Chronicle.
Try the .NET package on its own
With a .NET 10 SDK, create a console project and install the package:
dotnet new console --framework net10.0 --name FundamentalsDemo
cd FundamentalsDemo
dotnet add package Cratis.Fundamentals --version 7.32.0
Replace Program.cs with this complete example:
using System;
using Cratis.Monads;
public static class QuickStart
{
public static void Main()
{
Option<string> timeout = "30";
Console.WriteLine(timeout.Match(
value => $"Configured: {value}",
_ => "Use the default timeout"));
}
}
Option<string> represents either text or an explicit absence. Match handles both cases and returns the selected message. Run it:
dotnet run
Expected output:
Configured: 30
Continue with the Option, Result, and Catch chapter to look up an absent setting, reject invalid input with a typed error, and adapt a throwing parser. These APIs live in Cratis.Monads in the core package; they need no host or running service.
Browse the Fundamentals documentation for the other building blocks.
Support
Cratis is an open community, and we are glad to help users, teams evaluating the stack, and contributors.
| Channel | Details |
|---|---|
| Discord | Join the community on Discord for questions and discussions |
| GitHub Issues | Report bugs or request features |
| Documentation | Read the docs at cratis.io |
Contributing
If you want to jump into building this repository and possibly contributing, please refer to contributing.
Prerequisites
The following are prerequisites to work with this repository.
- .NET SDK 11.0 (currently a release candidate), as selected by
global.json(roll-forward policylatestFeature). - Node 23+ (
engines.nodeis>=23.0.0inpackage.json). - Yarn
Consumers of the published libraries are not affected by these contributor requirements; the libraries target net10.0 and net11.0.
Running .NET specifications
The specifications use Cratis.Specifications 5.0 on the native xUnit v3 runner and require .NET 11.
Specification projects target net11.0 by default. Set -p:SpecificationsTestFrameworks='"net10.0;net11.0"' to build them for both, as CI does; libraries build and pack for net10.0 and net11.0 in Release.
From the repository root, build once and run the five specification executables in parallel:
dotnet build -c Release
bash .github/scripts/run-specifications.sh Release
To run on both target frameworks, build with -p:SpecificationsTestFrameworks='"net10.0;net11.0"' and set SPECIFICATION_FRAMEWORKS="net10.0 net11.0" for the script.
Logs and TRX results go under TestResults/. The script fails if a project is missing, fails, or runs zero tests.
Use bash .github/scripts/run-specifications.sh --self-test to check the runner's failure guards.
For a single project, run its executable directly (append .exe on Windows):
Source/DotNET/Fundamentals.Specs/bin/Release/net11.0/Cratis.Fundamentals.Specs
Use -method, -class, or -namespace with a fully qualified name to filter the executable's tests;
run it with -? to see all options. For example:
Source/DotNET/Fundamentals.Specs/bin/Release/net11.0/Cratis.Fundamentals.Specs -namespace 'Cratis.Concepts*'
dotnet test -c Release --no-build and IDE test explorers continue to use the VSTest adapter.
They do not require Microsoft.Testing.Platform configuration. For Debug, build with dotnet build and run dotnet test --no-build.
AOT.Specs is skipped by dotnet test; run it as an executable through bash .github/scripts/run-specifications.sh Release (also covered by the native-aot CI job).
Central Package Management
This repository leverages Central Package Management, which means that all package versions are managed from a file at the root level called Directory.Packages.props.
In addition there are also Directory.Build.props files for setting up common settings that are applied cross cuttingly.
Root package.json
The package.json found at the root level defines all the workspaces. It is assumed
All developer dependencies are defined in the top level package.json. The reason for this is to be able to provide global scripts
for every package to use for easier maintenance.
The package.json found at the top level contains scripts that can then be used in a child project for this to work properly.
In a package, all you need to do is to define the scripts to use the global scripts in the `package.json´ of that project:
{
"scripts": {
"prepublish": "yarn g:build",
"clean": "yarn g:clean",
"build": "yarn g:build",
"lint": "yarn g:lint",
"lint:ci": "yarn g:lint:ci",
"test": "yarn g:test",
"ci": "yarn g:ci",
"up": "yarn g:up"
}
}
The Cratis ecosystem
This project is part of the Cratis Platform — tools for building event-sourced and CQRS applications.
- Chronicle — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. Docs
- Chronicle clients — first-class .NET SDK, plus TypeScript, Kotlin/Java, and Elixir; Python coming soon. AI agents connect through the Chronicle MCP server.
- Arc — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. Docs
- Components — React components aligned with Arc patterns. Docs
- CLI + Workbench — inspect and diagnose Chronicle from the terminal or the browser. Docs
- Model-first layer — Studio, Screenplay, Stage, Scene, Prologue
- Supporting — Fundamentals, Specifications, Synopsis, Lens, Narrator, and free AI tooling; Ensemble coming soon
- Samples — runnable event sourcing and CQRS samples for the whole stack
Fundamentals is MIT licensed and free to use.
Join the community on Discord.
Release notes and announcements: the Cratis blog.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Humanizer (>= 3.0.10)
- Microsoft.Extensions.DependencyInjection (>= 10.0.14)
- Microsoft.Extensions.DependencyModel (>= 10.0.14)
- OneOf (>= 3.0.271)
- OneOf.SourceGenerator (>= 3.0.271)
- System.Reactive (>= 7.0.0)
-
net11.0
- Humanizer (>= 3.0.10)
- Microsoft.Extensions.DependencyInjection (>= 10.0.14)
- Microsoft.Extensions.DependencyModel (>= 10.0.14)
- OneOf (>= 3.0.271)
- OneOf.SourceGenerator (>= 3.0.271)
- System.Reactive (>= 7.0.0)
NuGet packages (137)
Showing the top 5 NuGet packages that depend on Cratis.Fundamentals:
| Package | Downloads |
|---|---|
|
Cratis.Arc.Core
Core command and query pipelines, validation, identity, and tenancy for Cratis Arc — the CQRS application framework for ASP.NET Core — hostable from workers, consoles, and custom services. |
|
|
Cratis.Chronicle
The .NET client SDK for Cratis Chronicle - the open-source (MIT) event-sourcing database and runtime. Typed events, projections, reducers, reactors, constraints, and read models over a gRPC boundary. |
|
|
Cratis.Chronicle.Contracts
Cratis Chronicle contracts library for the event-sourcing database and runtime. |
|
|
Cratis.Arc.MongoDB
MongoDB current-state persistence for Cratis Arc: serialization conventions, tenant-aware database resolution, resilient collection access, and observable change streams for CQRS read models. |
|
|
Cratis.Arc
Opinionated CQRS application framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing; Chronicle integration is optional. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 7.34.2 | 0 | 11/18/2026 |
| 7.34.1 | 102 | 11/15/2026 |
| 7.34.0 | 26,609 | 11/10/2026 |
| 7.33.1 | 22,865 | 11/3/2026 |
| 7.33.0 | 271 | 11/3/2026 |
| 7.32.1 | 105 | 11/2/2026 |
| 7.32.0 | 27,419 | 11/1/2026 |
| 7.31.0 | 115 | 11/1/2026 |
| 7.30.2 | 1,653 | 10/31/2026 |
| 7.30.1 | 120 | 10/31/2026 |
| 7.30.0 | 151 | 10/30/2026 |
| 7.29.0 | 222 | 10/29/2026 |
| 7.28.0 | 100 | 10/29/2026 |
| 7.27.1 | 9,913 | 10/29/2026 |
| 7.27.0 | 18,793 | 10/25/2026 |
| 7.26.3 | 101 | 10/25/2026 |
| 7.26.2 | 1,188 | 10/25/2026 |
| 7.26.1 | 14,183 | 10/23/2026 |
| 7.26.0 | 1,355 | 10/23/2026 |
| 7.25.2 | 314 | 10/20/2026 |