Skip to content
Purview Dev logo

The problem

A small, dependency-free Result<TValue, TError> for .NET that makes expected failures part of a method's contract: not found, invalid, and conflict are values rather than exceptions. A Roslyn source generator adds C# 15 union ergonomics for the error cases, and companion packages carry the result into ASP.NET Core responses and ZodSharp validation problems.

From the repository

Result types for .NET - a small, dependency-light Result<TValue, TError> where expected failures are values instead of exceptions, C# 15 union error cases with generated AsFailure<TValue>() helpers, and ASP.NET Core and ZodSharp integrations that map failures to HTTP responses.

Why it became a project

Services kept re-declaring their own error types and hand-writing the same failure helpers and HTTP mapping, so the result type, the generated helpers, and the adapter packages became one shared package family.

Where it fits

Use it when

Expected failures are part of your domain model and you want them returned as values the caller must handle, with a strongly typed error case that still reaches the client as a standard HTTP problem response.

It may not fit when

You target a runtime below .NET 11 with C# 15 preview, or the failures you are modelling are exceptional circumstances that belong in exceptions.

Use cases

Concrete examples of what Results does, and who each one is for.

Developer

Return expected failures as values

You call a store that can fail in ways you expect — not found, disabled, already exists — and you do not want a thrown exception or a generic error string to be the only way the caller learns what happened.

csharp
Result<Tenant, TenantError> GetTenant(TenantId tenantId) =>
    _tenants.TryGet(tenantId, out var tenant)
        ? Result<Tenant, TenantError>.Success(tenant)
        : new TenantNotFound(tenantId).AsFailure<Tenant>();

What you get: The caller branches on the error value itself, so TenantNotFound keeps carrying its TenantId instead of being flattened into a message.

The core package has no dependencies: it ships the result type, its factories, and IResultValue without pulling anything else in.

Read Core Concepts →
Developer

Generate the failure helper for every union case

You model errors as a C# 15 union and need each case to become the failure side of a result without writing one conversion helper per case by hand.

csharp
[GenerateResult]
public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists);

What you get: The generator emits AsFailure<TValue>() for every case of an annotated union, plus a code fix and a CA1815 suppression, so the declaration needs no pragma.

C# forbids the implicit conversion a bare case value would need — no operators in static classes, no conversion operators in extension members, one user-defined conversion per sequence — which is why the helper is per case.

Read Union Errors →
Architect

Map one error union onto HTTP responses

The same domain error union surfaces from many minimal-API endpoints, and you do not want a hand-written switch deciding the status code at each one.

csharp
builder.Services.AddResultsHttp(options => options
    .Map<TenantNotFound>(error => TypedResults.NotFound())
    .Map<TenantError>(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict))
);

app.MapGet("/tenants/{id:int}", (int id) => GetTenant(id)).WithResultsHttp();

What you get: The mapping is declared once at startup, WithResultsHttp() applies it to the endpoints, and a host can replace IResultsHttpMapper when it needs different behaviour.

Mappings resolve in declaration order — any mapping or failure mapper the host declared earlier always wins — so the most specific rule is registered first.

Read ASP.NET Core Integration →
Team lead

Let ZodSharp validation failures become validation problems

Endpoints validate input with ZodSharp, and a failed validation should reach the client as the standard ASP.NET Core validation-problem payload rather than an error shape the API has to document separately.

json
{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "TenantId": ["Required field 'TenantId' is null"] },
  "issues": [{ "code": "missing_field", "path": ["TenantId"], "message": "Required field 'TenantId' is null" }]
}

What you get: A failure that implements IValidationErrorCarrier becomes HttpValidationProblemDetails without the host mapping it, unless a per-code or per-category rule answers that failure first.

The response is ASP.NET Core's own HttpValidationProblemDetails contract, so API clients keep the error shape they already parse.

Read ZodSharp Problem Details →

Packages

4 packages

Purview.ResultsnugetInstall ↓2.0.0—1,294
Purview.Results.AspNetCorenugetInstall ↓2.0.0—1,110
Purview.Results.ZodSharpnugetInstall ↓2.0.0—1,094
Purview.Results.ZodSharp.AspNetCorenugetInstall ↓2.0.0—1,014

Install

Purview.Results primary

.NET CLI
dotnet add package Purview.Results

Purview.Results.AspNetCore

.NET CLI
dotnet add package Purview.Results.AspNetCore

Purview.Results.ZodSharp

.NET CLI
dotnet add package Purview.Results.ZodSharp

Purview.Results.ZodSharp.AspNetCore

.NET CLI
dotnet add package Purview.Results.ZodSharp.AspNetCore

Agent skills

Results authors agent skills for coding agents. They are installed explicitly with the skills CLI and are not part of any package.

Skills are installed explicitly with the skills CLI. Nothing ships them inside a NuGet package, and no build writes into your agent's directories: installation is a decision you make. Use whichever package manager you already have.

npm

Terminal window
npx skills add purview-dev/results

bun

Terminal window
bunx skills add purview-dev/results

pnpm

Terminal window
pnpm dlx skills add purview-dev/results

yarn

Terminal window
yarn dlx skills add purview-dev/results
  • Installs at project level by default. Add -g for a user-level install, or -a <agent> to target one agent.
  • To match the release you use, pin a commit or tag by appending #<ref> to any command above (for example npx skills add purview-dev/results#<ref>).
  • The CLI records what it installed in skills-lock.json; restore it with the same runner:
Terminal window
npx skills experimental_install
  • purview-results-core

    Use when writing or reviewing code that returns Purview.Results Result<TValue, TError> or value-less Result<TError> values — choosing between exceptions and results, creating, reading, or transforming a result, and reasoning about the uninitialized default state.

    1 file
  • purview-results-http-mapping

    Use when an ASP.NET Core endpoint returns Purview.Results values — registering AddResultsHttp, mapping error cases to status codes with Map<T>, answering a failure by its shape with an IResultsFailureMapper, using fallbacks, correcting unmapped-failure 500s, converting a result with ToHttpResult, or serving results from a Native AOT host.

    1 file
  • purview-results-union-errors

    Use when modelling expected failures as a C# 15 union (including a Purview.Unions [GenerateUnion] type) and converting its cases into Purview.Results values — declaring [GenerateResult] unions, using the generated per-case AsFailure<TValue>()/AsFailure() helpers and the union-receiver Union.Failure(...)/Union.Success(...) factories, reacting to the RSG1000-RSG1009 and RSG9000 diagnostics, or explaining why a union case cannot convert implicitly.

    2 files
  • purview-results-zodsharp-problems

    Use when a Purview.Results failure that carries ZodSharp validation errors has to render as an ASP.NET Core HttpValidationProblemDetails — registering AddResultsZodSharpHttp, calling ToValidationProblem, or making a result-carried rejection and a thrown ZodException produce identical responses.

    1 file
  • purview-results-zodsharp-validation

    Use when ZodSharp validation has to feed Purview.Results — converting ValidationResult<T> with ToResult or the value-discarding ToUnitResult (and their async forms, including over Purview.ZodSharp.Http), carrying ValidationError values on a union case, implementing IValidationErrorCarrier, or deciding what a rejected input becomes in the result pipeline.

    1 file