@jsdoc/salty v0.2.8
Salty
Salty is a drop-in replacement for (some of) TaffyDB. It supports only the TaffyDB features that JSDoc has historically used.
Why Salty?
TaffyDB lets you query an array of objects, similar to the way you would query a database. JSDoc 3.x used TaffyDB to manage doclets, or objects that contain information about your code.
Specifically, after JSDoc parsed your code, it passed the doclets to your JSDoc template as a TaffyDB object. The template then used TaffyDB queries to remove unneeded doclets, and to retrieve the doclets that were needed to generate documentation.
Salty exists because TaffyDB is no longer maintained and is the subject of a CVE, causing TaffyDB to be flagged as a security risk. There's no real security risk, but it sure looks like there is.
Also, TaffyDB can't decide what license it uses:
- The README says that TaffyDB uses the 1-clause BSD License.
- The
package.json
file says that TaffyDB uses the 2-clause BSD License. - The
License
file says that TaffyDB uses the MIT License.
By replacing TaffyDB with Salty, which uses the Apache 2.0 License, JSDoc resolved the purported security issue and the licensing uncertainty.
Use Salty in a JSDoc template
Starting in version 4.0.0, JSDoc no longer uses the taffydb
package as a dependency. If you use a
JSDoc template that comes with JSDoc 4.0.0 or later, then you don't need to make any changes to the
template.
Otherwise, your template might use the taffydb
package. After you replace taffydb
with
@jsdoc/salty
, your template should remain compatible with JSDoc 3.x.
To replace taffydb
with @jsdoc/salty
, do the following:
In the template's
publish.js
file, find the line or lines that requiretaffydb
. They should look similar to one of the following:// Old-school, without object destructuring (might use `var` or `let` instead of `const`) const taffy = require('taffydb').taffy; // New-school, with object destructuring const { taffy } = require('taffydb');
Replace
taffydb
with@jsdoc/salty
:// Old-school, without object destructuring const taffy = require('@jsdoc/salty').taffy; // New-school, with object destructuring const { taffy } = require('@jsdoc/salty');
If the template has a
package.json
file that includestaffydb
as a dependency, then remove thetaffydb
dependency.In the template's
package.json
file, add@jsdoc/salty
as a dependency.Run
npm install
in the template directory, then confirm that the template works as expected.
Supported TaffyDB features
Salty supports only the TaffyDB features that have historically been used by JSDoc templates. That means that most TaffyDB functionality is missing.
Specifically, Salty lets you do the following:
Create a database
let db = taffy([{ a: 3 }, { a: 1, b: 'hello' }, { a: 7, b: 2 }]);
Sort items in a database
Items are sorted in place. Salty uses the following sort order, which differs from, but is more predictable than, TaffyDB:
- Non-null, non-undefined values, in standard sort order
- Null values
- Explicitly undefined values: key is present, value is undefined
- Implicitly undefined values: key is not present
// Sort by the `a` property
db.sort('a');
// Sort by the `a` property, then the `b` property
db.sort('a, b');
Get items from a database
// Get array of all items
const emptyMatcher = db().get();
// Get array of items where `a` is either `1` or `3`
const arrayMatcher = db({ a: [1, 3] }).get();
// Get array of items where `a` is `1` and `b` is `hello`
const multiMatcher = db({ a: 1 }, { b: 'hello' }).get();
// Get array of items where `b` is undefined
const undefinedMatcher = db({ b: { isUndefined: true } }).get();
// Get array of items where `b` starts with `he`
const leftMatcher = db({ b: { left: 'he' } }).get();
// Get array of items where `b` ends with `lo`
const rightMatcher = db({ b: { right: 'lo' } }).get();
Get items with a custom query function
Within the query function, this
is bound to the current item. As a result, the custom query
function cannot be an arrow function.
function query() {
return this.a > 1;
}
const items = db(query).get();
// `items` is `[{ a: 3 }, { a: 7, b: 2 }]`
Iterate over items in a database
// Iterate over all items
db().each((item, i) => console.log(`'b' property at index ${i}: ${item.b}`));
// Iterate over items where `b` equals `hello`
db({ b: 'hello' }).each((item) => console.log(`'a' property: ${item.a}`));
Remove items from a database
// Remove items where `a` equals `7`
db({ a: 7 }).remove(); // returns `1` (the number of items removed)
// Remove items where `b` is undefined
db({ b: { isUndefined: true } }).remove(); // returns `1`
// Remove items where `b` is defined
db({ b: { isUndefined: false } }).remove(); // returns `1`
// Remove all items
db().remove();
New features
Salty probably won't gain any new features, ever. It exists solely to meet the requirements of JSDoc.
The exception is if a JSDoc template uses TaffyDB features that aren't available in Salty. If that's the case, create an issue with details about the template you're using and the feature that's missing.
TaffyDB, JSDoc, and security
Is TaffyDB a security risk? And has JSDoc ever used TaffyDB in a way that creates a security risk? The answer to both questions is no.
First, CVE-2019-10790 says that "attackers can use the TaffyDB vulnerability to access any data items in the DB." But JSDoc used TaffyDB only to store data about your JavaScript code. That data is no more sensitive than the code itself.
Also, JSDoc doesn't persist the TaffyDB data to disk. It exists only while JSDoc is running.
Most important of all, TaffyDB doesn't pretend to have any sort of access control. To the contrary,
TaffyDB intentionally makes it very easy to access all of the data in a DB. If your DB is stored
in a variable named db
, then calling db().get()
retrieves all of the data in the DB.
This method is documented as the "prefered sic
method for extracting data." Because you can always access all of the data, it's unclear why a bug
that lets you access some of the data would create a security risk.
So Salty doesn't mitigate a security risk or fix a security issue. However, in general, it's not a good idea to tell people to ignore CVEs; also, it can be difficult to convince your colleagues or employer to ignore a specific CVE. For those reasons, it was worth the trouble to replace TaffyDB.
What's with the name?
It's a play on "saltwater taffy." Hilarious!