Types, Documentation, and Package Design

Why it matters

A function’s real contract — what it expects, what it returns, what can go wrong — is invisible to a reader (and an editor) unless it’s written down somewhere machine-readable. JSDoc and TypeScript both make that contract visible; designing a package’s public surface deliberately, with real versioning discipline, is what makes it safe for other code to depend on.

JSDoc: types without a build step

A JSDoc comment gives editor tooling (autocomplete, inline parameter hints, type-mismatch warnings) accurate information, using plain JavaScript with no compilation step required:

/**
 * Calculate the total price for a cart, including tax.
 * @param {Array<{ price: number, quantity: number }>} items
 * @param {number} taxRate - A decimal, e.g. 0.08 for 8%.
 * @returns {number} The total price, tax included.
 */
function calculateTotal(items, taxRate) {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  return subtotal * (1 + taxRate);
}

An editor configured to check JSDoc (most modern ones are, by default, for .js files) will flag calculateTotal('not an array', 0.08) as a type mismatch — real, useful feedback with zero build step.

TypeScript as a neighboring path

TypeScript adds a dedicated type system and compiler on top of JavaScript — the same contracts JSDoc can express, checked more thoroughly, plus features JSDoc can’t express as cleanly (generics, more precise narrowing):

function calculateTotal(items: { price: number; quantity: number }[], taxRate: number): number {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  return subtotal * (1 + taxRate);
}

Type narrowing is TypeScript refining a broader type to a more specific one based on a runtime check already in the code:

function describe(value: string | number) {
  if (typeof value === 'string') {
    return value.toUpperCase(); // narrowed to string here — .toUpperCase() is valid
  }
  return value.toFixed(2); // narrowed to number here — .toFixed() is valid
}

Designing a package’s public surface

What a package exports is its contract with everyone who depends on it — changing it is a breaking change for them, whether or not that was the intent:

{
  "name": "my-lib",
  "version": "2.3.1",
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js"
  }
}

The exports field explicitly declares what’s public — anything not listed isn’t importable by consumers at all, which is what makes internal refactoring of unexported files safe without breaking anyone.

A changelog documenting what actually changed per version — ideally generated or at least reviewed alongside every release — is what lets a consumer decide whether upgrading is safe without reading the full diff themselves.

Check your understanding

Practice: warm-up

Write a JSDoc comment for this function describing its parameter and return types accurately.

function findUserById(users, id) {
  return users.find((user) => user.id === id);
}

/**
 * Find a user by id.
 * @param {Array<{ id: number, name: string }>} users
 * @param {number} id
 * @returns {{ id: number, name: string } | undefined}
 */
function findUserById(users, id) {
  return users.find((user) => user.id === id);
}

Practice: apply it

A package’s package.json currently has "version": "1.4.2". For each change, name the correct next version: (1) fixing a bug where a function returned the wrong sign for negative numbers, (2) adding a new optional parameter with a default that preserves old behavior, (3) removing a previously-exported function nobody uses internally anymore.

1. Bug fix (wrong sign)              -> 1.4.3 (patch)
2. New optional parameter, safe default -> 1.5.0 (minor)
3. Removing an exported function     -> 2.0.0 (major) — a consumer might still import it,
   regardless of what the maintainers believe usage looks like.

Summary

• A JSDoc comment gives editor tooling a function’s real contract — parameter and return types — with no build step required; TypeScript adds a dedicated, more thorough type system on top of the same idea, adoptable gradually rather than all at once.
• Type narrowing refines a broader type to a more specific one based on a runtime check already present in the code.
• A type is a compile-time/editor-time guarantee only — it enforces nothing once the code actually runs, so data crossing a real boundary still needs runtime validation.
• A package’s exports field is its actual public contract; anything not listed is safe to refactor internally without breaking consumers.
• Semantic versioning is a promise about observable behavior, not an internal-effort measurement — a small-feeling change can still be a breaking (major) change if it changes what existing consumers depend on.