Relative Date

Date Expressions

A date expression encapsulates the logic for absolute and relative date. They may contain an optional modifier

Modifiers

Modifiers allow you to adjust a date to the beginning or end of a specific time period. They are appended to date expressions using a colon (:) separator.

Syntax

<date_expression>:<modifier>

Where:

• <date_expression> is any valid date (absolute, relative, or "now")
• <modifier> follows the pattern [se]o[unit]
  • s = start of
  • e = end of
  • o = literal "o"
  • [unit] = time unit (see below)

Available Time Units

| Unit | Description | Example | | ---- | ------------------- | ------------------------- | | y | Year | eoy = end of year | | s | Semester (6 months) | sos = start of semester | | t | Third (4 months) | sot = start of third | | q | Quarter (3 months) | soq = start of quarter | | b | Bimester (2 months) | eob = end of bimester | | m | Month | eom = end of month | | w | Week | som = start of month |

Examples

Basic Usage:

// Start of month
DateExpression.from("2023-06-15:som"); // Returns 2023-06-01
DateExpression.from("now:som"); // Returns start of current month

// End of month
DateExpression.from("2023-06-15:eom"); // Returns 2023-06-30
DateExpression.from("now:eom"); // Returns end of current month

// Start of year
DateExpression.from("2023-06-15:soy"); // Returns 2023-01-01
DateExpression.from("now:soy"); // Returns start of current year

// End of year
DateExpression.from("2023-06-15:eoy"); // Returns 2023-12-31
DateExpression.from("now:eoy"); // Returns end of current year

With Relative Dates:

// Start of month for a date 5 days from now
DateExpression.from("+5d:som"); // Returns start of month for date 5 days from now

// End of quarter for a date 2 months ago
DateExpression.from("-2m:eoq"); // Returns end of quarter for date 2 months ago

// Start of year for yesterday
DateExpression.from("-1d:soy"); // Returns start of year for yesterday

Advanced Time Periods:

// Semester (6-month periods: Jan-Jun, Jul-Dec)
DateExpression.from("2023-04-15:sos"); // Returns 2023-01-01 (start of semester)
DateExpression.from("2023-08-15:eos"); // Returns 2023-12-31 (end of semester)

// Bimester (2-month periods: Jan-Feb, Mar-Apr, etc.)
DateExpression.from("2023-03-15:sob"); // Returns 2023-03-01 (start of bimester)
DateExpression.from("2023-05-15:eob"); // Returns 2023-04-30 (end of bimester)

// Third (4-month periods: Jan-Apr, May-Aug, Sep-Dec)
DateExpression.from("2023-06-15:sot"); // Returns 2023-05-01 (start of third)
DateExpression.from("2023-07-15:eot"); // Returns 2023-08-31 (end of third)

Week Boundaries:

// Start of week (Sunday by default)
DateExpression.from("2023-06-15:sow"); // Returns start of week containing June 15

// End of week (Saturday by default)
DateExpression.from("2023-06-15:eow"); // Returns end of week containing June 15

Quarter Boundaries:

// Quarters: Q1 (Jan-Mar), Q2 (Apr-Jun), Q3 (Jul-Sep), Q4 (Oct-Dec)
DateExpression.from("2023-05-15:soq"); // Returns 2023-04-01 (start of Q2)
DateExpression.from("2023-08-15:eoq"); // Returns 2023-09-30 (end of Q3)

Class Architecture

classDiagram
    class DateExpression {
        -raw: string
        -rawDate: string
        -modifier: Modifier | null
        -dateParser: DateParser
        +isNow: boolean
        +isRelativeDate(): boolean
        +isAbsoluteDate(): boolean
        +hasModifier(): boolean
        +toDate(): Date
        +toAbsoluteString(): string
        +modify(modifier: Modifier): DateExpression
        +decomposeRelativeDate(): RelativeDateDecomposition | null
        +toJSON(): object
        +static isValid(expression: string): boolean
        +static from(expression: string): DateExpression
        +static now(): DateExpression
        +static yesterday(): DateExpression
    }

    class Modifier {
        -extreme: PeriodModifierExtreme
        -unit: PeriodModifierTimeUnit

        +static startOf(unit: PeriodModifierTimeUnit): Modifier
        +static endOf(unit: PeriodModifierTimeUnit): Modifier
        +static from(modifier: string): Modifier

        +apply(date: Date): Date
        +isStart(): boolean
        +isEnd(): boolean
        +toString(): string
        +toJSON(): object
    }

    class DateParser {
        <<interface>>
        +toJSDate(raw: string): Date
    }

    class AbsoluteDateParser {
        +toJSDate(raw: string): Date
        +static isAbsoluteDate(raw: string): boolean
    }

    class RelativeDateParser {
        +toJSDate(raw: string): Date
        +decompose(raw: string): RelativeDateDecomposition
        +static isRelativeDate(raw: string): boolean
    }

    %% Relationships
    DateExpression --> Modifier : has optional
    DateExpression --> DateParser : uses

    DateParser <|.. AbsoluteDateParser : implements
    DateParser <|.. RelativeDateParser : implements