Skip to content
Esc

@noctcore/eslint-plugin-contracts

v1.1.017 rules6 recommended2 strict only9 opt-innamespace noctcore-contracts

A bad fit if you do not use zod, or if your error handling is intentionally untyped.

IO boundaries (checked fetch responses, parsed boundary data), error taxonomy, schema and wire naming, env access, money precision and translation keys.

The places a system talks to the outside world are where types stop being true: a fetch whose body is parsed without checking .ok, a JSON.parse(...) as User, an error re-thrown without its cause, process.env.FOO read in forty places, money typed as a float. These rules hold the contract layer to conventions that make those boundaries explicit and checkable.

It will yell at you about naming and boundary discipline: zod schemas must be PascalCaseSchema with a paired inferred type, wire messages need a literal type discriminant, process.env goes through one config module, thrown errors come from an approved taxonomy. Several conventions are opinionated, and the naming rules assume zod. It is a bad fit if you do not use zod, or if your error handling is intentionally untyped. Nine rules ship off: five are inert until you give them a sink list, schema file, translation catalogs, route groups or an auth map (route-handler-order enforces one middleware order in route chains, for example docs, auth and validation before the handler, and describe-auth-matches-middleware checks that the auth kind a route docs call declares matches the middleware in its chain), restrict-throw-to-taxonomy reports every exception until allow names your error classes, require-schema-parse-at-boundary is a conservative syntactic slice of a concern a type-aware setup does better, route-params-validated (reports a route with :name segments and no param validator in its chain) matches routers and param validators by name, and zod-field-describe is a documentation convention you enable for the schema modules that feed a generator.

Install
npm install --save-dev @noctcore/eslint-plugin-contracts @typescript-eslint/parser
# or: bun add -D / pnpm add -D @noctcore/eslint-plugin-contracts @typescript-eslint/parser

The recommended preset enables 6 of 17 rules. The strict preset adds 2 house rules (naming, folder shape, size caps) on top. The rules board below builds the flat config: start from a preset, switch single rules between error and off, and copy the result.

Each rule links to its page, with the options it takes and Incorrect and Correct examples. A good first read is fetch-must-check-ok.

6 of 17 at error

--fixsuggestionsneeds optionstype infoEach switch sets a rule to error or off.

describe-auth-matches-middleware
Require the auth kind a route docs call declares to match the middleware in the same route chain, using a configured map from kind to middleware names.
Needs options
opt-in
env-var-schema-parity
Require every process.env.FOO / import.meta.env.FOO key to be declared in a schema file (.env.example or a zod-env module), so config access and config declaration cannot drift apart.
Needs options
opt-in
fetch-must-check-ok
Require a fetch response to be checked with .ok or a status comparison before .json() parses its body.
recommended
money-must-be-decimal
Disallow monetary values typed as the JS primitive number. Money-named fields explicitly typed : number lose precision to float rounding; use a Decimal money type instead.
recommended
no-direct-process-env
Disallow direct process.env access. Force every consumer through a typed, validated config accessor so a missing variable fails at boot, not at use.
recommended
no-error-stringify
Disallow stringifying an error with bare ${error} interpolation, error.toString(), or error + "". These give "Error: <message>" or "[object Object]". Use error instanceof Error ? error.message : String(error) instead.
Editor suggestions
recommended
require-error-cause
Require re-thrown errors inside a catch to forward the caught error as { cause }. A throw new SomeError(...) that omits the cause severs the chain to the original failure.
Fixable with --fixEditor suggestions
recommended
require-registered-keys
Require the key/name argument of configured sink APIs (storage, event channels, cache keys) to be an imported constant from a registry module, not a raw string literal.
Needs options
opt-in
require-schema-parse-at-boundary
Disallow asserting external boundary data with as T instead of parsing it at runtime. Flags casts of JSON.parse, res.json(), web storage, URL search params, message-event data and LLM tool input, directly or through a const; use a zod/valibot parse.
opt-in
restrict-throw-to-taxonomy
Restrict throw to an approved error taxonomy. Flags throwing a non-allowlisted error class and throwing a non-Error value (string, object, number, ...).
Needs options
opt-in
route-handler-order
Require the middleware arguments of a route method call to follow a configured group order (for example docs, auth, validation), with the handler last.
Needs options
opt-in
route-params-validated
Require a route whose path declares :name parameters to carry a param validator in its handler chain.
opt-in
schema-enum-field-consistency
Disallow a zod field that is an enum in one object schema of a module from being z.string() in another, which widens the wire type every consumer then narrows by hand.
recommended
translation-key-exists
Require every static i18next / react-i18next translation key (t(...), i18n.t(...), <Trans i18nKey>) to exist in the catalog of the namespace in scope.
Needs optionsType information optional
opt-in
wire-message-naming
A message-schema const ending in a role suffix (default Event/Command/Query) whose zod object declares type: z.literal(...) must set that literal to kebab-case(const name minus its role suffix).
Fixable with --fix
strict only
zod-field-describe
Require every property of a zod object schema to carry a non-empty .describe() or .meta({ description }), so generated JSON Schema, tool definitions and API docs have text for each field.
opt-in
zod-schema-naming
Every exported zod schema is a PascalCase const suffixed Schema, paired with a same-named inferred type (export type Foo = z.infer<typeof FooSchema>).
strict only