# decorators-parser-js

> ### License © 2023 Smartschool Inc. All rights reserved.

Latest version **0.0.8** (published 2023-09-04) · All rights reserved license · 0 weekly downloads

## Install

```sh
npm install decorators-parser-js
pnpm add decorators-parser-js
yarn add decorators-parser-js
bun add decorators-parser-js
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.8 |
| Published | 2023-09-04 |
| First published | 2023-08-21 |
| Weekly downloads | 0 |
| License | All rights reserved |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 25.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Michał Kostyk |
| Maintainers | mkostyk |
| Keywords | decorators, parser, js |

## Links

- npm: https://www.npmjs.com/package/decorators-parser-js
- Repository: https://github.com/mkostyk/decorators-parser-nodejs
- Homepage: https://github.com/mkostyk/decorators-parser-nodejs#readme
- Issues: https://github.com/mkostyk/decorators-parser-nodejs/issues
- npm.io page: https://npm.io/package/decorators-parser-js

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.0.8 (latest) — 2023-09-04
- 0.0.7 — 2023-09-03
- 0.0.6 — 2023-09-02
- 0.0.5 — 2023-08-21
- 0.0.4 — 2023-08-21
- 0.0.3 — 2023-08-21
- 0.0.2 — 2023-08-21
- 0.0.1 — 2023-08-21

## README

## Decorators Parser

### License
© 2023 Smartschool Inc. All rights reserved.

### Installation guide
1. Install NodeJS 18 or newer from [https://nodejs.org/en/download](https://nodejs.org/en/download)
2. Add NodeJS to PATH - [example guide](https://www.tutorialspoint.com/nodejs/nodejs_environment_setup.htm)
3. Run `npm install "decorators-parser-js"` in your command line


### API
#### parse
```js
function parse(file, data)
```
Parses given string or file and returns a list of dictionaries. If both `file` and `data` are provided, `data` will be ignored.

#### constructor
```js
function constructor(constraints={}, ignored=[])
```
Creates a new Parser object. `constraints` is a dictionary of constraints for decorators. `ignored` is a list of decorators to ignore.

### Decorators format
Decorator name can be any string that does not contain '@' character. If decorator
does not satisfy this requirement `InvalidDecoratorException` will be thrown.

#### Example:
```
@decorator(some nice value)
```

### Standard decorators
Decorators can be used in one of three ways:
```
@decorator(value)
```
or
```
@decorator()
Some very long and complicated value that would be hard to read if it were in parenthesis like the value above.
```
or
```
@decorator
Some very long and complicated value that would be hard to read if it were in parenthesis like the value above.
```

All of these create Javascript dictionary like this:
```js
{
    'decorator': 'value'
}
```

### @new decorator

Using @new decorator starts a new dictionary and adds it to the current list of dictionaries. In a single piece of text between two @new decorators (which correspond to a single JavaScript dictionary) there can not be two decorators with the same name. Using a same name without an appropriate @new decorator will result in `DuplicateDecoratorException` being thrown.

#### Example:
task.txt:
```
@question()
Who is Lincoln?

@new
@question()
What is the purpose of the Bill of Rights?
```

run.js:
```js
import { Parser } from "decorators-parser-js"
let task_parser = new Parser()
console.log(task_parser.parse('task.txt'))
```

result:
```js
[
    {
        'question': 'Who is Lincoln?'
    },
    {
        'question': 'What is the purpose of the Bill of Rights?'
    }
]
```
### Global decorators

In addition to standard decorators, decorators which name starts with `global-` are added to each dictionary while parsing a file. Dictionary key is the decorator's suffix after `global-` 

#### Example:
task.txt:
```
@global-topic(History)
@question()
Who is Lincoln?

@new
@question()
What is the purpose of the Bill of Rights?
```

run.js:
```js
import { Parser } from "decorators-parser-js"
let task_parser = new Parser()
console.log(task_parser.parse('task.txt'))
```

result:
```js
[
    {
        'topic': 'History',
        'question': 'Who is Lincoln?'
    },
    {
        'topic': 'History',
        'question': 'What is the purpose of the Bill of Rights?'
    }
]
```

### Constraints

Decorators can use constraints on their values. If a decorator has value that does not match regular expression
provided, Parser will throw `InvalidValueException`. Parser class takes optional `constraints` argument in its constructor which
is a JavaScript dictionary in a format shown below (if format of the given dictionary is invalid, `InvalidConstraintException` will be thrown):
```js
let example = {
    'question': 
    {
        'regex': '^([^@]+)$',
        'description': 'any non-empty string without @'
    },
    'correct':
    {
        'regex': '^([1-4])$',
        'description': 'any number from 1 to 4'
    }
}
```


#### Example 1

task.txt:
```
@correct(11)
```

run.js:
```js
import { Parser } from "decorators-parser-js"
let task_parser = new Parser(example)
console.log(task_parser.parse('task.txt'))
```

Will result in the following output:
```
InvalidValueException [Error]: 'correct' should be any number from 1 to 4 but is 11
```

#### Example 2
If we take Example 1 but change task.txt file to:
```
correct(1)
```

The output will be:
```js
[
    {
        'correct': '1'
    }
]
```

### Ignored decorators

If you need to use @ symbol for something else than decorator, you can specify
names to exclude from the search

#### Example:
task.txt:
```
@question
Some long question with @ref in it
```

run.js:
```js
import { Parser } from "decorators-parser-js"
let task_parser = new Parser({}, ["ref"])
console.log(task_parser.parse('task.txt'))
```

Will result in the following output:
```js
[
    {
        'question': 'Some long question with @ref in it'
    }
]
```

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