chronolizer 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # Chronolizer
 
-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.
+Chronolizer is an Effect 4 library that converts natural-language date ranges to compact date filters and back. It supports ranges without a start or end, autocomplete, spelling correction, and eight languages.
 
 ```text
 year to date          → { gte: "now/y", lte: "now" }
@@ -9,11 +9,11 @@ since January 2025    → { gte: "2025-01-01" }
 ```
 
 > [!NOTE]
-> Chronolizer currently uses `effect@4.0.0-rc.112`. The API can change while Effect v4 has release-candidate status.
+> Chronolizer currently uses `effect@4.0.0-rc.112`. Effect 4 is not stable yet, so its API can change.
 
 ## Install Chronolizer
 
-Chronolizer requires Effect 4 and ESM. Install both packages as direct dependencies.
+Chronolizer requires Effect 4 and uses ES modules. Install both packages:
 
 ```sh
 pnpm add chronolizer effect@4.0.0-rc.112
@@ -21,7 +21,7 @@ pnpm add chronolizer effect@4.0.0-rc.112
 
 ## Parse your first date range
 
-English is available from the main package entry.
+English is available from the main package.
 
 ```ts
 import { EnglishLanguageLayer, formatFilter, parseNatural } from "chronolizer";
@@ -43,7 +43,7 @@ Effect.runPromise(program);
 
 ### Parse other languages
 
-Import each non-English language from its own package entry. This keeps unused languages out of your bundle.
+Import each non-English language separately. This keeps unused language code out of your build.
 
 ```ts
 import { formatFilter, parseNatural } from "chronolizer";
@@ -60,7 +60,7 @@ Effect.runPromise(program);
 // { gte: "now/y", lte: "now" }
 ```
 
-Use `languagePluginsLayer` when one application needs more than one language:
+Use `languagePluginsLayer` to combine languages:
 
 ```ts
 import { EnglishLanguage, languagePluginsLayer, parseNatural } from "chronolizer";
@@ -77,7 +77,7 @@ 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.
+`formatNatural` returns one standard phrase for a range. It preserves the meaning, but it does not reproduce the original wording. Absolute days use the language's numeric `Intl.DateTimeFormat` form.
 
 ```ts
 import { formatNatural, parseFilter } from "chronolizer";
@@ -96,7 +96,7 @@ Effect.runPromise(program);
 
 ### Add autocomplete
 
-`suggestNatural` returns valid canonical phrases and their semantic ranges.
+`suggestNatural` returns valid standard phrases and their date ranges.
 
 ```ts
 import { EnglishLanguageLayer, suggestNatural } from "chronolizer";
@@ -115,7 +115,7 @@ The default limit is 10. The maximum limit is 100. A nonpositive or invalid limi
 
 ### Accept spelling errors
 
-Set `typoMode` to `"tolerant"` for conservative correction:
+Set `typoMode` to `"tolerant"` to correct close spelling errors:
 
 ```ts
 const program = parseNatural("januray of last yaer", {
@@ -124,11 +124,11 @@ const program = parseNatural("januray of last yaer", {
 });
 ```
 
-The successful value contains its `quality`, applied `corrections`, and any semantic `alternatives`. Strict mode is the default and does not correct the input.
+The result contains its `quality`, applied `corrections`, and any `alternatives` with a different meaning. Strict mode is the default and does not correct the input.
 
-### Exclude future relative ranges
+### Exclude future ranges
 
-Set `allowFuture` to `false` to reject explicit relative future ranges:
+Set `allowFuture` to `false` to reject periods after the current period:
 
 ```ts
 const program = parseNatural("next 3 months", {
@@ -137,7 +137,7 @@ const program = parseNatural("next 3 months", {
 });
 ```
 
-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.
+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 ranges that end at the current time.
 
 The option does not compare fixed dates, such as `January 2099`, with the current date. Parsing does not read the clock.
 
@@ -145,7 +145,7 @@ The same option is available in `suggestNatural`.
 
 ### Resolve a range to dates
 
-Provide an Effect time zone when you resolve relative expressions:
+Provide an Effect time zone when you calculate ranges based on the current date:
 
 ```ts
 import { parseFilter, resolve } from "chronolizer";
@@ -159,7 +159,7 @@ const program = parseFilter({ gte: "now/y", lte: "now" }).pipe(
 Effect.runPromise(program);
 ```
 
-`resolve` uses the Effect clock and `DateTime.CurrentTimeZone`. It does not use the host time zone without your decision.
+`resolve` uses the Effect clock and `DateTime.CurrentTimeZone`. It uses only the time zone that you provide.
 
 ### Validate an external filter
 
@@ -176,18 +176,19 @@ const program = Schema.decodeUnknownEffect(DateFilter)(externalInput).pipe(
 Effect.runPromise(program);
 ```
 
-## Supported expressions
+## Supported input
 
-Supported input families include:
+You can parse:
 
-- 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;
+- days, weeks, months, quarters, and years;
+- ranges with a length, such as `last 3 months`;
+- single periods in the past or future, such as `30 months ago`;
+- ranges from a period start to now, such as `year to date`;
+- fixed months, quarters, years, and date ranges;
 - 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`;
+- ranges without one end, such as `since January 2025` and `from January 12`;
+- written counts from one through ninety-nine, such as `two weeks ago` and `twenty-one weeks ago`;
+- combined phrases, such as `the day before January 12` and `yesterday two weeks ago`;
 - period starts, period ends, and weekends;
 - abbreviated month names and common equivalent phrases.
 
@@ -206,16 +207,16 @@ Examples:
 
 ## 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`                  |
+| Language | Code | 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
 
@@ -229,32 +230,34 @@ A date filter has at least one bound. It can have one lower bound and one upper
 | `lte` | On or before the value      |
 
 An expression starts with `now` or an ISO date. Operations run from left to right.
+Calendar shifts are not combined or canceled. For example, `2025-01-31||+1M+1M`
+resolves to March 28, not March 31. Each month shift clamps the day to the last
+valid day of that month. Time-zone gaps can also affect intermediate dates.
 
 ```text
-expression := anchor operation*
-anchor     := "now" | YYYY-MM-DD | YYYY-MM-DD "||"
+expression := "now" operation* | YYYY-MM-DD | YYYY-MM-DD "||" operation+
 operation  := ("+" | "-") positiveInteger unit | "/" unit
 unit       := "d" | "w" | "M" | "q" | "y"
 ```
 
 `/unit` moves a value to the start of its calendar unit. Add `||` before operations on a fixed date, for example `2025-01-01||+1M`.
 
-Complete calendar periods use a half-open interval: the lower bound is inclusive and the next period start is exclusive. Weeks start on Monday.
+A complete calendar period includes its start but excludes the start of the next period. Weeks start on Monday.
 
 A named day without a year uses the current calendar year. Write the year for February 29 because parsing does not read the clock.
 
 ## Main API
 
-| 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 |
+| Export                | Purpose                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `parseNatural`        | Parse complete natural-language input to a date range      |
+| `formatNatural`       | Write a supported range as one standard phrase             |
+| `suggestNatural`      | Return autocomplete suggestions and date ranges            |
+| `parseFilter`         | Parse a date filter to a date range                        |
+| `formatFilter`        | Format a date range as a date filter                       |
+| `resolve`             | Calculate dates with an Effect clock and time zone         |
+| `DateFilter`          | Validate external date-filter data with Effect Schema      |
+| `DateRangeFromFilter` | Convert a filter in both directions with one Effect Schema |
 
 ## License
 

package/dist/ast/fold.mjs

@@ -1,19 +1,17 @@
-import { DateLiteral, GreaterThanOrEqual, LessThan, Now, Shift, StartOf } from "./schemas.mjs";
-import { Match, Schema, absurd } from "effect";
+import { GreaterThanOrEqual, LessThan, Now, Shift, StartOf } from "./schemas.mjs";
+import { Match, Schema } 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 foldInstant = (expression, algebra) => Match.typeTags()({
+	Now: () => algebra.now(),
+	DateLiteral: (literal) => algebra.dateLiteral(literal.value),
+	Shift: (operation) => algebra.shift(foldInstant(operation.base, algebra), operation.amount, operation.unit),
+	StartOf: (operation) => algebra.startOf(foldInstant(operation.base, algebra), operation.unit)
+})(expression);
 const shiftOffset = (base, amount, unit) => Match.value(unit).pipe(Match.when("year", () => ({
 	...base,
 	months: base.months + amount * 12

package/dist/ast/normalize.mjs

@@ -1,21 +1,12 @@
-import { Shift } from "./schemas.mjs";
 import { boundedRange, dateLiteral, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, lowerOpenRange, now, shift, startOf, upperOpenRange } from "./constructors.mjs";
-import { Match, Schema } from "effect";
+import { foldInstant } from "./fold.mjs";
+import { Match } from "effect";
 //#region src/ast/normalize.ts
-const isShift = Schema.is(Shift);
-const normalizeInstant = (expression) => Match.valueTags(expression, {
-	Now: () => now(),
-	DateLiteral: (literal) => dateLiteral(literal.value),
-	StartOf: (operation) => startOf(normalizeInstant(operation.base), operation.unit),
-	Shift: (operation) => {
-		const base = normalizeInstant(operation.base);
-		if (operation.amount === 0) return base;
-		if (isShift(base) && base.unit === operation.unit) {
-			const amount = base.amount + operation.amount;
-			if (Number.isSafeInteger(amount)) return normalizeInstant(shift(base.base, amount, operation.unit));
-		}
-		return shift(base, operation.amount, operation.unit);
-	}
+const normalizeInstant = (expression) => foldInstant(expression, {
+	now,
+	dateLiteral,
+	startOf,
+	shift: (base, amount, unit) => amount === 0 ? base : shift(base, amount, unit)
 });
 const normalizeLower = (bound) => Match.valueTags(bound, {
 	GreaterThan: (value) => greaterThan(normalizeInstant(value.value)),

package/dist/filter/codec.mjs

@@ -31,13 +31,12 @@ const formatUpper = Match.typeTags()({
 	LessThanOrEqual: (bound) => DateFilter.make({ lte: formatInstantExpression(bound.value) })
 });
 const formatFilter = (range) => {
-	const normalized = normalizeRange(range);
-	if (normalized.lower !== void 0 && normalized.upper !== void 0) return DateFilter.make({
-		...formatLower(normalized.lower),
-		...formatUpper(normalized.upper)
+	if (range.lower !== void 0 && range.upper !== void 0) return DateFilter.make({
+		...formatLower(range.lower),
+		...formatUpper(range.upper)
 	});
-	if (normalized.lower !== void 0) return formatLower(normalized.lower);
-	return formatUpper(normalized.upper);
+	if (range.lower !== void 0) return formatLower(range.lower);
+	return formatUpper(range.upper);
 };
 const rangeKey = (range) => {
 	const filter = formatFilter(range);

package/dist/filter/expression.mjs

@@ -1,7 +1,6 @@
 import { isIsoDate } from "../ast/schemas.mjs";
 import { dateLiteral, now, shift, startOf } from "../ast/constructors.mjs";
 import { foldInstant } from "../ast/fold.mjs";
-import { normalizeInstant } from "../ast/normalize.mjs";
 import { FilterExpressionParseError } from "./errors.mjs";
 import { Effect, Match } from "effect";
 //#region src/filter/expression.ts
@@ -14,25 +13,31 @@ const failAt = (input, offset, expected) => Effect.fail(new FilterExpressionPars
 }));
 const isDigit = (value) => value >= "0" && value <= "9";
 const isFirstPositiveDigit = (value) => value >= "1" && value <= "9";
+const parseAnchor = Effect.fn(function* (input) {
+	if (input.startsWith("now")) return {
+		expression: now(),
+		cursor: 3,
+		fixed: false
+	};
+	const candidate = input.slice(0, 10);
+	if (!isIsoDate(candidate)) return yield* failAt(input, 0, "\"now\" or an ISO date (YYYY-MM-DD)");
+	return {
+		expression: dateLiteral(candidate),
+		cursor: 10,
+		fixed: true
+	};
+});
+const operationStart = Effect.fn(function* (input, anchor) {
+	if (!anchor.fixed || anchor.cursor === input.length) return anchor.cursor;
+	if (input.slice(anchor.cursor, anchor.cursor + 2) !== "||") return yield* failAt(input, anchor.cursor, "\"||\" before date operations");
+	const cursor = anchor.cursor + 2;
+	if (cursor === input.length) return yield* failAt(input, cursor, "an operation beginning with \"+\", \"-\", or \"/\"");
+	return cursor;
+});
 const parseInstantExpression = Effect.fn(function* (input) {
-	let cursor = 0;
-	let expression;
-	let fixedAnchor = false;
-	if (input.startsWith("now")) {
-		expression = now();
-		cursor = 3;
-	} else {
-		const candidate = input.slice(0, 10);
-		if (!isIsoDate(candidate)) return yield* failAt(input, 0, "\"now\" or an ISO date (YYYY-MM-DD)");
-		expression = dateLiteral(candidate);
-		cursor = 10;
-		fixedAnchor = true;
-	}
-	if (fixedAnchor && cursor < input.length) {
-		if (input.slice(cursor, cursor + 2) !== "||") return yield* failAt(input, cursor, "\"||\" before date operations");
-		cursor += 2;
-		if (cursor === input.length) return yield* failAt(input, cursor, "an operation beginning with \"+\", \"-\", or \"/\"");
-	}
+	const anchor = yield* parseAnchor(input);
+	let expression = anchor.expression;
+	let cursor = yield* operationStart(input, anchor);
 	while (cursor < input.length) {
 		const operator = input[cursor];
 		if (operator === "/") {
@@ -60,7 +65,7 @@ const appendOperation = (base, operation) => ({
 	text: `${base.text}${base.fixedAnchor ? "||" : ""}${operation}`,
 	fixedAnchor: false
 });
-const formatInstantExpression = (expression) => foldInstant(normalizeInstant(expression), {
+const formatInstantExpression = (expression) => foldInstant(expression, {
 	now: () => ({
 		text: "now",
 		fixedAnchor: false
@@ -69,7 +74,7 @@ const formatInstantExpression = (expression) => foldInstant(normalizeInstant(exp
 		text: value,
 		fixedAnchor: true
 	}),
-	shift: (base, amount, unit) => appendOperation(base, `${amount < 0 ? "-" : "+"}${Math.abs(amount)}${symbolFromUnit(unit)}`),
+	shift: (base, amount, unit) => amount === 0 ? base : appendOperation(base, `${amount < 0 ? "-" : "+"}${Math.abs(amount)}${symbolFromUnit(unit)}`),
 	startOf: (base, unit) => appendOperation(base, `/${symbolFromUnit(unit)}`)
 }).text;
 //#endregion

package/dist/language/model.mjs

@@ -35,7 +35,7 @@ const NaturalSuggestion = Schema.Struct({
 var BaseLanguageContribution = class extends Data.TaggedClass("BaseLanguage") {};
 var LanguageExtensionContribution = class extends Data.TaggedClass("LanguageExtension") {};
 const canonicalBaseLocale = (input) => Result.getSuccess(Result.try(() => new Intl.Locale(input).baseName));
-const Locale = Schema.String.check(Schema.makeFilter((value) => Option.contains(canonicalBaseLocale(value), value), { expected: "a canonical BCP 47 base locale identifier" })).annotate({ identifier: "Locale" });
+const Locale = Schema.String.check(Schema.makeFilter((value) => Option.contains(canonicalBaseLocale(value), value), { expected: "a standard BCP 47 language code" })).annotate({ identifier: "Locale" });
 const BaseLanguageMetadata = Schema.TaggedStruct("BaseLanguage", {
 	locale: Locale,
 	vocabulary: Schema.Array(Schema.String)

package/dist/language/registry.mjs

@@ -45,28 +45,34 @@ const compileLanguage = (locale, registered) => {
 	}));
 };
 const createRegistry = Effect.fn(function* () {
-	const entries = yield* Ref.make([]);
+	const state = yield* Ref.make({
+		entries: [],
+		compiledLanguages: /* @__PURE__ */ new Map()
+	});
 	const register = Effect.fn(function* (pluginId, contribution) {
 		if (pluginId.length === 0 || !Schema.is(LanguageContributionMetadata)(contribution)) return yield* new LanguageRegistrationError({
 			pluginId,
 			locale: contribution.locale,
-			message: "Invalid plugin identifier or contribution metadata"
+			message: "The plugin name or language settings are invalid"
 		});
 		const token = Symbol(pluginId);
-		yield* Effect.acquireRelease(Ref.modify(entries, (current) => {
+		yield* Effect.acquireRelease(Ref.modify(state, (current) => {
 			const conflictingBase = Match.valueTags(contribution, {
-				BaseLanguage: (base) => Array.findFirst(current, (entry) => Match.valueTags(entry.contribution, {
+				BaseLanguage: (base) => Array.findFirst(current.entries, (entry) => Match.valueTags(entry.contribution, {
 					BaseLanguage: (registeredBase) => registeredBase.locale === base.locale,
 					LanguageExtension: () => false
 				})),
 				LanguageExtension: () => Option.none()
 			});
 			return Option.match(conflictingBase, {
-				onNone: () => [Result.succeed(token), Array.append(current, {
-					token,
-					pluginId,
-					contribution
-				})],
+				onNone: () => [Result.succeed(token), {
+					entries: Array.append(current.entries, {
+						token,
+						pluginId,
+						contribution
+					}),
+					compiledLanguages: /* @__PURE__ */ new Map()
+				}],
 				onSome: (conflict) => [Result.fail(new LanguageConflictError({
 					locale: contribution.locale,
 					firstPluginId: conflict.pluginId,
@@ -74,12 +80,28 @@ const createRegistry = Effect.fn(function* () {
 					message: "Only one base language can be registered for a locale"
 				})), current]
 			});
-		}).pipe(Effect.flatMap((result) => Effect.fromResult(result))), (registeredToken) => Ref.update(entries, (items) => Array.filter(items, (entry) => entry.token !== registeredToken)));
+		}).pipe(Effect.flatMap((result) => Effect.fromResult(result))), (registeredToken) => Ref.update(state, (current) => ({
+			entries: Array.filter(current.entries, (entry) => entry.token !== registeredToken),
+			compiledLanguages: /* @__PURE__ */ new Map()
+		})));
 	});
 	const resolve = Effect.fn(function* (locale) {
+		const cached = (yield* Ref.get(state)).compiledLanguages.get(locale);
+		if (cached !== void 0) return cached;
 		const canonical = canonicalBaseLocale(locale);
 		if (Option.isSome(canonical)) {
-			const compiled = compileLanguage(canonical.value, yield* Ref.get(entries));
+			const compiled = yield* Ref.modify(state, (current) => {
+				const canonicalCached = current.compiledLanguages.get(canonical.value);
+				if (canonicalCached !== void 0) return [Option.some(canonicalCached), current];
+				const language = compileLanguage(canonical.value, current.entries);
+				if (Option.isNone(language)) return [language, current];
+				const cache = new Map(current.compiledLanguages);
+				cache.set(canonical.value, language.value);
+				return [language, {
+					entries: current.entries,
+					compiledLanguages: cache
+				}];
+			});
 			if (Option.isSome(compiled)) return compiled.value;
 		}
 		return yield* new UnsupportedLocaleError({ locale });
@@ -102,7 +124,7 @@ const createPluginRegistry = Effect.fn(function* (plugins) {
 	if (duplicate !== void 0) return yield* new LanguageRegistrationError({
 		pluginId: duplicate,
 		locale: "*",
-		message: "Plugin identifiers must be unique"
+		message: "Plugin names must be unique"
 	});
 	const registry = yield* createRegistry();
 	const context = { register: registry.register };