tandrewnichols / indefinite

Prefix a noun with an indefinite article - a or an - based on whether it begins with a vowel

indefinite

Prefix a noun with an indefinite article - a or an - based on whether it begins with a vowel.

Installation

npm install --save indefinite

Summary

It's not hard to check whether a noun begins with a vowel and decide whether to prefix with "a" or "an," but I got tired of doing it manually every time. So now there's this. Just pass in the word, and indefinite will return the word prefixed with either "a " or "an " depending on the first letter of the word.

As of version 2.0.0, indefinite will attempt to detect when an acronym is passed in and treat the response differently. E.g. it should be "a UFO" not "an UFO" because of how we pronounce a long U. This isn't a perfect science, so you might have false positives.

As of version 2.0.2, indefinite will also consult a list of irregular words to determine the appropriate article. For example, it should be "an hour" not "a hour." It also attempts to do this with various forms of the words (checking for singular, plural, and even past tense, since past tense verbs can be used as adjectives, as in "an honored man"). This is not an exact science either, and the list of irregulars is not exhaustive (and probably won't ever be), but if you find a word that's not in the list that's returning the wrong thing, please open an issue so it can be corrected.

Usage

var a = require('indefinite');

console.log(a('apple')); // "an apple"
console.log(a('banana')); // "a banana"
console.log(a('UFO')); // 'a UFO'
console.log(a('hour')); // 'an hour'
console.log(a('ukelele')); // 'a ukelele'

Indefinite also accepts an options object as the second parameter. The following options are supported:

• articleOnly - Return only the article.
• capitalize - Capitalize the article.
• caseInsensitive - Ignore the casing of the word passed in (i.e. bypassing the acronym checking). This is useful if, for some reason, you're yelling on the internet and want to make sure "UGLY GARDEN GNOME" doesn't become "a UGLY GARDEN GNOME."
• numbers - When numbers are passed in, they are prefixed with "a" except for 8, 11, 18, and higher numbers starting with 8. However, numbers like 1100 are ambiguous. Should it be "a one thousand one hundred" or "an eleven hundred"? There's not really any programmatic way to know this for sure, but if you know for sure, you can use the numbers option to tell indefinite how to handle these cases. The default is "formal" in which numbers are read literally (the way you'd say them if they were written out), but if you pass numbers: 'colloquial', the "eleven hundred"/"eighteen hundred" readings will be used.

console.log(a('apple', { articleOnly: true })); // 'an'
console.log(a('banana', { articleOnly: true })); // 'a'
console.log(a('apple', { capitalize: true })); // 'An apple'
console.log(a('banana', { capitalize: true })); // 'A banana'
console.log(a('UGLY SWEATER', { caseInsensitive: true })); // 'an UGLY SWEATER'
console.log(a('2')); // 'a 2'
console.log(a('8')); // 'an 8'
console.log(a('1892')); // 'a 1892' -> read "a one thousand eight hundred ninety-two"
console.log(a('1892', { numbers: 'colloquial' })); // 'an 1892' -> read "an eighteen ninety-two"

Browser

Files in dist are UMD format, and package.json contains a browser field pointing to dist/indefinite.js, so you should be able to bundle this via webpack, rollup, browserify, etc. or serve it in ye olde javascript fashion and access it via window.

Detecting the need for an indefinite article

It's worth mentioning that indefintite currently only differentiates between a and an for you. It doesn't do anything to decide if an indefinite article is required, so if you pass a plural to indefinite, you'll get something like "a shoes" back, which is obviously wrong. You can look at this issue for more context on why this isn't supported at the moment. It could be in the future, but there are some prohibitive issues to work through first. For now, it is up to you (the consumer) to either call or not call indefinite depending on the plurality of the word. You can do something like the suggestion in that issue:

const indefinite = require('indefinite');
const pluralize = require('pluralize');

module.exports = (subject) => {
  if (pluralize(subject) === subject) {
    return subject;
  }

  return indefinite(subject);
};

Or you can try is-singular or is-plural.

Contributing

Please see the contribution guidelines.

indefinite's Issues

Add Utah to irregular words list

Hi there, could you please add "Utah" to the irregular word list?
Thanks!

Any chance for TypeScript type definitions?

Mistake in "UX" workd conversion

a('UX Designer') returns an UX Designer and not a UX Designer

"red <word>" incorrectly formatted

import a from "indefinite";

a("red kite");
a("red rooster");

// returns "an red kite"
// returns "an red rooster"

Plural should not have indefinite article

// current
indefinite('French Fries') => 'a French Fries'

// expected
indefinite('French Fries') => 'French Fries'

Incorrect indefinite article when the word is quoted

Hi, firstly, thanks for the great work.

I noticed an issue that the library will always use 'a' if the word is quoted:

var a = require("indefinite")

a('\'email\'') // => a
a('"email"') // => a

And in those cases, it should use 'an' instead.

Addition to irregular words list - "user"

The word "user" could be added to the irregular list to return "a user" rather than "an user".
Thank you
Daniel

I'd like to just have the article, instead of the article appended with the word.

I'd like to just have the article, instead of the article appended with the word, because I want to encapsulate the word itself into different JSX tags. I'm proposing the following. Can make a pull request:

exports.capitalize = (article, word, opts) => {
  if (opts.capitalize) {
    article = `${article.charAt(0).toUpperCase()}${article.slice(1)}`;
  }

  let result = `${article} ${word}`;

  if(opts.articleOnly) {
     result = article;
  }

  return result;
};

the lib does not work when included in older browsers

Hey,

thanks for the lib!

We tried to use it in an internal project which unfortunately needs to support some old browsers like IE10 without a big success.

To fix that I could contribute and add rollup + babel to create a transpiled version that could be accessed like:

import indefinite from 'indefinite/dist/legacy'

If that's fine just let me know :)

Missing release for 2.4.3

Looks like you bumped versions but didn't add a release for it. Looks like just dependency bumps, but it would be nice to confirm that.

Numbers

How about support for numbers?

For example,

`You rolled ${indefinite(82)}.`

yields "You rolled a 82." when it should yield "You rolled an 82."

Incompatibility with @rails/webpacker

Hi here, first of all thanks for your work! We've been using your package on https://digitalnz.org/ for a long time.

It looks like you wrote a commit 8f9dbe0 which is making our server-side rendering failing. I'm pretty sure it's because of

{
  "presets": [["@babel/preset-env", { "modules": false }]]
}

It makes our server-side rendering fail. I'm not an expert in babel and everything, but I guess modules are used by the server-side rendering. Would it possible to add it back?

Wrong article from 'SCORM' word

Hello, i think i found an issue please have a look at my test cases bellow.

	it("should not change the article of banana", () => {
		const expected = "a banana";

		expect(MyService.fixArticles("a banana")).toEqual(expected);
	});

	it("should not change the article of BANANA", () => {
		const expected = "a BANANA";

		expect(MyService.fixArticles("a BANANA")).toEqual(expected);
	});

	it("should not change the article of Banana", () => {
		const expected = "a Banana";

		expect(MyService.fixArticles("a Banana")).toEqual(expected);
	});

	it("should not change the article of scorm", () => {
		const expected = "a scorm";

		expect(MyService.fixArticles("a scorm")).toEqual(expected);
	});

	it("should not change the article of Scorm", () => {
		const expected = "a Scorm";

		expect(MyService.fixArticles("a Scorm")).toEqual(expected);
	});

	it("should not change the article of SCORM", () => {
		const expected = "a SCORM file";

		expect(MyService.fixArticles("a SCORM file")).toEqual(expected);
	});

Running these tests i get this error

Error: Expected 'an SCORM file' to equal 'a SCORM file'.

And the important prats of the fixArticles method

	public static fixArticles(string: string): string {
		// Some code to isolate the current article from the next word
		
			if (article === article.toUpperCase())
				article = indefinite(word, {
					articleOnly: true
				}).toUpperCase();
			else if (article === article.toLowerCase()) {
				article = indefinite(word, {
					articleOnly: true
				}).toLowerCase();
			}

			return `${article} ${word}`;
		
	}

Acronyms starting with F, H, L, M, N, R, S, and X should be prefixed with "an"

Handle joined words LikeThis

In some applications we have joined words LikeThis.

indefinite cannot currently handle irregular cases like: UserRole or userRole.

It would be nice to add support for such joined words - maybe use library decamelize ?