@alanszp/relative-date 16.4.3 → 16.5.0

package/README.md

@@ -0,0 +1,168 @@
+# 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:**
+
+```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 {
+        <<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
+```

package/dist/DateExpression.d.ts

@@ -0,0 +1,74 @@
+import { DateParser } from "./date-parser/DateParser";
+import { AbsoluteDateParser } from "./date-parser/AbsoluteDateParser";
+import { RelativeDateDecomposition, RelativeDateParser } from "./date-parser/RelativeDateParser";
+import { Modifier } from "./Modifier";
+export declare const INPUT_DATE_FORMAT = "yyyy-MM-dd";
+export declare class DateExpression {
+    /**
+     * Matches date expressions, that consist of a date part and an optional modifier part.
+     * The date part can be a absolute date or a relative date.
+     * The modifier part can be a modifier string or null.
+     */
+    private static readonly DATE_EXPRESSION_REGEX;
+    readonly raw: string;
+    readonly rawDate: string;
+    readonly modifier: Modifier | null;
+    protected readonly dateParser: DateParser;
+    /**
+     * @param raw - The raw date expression
+     * @throws InvalidDateExpression
+     * @throws InvalidModifier
+     */
+    private constructor();
+    get isNow(): boolean;
+    isRelativeDate(): this is DateExpression & {
+        dateParser: RelativeDateParser;
+    };
+    isAbsoluteDate(): this is DateExpression & {
+        dateParser: AbsoluteDateParser;
+    };
+    hasModifier(): this is DateExpression & {
+        modifier: Modifier;
+    };
+    toDate(): Date;
+    toAbsoluteString(): string;
+    /**
+     * Creates a new DateExpression with the specified modifier.
+     * If the current expression already has a modifier, it will be replaced.
+     * @param modifier - The modifier to apply
+     * @returns A new DateExpression instance with the specified modifier
+     */
+    modify(modifier: Modifier): DateExpression;
+    decomposeRelativeDate(this: DateExpression & {
+        dateParser: RelativeDateParser;
+    }): RelativeDateDecomposition;
+    /**
+     * Checks if a date expression is valid
+     * @param expression - The date expression to check
+     * @returns True if the date expression is valid, false otherwise
+     */
+    static isValid(expression: string): boolean;
+    static from(expression: string): DateExpression;
+    static now(): DateExpression;
+    static yesterday(): DateExpression;
+    /**
+     * Parses a date expression and returns the date part and modifier part
+     * @param expression - The date expression to parse
+     * @returns Object with datePart and modifierPart (null if no modifier)
+     */
+    private static parse;
+    toJSON(): {
+        raw: string;
+        rawDate: string;
+        modifier: {
+            extreme: "s" | "e";
+            unit: "b" | "q" | "s" | "w" | "m" | "t" | "y";
+        } | null;
+        isNow: boolean;
+        isRelativeDate: boolean;
+        isAbsoluteDate: boolean;
+        hasModifier: boolean;
+        toDate: Date;
+        toAbsoluteString: string;
+    };
+}

package/dist/DateExpression.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateExpression = exports.INPUT_DATE_FORMAT = void 0;
+const DateParserFactory_1 = require("./date-parser/DateParserFactory");
+const AbsoluteDateParser_1 = require("./date-parser/AbsoluteDateParser");
+const RelativeDateParser_1 = require("./date-parser/RelativeDateParser");
+const InvalidDateExpression_1 = require("./errors/InvalidDateExpression");
+const Modifier_1 = require("./Modifier");
+const date_fns_1 = require("date-fns");
+// Date format compliant with ISO
+exports.INPUT_DATE_FORMAT = "yyyy-MM-dd";
+class DateExpression {
+    /**
+     * @param raw - The raw date expression
+     * @throws InvalidDateExpression
+     * @throws InvalidModifier
+     */
+    constructor(raw) {
+        this.raw = raw;
+        const { rawDatePart, rawModifierPart } = DateExpression.parse(raw);
+        this.modifier = rawModifierPart ? Modifier_1.Modifier.from(rawModifierPart) : null;
+        this.rawDate = rawDatePart;
+        // Parsing of the date part is delegated to DateParser
+        this.dateParser = DateParserFactory_1.DateParserFactory.create(rawDatePart);
+    }
+    get isNow() {
+        return this.rawDate === "now";
+    }
+    isRelativeDate() {
+        return this.dateParser instanceof RelativeDateParser_1.RelativeDateParser;
+    }
+    isAbsoluteDate() {
+        return this.dateParser instanceof AbsoluteDateParser_1.AbsoluteDateParser;
+    }
+    hasModifier() {
+        return this.modifier !== null;
+    }
+    toDate() {
+        var _a, _b;
+        const date = this.dateParser.toJSDate(this.rawDate);
+        return (_b = (_a = this.modifier) === null || _a === void 0 ? void 0 : _a.apply(date)) !== null && _b !== void 0 ? _b : date;
+    }
+    toAbsoluteString() {
+        return (0, date_fns_1.format)(this.toDate(), exports.INPUT_DATE_FORMAT);
+    }
+    /**
+     * Creates a new DateExpression with the specified modifier.
+     * If the current expression already has a modifier, it will be replaced.
+     * @param modifier - The modifier to apply
+     * @returns A new DateExpression instance with the specified modifier
+     */
+    modify(modifier) {
+        const newExpression = `${this.rawDate}:${modifier.toString()}`;
+        return DateExpression.from(newExpression);
+    }
+    decomposeRelativeDate() {
+        if (this.isRelativeDate()) {
+            return this.dateParser.decompose(this.rawDate);
+        }
+        return null;
+    }
+    /**
+     * Checks if a date expression is valid
+     * @param expression - The date expression to check
+     * @returns True if the date expression is valid, false otherwise
+     */
+    static isValid(expression) {
+        try {
+            DateExpression.from(expression);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    // Builders
+    static from(expression) {
+        return new DateExpression(expression);
+    }
+    static now() {
+        return new DateExpression("now");
+    }
+    static yesterday() {
+        return new DateExpression("-1d");
+    }
+    /**
+     * Parses a date expression and returns the date part and modifier part
+     * @param expression - The date expression to parse
+     * @returns Object with datePart and modifierPart (null if no modifier)
+     */
+    static parse(expression) {
+        const match = this.DATE_EXPRESSION_REGEX.exec(expression);
+        if (!match) {
+            throw new InvalidDateExpression_1.InvalidDateExpression(expression);
+        }
+        const [_, rawDatePart, rawModifierPart] = match;
+        return {
+            rawDatePart: rawDatePart.trim(),
+            rawModifierPart: (rawModifierPart === null || rawModifierPart === void 0 ? void 0 : rawModifierPart.trim()) || null,
+        };
+    }
+    toJSON() {
+        var _a, _b;
+        return {
+            raw: this.raw,
+            rawDate: this.rawDate,
+            modifier: (_b = (_a = this.modifier) === null || _a === void 0 ? void 0 : _a.toJSON()) !== null && _b !== void 0 ? _b : null,
+            isNow: this.isNow,
+            isRelativeDate: this.isRelativeDate(),
+            isAbsoluteDate: this.isAbsoluteDate(),
+            hasModifier: this.hasModifier(),
+            toDate: this.toDate(),
+            toAbsoluteString: this.toAbsoluteString(),
+        };
+    }
+}
+exports.DateExpression = DateExpression;
+/**
+ * Matches date expressions, that consist of a date part and an optional modifier part.
+ * The date part can be a absolute date or a relative date.
+ * The modifier part can be a modifier string or null.
+ */
+DateExpression.DATE_EXPRESSION_REGEX = /^(.+?)(?:\s*:\s*(.+?))?\s*$/;
+//# sourceMappingURL=DateExpression.js.map

package/dist/DateExpression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DateExpression.js","sourceRoot":"","sources":["../src/DateExpression.ts"],"names":[],"mappings":"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"}

package/dist/DateExpression.test.d.ts

@@ -0,0 +1 @@
+export {};