Relative Date

Date Expressions

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

$3

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

``
:
`

Where:

- is any valid date (absolute, relative, or "now")
- 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:

`javascript
// 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:

`javascript
// 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:

`javascript
// 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:

`javascript
// 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:

`javascript
// 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

`mermaid
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 {
<>
+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
``