CocoRoboDesktop/pdf1.js/node_modules/@jsdoc/salty/README.md

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:

1. In the template's publish.js file, find the line or lines that require taffydb. 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');
   

   1. 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');
   

2. If the template has a package.json file that includes taffydb as a dependency, then remove the taffydb dependency.

3. In the template's package.json file, add @jsdoc/salty as a dependency.

4. 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:

1. Non-null, non-undefined values, in standard sort order
2. Null values
3. Explicitly undefined values: key is present, value is undefined
4. 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 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 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 "[p]refered [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!