with

with()

Creates a new Chronos instance with the provided time component(s), using current values for any unspecified components.

Signature

static with(options: ChronosWithOptions): Chronos

Parameters

ChronosWithOptions Type

interface ChronosWithOptions {
  /** The full year (e.g., 2025). Years 0–99 are interpreted as 1900–1999. */
  year?: number;
  /** Month number from 1 (January) to 12 (December). */
  month?: NumberRange<1, 12>;
  /** Day of the month, from 1 to 31. */
  date?: NumberRange<1, 31>;
  /** Hour of the day, from 0 (midnight) to 23 (11 PM). */
  hour?: Enumerate<24>;
  /** Minutes of the hour, from 0 to 59. */
  minute?: Enumerate<60>;
  /** Seconds of the minute, from 0 to 59. */
  second?: Enumerate<60>;
  /** Milliseconds of the second, from 0 to 999. */
  millisecond?: Milliseconds;
}

Return Type

Chronos - A new instance with the provided time components applied

Behavior

• Partial Application: Only the specified components are changed; unspecified components use the current time's values
• Month Handling: Month values should be from 1 (January) to 12 (December)
• Date Preservation: If the current day is the last day of its month and the date component is omitted, the resulting instance will use the last day of the target month
• Date Override: If the date component is explicitly provided, it will be used even if it exceeds the last day of the target month and will follow the native Date constructor's behavior

Examples

Notes

• This method is useful for creating modified versions of the current date/time
• The original Chronos instance remains unchanged (immutable operation)
• Returns a new instance with the #ORIGIN set to 'with' for tracking purposes
• At least one option must be provided; empty options may return the current date-time but TypeScript will show a compile-time error message

Use Cases

• Scheduling future events based on current time
• Creating date variations for testing
• Building relative dates (e.g., "same time next month")
• Time component manipulation without affecting other components