salutation-generator

Generate contextual, personalized greetings like "Good morning, Mr. Smith" with support for professionalism levels, anonymous users, custom time boundaries, and flexible data injection. Built for modern applications that care about user experience.

Installation

npm install salutation-generator
# or
pnpm add salutation-generator
# or
yarn add salutation-generator

Usage

import { generateGreeting } from 'salutation-generator';

const result = generateGreeting({
  getFirstName: () => 'Tom',
  getGender: () => 'male',
  getRelationshipStatus: () => 'single',
  professionalism: 'formal',
  getDateTime: () => new Date(),
});

console.log(result.fullMessage); // "Good morning, Mr. Tom"

API

generateGreeting(config: GreetingConfig): GreetingResult

Generates a personalized greeting message.

Config

interface GreetingConfig {
  getFirstName: () => string | undefined;
  getGender: () => 'male' | 'female' | 'non-binary' | undefined;
  getRelationshipStatus: () => 'single' | 'married' | 'other' | undefined;
  professionalism: 'formal' | 'casual' | 'neutral';
  getDateTime: () => Date;
  nameFallback?: string | (() => string);
  canBidGoodNight?: boolean;
}

• getFirstName: Returns user's first name. Returns undefined for anonymous users.
• getGender: Returns user's gender identity.
• getRelationshipStatus: Returns relationship status (affects honorifics for females in formal mode).
• professionalism: Determines greeting style:
  • 'formal': Uses honorifics (Mr., Mrs., Ms., Mx.)
  • 'casual': Uses "Hey [Name]!" format
  • 'neutral': Uses time-based greeting with name only
• getDateTime: Function that returns a Date object for determining time of day.
• nameFallback: Optional fallback name for anonymous users when gender is unavailable.
• canBidGoodNight: Optional boolean (default: true). Whether to say "Good night" during night hours (9 PM - 4:59 AM). If false, uses "Good evening" instead.

Return Value

interface GreetingResult {
  timeOfDay: 'morning' | 'afternoon' | 'evening' | 'night';
  greeting: string;
  honorific?: 'Mr.' | 'Mrs.' | 'Ms.' | 'Mx.';
  name?: string;
  fullMessage: string;
}

Examples

Formal Business Context

const result = generateGreeting({
  getFirstName: () => 'Johnson',
  getGender: () => 'male',
  getRelationshipStatus: () => 'married',
  professionalism: 'formal',
  getDateTime: () => new Date(),
});
// Result: "Good morning, Mr. Johnson"

Casual Friend Context

const result = generateGreeting({
  getFirstName: () => 'Alex',
  getGender: () => 'non-binary',
  getRelationshipStatus: () => 'single',
  professionalism: 'casual',
  getDateTime: () => new Date(),
});
// Result: "Hey Alex!"

Anonymous User with Fallback

const result = generateGreeting({
  getFirstName: () => undefined,
  getGender: () => undefined,
  getRelationshipStatus: () => undefined,
  professionalism: 'neutral',
  getDateTime: () => new Date(),
  nameFallback: 'Guest',
});
// Result: "Good morning, Guest"

Using Result Components

const result = generateGreeting({
  getFirstName: () => 'Sarah',
  getGender: () => 'female',
  getRelationshipStatus: () => 'married',
  professionalism: 'formal',
  getDateTime: () => new Date(),
});

// Build custom message
const customMessage = `${result.greeting}! Welcome back, ${result.honorific} ${result.name}!`;
// "Good morning! Welcome back, Mrs. Sarah!"

Controlling Night Greetings

// Default behavior - says "Good night" during night hours
const result1 = generateGreeting({
  getFirstName: () => 'Tom',
  getGender: () => 'male',
  getRelationshipStatus: () => 'single',
  professionalism: 'formal',
  getDateTime: () => new Date('2024-01-01T22:00:00'), // 10 PM
});
// Result: "Good night, Mr. Tom"

// Disable "Good night" - uses "Good evening" instead
const result2 = generateGreeting({
  getFirstName: () => 'Tom',
  getGender: () => 'male',
  getRelationshipStatus: () => 'single',
  professionalism: 'formal',
  getDateTime: () => new Date('2024-01-01T22:00:00'), // 10 PM
  canBidGoodNight: false,
});
// Result: "Good evening, Mr. Tom"

Time of Day Boundaries

• Morning: 5:00 AM - 11:59 AM
• Afternoon: 12:00 PM - 4:59 PM
• Evening: 5:00 PM - 8:59 PM
• Night: 9:00 PM - 4:59 AM

Honorific Rules

Formal Professionalism

• Male: Always uses Mr.
• Female:
  • Married → Mrs.
  • Single/Other → Ms.
• Non-binary: Always uses Mx.

Casual & Neutral

No honorifics are used.

Anonymous Users

When getFirstName() returns undefined:

1. If formal professionalism + gender available → Uses honorific without period (e.g., "Good morning, Mr")
2. If nameFallback provided → Uses fallback value
3. Otherwise → Returns greeting only (e.g., "Good morning")

Complementary Packages

• humanparser - Parse full names into components (first, last, salutation, etc.)
• greeting-time - If you need customizable time boundaries

Using with humanparser for Full Name Parsing

If you need to parse full names, you can combine this with the humanparser package:

TypeScript Support

Full TypeScript support with comprehensive type definitions included.

License

MIT © Oghenetefa Okotete

Contributing

Issues and pull requests welcome at github.com/everurstruly/salutation-generator