Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add first name by decade range and age preference scaffolding (#1379)

Leendert de Borst2043e94a91b1
diff --git a/shared/identity-generator/src/__tests__/AgeRangeConverter.test.ts b/shared/identity-generator/src/__tests__/AgeRangeConverter.test.ts
new file mode 100644
index 000000000..cb915efb9
--- /dev/null
+++ b/shared/identity-generator/src/__tests__/AgeRangeConverter.test.ts
@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+import { convertAgeRangeToBirthdateOptions } from '../utils/AgeRangeConverter';
+
+describe('AgeRangeConverter', () => {
+ // Mock Date to ensure consistent test results
+ const MOCK_CURRENT_YEAR = 2025;
+ let originalDate: DateConstructor;
+
+ beforeEach(() => {
+ originalDate = global.Date;
+ const mockDate = new Date(`${MOCK_CURRENT_YEAR}-01-01T00:00:00.000Z`);
+ vi.spyOn(global, 'Date').mockImplementation((...args) => {
+ if (args.length === 0) {
+ return mockDate;
+ }
+ return new originalDate(...args as []);
+ }) as unknown as DateConstructor;
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ describe('convertAgeRangeToBirthdateOptions', () => {
+ it('should return null for "random" age range', () => {
+ const result = convertAgeRangeToBirthdateOptions('random');
+ expect(result).toBeNull();
+ });
+
+ it('should return null for empty string', () => {
+ const result = convertAgeRangeToBirthdateOptions('');
+ expect(result).toBeNull();
+ });
+
+ it('should convert "21-25" correctly', () => {
+ const result = convertAgeRangeToBirthdateOptions('21-25');
+ expect(result).toEqual({
+ targetYear: 2002, // 2025 - 23 (middle of 21-25)
+ yearDeviation: 2 // (25-21)/2
+ });
+ });
+
+ it('should convert "26-30" correctly', () => {
+ const result = convertAgeRangeToBirthdateOptions('26-30');
+ expect(result).toEqual({
+ targetYear: 1997, // 2025 - 28 (middle of 26-30)
+ yearDeviation: 2 // (30-26)/2
+ });
+ });
+
+ it('should convert "31-35" correctly', () => {
+ const result = convertAgeRangeToBirthdateOptions('31-35');
+ expect(result).toEqual({
+ targetYear: 1992, // 2025 - 33 (middle of 31-35)
+ yearDeviation: 2 // (35-31)/2
+ });
+ });
+
+ it('should convert "61-65" correctly', () => {
+ const result = convertAgeRangeToBirthdateOptions('61-65');
+ expect(result).toEqual({
+ targetYear: 1962, // 2025 - 63 (middle of 61-65)
+ yearDeviation: 2 // (65-61)/2
+ });
+ });
+
+ it('should handle odd range sizes correctly', () => {
+ const result = convertAgeRangeToBirthdateOptions('20-24');
+ expect(result).toEqual({
+ targetYear: 2003, // 2025 - 22 (middle of 20-24)
+ yearDeviation: 2 // floor((24-20)/2)
+ });
+ });
+
+ it('should return null for invalid format (missing dash)', () => {
+ const result = convertAgeRangeToBirthdateOptions('2125');
+ expect(result).toBeNull();
+ });
+
+ it('should return null for invalid format (too many parts)', () => {
+ const result = convertAgeRangeToBirthdateOptions('21-25-30');
+ expect(result).toBeNull();
+ });
+
+ it('should return null for non-numeric values', () => {
+ const result = convertAgeRangeToBirthdateOptions('abc-def');
+ expect(result).toBeNull();
+ });
+
+ it('should return null for partially numeric values', () => {
+ const result = convertAgeRangeToBirthdateOptions('21-abc');
+ expect(result).toBeNull();
+ });
+
+ it('should handle single-year ranges', () => {
+ const result = convertAgeRangeToBirthdateOptions('25-25');
+ expect(result).toEqual({
+ targetYear: 2000, // 2025 - 25
+ yearDeviation: 0 // (25-25)/2
+ });
+ });
+ });
+});
diff --git a/shared/identity-generator/src/implementations/base/IdentityGenerator.ts b/shared/identity-generator/src/implementations/base/IdentityGenerator.ts
index 3cbde6e6f..1d480f602 100644
--- a/shared/identity-generator/src/implementations/base/IdentityGenerator.ts
+++ b/shared/identity-generator/src/implementations/base/IdentityGenerator.ts
@@ -1,8 +1,17 @@
import { UsernameEmailGenerator } from '../../utils/UsernameEmailGenerator';
import { Gender } from '../../types/Gender';
-import { IIdentityGenerator } from '../../interfaces/IIdentityGenerator';
+import { IIdentityGenerator, IBirthdateOptions } from '../../interfaces/IIdentityGenerator';
import { Identity } from '../../types/Identity';
+/**
+ * Dictionary of firstnames organized by decade range.
+ */
+export interface IDecadeFirstnames {
+ startYear: number;
+ endYear: number;
+ names: string[];
+}
+
/**
* Base identity generator.
*/
@@ -26,10 +35,48 @@ export abstract class IdentityGenerator implements IIdentityGenerator {
protected abstract getFirstNamesFemaleJson(): string[];
protected abstract getLastNamesJson(): string[];
+ /**
+ * Get decade-based male first names. Override this to provide age-specific names.
+ * If not overridden, returns an empty array and falls back to generic names.
+ */
+ protected getFirstNamesMaleByDecade(): IDecadeFirstnames[] {
+ return [];
+ }
+
+ /**
+ * Get decade-based female first names. Override this to provide age-specific names.
+ * If not overridden, returns an empty array and falls back to generic names.
+ */
+ protected getFirstNamesFemaleByDecade(): IDecadeFirstnames[] {
+ return [];
+ }
+
/**
* Generate a random date of birth.
+ * @param birthdateOptions Optional birthdate configuration
*/
- protected generateRandomDateOfBirth(): Date {
+ protected generateRandomDateOfBirth(birthdateOptions?: IBirthdateOptions): Date {
+ if (birthdateOptions) {
+ const { targetYear, yearDeviation } = birthdateOptions;
+
+ if (yearDeviation === 0) {
+ // Generate a random date within the target year
+ const startOfYear = new Date(targetYear, 0, 1);
+ const endOfYear = new Date(targetYear, 11, 31);
+ const timestamp = startOfYear.getTime() + (this.random() * (endOfYear.getTime() - startOfYear.getTime()));
+ return new Date(timestamp);
+ } else {
+ // Generate a random date within the year range
+ const minYear = targetYear - yearDeviation;
+ const maxYear = targetYear + yearDeviation;
+ const startDate = new Date(minYear, 0, 1);
+ const endDate = new Date(maxYear, 11, 31);
+ const timestamp = startDate.getTime() + (this.random() * (endDate.getTime() - startDate.getTime()));
+ return new Date(timestamp);
+ }
+ }
+
+ // Default behavior: generate birthdate for age between 21 and 65
const today = new Date();
const minAge = 21;
const maxAge = 65;
@@ -41,10 +88,48 @@ export abstract class IdentityGenerator implements IIdentityGenerator {
return new Date(timestamp);
}
+ /**
+ * Select appropriate firstnames based on birthdate.
+ * Falls back to generic names if no decade-specific data is available.
+ */
+ protected selectFirstnamesForBirthdate(birthdate: Date, isMale: boolean): string[] {
+ const birthYear = birthdate.getFullYear();
+ const decadeData = isMale ? this.getFirstNamesMaleByDecade() : this.getFirstNamesFemaleByDecade();
+
+ if (decadeData.length === 0) {
+ // No decade-specific data, use generic lists
+ return isMale ? this.firstNamesMale : this.firstNamesFemale;
+ }
+
+ // Find matching decade ranges
+ const matchingRanges = decadeData.filter(
+ range => birthYear >= range.startYear && birthYear <= range.endYear
+ );
+
+ if (matchingRanges.length > 0) {
+ // Combine all matching ranges
+ const combinedNames: string[] = [];
+ matchingRanges.forEach(range => combinedNames.push(...range.names));
+ return combinedNames;
+ }
+
+ // No matching range found, combine all available decade names
+ const allDecadeNames: string[] = [];
+ decadeData.forEach(range => allDecadeNames.push(...range.names));
+
+ // If we have decade data but birthdate doesn't match, use all decade data
+ if (allDecadeNames.length > 0) {
+ return allDecadeNames;
+ }
+
+ // Fallback to generic lists
+ return isMale ? this.firstNamesMale : this.firstNamesFemale;
+ }
+
/**
* Generate a random identity.
*/
- public generateRandomIdentity(gender?: string | 'random'): Identity {
+ public generateRandomIdentity(gender?: string | 'random', birthdateOptions?: IBirthdateOptions): Identity {
const identity: Identity = {
firstName: '',
lastName: '',
@@ -70,22 +155,26 @@ export abstract class IdentityGenerator implements IIdentityGenerator {
}
}
- // Set gender and appropriate first name
+ // Set gender
identity.gender = selectedGender;
+
+ // Generate birthdate first (needed for age-based firstname selection)
+ identity.birthDate = this.generateRandomDateOfBirth(birthdateOptions);
+
+ // Select appropriate first name based on gender and birthdate
+ let availableFirstnames: string[];
if (selectedGender === Gender.Male) {
- identity.firstName = this.firstNamesMale[Math.floor(this.random() * this.firstNamesMale.length)];
+ availableFirstnames = this.selectFirstnamesForBirthdate(identity.birthDate, true);
} else if (selectedGender === Gender.Female) {
- identity.firstName = this.firstNamesFemale[Math.floor(this.random() * this.firstNamesFemale.length)];
+ availableFirstnames = this.selectFirstnamesForBirthdate(identity.birthDate, false);
} else {
// For Gender.Other, randomly choose from either list
const usesMaleNames = this.random() < 0.5;
- identity.firstName = usesMaleNames
- ? this.firstNamesMale[Math.floor(this.random() * this.firstNamesMale.length)]
- : this.firstNamesFemale[Math.floor(this.random() * this.firstNamesFemale.length)];
+ availableFirstnames = this.selectFirstnamesForBirthdate(identity.birthDate, usesMaleNames);
}
+ identity.firstName = availableFirstnames[Math.floor(this.random() * availableFirstnames.length)];
identity.lastName = this.lastNames[Math.floor(this.random() * this.lastNames.length)];
- identity.birthDate = this.generateRandomDateOfBirth();
const generator = new UsernameEmailGenerator();
identity.emailPrefix = generator.generateEmailPrefix(identity);
diff --git a/shared/identity-generator/src/index.ts b/shared/identity-generator/src/index.ts
index eb02bcf29..8b46e5364 100644
--- a/shared/identity-generator/src/index.ts
+++ b/shared/identity-generator/src/index.ts
@@ -3,7 +3,9 @@ export * from './types/Gender';
export * from './implementations/IdentityGeneratorEn';
export * from './implementations/IdentityGeneratorNl';
export * from './implementations/base/IdentityGenerator';
+export * from './interfaces/IIdentityGenerator';
export * from './utils/IdentityHelperUtils';
export * from './utils/UsernameEmailGenerator';
+export * from './utils/AgeRangeConverter';
export * from './factories/IdentityGeneratorFactory';
export * from './factories/UsernameEmailGeneratorFactory';
diff --git a/shared/identity-generator/src/interfaces/IIdentityGenerator.ts b/shared/identity-generator/src/interfaces/IIdentityGenerator.ts
index 723557c2b..5dd704333 100644
--- a/shared/identity-generator/src/interfaces/IIdentityGenerator.ts
+++ b/shared/identity-generator/src/interfaces/IIdentityGenerator.ts
@@ -1,5 +1,21 @@
import { Identity } from "../types/Identity";
+/**
+ * Options for birthdate generation.
+ */
+export interface IBirthdateOptions {
+ /**
+ * The target year for the birthdate (e.g., 1990).
+ */
+ targetYear: number;
+
+ /**
+ * The random deviation in years (e.g., 5 means ±5 years from targetYear).
+ * If 0, a random date within the target year will be chosen.
+ */
+ yearDeviation: number;
+}
+
export interface IIdentityGenerator {
- generateRandomIdentity(gender?: string | 'random'): Identity;
+ generateRandomIdentity(gender?: string | 'random', birthdateOptions?: IBirthdateOptions): Identity;
}
diff --git a/shared/identity-generator/src/utils/AgeRangeConverter.ts b/shared/identity-generator/src/utils/AgeRangeConverter.ts
new file mode 100644
index 000000000..c38ce5f38
--- /dev/null
+++ b/shared/identity-generator/src/utils/AgeRangeConverter.ts
@@ -0,0 +1,38 @@
+import type { IBirthdateOptions } from '../interfaces/IIdentityGenerator';
+
+/**
+ * Converts an age range string (e.g., "21-25", "30-35", or "random") to birthdate options.
+ * @param ageRange - The age range string
+ * @returns An object containing targetYear and yearDeviation, or null if random
+ */
+export function convertAgeRangeToBirthdateOptions(ageRange: string): IBirthdateOptions | null {
+ if (ageRange === 'random' || !ageRange) {
+ return null; // Use default behavior
+ }
+
+ // Parse age range like "21-25" or "30-35"
+ const parts = ageRange.split('-');
+ if (parts.length !== 2) {
+ return null;
+ }
+
+ const minAge = parseInt(parts[0], 10);
+ const maxAge = parseInt(parts[1], 10);
+
+ if (isNaN(minAge) || isNaN(maxAge)) {
+ return null;
+ }
+
+ const currentYear = new Date().getFullYear();
+
+ // Calculate the middle of the age range
+ const middleAge = Math.floor((minAge + maxAge) / 2);
+
+ // Calculate target year (birth year for middle age)
+ const targetYear = currentYear - middleAge;
+
+ // Calculate deviation (half the range size)
+ const yearDeviation = Math.floor((maxAge - minAge) / 2);
+
+ return { targetYear, yearDeviation };
+}