@trapi/metadata

@trapi/metadata 📚

This is a library to generate decorator metadata according to a generic specification, which can easily be extended. Therefore, you can use your own decorators or decorators declared by third party libraries.

Please read the CHANGELOG.md in the repository for breaking changes.

Table of Contents

• Installation
• Configuration
• Limitations
• Usage
  • Decorator(s)
  • Generator
• Structure

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 {Decorator, Cache} from '@trapi/metadata';

export interface Config {
    /**
     * The entry point to your API.
     */
    entryFile: string | string[];
    /**
     * Directory to ignore during TypeScript files scan.
     * Default: []
     */
    ignore?: string[];
    /**
     * Directory to store and cache metadata files.
     * Default: false
     */
    cache?: string | boolean | Partial<Cache.Config>;
    /**
     * Decorator config.
     * Default: {
     *      library: [], 
     *      internal: true,
     *      map: {}
     * }
     */
    decorator?: Decorator.Config;
}

Cache

The Cache can be configured by providing different kind of values:

• boolean:
  • true: Cache file will be saved to process.cwd() with generated hash file name and the cache will be cleared at a 10 percent chance.
  • false: Cache is disabled.
• string Cache will be saved to value directory with generated hash file name ...
• object: obda

export interface Config {
    /**
     * Specify if the cache driver should be enabled.
     * 
     * Default: false
     * */
    enabled?: boolean,
    /**
     * Directory relative or absolute path.
     * 
     * Default: process.cwd()
     */
    directoryPath?: string,
    /**
     * Specify the cache file name.
     * 
     * Default: metadata-{hash}.json
     */
    fileName?: string,
    
    /**
     * The cache file(s) will be cleared at a 10% percent change
     * each time.
     * 
     * Default: true
     */
    clearAtRandom?: boolean
}

Decorator

The decorator configuration is relative complex and is not described in detail here yet. Please read the source code and the according tests for better understanding.

• Tests:
  • test/unit/decorator/mapper/index.spec.ts
  • test/unit/decorator/representation/index.spec.ts
• Code:
  • src/decorator/**/*.ts

If you are the author (or contributor) of a TypeScript Decorator API library and need help to set things up, feel free to open an Issue and ask for help.

export interface Config {
    /**
     * Use a pre defined third party TypeRepresentationMap in full scope or
     * only use a partial amount of defined type representations.
     *
     * Default: []
     */
    library?: ConfigLibrary;
    /**
     * Use all internal defined type representations or only use a subset.
     * Default: true
     */
    internal?: TypeRepresentationConfig;
    /**
     * Set up self defined type representations.
     */
    map?: Partial<TypeRepresentationMap>;
}

Limitations

At the moment only the following TypeScript UtilityTypes are supported:

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

Usage

import {createMetadata, Output} from "@trapi/metadata";
import * as path from "path";
import * as process from "process";

const metadata : Output = createMetadata({
        entryFile: path.join(process.cwd(), 'src', 'controllers', '**', '*.ts'),
        ignore: ['**/node_modules/**'],
        cache: {
            enabled: true,    
            directoryPath: path.join(process.cwd(), 'writable')
        },
        decorator: {
            internal: true,
            // Because both libaries does not have any decorator
            // names in common, the represnetation also does not differ and 
            // we can use them both :)
            library: ['decorators-express', 'typescript-rest']
        }
});

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

Structure

coming soon

Credits

Parts of this package @trapi/metadata code rest on a continued fork repository (typescript-swagger) of the typescript-rest-swagger library of thiagobustamante and was also inspired by the tsoa library of lukeatury.