{"id":20672722,"url":"https://github.com/nas5w/random-word-slugs","last_synced_at":"2025-04-09T14:06:46.325Z","repository":{"id":38830086,"uuid":"328475753","full_name":"nas5w/random-word-slugs","owner":"nas5w","description":"A handy utility to create those random word slugs (e.g., generous-pink-biscuit) you see all over the place.","archived":false,"fork":false,"pushed_at":"2023-07-24T08:25:52.000Z","size":132,"stargazers_count":71,"open_issues_count":9,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T07:53:53.239Z","etag":null,"topics":["javascript","random","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/random-word-slugs","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/nas5w.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2021-01-10T20:44:49.000Z","updated_at":"2025-02-26T18:53:57.000Z","dependencies_parsed_at":"2024-06-18T15:13:25.331Z","dependency_job_id":"afd8ba0a-8ccf-4e94-83ae-cc70cfb599a7","html_url":"https://github.com/nas5w/random-word-slugs","commit_stats":{"total_commits":39,"total_committers":5,"mean_commits":7.8,"dds":"0.28205128205128205","last_synced_commit":"063db9fa1aa76947c2667ba739d2f1575aeeb624"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nas5w%2Frandom-word-slugs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nas5w%2Frandom-word-slugs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nas5w%2Frandom-word-slugs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nas5w%2Frandom-word-slugs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nas5w","download_url":"https://codeload.github.com/nas5w/random-word-slugs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054227,"owners_count":21039952,"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":["javascript","random","typescript"],"created_at":"2024-11-16T20:38:36.836Z","updated_at":"2025-04-09T14:06:46.284Z","avatar_url":"https://github.com/nas5w.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Random Word Slugs\n\nA handy utility to create those random word slugs (e.g., `generous-pink-biscuit`) you see all over the place.\n\n![run](https://github.com/nas5w/random-word-slugs/actions/workflows/test.yml/badge.svg)\n[![Codecov Status](https://codecov.io/gh/nas5w/random-word-slugs/branch/master/graph/badge.svg)](https://codecov.io/gh/nas5w/random-word-slugs/branch/master)\n\n\u003chr /\u003e\n\n# Installation\n\nInstall with npm\n\n```bash\nnpm i random-word-slugs\n```\n\nInstall with yarn\n\n```bash\nyarn add random-word-slugs\n```\n\n# Usage\n\nThe `random-word-slugs` package can be used without any parameters and defaults to a three-word, kebab-cased slug. **Currently, the default configuration has 30,021,543 unique slug combinations**.\n\n```javascript\nimport { generateSlug } from \"random-word-slugs\";\n\nconst slug = generateSlug();\nconsole.log(slug);\n// \"elegant-green-coat\"\n```\n\nThe `generateSlug` function takes up to two arguments. The first argument is the `numberOfWords` in the slug (defaulting to three) and the second argument is the package `options`. The following example makes use of both parameters and provides an option to title-case the output:\n\n```javascript\nconst slug = generateSlug(4, { format: \"title\" });\nconsole.log(slug);\n// \"Elegant Happy Green Coat\"\n```\n\n# Available Options\n\nThe `options` object can have any partial set of the following key/value pairs:\n\n```\n{\n  format: \"kebab\" | \"camel\" | \"sentence\" | \"lower\" | \"title\",\n  partsOfSpeech: (\"adjective\" | \"noun\")[],\n  categories: {\n    adjective: (\"color\" | \"appearance\" | etc...)[],\n    noun: (\"people\" | \"animals\" | etc...)[]\n  }\n}\n```\n\nNote that, if provided, `partsOfSpeech` must be an array the same length as the number of words you're requesting. If using Typescript, the compiler will check this for you.\n\nAn example of a completed `options` object might look like this for a three-word slug:\n\n```javascript\nconst options = {\n  format: \"camel\",\n  partsOfSpeech: [\"adjective\", \"noun\", \"adjective\"],\n  categories: {\n    adjective: [\"color\", \"appearance\"],\n    noun: [\"animals\"],\n  },\n};\n```\n\nBased on these options, our output might look something like `blueBearTall`.\n\n# Typescript Support for Options\n\nThe package exposes a `RandomWordOptions\u003cN\u003e` type, with `N` being the number of words in the slug. If you want to use this type to specify an options object, it might look something like this (although a `Partial` options object is certainly allowed and probably more common):\n\n```typescript\nimport { RandomWordOptions } from \"random-word-slugs\";\n\nconst options: RandomWordOptions\u003c3\u003e = {\n  format: \"title\",\n  categories: {\n    noun: [\"animals\", \"place\"],\n    adjective: [\"color\", \"personality\"],\n  },\n  partsOfSpeech: [\"adjective\", \"noun\", \"adjective\"],\n};\n```\n\nImportantly, the generic `3` here will enforce `partsOfSpeech` being a three-element tuple.\n\n# Categories\n\nThe `categories` option allows you to generate your random slug from a subset of categories. Perhaps you only want colorful animals! You can specify one or many categories for the adjectives and nouns that comprise your random slug. The following is a list of categories currently in the repository:\n\nAdjective Categories:\n\n- appearance\n- color\n- condition\n- personality\n- quantity\n- shapes\n- size\n- sounds\n- taste\n- time\n- touch\n\nNoun Categories:\n\n- animals\n- business\n- education\n- family\n- food\n- health\n- media\n- people\n- place\n- profession\n- religion\n- science\n- sports\n- technology\n- thing\n- time\n- transportation\n\n# Assessing the Combinatorics\n\nWhen using the package, you might be curious about how many different slug combinations exist. The package exposes a function to help with this called `totalUniqueSlugs`. This function can be used without arguments and will assume a three-slug `adjective-adjective-noun` format:\n\n```javascript\nimport { totalUniqueSlugs } from \"random-word-slugs\";\n\nconst totalSlugs = totalUniqueSlugs();\nconsole.log(totalSlugs);\n// 100000\n```\n\n**Note:** The `100000` number shown here is just an example and not a representation of the total number of slugs in the package at any moment (that evolves as words are added).\n\nYou can also assess the combinatoric space if you have a different number of words, word ordering, or a subset of categories. In the following example, we'll assume a four-word slug, in the order `adjective-noun-adjective-noun`, with only color adjectives and animal nouns:\n\n```javascript\nimport { totalUniqueSlugs } from \"random-word-slugs\";\n\nconst totalSlugs = totalUniqueSlugs(4, {\n  partsOfSpeech: [\"adjective\", \"noun\", \"adjective\", \"noun\"],\n  categories: {\n    adjective: [\"color\"],\n    noun: [\"animals\"],\n  },\n});\nconsole.log(totalSlugs);\n// 1000\n```\n\nAgain, this `1000` is just an example. Importantly, this could help you determine that you're not comfortable with this limited combinatoric space and you can choose to add additional categories.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnas5w%2Frandom-word-slugs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnas5w%2Frandom-word-slugs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnas5w%2Frandom-word-slugs/lists"}