Principle:Eventual Inc Daft API Boundary Protection
| Knowledge Sources | |
|---|---|
| Domains | API_Design, Type_Safety |
| Last Updated | 2026-02-08 14:00 GMT |
Overview
Design pattern that enforces type contracts at public API boundaries via runtime validation decorators, providing early error detection and clean error messages.
Description
API Boundary Protection wraps public-facing functions with decorators that introspect type annotations and validate arguments at call time. Unlike static type checkers (mypy, pyright) that run at development time, this pattern catches type errors at runtime when users call the API with incorrect types. The decorators also manage tracebacks to hide internal frames, producing user-friendly error messages that point to the call site rather than internal implementation details.
Usage
Apply this principle to all user-facing API functions in a library where incorrect argument types would otherwise produce confusing errors deep in the call stack. It is particularly valuable for DataFrame APIs where users frequently pass strings, expressions, or mixed types.
Theoretical Basis
Runtime type checking at API boundaries follows the contracts model:
- Precondition validation: Before executing function logic, validate that all arguments satisfy their declared types.
- Error localization: By catching type mismatches at the public boundary, errors are reported at the user's call site, not in internal helper functions.
- Traceback management: Internal frames are stripped from exception tracebacks to focus the user on their own code.