From 8518bed1314b3b57e765428dfb47a9f179b64f9e Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 15 Nov 2026 09:55:21 +0000 Subject: [PATCH] chore: publish this project's purview.dev catalogue record See ADR 0013 in purview-dev/purview-dev. --- .config/purview-docs.yml | 138 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 .config/purview-docs.yml diff --git a/.config/purview-docs.yml b/.config/purview-docs.yml new file mode 100644 index 0000000..b83cb72 --- /dev/null +++ b/.config/purview-docs.yml @@ -0,0 +1,138 @@ +# The purview.dev catalogue record for this project (ADR 0013 in purview-dev/purview-dev). +# The site reads this file from the default branch of this repository, so the record +# changes in the same pull request as the thing it describes. +# +# `$schema` is an editor hint and nothing more: the enforcing validation is the site's +# loader, which `just check-projects` runs there. +$schema: https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/lib/manifest/schema.ts + +id: results +name: Results +shortDescription: Result for .NET — expected failures as values the caller must handle. +description: >- + A small, dependency-free Result 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. +origin: >- + 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. +useWhen: >- + 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. +avoidWhen: >- + You target a runtime below .NET 11 with C# 15 preview, or the failures you + are modelling are exceptional circumstances that belong in exceptions. +repository: purview-dev/results +category: application-framework +status: stable +order: 45 +docs: + source: github-path + path: docs/wiki + rootPage: Getting-Started.md + exclude: + - _Sidebar.md + - Home.md + - index.md +targetFrameworks: + - net10.0 + - net11.0 +packages: + - id: Purview.Results + description: The result type, its factories, IResultValue, and the bundled union source generator. No dependencies. + primary: true + # Purview.Results.SourceGenerator was published by mistake and is now packed + # into Purview.Results as an analyzer, so it is deliberately not declared here. + - id: Purview.Results.AspNetCore + description: Result-to-response mapping, endpoint filter, and dependency-injection registration. + - id: Purview.Results.ZodSharp + description: Bridges ZodSharp validation results into results. + - id: Purview.Results.ZodSharp.AspNetCore + description: Renders validation-carrying failures as HttpValidationProblemDetails. +related: + - zodsharp + - sourcegenerator-framework +useCases: + - audience: developer + title: Return expected failures as values + scenario: >- + 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. + code: | + Result GetTenant(TenantId tenantId) => + _tenants.TryGet(tenantId, out var tenant) + ? Result.Success(tenant) + : new TenantNotFound(tenantId).AsFailure(); + language: csharp + outcome: >- + The caller branches on the error value itself, so TenantNotFound keeps carrying + its TenantId instead of being flattened into a message. + evidence: >- + The core package has no dependencies: it ships the result type, its factories, + and IResultValue without pulling anything else in. + docsPage: core-concepts + - audience: developer + title: Generate the failure helper for every union case + scenario: >- + 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. + code: | + [GenerateResult] + public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists); + language: csharp + outcome: >- + The generator emits AsFailure() for every case of an annotated union, + plus a code fix and a CA1815 suppression, so the declaration needs no pragma. + evidence: >- + 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. + docsPage: union-errors + - audience: architect + title: Map one error union onto HTTP responses + scenario: >- + 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. + code: | + builder.Services.AddResultsHttp(options => options + .Map(error => TypedResults.NotFound()) + .Map(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict)) + ); + + app.MapGet("/tenants/{id:int}", (int id) => GetTenant(id)).WithResultsHttp(); + language: csharp + outcome: >- + The mapping is declared once at startup, WithResultsHttp() applies it to the + endpoints, and a host can replace IResultsHttpMapper when it needs different + behaviour. + evidence: >- + Mappings resolve in declaration order — any mapping or failure mapper the host + declared earlier always wins — so the most specific rule is registered first. + docsPage: aspnetcore-integration + - audience: team-lead + title: Let ZodSharp validation failures become validation problems + scenario: >- + 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. + code: | + { + "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" }] + } + language: json + outcome: >- + A failure that implements IValidationErrorCarrier becomes + HttpValidationProblemDetails without the host mapping it, unless a per-code or + per-category rule answers that failure first. + evidence: >- + The response is ASP.NET Core's own HttpValidationProblemDetails contract, so API + clients keep the error shape they already parse. + docsPage: zodsharp-problemdetails