Pluralization and Lists

/**
 * Returns plural version of a word if value is not 1
 * @param number - Count to check for pluralization
 * @param singular - Singular form of the word
 * @param plural - Plural form (default: singular + 's')
 * @returns Appropriate singular or plural form
 */
function pluralize(number: number, singular: string, plural?: string): string | null;

const Humanize = require('humanize-plus');

// Default pluralization (adds 's')
console.log(Humanize.pluralize(1, 'cat')); // "cat"
console.log(Humanize.pluralize(2, 'cat')); // "cats"
console.log(Humanize.pluralize(0, 'item')); // "items"

// Custom plural forms
console.log(Humanize.pluralize(1, 'person', 'people')); // "person"
console.log(Humanize.pluralize(3, 'person', 'people')); // "people"
console.log(Humanize.pluralize(1, 'child', 'children')); // "child"
console.log(Humanize.pluralize(2, 'child', 'children')); // "children"

// Returns null for invalid input
console.log(Humanize.pluralize(null, 'word')); // null
console.log(Humanize.pluralize(5, null)); // null

/**
 * Converts a list of items to a human readable string with optional limit
 * @param items - Array of items to join
 * @param limit - Optional maximum number of items to show
 * @param limitStr - Custom string for excess items
 * @returns Formatted string with proper conjunctions
 */
function oxford(items: string[], limit?: number, limitStr?: string): string;

const Humanize = require('humanize-plus');

const fruits = ['apple', 'orange', 'banana', 'pear', 'pineapple'];

// Basic Oxford comma formatting
console.log(Humanize.oxford([])); // ""
console.log(Humanize.oxford(['apple'])); // "apple"
console.log(Humanize.oxford(['apple', 'orange'])); // "apple and orange"
console.log(Humanize.oxford(fruits)); // "apple, orange, banana, pear, and pineapple"

// With limits
console.log(Humanize.oxford(fruits, 3)); // "apple, orange, banana, and 2 others"
console.log(Humanize.oxford(fruits, 4)); // "apple, orange, banana, pear, and 1 other"

// Custom limit strings
console.log(Humanize.oxford(fruits, 3, 'and some other fruits')); 
// "apple, orange, banana, and some other fruits"

/**
 * Interprets numbers as occurrences with optional custom overrides
 * @param value - Number of occurrences
 * @param overrides - Custom mappings for specific values (default: {})
 * @returns Occurrence description or null for invalid input
 */
function times(value: number, overrides?: object): string | null;

const Humanize = require('humanize-plus');

// Special cases
console.log(Humanize.times(0)); // "never"
console.log(Humanize.times(1)); // "once"
console.log(Humanize.times(2)); // "twice"

// Regular numbers
console.log(Humanize.times(3)); // "3 times"
console.log(Humanize.times(12)); // "12 times"

// Custom overrides
console.log(Humanize.times(3, {3: 'thrice'})); // "thrice"
console.log(Humanize.times(12, {12: 'a dozen times'})); // "a dozen times"

// Invalid input
console.log(Humanize.times(-1)); // null
console.log(Humanize.times('invalid')); // null

/**
 * Describes how many times an item appears in a list
 * @param list - Array to count
 * @param verb - Action description
 * @returns Frequency description string or null for invalid input
 */
function frequency(list: any[], verb: string): string | null;

const Humanize = require('humanize-plus');

const photos = ['photo1.jpg', 'photo2.jpg', 'photo3.jpg'];
const emptyList = [];

console.log(Humanize.frequency(photos, 'took pictures')); // "took pictures 3 times"
console.log(Humanize.frequency(emptyList, 'took pictures')); // "never took pictures"

// Different verb forms
console.log(Humanize.frequency([1], 'appeared')); // "appeared once"
console.log(Humanize.frequency([1, 2], 'appeared')); // "appeared twice"

// Invalid input
console.log(Humanize.frequency('not an array', 'verb')); // null