# datatype-expansion

> Utility tool to expand a given RAML type and create a canonical form

Latest version **0.4.1** (published 2020-07-14) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install datatype-expansion
pnpm add datatype-expansion
yarn add datatype-expansion
bun add datatype-expansion
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.4.1 |
| Published | 2020-07-14 |
| First published | 2016-08-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 319.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Mulesoft |
| Maintainers | jstoiko |
| Keywords | raml, expansion, json, types |

## Links

- npm: https://www.npmjs.com/package/datatype-expansion
- Repository: https://github.com/raml-org/datatype-expansion
- Homepage: https://github.com/raml-org/datatype-expansion#readme
- Issues: https://github.com/raml-org/datatype-expansion/issues
- npm.io page: https://npm.io/package/datatype-expansion

## Dependencies (1)

- [lodash](https://npm.io/package/lodash.md) ^4.17.19

## 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.4.1 (latest) — 2020-07-14
- 0.4.0 — 2020-05-08
- 0.3.8 — 2019-07-22
- 0.3.7 — 2019-05-17
- 0.3.6 — 2018-12-03
- 0.3.5 — 2018-11-01
- 0.3.4 — 2018-05-17
- 0.3.3 — 2018-05-15
- 0.3.2 — 2018-04-02
- 0.3.1 — 2018-02-24
- 0.3.0 — 2018-02-09
- 0.2.6 — 2017-12-05
- 0.2.5 — 2017-11-08
- 0.2.4 — 2017-11-02
- 0.2.3 — 2017-10-21
- … 16 more at https://npm.io/package/datatype-expansion/versions

## README

# RAML Data Type Expansion

[![Greenkeeper badge](https://badges.greenkeeper.io/raml-org/datatype-expansion.svg)](https://greenkeeper.io/)
[![Build Status](https://travis-ci.org/raml-org/datatype-expansion.svg?branch=master)](https://travis-ci.org/raml-org/datatype-expansion) 
[![Coverage Status](https://coveralls.io/repos/github/raml-org/datatype-expansion/badge.svg?branch=master)](https://coveralls.io/github/raml-org/datatype-expansion?branch=master)

> Often, tools need the full expansion of RAML data types where there are no references. This module gives you a utility tool to expand a given type and create a canonical form.

## Installation

### NPM

```
npm install datatype-expansion
```

## RAML type expanded form

The RAML expanded form for a RAML type, resolves references and fills missing information to compute a fully expanded representation of the type.
The form and the algorithm to compute is [documented here](doc/algorithms.md).

### Usage

The Node.js interface for the library offers the `expandedForm` function to compute the expanded form.
It accepts an in-memory JSON representation of the type, the types mapping and an optional callback function or options object.
It returns the canonical form or an exception. The following options are supported:

* `callback`: Provides a callback function via the options object.
* `topLevel` (default: `any`): The default RAML type to use when base type is not explicit and cannot be inferred.
It can be `any` or `string`, depending on whether the type comes from the `body` of a RAML service.
* `trackOriginalType` (default: `false`): Controls whether expansion should track the original type in a property called `originalType` when expanding a type reference.

#### Sync API
```js
const tools = require('datatype-expansion');

const typesContext = {
  Song: {
    properties: {
      title: 'string',
      length: 'number'
    }
  },
  Album: {
    properties: {
      title: 'string',
      songs: 'Songs.Song[]'
    }
  }
};
const expanded = tools.expandedForm(typesContext['Album'], typesContext)
console.log(JSON.stringify(expanded,null,2));
```

#### Callback API
```js
const tools = require('datatype-expansion');

const typesContext = {
  Song: {
    properties: {
      title: 'string',
      length: 'number'
    }
  },
  Album: {
    properties: {
      title: 'string',
      songs: 'Songs.Song[]'
    }
  }
};
tools.expandedForm(typesContext['Album'], typesContext, function(err, expanded) {
  // expanded contains the computed expanded form
  console.log(JSON.stringify(expanded,null,2));
});
```

#### Result
```json
{
  "properties": {
    "title": {
      "type": "string",
      "required": true
    },
    "songs": {
      "type": "array",
      "items": {
        "properties": {
          "title": {
            "type": "string",
            "required": true
          },
          "length": {
            "type": "number",
            "required": true
          }
        },
        "additionalProperties": true,
        "type": "object",
        "required": true
      },
      "required": true
    }
  },
  "additionalProperties": true,
  "type": "object",
  "required": true
}
```

## RAML type canonical form

The canonical form computes inheritance and pushes unions to the top level of the type structure of an expanded RAML type. It is described in the [documentation section](doc/algorithms.md) of this repository.

### Usage

The Node.js version of the canonical form function is defined in the `canonicalForm` function of the library module.
It accepts a JSON in-memory representation of an expanded RAML type and an optional callback function or options object. It returns the canonical form or an exception. The following options are supported:

* `callback`: Provides a callback function via the options object.
* `hoistUnions` (default: `true`): Controls whether canonicalization should hoist unions to the top level of the type form. When enabled, `union` can only appear as the top-level type, and the associated type alternatives are the permutation of any nested unions in the input type. When disabled, unions remain nested.

#### Sync API
```js
const tools = require('datatype-expansion');

const typesContext = {
  SimpleUnion: {
    properties: {
      a: 'string',
      b: 'number | string'
    }
  },
};
const expanded = tools.expandedForm(typesContext['SimpleUnion'], typesContext)
const canonical = tools.canonicalForm(expanded)
console.log(JSON.stringify(canonical,null,2));
```

#### Callback API
```js
const tools = require('datatype-expansion');

const typesContext = {
  SimpleUnion: {
    properties: {
      a: 'string',
      b: 'number | string'
    }
  },
};
tools.expandedForm(typesContext['Songs.Album'], typesContext, function(err, expanded) {
   tools.canonicalForm(expanded, function(err, canonical) {
    // canonical contains the computed canonical form
    console.log(canonical);
   });
});
```

#### Result
```json
{
  "type": "union",
  "additionalProperties": true,
  "anyOf": [
    {
      "properties": {
        "a": {
          "type": "string",
          "required": true
        },
        "b": {
          "type": "number",
          "required": true
        }
      },
      "type": "object",
      "additionalProperties": true
    },
    {
      "properties": {
        "a": {
          "type": "string",
          "required": true
        },
        "b": {
          "type": "string",
          "required": true
        }
      },
      "type": "object",
      "additionalProperties": true
    }
  ]
}
```

## Browser usage

Include it via unpkg ( if you don't use a bundler like webpack )
```html
<script src="https://unpkg.com/datatype-expansion"></script>
```

It gets exported as `expansion`
```js
expansion.expandedForm('string', {})
```

## Running tests

Tests for the library can be run using:

``` shell
$ npm run test
```

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