chronolizer 0.1.0 → 0.3.0

package/README.md

@@ -1,195 +1,260 @@
 # Chronolizer
 
-Chronolizer is an Effect v4 library for bidirectional natural-language date ranges.
+Chronolizer is an Effect 4 library that converts natural-language date ranges to compact date-math filters and back. It supports open ranges, autocomplete, typo correction, and eight languages.
 
-It converts complete English and German date-range expressions to a small date-math format. It also renders supported ranges to canonical natural language and resolves the AST with an explicit Effect time zone.
+```text
+year to date          → { gte: "now/y", lte: "now" }
+January of last year  → { gte: "now-1y/y", lt: "now-1y/y+1M" }
+since January 2025    → { gte: "2025-01-01" }
+```
 
-## Status
+> [!NOTE]
+> Chronolizer currently uses `effect@4.0.0-rc.112`. The API can change while Effect v4 has release-candidate status.
 
-This package uses `effect@4.0.0-rc.112`. Its API can change while Effect v4 is in release-candidate status.
+## Install Chronolizer
 
-## Main concepts
+Chronolizer requires Effect 4 and ESM. Install both packages as direct dependencies.
 
-- Effect Schema owns the date AST, filter data, results, and errors.
-- Complete periods are half-open: `[start, next period start)`.
-- Open ranges are supported.
-- Weeks always start on Monday.
-- Parsing does not read the clock or host time zone.
-- Resolution requires `DateTime.CurrentTimeZone`.
-- Natural rendering is canonical. It does not reproduce the source wording.
-- Typo correction is conservative and optional. It does not change numbers, ISO dates, or short ambiguous words.
+```sh
+pnpm add chronolizer effect@4.0.0-rc.112
+```
 
-## Natural language to filter
+## Parse your first date range
+
+English is available from the main package entry.
 
 ```ts
-import { DefaultLanguageLayer, formatFilter, parseNatural } from "chronolizer";
+import { EnglishLanguageLayer, formatFilter, parseNatural } from "chronolizer";
 import { Effect } from "effect";
 
-const run = Effect.fn(function* () {
-  const result = yield* parseNatural("January of last year", {
-    locale: "en",
-    typoMode: "strict",
-  });
-
-  return formatFilter(result.range);
-}, Effect.provide(DefaultLanguageLayer));
-
-const program = run();
+const program = parseNatural("January of last year", { locale: "en" }).pipe(
+  Effect.map(({ range }) => formatFilter(range)),
+  Effect.tap((filter) => Effect.log("Date filter", filter)),
+  Effect.provide(EnglishLanguageLayer),
+);
 
+Effect.runPromise(program);
 // { gte: "now-1y/y", lt: "now-1y/y+1M" }
 ```
 
-Other examples:
+`parseNatural` parses the complete input. It does not extract a date range from a longer sentence.
 
-```text
-year to date                    -> { gte: "now/y", lte: "now" }
-January 2025                    -> { gte: "2025-01-01", lt: "2025-02-01" }
-since January 2025              -> { gte: "2025-01-01" }
-before January 2025             -> { lt: "2025-01-01" }
-through January 2025            -> { lt: "2025-02-01" }
-last 3 months                   -> { gte: "now-3M", lte: "now" }
-30 months ago                   -> { gte: "now-30M/M", lt: "now-30M/M+1M" }
-01 January 2025 - 31 January 2025
-                                -> { gte: "2025-01-01", lt: "2025-02-01" }
-Q1 2025                         -> { gte: "2025-01-01", lt: "2025-04-01" }
-Januar letzten Jahres           -> { gte: "now-1y/y", lt: "now-1y/y+1M" }
-die letzten 3 Monate            -> { gte: "now-3M", lte: "now" }
-seit Jahresbeginn               -> { gte: "now/y", lte: "now" }
-seit Januar 2025                -> { gte: "2025-01-01" }
-```
+## Common tasks
 
-Chronolizer parses the complete input. It does not extract a date phrase from a larger sentence.
+### Parse other languages
 
-Supported families include named and abbreviated months, named dates, quarters, weekends, period starts and ends, past and future rolling windows, calendar offsets, open boundaries, `now`-bounded ranges, and explicit inclusive connectors. English and German use their own grammar and canonical forms.
+Import each non-English language from its own package entry. This keeps unused languages out of your bundle.
 
-### Exclude positive relative ranges
+```ts
+import { formatFilter, parseNatural } from "chronolizer";
+import { GermanLanguageLayer } from "chronolizer/locales/de";
+import { Effect } from "effect";
 
-Set `allowFuture: false` to reject expressions whose relative range extends after `now`:
+const program = parseNatural("seit Jahresbeginn", { locale: "de" }).pipe(
+  Effect.map(({ range }) => formatFilter(range)),
+  Effect.tap((filter) => Effect.log("Datumsfilter", filter)),
+  Effect.provide(GermanLanguageLayer),
+);
 
-```ts
-const program = parseNatural("next 3 months", {
-  locale: "en",
-  allowFuture: false,
-});
+Effect.runPromise(program);
+// { gte: "now/y", lte: "now" }
 ```
 
-This option rejects relative forms such as `next month`, `this year`, and `in 3 years`. It does not classify fixed dates such as `January 2099`, because parsing does not read the clock.
-
-## Filter to natural language
+Use `languagePluginsLayer` when one application needs more than one language:
 
 ```ts
-import { DefaultLanguageLayer, formatNatural, parseFilter } from "chronolizer";
+import { EnglishLanguage, languagePluginsLayer, parseNatural } from "chronolizer";
+import { GermanLanguage } from "chronolizer/locales/de";
+import { PolishLanguage } from "chronolizer/locales/pl";
 import { Effect } from "effect";
 
-const run = Effect.fn(function* () {
-  const range = yield* parseFilter({
-    gte: "2025-01-01",
-    lt: "2025-02-01",
-  });
+const Languages = languagePluginsLayer([EnglishLanguage, GermanLanguage, PolishLanguage]);
 
-  return yield* formatNatural(range, { locale: "de" });
-}, Effect.provide(DefaultLanguageLayer));
+const program = parseNatural("letzten Monat", { locale: "de" }).pipe(Effect.provide(Languages));
 
-const program = run();
+Effect.runPromise(program);
+```
 
+### Format a range as natural language
+
+`formatNatural` returns the canonical phrase for a range. It preserves the meaning, but it does not reproduce the original wording. Absolute days use the locale's numeric `Intl.DateTimeFormat` form.
+
+```ts
+import { formatNatural, parseFilter } from "chronolizer";
+import { GermanLanguageLayer } from "chronolizer/locales/de";
+import { Effect } from "effect";
+
+const program = parseFilter({ gte: "2025-01-01", lt: "2025-02-01" }).pipe(
+  Effect.flatMap((range) => formatNatural(range, { locale: "de" })),
+  Effect.tap((text) => Effect.log("Date range", text)),
+  Effect.provide(GermanLanguageLayer),
+);
+
+Effect.runPromise(program);
 // "Januar 2025"
 ```
 
-Natural language is many-to-one. Chronolizer therefore guarantees semantic round trips, not the original words.
+### Add autocomplete
 
-## Validate external filters
-
-`parseFilter` accepts a validated `DateFilter`. Decode external data with the exported Schema first:
+`suggestNatural` returns valid canonical phrases and their semantic ranges.
 
 ```ts
-import { DateFilter, parseFilter } from "chronolizer";
-import { Effect, Schema } from "effect";
+import { EnglishLanguageLayer, suggestNatural } from "chronolizer";
+import { Effect } from "effect";
 
-const decodeDateFilter = Schema.decodeUnknownEffect(DateFilter);
+const program = suggestNatural("last m", { locale: "en", limit: 5 }).pipe(
+  Effect.tap((suggestions) => Effect.log("Suggestions", suggestions)),
+  Effect.provide(EnglishLanguageLayer),
+);
 
-const program = decodeDateFilter(externalInput).pipe(Effect.flatMap(parseFilter));
+Effect.runPromise(program);
+// [{ text: "last month", range: ... }, ...]
 ```
 
-A filter has at most one lower bound (`gt` or `gte`), at most one upper bound (`lt` or `lte`), and at least one bound.
+The default limit is 10. The maximum limit is 100. A nonpositive or invalid limit returns no suggestions.
 
-## Compact expression syntax
+### Accept spelling errors
 
-```text
-expression := anchor operation*
-anchor     := "now" | YYYY-MM-DD | YYYY-MM-DD "||"
-operation  := ("+" | "-") positiveInteger unit | "/" unit
-unit       := "d" | "w" | "M" | "q" | "y"
+Set `typoMode` to `"tolerant"` for conservative correction:
+
+```ts
+const program = parseNatural("januray of last yaer", {
+  locale: "en",
+  typoMode: "tolerant",
+});
 ```
 
-Examples:
+The successful value contains its `quality`, applied `corrections`, and any semantic `alternatives`. Strict mode is the default and does not correct the input.
 
-```text
-now/y
-now-1y/y
-now-1y/y+1M
-2025-01-01
-2025-01-01||+1M
+### Exclude future relative ranges
+
+Set `allowFuture` to `false` to reject explicit relative future ranges:
+
+```ts
+const program = parseNatural("next 3 months", {
+  locale: "en",
+  allowFuture: false,
+});
 ```
 
-Operations run from left to right. `/unit` floors to the start of the calendar unit. Fixed dates require `||` before operations.
+This option rejects forms such as `next month`, `next 3 weeks`, and `in 3 years`. It keeps complete current calendar periods such as `today`, `this week`, and `this month`. It does not change them to period-to-date ranges.
+
+The option does not compare fixed dates, such as `January 2099`, with the current date. Parsing does not read the clock.
+
+The same option is available in `suggestNatural`.
+
+### Resolve a range to dates
 
-## Resolve with an explicit time zone
+Provide an Effect time zone when you resolve relative expressions:
 
 ```ts
 import { parseFilter, resolve } from "chronolizer";
 import { DateTime, Effect } from "effect";
 
-const run = Effect.fn(function* () {
-  const range = yield* parseFilter({ gte: "now/y", lte: "now" });
-  return yield* resolve(range);
-}, DateTime.withCurrentZoneNamed("Europe/Berlin"));
+const program = parseFilter({ gte: "now/y", lte: "now" }).pipe(
+  Effect.flatMap(resolve),
+  DateTime.withCurrentZoneNamed("Europe/Berlin"),
+);
 
-const program = run();
+Effect.runPromise(program);
 ```
 
-The resolver uses Effect Clock and `DateTime.CurrentTimeZone`. It never uses the host local time zone without an explicit caller decision. Named zones use the runtime ICU time-zone data.
+`resolve` uses the Effect clock and `DateTime.CurrentTimeZone`. It does not use the host time zone without your decision.
 
-## Tolerant parsing
+### Validate an external filter
+
+Use the exported Effect Schema before you parse unknown data:
 
 ```ts
-const program = parseNatural("januray of last yaer", {
-  locale: "en",
-  typoMode: "tolerant",
-});
-```
+import { DateFilter, parseFilter } from "chronolizer";
+import { Effect, Schema } from "effect";
 
-The result reports:
+const program = Schema.decodeUnknownEffect(DateFilter)(externalInput).pipe(
+  Effect.flatMap(parseFilter),
+);
 
-- `quality`: `exact`, `corrected`, or `ambiguous`;
-- each correction and edit distance;
-- semantic alternatives for equal-cost ties.
+Effect.runPromise(program);
+```
 
-Strict mode never runs correction.
+## Supported expressions
 
-## Language plugins
+Supported input families include:
 
-`LanguageRegistry` is an Effect service. A language is a scoped plugin contribution. `languagePluginsLayer` validates plugin identifiers, rejects conflicting base languages, applies deterministic extension order, and removes registrations when the Layer scope closes.
+- calendar days, weeks, months, quarters, and years;
+- rolling ranges, such as `last 3 months`;
+- calendar offsets, such as `30 months ago`;
+- period-to-date ranges, such as `year to date`;
+- fixed months, quarters, years, and explicit date intervals;
+- named days with or without a year, such as `January 12` and `12th of January`;
+- open ranges, such as `since January 2025` and `from January 12`;
+- compositional boundaries, such as `the day before January 12`;
+- period starts, period ends, and weekends;
+- abbreviated month names and common equivalent phrases.
 
-Language identifiers use canonical BCP 47 base tags. Lookup removes one subtag at a time. For example, `zh-Hant-TW` tries `zh-Hant-TW`, `zh-Hant`, and then `zh`.
+Examples:
 
-Each base language owns:
+| Input                               | Filter                                     |
+| ----------------------------------- | ------------------------------------------ |
+| `today`                             | `{ gte: "now/d", lt: "now/d+1d" }`         |
+| `last 3 months`                     | `{ gte: "now-3M", lte: "now" }`            |
+| `30 months ago`                     | `{ gte: "now-30M/M", lt: "now-30M/M+1M" }` |
+| `January 2025`                      | `{ gte: "2025-01-01", lt: "2025-02-01" }`  |
+| `January 12`                        | `{ gte: "now/y+11d", lt: "now/y+12d" }`    |
+| `Q1 2025`                           | `{ gte: "2025-01-01", lt: "2025-04-01" }`  |
+| `01 January 2025 - 31 January 2025` | `{ gte: "2025-01-01", lt: "2025-02-01" }`  |
+| `through January 2025`              | `{ lt: "2025-02-01" }`                     |
+
+## Supported languages
+
+| Language | Locale | Import                                    |
+| -------- | ------ | ----------------------------------------- |
+| English  | `en`   | `chronolizer` or `chronolizer/locales/en` |
+| German   | `de`   | `chronolizer/locales/de`                  |
+| Spanish  | `es`   | `chronolizer/locales/es`                  |
+| French   | `fr`   | `chronolizer/locales/fr`                  |
+| Dutch    | `nl`   | `chronolizer/locales/nl`                  |
+| Turkish  | `tr`   | `chronolizer/locales/tr`                  |
+| Czech    | `cs`   | `chronolizer/locales/cs`                  |
+| Polish   | `pl`   | `chronolizer/locales/pl`                  |
+
+## Date filter reference
+
+A date filter has at least one bound. It can have one lower bound and one upper bound.
+
+| Key   | Meaning                     |
+| ----- | --------------------------- |
+| `gt`  | After the value, exclusive  |
+| `gte` | On or after the value       |
+| `lt`  | Before the value, exclusive |
+| `lte` | On or before the value      |
+
+An expression starts with `now` or an ISO date. Operations run from left to right.
 
-- exact parsing and canonical rendering;
-- optional text normalization;
-- its typo-correction strategy, which can be disabled;
-- vocabulary shared with registered language extensions.
+```text
+expression := anchor operation*
+anchor     := "now" | YYYY-MM-DD | YYYY-MM-DD "||"
+operation  := ("+" | "-") positiveInteger unit | "/" unit
+unit       := "d" | "w" | "M" | "q" | "y"
+```
 
-`normalizeNaturalText` and `correctWhitespaceSeparatedText` are available for languages that use whitespace-separated words. A compact-script language can provide character, dictionary, or `Intl.Segmenter` based correction without changing Chronolizer core.
+`/unit` moves a value to the start of its calendar unit. Add `||` before operations on a fixed date, for example `2025-01-01||+1M`.
 
-Built-in plugins:
+Complete calendar periods use a half-open interval: the lower bound is inclusive and the next period start is exclusive. Weeks start on Monday.
 
-- `EnglishLanguage`
-- `GermanLanguage`
-- `DefaultLanguageLayer`
+A named day without a year uses the current calendar year. Write the year for February 29 because parsing does not read the clock.
 
-Chinese and Japanese language packs are not included yet.
+## Main API
 
-Business calendars, holidays, times of day, recurrence, and sentence extraction are outside v1. A future business-day feature will use an injected calendar service.
+| Export                | Purpose                                                             |
+| --------------------- | ------------------------------------------------------------------- |
+| `parseNatural`        | Parse complete natural-language input to a semantic range           |
+| `formatNatural`       | Render a supported range as a canonical phrase                      |
+| `suggestNatural`      | Return autocomplete suggestions and semantic ranges                 |
+| `parseFilter`         | Parse a date filter to a semantic range                             |
+| `formatFilter`        | Format a semantic range as a date filter                            |
+| `resolve`             | Resolve a semantic range with an Effect clock and time zone         |
+| `DateFilter`          | Validate external date-filter data with Effect Schema               |
+| `DateRangeFromFilter` | Decode and encode a filter through one Effect Schema transformation |
 
 ## License
 

package/dist/ast/constructors.d.mts

@@ -0,0 +1,135 @@
+import { DateLiteral, InstantExpr, IsoDate, LowerBound, Now, Shift, StartOf, Unit, UpperBound } from "./schemas.mjs";
+//#region src/ast/constructors.d.ts
+declare const now: () => Now;
+declare const dateLiteral: (value: IsoDate) => DateLiteral;
+declare const shift: (base: InstantExpr, amount: number, unit: Unit) => Shift;
+declare const startOf: (base: InstantExpr, unit: Unit) => StartOf;
+declare const greaterThan: (value: InstantExpr) => {
+  readonly _tag: "GreaterThan";
+  readonly value: InstantExpr;
+};
+declare const greaterThanOrEqual: (value: InstantExpr) => {
+  readonly _tag: "GreaterThanOrEqual";
+  readonly value: InstantExpr;
+};
+declare const lessThan: (value: InstantExpr) => {
+  readonly _tag: "LessThan";
+  readonly value: InstantExpr;
+};
+declare const lessThanOrEqual: (value: InstantExpr) => {
+  readonly _tag: "LessThanOrEqual";
+  readonly value: InstantExpr;
+};
+declare const boundedRange: (lower: LowerBound, upper: UpperBound) => {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+} | {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper?: never;
+} | {
+  readonly _tag: "DateRange";
+  readonly lower?: never;
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+};
+declare const lowerOpenRange: (lower: LowerBound) => {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+} | {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper?: never;
+} | {
+  readonly _tag: "DateRange";
+  readonly lower?: never;
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+};
+declare const upperOpenRange: (upper: UpperBound) => {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+} | {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper?: never;
+} | {
+  readonly _tag: "DateRange";
+  readonly lower?: never;
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+};
+//#endregion
+export { boundedRange, dateLiteral, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, lowerOpenRange, now, shift, startOf, upperOpenRange };

package/dist/ast/constructors.mjs

@@ -0,0 +1,25 @@
+import { DateLiteral, DateRangeExpr, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, Now, Shift, StartOf } from "./schemas.mjs";
+//#region src/ast/constructors.ts
+const now = () => Now.make({});
+const dateLiteral = (value) => DateLiteral.make({ value });
+const shift = (base, amount, unit) => Shift.make({
+	base,
+	amount,
+	unit
+});
+const startOf = (base, unit) => StartOf.make({
+	base,
+	unit
+});
+const greaterThan = (value) => GreaterThan.make({ value });
+const greaterThanOrEqual = (value) => GreaterThanOrEqual.make({ value });
+const lessThan = (value) => LessThan.make({ value });
+const lessThanOrEqual = (value) => LessThanOrEqual.make({ value });
+const boundedRange = (lower, upper) => DateRangeExpr.make({
+	lower,
+	upper
+});
+const lowerOpenRange = (lower) => DateRangeExpr.make({ lower });
+const upperOpenRange = (upper) => DateRangeExpr.make({ upper });
+//#endregion
+export { boundedRange, dateLiteral, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, lowerOpenRange, now, shift, startOf, upperOpenRange };

package/dist/ast/fold.d.mts

@@ -0,0 +1,13 @@
+import { DateRangeExpr, InstantExpr, IsoDate, Unit } from "./schemas.mjs";
+//#region src/ast/fold.d.ts
+interface InstantAlgebra<A> {
+  readonly now: () => A;
+  readonly dateLiteral: (value: IsoDate) => A;
+  readonly shift: (base: A, amount: number, unit: Unit) => A;
+  readonly startOf: (base: A, unit: Unit) => A;
+}
+declare const foldInstant: <A>(expression: InstantExpr, algebra: InstantAlgebra<A>) => A;
+declare const containsPositiveShift: (range: DateRangeExpr) => boolean;
+declare const isCurrentPeriod: (range: DateRangeExpr) => boolean;
+//#endregion
+export { InstantAlgebra, containsPositiveShift, foldInstant, isCurrentPeriod };

package/dist/ast/fold.mjs

@@ -0,0 +1,58 @@
+import { DateLiteral, GreaterThanOrEqual, LessThan, Now, Shift, StartOf } from "./schemas.mjs";
+import { Match, Schema, absurd } from "effect";
+//#region src/ast/fold.ts
+const isDateLiteral = Schema.is(DateLiteral);
+const isGreaterThanOrEqual = Schema.is(GreaterThanOrEqual);
+const isLessThan = Schema.is(LessThan);
+const isNow = Schema.is(Now);
+const isShift = Schema.is(Shift);
+const isStartOf = Schema.is(StartOf);
+const foldInstant = (expression, algebra) => {
+	if (isNow(expression)) return algebra.now();
+	if (isDateLiteral(expression)) return algebra.dateLiteral(expression.value);
+	if (isShift(expression)) return algebra.shift(foldInstant(expression.base, algebra), expression.amount, expression.unit);
+	if (isStartOf(expression)) return algebra.startOf(foldInstant(expression.base, algebra), expression.unit);
+	return absurd(expression);
+};
+const shiftOffset = (base, amount, unit) => Match.value(unit).pipe(Match.when("year", () => ({
+	...base,
+	months: base.months + amount * 12
+})), Match.when("quarter", () => ({
+	...base,
+	months: base.months + amount * 3
+})), Match.when("month", () => ({
+	...base,
+	months: base.months + amount
+})), Match.when("week", () => ({
+	...base,
+	days: base.days + amount * 7
+})), Match.when("day", () => ({
+	...base,
+	days: base.days + amount
+})), Match.exhaustive);
+const containsPositiveShiftInstant = (expression) => {
+	const offset = foldInstant(expression, {
+		now: () => ({
+			months: 0,
+			days: 0
+		}),
+		dateLiteral: () => ({
+			months: 0,
+			days: 0
+		}),
+		shift: shiftOffset,
+		startOf: (base) => base
+	});
+	return offset.months > 0 || offset.days > 0;
+};
+const containsPositiveShift = (range) => range.lower !== void 0 && containsPositiveShiftInstant(range.lower.value) || range.upper !== void 0 && containsPositiveShiftInstant(range.upper.value);
+const isCurrentPeriod = (range) => {
+	if (!isGreaterThanOrEqual(range.lower) || !isLessThan(range.upper)) return false;
+	const start = range.lower.value;
+	const end = range.upper.value;
+	if (!isStartOf(start) || !isNow(start.base) || !isShift(end)) return false;
+	if (end.amount !== 1 || !isStartOf(end.base) || !isNow(end.base.base)) return false;
+	return start.unit === end.unit && start.unit === end.base.unit;
+};
+//#endregion
+export { containsPositiveShift, foldInstant, isCurrentPeriod };

package/dist/ast/normalize.d.mts

@@ -0,0 +1,42 @@
+import { DateRangeExpr, InstantExpr } from "./schemas.mjs";
+//#region src/ast/normalize.d.ts
+declare const normalizeInstant: (expression: InstantExpr) => InstantExpr;
+declare const normalizeRange: (range: DateRangeExpr) => {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+} | {
+  readonly _tag: "DateRange";
+  readonly lower: {
+    readonly _tag: "GreaterThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "GreaterThanOrEqual";
+    readonly value: InstantExpr;
+  };
+  readonly upper?: never;
+} | {
+  readonly _tag: "DateRange";
+  readonly lower?: never;
+  readonly upper: {
+    readonly _tag: "LessThan";
+    readonly value: InstantExpr;
+  } | {
+    readonly _tag: "LessThanOrEqual";
+    readonly value: InstantExpr;
+  };
+};
+//#endregion
+export { normalizeInstant, normalizeRange };