stubber-interpolation-pkg

This is the Stubber Interpolation Package, used by services to interpolate a field, specified as a string, from data, which is generally an object.

See the wiki page

The package exports a function called Plugin. The Plugin function returns an object that contains a function called process. This process function takes two parameters, field and data. It then extract variables specified in field from data. See usage example in the Usage section

Building

To update the npm package version, you have to run npm version {{update_type}}. If the package version is x.y.z the following applies:

• npm version major updates x
• npm version minor updates y
• npm version patch updates z

Take a look at npm's semantic versioning to decide what update to apply.

The npm version {{update_type}} command creates a commit on the repo with the updated version number in the package.json file. REMEMBER to push this commit to the repo, or the next person to run npm publish will get an error.

Then run npm publish, which will compress the project and publish it to npm. Files that should not be public should be placed in the .npmigore file.

In summary

npm version {{update_type}} # major, minor, patch
npm publish
git push

Usage

Import the Plugin function, and then call it with the sref_co_host and sref_cc_host values to ensure that stublinks and stuburls point to live/dev.

import { Plugin } from "stubber-interpolation-pkg"

let interpolation = Plugin({
      sref_co_host: config.sref_co?.host,  // "http://sref.co" or http://dev.sref.co",
      sref_cc_host: config.sref_cc?.host, // "http://sref.cc" or http://dev.sref.cc",
      stubby_url_shortener_host: config.stubby_url_shortener?.host // "http://stub.by" or "http://dev.stub.by",
      stubby_url_shortener_security_token: config.stubby_url_shortener?.apikey,
    });

This interpolation can then be exported to use everywhere in the code. This is generally done as a plugin, which can be seen in the stubber-core project.

To use it:

interpolation.process(field, data)

Local Development

The steps below walk through how you would add a new helper.

1. Open the initHandlebars.js file
2. Add a new file in the helpers directory
   • Use an existing helper as a starting point
3. Open the interpolation.test.js file and add at least one test for your helper
4. Run npm run test from the project directory to run the tests.
   • Ensure all tests pass
   • Remember to run npm install first if the run command fails.

Result examples

eg:

"~~stub.number" -> "2022-12-07-1123"
"Hello {{name}}" -> "Hello Abrie"

Various field types are handled as follows:

• Pure strings - eg. "some string" Returned unchanged
• Strings starting with ~~ - eg "~~stub.data.value", value are extracted from data as stub.data.value. This handles bracket notation as well, so the same value could also have been specified as "~~stub[data][value]"
• Integers and floats - eg 2 or 3.14 become strings "2" and "3.14".
• Arrays - eg ["~~stub.data.value", "~~post.uuid"] are run recursively, each element executes interpolate with the element as field and the same data as data. It then returns an array with each element interpolated [stub_data_value, post_uuid]
• Objects - eg {stubnumber: "~~stub.number", d1:{d2:{d3:'~~d1.d2.d3'}}} also run recursively, each nested value is interpolated and the result is returned as an object. {stubnumber: "2022-12-07-1123", d1:{d2:{d3:'d3_value'}}}

Internal workings

The package uses the function handleTildeNotation to handle fields that starts with a double tilde ("~~"). The handleHandlebarsTemplate (lol) function is used to handle fields that contain plain strings or strings that contain handlebar templates, ie. anything with {{}} type syntax.

Handlebar helpers or partials are defined in the src/initHandlebars.js file.