npm: @asyncapi/optimizer Source: packages/optimizer/

This document describes what the package is, what problem it solves, how it works, how to develop and release it inside the asyncapi/cli monorepo, and the v2 contract. Consumer-facing install/usage examples live in packages/optimizer/README.md. A beginner-oriented migration walkthrough lives in optimizer-migration.md.

@asyncapi/optimizer is a library that analyzes an AsyncAPI document and reports (and optionally applies) structural optimizations that make the document smaller and less repetitive:

• remove unused components,
• reuse existing components where the same object is duplicated,
• move duplicated objects into components,
• move all eligible objects into components and replace them with $refs.

It is designed to be consumed by UIs and CLIs. The primary in-repo consumer is the asyncapi optimize command. It is not a CLI itself (no bin).

AsyncAPI documents frequently inline the same message/schema shapes in many places. The optimizer detects those and rewrites the document to use the components section plus $refs, without changing the document's meaning.

AsyncAPI YAML/JSON
      │  new Optimizer(text)
      ▼
  getReport()  ──►  Report[]  (what could be optimized, grouped by type)
      │  getOptimizedDocument({ rules, output, disableOptimizationFor })
      ▼
  optimized AsyncAPI document (YAML or JSON string)

import { Optimizer, Output } from '@asyncapi/optimizer';

const optimizer = new Optimizer(yamlOrJsonOrObject);
const report = await optimizer.getReport();               // Report[]
const optimized = optimizer.getOptimizedDocument(options); // string (YAML or JSON)

interface ReportElement { path: string; action: Action; target?: string }
interface Report { type: string; elements: ReportElement[] }   // v2 shape
interface Options {
  rules?: { reuseComponents?: boolean; removeComponents?: boolean; moveAllToComponents?: boolean; moveDuplicatesToComponents?: boolean };
  output?: Output;
  disableOptimizationFor?: { schema?: boolean };
}

All failures are typed subclasses of OptimizerError, each carrying a stable code (OptimizerErrorCode) and optional details. The library never calls process.exit and never prints to the console.

Consumers can branch on err instanceof OptimizerError and/or err.code.

Exit codes are a CLI-process concept and live in the CLI, not the library. The asyncapi optimize command maps optimizer error codes onto the unified exit-code table in codes_reference-cleanup-docs.md:

No new CLI codes were required; see optimizer-migration/v2-error-codes-mapping.md in the working docs.

packages/optimizer/
├── src/                 # TypeScript source (published as compiled lib/)
├── test/                # Jest tests + fixtures
├── package.json
├── tsconfig.json        # CJS build -> lib/
├── jest.config.js
├── README.md            # npm-facing install/usage
└── CHANGELOG.md         # managed with Changesets

Published npm files: /lib, README.md, LICENSE (main/types point at lib/). Build output is CommonJS only (unchanged from v1).

From the repo root (npm workspaces + Turborepo):

npm install
npm run optimizer:build   # turbo run build --filter=@asyncapi/optimizer
npm run optimizer:test    # turbo run test  --filter=@asyncapi/optimizer
npm test                  # optimizer Jest + CLI Mocha + GitHub Action tests (what PR CI runs)

Turbo builds @asyncapi/optimizer before the root CLI build, because the CLI's build compiles src/apps/cli/commands/optimize.ts, which imports this package. Root pretest is npm run build, so npm test always builds the optimizer first. Do not use unfiltered turbo run test: workspaces include ".", so that would recurse into the root test script.

Published from asyncapi/cli (not the old standalone repo). The CLI stays at the repo root; package.json workspaces are [".", "packages/*"] so Changesets still sees @asyncapi/cli (same contributor flow as today) plus @asyncapi/optimizer.

1. Change code. For optimizer-only work, select @asyncapi/optimizer. For CLI work, select @asyncapi/cli (unchanged). A PR can name both.
2. npx changeset → choose the package(s), bump, write a summary; commit the .changeset/*.md.
3. On merge, the Changesets action opens/updates a Version Packages PR (changeset version + bump:github-action). That bumps each named package's package.json and CHANGELOG.
4. Merging that PR publishes changed packages to npm (changeset publish, with a root npm publish --provenance fallback) from .github/workflows/release-with-changesets.yml.

@asyncapi/optimizer must be registered as a Trusted Publisher on npm for asyncapi/cli before the first publish. Package metadata: private: false, publishConfig.access: public.

• It is not a full AsyncAPI validator (it relies on @asyncapi/parser).
• It does not call process.exit or print to the console (that is the CLI command's job).
• It does not change the asyncapi optimize command's UX.