# graphql-metadata

> Annotate a GraphQL Schema

Latest version **0.7.6** (published 2020-08-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install graphql-metadata
pnpm add graphql-metadata
yarn add graphql-metadata
bun add graphql-metadata
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.6 |
| Published | 2020-08-21 |
| First published | 2020-01-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 33.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 27 |
| Author | Enda Phelan |
| Maintainers | wtrocki |

## Links

- npm: https://www.npmjs.com/package/graphql-metadata
- Repository: https://github.com/aerogear/graphql-metadata
- Homepage: https://github.com/aerogear/graphql-metadata/#readme
- Issues: https://github.com/aerogear/graphql-metadata/issues
- npm.io page: https://npm.io/package/graphql-metadata

## Dependencies (1)

- [vm2](https://npm.io/package/vm2.md) 3.9.2

## Recent versions

- 0.7.6 (latest) — 2020-08-21
- 0.7.3-dev1 (next) — 2020-07-28
- 0.7.5 — 2020-08-21
- 0.7.4 — 2020-08-20
- 0.7.3 — 2020-07-28
- 0.7.2 — 2020-07-27
- 0.7.1 — 2020-07-27
- 0.7.0 — 2020-06-23
- 0.6.3 — 2020-06-08
- 0.6.2 — 2020-06-03
- 0.6.1 — 2020-06-03
- 0.6.0 — 2020-06-03
- 0.5.0 — 2020-01-17
- 0.4.0 — 2020-01-17
- 0.3.0 — 2020-01-17
- … 2 more at https://npm.io/package/graphql-metadata/versions

## README

# graphql-metadata

Attach metadata to your GraphQL schema using directive like syntax. 

Library supoports following formats:

- (**DEPRECATED**) Annotations: Group of elements with common namespace. For example `@db.length: 200`
- Marker: Single instance (key) with multiple values. For example `@db length:200`
- Metadata: Directive-like config. For example `@db(length: 200, columns: ['id', 'name'])`

## Installation

```bash
npm i graphql-metadata
```

## Usage

### Marker parsing

Markers using different syntax for elements that do not support grouping.
For example `@marker true` etc.

Usage: 
```js
const result = parseMarker('db', `
  This is a description
  @db length:200, unique: true 
`)
```

No value usage:

```js
const result = parseMarker('db', `
  This is a description
  @db
`)
```

### Metadata parsing

Metadata uses the same syntax as GraphQL directives.

Usage: 

```js
const field: GraphQLField<any,any> = {
  ...,
  description: `@db(length:200, 
      unique: true, 
      columns: ['id', 'name']
      description: 'Some description'
    )`
}
const result = parseMetadata('db', field)

// Returns:
{
  length:200, 
  unique: true, 
  columns: ['id', 'name']
  description: 'Some description'
}
```

No value usage:

```js
const field: GraphQLField<any,any> = {
  ...,
  description: '@db',
}
const result = parseMetadata('db', field)

// Returns true
```

Or with a string:

```js
const result = parseMetadata('db', '@db(name: "users")')
```

### [DEPRECATED] Annotations parsing

Here is a very basic example with a `namespace` (here `'db'`) and a `description` that needs to be parsed:

```js
const { parseAnnotations } = require('graphql-metadata')

const result = parseAnnotations('db', `
  This is a description
  @db.length: 200
  @db.foo: 'bar'
  @db.unique
  @db.index: { name: 'foo', type: 'string' }
`)

console.log(result)
```

This will output an object containing the annotations:

```js
{
  length: 200,
  foo: 'bar',
  unique: true,
  index: { name: 'foo', type: 'string' }
}
```

In a GraphQL schema, you can use the `description` property on `GraphQLObjectType`, `GraphQLField`...

```js
const { parseAnnotations } = require('graphql-metadata')
const { buildSchema, isObjectType } = require('graphql')

const schema = buildSchema(`
  """
  @db.table: 'users'
  """
  type User {
    """
    @db.primary
    """
    id: ID!
  }
`)

const typeMap = schema.getTypeMap()
for (const key in typeMap) {
  const type = typeMap[key]
  // Tables
  if (isObjectType(type)) {
    const typeAnnotations = parseAnnotations('db', type.description)
    console.log(type.name, typeAnnotations)
    const fields = type.getFields()
    for (const key in fields) {
      const field = fields[key]
      const fieldAnnotations = parseAnnotations('db', field.description)
      console.log(field.name, fieldAnnotations)
    }
  }
}
```

Which will output:

```js
User { table: 'users' }
id { primary: true }
```


### Strip annotations

Sometimes it will be helpful to strip the annotations from the description. For example, you may not want to display them in a GraphQL schema explorer.

```js
const { stripAnnotations } = require('graphql-metadata')

const result = stripAnnotations('db', `
  This is a description
  @db.length: 200
  @db.foo: 'bar'
  @db.unique
  @db.index: { name: 'foo', type: 'string' }
`)

console.log(result)
```

The result will be:

```js
`
  This is a description
`
```

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