@trapi/metadata 📚

This package is responsible for generating metadata information by analyzing TypeScript REST decorators (self defined or third-party libraries). The metadata can than be used for generating a documentation according to the OpenAPI Specification or to create route schema/handling for libraries like: express, koa, etc.

Inspect the CHANGELOG.md in the repository for breaking changes.

Public API

The stable public surface is documented in the API Reference. Anything not listed there should be treated as internal even if it is re-exported, and may change without a major version bump.

Table of Contents

• Installation
• Configuration
• Limitations
• Usage
• Structure
• License

Installation

npm install --save @trapi/metadata

Configuration

Metadata

The metadata configuration object (Top-Level) is the main configuration object of this library and can be defined according the following type scheme:

import type {
    CacheOptions,
    DecoratorConfig,
    TsConfig,
} from "@trapi/metadata";

export type EntryPointOptions = {
    cwd: string,
    pattern: string
};

export type EntryPoint = string |
    string[] |
    EntryPointOptions |
    EntryPointOptions[];

export interface MetadataGenerateOptions {
    /**
     * The entry point to your API.
     */
    entryPoint: EntryPoint;

    /**
     * Directory to ignore during TypeScript files scan.
     * Default: []
     */
    ignore?: string[];

    /**
     * Directory to allow during TypeScript files scan.
     * Default: []
     */
    allow?: string[],

    /**
     * Directory to store and cache metadata files.
     * Default: false
     */
    cache?: string | boolean | Partial<CacheOptions>;

    /**
     * Manual decorator properties configuration.
     */
    decorators?: DecoratorConfig[],

    /**
     * Load a specific preset configuration.
     */
    preset?: string;

    /**
     * Path to tsconfig.json or a TsConfig object.
     */
    tsconfig?: string | TsConfig;
}

Limitations

TRAPI's resolver explicitly handles these TypeScript utility types:

• NonNullable
• Omit
• Partial
• Readonly
• Record
• Required
• Pick

Additionally these are delegated to the TypeScript type checker and resolve through the compiler's own computation:

• Extract
• Exclude
• ReturnType
• Parameters
• Awaited
• InstanceType
• ConstructorParameters

Usage

import {
    generateMetadata,
    Metadata
} from "@trapi/metadata";
import path from "node:path";
import process from "node:process";

const metadata : Metadata = await generateMetadata({
    entryPoint: ['src/controllers/**/*.ts'],
    ignore: ['**/node_modules/**'],
    cache: true,
    preset: '@trapi/preset-decorators-express'
});

console.log(metadata);
// {controllers: [], referenceTypes: {}}

Structure

The package follows a hexagonal layout:

src/
├── core/         # Domain types, port interfaces, generator contracts
│   ├── types/          # Metadata, Controller, Method, Parameter, Type, ...
│   ├── config/         # MetadataGenerateOptions, MetadataGeneratorOptions, EntryPoint
│   ├── decorator/      # DecoratorID enum, decorator config shapes
│   ├── error/          # MetadataError, GeneratorError, ResolverError
│   ├── metadata/       # IMetadataGenerator, IGeneratorContext
│   └── utils/          # Internal helpers (hasOwnProperty, normalizePath, …)
│
├── adapters/     # Infrastructure adapters
│   ├── typescript/     # TypeScript compiler API adapter (type resolver, JSDoc, AST)
│   ├── decorator/      # Decorator resolver + preset loader
│   ├── filesystem/     # Source file scanner, tsconfig loader
│   └── cache/          # Metadata cache
│
├── app/          # Orchestration / use-cases
│   ├── generate.ts     # generateMetadata()
│   └── generator/      # Controller, Method, Parameter generators
│
└── index.ts      # Public entry point

The dependency rule is strict: core/ imports nothing from adapters/ or app/, adapters/ depends only on core/, and app/ wires both together.

License

Made with 💚

Published under MIT License.