Cyclomatic complexity in plain JavaScript

Cyclomatic complexity is a source-level measure based on the number of independent paths through a function. A straight-line function begins with one path. Decisions such as if branches, loop conditions, case clauses, conditional expressions, and some logical operations increase the number according to the tool’s chosen variant.

The JavaScript Complexity Calculator provides a narrow, repeatable reading for pasted source. The score is most useful as a prompt: “Why does this function have so many paths, and are they all tested?” It is not a universal definition of quality, maintainability, or performance.

Read the decisions behind the number

Consider a checkout function that handles guest and signed-in users, physical and digital products, several discount types, tax regions, stock rules, and payment retries. A high score may reveal that many policies have been combined in one place. The useful next step is not to chase a smaller number mechanically; it is to identify which decisions belong to separate concepts.

Different tools count modern syntax differently. ESLint’s complexity rule documents classic and modified variants and counts paths created by constructs such as default values, optional chaining, and logical assignment. A switch may add one decision per case under a classic interpretation but only one under a modified variant. Always record the tool and options beside a reported score.

Complexity is normally calculated per function. Class field initializers and static blocks may be treated as implicit functions. A file-level average can hide one risky function among many trivial helpers, so inspect the per-function distribution and the source locations.

A small example

function shippingLabel(order) {
  if (!order.address) return "pickup";
  if (order.expedited && order.weight < 10) return "express";

  switch (order.region) {
    case "local":
      return "ground";
    case "international":
      return order.customsReady ? "air" : "hold";
    default:
      return "review";
  }
}

The function has several independent outcomes. That does not make it automatically wrong; shipping policy really has branches. The review questions are whether order has a validated shape, whether the priority of expedited over region is intentional, whether every region is represented, and whether tests cover the meaningful combinations.

Extracting every return into a tiny function could lower some local scores while making the overall flow harder to follow. A better refactor might represent regions and eligibility as named policy functions, or move data-driven mappings out of control flow while leaving exceptional decisions explicit.

A responsible measurement workflow

1. Choose and document the rule. Record classic or modified counting, threshold, parser, and version. Do not compare numbers from incompatible configurations.
2. Measure functions individually. Sort by score and inspect the top few rather than reducing a repository to one average.
3. Read the code. Identify business decisions, error handling, defensive checks, parsing branches, and incidental nesting.
4. Map tests to outcomes. Branch coverage is not identical to path coverage, but it reveals which decisions have never taken both outcomes.
5. Check change frequency. A high-complexity function that changes weekly presents more risk than stable, well-tested protocol code.
6. Refactor around concepts. Extract cohesive policies, simplify data shapes, replace boolean combinations with explicit states, and use early returns where they clarify exceptional cases.
7. Remeasure and reread. Confirm the code became easier to explain, not merely lower-scoring.
8. Run behavior and performance tests. Structural changes can alter order, error semantics, allocation, and hot paths.

Refactoring strategies that help

Name compound conditions. A variable such as isEligibleForExpress can make a business rule visible, though it does not necessarily reduce complexity. That is fine: readability is the goal.

Replace incompatible booleans with a discriminated state. Three booleans can represent eight combinations even when only four are valid. A status value such as pending, approved, rejected, or cancelled prevents impossible combinations and often simplifies branches.

Move lookup behavior into data when each key maps directly to a value. A table of region labels can replace a switch used only as a dictionary. Do not force side effects, validation, and multi-step logic into an opaque configuration object merely to avoid if statements.

Extract functions when they own a coherent concept and have a clear input/output contract. Extraction that passes ten flags and mutates shared state has moved syntax without reducing reasoning cost. Improving the data model may be more valuable than slicing the function.

What complexity misses

A function can score one and still be dangerous. A regular expression can have pathological runtime behavior. A single call can delete data. A compact promise chain can mishandle errors. Dense array operations can obscure mutation and ordering. Complexity does not measure naming, coupling, temporal behavior, security, or the cost of external systems.

The reverse is also true. A parser, state machine, or protocol handler may contain legitimate branches and still be well engineered because states are explicit, invariants are documented, and tests cover transitions. A threshold should start a conversation and focus review effort, not automatically condemn specialized code.

Cognitive complexity, nesting depth, maintainability indices, dependency graphs, mutation analysis, and test coverage illuminate different properties. Use a small set that answers actual team questions rather than creating a dashboard of numbers no one acts on.

Common mistakes

• Setting a repository threshold before examining the current distribution.
• Comparing scores from tools that count switch, logical operators, or optional chaining differently.
• Splitting a function into arbitrary fragments to satisfy a gate.
• Treating generated code, migrations, and hand-written domain logic identically.
• Using a score as an individual performance metric.
• Ignoring tests and change history when prioritizing work.
• Assuming low complexity means low security or runtime risk.
• Refactoring without preserving the order of guards and side effects.

Review checklist

• The metric variant and threshold are documented.
• High-scoring functions are inspected individually.
• Every branch represents a deliberate business or technical decision.
• Impossible states are prevented by the data model where practical.
• Meaningful outcomes have tests, including errors and boundaries.
• Extracted helpers own coherent concepts and explicit contracts.
• The new version is easier to explain to a teammate.
• Performance-sensitive behavior is measured after structural changes.

Frequently asked questions

What is a good maximum complexity?

There is no universal number. ESLint’s rule has a configurable threshold, but a team should inspect its codebase, domain, testing practices, and change risk. Start by reporting outliers, then adopt a gate only when the response to a violation is clear.

Does an else branch add complexity?

Counting details depend on the implementation. The decision normally comes from the conditional, while else represents the other outcome. Switch cases, logical operators, defaults, and optional chains are where tools more often differ.

Will early returns reduce the score?

They may reduce nesting and improve readability without changing the number of decisions. That can still be an excellent refactor. The score is not the objective; clearer control flow is.

Should generated code be included?

Usually generated code should be measured or governed separately because humans do not maintain it directly. Exclude it intentionally and keep the generator and generated-output verification in the build process.

Further reading

• ESLint complexity rule

Complexity data is valuable when it leads to a better question, a better test, or a clearer model. Keep the number connected to the source decisions that produced it.