Interface / API Clarity

Review this interface/API for clarity and ease of use:
[Paste code]
Suggest improvements.

You are a senior JavaScript and TypeScript engineer. Write a function or small module to the spec below.

## What I need
[What the code should do]

## Environment
- Language and module system: [Language and module system]
- Runtime: [Runtime]
- Signature or example calls I expect: [Expected signature or example calls]
- Constraints (dependencies, target version, size, performance): [Constraints]
- Existing types or code this must fit with: [Existing types or related code]

## Step 1 - Contract
Write this before any implementation:
- The exported signature with full types. In plain JavaScript, use JSDoc types.
- Three or four example calls with their results, including one failure.
- The error contract: for each failure, whether the function throws (and what), rejects, or returns a value that signals failure. Choose one style and keep to it.
- Whether it is synchronous or asynchronous, and why.
If my expected signature conflicts with the task, say so and propose a correction instead of working around it silently.

## Step 2 - Implementation
Write code that satisfies the contract.
- Treat arguments as read-only: no mutation of input objects or arrays unless the spec asks for it.
- Use only APIs available in the stated runtime. No Node built-ins in browser code, no DOM or window in server code. If an API is recent or not available everywhere, name it and give the minimum version you believe it needs, marked as "check".
- No dependencies beyond those the constraints allow. Prefer the platform over a package for anything a few lines can do.
- Use const by default, strict equality, and explicit handling of null and undefined at the boundary.
- TypeScript: no any, no non-null assertions and no type casts to silence errors. Narrow with checks instead.
- Async code: await or return every promise, and do not leave rejections unhandled.
- Complete code only. No elided sections, no placeholder comments.

## Step 3 - Review your own work
Check each example call from Step 1 against the implementation and correct any mismatch before answering. Then list inputs that could still surprise a caller.

## Reply format
1. Contract
2. Code, in one fenced block per file with the filename above it
3. Usage: a short snippet showing a call and how a failure is handled
4. Notes: assumptions, items marked "check", and anything you would want tested first