batchweaver

README

BatchWeaver

BatchWeaver is a proof-gated batching compiler and typed request-coalescing runtime for Go. It finds supported scalar access patterns—including common N+1 query shapes—proves their safety conditions, previews deterministic changes, and executes compatible calls in bounded batches without silently crossing request, tenant, authorization, transaction, or session boundaries.

Release status: v1.0.1 is the current stable release. The Tier 1 Go API is frozen under Semantic Versioning; bridge and the adapters/* packages are explicitly experimental, and compiler artifact schemas remain v1alpha1. Artifacts are checksummed and reproducible but not signed. See the release notes, the API freeze, and the stable-release decision, which records the accepted risks this release ships with.

Why BatchWeaver?

Hand-written batching can reduce backend round trips, but changing scalar code can also change evaluation order, error identity, cancellation, deadlines, result mapping, and isolation. BatchWeaver treats those behaviors as proof obligations rather than implementation details.

• Proof before transformation. Unknown or unsupported behavior is rejected.
• Overlay before mutation. Scan, proof, plan, diff, build, and test can run without changing source files.
• Typed library contracts. Generic requests, outcomes, providers, and declarations avoid reflection in application-facing code.
• Explicit isolation. Scope and partition contracts keep incompatible work out of the same batch.
• Fail-closed release tooling. Checksums, SBOMs, provenance, compatibility, and publication gates are verified separately from publishing.
• No hidden telemetry. Workload profiles exclude raw keys, payloads, credentials, tenant identifiers, and source.

BatchWeaver does not promise that every Go call can be batched or that batching always improves performance. Unsupported patterns remain scalar or are rejected with a diagnostic.

Install

Go 1.26.x is the tested support window: 1.26.0 is the minimum and 1.26.5 is the current pinned release toolchain.

Install the CLI or add the typed library at the immutable beta version:

go install github.com/Voskan/BatchWeaver/cmd/batchweaver@v1.0.1
go get github.com/Voskan/BatchWeaver@v1.0.1

For a source checkout at the same version:

git clone https://github.com/Voskan/BatchWeaver.git
cd BatchWeaver
git checkout v1.0.1
make build
./bin/batchweaver version
./bin/batchweaver doctor

Package documentation and import examples are available through pkg.go.dev. See Using BatchWeaver as a Go module for the library and CLI installation paths.

Use the Go package

Declare a scalar function and its compatible batch provider with one typed, statically discoverable value:

package users

import (
    "context"

    batchweaver "github.com/Voskan/BatchWeaver"
    "github.com/Voskan/BatchWeaver/operation"
)

type User struct {
    ID   int
    Name string
}

func loadUser(ctx context.Context, id int) (User, error) {
    // Scalar implementation.
    return User{ID: id}, nil
}

func loadUsers(
    ctx context.Context,
    req batchweaver.BatchRequest[int],
) (batchweaver.BatchResponse[User], error) {
    values := make([]User, req.Len())
    for i, item := range req.Items() {
        values[i] = User{ID: item.Key}
    }
    return batchweaver.OrderedOutcomes(req, values)
}

var GetUser = batchweaver.MustDeclareFunction(
    operation.MustNewSpec(
        operation.MustParseID("users.get"),
        operation.ReadOnly(),
        operation.WithOrderedResults(),
        operation.WithRequestScope(),
    ),
    loadUser,
    loadUsers,
)

This declaration does not start goroutines, register global state, or mutate source. The runtime API is opt-in; see the runtime guide and the compile-tested declaration example.

Five-minute workflow

# Inspect supported commands and validate configuration.
batchweaver help
batchweaver config validate --file examples/configuration/batchweaver.yaml

# Discover and prove candidates without modifying source.
batchweaver scan ./...
batchweaver prove ./...

# Review a deterministic plan and diff.
batchweaver transform plan ./...
batchweaver transform diff ./...

# Test transformed code through an overlay.
batchweaver test -- -race ./...

Materialization is a separate, explicit operation with backup, recovery, and revert support. Start with the verified batching tutorial.

Architecture

flowchart LR
    A["Go source and config"] --> B["Package loading and static analysis"]
    B --> C["Semantic proof obligations"]
    C -->|"proven"| D["Versioned transformation plan"]
    C -->|"unknown or unsafe"| R["Reject with diagnostic"]
    D --> E["Preview and build overlay"]
    E --> F["Transformed tests"]
    F -->|"explicit approval"| G["Optional materialization"]
    E --> H["Typed bridge and runtime"]
    H --> I["Partitioned batch provider"]

The compiler is conservative: proof certificates are versioned, source anchors are checked before use, transformed builds use overlays by default, and the runtime validates provider outcomes before returning them to callers.

Read the architecture overview, package boundaries, and safety model.

What is implemented

• typed operation, request, response, partition, scheduling, retry, and fallback contracts;
• explicit request-scoped runtime coalescing with bounded queues, independent cancellation, deadlines, deduplication, memoization, and result validation;
• Go package loading, SSA, conservative call-graph/effect analysis, candidate discovery, and deterministic reports;
• semantic proof certificates and static loop-prefetch/runtime-lowering transformations through build overlays;
• exact/composite-key PostgreSQL read synthesis with bounded at-most-one joins, compile-checked SQL binding overlays, database/sql, Redis mapping, explicit HTTP/OpenAPI batching, GraphQL wave analysis, and gRPC contracts;
• typed pgx v5, go-redis v9, gqlgen, and grpc-go integration packages on the default branch, with pgxmock, miniredis, public-extension, and bufconn tests;
• privacy-safe adaptive analysis, fairness, overload control, recursive waves, and bounded shadow/active tuning;
• standalone LSP, optional gopls proxy, VS Code extension, and a secure workspace daemon with bounded shared analysis caching for CLI/editor requests;
• deterministic release archives, checksums, SPDX/CycloneDX SBOMs, local provenance, compatibility reports, and non-publishing release verification.

Important limitations

• bridge and the four adapters/* client packages are experimental: they ship in the v1 module but are not covered by the v1 compatibility promise, because they track third-party client APIs.
• Release artifacts are checksummed, SBOM-documented, and reproducible, but they are not cryptographically signed and carry no hosted build attestation.
• Client integrations are covered by hermetic fakes, not by live PostgreSQL or Redis Cluster acceptance runs.
• SQL synthesis is limited to documented exact/composite-key PostgreSQL reads and one explicitly at-most-one INNER/LEFT join; writes, one-to-many joins, and arbitrary SQL rewrites are rejected.
• GraphQL/gRPC optimization requires explicit integrations; arbitrary network request fusion is not inferred.
• Compiler and runtime artifact schemas remain v1alpha1; they are regenerated rather than migrated and are excluded from the v1 API promise.
• Linux, macOS, and Windows hosted builds pass on the corrected release branch.
• The VS Code extension is supplied as a GitHub Release VSIX, not through the Visual Studio Marketplace.
• Checksums are published, but the beta has no cryptographic tag or artifact signature; see the release notes and verification instructions.

See known issues and the detailed limitations index.

Documentation

• Documentation website
• Runnable examples
• Go API and CLI
• Implemented features and v1 readiness
• Documentation index
• Tutorials
• How-to guides
• Reference
• Architecture
• Compatibility
• Security
• Support
• Contributing

Development

make fmt-check
go test ./...
go test -race ./...
go vet ./...
make check

Release assurance is non-publishing:

make release-snapshot
./bin/batchweaver release verify dist/release-manifest.json

Project status

v1.0.0 freezes the Tier 1 public Go API under Semantic Versioning and ships a tested upgrade path from every published prerelease. It ships with explicitly accepted risks — unsigned artifacts, hosted compatibility evidence not observed at the tagged commit, a short public prerelease period, and no live-backend acceptance — each recorded with a remediation plan in the stable-release decision and the machine-readable gate report.

The project does not claim long-term production-stability evidence. See beta evidence and the continuation plan.

License

Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.

Documentation

Overview

Package batchweaver defines the public, typed contracts used to declare and implement semantically safe Go batch operations.

The package provides generic request and response types, per-item outcomes, scalar and batch function signatures, and declarations that connect an operation.Spec to concrete implementations. Declarations have no global registration side effects and can be discovered statically by the BatchWeaver analyzer.

A batch provider must return exactly one outcome for every request ID unless it returns a global error. Helpers such as OrderedOutcomes, KeyedOutcomes, and SparseOutcomes preserve request identity and validate result shape. See the package examples for a complete typed declaration.

Request coalescing is implemented by the runtime package, normally imported with an alias:

import batchruntime "github.com/Voskan/BatchWeaver/runtime"

Static analysis, proof-gated transformation, overlays, and materialization are exposed through the batchweaver command. Source is never changed merely by importing this package or declaring an operation.

Index

• Constants
• Variables
• type BatchFunc
• type BatchItem
  • func NewBatchItem[K any](id RequestID, key K) BatchItem[K]
  • func (it BatchItem[K]) Validate() error
  • func (it BatchItem[K]) WithDeadline(d time.Time) BatchItem[K]
  • func (it BatchItem[K]) WithPriority(p int) BatchItem[K]
  • func (it BatchItem[K]) WithWeight(w int) BatchItem[K]
• type BatchMethod
• type BatchRequest
  • func MustNewBatchRequest[K any](items []BatchItem[K]) BatchRequest[K]
  • func NewBatchRequest[K any](items []BatchItem[K]) (BatchRequest[K], error)
  • func (r BatchRequest[K]) IDs() []RequestID
  • func (r BatchRequest[K]) Items() []BatchItem[K]
  • func (r BatchRequest[K]) Len() int
  • func (r BatchRequest[K]) Validate() error
• type BatchResponse
  • func KeyedOutcomes[K comparable, V any](req BatchRequest[K], values map[K]V, ...) (BatchResponse[V], error)
  • func MustNewBatchResponse[V any](outcomes []Outcome[V]) BatchResponse[V]
  • func NewBatchResponse[V any](outcomes []Outcome[V]) (BatchResponse[V], error)
  • func OrderedOutcomes[K, V any](req BatchRequest[K], values []V) (BatchResponse[V], error)
  • func OrderedResultOutcomes[K, V any](req BatchRequest[K], results []ItemResult[V]) (BatchResponse[V], error)
  • func SparseOutcomes[K, V any](req BatchRequest[K], lookup func(key K) (V, bool), ...) (BatchResponse[V], error)
  • func (r BatchResponse[V]) Len() int
  • func (r BatchResponse[V]) Outcomes() []Outcome[V]
  • func (r BatchResponse[V]) Validate() error
  • func (r BatchResponse[V]) ValidateAgainst(requestIDs []RequestID) error
• type FunctionDeclaration
  • func DeclareFunction[K, V any](spec operation.Spec, scalar ScalarFunc[K, V], batch BatchFunc[K, V]) (FunctionDeclaration[K, V], error)
  • func MustDeclareFunction[K, V any](spec operation.Spec, scalar ScalarFunc[K, V], batch BatchFunc[K, V]) FunctionDeclaration[K, V]
  • func (d FunctionDeclaration[K, V]) Batch() BatchFunc[K, V]
  • func (d FunctionDeclaration[K, V]) Scalar() ScalarFunc[K, V]
  • func (d FunctionDeclaration[K, V]) Spec() operation.Spec
  • func (d FunctionDeclaration[K, V]) Validate() error
• type ItemResult
• type MethodDeclaration
  • func DeclareMethod[R, K, V any](spec operation.Spec, scalar ScalarMethod[R, K, V], batch BatchMethod[R, K, V]) (MethodDeclaration[R, K, V], error)
  • func MustDeclareMethod[R, K, V any](spec operation.Spec, scalar ScalarMethod[R, K, V], batch BatchMethod[R, K, V]) MethodDeclaration[R, K, V]
  • func (d MethodDeclaration[R, K, V]) Batch() BatchMethod[R, K, V]
  • func (d MethodDeclaration[R, K, V]) Scalar() ScalarMethod[R, K, V]
  • func (d MethodDeclaration[R, K, V]) Spec() operation.Spec
  • func (d MethodDeclaration[R, K, V]) Validate() error
• type Outcome
  • func Failure[V any](id RequestID, err error) Outcome[V]
  • func NotFound[V any](id RequestID) Outcome[V]
  • func Success[V any](id RequestID, value V) Outcome[V]
  • func (o Outcome[V]) IsFailure() bool
  • func (o Outcome[V]) IsNotFound() bool
  • func (o Outcome[V]) IsSuccess() bool
  • func (o Outcome[V]) Validate() error
• type RequestID
  • func (id RequestID) IsValid() bool
• type ScalarFunc
• type ScalarMethod

Examples

• MustDeclareFunction

Constants

const (
	// MinPriority is the lowest allowed item priority.
	MinPriority = -1000
	// MaxPriority is the highest allowed item priority.
	MaxPriority = 1000
)

Priority bounds. Priority is relative: higher values indicate higher priority.

Variables

var ErrInvalidBatchItem = errors.New("invalid batch item")

ErrInvalidBatchItem is returned when a BatchItem fails validation.

var ErrInvalidBatchRequest = errors.New("invalid batch request")

ErrInvalidBatchRequest is returned when a BatchRequest fails validation.

var ErrInvalidBatchResponse = errors.New("invalid batch response")

ErrInvalidBatchResponse is returned when a BatchResponse fails validation.

var ErrInvalidOutcome = errors.New("invalid outcome")

ErrInvalidOutcome is returned when an Outcome fails validation.

var ErrNilImplementation = errors.New("nil implementation")

ErrNilImplementation is returned when a declaration is missing its scalar or batch implementation.

Types

type BatchFunc

type BatchFunc[K, V any] func(context.Context, BatchRequest[K]) (BatchResponse[V], error)

BatchFunc is the signature of a batch operation: many inputs, many outcomes. The returned error represents a global provider or transport failure; per-item failures belong in Outcome.Err.

type BatchItem

type BatchItem[K any] struct {
	// ID identifies the request; it must be non-zero.
	ID RequestID
	// Key is the operation input for this request.
	Key K
	// Deadline is an optional per-item deadline; the zero time means none.
	Deadline time.Time
	// Priority is the relative priority within [MinPriority, MaxPriority].
	Priority int
	// Weight is the item's cost contribution; it must be positive.
	Weight int
}

BatchItem is one logical request within a batch. Key is the operation's input value; the remaining fields are batching metadata. A zero Deadline means the item has no item-specific deadline. K is unconstrained: keys need not be comparable.

func NewBatchItem

func NewBatchItem[K any](id RequestID, key K) BatchItem[K]

NewBatchItem returns a BatchItem with the given ID and key, a weight of one, and no deadline or priority. Use the With* methods to set optional fields.

func (BatchItem[K]) Validate

func (it BatchItem[K]) Validate() error

Validate reports whether the item is well-formed.

func (BatchItem[K]) WithDeadline

func (it BatchItem[K]) WithDeadline(d time.Time) BatchItem[K]

WithDeadline returns a copy of the item with the given deadline.

func (BatchItem[K]) WithPriority

func (it BatchItem[K]) WithPriority(p int) BatchItem[K]

WithPriority returns a copy of the item with the given priority.

func (BatchItem[K]) WithWeight

func (it BatchItem[K]) WithWeight(w int) BatchItem[K]

WithWeight returns a copy of the item with the given weight.

type BatchMethod

type BatchMethod[R, K, V any] func(R, context.Context, BatchRequest[K]) (BatchResponse[V], error)

BatchMethod is a batch operation expressed as a method expression.

type BatchRequest

type BatchRequest[K any] struct {
	// contains filtered or unexported fields
}

BatchRequest is an immutable-by-convention, ordered collection of batch items with unique request IDs. Construct it with NewBatchRequest, which defensively copies the input; accessors also return copies so callers cannot mutate the stored items.

func MustNewBatchRequest

func MustNewBatchRequest[K any](items []BatchItem[K]) BatchRequest[K]

MustNewBatchRequest is like NewBatchRequest but panics on error. It is intended for tests and internal construction with known-valid input.

func NewBatchRequest

func NewBatchRequest[K any](items []BatchItem[K]) (BatchRequest[K], error)

NewBatchRequest validates items and returns a BatchRequest. It rejects an empty request, invalid items, and duplicate request IDs, and copies the input slice so later mutation of the caller's slice does not affect the request.

func (BatchRequest[K]) IDs

func (r BatchRequest[K]) IDs() []RequestID

IDs returns the request IDs in order.

func (BatchRequest[K]) Items

func (r BatchRequest[K]) Items() []BatchItem[K]

Items returns a copy of the items in their original order.

func (BatchRequest[K]) Len

func (r BatchRequest[K]) Len() int

Len returns the number of items.

func (BatchRequest[K]) Validate

func (r BatchRequest[K]) Validate() error

Validate reports whether the request is well-formed. A request built by NewBatchRequest is always valid; this re-checks a value that may have been constructed as a zero value.

type BatchResponse

type BatchResponse[V any] struct {
	// contains filtered or unexported fields
}

BatchResponse is an immutable-by-convention, ordered collection of outcomes. Construct it with NewBatchResponse, which defensively copies the input; accessors return copies. Order is preserved but the type does not force any particular mapping policy.

func KeyedOutcomes

func KeyedOutcomes[K comparable, V any](
	req BatchRequest[K],
	values map[K]V,
	onMissing func(id RequestID, key K) Outcome[V],
) (BatchResponse[V], error)

KeyedOutcomes maps a map of values keyed by K to outcomes, one per request item. When a key is absent, onMissing is consulted; if onMissing is nil, a not-found outcome is produced. Duplicate keys across items yield separate outcomes with their own request IDs.

func MustNewBatchResponse

func MustNewBatchResponse[V any](outcomes []Outcome[V]) BatchResponse[V]

MustNewBatchResponse is like NewBatchResponse but panics on error.

func NewBatchResponse

func NewBatchResponse[V any](outcomes []Outcome[V]) (BatchResponse[V], error)

NewBatchResponse validates outcomes and returns a BatchResponse, copying the input slice. It rejects invalid outcomes but permits an empty response so that callers can represent a global failure with no outcomes.

func OrderedOutcomes

func OrderedOutcomes[K, V any](req BatchRequest[K], values []V) (BatchResponse[V], error)

OrderedOutcomes maps a slice of values to outcomes by request order. It requires len(values) == req.Len() and treats every value as a success. Distinct request IDs are preserved even when item keys are equal.

func OrderedResultOutcomes

func OrderedResultOutcomes[K, V any](req BatchRequest[K], results []ItemResult[V]) (BatchResponse[V], error)

OrderedResultOutcomes maps ordered per-item results to outcomes by request order. It requires len(results) == req.Len().

func SparseOutcomes

func SparseOutcomes[K, V any](
	req BatchRequest[K],
	lookup func(key K) (V, bool),
	onMissing func(id RequestID, key K) Outcome[V],
) (BatchResponse[V], error)

SparseOutcomes maps outcomes using a callback lookup, which avoids requiring comparable keys. When lookup reports a key absent, onMissing is consulted; if onMissing is nil, a not-found outcome is produced.

func (BatchResponse[V]) Len

func (r BatchResponse[V]) Len() int

Len returns the number of outcomes.

func (BatchResponse[V]) Outcomes

func (r BatchResponse[V]) Outcomes() []Outcome[V]

Outcomes returns a copy of the outcomes in order.

func (BatchResponse[V]) Validate

func (r BatchResponse[V]) Validate() error

Validate reports whether all outcomes are well-formed and no request ID is duplicated.

func (BatchResponse[V]) ValidateAgainst

func (r BatchResponse[V]) ValidateAgainst(requestIDs []RequestID) error

ValidateAgainst checks the response against the exact set of request IDs it should answer. It reports missing IDs, unexpected IDs, duplicate IDs, and invalid outcomes. The requestIDs argument is treated as the authoritative set.

type FunctionDeclaration

type FunctionDeclaration[K, V any] struct {
	// contains filtered or unexported fields
}

FunctionDeclaration connects an operation spec to concrete scalar and batch function implementations. It is an immutable-by-convention value with no global side effects: constructing one registers nothing.

func DeclareFunction

func DeclareFunction[K, V any](
	spec operation.Spec,
	scalar ScalarFunc[K, V],
	batch BatchFunc[K, V],
) (FunctionDeclaration[K, V], error)

DeclareFunction validates the spec and implementations and returns a FunctionDeclaration. It returns an error if the spec is invalid or either implementation is nil.

func MustDeclareFunction

func MustDeclareFunction[K, V any](
	spec operation.Spec,
	scalar ScalarFunc[K, V],
	batch BatchFunc[K, V],
) FunctionDeclaration[K, V]

MustDeclareFunction is like DeclareFunction but panics on error. It is meant for package-level declarations, where a failure is a programmer error. The panic message includes the operation ID and is deterministic.

Example

package main

import (
	"context"
	"fmt"

	batchweaver "github.com/Voskan/BatchWeaver"
	"github.com/Voskan/BatchWeaver/operation"
)

type exampleUser struct {
	ID   int
	Name string
}

func exampleLoadUser(_ context.Context, id int) (exampleUser, error) {
	return exampleUser{ID: id, Name: "Ada"}, nil
}

func exampleLoadUsers(
	_ context.Context,
	req batchweaver.BatchRequest[int],
) (batchweaver.BatchResponse[exampleUser], error) {
	values := make([]exampleUser, req.Len())
	for i, item := range req.Items() {
		values[i] = exampleUser{ID: item.Key, Name: "Ada"}
	}
	return batchweaver.OrderedOutcomes(req, values)
}

func main() {
	getUser := batchweaver.MustDeclareFunction(
		operation.MustNewSpec(
			operation.MustParseID("users.get"),
			operation.ReadOnly(),
			operation.WithOrderedResults(),
			operation.WithRequestScope(),
		),
		exampleLoadUser,
		exampleLoadUsers,
	)

	fmt.Println(getUser.Spec().ID())
}

Output:
users.get

func (FunctionDeclaration[K, V]) Batch

func (d FunctionDeclaration[K, V]) Batch() BatchFunc[K, V]

Batch returns the batch implementation.

func (FunctionDeclaration[K, V]) Scalar

func (d FunctionDeclaration[K, V]) Scalar() ScalarFunc[K, V]

Scalar returns the scalar implementation.

func (FunctionDeclaration[K, V]) Spec

func (d FunctionDeclaration[K, V]) Spec() operation.Spec

Spec returns the operation spec.

func (FunctionDeclaration[K, V]) Validate

func (d FunctionDeclaration[K, V]) Validate() error

Validate reports whether the declaration is well-formed.

type ItemResult

type ItemResult[V any] struct {
	// Value is the successful value; meaningful only when Found is true.
	Value V
	// Err is a per-item error, if any.
	Err error
	// Found reports whether a value was produced.
	Found bool
}

ItemResult is a per-item provider result used when adapting ordered results that may individually succeed, fail, or be missing.

type MethodDeclaration

type MethodDeclaration[R, K, V any] struct {
	// contains filtered or unexported fields
}

MethodDeclaration connects an operation spec to scalar and batch method expressions whose first parameter is the receiver R. It is immutable by convention and performs no global registration.

func DeclareMethod

func DeclareMethod[R, K, V any](
	spec operation.Spec,
	scalar ScalarMethod[R, K, V],
	batch BatchMethod[R, K, V],
) (MethodDeclaration[R, K, V], error)

DeclareMethod validates the spec and method expressions and returns a MethodDeclaration.

func MustDeclareMethod

func MustDeclareMethod[R, K, V any](
	spec operation.Spec,
	scalar ScalarMethod[R, K, V],
	batch BatchMethod[R, K, V],
) MethodDeclaration[R, K, V]

MustDeclareMethod is like DeclareMethod but panics on error, for package-level declarations.

func (MethodDeclaration[R, K, V]) Batch

func (d MethodDeclaration[R, K, V]) Batch() BatchMethod[R, K, V]

Batch returns the batch method expression.

func (MethodDeclaration[R, K, V]) Scalar

func (d MethodDeclaration[R, K, V]) Scalar() ScalarMethod[R, K, V]

Scalar returns the scalar method expression.

func (MethodDeclaration[R, K, V]) Spec

func (d MethodDeclaration[R, K, V]) Spec() operation.Spec

Spec returns the operation spec.

func (MethodDeclaration[R, K, V]) Validate

func (d MethodDeclaration[R, K, V]) Validate() error

Validate reports whether the declaration is well-formed.

type Outcome

type Outcome[V any] struct {
	// RequestID identifies which request this outcome answers; non-zero.
	RequestID RequestID
	// Value is the successful result; meaningful only when Found is true.
	Value V
	// Err is the per-item error; non-nil only for a failure outcome.
	Err error
	// Found reports whether a value was produced.
	Found bool
}

Outcome is the result of a single logical request within a batch. Exactly one of three states is valid: success (Found, no error), not-found (no error, not found), or failure (error, not found). The ambiguous found-plus-error state is rejected by validation.

func Failure

func Failure[V any](id RequestID, err error) Outcome[V]

Failure returns a failure outcome for id carrying err. A nil err is treated as an invalid outcome by Validate.

func NotFound

func NotFound[V any](id RequestID) Outcome[V]

NotFound returns a not-found outcome for id.

func Success

func Success[V any](id RequestID, value V) Outcome[V]

Success returns a successful outcome for id carrying value.

func (Outcome[V]) IsFailure

func (o Outcome[V]) IsFailure() bool

IsFailure reports whether the outcome carries an error.

func (Outcome[V]) IsNotFound

func (o Outcome[V]) IsNotFound() bool

IsNotFound reports whether the outcome represents a missing value.

func (Outcome[V]) IsSuccess

func (o Outcome[V]) IsSuccess() bool

IsSuccess reports whether the outcome is a successful value.

func (Outcome[V]) Validate

func (o Outcome[V]) Validate() error

Validate reports whether the outcome is in a well-formed state.

type RequestID

type RequestID uint64

RequestID identifies a single logical request within one BatchRequest.

The zero value is invalid for a dispatched request. IDs are opaque to providers, which must return the same IDs they received; they are scoped to a single BatchRequest and need not be globally unique. No IDs are generated in this release.

func (RequestID) IsValid

func (id RequestID) IsValid() bool

IsValid reports whether the request ID is non-zero.

type ScalarFunc

type ScalarFunc[K, V any] func(context.Context, K) (V, error)

ScalarFunc is the signature of a scalar operation: one input, one result.

type ScalarMethod

type ScalarMethod[R, K, V any] func(R, context.Context, K) (V, error)

ScalarMethod is a scalar operation expressed as a method expression, so the receiver R is an explicit first parameter. R may be a pointer or interface type.