{"id":50939187,"url":"https://github.com/vltpkg/namethis","last_synced_at":"2026-06-17T12:02:28.984Z","repository":{"id":362380556,"uuid":"611909726","full_name":"vltpkg/namethis","owner":"vltpkg","description":"Check the existence of a package on npmjs.com","archived":false,"fork":false,"pushed_at":"2026-06-03T23:46:03.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-04T02:05:11.738Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/vltpkg.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,"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":"2023-03-09T19:46:53.000Z","updated_at":"2026-06-03T23:46:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vltpkg/namethis","commit_stats":null,"previous_names":["vltpkg/namethis"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vltpkg/namethis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fnamethis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fnamethis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fnamethis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fnamethis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vltpkg","download_url":"https://codeload.github.com/vltpkg/namethis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fnamethis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34447266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"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":[],"created_at":"2026-06-17T12:02:24.688Z","updated_at":"2026-06-17T12:02:28.979Z","avatar_url":"https://github.com/vltpkg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# namethis\n\nCheck whether a package exists on the npm registry.\n\n## Install\n\n```bash\nvlt install namethis\n```\n\n## Usage\n\n### As a module\n\n```ts\nimport exists from \"namethis\";\n\n// returns a boolean by default — easy to use in conditionals\nif (await exists(\"react\")) {\n  console.log(\"react is taken\");\n}\n\nawait exists(\"nonexistent-pkg-abc123\"); // false\nawait exists(\"@my-org/unknown-pkg\"); // true (org exists)\n\n// multiple packages — returns true only if ALL exist\nawait exists([\"react\", \"express\"]); // true\nawait exists([\"react\", \"fake-pkg\"]); // false\n\n// pass { detailed: true } to get the full result object\nconst info = await exists(\"react\", { detailed: true });\n// { exists: true, type: \"package\", url: \"https://www.npmjs.com/package/react\" }\n\nconst scopeInfo = await exists(\"@my-org/pkg\", { detailed: true });\n// { exists: true, type: \"scope\", scope: \"org\", url: \"https://www.npmjs.com/org/my-org\" }\n\n// detailed mode with arrays — returns Map\u003cstring, ExistsResult\u003e\nconst detailed = await exists([\"react\", \"fake\"], { detailed: true });\n\n// custom registry\nawait exists(\"my-pkg\", { registry: \"https://registry.internal.co\" });\n\n// generate synonym-based name variations\nimport { synonyms } from \"namethis\";\n\nconst names = await synonyms(\"fast-logger\");\n// [\"quick-logger\", \"rapid-logger\", \"speedy-logger\", ...]\n\n// check which similar names are taken\nconst taken = await exists(names);\n```\n\n### As a CLI\n\nRun directly without installing:\n\n```bash\nvlx namethis react\n# react: exists (package) https://www.npmjs.com/package/react\n\nvlx namethis @scope/pkg fake-package\n# @scope/pkg: exists (scope: org) https://www.npmjs.com/org/scope\n# fake-package: not found\n```\n\nJSON output with `--view=json`:\n\n```bash\nvlx namethis react express --view=json\n# {\n#   \"react\": { \"exists\": true, \"type\": \"package\", \"url\": \"...\" },\n#   \"express\": { \"exists\": true, \"type\": \"package\", \"url\": \"...\" }\n# }\n```\n\nCheck similar/synonym names:\n\n```bash\nvlx namethis fast-logger --similar\n# fast-logger: exists (package) https://www.npmjs.com/package/fast-logger\n# quick-logger: not found\n# rapid-logger: not found\n# speedy-logger: not found\n# ...\n```\n\n#### CLI Options\n\n```\nUsage: namethis \u003cpackage-name\u003e [...package-names]\n\nOptions:\n  --registry \u003curl\u003e   Use a custom registry (default: https://registry.npmjs.org)\n  --similar          Also check synonym-based variations of each name\n  --view \u003cformat\u003e    Output format: \"json\" for structured JSON (default: human-readable)\n  -h, --help         Show this help message\n```\n\nExit codes:\n- `0` — all queried packages exist\n- `1` — one or more packages do not exist\n\n## Important: Registry-Side Restrictions\n\nEven if `exists()` reports that a name is available, the registry may still reject a publish attempt. npm applies additional server-side validation beyond what can be checked locally, including:\n\n- **Name squatting policies** — names that were previously published (even if later unpublished) may be reserved.\n- **Trademark and moniker rules** — names too similar to existing popular packages can be blocked.\n- **Spam and abuse filters** — automated systems may flag certain names.\n\nThis library validates names against [npm's naming rules](https://github.com/npm/validate-npm-package-name) and checks registry existence, but a successful check is not a guarantee that you will be able to publish under that name.\n\n## API\n\n### `exists(name: string, options?): Promise\u003cboolean\u003e`\n\nReturns `true` if the package or its scope exists on the registry. Names that are invalid per npm's naming rules return `false` immediately without a network request.\n\n### `exists(name: string, { detailed: true }): Promise\u003cExistsResult\u003e`\n\nReturns a detailed result object with type, scope kind, URL, and validation info.\n\n### `exists(names: string[], options?): Promise\u003cboolean\u003e`\n\nChecks multiple packages concurrently. Returns `true` only if all exist.\n\n### `exists(names: string[], { detailed: true }): Promise\u003cMap\u003cstring, ExistsResult\u003e\u003e`\n\nChecks multiple packages concurrently. Returns a `Map` of detailed results.\n\n### `validate(name: string): ValidationResult`\n\nValidates a package name against [npm's naming rules](https://github.com/npm/validate-npm-package-name) without making any network requests.\n\n```ts\nimport { validate } from \"namethis\";\n\nvalidate(\"my-package\");\n// { validForNewPackages: true, validForOldPackages: true }\n\nvalidate(\"My Package!\");\n// {\n//   validForNewPackages: false,\n//   validForOldPackages: false,\n//   errors: [\"name can only contain URL-friendly characters\"],\n//   warnings: [\"name can no longer contain capital letters\", \"name can no longer contain special characters (\\\"~'!()*\\\")\"]\n// }\n```\n\n### `ExistsResult`\n\n```ts\ninterface ExistsResult {\n  exists: boolean;\n  type?: \"package\" | \"scope\";\n  scope?: \"user\" | \"org\";\n  url?: string;\n  validForNewPackages?: boolean;\n  validForOldPackages?: boolean;\n  warnings?: string[];\n  errors?: string[];\n}\n```\n\n| Field | Value | Meaning |\n|-------|-------|---------|\n| `type` | `\"package\"` | A published package was found on the registry |\n| `type` | `\"scope\"` | The package's scope exists (even if the specific package doesn't) |\n| `type` | `undefined` | The package does not exist |\n| `scope` | `\"user\"` | The scope belongs to an individual user |\n| `scope` | `\"org\"` | The scope belongs to an organization |\n| `scope` | `undefined` | Not a scope match (either a direct package or not found) |\n| `url` | `string` | Link to the package or scope on npmjs.com |\n| `validForNewPackages` | `boolean` | Name meets all current npm naming rules |\n| `validForOldPackages` | `boolean` | Name meets legacy npm naming rules (less strict) |\n| `warnings` | `string[]` | Naming issues that prevent new package registration |\n| `errors` | `string[]` | Naming issues that make the name fundamentally invalid |\n\n### `ValidationResult`\n\n```ts\ninterface ValidationResult {\n  validForNewPackages: boolean;\n  validForOldPackages: boolean;\n  warnings?: string[];\n  errors?: string[];\n}\n```\n\n### `synonyms(name: string, options?: SimilarOptions): Promise\u003cstring[]\u003e`\n\nGenerates synonym-based variations of a package name using the [Datamuse API](https://www.datamuse.com/api/). Splits the name on `-` or `_`, finds synonyms for each word part, and recombines them.\n\n#### ExistsOptions\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `registry` | `string` | `https://registry.npmjs.org` | Registry URL to check against |\n| `detailed` | `boolean` | `false` | Return full `ExistsResult` objects instead of booleans |\n\n#### SimilarOptions\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `max` | `number` | `10` | Maximum number of name variations to return (cap: 1000) |\n| `perWord` | `number` | `10` | Synonym candidates to fetch per word part from the API (cap: 1000) |\n\n## Development\n\nThis project uses [vlt](https://docs.vlt.sh) as its package manager.\n\n```bash\nvlt install        # install dependencies\nvlt run build      # compile typescript\nvlt run test       # run tests\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvltpkg%2Fnamethis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvltpkg%2Fnamethis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvltpkg%2Fnamethis/lists"}