# commonform-load-components

> replace components with the right Common Forms

Latest version **4.0.1** (published 2022-06-06) · BlueOak-1.0.0 license · 0 weekly downloads

## Install

```sh
npm install commonform-load-components
pnpm add commonform-load-components
yarn add commonform-load-components
bun add commonform-load-components
```

## 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 | 4.0.1 |
| Published | 2022-06-06 |
| First published | 2018-01-18 |
| Weekly downloads | 0 |
| License | BlueOak-1.0.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 11.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Kyle E. Mitchell |
| Maintainers | kemitchell |

## Links

- npm: https://www.npmjs.com/package/commonform-load-components
- Repository: https://github.com/commonform/commonform-load-components
- Homepage: https://github.com/commonform/commonform-load-components#readme
- Issues: https://github.com/commonform/commonform-load-components/issues
- npm.io page: https://npm.io/package/commonform-load-components

## Dependencies (7)

- [once](https://npm.io/package/once.md) ^1.4.0
- [simple-concat](https://npm.io/package/simple-concat.md) ^1.0.1
- [commonform-hash](https://npm.io/package/commonform-hash.md) ^1.0.0
- [json-parse-errback](https://npm.io/package/json-parse-errback.md) ^2.0.1
- [run-parallel-limit](https://npm.io/package/run-parallel-limit.md) ^1.0.3
- [commonform-predicate](https://npm.io/package/commonform-predicate.md) ^4.0.0
- [commonform-substitute](https://npm.io/package/commonform-substitute.md) ^1.0.0

## Recent versions

- 4.0.1 (latest) — 2022-06-06
- 4.0.0 — 2022-06-05
- 3.0.0 — 2022-06-05
- 2.1.0 — 2020-05-01
- 2.0.0 — 2020-04-24
- 1.3.2 — 2020-04-18
- 1.3.1 — 2018-06-04
- 1.3.0 — 2018-05-29
- 1.2.2 — 2018-05-28
- 1.2.1 — 2018-05-28
- 1.2.0 — 2018-05-28
- 1.1.0 — 2018-01-28
- 1.0.5 — 2018-01-19
- 1.0.3 — 2018-01-18
- 1.0.2 — 2018-01-18
- … 2 more at https://npm.io/package/commonform-load-components/versions

## README

replace components with the right Common Forms

```javascript
var assert = require('assert')
var loadComponents = require('commonform-load-components')

// The URL of the component we'll be using.
var toyDisclaimerURL = 'https://example.com/toy-disclaimer'
// The version we'll be referencing.
var version = '1.0.0'

// The component form we'll be incorporating by reference.
var toyDisclaimerForm = {
  content: [
    'Except under ', { reference: 'Warranties' },
    ', the ', { use: 'Seller' },
    ' disclaims all liability to the ', { use: 'Buyer' },
    ' related to the ', { use: 'Product' }, '.'
  ]
}

// A reference to the component, as it might appear in a Common Form.
var toyDisclaimerReference = {
  component: toyDisclaimerURL,
  version,
  substitutions: {
    terms: {
      Seller: 'Vendor',
      Buyer: 'Customer',
      Product: 'Software'
    },
    headings: {
      Warranties: 'Quality Assurance'
    }
  }
}

// The component form with all terms and headings substitutions applied.
var toyDisclaimerSubstituted = {
  content: [
    'Except under ', { reference: 'Quality Assurance' /* was Warranties */},
    ', the ', { use: 'Vendor' /* was Seller */},
    ' disclaims all liability to the ', { use: 'Customer' /* was Buyer */},
    ' related to the ', { use: 'Software' /* was Product */}, '.'
  ]
}

// The component record that would be stored on example.com.
var toyDisclaimerComponent = {
  publisher: 'Example Publisher',
  name: 'Legal Action Definition',
  version,
  form: toyDisclaimerForm
}

var cache

loadComponents(
  { content: [toyDisclaimerReference] },
  // The cache option permits caching of queries:
  {
    cache: (function() {
      var componentsCache = {}
      componentsCache[toyDisclaimerURL + '/' + version + '.json'] = toyDisclaimerComponent
      cache = {
        get: function (url, callback) {
          callback(null, componentsCache[url] || false)
        },
        put: function (url, component, callback) {
          componentsCache[url] = component
          callback()
        }
      }
      return cache
    })()
  },
  function (error, loaded) {
    assert.ifError(error)
    assert.deepStrictEqual(
      loaded,
      { content: [{ form: toyDisclaimerSubstituted }] }
    )
  }
)
```

The `markLoaded` option will add metadata to loaded forms:

```javascript
loadComponents(
  { content: [ toyDisclaimerReference ] },
  { markLoaded: true, cache },
  function (error, loaded) {
    assert.ifError(error)
    assert.deepStrictEqual(
      loaded,
      {
        content: [
          {
            form: toyDisclaimerSubstituted,
            reference: toyDisclaimerReference,
            component: toyDisclaimerComponent
          }
        ]
      }
    )
  }
)
```


The `hostnames` option array limits components to those from the given array:

```javascript
loadComponents(
  {
    content: [
      {
        component: 'https://example.com/component',
        version: '1.0.0',
        substitutions: { terms: {}, headings: {} }
      }
    ]
  },
  { hostnames: ['other.org'] },
  function (error) {
    assert(error)
    assert.equal(
      error.message, 'unauthorized hostname: example.com'
    )
    assert.equal(error.hostname, 'example.com')
  }
)
```

The function will yield an error when a component tries to incorporate itself:

```javascript
var cyclicalURL = 'https://example.com/cyclical'
var cyclical = {
  component: cyclicalURL,
  version: '1.0.0',
  substitutions: { terms: {}, headings: {} }
}

loadComponents(
  { content: [cyclical] },
  {
    cache: {
      get: function (url, callback) {
        if (url === cyclicalURL + '/1.0.0.json') {
          callback(null, {
            publisher: 'Example',
            name: 'Cyclical Component',
            version: '1.0.0',
            form: { content: [cyclical] }
          })
        } else {
          callback(null, false)
        }
      }
    }
  },
  function (error) {
    assert.equal(error.message, 'cycle')
    assert(typeof error.digest === 'string')
  }
)
```

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