Skip to content

Loading and Validating Decisions

Setup

Dependencies

The following packages are required:

Terminal window
npm install @noodlestan/designer-functions @noodlestan/designer-schemas

Decision data

Populate your design decisions data source.

As illustrated in the Capturing Design Decisions guide, you can simply create one or more JSON files anywhere in your project.

  • Directorydata/
    • Directorydecisions/
      • color.json
      • space.json

Validation input schemas

Add a script to load decisions and print eventual validation errors.

  • Directorydata/
  • Directoryscripts
    • validate-decisions.js

We will use the all-in-one createDecisionLoader() providing it with:

src/scripts/validate-decisions.js
import path from 'path';
import { createDecisionLoader, formatValidationError } from '@noodlestan/designer-functions';
import { DECISION_SCHEMAS } from '@noodlestan/designer-schemas';
const DATA_PATH = path.resolve('./data/decisions');
const loader = createDecisionLoader(
[DECISION_SCHEMAS],
[DATA_PATH],
async (moduleName: string) => `../../../node_modules/${moduleName}`,
);

The loader returns a populated decision store asynchronously.

We can use this store to inspect validation errors.

src/scripts/validate-decisions.js
const loadDecisions = async () => {
const store = await loader();
if (store.hasErrors()) {
store.storeErrors().forEach(({ msg, error }) => console.error(msg, error));
store.validationErrors().forEach(error => console.error(formatValidationError(error)));
}
const records = store.records();
const errors = store.storeErrors().length;
const validationErrors = store.validationErrors().length;
records.forEach(record => console.info(record));
console.info(`🐘 ${records.length} records, ${errors} errors, ${validationErrors} warnings`);
};
loadDecisions();

You can run this directly from the command line:

Terminal window
node scripts/build-decisions.js

The output should look something like:

...
{
model: 'color-srgb-hue-value/explicit',
name: 'Brand Pink Hue',
description: 'Hue component of Brand Pink color',
params: {
value: 336
}
}
🐘 4 records, 0 errors, 0 warnings

In case of validation errors these will be printed using the formatValidationError() formatter.

For instance, if we delete the param attribute from a couple of decision input records:

🟨 Decision Pink Palette (required) must have required property 'params'
🟨 Brand Pink Hue (required) must have required property 'params'
🐘 4 records, 0 errors, 2 warnings

Inspecting and validating decision values

Schema validation does not check for data errors such as

  • missing references between decisions
  • color values out of range

These values are only resolved on-demand.

To show all errors you can use the getDecisionStatus() and formatDecision() utility functions.

src/scripts/validate-decisions.js
import { formatDecision, getDecisionStatus } from '@noodlestan/designer-functions';
records.forEach(record => {
const status = getDecisionStatus(store, record);
console.info(formatDecision(status));
});

In the following example output, using formatDecision() default options, the reference error is expanded after the value.

🐘 4 records, 0 errors, 0 warnings
🟩 | Pink Palette | color-set/anchored | [8] |
🟩 | Space Unit | space-value/explicit | 5px |
🟥 | Action Contrast Color | color-value/explicit | false | 1 errors |
💥 Decision "Action Contrast Color" ...
🟩 | Layout Space Scale | space-scale/explicit | [6] |

You can customize the output by providing a second argument to formatDecision() specifying which columns should be printed and in which order.

The following values are accepted:

  • status
  • uuid
  • name
  • model
  • value
  • error-count

Additionally, the following two items - when provided in whatever order - determine how status and errors are displayed:

  • status-colors - print 🟩/🟥 (when absent, prints -/X instead)
  • error-details - when present, eventual errors are show in full after each decision

If you wish to filter out decisions that produce valid values, and inspect only the errors, you can adjust your script to the following:

records.forEach(record => {
const status = getDecisionStatus(store, record);
if (status.hasErrors) {
console.error(formatDecision(status, ['error-details']));
}
});

Next steps

The next guides provide step by step instructions on practical uses cases for your decision data:

See Also