{"id":22218575,"url":"https://github.com/megahertz/package-options","last_synced_at":"2025-03-25T07:22:54.154Z","repository":{"id":57317727,"uuid":"212432061","full_name":"megahertz/package-options","owner":"megahertz","description":"The single point to load options for your node package","archived":false,"fork":false,"pushed_at":"2020-02-16T08:07:47.000Z","size":68,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-16T19:55:25.458Z","etag":null,"topics":["args","cli","command-line","config","environment","file","module","options","package"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/megahertz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-02T20:11:07.000Z","updated_at":"2023-03-17T12:19:18.000Z","dependencies_parsed_at":"2022-08-25T20:40:27.871Z","dependency_job_id":null,"html_url":"https://github.com/megahertz/package-options","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megahertz%2Fpackage-options","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megahertz%2Fpackage-options/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megahertz%2Fpackage-options/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megahertz%2Fpackage-options/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/megahertz","download_url":"https://codeload.github.com/megahertz/package-options/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245415612,"owners_count":20611577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["args","cli","command-line","config","environment","file","module","options","package"],"created_at":"2024-12-02T22:27:10.947Z","updated_at":"2025-03-25T07:22:54.119Z","avatar_url":"https://github.com/megahertz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# package-options\n[![Build Status](https://travis-ci.org/megahertz/package-options.svg?branch=master)](https://travis-ci.org/megahertz/package-options)\n[![NPM version](https://badge.fury.io/js/package-options.svg)](https://badge.fury.io/js/package-options)\n[![Dependencies status](https://david-dm.org/megahertz/package-options/status.svg)](https://david-dm.org/megahertz/package-options)\n\nThe single point to load config for your node package\n\nIt reads:\n\n- command line arguments\n- environment variables\n- `package.json`\n- `${yourPackage}.config.json`\n- `${yourPackage}.config.js`\n- other custom sources\n\nFeatures:\n\n- Converts options from CLI and ENV to camelCase\n\n  `--log-level` → `logLevel`; `MY_LOG_LEVEL` → `logLevel`\n  \n- Converts negative flags like\n\n  `--no-log` → `log = false`\n  \n- Converts dot-separated values to object\n\n  `--filter.name John` → `{ filter: { name: 'John' } }`\n  \n- Converts number and boolean parameters to the corresponding type\n  \n\n## Usage\n\n1. Install with [npm](https://npmjs.org/package/package-options):\n\n    npm install -g package-options\n    \n2. Use in your code\n  \n```js\n// $ env MYMODULE_DEBUG=yes mymodule arg1 -a -b 1 -c 1 -c 2\nimport options from 'package-options';\n\nconsole.log(options._); // ['arg1']\nconsole.log(options.a); // true\nconsole.log(options.b); // 1\nconsole.log(options.c); // [1, 2]\nconsole.log(options.debug); // true\n```\n\n### Data sources\nLet's imagine the project of some end-user:\n\n```\nsome-project\n├─┬node_modules\n│ ├─┬mymodule        - the NPM package you're working on\n│ │ └──index.js      - const options = require('package-options');\n│ ├──package-options\n│ └──...\n├──index.js\n└──package.js        - \"dependencies\": { \"mymodule\": \"*\" }\n```\n\n`mymodule` might be installed global instead, in that case the behavior\nis the same\n\nSo, end-user runs `npx mymodule --some-arg 1`. By default, 'package-options':\n- Determines a name of the parent module (`mymodule`).\n- Reads `mymodule` section of `some-project/package.json`\n- Reads `some-project/mymodule.config.json`\n- Reads `some-project/mymodule.config.js`\n- Reads all environment variables which have 'MYMODULE' prefix\n- Reads command lines arguments\n\nIf you want to skip options loading from the default sources:\n\n```js\noptions.reset() // skip loading from default sources\n  .loadCmd()\n  .loadFile('my-custom.config.json');\n```\n\n#### Load options from another sources\n\n- From object\n\n  `options.load({ someOptions: 1 })`\n  \n- From command line\n\n  `options.loadCmd(process.argv.slice(2))`\n  \n  argument `argv` is optional\n  \n- From environment variables\n\n  `options.loadEnv('MY', process.env) // only ENV vars prefixed with 'MY'`\n  `options.loadEnv(['NODE_ENV', 'LOG']) // only exact ENV vars`\n  \n  all arguments are optional\n  \n- From file\n  \n  `options.loadFile('.mymodulerc')`\n  `options.loadFile(['config.js', 'other.mymodule'])`\n  \n  `loadFile()` loads file content from some-project/${fileName}. If there is\n  no such a file, it tries to find it in upper folders. If the second argument\n  is specified, it reads only the data at specified path of data object. JS and\n  JSON files are supported.\n  \n### Read and write options\n\nYou can easily manipulate options:\n\n`console.log(options.someValue)`\n`options.someValue = 2`\n\nThere are helpers `.get()` and `.set()` which allow to easily manipulate\nnested data without existence check:\n\n`options.get('not.existed.key', 'Default value')`\n`options.set('not.existed.key', 'Parent objects will be created')`\n\nTo get a pure JS object contained all loaded options you can call\n`options.toJSON()`\n\n### Better parameters processing\n\n```js\noptions.param('log.level', { // can be applied to a nested parameter\n  alias: 'l',\n  type: 'number', // number, string or boolean\n  default: 2,\n})\n```\n\nAll keys of the second argument are optional.\n\nHere is an shortcut to define parameters with boolean type:\n\n```js\noptions.boolean(['showLine', 'colors']);\n```\n\n### Displaying help text\n\nThe package has a helper which simplifies help printing in CLI. It can:\n - automatically normalize space indents\n - parse command line arguments from help text\n \n```js\noptions.help(`\n  Usage: mymodule [OPTIONS]\n  Options:\n    -f, --file STRING       Input file\n    -l, --log-level NUMBER  Log level 0-5\n        --help              Show this help\n`, helpOptions)\n```\n\nUsing this help text has the same effect as:\n\n```js\noptions\n  .param('file', { alias: 'f', type: 'string' })\n  .param('logLevel', { alias: 'l', type: 'number' })\n```\n\nThe optional second argument of `.help()` may contain the following options:\n\n- `autoShow`: if false, it won't process `--help` CLI argument automatically\n- `paddingBottom`: add n blank lines before the text\n- `paddingLeft`: add n leading spaces\n- `paddingTop`: add n blank lines after the text\n\n### Additional settings\n\n`package-options` has the following options itself, which can be set using \n`options.config(cfg)` method:\n\n- name: Explicitly set parent package name\n- params: You can set parameters here instead of callings `.param()`\n- inferTypes: By default, `package-options` tries to convert parameters from CLI\n  and ENV to the corresponding type, like '2' → 2, 'yes' → true. Set false to\n  disable.\n- projectPath: By default, it uses `process.cwd()` to get the path of the\n  current project (path to `some-project` in the example above). The path\n  is used by `.loadFile()`. If you need to get this path in you code use \n  `options.getProjectPath()`.\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegahertz%2Fpackage-options","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegahertz%2Fpackage-options","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegahertz%2Fpackage-options/lists"}