# conga-annotations

> Annotation parser library for ES2014/ES2015, ES5/ES6

Latest version **1.0.0** (published 2017-04-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install conga-annotations
pnpm add conga-annotations
yarn add conga-annotations
bun add conga-annotations
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2017-04-02 |
| First published | 2013-05-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 4.0.0 |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17 |
| Author | Marc Roulias |
| Maintainers | lampjunkie |
| Keywords | annotation, annotations, ecmas, es6, es2015 |

## Links

- npm: https://www.npmjs.com/package/conga-annotations
- Repository: https://github.com/congajs/conga-annotations
- Issues: https://github.com/congajs/conga-annotations/issues
- npm.io page: https://npm.io/package/conga-annotations

## Dependencies (1)

- [StringScanner](https://npm.io/package/StringScanner.md) 0.0.3

## Recent versions

- 1.0.0 (latest) — 2017-04-02
- 0.1.8 — 2015-01-27
- 0.1.7 — 2014-05-19
- 0.1.6 — 2014-05-19
- 0.1.5 — 2014-01-25
- 0.1.4 — 2013-12-29
- 0.1.3 — 2013-07-24
- 0.1.2 — 2013-07-20
- 0.1.1 — 2013-07-13
- 0.1.0 — 2013-07-13
- 0.0.7 — 2013-07-13
- 0.0.6 — 2013-07-12
- 0.0.5 — 2013-07-11
- 0.0.4 — 2013-07-09
- 0.0.3 — 2013-06-08
- … 2 more at https://npm.io/package/conga-annotations/versions

## README

# conga-annotations 

[![NPM version][npm-image]][npm-url]
[![NPM downloads][npm-download]][npm-url]
[![Build status][ci-image]][ci-url]
[![Dependency Status][daviddm-image]][daviddm-url]


## Overview

This is a Node.js library which allows you to add annotations describing metdata data
about classes, constructors, methods, and properties within javascript files.

ES6 Example:

    /**
     * @MyClassAnnotation("hello world")
     */
    class HelloWorld {

        constructor() {

            /**
             * @MyPropertyAnnotation(foo=[1,2,3,4], bar={"hello":"there"})
             */   
            this.myProperty = 'foo'
        }

        /**
         * @MyMethodAnnotation("foobar", something="hello")
         */
        myMethod() {

        }

    }

ES5 Example:

    /**
     * @MyConstructorAnnotation("some value")
     */
    function HelloWorld(){}

    HelloWorld.prototype = {
        
        /**
         * @MyPropertyAnnotation(foo=[1,2,3,4], bar={"hello":"there"})
         */
        myProperty: 'foo',

        /**
         * @MyMethodAnnotation("foobar", something="hello")
         */
        myMethod: function(){

        }
    }


## Installation
Need Node >= 4.0.0

    > npm install conga-annotations

## Usage

Full example in [example folder](https://github.com/congajs/conga-annotations/tree/master/example) (`node main.js` to test is). 

### Create an Annotation

    // my-class-annotation.js
    // ----------------------------
    'use strict'
    const Annotation = require('conga-annotations').Annotation;

    module.exports = class MyClassAnnotation extends Annotation {

        /**
         * The possible targets
         *
         * (Annotation.DEFINITION, Annotation.CONSTRUCTOR, Annotation.PROPERTY, Annotation.METHOD)
         *
         * @type {Array}
         */
        static get targets() { return [Annotation.DEFINITION] }

        /**
         * Constructor to add attributes
         * @type {Array}
         */
        constructor(data, filePath){
          super(data, filePath)        
        }
        
        /**
         * Optional initialization method that
         * can be used to transform data
         *
         * @param  {Object} data
         * @return {void}
         */
        init: function(data){

            // set defaults
            this.value = data.value || 'default value'
            this.sample = data.sample || 'default value for sample'

            // do something with data (error check, etc.)
        }
        
    });


### Add the Annotation to a File

    // my-sample.js
    // ------------

    /**
     * @MyClassAnnotation("some value", sample="here is an attribute value")
     */
    class HelloWorld {}

### Parse the Annotation

    // my-parser.js
    // ------------

    const path = require('path')
    const annotations = require('conga-annotations')

    // create the registry
    const registry = new annotations.Registry()

    // add annotations to the registry
    registry.registerAnnotation(path.join(__dirname, 'my-class-annotation'))

    // create the annotation reader
    const reader = new annotations.Reader(registry)

    // parse the annotations from a file, default parse ES6 file, Reader.ES5 to force ES5
    reader.parse(path.join(__dirname, 'my-sample.js'), Reader.ES6)

    // get the annotations
    const definitionAnnotations = reader.definitionAnnotations
    const constructorAnnotations = reader.constructorAnnotations
    const methodAnnotations = reader.methodAnnotations
    const propertyAnnotations = reader.propertyAnnotations

    // loop through and handle the annotations
    constructorAnnotations.forEach(function(annotation){

        // @MyConstructorAnnotation
        if (annotation.constructor.name === 'MyClassAnnotation'){

            // do something with the annotation data
            console.log(annotation.target); // -> "HelloWorld"
            console.log(annotation.value); // -> "some value"
            console.log(annotation.sample); // -> "here is an attribute value"
        }

    });

## Supported Attribute Types

    // string
    @MyAnnotation(foo="a string")

    // boolean
    @MyAnnotation(foo=true)

    // array
    @MyAnnotation(foo=[1,2,3,4])

    // object
    @MyAnnotation(foo={hi:"there"})

    // nested annotations
    @MyAnnotation(foo=@MyNestedAnnotation("this is nested", foo=true))

    // array of nested annotations
    @MyAnnotation(foo=[@MyNestedAnnotation("nested 1"), @MyNestedAnnotation("nested 2")])

## License
[MIT](https://github.com/conga/conga-annotations/blob/master/LICENSE)

[npm-image]: https://img.shields.io/npm/v/conga-annotations.svg?style=flat-square
[npm-url]: https://npmjs.org/package/conga-annotations
[npm-download]: https://img.shields.io/npm/dt/conga-annotations.svg
[ci-image]: https://travis-ci.org/congajs/conga-annotations.svg?branch=master
[ci-url]: https://travis-ci.org/congajs/conga-annotations
[daviddm-image]: http://img.shields.io/david/congajs/conga-annotations.svg?style=flat-square
[daviddm-url]: https://david-dm.org/congajs/conga-annotations
[codeclimate-image]: https://img.shields.io/codeclimate/github/congajs/conga-annotations.svg?style=flat-square
[codeclimate-url]: https://codeclimate.com/github/congajs/conga-annotations

---
_Source: https://npm.io/package/conga-annotations · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
