Gulp plugin for synchronizing JSON file key structures against a primary source
This plugin can synchronize the key structures of JSON files. It must be provided a 'source of truth', or primary filename. For each directory it encounters, the plugin will make all JSON files present conform to that directory's primary file's key structure. It is recursive, so it handles nested key structures as one would expect.
- It does not synchronize values. It only synchronizes keys.
- It cannot synchronize files across different directories.
- It will not synchronize array structures, including objects inside arrays. Arrays are treated as primitives; only objects are recursed and processed.
This plugin has no relation to grunt-sync-json.
MIT License (Expat)
Given these files:
a.json
{
"key_one": "value",
"key_two": 42,
"nested": {
"key": "nested value"
}
}
b.json
{
"key_two": 100,
"nested": {
"key": "different value",
"other_key": "other value"
}
}
Running the plugin with a.json as the primary file will change b.json to the following:
{
"key_one": "value",
"key_two": 100,
"nested": {
"key": "different value"
}
}
To make all JSON files within the cwd conform to an 'en.json' sibling file:
var gulp = require('gulp');
var syncJSON = require('gulp-sync-json');
gulp.task('sync-json', function() {
return gulp.src('./**/*.json')
.pipe(syncJSON('en.json'))
.pipe(gulp.dest('./'));
});
syncJSON(primaryFile: string, options?: {
report?: boolean,
errorOnReportFail?: boolean,
spaces?: number,
verbose?: boolean
})
A filename, or the basename portion of a path, that is the source of truth for key structure for every other JSON file in the directory
An optional options object. The following properties are supported; all are optional:
report
- Defaultfalse
. If set totrue
, the plugin will audit files instead of changing them on the filesystem. Key mismatches are treated as errors and (almost) all errors are supressed and collected instead of being emitted onto the stream as they occur. If the audit finds anything it will log everything out at the enderrorOnReportFail
- Defaultfalse
. If set totrue
, the plugin will emit an error onto the stream ifreport
mode finds anything. Since this causes gulp to exit with a non-zero exit code, it's possible to fail a CI/build step with this. The error is emitted after auditing all files in the stream, and after logging the report output. Has no effect ifreport
isfalse
spaces
- Default4
. How many spaces to use when formatting JSON. Passed directly to JSON.stringifyverbose
- Defaultfalse
. If set totrue
, the plugin will log out a summary of key additions and removals as it processes each file
- When filling in a new key, the plugin will use the value from the primary file
- When the plugin encounters a key not present in the primary file, it will remove it
- If a key is present in both a source and target file but the value types do not match, the plugin will emit an error with the file, key, and types
- The plugin only cares about files in directories with both a primary file and other files present. Any files in the stream that aren't in such a directory are piped through untouched
- For files it does care about, the plugin will emit an error when it encounters invalid JSON, whether in report mode or not. There are a couple gulp plugins already available for linting JSON, which can sit in front of this plugin on the stream
Need to handle line endings differently? Pipe the results through gulp-eol.