@qrvey/formula-lang 3.1.0-rc.908 → 3.2.0-rc.1078

package/QRVEY-DATE-PRESETS.md

@@ -0,0 +1,709 @@
+# QDP Date Presets
+
+This document summarizes the current state of QDP Date Presets in Formula Lang: public API, output types, available functions, supported JSON, legacy tokens, calendar rules, and equivalences with the external date picker.
+
+The reference date used in this document's examples is `2026-07-22`, unless an example states otherwise. The QDP engine resolves dynamic values at execution time.
+
+## Purpose
+
+QDP Date Presets makes it possible to express date values produced by operators, legacy tokens, or external components such as the date picker. The output is resolved through Formula Lang, but restricted to the `QDP` engine and date-like result types.
+
+The API does not change the main grammar. It uses regular Formula Lang functions registered for `ENGINES.QDP`.
+
+## Public API
+
+The main APIs are in `src/date-presets.ts` and are exported from `src/index.ts`.
+
+```ts
+TranspileDatePreset(program: string, context?: FormulaContext): DatePresetTranspilationResponse | undefined
+```
+
+Compiles a QDP expression and returns a typed result. Only expressions whose final result is `date`, `dateRange`, or `partialDate` are valid.
+
+```ts
+TranspileJSONToDatePreset(input: DatePresetJSON | string): string
+```
+
+Converts a legacy token or date preset JSON object into a QDP expression.
+
+```ts
+FormatDatePreset(value: DatePresetValue, options?: DatePresetFormatOptions): DatePresetValue
+```
+
+Formats dates, ranges, and partial dates for UI.
+
+## Output Types
+
+```ts
+type DatePresetValue = string | DateRangeValue | PartialDateValue;
+```
+
+`date` is represented as an ISO string:
+
+```json
+"2026-07-22T00:00:00.000Z"
+```
+
+`dateRange` is represented as an object with `start` and `end`:
+
+```json
+{
+  "start": "2026-07-01T00:00:00.000Z",
+  "end": "2026-07-31T23:59:59.999Z"
+}
+```
+
+`partialDate` represents incomplete or recurring dates:
+
+```json
+{
+  "month": 4,
+  "day": 15
+}
+```
+
+Supported fields for `partialDate`:
+
+| Field | Meaning | Range |
+| --- | --- | --- |
+| `year` | Specific year | Integer |
+| `month` | Month | 1-12 |
+| `quarter` | Quarter | 1-4 |
+| `week` | Week | 1-54 |
+| `day` | Day of month | 1-31 |
+
+## Value Types
+
+`TranspileDatePreset` returns `valueType` to describe the nature of the value.
+
+| Value type | Meaning | Examples |
+| --- | --- | --- |
+| `fixed` | Fixed value or materialized range | `DATE("2026-07-20")`, `DATE_RANGE(...)` |
+| `recurring` | Partial pattern that repeats | `PARTIAL_DATE("ANY", 4)`, `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` |
+| `relative` | Period relative to the calendar or positioned inside a period | `CALENDAR_PERIOD("MONTH", 0)`, `PERIOD_AT("MONTH", 4, 2026)` |
+| `rolling` | Moving window from an anchor | `RELATIVE_PERIOD(-29, "DAY")` |
+
+Current note: `PERIOD_AT("MONTH", 4, 2026)` produces a concrete range, but it is classified as `relative` because the root expression is `PERIOD_AT`. If the business goal requires distinguishing `April 2026` as `fixed`, that would be a classification improvement, not a resolution change.
+
+## Resolution Context
+
+QDP functions can receive `FormulaContext` with date preset configuration:
+
+```ts
+{
+  datePreset: {
+    calendar: 'gregorian',
+    timezone: 'UTC',
+    locale: 'en-US',
+    fiscalYearStartMonth: 1,
+    fiscalYearStartDay: 1,
+    weekStartsOn: 0
+  }
+}
+```
+
+Current defaults:
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `calendar` | `gregorian` | Also supports `corporate-fiscal`, `retail-4-4-5`, `retail-4-5-4` |
+| `timezone` | `UTC` | Affects day starts/ends and periods |
+| `locale` | `en-US` | Used by formatting options |
+| `fiscalYearStartMonth` | `1` | Clamped to 1-12 |
+| `fiscalYearStartDay` | `1` | Clamped to 1-31 and adjusted to the last valid day of the month |
+| `weekStartsOn` | `0` | Sunday. Accepts 0-6 or English weekday names |
+
+Current week convention:
+
+- The default is Sunday (`weekStartsOn: 0`).
+- Week 1 of a year starts on the Sunday on or before Jan 1.
+- Some years can have W54 under this convention.
+- `PERIOD_AT("WEEK", "LAST", year)` is preferred for representing the last week of the year because it avoids hardcoding 52, 53, or 54.
+
+## QDP Date Preset Functions
+
+### `NOW()`
+
+Returns the current timestamp.
+
+```ts
+NOW()
+// 2026-07-22T23:42:50.413Z
+```
+
+Output: `date`.
+
+Value type when used as the final result: `fixed`.
+
+### `TODAY()`
+
+Returns the start of the current day in the context timezone.
+
+```ts
+TODAY()
+// 2026-07-22T00:00:00.000Z
+```
+
+Output: `date`.
+
+Value type when used as the final result: `fixed`.
+
+### `DATE(value)`
+
+Normalizes an ISO date or ISO date-time string to UTC ISO.
+
+```ts
+DATE("2026-07-20")
+// 2026-07-20T00:00:00.000Z
+```
+
+Supported input formats:
+
+| Input | Example | Resolved value |
+| --- | --- | --- |
+| ISO date | `DATE("2026-07-08")` | `2026-07-08T00:00:00.000Z` |
+| ISO date-time without timezone | `DATE("2026-07-08T15:30")` | `2026-07-08T15:30:00.000Z` |
+| ISO date-time with UTC timezone | `DATE("2026-07-08T15:30:45Z")` | `2026-07-08T15:30:45.000Z` |
+| ISO date-time with offset timezone | `DATE("2026-07-08T15:30:45-05:00")` | `2026-07-08T20:30:45.000Z` |
+
+Parameters:
+
+| Parameter | Type | Required | Validation |
+| --- | --- | --- | --- |
+| `VALUE` | `string` | Yes | ISO date or ISO date-time |
+
+Rules:
+
+- `DATE("2026-07-08")` is valid and resolves to `2026-07-08T00:00:00.000Z`.
+- Calendrically invalid dates, such as `DATE("2026-02-31T00:00")`, are rejected.
+- If the string does not include a timezone, UTC is assumed.
+
+Output: `date`.
+
+Value type: `fixed`.
+
+### `DATE_RANGE(start, end)`
+
+Builds a range between two dates.
+
+```ts
+DATE_RANGE(
+  DATE("2026-07-20"),
+  END_OF(DATE("2026-07-25"))
+)
+// { start: "2026-07-20T00:00:00.000Z", end: "2026-07-25T23:59:59.999Z" }
+```
+
+Parameters:
+
+| Parameter | Type | Required |
+| --- | --- | --- |
+| `START` | `date` | Yes |
+| `END` | `date` | Yes |
+
+Rules:
+
+- `END` must be greater than or equal to `START`.
+- If `END < START`, the function returns `INVALID_DATE_RANGE`.
+
+Output: `dateRange`.
+
+Value type: `fixed`.
+
+### `RELATIVE_PERIOD(offset, unit, anchor?)`
+
+Creates a moving window relative to an anchor. If no anchor is passed, it uses `TODAY()`.
+
+```ts
+RELATIVE_PERIOD(-29, "DAY")
+// { start: "2026-06-23T00:00:00.000Z", end: "2026-07-22T23:59:59.999Z" }
+```
+
+Parameters:
+
+| Parameter | Type | Required | Values |
+| --- | --- | --- | --- |
+| `OFFSET` | Integer `number` | Yes | Negative, zero, or positive |
+| `UNIT` | `string` | Yes | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `ANCHOR` | `date` | No | Base date |
+
+Semantics:
+
+- Negative offset: from `anchor + offset` to the end of the anchor day.
+- Positive offset: from the start of the anchor day to `anchor + offset`.
+- It is rolling and not necessarily aligned to calendar boundaries.
+
+Examples:
+
+```ts
+RELATIVE_PERIOD(-2, "WEEK", DATE("2026-07-08T15:30"))
+// 2026-06-24T00:00:00.000Z -> 2026-07-08T23:59:59.999Z
+```
+
+Output: `dateRange`.
+
+Value type: `rolling`.
+
+### `CALENDAR_PERIOD(period, offset?)`
+
+Returns a complete calendar period containing the current day, shifted by `offset`.
+
+```ts
+CALENDAR_PERIOD("MONTH", 0)
+// 2026-07-01T00:00:00.000Z -> 2026-07-31T23:59:59.999Z
+```
+
+Parameters:
+
+| Parameter | Type | Required | Values |
+| --- | --- | --- | --- |
+| `PERIOD` | `string` | Yes | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `OFFSET` | Integer `number` | No | Default `0` |
+
+Semantics:
+
+- `0` means the current period.
+- `-1` means the previous period.
+- `1` means the next period.
+- Respects calendar boundaries, timezone, fiscal calendar, and week start from the context.
+
+Examples:
+
+```ts
+CALENDAR_PERIOD("WEEK", 0)
+// with weekStartsOn Sunday: 2026-07-19T00:00:00.000Z -> 2026-07-25T23:59:59.999Z
+
+CALENDAR_PERIOD("QUARTER", -1)
+// 2026-04-01T00:00:00.000Z -> 2026-06-30T23:59:59.999Z
+```
+
+Output: `dateRange`.
+
+Value type: `relative`.
+
+### `PERIOD_AT(period, position, year?)`
+
+Returns the period located at a position inside a year. If `year` is not passed, it uses the current year from the context.
+
+```ts
+PERIOD_AT("MONTH", 4, 2026)
+// 2026-04-01T00:00:00.000Z -> 2026-04-30T23:59:59.999Z
+```
+
+Parameters:
+
+| Parameter | Type | Required | Values |
+| --- | --- | --- | --- |
+| `PERIOD` | `string` | Yes | `DAY`, `WEEK`, `MONTH`, `QUARTER` |
+| `POSITION` | Integer `number` or `string` | Yes | Number, `FIRST`, `LAST` |
+| `YEAR` | Integer `number` | No | Default: current year |
+
+Examples:
+
+```ts
+PERIOD_AT("QUARTER", 2, 2026)
+// 2026-04-01T00:00:00.000Z -> 2026-06-30T23:59:59.999Z
+
+PERIOD_AT("MONTH", "LAST", 2025)
+// 2025-12-01T00:00:00.000Z -> 2025-12-31T23:59:59.999Z
+
+PERIOD_AT("WEEK", "LAST", 2028)
+// 2028-12-31T00:00:00.000Z -> 2029-01-06T23:59:59.999Z
+```
+
+Week rules:
+
+- For `WEEK`, the start of the year is anchored to the start of the week that falls on or before the start of the year.
+- The last week can cross into the next year.
+- Numeric `POSITION` does not force an error if it points to a computable range outside the nominal year. For example, W54 can resolve by shifting even when the year does not nominally have W54.
+- `"MIDDLE"` and other strings different from `FIRST` or `LAST` are invalid.
+
+Output: `dateRange`.
+
+Current value type: `relative`.
+
+### `PARTIAL_DATE(year?, month?, quarter?, week?, day?)`
+
+Represents a partial or recurring date. Each field can be a number or `"ANY"`. Omitted fields are treated as `ANY`.
+
+```ts
+PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)
+// { month: 4, day: 15 }
+```
+
+Parameters:
+
+| Position | Field | Range | Example |
+| --- | --- | --- | --- |
+| 1 | `YEAR` | Integer or `ANY` | `2026` |
+| 2 | `MONTH` | 1-12 or `ANY` | `4` |
+| 3 | `QUARTER` | 1-4 or `ANY` | `2` |
+| 4 | `WEEK` | 1-54 or `ANY` | `40` |
+| 5 | `DAY` | 1-31 or `ANY` | `15` |
+
+Date picker examples:
+
+```ts
+PARTIAL_DATE()
+// {}
+// Short format: Any date
+
+PARTIAL_DATE("ANY", 4)
+// { month: 4 }
+// Short format: Apr
+
+PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)
+// { month: 4, day: 15 }
+// Short format: Apr 15
+
+PARTIAL_DATE("ANY", "ANY", 2)
+// { quarter: 2 }
+// Short format: Q2
+
+PARTIAL_DATE("ANY", "ANY", "ANY", 40)
+// { week: 40 }
+// Short format: W40
+
+PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15)
+// { day: 15 }
+// Short format: Day 15
+```
+
+Value type:
+
+- `fixed` if it includes `year`, `month`, and `day`, without `week`.
+- `relative` if it includes `week`.
+- `recurring` for all other partial dates.
+
+### `START_OF(value)`
+
+Returns the start of a `date` or the `start` of a `dateRange`.
+
+```ts
+START_OF(DATE("2026-07-08T15:30"))
+// 2026-07-08T00:00:00.000Z
+
+START_OF(CALENDAR_PERIOD("MONTH", -1))
+// 2026-06-01T00:00:00.000Z
+```
+
+Parameter:
+
+| Parameter | Type |
+| --- | --- |
+| `VALUE` | `date` or `dateRange` |
+
+Output: `date`.
+
+Value type when used as root: `relative`.
+
+### `END_OF(value)`
+
+Returns the end of a `date` or the `end` of a `dateRange`.
+
+```ts
+END_OF(DATE("2026-07-08T15:30"))
+// 2026-07-08T23:59:59.999Z
+
+END_OF(CALENDAR_PERIOD("YEAR", -1))
+// 2025-12-31T23:59:59.999Z
+```
+
+Parameter:
+
+| Parameter | Type |
+| --- | --- |
+| `VALUE` | `date` or `dateRange` |
+
+Output: `date`.
+
+Value type when used as root: `relative`.
+
+### `PART(date, part)`
+
+Extracts one part of a date.
+
+```ts
+PART(DATE("2026-07-08T15:30"), "DAY_OF_WEEK_NAME")
+// Wednesday
+```
+
+Parameters:
+
+| Parameter | Type | Values |
+| --- | --- | --- |
+| `DATE` | `date` | Resolved ISO date |
+| `PART` | `string` | See the table below |
+
+Supported parts:
+
+| Value | Output |
+| --- | --- |
+| `YEAR` | UTC year |
+| `QUARTER` | Quarter 1-4 |
+| `MONTH` | Month 1-12 |
+| `MONTH_NAME` | English month name |
+| `DAY` | Day of month |
+| `DAY_OF_MONTH` | Day of month |
+| `DAY_OF_WEEK` | UTC weekday, Sunday = 0 |
+| `DAY_OF_WEEK_NAME` | English weekday name |
+| `DAY_OF_YEAR` | Day of year |
+| `WEEK_OF_YEAR` | Week according to the current convention |
+| `HOUR` | UTC hour |
+| `MINUTE` | UTC minute |
+| `SECOND` | UTC second |
+
+Important: `PART` is available as a QDP function, but it is not a valid final result for `TranspileDatePreset` because it returns `string`. It can be used as a helper function when accessing the QDP transpiler directly, but a final date preset expression must return `date`, `dateRange`, or `partialDate`.
+
+## Differences Between Period Functions
+
+| Function | Question it answers | Example | Type |
+| --- | --- | --- | --- |
+| `CALENDAR_PERIOD` | What is this/previous/next calendar period? | This month, last week | `relative` |
+| `PERIOD_AT` | What is period N inside a year? | April 2026, Q2 2026, W40 2026 | Current `relative` |
+| `RELATIVE_PERIOD` | What is the moving window from today/anchor? | Last 30 days | `rolling` |
+
+Examples with current date `2026-07-22`:
+
+```ts
+CALENDAR_PERIOD("MONTH", -1)
+// previous calendar month: Jun 1 -> Jun 30
+
+PERIOD_AT("MONTH", 4, 2026)
+// fourth month of 2026: Apr 1 -> Apr 30
+
+RELATIVE_PERIOD(-29, "DAY")
+// last 30 days inclusive: Jun 23 -> Jul 22
+```
+
+It is not recommended to merge them into a single public function because they express different concepts. If unification is desired, the best layer is the picker JSON/contract, which can then compile to these explicit QDP functions.
+
+## Supported JSON
+
+`TranspileJSONToDatePreset` accepts legacy tokens as strings or JSON nodes.
+
+### Expression Nodes
+
+```ts
+{ type: 'NOW' }
+{ type: 'TODAY' }
+{ type: 'DATE', value: '2026-07-20' }
+{ type: 'DATE_RANGE', start: DatePresetJSON, end: DatePresetJSON }
+{ type: 'PARTIAL_DATE', value: { year?, quarter?, month?, week?, day? } }
+{ type: 'RELATIVE_PERIOD', offset: -30, unit: 'DAY', anchor?: DatePresetJSON }
+{ type: 'CALENDAR_PERIOD', period: 'MONTH', offset?: 0 }
+{ type: 'PERIOD_AT', period: 'MONTH', position: 4 | 'FIRST' | 'LAST', year?: 2026 }
+{ type: 'START_OF', input: DatePresetJSON }
+{ type: 'END_OF', input: DatePresetJSON }
+```
+
+Example:
+
+```ts
+TranspileJSONToDatePreset({
+  type: 'PERIOD_AT',
+  period: 'WEEK',
+  position: 'LAST',
+  year: 2028,
+})
+// PERIOD_AT("WEEK", "LAST", 2028)
+```
+
+### Form JSON
+
+Date picker oriented shapes are also supported:
+
+```ts
+{ type: 'SINGLE_PERIOD', date: { year: 2026, month: 7 } }
+// DATE_RANGE(DATE("2026-07-01"), END_OF(DATE("2026-07-31")))
+
+{ type: 'SINGLE_PERIOD', period: 'month', offset: -1 }
+// CALENDAR_PERIOD("MONTH", -1)
+
+{ type: 'CUSTOM_RANGE', from: { year: 2026, month: 5, day: 31 }, to: { year: 2026, month: 6, day: 30 } }
+// DATE_RANGE(DATE("2026-05-31"), END_OF(DATE("2026-06-30")))
+
+{ type: 'ROLLING_WINDOW', direction: 'last', amount: 30, unit: 'days' }
+// RELATIVE_PERIOD(-30, "DAY")
+```
+
+Rules:
+
+- `SINGLE_PERIOD` with `date` requires `year`.
+- `CUSTOM_RANGE` materializes dates with start-of-day and end-of-day boundaries.
+- `ROLLING_WINDOW` normalizes plural units by removing the final `s`.
+- `direction: 'NEXT'` produces a positive offset; any other value behaves as `LAST`.
+
+## Formatting
+
+`FormatDatePreset` formats values using `Intl.DateTimeFormat`.
+
+By default, `date` and `dateRange` values include time using `timeStyle: 'short'`. When `partialDateStyle: 'short'` is used and no explicit `timeStyle` is provided, `date` and `dateRange` values omit time so they align with picker-style labels. Passing `timeStyle` explicitly keeps time in the output.
+
+Main options:
+
+```ts
+{
+  locale?: 'en-US',
+  timezone?: 'UTC',
+  dateStyle?: 'full' | 'long' | 'medium' | 'short',
+  timeStyle?: 'full' | 'long' | 'medium' | 'short',
+  partialDateStyle?: 'long' | 'short'
+}
+```
+
+Examples:
+
+```ts
+FormatDatePreset('2026-07-15T14:35:27.000Z', {
+  locale: 'en-US',
+  timezone: 'America/Chicago',
+  dateStyle: 'medium',
+  timeStyle: 'short',
+})
+// Jul 15, 2026, 9:35 AM
+
+FormatDatePreset('2026-07-15T14:35:27.000Z', { partialDateStyle: 'short' })
+// Jul 15, 2026
+
+FormatDatePreset(
+  { start: '2026-07-01T00:00:00.000Z', end: '2026-07-31T23:59:59.999Z' },
+  { partialDateStyle: 'short' },
+)
+// { start: 'Jul 1, 2026', end: 'Jul 31, 2026' }
+
+FormatDatePreset({ month: 4, day: 15 })
+// April 15
+
+FormatDatePreset({ month: 4, day: 15 }, { partialDateStyle: 'short' })
+// Apr 15
+
+FormatDatePreset({ week: 40 }, { partialDateStyle: 'short' })
+// W40
+
+FormatDatePreset({ day: 15 }, { partialDateStyle: 'short' })
+// Day 15
+```
+
+## Legacy Tokens
+
+Legacy tokens are resolved with `TranspileJSONToDatePreset(token)` using `DATE_PRESET_TOKEN_MAP`.
+
+| Token | QDP expression |
+| --- | --- |
+| `NOW` | `NOW()` |
+| `TODAY` | `TODAY()` |
+| `CURRENT_DATE` | `TODAY()` |
+| `TODAY-7` | `START_OF(RELATIVE_PERIOD(-7, "DAY"))` |
+| `TODAY-30` | `START_OF(RELATIVE_PERIOD(-30, "DAY"))` |
+| `TODAY-60` | `START_OF(RELATIVE_PERIOD(-60, "DAY"))` |
+| `TODAY-90` | `START_OF(RELATIVE_PERIOD(-90, "DAY"))` |
+| `TODAY-120` | `START_OF(RELATIVE_PERIOD(-120, "DAY"))` |
+| `TODAY-365` | `START_OF(RELATIVE_PERIOD(-365, "DAY"))` |
+| `YESTERDAY` | `START_OF(RELATIVE_PERIOD(-1, "DAY"))` |
+| `TOMORROW` | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))` |
+| `CURRENT_MONTH` | `CALENDAR_PERIOD("MONTH", 0)` |
+| `CURRENT_MONTH_START` | `START_OF(CALENDAR_PERIOD("MONTH", 0))` |
+| `CURRENT_MONTH_END` | `END_OF(CALENDAR_PERIOD("MONTH", 0))` |
+| `LAST_MONTH` | `CALENDAR_PERIOD("MONTH", -1)` |
+| `LAST_MONTH_START` | `START_OF(CALENDAR_PERIOD("MONTH", -1))` |
+| `LAST_MONTH_END` | `END_OF(CALENDAR_PERIOD("MONTH", -1))` |
+| `CURRENT_WEEK` | `CALENDAR_PERIOD("WEEK", 0)` |
+| `CURRENT_WEEK_START` | `START_OF(CALENDAR_PERIOD("WEEK", 0))` |
+| `CURRENT_WEEK_END` | `END_OF(CALENDAR_PERIOD("WEEK", 0))` |
+| `LAST_WEEK` | `CALENDAR_PERIOD("WEEK", -1)` |
+| `LAST_WEEK_START` | `START_OF(CALENDAR_PERIOD("WEEK", -1))` |
+| `LAST_WEEK_END` | `END_OF(CALENDAR_PERIOD("WEEK", -1))` |
+| `CURRENT_QUARTER` | `CALENDAR_PERIOD("QUARTER", 0)` |
+| `CURRENT_QUARTER_START` | `START_OF(CALENDAR_PERIOD("QUARTER", 0))` |
+| `CURRENT_QUARTER_END` | `END_OF(CALENDAR_PERIOD("QUARTER", 0))` |
+| `LAST_QUARTER` | `CALENDAR_PERIOD("QUARTER", -1)` |
+| `LAST_QUARTER_START` | `START_OF(CALENDAR_PERIOD("QUARTER", -1))` |
+| `LAST_QUARTER_END` | `END_OF(CALENDAR_PERIOD("QUARTER", -1))` |
+| `CURRENT_YEAR` | `CALENDAR_PERIOD("YEAR", 0)` |
+| `CURRENT_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", 0))` |
+| `LAST_YEAR` | `CALENDAR_PERIOD("YEAR", -1)` |
+| `LAST_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", -1))` |
+| `LAST_YEAR_END` | `END_OF(CALENDAR_PERIOD("YEAR", -1))` |
+| `YEAR_BEFORE_LAST_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", -2))` |
+| `YEAR_BEFORE_LAST_YEAR_END` | `END_OF(CALENDAR_PERIOD("YEAR", -2))` |
+
+Tokens can be wrapped like `{{TODAY-7}}`. The normalizer removes braces and outer spaces.
+
+Scalar tokens such as `CURRENT_TIME`, `CURRENT_TIMEZONE`, and `CURRENT_DAY_OF_WEEK` are not supported as date presets because they do not return `date`, `dateRange`, or `partialDate`.
+
+## Main Equivalences With The Date Picker
+
+| Picker expression | QDP expression | Note |
+| --- | --- | --- |
+| Today | `TODAY()` | Fixed date at the start of the current day |
+| Yesterday | `START_OF(RELATIVE_PERIOD(-1, "DAY"))` | Start of yesterday |
+| Tomorrow | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))` | Start of tomorrow |
+| This month | `CALENDAR_PERIOD("MONTH", 0)` | Current calendar month |
+| Previous month | `CALENDAR_PERIOD("MONTH", -1)` | Previous calendar month |
+| Last 30 days inclusive | `RELATIVE_PERIOD(-29, "DAY")` | Inclusive 30-day rolling window counting today |
+| April | `PARTIAL_DATE("ANY", 4)` | Recurring month |
+| April 2026 | `PERIOD_AT("MONTH", 4, 2026)` | Positional month in a year |
+| Apr 15 | `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` | Recurring month/day |
+| Day 15 | `PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15)` | Recurring day of month |
+| Q2 | `PARTIAL_DATE("ANY", "ANY", 2)` | Recurring quarter |
+| Q2 2026 | `PERIOD_AT("QUARTER", 2, 2026)` | Positional quarter in a year |
+| W40 | `PARTIAL_DATE("ANY", "ANY", "ANY", 40)` | Recurring week |
+| W40 2026 | `PERIOD_AT("WEEK", 40, 2026)` | Positional week in a year |
+| Last week of 2028 | `PERIOD_AT("WEEK", "LAST", 2028)` | Avoids assuming W53/W54 |
+| Last month of the past year | `PERIOD_AT("MONTH", "LAST", 2025)` | Equivalent to December 2025 with current date 2026 |
+| Between inclusive | `DATE_RANGE(DATE(start), END_OF(DATE(end)))` | Materialize inclusive boundaries |
+| Between exclusive | `DATE_RANGE(DATE(adjustedStart), END_OF(DATE(adjustedEnd)))` | Materialize exclusion in the dates |
+
+## Validations And Expected Errors
+
+Important invalid cases:
+
+```ts
+DATE("2026-02-31")
+// INVALID_ALLOW_VALUE: calendrically invalid date
+
+DATE("2026-02-31T00:00")
+// INVALID_ALLOW_VALUE: calendrically invalid date
+
+RELATIVE_PERIOD(-1, "HOUR")
+// INVALID_ALLOW_VALUE: unsupported unit
+
+CALENDAR_PERIOD("DECADE", 0)
+// INVALID_ALLOW_VALUE: unsupported period
+
+PERIOD_AT("MONTH", "MIDDLE", 2026)
+// INVALID_ALLOW_VALUE: unsupported symbolic position
+
+PARTIAL_DATE("ANY", 13)
+// INVALID_ALLOW_VALUE: month out of range
+
+DATE_RANGE(DATE("2026-07-31T00:00"), DATE("2026-07-01T00:00"))
+// INVALID_DATE_RANGE: end before start
+```
+
+Additionally, any QDP expression whose final result is not `date`, `dateRange`, or `partialDate` returns `INVALID_DATE_PRESET_RESULT`.
+
+## Relevant Files
+
+| File | Responsibility |
+| --- | --- |
+| `src/date-presets.ts` | Public API, JSON conversion, formatting, and `valueType` classification |
+| `src/date-preset-tokens.ts` | Legacy token map to QDP expressions |
+| `src/functions/index.ts` | Function registration for `ENGINES.QDP` |
+| `src/functions/datePresetUtils.ts` | Date, range, calendar, week, timezone, and partial date resolution |
+| `src/functions/*.ts` | Individual QDP function definitions |
+| `__tests__/unit/datePresetTranspiler.test.ts` | Main transpilation and picker compatibility cases |
+| `__tests__/unit/datePresetJson.test.ts` | JSON to QDP conversion |
+| `__tests__/unit/datePresetFormat.test.ts` | Date and partial date formatting |
+| `__tests__/unit/datePresetTokens.test.ts` | Legacy tokens |
+| `date-preset-qdp-examples.csv` | Generated examples with tokens and picker expressions |
+
+## Current State And Design Notes
+
+- QDP is limited to date preset functions in `ENGINE_FN_MAP[ENGINES.QDP]`.
+- Date preset expressions can be nested as long as the final result is `date`, `dateRange`, or `partialDate`.
+- `partialDate` was added as a primitive to represent incomplete date picker selections.
+- Week compatibility with the date picker uses Sunday as the default start day and supports W54.
+- `PERIOD_AT` supports symbolic positions `FIRST` and `LAST` to reduce ambiguity in variable-length periods.
+- For documentation and example auditing, the CSV `date-preset-qdp-examples.csv` contains resolved, formatted, and classified values.