{"id":34870571,"url":"https://github.com/ioncakephper/commander-pkg-meta","last_synced_at":"2026-04-28T03:07:07.094Z","repository":{"id":325917325,"uuid":"1103880473","full_name":"ioncakephper/commander-pkg-meta","owner":"ioncakephper","description":"A lightweight and robust utility to extract and validate essential metadata from `package.json` properties.","archived":false,"fork":false,"pushed_at":"2025-11-25T15:30:21.000Z","size":76,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-27T07:58:35.843Z","etag":null,"topics":["build-tool","build-utility","cli","cli-helper","graceful-fallback","json","lightweight","metadata","package-json","package-json-reader","robust","semver","validation","version-validation"],"latest_commit_sha":null,"homepage":"","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/ioncakephper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-25T13:09:12.000Z","updated_at":"2025-11-25T15:30:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ioncakephper/commander-pkg-meta","commit_stats":null,"previous_names":["ioncakephper/commander-pkg-meta"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ioncakephper/commander-pkg-meta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fcommander-pkg-meta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fcommander-pkg-meta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fcommander-pkg-meta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fcommander-pkg-meta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioncakephper","download_url":"https://codeload.github.com/ioncakephper/commander-pkg-meta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fcommander-pkg-meta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32364118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["build-tool","build-utility","cli","cli-helper","graceful-fallback","json","lightweight","metadata","package-json","package-json-reader","robust","semver","validation","version-validation"],"created_at":"2025-12-25T23:16:33.598Z","updated_at":"2026-04-28T03:07:07.076Z","avatar_url":"https://github.com/ioncakephper.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# commander-pkg-meta\n\n[![NPM Version](https://img.shields.io/npm/v/commander-pkg-meta.svg)](https://www.npmjs.com/package/commander-pkg-meta)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Codecov](https://codecov.io/gh/ioncakephper/commander-pkg-meta/branch/main/graph/badge.svg)](https://codecov.io/gh/ioncakephper/commander-pkg-meta)\n[![Last Commit](https://img.shields.io/github/last-commit/ioncakephper/commander-pkg-meta.svg)](https://github.com/ioncakephper/commander-pkg-meta/commits/main)\n[![GitHub stars](https://img.shields.io/github/stars/ioncakephper/commander-pkg-meta.svg?style=social)](https://github.com/ioncakephper/commander-pkg-meta/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/ioncakephper/commander-pkg-meta.svg?style=social)](https://github.com/ioncakephper/commander-pkg-meta/network)\n\nA lightweight and robust utility to extract and validate essential metadata from `package.json` properties.\n\n## Description\n\nThis package provides a simple function, `getMetaData`, to reliably extract a package's name, version, and description. It intelligently determines the package name from either the `bin` or `name` field in your `package.json` and ensures the version is a valid semantic version. It provides sensible defaults and console warnings for invalid inputs, making it a dependable tool for CLI applications and build scripts.\n\n## Key Features\n\n- **Intelligent Name Resolution**: Automatically selects the best name from `package.json` `bin` or `name` fields. It prioritizes the `bin` field:\n  - If `bin` is a string, its trimmed value is used.\n  - If `bin` is an object, the trimmed value of its first key is used.\n  - If `bin` is not available or usable, it falls back to the `name` field.\n- **Semantic Version Validation**: Uses `semver` to validate and clean version strings.\n- **Graceful Fallbacks**: Provides sensible default values for missing or invalid fields.\n- **Developer Warnings**: Logs helpful warnings to the console when input data is invalid, preventing silent failures.\n- **Zero Dependencies**: Aside from `semver`, this utility is lightweight and dependency-free.\n\n## Installation\n\n```bash\nnpm install commander-pkg-meta\n```\n\n## Usage\n\nSimply import the `getMetaData` function and pass it an object containing properties from your `package.json`.\n\n```javascript\nconst { getMetaData } = require('commander-pkg-meta');\nconst pkg = require('./package.json');\n\nconst metadata = getMetaData({\n  name: pkg.name,\n  bin: pkg.bin,\n  version: pkg.version,\n  description: pkg.description,\n});\n\nconsole.log(metadata);\n// Example Output:\n// {\n//   name: 'my-cli-tool',\n//   version: '1.2.3',\n//   description: 'A cool command-line tool.'\n// }\n```\n\n### Integration with Commander.js\n\n```javascript\nconst { getMetaData } = require('commander-pkg-meta');\nconst { Command } = require('commander');\n\ntry {\n  const pkg = require('./package.json');\n  const metaData = getMetaData(pkg);\n\n  // program's name, version, and description match those in package.json\n  const program = new Command();\n  program.name(metaData.name).version(metaData.version).description(metadata.description);\n\n  // ...\n} catch (error) {\n  console.error(error);\n}\n```\n\n## API Reference\n\n### `getMetaData(props)`\n\nExtracts and validates metadata from `package.json` properties.\n\n**Parameters:**\n\n- `props` (Object): An object containing properties, typically from a `package.json` file.\n  - `props.name` (string, optional): The package name.\n  - `props.bin` (string | object, optional): The `bin` field. The name is often derived from this for CLI tools.\n  - `props.version` (string, optional): The package version string.\n  - `props.description` (string, optional): The package description.\n\n**Returns:**\n\n- (Object): An object containing the extracted metadata with fallbacks applied.\n  - `name` (string): The resolved package name.\n  - `version` (string): The cleaned semantic version.\n  - `description` (string): The package description.\n\n## Contributing\n\nContributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) to get started.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Fcommander-pkg-meta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioncakephper%2Fcommander-pkg-meta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Fcommander-pkg-meta/lists"}