declaration-contracts
/declaration-contracts
Declaration contracts for packages and untyped JavaScript APIs. Use when authoring, repairing, testing, augmenting, or publishing .d.ts files; model runtime exports, globals, callbacks, overloads, and package type entry points. Not for purely type-level utilities or tsconfig selection.
- Author
- j0hanz ↗
- Repository
- j0hanz-marketplace ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Declaration contracts for packages and untyped JavaScript APIs. Use when authoring, repairing, testing, augmenting, or publishing .d.ts files; model runtime exports, globals, callbacks, overloads, and package type entry points. Not for purely type-level utilities or tsconfig selection.
Original author description
Declaration contracts for packages and untyped JavaScript APIs. Use when authoring, repairing, testing, augmenting, or publishing .d.ts files; model runtime exports, globals, callbacks, overloads, and package type entry points. Not for purely type-level utilities or tsconfig selection.
How it works
- 1. Map the runtime surface
- 2. Encode observable behavior
- 3. Prove the consumer contract
- 4. Ship the declarations consumers resolve
SKILL.md preview
---
name: declaration-contracts
description: Declaration contracts for packages and untyped JavaScript APIs. Use when authoring, repairing, testing, augmenting, or publishing .d.ts files; model runtime exports, globals, callbacks, overloads, and package type entry points. Not for purely type-level utilities or tsconfig selection.
metadata:
category: reference
---
# Declaration contracts
A `.d.ts` is a contract for JavaScript that already runs. Runtime behavior is the authority; types make its valid use precise and invalid use fail early.
## 1. Map the runtime surface
Inspect the library's actual exports, import forms, globals, callable values, constructors, callbacks, mutations, and supported subpaths. Classify its entry point before declaring it:
- `module.exports = value` maps to `export = value`; attach static members with a merged `declare namespace`.
- ESM named/default exports map to matching `export` declarations.
- A runtime global maps to `declare const`, `declare function`, `declare class`, or `declare namespace` in a global script declaration.
- A module supplied by the runtime but lacking a file maps to an ambient `declare module "name"`.
- An existing module extended by an application or plugin maps to a module augmentation.
An ambient `declare module` must live in a script declaration. A top-level import or export makes its file a module, where the same syntax augments an existing module instead. Keep imports needed only by an ambient module inside its declaration.
Done when every public runtime entry point, export shape, and supported import form has one matching declaration target.
## 2. Encode observable behavior
Write the smallest declarations that preserve how callers can use the API.
- Use primitive `string`, `number`, `boolean`, `symbol`, and `object` types.
- Model unexamined inputs as `unknown`; validate or narrow them where runtime code does.
- Mark a property optional when its key can be absent. Include `undefined` in its value type when the present key accepts `undefined`.
- Give a callback a required parameter when the library supplies it on every call; consumers may still omit unused callback parameters.
- Use a union for alternatives with one return type. Use overloads when return type or accepted behavior depends on the input, ordered most-specific to most-general because TypeScript selects the first match.
- Export types and values along the same paths the runtime exposes. Use `import type` and `export type` for declaration-only bindings.
Done when each declaration represents a runtime-observable capability, constraint, or result without inventing a value or hiding a valid call.
## 3. Prove the consumer contract
Create a small consumer fixture and type-check it with the project's normal TypeScript command, or `tsc --noEmit` when no narrower command exists. Exercise every public entry point through its published specifier, not an internal source path.
Make the fixture prove three things:
1. Representative valid runtime calls compile and infer the intended result.
2. Representative invalid calls carry `@ts-expect-error` and fail for the intended reason.
3. Runtime-sensitive choices are covered: overload selection, optional-key behavior, callbacks, CJS/ESM import form, globals, or augmentation as applicable.
Each `@ts-expect-error` must guard a line that genuinely errors; the compiler reports stale directives. For reusable type assertions, use the test harness from `advanced-types` rather than copying an equality helper.
Done when every public surface has a valid-use proof and each meaningful restriction has a red proof that fails if the declaration becomes too broad.
## 4. Ship the declarations consumers resolve
Generated declarations belong with their source package. Point `package.json` `types` at the root declaration file and give each exported subpath a matching `types` condition when the package uses `exports`.
```json
{
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./plugin": {
"types": "./dist/plugin.d.ts",
"import": "./dist/plugin.js"
}
}
}
```
Place declaration packages exposed through the public contract in `dependencies`, so consumers resolve them. Submit independently authored declarations for a third-party package to DefinitelyTyped for `@types` publication.
Type-check the packed or installed package from a clean consumer fixture under the module modes the package supports. Test ESM and CommonJS entry points separately when both are published.
Done when every documented package specifier resolves to the declaration alongside its runtime file from an installed artifact.
Versions
The database has no other skills named declaration-contracts.
Database snapshot: 13.11.2026 · package version 8fbe48ae5505 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90TypeScript
Writes, reviews, and debugs type-safe TypeScript: type errors, narrowing, generics, tsconfig strictness, and declaration files. Use when a build hits type errors ("not assignable", "possibly undefined", "excessively deep", "cannot find module"), when eliminating any or unchecked… - 100project-system
Use when configuring TypeScript projects, tsconfig.json, build tools, bundlers, and compilation pipelines. Covers compiler options, module systems, project references, and declaration files. USE FOR: tsconfig.json configuration, compiler options, build tool selection, bundler… - 100typescript
Expert TypeScript assistance covering advanced type gymnastics, generic constraints, conditional types, mapped types, declaration merging, and tsconfig optimization. Use when building type-safe applications, designing strict library typings, or refactoring JavaScript to TypeScript. - 90fec-typescript-project-standard
Use when creating, configuring, reviewing, or debugging TypeScript project standards across frontend apps, libraries, SDKs, CLIs, monorepo packages, tsconfig, strictness, module/moduleResolution, path aliases, project references, declaration files, package exports, public API… - 100typescript
Enforces modern TypeScript best practices for type-safe code, strict configuration, runtime validation, and clear type contracts. Use when writing or reviewing TypeScript/JavaScript code, configuring tsconfig.json, or when the user asks for TypeScript style guidance. - 100typescript
Sets up and repairs TypeScript projects: picks tsconfig.json settings for a Node.js service, an npm library or a bundled web app, runs type-checking in CI, and replaces `any` and unsafe casts with types the compiler can verify. Use when someone asks to "set up TypeScript", "fix…