api.go

package restapi

// API is the entry point to the library. It bundles an [ErrorRegistry] and
// exposes helpers that write standardised responses to a [gin.Context].
//
// Instances are safe for concurrent use once constructed. The zero value is
// not usable; call [NewAPI] instead.
type API struct {
	registry *ErrorRegistry
}

// NewAPI returns a new [API] configured with opts. Nil options are ignored,
// so callers can chain options conditionally.
//
// The returned API always has a non-nil registry: if no [WithErrorRegistry]
// option is supplied (or it is passed nil), the package's default registry
// from [Default] is used.
func NewAPI(opts ...APIOption) *API {
	api := &API{}

	for _, opt := range opts {
		if opt != nil {
			opt(api)
		}
	}

	if api.registry == nil {
		api.registry = Default().registry
	}

	return api
}

// Default returns the package-level [API] used by the top-level wrapper
// functions such as [Success], [Error], and [Abort].
//
// Default is backed by an atomic pointer so it can be swapped at runtime with
// [SetDefault]; mutating the returned *API directly is not supported.
func Default() *API {
	return defaultAPI.Load()
}

// SetDefault replaces the package-level [API] returned by [Default]. It
// panics if api is nil, which would leave the top-level wrappers unusable.
func SetDefault(api *API) {
	if api == nil {
		panic("restapi: SetDefault called with nil *API")
	}
	defaultAPI.Store(api)
}

// Registry returns the underlying [ErrorRegistry]. Callers may register
// additional codes through the returned registry; they must not replace its
// internal state.
func (a *API) Registry() *ErrorRegistry {
	return a.registry
}

// IsRegistered reports whether errorCode is explicitly registered in the
// API's registry. It is a convenience shortcut for
// [API.Registry].[ErrorRegistry.IsRegistered].
func (a *API) IsRegistered(errorCode int) bool {
	return a.registry.IsRegistered(errorCode)
}

// Lookup resolves errorCode to an entry. The second return value reports
// whether a registered entry was found (true) or the fallback was used
// (false).
func (a *API) Lookup(errorCode int) (ErrorRegistryEntry, bool) {
	return a.registry.Lookup(errorCode)
}

// MustLookup is like [API.Lookup] but returns a wrapped [ErrUnknownErrorCode]
// instead of falling back to the registry fallback entry.
func (a *API) MustLookup(errorCode int) (ErrorRegistryEntry, error) {
	return a.registry.MustLookup(errorCode)
}

// Register adds entries to the API's registry. See [ErrorRegistry.Register]
// for semantics.
func (a *API) Register(entries ...ErrorRegistryEntry) error {
	return a.registry.Register(entries...)
}

// MustRegister is like [API.Register] but panics on error. It is convenient
// for static registration at program start-up.
func (a *API) MustRegister(entries ...ErrorRegistryEntry) {
	a.registry.MustRegister(entries...)
}