Open code, practice, and notes →
Download source with English comments · for reading
TypeScript · 25 Declaration Files and External Boundaries
Series contents · Technology map
Stage: Module Contracts and Plugins · Editable example · Storage ID: typescript-step-25
Goals and learning outcomes
- Record the diagnostic for a call with an invalid argument.
- Keep logs comparing the declared and actual return types.
Prerequisites
Work and experiment records from Unit 24, “Modules and type-only import”
Key concepts and explanations
Declaration Contracts
d.ts describes an implementation's type contract. It does not create actual JavaScript behavior.
Contract Mismatches
Incorrect declarations can still let consumer checks pass. Check implementation and declarations with the same call cases.
Practice setup
First check the execution scope guidance on the example screen. The following environment is for extending the assignment in a separate project. Implement it yourself in a separate local project and check it with browser developer tools and tsc --noEmit. Record the installed tsc version in a separate TypeScript project. Enable strict in tsconfig.json and check with tsc --noEmit, then open the runtime exercise using compiled output or a local development server. Do not assume the browser executes TS type annotations directly.
The linked example is a starting point. It does not implement every task below. Complete work beyond its supported scope in a separate project.
Practice tasks
- In legacy.d.ts, prepare conditions for string-key and number-key calls.
- Declare a small legacy.js storage function and call it from a TS consumer with valid and invalid arguments.
- Run with string-key and number-key calls. Results to check: Record the diagnostic for a call with an invalid argument. Keep logs comparing the declared and actual return types. Record expected and actual results separately.
Variables to observe
| Variable | Baseline | Change | Expected change / hypothesis |
|---|---|---|---|
| Declared Return | actual string | incorrect number declaration | Pre-run hypothesis: successful compilation and runtime behavior may disagree. Keep other conditions fixed and record the actual result separately after running. |
Predictions in this table are not measured results. Change one condition at a time and record why the actual result differs.
Completion criteria
- Record the diagnostic for a call with an invalid argument.
- Keep logs comparing the declared and actual return types.
Self-check
- Does shipping only d.ts also create the implementation?
- How do you trace responsibility for an inaccurate declaration?
Official references
Linked example and execution scope
Example source · Runtime environments and limits
The preview is a JavaScript runtime boundary experiment. It does not run TypeScript diagnostics. Check lesson.ts locally with tsc --strict --noEmit --lib ES2023,DOM.
Source code and records are not overwritten automatically. Resetting an existing example also preserves your notes.
Next learning
Previous: Modules and type-only import · Next: Cases That Verify Compilation Failures