{"id":28236966,"url":"https://github.com/bytebodger/string-contains","last_synced_at":"2025-08-01T07:14:35.759Z","repository":{"id":57167232,"uuid":"341947572","full_name":"bytebodger/string-contains","owner":"bytebodger","description":"A string-inspection utility that is mindful of international (i.e. non-ASCII) letters","archived":false,"fork":false,"pushed_at":"2021-04-10T20:40:27.000Z","size":111,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-19T18:27:08.515Z","etag":null,"topics":[],"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/bytebodger.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":"2021-02-24T15:37:49.000Z","updated_at":"2021-04-10T20:40:29.000Z","dependencies_parsed_at":"2022-08-30T15:22:00.659Z","dependency_job_id":null,"html_url":"https://github.com/bytebodger/string-contains","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bytebodger/string-contains","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebodger%2Fstring-contains","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebodger%2Fstring-contains/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebodger%2Fstring-contains/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebodger%2Fstring-contains/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytebodger","download_url":"https://codeload.github.com/bytebodger/string-contains/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebodger%2Fstring-contains/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268185275,"owners_count":24209383,"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","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"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":"2025-05-19T00:17:11.195Z","updated_at":"2025-08-01T07:14:35.731Z","avatar_url":"https://github.com/bytebodger.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# string-contains\n\nThis is a string inspection utility that is mindful of non-English character sets. A common pattern in JavaScript is to test for the presence of alphabetic characters like this:\n\n```javascript\nconst containsOnlyLetters = (string = '') =\u003e !!string.match(/^[a-zA-Z]+$/);\n```\n\nBut the above code is entirely Anglo-centric, because it assumes that the universe of letters consists of the capitals A-Z and the lowercases a-z. In other words, this approach only checks for the presence of letters in the ASCII range.\n\nEven if an application is not specifically designed to be multilingual, it can be exclusionary (and potentially discriminatory) to force names (or other sensitive data) to conform to ASCII standards.\n\nFor example, when prompting a user to enter their last name, many English speakers assume that\n\n\u003e Calderón\n\nIs no different than\n\n\u003e Calderon\n\nOr that\n\n\u003e Núñez\n\nIs no different than\n\n\u003e Nunez\n\nBut there are many in the Latinx community who feel otherwise.\n\nThe same problem often occurs when handling place names - even places _in English-speaking countries_.\n\nFor example, there is no city called\n\n\u003e Pinon Hills\n\nin California. But there _is_ a city called\n\n\u003e Piñon Hills\n\nAnd in Minnesota, there is a city commonly referred to as\n\n\u003e Lindstrom\n\nBut its proper spelling is\n\n\u003e Lindström\n\nEnglish speakers may assume that there is no harm in forcing someone with the name of \"Núñez\" to enter their name as \"Nunez\". But aside from being potentially discriminatory, these discrepancies can have systemic effects.\n\nFor example, it is perfectly valid (albeit, rare) to have non-ASCII values in an email address. So if someone's email address is núñez@somedomain.com, and your validation scripts reject any email addresses with non-ASCII letters, the user would be faced with the choice to either A) enter a non-working email, just to pass the validation, or B) abandon the form altogether.\n\nSimilarly, non-ASCII characters can absolutely be in domain names. So restricing non-ASCII characters may keep you from collecting the user's email address or the URL for their website.\n\n## Methodology\n\nThis utility works by using the `Letter` and `Mark` RegEx Unicode character classes.\n\n## Usage\n\n```javascript\nimport { contains } from '@toolz/string-contains';\n\nconst letters = 'úñóö';\n\nconst containsLetters = (string = '') =\u003e string.match(/[A-Za-z]/);\ncontainsLetters(letters); // returns FALSE\n\ncontains.letters(letters); // returns TRUE\n```\n\n## Methods\n\n### .alphanumerics()\n\n`.alphanumerics()` determines whether a string contains _any_ alphanumeric values.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst letters = 'úñóö';\nconst numbers = '122';\nconst empty = '';\nconst specialCharacters = '_*%$';\n\ncontains.alphanumerics(letters); // returns TRUE\ncontains.alphanumerics(numbers); // returns TRUE\ncontains.alphanumerics(empty); // returns FALSE\ncontains.alphanumerics(specialCharacters); // returns FALSE\n```\n\n### .letters()\n\n`.letters()` determines whether a string contains _any_ letters.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'howdy';\n\ncontains.letters(pi); // returns FALSE\ncontains.letters(russian); // returns TRUE\ncontains.letters(english); // returns TRUE\n```\n\n### .lowercaseLetters()\n\n`.lowercaseLetters()` determines whether a string contains _any_ lowercase letters.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst uppercaseRussian = 'БЫСТРЫЙЛЕНИВЫЙЛИС';\nconst mixedCaseEnglish = 'Bill Joe Henry';\nconst pi = '3.14';\n\ncontains.lowercaseLetters(uppercaseRussian); // returns FALSE\ncontains.lowercaseLetters(mixedCaseEnglish); // returns TRUE\ncontains.lowercaseLetters(pi); // returns FALSE\n```\n\n### .numbers()\n\n`.numbers()` determines whether a string contains _any_ numbers.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'day number one';\n\ncontains.numbers(pi); // returns TRUE\ncontains.numbers(russian); // returns FALSE\ncontains.numbers(english); // returns FALSE\n```\n\n### .onlyAlphanumerics()\n\n`.onlyAlphanumerics()` determines whether a string contains _only_ alphanumeric values.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n      ignoredCharacters: {\n         optional,\n         format: 'array of strings',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'day number 1';\n\ncontains.onlyAlphanumerics(pi); // returns FALSE\ncontains.onlyAlphanumerics(russian); // returns TRUE\ncontains.onlyAlphanumerics(english); // returns FALSE (because of the spaces)\ncontains.onlyAlphanumerics(pi, ['.']); // returns TRUE\ncontains.onlyAlphanumerics(english, [' ']); // returns TRUE\n```\n\n### .onlyLetters()\n\n`.onlyLetters()` determines whether a string contains _only_ letters.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n      ignoredCharacters: {\n         optional,\n         format: 'array of strings',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'day number one';\n\ncontains.onlyLetters(pi); // returns FALSE\ncontains.onlyLetters(russian); // returns TRUE\ncontains.onlyLetters(english); // returns FALSE (because of the spaces)\ncontains.onlyLetters(pi, ['.']); // returns FALSE\ncontains.onlyLetters(english, [' ']); // returns TRUE\n```\n\n### .onlyLowercaseLetters()\n\n`.onlyLowercaseLetters()` determines whether a string contains _only_ lowercase letters.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n      ignoredCharacters: {\n         optional,\n         format: 'array of strings',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'day number one';\n\ncontains.onlyLowercaseLetters(pi); // returns FALSE\ncontains.onlyLowercaseLetters(russian); // returns FALSE\ncontains.onlyLowercaseLetters(english); // returns FALSE (because of the spaces)\ncontains.onlyLowercaseLetters(pi, ['.']); // returns FALSE\ncontains.onlyLowercaseLetters(english, [' ']); // returns TRUE\n```\n\n### .onlyNumbers()\n\n`.onlyNumbers()` determines whether a string contains _only_ numbers.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n      ignoredCharacters: {\n         optional,\n         format: 'array of strings',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'day number one';\n\ncontains.onlyNumbers(pi); // returns FALSE\ncontains.onlyNumbers(russian); // returns FALSE\ncontains.onlyNumbers(english); // returns FALSE (because of the spaces)\ncontains.onlyNumbers(pi, ['.']); // returns TRUE\ncontains.onlyNumbers(english, [' ']); // returns FALSE\n```\n\n### .onlyUppercaseLetters()\n\n`.onlyUppercaseLetters()` determines whether a string contains _only_ uppercase letters.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n      ignoredCharacters: {\n         optional,\n         format: 'array of strings',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'DAY ONE';\n\ncontains.onlyUppercaseLetters(pi); // returns FALSE\ncontains.onlyUppercaseLetters(russian); // returns FALSE\ncontains.onlyUppercaseLetters(english); // returns FALSE (because of the space)\ncontains.onlyUppercaseLetters(pi, ['.']); // returns FALSE\ncontains.onlyUppercaseLetters(english, [' ']); // returns TRUE\n```\n\n### .specialCharacters()\n\n`.specialCharacters()` determines whether a string contains _any_ nonalphanumeric values.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n      ignoredCharacters: {\n         optional,\n         format: 'array of strings',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst pi = '3.14';\nconst russian = 'быстрыйленивыйлис';\nconst english = 'DAY ONE';\n\ncontains.specialCharacters(pi); // returns TRUE\ncontains.specialCharacters(russian); // returns FALSE\ncontains.specialCharacters(english); // returns TRUE (because of the space)\ncontains.specialCharacters(pi, ['.']); // returns FALSE\ncontains.specialCharacters(english, [' ']); // returns FALSE\n```\n\n### .uppercaseLetters()\n\n`.uppercaseLetters()` determines whether a string contains _any_ uppercase letters.\n\n```javascript\nconst API = {\n   arguments: {\n      string: {\n         required,\n         format: 'string',\n      },\n   },\n   returns: Boolean,\n}\n```\n\n**Examples:**\n\n```javascript\nconst uppercaseRussian = 'БЫСТРЫЙЛЕНИВЫЙЛИС';\nconst mixedCaseEnglish = 'Bill Joe Henry';\nconst pi = '3.14';\n\ncontains.uppercaseLetters(uppercaseRussian); // returns TRUE\ncontains.uppercaseLetters(mixedCaseEnglish); // returns TRUE\ncontains.uppercaseLetters(pi); // returns FALSE\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebodger%2Fstring-contains","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytebodger%2Fstring-contains","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebodger%2Fstring-contains/lists"}