Overview

This package provides TypeScript types and utilities for working with the type information generated by @hubspot/ts-export-types. It includes:

• Type definitions — All ApiNode types representing exports, functions, classes, properties, and more
• Type guards — Functions for narrowing ApiNode types safely
• Result utilities — Helpers for looking up exports and referenced types

Installation

npm install @hubspot/ts-export-types-reader

Usage

Working with analyze results

import {
  type AnalyzePackageResult,
  createAnalyzeResultReader,
} from '@hubspot/ts-export-types-reader';

// Load your generated API types (from @hubspot/ts-export-types output)
import apiData from './api/api.json';

const api = createAnalyzeResultReader(apiData as AnalyzePackageResult);

// Find an export by name
const myFunction = api.findExportByName({
  exportPath: '.',
  exportName: 'myFunction',
});

// Find a referenced type by its ID
const myType = api.findReferencedTypeById('MyType:my-package:dist/index.d.ts');

Using type guards

import {
  type ApiNode,
  isFunctionNode,
  isObjectNode,
  isTypeReferenceNode,
  isUnionNode,
} from '@hubspot/ts-export-types-reader';

function processNode(node: ApiNode) {
  if (isFunctionNode(node)) {
    console.log('Function parameters:', node.parameters);
    console.log('Return type:', node.returnType);
  }

  if (isObjectNode(node)) {
    node.properties.forEach((prop) => {
      console.log(`Property: ${prop.name}`);
    });
  }

  if (isUnionNode(node)) {
    node.types.forEach(processNode);
  }

  if (isTypeReferenceNode(node)) {
    console.log('References type:', node.typeId);
  }
}

Traversing types

import {
  type AnalyzePackageResult,
  type ApiNode,
  createAnalyzeResultReader,
  isTypeReferenceNode,
} from '@hubspot/ts-export-types-reader';

function collectAllTypeIds(
  api: ReturnType<typeof createAnalyzeResultReader>,
  node: ApiNode,
  visited = new Set<string>()
): string[] {
  const typeIds: string[] = [];

  if (isTypeReferenceNode(node)) {
    if (!visited.has(node.typeId)) {
      visited.add(node.typeId);
      typeIds.push(node.typeId);

      const referencedType = api.findReferencedTypeById(node.typeId);
      typeIds.push(...collectAllTypeIds(api, referencedType, visited));
    }
  }

  return typeIds;
}

API Reference

Result utilities

createAnalyzeResultReader(result: AnalyzePackageResult): AnalyzeResultExport

Creates a helper object for querying analyze results.

interface AnalyzeResultExport {
  findExportByName(options: FindExportByNameOptions): ExportNode;
  findReferencedTypeById(typeId: string): ApiNode;
}

interface FindExportByNameOptions {
  exportPath: string; // e.g., "." or "./utils"
  exportName: string; // e.g., "myFunction"
}

Types

AnalyzePackageResult

The root type for analyze output:

interface AnalyzePackageResult {
  exports: Record<string, ExportNode[]>;
  types: Record<string, ApiNode>;
}

ApiNode

Union of all possible node types:

type ApiNode =
  | ArrayNode
  | BuiltInTypeReferenceNode
  | ClassNode
  | ConditionalNode
  | ConstructorNode
  | ExportNode
  | ExternalTypeReferenceNode
  | FunctionNode
  | InlinedTypeReferenceNode
  | IntersectionNode
  | LiteralNode
  | MappedTypeNode
  | MethodNode
  | ObjectNode
  | ParameterNode
  | PrimitiveNode
  | PropertyNode
  | TupleElementNode
  | TupleNode
  | TypeParameterNode
  | TypeReferenceNode
  | UnionNode
  | UnknownNode;

ApiNodeKind

Constants for all node kinds:

const ApiNodeKind = {
  Array: 'array',
  BuiltInTypeReference: 'built-in-type-reference',
  Class: 'class',
  Conditional: 'conditional',
  Constructor: 'constructor',
  Export: 'export',
  ExternalTypeReference: 'external-type-reference',
  Function: 'function',
  InlinedTypeReference: 'inlined-type-reference',
  Intersection: 'intersection',
  Literal: 'literal',
  MappedType: 'mapped-type',
  Method: 'method',
  Object: 'object',
  Parameter: 'parameter',
  Primitive: 'primitive',
  Property: 'property',
  Tuple: 'tuple',
  TupleElement: 'tuple-element',
  TypeParameter: 'type-parameter',
  TypeReference: 'type-reference',
  Union: 'union',
  Unknown: 'unknown',
} as const;

Type guards

All type guards follow the pattern is{NodeType}(node: ApiNode): node is {NodeType}:

| Function | Narrows to | | ----------------------------- | --------------------------- | | isArrayNode | ArrayNode | | isBuiltInTypeReferenceNode | BuiltInTypeReferenceNode | | isClassNode | ClassNode | | isConditionalNode | ConditionalNode | | isConstructorNode | ConstructorNode | | isExportNode | ExportNode | | isExternalTypeReferenceNode | ExternalTypeReferenceNode | | isFunctionNode | FunctionNode | | isInlinedTypeReferenceNode | InlinedTypeReferenceNode | | isIntersectionNode | IntersectionNode | | isLiteralNode | LiteralNode | | isMappedTypeNode | MappedTypeNode | | isMethodNode | MethodNode | | isObjectNode | ObjectNode | | isParameterNode | ParameterNode | | isPrimitiveNode | PrimitiveNode | | isPropertyNode | PropertyNode | | isTupleElementNode | TupleElementNode | | isTupleNode | TupleNode | | isTypeParameterNode | TypeParameterNode | | isTypeReferenceNode | TypeReferenceNode | | isUnionNode | UnionNode | | isUnknownNode | UnknownNode |

Node type interfaces

ExportNode

Represents an exported symbol:

interface ExportNode {
  kind: 'export';
  exportName: string;
  declarationKind: ExportDeclarationKind;
  isType?: boolean;
  isDefault?: boolean;
  type: ApiNode;
  jsdoc?: Jsdoc;
}

type ExportDeclarationKind =
  | 'const'
  | 'let'
  | 'var'
  | 'function'
  | 'class'
  | 'type'
  | 'interface'
  | 'enum';

FunctionNode

Represents a function type:

interface FunctionNode {
  kind: 'function';
  functionKind: FunctionKind;
  parameters: ParameterNode[];
  returnType: ApiNode;
  typeParameters?: TypeParameterNode[];
  name?: string;
  isAsync?: boolean;
  jsdoc?: Jsdoc;
}

type FunctionKind = 'arrow' | 'expression' | 'declaration' | 'call-signature';

ClassNode

Represents a class:

interface ClassNode {
  kind: 'class';
  name?: string;
  isAbstract: boolean;
  typeParameters?: TypeParameterNode[];
  implements?: ApiNode[];
  constructors: ConstructorNode[];
  properties: PropertyNode[];
  methods: MethodNode[];
  staticProperties: PropertyNode[];
  staticMethods: MethodNode[];
  jsdoc?: Jsdoc;
}

TypeReferenceNode

References a type defined in the types map:

interface TypeReferenceNode {
  kind: 'type-reference';
  typeId: string;
  typeString: string;
  typeArguments?: ApiNode[];
}

ExternalTypeReferenceNode

References a type from an external package:

interface ExternalTypeReferenceNode {
  kind: 'external-type-reference';
  typeName: string;
  typeString: string;
  packageName: string;
  packageVersion: string;
  typeArguments?: ApiNode[];
}

Requirements

• Node.js >= 18.0.0

License

MIT © HubSpot