Date & Time

/**
 * Generate a random date that can be either in the past or in the future
 * @param options - Configuration options
 * @returns Random date
 */
anytime(options?: {
  /** The date to use as reference point for the newly generated date */
  refDate?: string | Date | number;
}): Date;

/**
 * Generate a random date in the past
 * @param options - Configuration options  
 * @returns Date in the past
 */
past(options?: {
  /** The range of years the date may be in the past */
  years?: number;
  /** The date to use as reference point for the newly generated date */
  refDate?: string | Date | number;
}): Date;

/**
 * Generate a random date in the future
 * @param options - Configuration options
 * @returns Date in the future
 */
future(options?: {
  /** The range of years the date may be in the future */
  years?: number;
  /** The date to use as reference point for the newly generated date */
  refDate?: string | Date | number;
}): Date;

import { faker } from "@faker-js/faker";

// Generate any random date
const anyDate = faker.date.anytime();
// Example: 2022-07-31T01:33:29.567Z

// Generate date in the past
const pastDate = faker.date.past({ years: 5 });
// Example: 2019-03-15T14:20:10.123Z

// Generate future date with reference
const futureDate = faker.date.future({ 
  years: 2, 
  refDate: '2023-01-01' 
});
// Example: 2024-08-20T09:15:30.456Z

/**
 * Generate a random date between the given boundaries
 * @param options - Date range configuration
 * @returns Date within the specified range
 */
between(options: {
  /** The early date boundary */
  from: string | Date | number;
  /** The late date boundary */
  to: string | Date | number;
}): Date;

/**
 * Generate multiple random dates between boundaries, sorted chronologically
 * @param options - Date range and count configuration
 * @returns Array of dates sorted in chronological order
 */
betweens(options: {
  /** The early date boundary */
  from: string | Date | number;
  /** The late date boundary */
  to: string | Date | number;
  /** The number of dates to generate */
  count?: number | {
    /** The minimum number of dates to generate */
    min: number;
    /** The maximum number of dates to generate */
    max: number;
  };
}): Date[];

import { faker } from "@faker-js/faker";

// Generate date in specific range
const betweenDate = faker.date.between({
  from: '2020-01-01',
  to: '2023-12-31'
});

// Generate multiple dates in range
const multipleDates = faker.date.betweens({
  from: '2020-01-01',
  to: '2023-12-31',
  count: 5
});

// Generate variable count of dates
const variableDates = faker.date.betweens({
  from: '2020-01-01', 
  to: '2023-12-31',
  count: { min: 2, max: 8 }
});

/**
 * Generate a random date in the recent past
 * @param options - Configuration options
 * @returns Recent past date
 */
recent(options?: {
  /** The range of days the date may be in the past */
  days?: number;
  /** The date to use as reference point for the newly generated date */
  refDate?: string | Date | number;
}): Date;

/**
 * Generate a random date in the near future
 * @param options - Configuration options
 * @returns Near future date
 */
soon(options?: {
  /** The range of days the date may be in the future */
  days?: number;
  /** The date to use as reference point for the newly generated date */
  refDate?: string | Date | number;
}): Date;

import { faker } from "@faker-js/faker";

// Generate recent date (within 1 day)
const recentDate = faker.date.recent();

// Generate recent date within 10 days
const recentTenDays = faker.date.recent({ days: 10 });

// Generate date soon (within 1 day)
const soonDate = faker.date.soon();

// Generate near future date within 30 days
const soonMonth = faker.date.soon({ days: 30 });

/**
 * Generate a random birthdate with flexible age or year constraints
 * @param options - Birthdate generation options
 * @returns Realistic birthdate
 */
birthdate(options?: {
  /** Generation mode: 'age' or 'year' */
  mode?: 'age' | 'year';
  /** Minimum age (mode: 'age') or year (mode: 'year') */
  min?: number;
  /** Maximum age (mode: 'age') or year (mode: 'year') */
  max?: number;
  /** Reference date for age-based generation */
  refDate?: string | Date | number;
}): Date;

import { faker } from "@faker-js/faker";

// Generate adult birthdate (18-80 years old by default)
const adultBirthdate = faker.date.birthdate();

// Generate birthdate for specific age range
const youngAdultBirthdate = faker.date.birthdate({
  mode: 'age',
  min: 18,
  max: 35
});

// Generate birthdate for specific year range
const vintageBirthdate = faker.date.birthdate({
  mode: 'year',
  min: 1950,
  max: 1980
});

// Generate child birthdate with reference date
const childBirthdate = faker.date.birthdate({
  mode: 'age',
  min: 5,
  max: 12,
  refDate: '2023-01-01'
});

/**
 * Generate a random localized month name
 * @param options - Month name options
 * @returns Localized month name
 */
month(options?: {
  /** Whether to return an abbreviation */
  abbreviated?: boolean;
  /** Whether to return the name in the context of a date */
  context?: boolean;
}): string;

/**
 * Generate a random localized weekday name
 * @param options - Weekday name options
 * @returns Localized weekday name
 */
weekday(options?: {
  /** Whether to return an abbreviation */
  abbreviated?: boolean;
  /** Whether to return the name in the context of a date */
  context?: boolean;
}): string;

import { faker } from "@faker-js/faker";

// Generate month names
const fullMonth = faker.date.month();
// Example: 'October'

const abbrevMonth = faker.date.month({ abbreviated: true });
// Example: 'Oct'

const contextMonth = faker.date.month({ context: true });
// Example: 'October' (or locale-specific variant)

// Generate weekday names
const fullWeekday = faker.date.weekday();
// Example: 'Monday'

const abbrevWeekday = faker.date.weekday({ abbreviated: true });
// Example: 'Mon'

const contextWeekday = faker.date.weekday({ 
  abbreviated: true, 
  context: true 
});
// Example: 'Mon'

/**
 * Generate a random IANA time zone name
 * @returns IANA time zone identifier
 */
timeZone(): string;

import { faker } from "@faker-js/faker";

// Generate random time zone
const timezone = faker.date.timeZone();
// Example: 'Pacific/Guam'

// Generate multiple time zones
const timezones = Array.from({ length: 3 }, () => faker.date.timeZone());
// Example: ['America/New_York', 'Europe/London', 'Asia/Tokyo']

import { faker } from "@faker-js/faker";

faker.seed(123);
const date1 = faker.date.future();

faker.seed(123);
const date2 = faker.date.future();
// date1 === date2 (same result)