Flow Types for JavaScript AST

Common errors

• Cannot get `node.id.name` because `node.id` is `null` or `undefined`.

  cause Attempting to access a property on an AST node's `id` property, when `id` is defined as nullable (e.g., for anonymous functions or classes without explicit identifiers).
  fix Add a null check for the `id` property before attempting to access its `name`: `if (node.id) { return node.id.name; }`

• Property `name` is missing in `Literal` [1].

  cause Attempting to access a property (like `name`) that does not exist on a specific AST node type (e.g., `Literal` nodes have a `value` property, not `name`).
  fix Consult the AST specification for the correct properties available on the specific node type you are working with. For `Literal` nodes, you likely want `node.value`.

• Error: `ast-types-flow` cannot be found or is not a module.

  cause Attempting to use `require()` or a non-type `import` for `ast-types-flow`, which is exclusively a type definition package and does not provide runtime JavaScript modules.
  fix Ensure you are using `import type { ... } from 'ast-types-flow';` for Flow type imports. The package is not meant for runtime consumption.

Warnings

• deprecated The `ast-types-flow` package is largely abandoned (last updated ~8-10 years ago) and targets Flow, a static type checker that has seen significantly reduced adoption in favor of TypeScript. It is not recommended for new projects.
  Fix: Consider using TypeScript with `@types/estree` or `@types/babel__types` for AST typing in modern JavaScript projects, or migrate existing Flow projects to TypeScript.
• gotcha The library utilizes a non-standard syntax (comments like `// extends Node`) for defining type hierarchies, requiring a specific transform step to generate the final Flow types. This can complicate tooling integration and understanding.
  Fix: Ensure the necessary transform is applied in your build pipeline if you are using this library. Be aware that this approach is unique to this library and not standard Flow syntax.
• gotcha To ensure Flow's disjoint union refinement works correctly, the library generates types with duplicated complete definitions and adds private `_Foo: void` fields. This can lead to verbose type definitions and might be confusing.
  Fix: This is an internal implementation detail of the library to work around Flow's limitations at the time. There is no direct fix for users other than being aware of this behavior.
• gotcha Flow type definitions for ASTs often expose properties that can be `null` or `undefined` (e.g., `id` on `ClassDeclaration` or `FunctionExpression`) or that simply do not exist on certain node types (e.g., `name` on `Literal`). Direct access without checks will result in Flow errors.
  Fix: Always implement explicit null/undefined checks (e.g., `if (node.id)`) or type guards when accessing potentially nullable properties, and consult the AST specification for property existence on specific node types.

Install

• npm install ast-types-flow npm
• yarn add ast-types-flow yarn
• pnpm add ast-types-flow pnpm

Imports

• Node
  wrong:

  const Node = require('ast-types-flow');

  correct:

  import type { Node } from 'ast-types-flow';

  Flow type imports use `import type`. CommonJS `require` does not handle Flow types directly.
• Identifier
  wrong:

  import { Identifier } from 'ast-types-flow';

  correct:

  import type { Identifier } from 'ast-types-flow';

  Always use `import type` for Flow type declarations. Named imports without `type` are for JavaScript values.
• ClassDeclaration
  wrong:

  const { ClassDeclaration } = require('ast-types-flow');

  correct:

  import type { ClassDeclaration } from 'ast-types-flow';

  The package exports only Flow types, not runtime JavaScript modules. CommonJS `require` is not applicable for types.

Quickstart

Demonstrates importing Flow types for AST nodes and using them in a type-checked function to safely extract names, handling potential nulls and missing properties according to Flow's rules.

/* @flow */

import type { Node, Identifier, ClassDeclaration, FunctionDeclaration, FunctionExpression, Literal } from 'ast-types-flow';

/**
 * Safely extracts the name from various AST node types.
 * Handles cases where IDs might be null or properties might not exist.
 * @param {Node} node - The AST node to inspect.
 * @returns {string} The name of the node or 'Unknown'.
 */
function getName(node: Node): string {
  switch (node.type) {
    case 'Identifier':
      return node.name; // 'Identifier' nodes reliably have a 'name' property.

    case 'ClassDeclaration':
      // Flow would flag 'node.id' as potentially null. Refinement is needed.
      if (node.id) {
        return node.id.name;
      }
      return 'AnonymousClass'; // Handle the nullable case explicitly.

    case 'FunctionDeclaration':
      // Assuming 'id' is always present for 'FunctionDeclaration' in this context.
      return node.id.name;

    case 'FunctionExpression':
      // 'FunctionExpression' can be anonymous; 'id' might be null.
      if (node.id) {
        return node.id.name;
      } else {
        return 'AnonymousFunction';
      }

    case 'Literal':
      // 'Literal' nodes do not have a 'name' property. Flow would error here.
      if (typeof node.value === 'string' || typeof node.value === 'number') {
        return String(node.value); // Return the literal's value instead.
      }
      return 'LiteralValue';

    default:
      return 'UnknownNode';
  }
}

// Example usage (not runnable without an actual AST node)
const myIdentifier: Identifier = { type: 'Identifier', name: 'foo' };
const myClassDecl: ClassDeclaration = { type: 'ClassDeclaration', id: { type: 'Identifier', name: 'MyClass' }, body: { type: 'BlockStatement', body: [] } };
const myLiteral: Literal = { type: 'Literal', value: 123, raw: '123' };

console.log(getName(myIdentifier)); // Expected: foo
console.log(getName(myClassDecl));  // Expected: MyClass
console.log(getName(myLiteral));    // Expected: 123