Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

declaration-contracts

/declaration-contracts

Obsługuje kontrakty deklaracji typów dla pakietów i nietypowanych API JavaScript: tworzenie, naprawa, testowanie i publikacja plików .d.ts z eksportami runtime, globalami, callbackami, przeciążeniami i punktami wejścia.

Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Obsługuje kontrakty deklaracji typów dla pakietów i nietypowanych API JavaScript: tworzenie, naprawa, testowanie i publikacja plików .d.ts z eksportami runtime, globalami, callbackami, przeciążeniami i punktami wejścia.

Oryginalny opis (EN)

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.

Jak działa

  1. 1. Map the runtime surface
  2. 2. Encode observable behavior
  3. 3. Prove the consumer contract
  4. 4. Ship the declarations consumers resolve
Sekcje z nagłówków SKILL.md, w oryginale · 73 linii, 633 słów
Podgląd SKILL.md
---
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.

Wersje

W bazie nie ma innych skilli o nazwie declaration-contracts.

Migawka bazy z 13.11.2026 · wersja paczki 8fbe48ae5505 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90TypeScript
    Pisze, przegląda i naprawia kod TypeScript z bezpiecznymi typami: błędy typów, zawężanie, generyki, tsconfig i pliki deklaracji.
  • 100project-system
    Pomaga konfigurować projekty TypeScript: tsconfig.json, narzędzia budowania, bundlery, opcje kompilatora, systemy modułów, project references i pliki deklaracji.
  • 100typescript
    Pomaga w złożonych typach TypeScript: ograniczenia generyków, typy warunkowe i mapowane, łączenie deklaracji, optymalizacja tsconfig i refaktoryzacja JavaScript do TypeScript.
  • 90fec-typescript-project-standard
    Tworzy, konfiguruje i przegląda standardy projektów TypeScript: tsconfig, tryby ścisłości, rozwiązywanie modułów, aliasy ścieżek, project references, pliki deklaracji, eksporty pakietów, generyki i zawężanie typów.
  • 100typescript
    Egzekwuje nowoczesne praktyki TypeScript przy pisaniu i przeglądzie kodu oraz konfiguracji tsconfig.json.
  • 100typescript
    Konfiguruje i naprawia projekty TypeScript: dobiera ustawienia tsconfig.json, uruchamia sprawdzanie typów w CI, zastępuje any i niebezpieczne rzutowania oraz pomaga migrować z JavaScript.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.