consuming-results-at-api-boundaries

name	consuming-results-at-api-boundaries
description	Use when exporting a function from a package that uses neverthrow internally, when tempted to export a safeX / xResult variant returning Result/ResultAsync, when asked to "provide" a fromThrowable-wrapped API to library users, or when deciding where a chain's final .match belongs.

Consuming Results at API Boundaries

Overview

A package's public API boundary IS a consumption edge. Result / ResultAsync never appear in exported signatures — the outermost exported function calls .match itself and presents a conventional contract.

This closes the gap in [[chaining-neverthrow-results]]: "one .match at the consumption edge" does NOT mean "leave the .match to the caller of your package." Anything that crosses exports in package.json leaves your code for the outside world — that is, by definition, the edge. neverthrow is an internal composition tool, not a public contract.

The rule

Surface	Error channel
Internal module ↔ internal module	Pass Result / ResultAsync, keep chaining ([[chaining-neverthrow-results]])
Exported function (sync)	.match inside; ok → return value, err → throw a named error class
Exported long-lived object	.match inside; err → emit("error", error) / callback
Exported error types	Export the error classes ([[modeling-errors-as-classes]]) — never Result values, never Result in a public type

The recipe (real example from this repo — packages/core)

// ✅ Wrap once at module scope (arguments are forwarded — no IIFE-style
// `fromThrowable(...)()` immediate call), match once at the exported edge.
const safeDispatchSend = Result.fromThrowable(
  dispatchSend,                                             // internal throwing dispatch
  (cause) => new TextureSendError(cause instanceof Error ? cause.message : `${cause}`, { cause }),
);

export const sendTextureFromPaintEvent = (
  sender: InstanceType<typeof TextureSender>,
  textureInfo: TextureInfo | undefined,
): void => {
  if (!textureInfo) return;
  safeDispatchSend(sender, textureInfo).match(
    () => undefined,
    (error) => { throw error; },                            // conventional contract: void + typed throw
  );
};

export { TextureSendError };                                // classes yes, Results no

// ❌ What both baseline attempts produced — a Result in the public contract
export const safeEncode = (encoder: Encoder, buf: Buffer): Result<Buffer, EncodeError> => ...
export const safeFlush: () => Result<void, FlushError> = Result.fromThrowable(...);

Consumers get instanceof TextureSendError, the original message, and the thrown value on Error.cause — full fidelity, zero neverthrow coupling.

Common rationalizations

Excuse	Reality
"A library is never the consumption edge — only the caller knows their edge"	The package boundary is YOUR edge. The caller has their own edge for their own Results; yours must not become their dependency.
"Pre-matching collapses the typed error channel"	No — the channel survives as an exported error class discriminated with instanceof. Types collapse; fidelity doesn't.
"Declare neverthrow as a peerDependency and make Result part of the contract"	That forces every consumer onto one specific neverthrow major forever. Version skew breaks instanceof Result across duplicated installs.
"The user asked for the fromThrowable-wrapped version"	They asked for the throw to be handled via fromThrowable — do that internally. 「提供」= provide the behavior, not the Result object.
"An additive safeX export is non-breaking, so it's fine"	Additive or not, it leaks the internal composition style into the public contract.

Red flags — STOP

• An exported name like safeX, xResult, tryX whose return type mentions Result / ResultAsync.
• neverthrow appearing in peerDependencies, or in any exported .d.ts type.
• A JSDoc example telling consumers where to put their .match on your return value.
• Reasoning that contains "the library cannot know the caller's edge" — that sentence means you are about to leak a Result.

When NOT to apply

• Inside the package: keep passing Results between internal modules; do not .match mid-pipeline.
• App code (not a published package): the edge is the route handler / CLI main / event emit, exactly as [[chaining-neverthrow-results]] says.