{"_id":"@auturge/json-trim","_rev":"1-4de5897e0decc81d8a33f53bc4fb86ba","name":"@auturge/json-trim","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@auturge/json-trim","description":"Copies a json file, trimming out all but a select list of keys.","version":"1.0.0","author":{"name":"auturge"},"license":"MIT","bugs":{"url":"https://github.com/auturge/json-trim/issues"},"homepage":"https://github.com/auturge/json-trim","repository":{"type":"git","url":"git+https://github.com/auturge/json-trim.git"},"engines":{"node":">=12.8.1"},"bin":{"json-trim":"bin/json-trim.js"},"main":"./lib/JsonTrim.js","dependencies":{"@auturge/config-resolver":"^1.0.0","colorette":"^1.2.2","command-line-usage":"^6.1.1","commander":"^7.1.0","is-valid-path":"^0.1.1","fastest-levenshtein":"^1.0.12"},"_id":"@auturge/json-trim@1.0.0","_nodeVersion":"12.18.0","_npmVersion":"6.14.8","dist":{"integrity":"sha512-Oxm1GCaWWg4BtwUOilC+F3ghcCkpkNN1kfxH4AZDJHLC30D8/Pnrlt3C7DpueFvGVOdSJf5WaCSEE03pU1RBKQ==","shasum":"0539b14252cd2b00a9397ec58aec20cf27393f94","tarball":"https://registry.npmjs.org/@auturge/json-trim/-/json-trim-1.0.0.tgz","fileCount":24,"unpackedSize":76973,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgYP3ACRA9TVsSAnZWagAAqLkP/jtgZWEGrtB/1M9wC1DD\n4j8imEm937oXGVJs211z3M0ca+CHC3tSkH69HBExWAsHzOLvIqybGzEUApyY\nkx3BKn5vyecIKdXJ3SkltfmkawEGFdd5+SDfvnNRSm/i4k1s/9NjPFnxLfnY\nNQn7Xp6Tf7LzESZTp0VJgDTBKAM4Hr6ivrtnewukIT/AGSi4CknJAkkLpu7/\nSYsNwzu/yfN6dv0Pv9a+6Ad3PD+ioPbU9BCRgm++n9sk6efTpoKbA2F6oxeW\nw+QdP2oJyBfc6yohNLO4YNG7adWRG6MXdJGoL+Es6wO9HBGdTzWHz0b/Mk0C\nsqW12UYOXRZATKFthazwqBz1tcN6XjVe5xkIXIzJdfKkVfKlAqvGIwzl82Nx\nGyY3PJbCRvXT0QUybpLGJUFpVdOi+u3P/Y0PrSUXvPW0GE6zn2dC63PnZoMb\nxZLq6QUKEQRVTmoNaIKuDH8ZinEDZAlXPtZ24NQbmRYhP15zkxLNR0biBlJ2\nlCtiiQxZoEXRlGcKWVU/OPFSdEyUO3BZAkAFGn1msWS6FvW0VOj8RjfwyDrM\nYxMVSWHp3Ud94LZEyTwwL4oE/lt3y0jTela4GouCvvWZVMwvGKu3bNiBItGB\nzXnznHDblGVsH3ADsaTyL7UIchjAibIt6noYQN/CstHKi3MgUjYCWQiQbU9q\nwduD\r\n=Uplu\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC6kmsULZxbogbRbS+bIuuRRbH6x8Xl5Ul0SsV0VTnJQwIhANs2QzMbJMHe5GyD2Bigx2S5mQHUQ+LULsyB37C9rK8r"}]},"_npmUser":{"name":"curtis.kaler","email":"curt.kaler@gmail.com"},"directories":{},"maintainers":[{"name":"curtis.kaler","email":"curt.kaler@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/json-trim_1.0.0_1616969151562_0.14190078800437855"},"_hasShrinkwrap":false}},"time":{"created":"2021-03-28T22:05:51.373Z","1.0.0":"2021-03-28T22:05:51.732Z","modified":"2022-04-04T16:41:24.863Z"},"maintainers":[{"name":"curtis.kaler","email":"curt.kaler@gmail.com"}],"description":"Copies a json file, trimming out all but a select list of keys.","homepage":"https://github.com/auturge/json-trim","repository":{"type":"git","url":"git+https://github.com/auturge/json-trim.git"},"author":{"name":"auturge"},"bugs":{"url":"https://github.com/auturge/json-trim/issues"},"license":"MIT","readme":"#

auturge/json-trim

\n\n

\n Copies a trimmed version of a json file.\n

\n\n[![License][license-image]][license-url]\n[![npm][npm-badge]][npm-url] [![Build][travis-badge]][travis-url]\n[![Coverage Status][coverage-badge]][coverage-url]\n\n## Table of Contents\n\n---\n\n- [About](#about)\n - [Motivation](#motivation)\n- [How to Install](#how-to-install)\n- [Supported Command-line Arguments](#supported-command-line-arguments)\n- [Common Options](#common-options)\n- [Configuration Files](#configuration-files)\n - [The configuration object](#the-configuration-object)\n- [Examples](#examples)\n\t- [Example: from the command line](#example-from-the-command-line)\n - [Example: a simple config file](#example-simple-config-file)\n - [Example: a more advanced config file](#example-more-advanced-config-file)\n- [Contributing and Internal Documentation](#contributing-and-internal-documentation)\n- [License](#license)\n\n\n\n## About\n\n---\n\nWhen building a JS/TS library, I find that I often want separate versions of my `package.json` for the project source and the finished library. I don't usually want to include my build scripts or devDependencies in the final product, but I also don't want the name, version, or other metadata to be out of sync.\n\n`json-trim` provides a method of easily copying a pared-down version of a json file to another file location.\n\n\n\n### Motivation\n\nFor a specific example, let's pretend that I'm building a new TypeScript library called `@auturge/maximus`, which I plan to publish to a package repository (e.g., the `npm` repository). My development process includes:\n\n1. `lint`, `test`, and `build` (into the `dist` folder),\n2. update and copy relevant files (`package.json`, `README`, `CHANGELOG`, `LICENSE`, etc.) into the `dist` folder,\n3. run some pre-publishing checks, and\n4. publish to the package repository (from the `dist` folder).\n\nTypically, my `dist` folder includes everything that I intend to publish, so the project tends to take this shape:\n\n```none\nmaximus\n├── dist/\n│ ├── package.json\n│ ├── README.md\n│ ├── CHANGELOG.md\n│ ├── LICENSE\n│ ├── maximus.js\n│ └── maximus.d.ts\n│\n├── src/\n│ ├── index.ts\n│ ├── ...\n│\n├── test/\n│ ├── ...\n│\n├── package.json\n├── README.md\n├── CHANGELOG.md\n├── LICENSE\n├── ...\n```\n\n`json-trim` makes step #2 in the process above less cumbersome: it copies the root `package.json` file into the `dist` folder, and removes any keys that I don't want to publish from the copy.\n\n> **NOTE:** I still need to update the `version` property before publishing.\n\nFor example, assume that the root `package.json` looks like this:\n\n```json\n{\n \"name\": \"@auturge/maximus\",\n \"version\": \"1.0.0\",\n \"description\": \"auturge/maximus - does a thing!\",\n \"author\": \"auturge\",\n \"license\": \"MIT\",\n \"bugs\": {\n \"url\": \"https://github.com/auturge/maximus/issues\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/auturge/maximus.git\"\n },\n \"homepage\": \"https://github.com/auturge/maximus\",\n \"main\": \"maximus.js\",\n \"files\": [\n \"README.md\",\n \"CHANGELOG.md\",\n\t...\n ],\n \"engines\": {\n \"node\": \">=12.8.1\"\n },\n \"scripts\": {\n \"build\": \"npm run ~rollup\",\n \"test\": \"npm-run-all ~test:clean ~test:run\",\n ...\n },\n \"oldScripts\": {\n \"build\": \"npm run ~webpack\",\n ...\n },\n \"devDependencies\": {\n \"@auturge/testing\": \"latest\",\n ...\n }\n}\n```\n\nThere are certain portions of this that will not be useful without the source code, which I don't publish to the package registry. In this case, I don't need to publish `\"scripts\"`, `\"oldScripts\"`, or `\"devDependencies\"`... they are helpful during the development process, but would be cruft if included with the distributed library.\n\nSo I want to copy my `package.json`, while trimming out those keys.\n\n\n\n## How to Install\n\n---\n\nThe following commands will install json-trim:\n\n```shell\nnpm install --save-dev @auturge/json-trim\n```\n\nor\n\n```shell\nyarn add @auturge/json-trim --dev\n```\n\n\n\n## Supported Command-Line Arguments\n\n---\n\n`json-trim` allows the following command-line flags and options:\n\n| option | alias | usage | description |\n| :--- | :---: | :--- | :--- |\n| config | -c | `--config ` | Location of the json-trim configuration file, e.g. `./conf/trim.config.js` |\n| destination | -d | `--destination ` | Output location of the file generated by `json-trim`, e.g., `./dist/package.json` |\n| env | | ` --env [=]` | Environment passed to the configuration when it is a function, e.g.,
`dev` or
`prod` or
`prod=dist` |\n| help | -help | `--help` | Displays usage information |\n| keeplist | -k | `--keeplist ` | Space-separated list of json keys to copy, e.g., `name version description` |\n| quiet | -q | `--quiet` | Toggles quiet mode. Will only display errors |\n| source | -s | `--source ` | Input location of the file `json-trim` should copy, e.g., `./package.json` |\n| trimlist | -t | `--trimlist ` | Space-separated list of json keys to exclude (takes precedence over `keeplist`) |\n| verbose | -v | `--verbose` | Toggles verbose mode |\n| version | -ver | `--version` | Gets the current version of `json-trim` |\n\n\n\n## Common Options\n\n---\n\n> _Note that json-trim has a higher precendence for the arguments you use it with than the options set in your configuration file. For instance, if you pass\n> `--env=\"production\"` to json-trim on the command-line, and your configuration file uses `development`, then `production` will be used._\n\n---\n\n### List all of the commands and flags available on the cli\n\n```{shell}\njson-trim --help\n```\n\n### Show help for a single flag\n\n```{shell}\njson-trim --help \n```\n\n### Execute using a configuration file\n\n```{shell}\njson-trim --config ./conf/trim.config.js\n```\n\nThis uses the configuration file at `./conf/trim.config.js`, and does not override any options.\n\n### Execute without using a configuration file\n\n```{shell}\njson-trim --source ./package.json --destination ./dist/package.json --trimlist scripts oldscripts devDependencies\n```\n\nThis\n\n1. copies `./package.json` file to `./dist/package.json`,\n2. trims the `scripts`, `oldScripts`, and `devDependencies` keys out of the copy, and\n3. leaves the original `./package.json` unchanged.\n\n\n\n## Configuration Files\n\n---\n\nDevelopers can specify a configuration file to make `json-trim` usage easier. The config must be an exported javascript function. \n\nIf no config file is specified, `json-trim` will first look for a file in the project root (next to the `./package.json`) called `./trim.config.js`.\n\nIf `json-trim` finds a config file, it will load that configuration, and then override any options with those specified on the command-line.\n\n> **NOTE:** If a config file is specified on the command line, and `json-trim` cannot find that config file, then `json-trim` will fail with an error.\n\n### The Configuration Object\n\nWhen given a json configuration object exported from a config file, `json-trim` considers the following (case-insensitive) keys:\n\n#### source\n\nInput location of the file `json-trim` should copy.\n\n> ```'source': './package.json'```\n\n#### destination\n\nOutput location of the file generated by `json-trim`.\n\n> ```'destination': './dist/package.json'```\n\n#### keeplist [optional]\n\nCase-insensitive String[] array of keys to copy. Will not error if a key is not found.\n\n> ```'keeplist': ['name', 'version', 'description']```\n\n#### trimlist [optional]\n\nCase-insensitive String[] array of keys to exclude (takes precedence over `keeplist`). Will not error if a key is not found.\n\n> ```'trimlist': ['scripts', 'oldscripts', 'devDependencies']```\n\n#### verbose [optional, default: _false_]\n\n> ```'verbose': false```\n\n#### quiet [optional, default: _false_]\n\n> ```'quiet': false```\n\n\n\n## EXAMPLES\n\n---\n\nThe following examples use the structure of the above project (`@auturge/maximus`).\nThe developer can use `json-trim` from the command-line (or a `scripts` entry in the `package.json`), or by specifying the configuration in a config file.\n\n\n\n## EXAMPLE: from the Command-Line\n\n---\n\nSuppose you want the following options:\n\n1. the input file is the `./package.json` in the project root (as described above),\n2. the output file is `./dist/package.json`,\n3. remove the `scripts`, `oldScripts`, and `devDependencies` keys.\n\nYour command-line would look like this:\n\n```{shell}\njson-trim -s ./package.json -d ./dist/package.json -t scripts oldScripts devDependencies\n```\n\n\n## EXAMPLE: simple config file\n\n---\n\nSuppose you want the following options:\n\n1. use a config file at the default location, `./trim.config.js`,\n2. the input file is the `./package.json` in the project root (as described above),\n3. the output file is `./dist/package.json`,\n4. remove the `scripts`, `oldScripts`, and `devDependencies` keys, and\n5. use the default logging options.\n\n### ./trim.config.js\n\n```{JavaScript}\nconst path = require('path');\n\nmodule.exports = () => {\n return {\n 'source': './package.json',\n 'destination': './dist/package.json',\n 'trimlist': ['oldScripts', 'scripts', 'devDependencies']\n }\n}\n```\n\n### command-line\n\n```bash\njson-trim\n```\n\n### result (`./dist/package.json`)\n\n```json\n{\n \"name\": \"@auturge/maximus\",\n \"version\": \"1.0.0\",\n \"description\": \"auturge/maximus - does a thing!\",\n \"author\": \"auturge\",\n \"license\": \"MIT\",\n \"bugs\": {\n \"url\": \"https://github.com/auturge/maximus/issues\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/auturge/maximus.git\"\n },\n \"homepage\": \"https://github.com/auturge/maximus\",\n \"main\": \"maximus.js\",\n \"files\": [\n \"README.md\",\n \"CHANGELOG.md\",\n\t...\n ],\n \"engines\": {\n \"node\": \">=12.8.1\"\n }\n}\n```\n\n\n\n## EXAMPLE: more advanced config file\n\n---\n\nSuppose you want the following options:\n\n1. your `json-trim` config file lives in the `./conf/` directory (e.g., at `./conf/trim.config.js`),\n2. the input file is the `./package.json` in the project root (as described above),\n3. the output file goes into a specific folder depending on which 'environment' you're building:\n - If you're building in `dev` mode, the output file should be `./build/dev/package,json`\n - If you're building in `prod` mode, the output file should be `./build/prod/package,json`\n - If you're building in `dist` mode, the output file should be `./dist/package,json`\n4. keep _only_ the `name`, `version`, and `description` keys, and\n5. to see all the little details of what `json-trim` is doing\n\n### ./conf/trim.config.js\n\n```JavaScript\nconst path = require('path');\n\nmodule.exports = (env) => {\n const isProd = env && env['prod'];\n const isDist = isProd && isProd.toLowerCase() === 'dist';\n\n const SOURCE = './package.json';\n const DESTINATION = isDist\n ? './dist/package.json' \n : './build/{0}/package.json'\n .replace('{0}', isProd ? 'prod' : 'dev')\n \n const config = {\n 'source': path.join(PROJECT_ROOT, SOURCE),\n 'destination': path.join(PROJECT_ROOT, DESTINATION),\n 'keeplist': ['name', 'version', 'description'],\n 'verbose': true\n }\n \n return config;\n}\n```\n\n### command-line (dev)\n\n```bash\njson-trim -c ./conf/trim.config.js -env dev\n```\n\n### command-line (prod)\n\n```bash\njson-trim -c ./conf/trim.config.js -env prod\n```\n\n### command-line (dist)\n\n```bash\njson-trim -c ./conf/trim.config.js -env prod=dist\n```\n\n### result\n\n```json\n{\n \"name\": \"@auturge/maximus\",\n \"version\": \"1.0.0\",\n \"description\": \"auturge/maximus - does a thing!\"\n}\n```\n\n\n\n## Contributing and Internal Documentation\n\n---\n\nThe auturge family welcomes any contributor, small or big. We are happy to elaborate, guide you through the source code and find issues you might want to work on! To get started have a look at our [documentation on contributing][contributing].\n\n\n\n## License\n\n---\n\nDistributed under the MIT license. See [`LICENSE`][license] for more information.\n\n\n\n---\n\n[license]: https://github.com/auturge/json-trim/blob/master/LICENSE\n[license-url]: https://github.com/auturge/auturge/blob/master/LICENSE\n[license-image]: http://img.shields.io/:license-mit-blue.svg?style=flat-square\n[contributing]: https://github.com/auturge/auturge/blob/master/docs/CONTRIBUTING.md\n[npm-badge]: https://img.shields.io/npm/v/@auturge/json-trim.svg\n[npm-url]: https://www.npmjs.com/package/@auturge/json-trim\n[travis-badge]: https://api.travis-ci.com/auturge/json-trim.svg?branch=master\n[travis-url]: https://travis-ci.com/github/auturge/json-trim\n[coverage-badge]: https://coveralls.io/repos/github/auturge/json-trim/badge.svg\n[coverage-url]: https://coveralls.io/github/auturge/json-trim\n","readmeFilename":"README.md"}