@jarenjs/core 0.46.5 → 0.56.0

package/src/dates/civil.js

@@ -205,7 +205,26 @@ export function fixedUnitMs(unit) {
 
 //#endregion
 
-//#region arithmetic over parts
+//#region lexical precision
+
+// A parts record spells one of three lexical families (rfc3339.js): a
+// full-date with no clock, a full-time with no calendar, or both. An
+// operation that reads a half the value has not got has no answer, and
+// the alternative to refusing is to guess one - which is how `end-of`
+// hour on a full-date used to answer the day BEFORE it, and how adding
+// a day to a full-time used to be a silent no-op.
+//
+// Which half an operation reads follows from its unit:
+//
+//   year, quarter, month     the calendar; a full-time has none
+//   week, day                the calendar, plus the clock when the
+//                            amount carries a fraction of a day
+//   hour .. millisecond      the clock; a full-date has none
+//
+// `day` and coarser truncate to a boundary a calendar has, so
+// `start-of` day of a full-time is midnight and needs no date. A
+// sub-day truncation names a boundary INSIDE a day, which a value with
+// no clock does not have.
 
 // A parts record with no time half reads -1 for hours/minutes/seconds;
 // arithmetic treats that as midnight but must not *introduce* a time, so
@@ -214,6 +233,48 @@ function hasTime(parts) {
   return parts.hours >= 0;
 }
 
+/** Whether a parts record carries a calendar half. */
+function hasDate(parts) {
+  return parts.year >= 0;
+}
+
+function requireDate(parts, unit) {
+  if (!hasDate(parts))
+    throw new TypeError(`'${unit}' needs a date half, and this value has none`);
+}
+
+function requireTime(parts, unit) {
+  if (!hasTime(parts))
+    throw new TypeError(`'${unit}' needs a time half, and this value has none`);
+}
+
+/**
+ * Split a millisecond offset into a day into clock fields. `seconds`
+ * carries the fraction, as everywhere else in this module.
+ * @param {number} rest - milliseconds since midnight, [0, 86400000)
+ * @returns {{ hours: number, minutes: number, seconds: number }}
+ */
+function clockFromDayMs(rest) {
+  const hours = Math.floor(rest / 3600000);
+  rest -= hours * 3600000;
+  const minutes = Math.floor(rest / 60000);
+  rest -= minutes * 60000;
+  return { hours, minutes, seconds: rest / 1000 };
+}
+
+/** Milliseconds since midnight for a parts record that carries a clock. */
+function dayMsOf(parts) {
+  return parts.hours * 3600000 + parts.minutes * 60000 + Math.round(parts.seconds * 1000);
+}
+
+//#endregion
+
+//#region arithmetic over parts
+
+// how many months each calendar unit is worth; a fraction of one of
+// these is only a quantity when it converts to a whole month
+const CALENDAR_MONTHS = Object.freeze({ year: 12, quarter: 3, month: 1 });
+
 function withTime(out, parts, hours, minutes, seconds) {
   if (hasTime(parts)) {
     out.hours = hours;
@@ -233,68 +294,91 @@ function withTime(out, parts, hours, minutes, seconds) {
 /**
  * Add a signed amount of calendar units to a parts record, returning a
  * new one. The input is never mutated and its lexical shape is kept: a
- * full-date stays a full-date, and a value keeps its own UTC offset
- * rather than being normalized.
+ * full-date stays a full-date, a full-time stays a full-time, and a
+ * value keeps its own UTC offset rather than being normalized.
  *
  * Month and year arithmetic **clamps** to the end of the target month —
  * 2026-01-31 plus one month is 2026-02-28 — which is the rule every
  * mainstream date library uses, because the alternative (overflowing
  * into March) makes `add(1, 'month')` non-monotonic.
  *
+ * A fraction is a quantity only where the unit has an exact conversion.
+ * A fixed-width fraction becomes whole milliseconds, so `1.5 day` is
+ * thirty-six hours; a calendar fraction is refused unless it lands on a
+ * whole month, because half of January is not a length. The clock those
+ * milliseconds land on has to exist: a full-date can be moved by whole
+ * days but not by half of one.
+ *
  * @param {object} parts - a parts record from `parseRFC3339Parts`
- * @param {number} amount - signed count, may be fractional only for
- *   fixed-width units (a fractional month has no meaning)
+ * @param {number} amount - signed count, fractional only where the unit
+ *   converts exactly and the value has the half to carry it
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, a fraction with no exact
+ *   conversion, or a value missing a half the operation reads
  */
 export function addToParts(parts, amount, unit) {
   if (amount === 0)
     return { ...parts };
-  if (unit === 'year' || unit === 'quarter' || unit === 'month') {
-    const months = unit === 'year' ? amount * 12 : unit === 'quarter' ? amount * 3 : amount;
-    const total = (parts.year * 12 + (parts.month - 1)) + Math.trunc(months);
+  const perMonth = CALENDAR_MONTHS[unit];
+  if (perMonth !== undefined) {
+    const months = amount * perMonth;
+    if (!Number.isInteger(months))
+      throw new TypeError(`a fraction of a '${unit}' has no exact calendar length`);
+    requireDate(parts, unit);
+    const total = (parts.year * 12 + (parts.month - 1)) + months;
     const year = Math.floor(total / 12);
     const month = total - year * 12 + 1;
     const day = Math.min(parts.day, daysInMonth(year, month)); // clamp
     return withTime({ year, month, day }, parts, parts.hours, parts.minutes, parts.seconds);
   }
+  const width = FIXED_MS[unit];
+  if (width === undefined)
+    throw new TypeError(`'${unit}' is not a calendar unit`);
   if (unit === 'day' || unit === 'week') {
-    const days = unit === 'week' ? amount * 7 : amount;
-    const z = daysFromCivil(parts.year, parts.month, parts.day) + Math.trunc(days);
-    const civil = civilFromDays(z);
-    return withTime(civil, parts, parts.hours, parts.minutes, parts.seconds);
+    requireDate(parts, unit);
+    if (Number.isInteger(amount)) {
+      // whole days move the day number rather than a span of
+      // milliseconds: that keeps a full-date a full-date, and stays
+      // exact past the range milliseconds can count
+      const z = daysFromCivil(parts.year, parts.month, parts.day)
+        + amount * (unit === 'week' ? 7 : 1);
+      return withTime(civilFromDays(z), parts, parts.hours, parts.minutes, parts.seconds);
+    }
   }
-  // fixed sub-day units: carry through the day number so a time crossing
-  // midnight moves the date with it
-  const ms = FIXED_MS[unit];
-  if (ms === undefined)
-    throw new TypeError(`'${unit}' is not a calendar unit`);
-  const z = daysFromCivil(parts.year, parts.month, parts.day);
-  const dayMs = hasTime(parts)
-    ? parts.hours * 3600000 + parts.minutes * 60000 + Math.round(parts.seconds * 1000)
-    : 0;
-  const moved = z * 86400000 + dayMs + amount * ms;
+  // a span of milliseconds: the sub-day units, and the fraction of a day
+  // or week that only a clock can hold
+  requireTime(parts, unit);
+  const ms = Math.round(amount * width);
+  if (!hasDate(parts)) {
+    // no calendar to carry into, so the clock wraps inside its own day
+    const dayMs = ((dayMsOf(parts) + ms) % 86400000 + 86400000) % 86400000;
+    return { year: -1, month: -1, day: -1, ...clockFromDayMs(dayMs), offset: parts.offset };
+  }
+  // carry through the day number, so a time crossing midnight moves the
+  // date with it
+  const moved = daysFromCivil(parts.year, parts.month, parts.day) * 86400000
+    + dayMsOf(parts) + ms;
   const dz = Math.floor(moved / 86400000);
-  let rest = moved - dz * 86400000;
-  const civil = civilFromDays(dz);
-  const hours = Math.floor(rest / 3600000);
-  rest -= hours * 3600000;
-  const minutes = Math.floor(rest / 60000);
-  rest -= minutes * 60000;
-  // a value with no time half acquires one as soon as a sub-day unit
-  // moves it - there is nowhere else for the result to live
-  const out = { ...civil, hours, minutes, seconds: rest / 1000, offset: parts.offset };
-  if (out.offset === null && !hasTime(parts))
-    out.offset = 0; // a bare full-date is UTC midnight by rfc3339.js's rule
-  return out;
+  return {
+    ...civilFromDays(dz), ...clockFromDayMs(moved - dz * 86400000), offset: parts.offset,
+  };
 }
 
 /**
  * Truncate a parts record to the start of a calendar unit, returning a
  * new one. `week` starts on Monday (ISO 8601).
+ *
+ * `day` and coarser name a boundary the calendar has, so the start of
+ * the day of a full-time is midnight. A sub-day unit names a boundary
+ * inside a day, which a value with no clock does not have, and is
+ * refused rather than answered from a clock that is not there.
+ *
  * @param {object} parts - a parts record
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, or a value missing a half
+ *   the truncation reads
  */
 export function startOfParts(parts, unit) {
   let { year, month, day } = parts;
@@ -303,12 +387,14 @@ export function startOfParts(parts, unit) {
   let seconds = parts.seconds;
   switch (unit) {
     case 'year':
-      month = 1; day = 1; break;
+      requireDate(parts, unit); month = 1; day = 1; break;
     case 'quarter':
+      requireDate(parts, unit);
       month = (quarterOfYear(parts) - 1) * 3 + 1; day = 1; break;
     case 'month':
-      day = 1; break;
+      requireDate(parts, unit); day = 1; break;
     case 'week': {
+      requireDate(parts, unit);
       const z = daysFromCivil(year, month, day);
       ({ year, month, day } = civilFromDays(z - (isoWeekdayFromDays(z) - 1)));
       break;
@@ -316,12 +402,13 @@ export function startOfParts(parts, unit) {
     case 'day':
       break;
     case 'hour':
-      minutes = 0; seconds = 0; break;
+      requireTime(parts, unit); minutes = 0; seconds = 0; break;
     case 'minute':
-      seconds = 0; break;
+      requireTime(parts, unit); seconds = 0; break;
     case 'second':
-      seconds = Math.trunc(seconds); break;
+      requireTime(parts, unit); seconds = Math.trunc(seconds); break;
     case 'millisecond':
+      requireTime(parts, unit);
       return { ...parts };
     default:
       throw new TypeError(`'${unit}' is not a calendar unit`);
@@ -339,16 +426,24 @@ export function startOfParts(parts, unit) {
  * The last representable instant inside a calendar unit: the start of
  * the next unit less one millisecond. A value with no time half is
  * truncated to the unit's last *day* instead, so a full-date stays a
- * full-date.
+ * full-date, and it refuses the same sub-day units `startOfParts` does.
  * @param {object} parts - a parts record
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, or a value missing a half
+ *   the truncation reads
  */
 export function endOfParts(parts, unit) {
   const start = startOfParts(parts, unit);
   if (unit === 'millisecond')
     return start;
-  const next = addToParts(start, 1, unit === 'quarter' ? 'quarter' : unit);
+  if (!hasDate(parts)) {
+    // a clock has no next day to step back from, so the end is the
+    // unit's own width less a millisecond, inside the day it lives in
+    const rest = dayMsOf(start) + FIXED_MS[unit] - 1;
+    return { year: -1, month: -1, day: -1, ...clockFromDayMs(rest), offset: parts.offset };
+  }
+  const next = addToParts(start, 1, unit);
   if (!hasTime(parts)) {
     // date-only: step back one whole day rather than one millisecond
     const z = daysFromCivil(next.year, next.month, next.day) - 1;

package/src/dates/index.js

@@ -16,7 +16,9 @@
 //   rfc3339.js  validation, lexical decomposition, epoch conversion
 //   civil.js    proleptic Gregorian arithmetic over integers
 //   format.js   LDML pattern -> compiled formatter
+//   parse.js    LDML pattern -> compiled strict parser
 //   duration.js ISO 8601 duration decomposition and conversion
+//   ticks.js    the time-axis step ladder and its boundaries
 //
 // Locale-dependent presentation (month and weekday names, relative
 // phrasing) is NOT here: it belongs to @jarenjs/locales, so this module
@@ -25,6 +27,8 @@
 export * from './rfc3339.js';
 export * from './civil.js';
 export * from './format.js';
+export * from './parse.js';
 export * from './duration.js';
+export * from './ticks.js';
 
 //#endregion

package/src/dates/parse.js

@@ -0,0 +1,410 @@
+//@ts-check
+
+//#region Date parsing
+// The inverse of `compileDateFormat`: a pattern is scanned once into a
+// chain of *readers*, and calling the result only walks the chain. The
+// shape is deliberately the same two-stage compiler the formatter uses,
+// for the same reason — a `parse(text, pattern)` helper re-scans its
+// pattern on every row, and a Gantt chart with ten thousand tasks reads
+// ten thousand dates through one pattern.
+//
+// No regular expression is built here, per parse or per compile: every
+// reader is a closure over integers, and digits are read by char code.
+//
+// The vocabulary is the formatter's (Unicode LDML, `yyyy-MM-dd`), minus
+// the tokens that are *derived* from a date rather than part of one.
+// `EEEE` (weekday name), `DDD` (day of year), `ww` (ISO week) and `Q`
+// (quarter) all format, and none of them is an independent field, so
+// asking this compiler for one is an error rather than a token that
+// silently reads nothing.
+//
+// Consumers whose patterns are NOT LDML (Mermaid's Gantt directives use
+// moment's grammar, a d3 axis uses strftime) adapt their tokens to this
+// vocabulary; they do not hand their own spelling to this compiler.
+
+import { daysInMonth } from './civil.js';
+
+// `DateNames` is format.js's typedef and stays there: re-declaring it
+// here would export the same name from two modules of one barrel, which
+// is an ambiguous re-export in the generated declarations — a defect
+// only the packed-consumer gate sees.
+
+// char codes
+const C_0 = 48;
+const C_9 = 57;
+const C_QUOTE = 39;
+const C_PLUS = 43;
+const C_MINUS = 45;
+const C_COLON = 58;
+const C_Z_UPPER = 90;
+const C_Z_LOWER = 122;
+
+/**
+ * Read between `min` and `max` ASCII digits at `i`.
+ * @param {string} text
+ * @param {number} i
+ * @param {number} min
+ * @param {number} max
+ * @returns {[number, number]} `[value, next]`, or `[-1, -1]` on failure
+ */
+function readDigits(text, i, min, max) {
+  let value = 0;
+  let n = 0;
+  while (n < max) {
+    const c = text.charCodeAt(i + n);
+    // past the end `charCodeAt` is NaN, and NaN fails BOTH comparisons —
+    // so this has to be written as the positive test or the loop reads
+    // six characters of nothing and returns NaN
+    if (!(c >= C_0 && c <= C_9)) break;
+    value = value * 10 + (c - C_0);
+    n++;
+  }
+  if (n < min) return [-1, -1];
+  return [value, i + n];
+}
+
+/**
+ * A field reader: `(text, i, out) => next index`, or -1.
+ * @typedef {(text: string, i: number, out: any) => number} Reader
+ */
+
+/**
+ * Build a reader for a numeric field.
+ * @param {string} field - the `out` member to assign
+ * @param {number} min - minimum digits
+ * @param {number} max - maximum digits
+ * @returns {Reader}
+ */
+function numeric(field, min, max) {
+  return (text, i, out) => {
+    const [value, next] = readDigits(text, i, min, max);
+    if (next < 0) return -1;
+    out[field] = value;
+    return next;
+  };
+}
+
+/** The two-digit-year pivot: 00–68 is 2000–2068, 69–99 is 1969–1999. */
+const YY_PIVOT = 69;
+
+/** @type {Reader} */
+const readYY = (text, i, out) => {
+  const [value, next] = readDigits(text, i, 2, 2);
+  if (next < 0) return -1;
+  out.year = value < YY_PIVOT ? 2000 + value : 1900 + value;
+  return next;
+};
+
+/** @type {Reader} */
+const readSignedYear = (text, i, out) => {
+  let j = i;
+  let sign = 1;
+  if (text.charCodeAt(j) === C_MINUS) { sign = -1; j++; }
+  const [value, next] = readDigits(text, j, 1, 6);
+  if (next < 0) return -1;
+  out.year = sign * value;
+  return next;
+};
+
+/**
+ * A name reader: longest candidate first, so a name that is a prefix of
+ * another (`Ju` in a hypothetical catalog) cannot shadow it.
+ * @param {string} field
+ * @param {string[]} names
+ * @param {number} base - the value of `names[0]`
+ * @returns {Reader}
+ */
+function nameOf(field, names, base) {
+  // index by descending length once, at compile time
+  const order = names.map((name, index) => ({ name, value: index + base }))
+    .sort((a, b) => b.name.length - a.name.length);
+  const count = order.length;
+  return (text, i, out) => {
+    for (let k = 0; k < count; k++) {
+      const { name, value } = order[k];
+      if (name.length !== 0 && text.startsWith(name, i)) {
+        out[field] = value;
+        return i + name.length;
+      }
+    }
+    return -1;
+  };
+}
+
+/**
+ * @param {boolean} colon - require `+HH:MM` rather than `+HHMM`
+ * @param {boolean} zForUtc - accept a bare `Z`
+ * @returns {Reader}
+ */
+function offsetOf(colon, zForUtc) {
+  return (text, i, out) => {
+    const c = text.charCodeAt(i);
+    if (zForUtc && (c === C_Z_UPPER || c === C_Z_LOWER)) {
+      out.offset = 0;
+      return i + 1;
+    }
+    if (c !== C_PLUS && c !== C_MINUS) return -1;
+    const [hh, afterH] = readDigits(text, i + 1, 2, 2);
+    if (afterH < 0) return -1;
+    let j = afterH;
+    if (colon) {
+      if (text.charCodeAt(j) !== C_COLON) return -1;
+      j++;
+    }
+    const [mm, afterM] = readDigits(text, j, 2, 2);
+    if (afterM < 0) return -1;
+    if (hh > 23 || mm > 59) return -1;
+    out.offset = (c === C_MINUS ? -1 : 1) * (hh * 60 + mm);
+    return afterM;
+  };
+}
+
+/** @type {Reader} */
+const readMillis = (text, i, out) => {
+  const [value, next] = readDigits(text, i, 3, 3);
+  if (next < 0) return -1;
+  out.millis = value;
+  return next;
+};
+
+/** @type {Reader} */
+const readTenths = (text, i, out) => {
+  const [value, next] = readDigits(text, i, 1, 1);
+  if (next < 0) return -1;
+  out.millis = value * 100;
+  return next;
+};
+
+/**
+ * Which half of a value each token contributes to, and how to read it.
+ * `names` is the `DateNames` member a token needs, if any.
+ */
+const TOKENS = Object.freeze({
+  yyyy: { half: 'date', reader: numeric('year', 4, 4) },
+  yy: { half: 'date', reader: readYY },
+  y: { half: 'date', reader: readSignedYear },
+  MMMM: { half: 'date', names: 'months' },
+  MMM: { half: 'date', names: 'monthsShort' },
+  MM: { half: 'date', reader: numeric('month', 2, 2) },
+  M: { half: 'date', reader: numeric('month', 1, 2) },
+  dd: { half: 'date', reader: numeric('day', 2, 2) },
+  d: { half: 'date', reader: numeric('day', 1, 2) },
+  HH: { half: 'time', reader: numeric('hours', 2, 2) },
+  H: { half: 'time', reader: numeric('hours', 1, 2) },
+  hh: { half: 'time', reader: numeric('hour12', 2, 2) },
+  h: { half: 'time', reader: numeric('hour12', 1, 2) },
+  mm: { half: 'time', reader: numeric('minutes', 2, 2) },
+  m: { half: 'time', reader: numeric('minutes', 1, 2) },
+  ss: { half: 'time', reader: numeric('seconds', 2, 2) },
+  s: { half: 'time', reader: numeric('seconds', 1, 2) },
+  SSS: { half: 'time', reader: readMillis },
+  S: { half: 'time', reader: readTenths },
+  a: { half: 'time', names: 'meridiem' },
+  XXX: { half: 'offset', reader: offsetOf(true, true) },
+  XX: { half: 'offset', reader: offsetOf(false, true) },
+  X: { half: 'offset', reader: offsetOf(true, false) },
+});
+
+/**
+ * Tokens `compileDateFormat` writes that no value carries as a field —
+ * they are computed FROM a date, so reading one back tells the parser
+ * nothing it did not already have. Named individually so the error says
+ * which token and why, rather than "unknown token".
+ */
+const DERIVED = Object.freeze({
+  EEEE: 'the weekday name', EEE: 'the abbreviated weekday name',
+  E: 'the ISO weekday number', DDD: 'the day of the year',
+  D: 'the day of the year', ww: 'the ISO week number',
+  w: 'the ISO week number', Q: 'the quarter',
+});
+
+const MAX_TOKEN = 4;
+
+/**
+ * The value a name token reads into, and the base of its numbering.
+ * @param {string} token
+ * @returns {[string, number]}
+ */
+function nameTarget(token) {
+  if (token === 'a') return ['meridiem', 0];
+  return ['month', 1];
+}
+
+/**
+ * Compile an LDML date pattern into a strict parser.
+ *
+ * The returned function takes a string and returns a parts record in
+ * exactly the shape `parseRFC3339Parts` produces — so
+ * `epochOfRFC3339Parts`, `formatRFC3339Parts`, `addToParts` and every
+ * other calendar function accept it unchanged — or `null` when the text
+ * does not match. Failure is `null`, never a throw and never a partial
+ * record: a malformed *pattern* is the programmer's error and throws at
+ * compile time; malformed *text* is data and is reported as no match.
+ *
+ * Strict means three things:
+ *
+ * 1. **Full consumption.** Trailing text fails; `yyyy-MM-dd` does not
+ *    read `2026-01-02T03:04`.
+ * 2. **Impossible civil dates fail.** 31 February and hour 24 are not
+ *    silently rolled forward into March and the next day.
+ * 3. **Fixed-width tokens are fixed width.** `MM` reads exactly two
+ *    digits, `M` one or two, and neither reads three.
+ *
+ * The lexical family of the result follows the pattern: a pattern with
+ * only date tokens yields a full-date (`hours`/`minutes`/`seconds` are
+ * the contract's `-1`), one with only time tokens a full-time
+ * (`year`/`month`/`day` are `-1`), and one with both a date-time. A
+ * pattern with no field token at all is a compile error — it could only
+ * ever return the same empty record.
+ *
+ * Two tokens are not strict inverses of an arbitrary value and are
+ * documented rather than refused: `yy` reads 00–68 as 2000–2068 and
+ * 69–99 as 1969–1999 (the POSIX pivot moment uses), and `h`/`hh`
+ * without an `a` in the same pattern read as the morning, so 12 is
+ * midnight. Both round-trip their own spelling exactly.
+ *
+ * @param {string} pattern - an LDML pattern, e.g. `'yyyy-MM-dd'`
+ * @param {import('./format.js').DateNames} [names] - locale names, required only if the
+ *   pattern uses `MMM`/`MMMM`/`a`
+ * @returns {(text: string) => object | null} the compiled parser
+ * @throws {TypeError} on an unterminated quote, a derived token, a name
+ *   token with no provider, or a pattern that reads no field
+ * @example
+ * const read = compileDateParser('dd-MM-yyyy');
+ * read('06-01-2014');  // { year: 2014, month: 1, day: 6, hours: -1, … }
+ * read('06-01-2014x'); // null — trailing input
+ * read('31-02-2014');  // null — February has no 31st
+ */
+export function compileDateParser(pattern, names = undefined) {
+  if (typeof pattern !== 'string')
+    throw new TypeError('a date pattern must be a string');
+
+  /** @type {Reader[]} */
+  const steps = [];
+  let literal = '';
+  let hasDate = false;
+  let hasTime = false;
+  let hasOffset = false;
+  let hasMeridiem = false;
+
+  const flushLiteral = () => {
+    if (literal !== '') {
+      const text = literal;
+      const width = text.length;
+      steps.push((source, i) => (source.startsWith(text, i) ? i + width : -1));
+      literal = '';
+    }
+  };
+
+  for (let i = 0; i < pattern.length;) {
+    const ch = pattern[i];
+    if (ch === "'") { // quoted literal, '' is one quote
+      if (pattern.charCodeAt(i + 1) === C_QUOTE) {
+        literal += "'";
+        i += 2;
+        continue;
+      }
+      const end = pattern.indexOf("'", i + 1);
+      if (end < 0)
+        throw new TypeError(`unterminated quoted literal in date pattern '${pattern}'`);
+      literal += pattern.slice(i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    let matched = null;
+    for (let len = MAX_TOKEN; len >= 1; len--) {
+      const candidate = pattern.slice(i, i + len);
+      if (candidate.length !== len) continue;
+      if (TOKENS[candidate] !== undefined || DERIVED[candidate] !== undefined) {
+        matched = candidate;
+        break;
+      }
+    }
+    if (matched === null) {
+      literal += ch;
+      i += 1;
+      continue;
+    }
+    if (DERIVED[matched] !== undefined) {
+      throw new TypeError(`the '${matched}' token writes ${DERIVED[matched]},`
+        + ' which is derived from a date rather than part of one, so it cannot be parsed');
+    }
+    const spec = TOKENS[matched];
+    let reader = spec.reader;
+    if (spec.names !== undefined) {
+      const table = names === undefined ? undefined : names[spec.names];
+      if (table === undefined)
+        throw new TypeError(`the '${matched}' token needs a '${spec.names}' names provider`
+          + ' (@jarenjs/core/dates is locale-free by design)');
+      const [field, base] = nameTarget(matched);
+      reader = nameOf(field, table, base);
+      if (matched === 'a') hasMeridiem = true;
+    }
+    flushLiteral();
+    steps.push(reader);
+    if (spec.half === 'date') hasDate = true;
+    else if (spec.half === 'time') hasTime = true;
+    else hasOffset = true;
+    i += matched.length;
+  }
+  flushLiteral();
+
+  if (!hasDate && !hasTime)
+    throw new TypeError(`the date pattern '${pattern}' reads no date or time field`);
+
+  const count = steps.length;
+  return (text) => {
+    if (typeof text !== 'string') return null;
+    /** @type {any} */
+    const out = {
+      year: 1970, month: 1, day: 1,
+      hours: 0, minutes: 0, seconds: 0, millis: 0,
+      hour12: -1, meridiem: -1, offset: null,
+    };
+    let i = 0;
+    for (let k = 0; k < count; k++) {
+      i = steps[k](text, i, out);
+      if (i < 0) return null;
+    }
+    if (i !== text.length) return null;
+    return assemble(out, hasDate, hasTime, hasOffset, hasMeridiem);
+  };
+}
+
+/**
+ * Turn the reader's scratch record into a validated parts record.
+ * @param {any} out
+ * @param {boolean} hasDate
+ * @param {boolean} hasTime
+ * @param {boolean} hasOffset
+ * @param {boolean} hasMeridiem
+ * @returns {object | null}
+ */
+function assemble(out, hasDate, hasTime, hasOffset, hasMeridiem) {
+  if (hasDate) {
+    if (out.month < 1 || out.month > 12) return null;
+    if (out.day < 1 || out.day > daysInMonth(out.year, out.month)) return null;
+  }
+  let hours = out.hours;
+  if (hasTime) {
+    if (out.hour12 >= 0) {
+      if (out.hour12 < 1 || out.hour12 > 12) return null;
+      hours = out.hour12 % 12;
+      if (hasMeridiem && out.meridiem === 1) hours += 12;
+    }
+    if (hours < 0 || hours > 23) return null;
+    if (out.minutes < 0 || out.minutes > 59) return null;
+    if (out.seconds < 0 || out.seconds > 59) return null;
+  }
+  return {
+    year: hasDate ? out.year : -1,
+    month: hasDate ? out.month : -1,
+    day: hasDate ? out.day : -1,
+    hours: hasTime ? hours : -1,
+    minutes: hasTime ? out.minutes : -1,
+    seconds: hasTime ? out.seconds + out.millis / 1000 : -1,
+    offset: hasOffset ? out.offset : null,
+  };
+}
+
+//#endregion