kit-conventions

name	kit-conventions
description	The anatomy and conventions of a kit in @white-cross/reusable-function-library — file structure, JSDoc requirements, named exports, barrel wiring, naming, and tests. Use when creating or modifying any kit so it matches the existing 433+ kits and passes the zero-warning lint gate.

Kit conventions

A "kit" is a focused module of reusable functions/classes/types. New code must be indistinguishable in style from the existing 433+ kits. The closest existing kit is the spec — open it and match it.

File header (required on every .ts)

/**
 * @fileoverview <one-line purpose of this kit>
 * @module <domain>/<area>
 *
 * <2–4 line description: what it does, when to use it.>
 *
 * @example
 * ```typescript
 * import { doThing } from '@reuse/<domain>/<area>';
 * const result = doThing(input);
 * ```
 *
 * @version 1.0.0
 * @since <YYYY-MM-DD>
 */

Every export (functions, classes, types, interfaces)

• Named export for every function/type/interface/schema — this is the tree-shakable public API consumers import. In addition, each kit ends with a single export default aggregate object that bundles the kit (e.g. export default RateLimitingKit or export default { ... }). Both are required; copy the closest existing kit's shape.
• Full JSDoc: summary line, @param (name + type + meaning), @returns, @throws if it can throw, and at least one runnable @example. eslint-plugin-jsdoc runs at --max-warnings 0, so missing tags fail lint.
• Keep functions pure and dependency-light; reuse existing core kits (errors, validation, types) instead of re-implementing primitives.

Naming

Thing	Convention	Example
File	kebab-case.ts	rate-limiter.ts
Function	camelCase, verb-first	createRateLimiter
Type / Interface / Class	PascalCase	RateLimiterOptions
Module path	@reuse/<domain>/<area>	@reuse/core/api

Barrel wiring (this is what makes it reusable)

Every directory has an index.ts that re-exports its children. When you add a kit, re-export it up the chain until it reaches the domain root:

core/api/rate-limiter.ts   ->  export { createRateLimiter } ...
core/api/index.ts          ->  export * from './rate-limiter';
core/index.ts              ->  export * from './api';

If import { createRateLimiter } from '@reuse/core' doesn't resolve, the kit isn't done.

Tests

Add <name>.spec.ts next to the source, starting from tests/templates/utility.spec.template (or service/controller template). Cover the happy path, branches, boundaries, and each error path. Run npm test -- <path>.

Don't

• Don't edit generated *.js / *.d.ts / *.map — change the source .ts and let the build regenerate them.
• Don't skip JSDoc, ship any, or leave a kit unexported from its barrel.
• Don't omit the named exports and ship only the default object — consumers import named symbols.
• Don't re-implement something kit-explorer / npm run search can already find.