Skip to content
Sarj Code Standards

TypeScript rules

170 rules

Rule Category Introduced
TS directive-disable-enable-pair Require an `eslint-enable` directive for every block `eslint-disable` or `oxlint-disable` directive. maintainability
TS directive-no-aggregating-enable Disallow one `eslint-enable` or `oxlint-enable` directive closing several disable directives. maintainability
TS directive-no-duplicate-disable Disallow `eslint-disable` and `oxlint-disable` directives for rules that are already disabled there. maintainability
TS directive-no-restricted-disable Disallow `eslint-disable` and `oxlint-disable` directives that turn off a restricted rule or every rule. maintainability
TS directive-no-unused-enable Disallow `eslint-enable` and `oxlint-enable` directives for rules that are not disabled. maintainability
TS directive-no-use Disallow directive comments, `eslint-*` or `oxlint-*`, except the allowed kinds. maintainability
TS directive-require-description Require a `--` description on every directive comment, `eslint-*` or `oxlint-*`. maintainability
TS duplicate-test-body Disallow substantial sibling tests with the same body shape; express their differing inputs as a parameterized case table. testing
TS enforce-file-structure Require imports before body statements and require `use server` to be the first statement. correctness
TS excessive-commentary Flag long standalone implementation commentary that should be expressed by code. maintainability
TS iac-source-coupled-test Disallow raw IaC source text as a test oracle; inspect a rendered plan, provider state, or runtime behavior. testing
TS interface-contract-members-private Require methods outside an implemented interface contract to use ECMAScript private names. architecture
TS named-child-schema-type Reference a named Zod record child's complete schema type instead of repeating its explicit annotation. maintainability
TS no-bare-return-from-test-catch Disallow a bare return from a test catch block when it skips a later assertion. testing
TS no-bespoke-api-case-conversion Review direct snake_case/camelCase mirror mappings on explicitly API-typed adapter values. architecture
TS no-blocked-input-paste Allow clipboard input when a text control has no replacement paste handling. correctness
TS no-boolean-selector-parameter Prefer intention-revealing operations over a boolean parameter selecting between actions. maintainability
TS no-broad-return-type Report explicit broad return annotations that erase a known return value. maintainability
TS no-client-side-data-fetching Disallow direct data fetching inside `useEffect` or `useLayoutEffect`. performance
TS no-comment-cruft Flag commented-out code, section-banner comments, and leading file-header comment preambles. maintainability
TS no-conditional-empty-object-spread Build conditional properties explicitly instead of spreading an empty-object branch. style
TS no-contradictory-overload-return Preserve the input/result relationship promised by literal overloads. correctness
TS no-contradictory-type-predicate Keep explicit type predicates consistent with their primitive, array or record membership check. correctness
TS no-cors-wildcard-with-credentials Review wildcard CORS origins combined with an explicit credentials opt-in. correctness
TS no-credential-in-browser-storage Do not write credential-named values to browser storage or script-readable cookies. security
TS no-dangerously-allow-svg Require an explicit hardening policy for Next Image SVG delivery security
TS no-declaration-comment-wall Flag an enum body or class body whose member comments mostly re-spell the members' own names. maintainability
TS no-detached-global-fetch Keep the ambient global fetch receiver-safe when storing or explicitly rebinding it. correctness
TS no-discarded-validation-result Consume Zod validation outcomes and transformed outputs instead of discarding them. correctness
TS no-duplicate-lifecycle-refresh-listeners Do not register one Next.js route-refresh callback for both focus and visibilitychange. performance
TS no-duplicate-test-case Report repeated literal rows in framework each tables and Vitest for tables. testing
TS no-dynamic-sql Disallow runtime values and fragments interpolated into SQL passed to statement-execution methods. security
TS no-enum Disallow TypeScript `enum`; use string-literal unions or `as const` objects instead. maintainability
TS no-exception-text-in-5xx-response Keep caught exception messages and stacks out of returned 5xx JSON responses and Server Action results. security
TS no-excess-jsx-props Report statically known fields spread outside a resolved component props contract. maintainability
TS no-excessive-cognitive-complexity Report an error for function bodies with cognitive complexity above 20. maintainability
TS no-explicit-type-predicate Use compiler-checked narrowing instead of handwritten type predicates. maintainability
TS no-fat-try-blocks Review try blocks exceeding the configured count of syntactically selected operations. correctness
TS no-first-party-module-mock Prefer injected collaborators over mocking maintained first-party modules in tests. testing
TS no-frontend-comments Express frontend behavior through code instead of prose comments. maintainability
TS no-generic-json-parser Parse known JSON fields with an object schema instead of an open JSON or record parser. correctness
TS no-generic-single-export-module Disallow generic module stems when one runtime export already names the responsibility. maintainability
TS no-growing-array-spread-in-loop Review repeated prefix copies of a growing fresh local array inside a loop. performance
TS no-hand-rolled-sleep Disallow uncancellable promisified timers and timeout arms. correctness
TS no-hand-rolled-spinner Disallow intrinsic elements styled as Tailwind border-ring spinners outside the design-system implementation. maintainability
TS no-impossible-zod-literal-bounds Disallow same-chain literal Zod bounds whose accepted set is mathematically empty. correctness
TS no-in-operator-on-built-in-collections Do not use the `in` operator to test entries in built-in Map and Set collections. correctness
TS no-insecure-random-id Disallow using `Math.random()` to generate identifiers, tokens, or secrets; use `crypto.randomUUID()` or `crypto.getRandomValues(...)` instead. security
TS no-invalid-typed-mutation Keep native object mutation APIs from writing incompatible values into declared property types. correctness
TS no-invalid-web-resource-hints Keep native resource hints consistent with browser loading and preload request modes. performance
TS no-invalid-zod-custom-parse Do not parse an incompatible primitive literal through an unvalidated Zod custom schema. correctness
TS no-json-stringify-error Avoid generic JSON serialization that can omit native Error details. correctness
TS no-json-stringify-object-equality Do not use JSON serialization as structural object equality. correctness
TS no-known-value-widening Preserve a known value's contract instead of widening a local binding to unknown, object, or an unknown-valued dictionary. maintainability
TS no-log-only-catch Disallow `catch` clauses that only log (or silently do nothing) and then swallow the error; rethrow or handle it instead. correctness
TS no-logical-or-fallback Use nullish defaults or explicit falsy-value checks instead of logical OR fallbacks. correctness
TS no-long-comment Flag unusually large unstructured JSDoc blocks in implementation code. maintainability
TS no-message-origin-string-matching Compare incoming browser message origins against exact trusted origins. security
TS no-mutating-container-transform Return array replacements without mutating borrowed array inputs. correctness
TS no-mutating-input-with-result Return replacement object values instead of writing input fields in result-returning functions. correctness
TS no-negative-only-http-status-assertion Assert the intended HTTP status instead of only excluding a server error. testing
TS no-numeric-search-param-coercion Parse numeric URL search parameters with a schema instead of parseInt or Number. correctness
TS no-offset-pagination Prefer keyset pagination for embedded SQL queries using OFFSET. performance
TS no-oxlint-directive Write every suppression directive with the `eslint-*` spelling. maintainability
TS no-partial-type-predicate Do not give a partial primitive filter an explicit type predicate that excludes valid values in the false branch. correctness
TS no-password-get-form Keep named password controls out of native GET form submissions. security
TS no-positional-tuple-return Disallow returning a multi-field tuple from a named function; return a named object so call sites cannot mismatch slots. maintainability
TS no-production-browser-source-maps Next.js production browser source maps expose application source security
TS no-raw-env Disallow direct `process.env` and `import.meta.env` reads outside validated boundaries. correctness
TS no-raw-fetch-outside-clients Disallow calling the global `fetch` outside the client layer; route outbound HTTP through a client module that owns retry, timeout and status handling. architecture
TS no-readonly-prop-state Review props copied into state without a usable updater. correctness
TS no-reduce-accumulator-copy Review copies of the accumulated collection inside a built-in reduce callback. performance
TS no-redundant-consumer-union Keep the covering object contract in a private scalar consumer union. maintainability
TS no-redundant-local-alias Pass the original local into an object field instead of creating a single-use rename. maintainability
TS no-redundant-optional-array-default Remove `.optional()` immediately inside a Zod array default. maintainability
TS no-repeated-string-literal Disallow a long structured string literal repeated across functions; the copies drift when one is edited. Extract a module-level constant. maintainability
TS no-restated-comment Flag short standalone comments that repeat the adjacent statement's identifiers. maintainability
TS no-restated-jsdoc Flag JSDoc prose that appears to repeat declaration names without adding behavioral information. maintainability
TS no-restricted-library-load Apply configured library restrictions to literal runtime loads and CommonJS resolution references. architecture
TS no-return-disposed-resource Do not return a resource whose using declaration disposes it before the caller receives it. correctness
TS no-router-refresh-polling Do not poll by calling a Next.js router's refresh method from a timer. performance
TS no-runtime-typeof Prefer Zod boundary schemas or discriminated unions over runtime typeof checks. maintainability
TS no-secret-in-log Disallow passing a secret-named value or a raw request/response blob to a logging call; both leak to log sinks. Redact or omit. security
TS no-select-star Prefer explicit column projections over SELECT * in embedded SQL. correctness
TS no-sentinel-return-on-catch Disallow swallowing a caught error by returning an empty sentinel unless the error is handled or the sentinel is part of the function contract. correctness
TS no-server-env-in-client-component server-only environment settings imported or re-exported by a client module correctness
TS no-server-file-uploads Keep native File handling outside explicit server boundaries. architecture
TS no-silent-promise-catch Disallow `.catch()` and second-argument `.then()` handlers that silently swallow a rejection; log, rethrow, or handle the error. correctness
TS no-sleep-in-test-body Avoid fixed timed sleeps directly in test bodies; synchronize on observable behavior or use controlled timers. testing
TS no-storage-in-stateless-modules Disallow SQL or key/value access inside configured stateless modules; derive state from a system of record instead. architecture
TS no-string-concat-in-loop Prefer collecting string fragments over repeatedly accumulating a growing string inside a loop. performance
TS no-tautological-expect Disallow supported assertions fixed by literal setup or immutable self identity. testing
TS no-test-comments Express test behavior through names, fixtures and assertions instead of prose comments. testing
TS no-trailing-value-narration Flag a trailing comment that repeats the line's numeric value only to name its unit. maintainability
TS no-type-member-comment-wall Flag an object type whose member comments mostly re-spell the members' own names and types. maintainability
TS no-typed-doc-sections Reject typed-signature repetition while preserving behavior that types cannot express. maintainability
TS no-union-in-comment Flag a comment that lists a `string` field's allowed values instead of the type listing them. maintainability
TS no-unlocalized-jsx-attributes Require translation for literal user-visible JSX attributes in opted-in localized interfaces. correctness
TS no-unlocalized-jsx-text Require translation for literal JSX text in opted-in localized interfaces. correctness
TS no-unlocalized-toast Require translation for literal toast messages in opted-in localized interfaces. correctness
TS no-unnecessary-use-client Flag `'use client'` files with no hooks or event handlers — they could be RSC. performance
TS no-unsafe-mock-casting Disallow casting to mock types like `jest.Mock` or `vi.Mock`. Use `vi.mocked()` or `jest.mocked()` instead. testing
TS no-unsafe-test-double-cast Disallow mock-backed test doubles that bypass collaborator contracts through double assertions. testing
TS no-vague-suppression-description Require suppression descriptions to name the concrete mismatch or invariant instead of a generic non-reason. maintainability
TS no-zod-native-enum Disallow `z.nativeEnum()` (and `z.enum()` over a TypeScript enum); use `z.enum(["a", "b"])` with a string-literal union instead. maintainability
TS no-zod-parse-typed-object Reuse known object contracts instead of parsing them again with Zod. architecture
TS prefer-await-in-async-return Prefer explicit `await` for proven Promise `.then` calls; the default scope checks direct async returns. maintainability
TS prefer-coded-error-result Return a stable error code and typed context instead of only a rendered failure message. correctness
TS prefer-configured-cloud-scope Prefer validated deployment configuration for account scope in outgoing cloud management requests. correctness
TS prefer-constant-time-secret-compare Prefer a supported constant-time comparison primitive for secret-like values. security
TS prefer-dependency-interface Annotate retained collaborators with their existing interface when the consumer uses only that contract. architecture
TS prefer-discriminated-union Preserve producer-proven tag/payload and Boolean state relationships in return types. correctness
TS prefer-ecmascript-private-members Prefer ECMAScript `#private` class members over TypeScript-only `private` members. maintainability
TS prefer-immutable-module-constant Require module-level constant collections to expose readonly state. correctness
TS prefer-input-group-search Require search icons and shared Input controls in the same visual wrapper to use InputGroup. style
TS prefer-logical-tailwind-utilities Prefer logical Tailwind utilities in explicitly opted-in bidirectional interfaces. correctness
TS prefer-millisecond-control-duration-schema Require application-owned Zod control-duration fields to use millisecond granularity. correctness
TS prefer-minimal-parameter-contract Prefer the proven read-only subset for a private consumer parameter. architecture
TS prefer-module-level-constant Hoist literal-only constant collections and regexes out of function bodies to module scope so they are allocated once. performance
TS prefer-module-level-refined-schema Declare closed Zod scalar, format, and wrapper schemas at module scope. performance
TS prefer-module-level-schema Declare a Zod schema at module scope when it closes over nothing in the enclosing function performance
TS prefer-multi-value-zod-literal Use the Zod 4 multi-value literal API instead of a union of literal schemas. maintainability
TS prefer-named-callback-domain Name literal-union domains used by callbacks in exported contracts. maintainability
TS prefer-named-complex-return-type Prefer a named contract for structurally complex function return types. maintainability
TS prefer-native-fetch-in-server-actions Server action modules should call native fetch instead of importing ky. correctness
TS prefer-native-random-uuid Prefer `globalThis.crypto.randomUUID()` over resolved zero-argument UUID v4 bindings from the `uuid` package. maintainability
TS prefer-node-crypto-hash Prefer the modern one-shot node:crypto hash API when streaming state is unnecessary. performance
TS prefer-node-fs-promises Prefer promise-based Node.js filesystem APIs over synchronous calls in production modules. performance
TS prefer-nominal-id-types Distinguish identifier roles sharing primitive types at callable boundaries. correctness
TS prefer-non-nullable-collection Suggest reviewing nullish arrays that use local empty-array defaults or a shared null-or-empty guard. maintainability
TS prefer-nullish-filter-predicate Prefer an explicit nullish predicate when `filter(Boolean)` removes only nullish values but does not narrow the result type. correctness
TS prefer-schema-for-api-payload Require Zod (or similar) schema validation on `response.json()` / `JSON.parse()` results before property access. correctness
TS prefer-semantic-colors Enforce semantic color tokens over raw Tailwind palette classes, arbitrary color values, and inline color literals. style
TS prefer-server-actions Prefer Next.js Server Actions over same-origin API mutations. architecture
TS prefer-server-data-preparation Prepare data-only input collections before an interactive client view when possible. architecture
TS prefer-shadcn-primitives Require visible raw JSX controls to use the corresponding shared shadcn primitive. style
TS prefer-shared-zod-enum Give repeated literal Zod enum domains one reusable module-level schema. maintainability
TS prefer-switch-for-repeated-equality Prefer switch over long if/else-if chains that compare one value for strict equality. maintainability
TS prefer-test-fixture-reuse Reuse a requested test fixture instead of constructing another instance of its class. testing
TS prefer-typed-reflection Prefer typed access when Reflect.get or Reflect.apply discards a known contract. maintainability
TS prefer-whole-object-assertion Collapse consecutive assertions on one object into a whole-object assertion so related mismatches are reported together. testing
TS prefer-zod-enum-validator Express closed string validators with a reusable Zod enum schema. maintainability
TS prefer-zod-infer Derive a type from its Zod schema with `z.infer` instead of hand-writing a twin declaration beside it. correctness
TS prefer-zod-parse-output-type Consider deriving validated return contracts from the Zod schema when the schema owns the contract. correctness
TS production-derived-test-cases Keep an independent membership oracle when production collections supply test cases. testing
TS repeated-static-call-cases Review three or more consecutive static-input call assertions as potential named cases. testing
TS require-assert-never Require a never witness in empty switch defaults so discriminated unions remain exhaustive at compile time. correctness
TS require-button-accessible-name Require an accessible name on statically unnamed native or configured JSX buttons. correctness
TS require-camelcase-properties Require unquoted lower snake_case TypeScript properties and dot access to use camelCase. style
TS require-constrained-schema-integer Declare integer and lower-bound validation for numeric limit and version schema fields. correctness
TS require-explicit-contract-implementation Require nominal inheritance when an injected abstract class is rejected by an instanceof guard. architecture
TS require-explicit-service-contract Require explicit contracts for classes that invoke retained collaborators. architecture
TS require-fetch-timeout Require an explicit abort signal on locally analyzable global fetch calls. correctness
TS require-ime-safe-enter-handler Preserve IME composition before Enter submits or blurs a native text control. correctness
TS require-interface-for-exported-class Require exported concrete classes with public behavior to declare a contract. architecture
TS require-jwt-lifetime Require an expiration claim or a maximum token age when returning a verified JWT. security
TS require-pascal-case-zod-schema-name Require confirmed module-level Zod schema contracts to use PascalCase with a `Schema` suffix. style
TS require-port-for-service Advise when an exported service with injected collaborators has public methods not covered by its declared ports. architecture
TS require-sql-access-class Keep SQL reads and writes inside a class that receives its database dependency. architecture
TS require-static-next-matcher Require Next.js middleware and proxy matcher configuration to contain only build-time literals. correctness
TS require-svg-accessible-name Require a name or explicit decorative semantics on inline SVG elements. correctness
TS require-use-form-default-values Require explicit form-level initialization or a field default for directly bound Controller fields. correctness
TS require-use-server-in-actions-file route action module missing the use server directive correctness
TS require-zod-form-validation Require Zod validation (`Schema.parse(...)` / `Schema.safeParse(...)`) when reading values out of a `FormData` object. security
TS sole-export-matches-filename Make a module filename reflect its sole named public runtime export. maintainability
TS source-coupled-test Disallow raw repository source text as a test oracle; parse or execute the artifact instead. testing
TS stepdown Place a private helper below its sole direct same-scope caller. maintainability
TS store-insert-requires-on-conflict Review conflict handling for embedded inserts in replay-named callables. correctness
TS test-loops-over-literal-cases Disallow assertions over an inline literal case loop in a test; parameterization reports and names every case independently. testing
TS test-phase-label-comment Tests must not use bare Arrange, Act, Assert, Given, When, or Then phase comments. testing