Api-ref-bundler NPM

api-ref-bundler

GitHub Workflow Status (with event)

This package provides utils to resolve all external/internal references in Json based API document and bundle/dereference into single document

Works perfectly with API specifications

Features

bundle all external refs in signle document
converts external references into internal
support full and partial dereference
support external '.md' references
support for all kinds of circularity
no concept of resolvers - you are in charge of the whole reading & path parsing process
no parser included - bring your own!
Typescript syntax support out of the box
No dependencies, can be used in nodejs or browser

Installation

npm install api-ref-bundler --save

Usage

Nodejs

import { promises as fs } from 'fs'
import { bundle, dereference } from 'api-ref-bundler'

const resolver = async (sourcePath) => {
  const data = await fs.readFile(path.join(__dirname, "./", sourcePath), "utf8")
  return sourcePath.slice(-3) === ".md" ? data : JSON.parse(data)      
}

// bundle (convert all external refs to internal)
bundle("schema.json", resolver, { ignoreSibling: true }).then(schema => {
  console.log(schema)
}).catch(errors => {
  console.log(errors)
})

const onErrorHook = (msg: string) => {
  throw new Error(msg)
}

// full dereference (remove all refs)
dereference("schema.json", resolver, { hooks: { onError: onErrorHook }}).then(schema => {
  console.log(schema)
}).catch(errors => {
  console.log(errors)
})

// partial dereference (remove all refs in path '/properties/foo')
dereference("schema.json#/properties/foo", resolver).then(foo => {
  console.log(foo)
}).catch(errors => {
  console.log(errors)
})

Bundle options

interface BundleOptions {
  ignoreSibling?: boolean     // ignore $ref sibling content
  hooks?: {
    onError?: (message: string, ctx: BundleContext) => void // error hook
    onRef?: (ref: string, ctx: BundleContext) => void       // ref hook
    onCrawl?: (value: any, ctx: BundleContext) => void      // node crawl hook
    onExit?: (value: any, ctx: BundleContext) => void      // node crawl exit hook
  }
}

Dereference options

interface DereferenceOptions {
  ignoreSibling?: boolean   // ignore $ref sibling content
  fullCrawl?: boolean       // crawl all nodes includin cached
  enableCircular?: boolean  // convert circular $refs to nodes
  hooks?: {
    onError?: (message: string, ctx: DereferenceContext) => void  // error hook
    onRef?: (ref: string, ctx: DereferenceContext) => void        // ref hook
    onCrawl?: (value: any, ctx: DereferenceContext) => void       // node crawl hook
    onExit?: (value: any, ctx: DereferenceContext) => void       // node crawl exit hook
    onCycle?: (ref: string, ctx: DereferenceContext) => void      // cycle refs hook
  }
}

Browsers

A browser version of api-ref-bundler is also available via CDN:

<script src="https://cdn.jsdelivr.net/npm/api-ref-bundler@latest/browser/api-ref-bundler.es.js"></script>
<script src="https://cdn.jsdelivr.net/npm/api-ref-bundler@latest/browser/api-ref-bundler.umd.js"></script>

Reference api-ref-bundler.min.js in your HTML and use the global variable ApiRefBundler.

<script>
  const resolver = async (sourcePath) => {
    const data = await fetch(sourcePath)
    return sourcePath.slice(-3) === ".md" ? data.text() : data.json()
  }

  ApiRefBundler.bundle("http://example.com/schema", resolver).then(schema => {
    console.log(schema)
  }).catch(errors => {
    console.log(errors)
  })  
</script>

Contributing

When contributing, keep in mind that it is an objective of api-ref-bundler to have no package dependencies. This may change in the future, but for now, no-dependencies.

Please run the unit tests before submitting your PR: npm test. Hopefully your PR includes additional unit tests to illustrate your change/modification!