Give the NPM package some love (badges#2200)

chris48s · web-flow · commit 6fc8744babf3 · 2018-10-30T18:34:04.000Z
* define a public interface for NPM package
* move check-node-version to dependencies
* add missing file to package
* update docs
* bump version
* add gh-badges option to issue template
* abstract text measuring from users
* add a DocBlock for BadgeFactory.create()
diff --git a/.github/ISSUE_TEMPLATE/1_Bug_report.md b/.github/ISSUE_TEMPLATE/1_Bug_report.md
@@ -4,9 +4,10 @@ about: Report errors and problems
 
 ---
 
-Are you experiencing this issue on shields.io or your own instance?
- - [ ] shields.io
- - [ ] My instance
+Are you experiencing an issue with...
+ - [ ] [shields.io](https://shields.io/#/)
+ - [ ] My own instance
+ - [ ] [gh-badges NPM package](https://www.npmjs.com/package/gh-badges)
 
 :beetle: **Description**
 <!-- A clear and concise description of the problem. -->
diff --git a/README.md b/README.md
@@ -88,28 +88,24 @@ badge build passed :green .png > mybadge.png
 ```
 
 ```js
-const badge = require('gh-badges')
+const { BadgeFactory } = require('gh-badges')
+
+const bf = new BadgeFactory({ fontPath: '/path/to/Verdana.ttf' })
 
-// Optional step, to have accurate text width computation.
 const format = {
   text: ['build', 'passed'],
   colorscheme: 'green',
   template: 'flat',
 }
 
-badge.loadFont('/path/to/Verdana.ttf', err => {
-  badge(format, (svg, err) => {
-    // svg is a string containing your badge
-  })})
+const svg = bf.create(format)
 ```
 
 View the [documentation for gh-badges][gh-badges doc].
 
-**Note:** The badge library was last released in 2016.
-
 [![npm version](http://img.shields.io/npm/v/gh-badges.svg)](https://npmjs.org/package/gh-badges)
 
-[gh-badges doc]: doc/gh-badges.md
+[gh-badges doc]: https://github.com/badges/shields/blob/master/doc/gh-badges.md
 
 
 Development
diff --git a/doc/gh-badges.md b/doc/gh-badges.md
@@ -49,3 +49,30 @@ same dark grey, so you can rely on that default value by not providing a
 You can also use the `"colorA"` and `"colorB"` fields directly in the badges if
 you don't want to make a color scheme for it. In that case, remove the
 `"colorscheme"` field altogether.
+
+Text Width Computation
+----------------------
+
+`BadgeFactory`'s constructor takes an optional boolean
+`precomputeWidths` parameter which defaults to `false`.
+
+Pre-computing the font width table adds some overhead to constructing the
+`BadgeFactory` object (so will slow down generation of a single image),
+but will speed up each badge generation if you are creating a lot of images.
+As a rule of thumb:
+
+If you are generating just one image, use:
+
+```js
+const bf = new BadgeFactory(
+    { fontPath: '/path/to/Verdana.ttf' }
+)
+```
+
+If you are generating many images with a single instance of `BadgeFactory`:
+
+```js
+const bf = new BadgeFactory(
+    { fontPath: '/path/to/Verdana.ttf', precomputeWidths: true }
+)
+```
diff --git a/lib/gh-badges.js b/lib/gh-badges.js
@@ -0,0 +1,33 @@
+'use strict'
+
+const { makeBadge } = require('./make-badge')
+const { PDFKitTextMeasurer, QuickTextMeasurer } = require('./text-measurer')
+
+class BadgeFactory {
+  constructor({ fontPath, fallbackFontPath, precomputeWidths = false }) {
+    this.measurer = precomputeWidths
+      ? new QuickTextMeasurer(fontPath, fallbackFontPath)
+      : new PDFKitTextMeasurer(fontPath, fallbackFontPath)
+  }
+
+  /**
+   * Create a badge
+   *
+   * @param {object} format - Object specifying badge data
+   * @param {string[]} format.text
+   * @param {string} format.colorscheme
+   * @param {string} format.colorA
+   * @param {string} format.colorB
+   * @param {string} format.format
+   * @param {string} format.template
+   * @return {string} Badge in SVG or JSON format
+   * @see https://github.com/badges/shields/blob/master/doc/gh-badges.md
+   */
+  create(format) {
+    return makeBadge(this.measurer, format)
+  }
+}
+
+module.exports = {
+  BadgeFactory,
+}
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gh-badges",
-  "version": "1.3.0",
+  "version": "2.0.0-beta1",
   "description": "Official Shields.io badge library.",
   "keywords": [
     "GitHub",
@@ -16,14 +16,15 @@
   },
   "license": "CC0-1.0",
   "author": "Thaddée Tyl <thaddee.tyl@gmail.com>",
-  "main": "lib/make-badge.js",
+  "main": "lib/gh-badges.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/badges/shields"
   },
   "dependencies": {
     "camp": "~17.2.1",
     "chalk": "^2.4.1",
+    "check-node-version": "^3.1.0",
     "chrome-web-store-item-property": "~1.1.2",
     "dot": "~1.1.2",
     "emojic": "^1.1.14",
@@ -113,6 +114,7 @@
     "lib/lru-cache.js",
     "lib/text-measurer.js",
     "lib/svg-to-img.js",
+    "lib/defaults.js",
     "templates",
     "logo"
   ],
@@ -127,7 +129,6 @@
     "chai-as-promised": "^7.1.1",
     "chai-string": "^1.4.0",
     "chainsmoker": "^0.1.0",
-    "check-node-version": "^3.1.0",
     "child-process-promise": "^2.2.1",
     "classnames": "^2.2.5",
     "concurrently": "^4.0.1",
