@jarenjs/core 0.9.2 → 0.34.0

package/dist/types/cache.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @file The suite's one bounded-cache primitive. Before this file the
+ * FIFO-512 delete-oldest map was written five times (the query engine's
+ * string cache, the JSONPath query cache, forms' three pointer caches)
+ * with a sixth divergent flush-all variant in forms' regex cache and a
+ * true LRU in the view projection memo. One implementation, one policy:
+ *
+ *  - **LRU with recency refresh**: a `get` hit re-inserts the entry, so
+ *    the evicted entry is the least recently USED, not the oldest
+ *    inserted. (FIFO versus LRU was never result-observable at any call
+ *    site — both bound memory; LRU keeps hot entries hotter.)
+ *  - **Evict at `size >= limit` before inserting a new key**, so the
+ *    cache never holds more than `limit` entries. (The old sites
+ *    disagreed between `>=`-before and `>`-after; the capacity is the
+ *    same, the invariant here is simply "never above `limit`".)
+ *  - `undefined` is the miss sentinel: a cache MUST NOT store
+ *    `undefined` as a value (store `null` for "computed, negative" —
+ *    the regex cache does exactly that).
+ *
+ * The identity axis is {@link createWeakCache}: reference-keyed,
+ * unbounded by design because a WeakMap is bounded by its keys'
+ * lifetimes — an entry dies with its key. Compose the two for
+ * "per-registry bounded caches" (a WeakMap of bounded caches).
+ *
+ * The VALUE axis is {@link createSemanticCache}: keyed by what a
+ * plain-data value IS rather than by a fingerprint of it, for the caches
+ * whose entries carry meaning (a compiled query, a query plan, a
+ * registered function body) and where serving the wrong entry is wrong
+ * data rather than a slow repaint.
+ */
+export type BoundedCache<K, V> = {
+    /**
+     * - Lookup; a hit refreshes
+     * recency. `undefined` means miss.
+     */
+    get: (key: K) => V | undefined;
+    /**
+     * - Insert or refresh; evicts
+     * the least recently used entry when the cache is full.
+     */
+    set: (key: K, value: V) => void;
+    /**
+     * - Lookup
+     * or compute-and-insert in one step.
+     */
+    getOrCreate: (key: K, create: (key: K) => V) => V;
+    /**
+     * - Drop every entry.
+     */
+    clear: () => void;
+    /**
+     * - Current entry count.
+     */
+    size: () => number;
+};
+/**
+ * @template K, V
+ * @typedef {object} BoundedCache
+ * @property {(key: K) => V | undefined} get - Lookup; a hit refreshes
+ *   recency. `undefined` means miss.
+ * @property {(key: K, value: V) => void} set - Insert or refresh; evicts
+ *   the least recently used entry when the cache is full.
+ * @property {(key: K, create: (key: K) => V) => V} getOrCreate - Lookup
+ *   or compute-and-insert in one step.
+ * @property {() => void} clear - Drop every entry.
+ * @property {() => number} size - Current entry count.
+ */
+/**
+ * A bounded, string-or-value-keyed LRU cache.
+ * @template K, V
+ * @param {number} limit - Maximum number of retained entries (> 0)
+ * @returns {BoundedCache<K, V>}
+ */
+export declare function createBoundedCache<K, V>(limit: number): BoundedCache<K, V>;
+export type SemanticCache<V> = {
+    /**
+     * - Lookup by structural
+     * identity. `undefined` means miss — including "this value cannot be
+     * keyed", which is a permanent miss, never someone else's entry.
+     */
+    get: (value: any) => V | undefined;
+    /**
+     * - Insert or refresh.
+     * Returns whether the entry was retained — `false` means the value
+     * could not be keyed, which a caller comparing sizes to detect an
+     * eviction must not mistake for one.
+     */
+    set: (value: any, entry: V) => boolean;
+    /**
+     * - Lookup or compute-and-insert in one step. `create`
+     * receives the identity, or `null` when the value was unkeyable and
+     * the result will NOT be retained.
+     */
+    getOrCreate: (value: any, create: (identity: string | null) => V) => V;
+    /**
+     * - Drop every entry.
+     */
+    clear: () => void;
+    /**
+     * - Current entry count.
+     */
+    size: () => number;
+};
+/**
+ * @template V
+ * @typedef {object} SemanticCache
+ * @property {(value: any) => V | undefined} get - Lookup by structural
+ *   identity. `undefined` means miss — including "this value cannot be
+ *   keyed", which is a permanent miss, never someone else's entry.
+ * @property {(value: any, entry: V) => boolean} set - Insert or refresh.
+ *   Returns whether the entry was retained — `false` means the value
+ *   could not be keyed, which a caller comparing sizes to detect an
+ *   eviction must not mistake for one.
+ * @property {(value: any, create: (identity: string | null) => V) => V}
+ *   getOrCreate - Lookup or compute-and-insert in one step. `create`
+ *   receives the identity, or `null` when the value was unkeyable and
+ *   the result will NOT be retained.
+ * @property {() => void} clear - Drop every entry.
+ * @property {() => number} size - Current entry count.
+ */
+/**
+ * A bounded cache keyed by a value's COLLISION-FREE structural identity
+ * ({@link semanticKey}), for entries whose reuse decides a result.
+ *
+ * Two guarantees a fingerprint-keyed cache cannot give:
+ *
+ *  - **Distinct inputs never share an entry.** The key is the whole
+ *    deterministic serialization, so a hash collision cannot make one
+ *    document's compiled semantics answer for another's.
+ *  - **An unkeyable input is a permanent miss, never a wrong hit.** A
+ *    value carrying a cycle, a function or a class instance cannot be
+ *    keyed injectively, so it is computed afresh every time and never
+ *    retained. Correct and slow beats fast and wrong; callers that want
+ *    to *reject* such input should validate before asking the cache.
+ *
+ * Compose with a discriminating tuple when an entry depends on more than
+ * the document — `cache.getOrCreate([document, dialect, strict], …)`
+ * keys the whole tuple, which a `${a}|${b}` string concatenation cannot
+ * do injectively once `a` may itself contain the separator.
+ * @template V
+ * @param {number} limit - Maximum number of retained entries (> 0)
+ * @returns {SemanticCache<V>}
+ */
+export declare function createSemanticCache<V>(limit: number): SemanticCache<V>;
+export type WeakCache<K extends object, V> = {
+    get: (key: K) => V | undefined;
+    set: (key: K, value: V) => void;
+    getOrCreate: (key: K, create: (key: K) => V) => V;
+};
+/**
+ * @template {object} K
+ * @template V
+ * @typedef {object} WeakCache
+ * @property {(key: K) => V | undefined} get
+ * @property {(key: K, value: V) => void} set
+ * @property {(key: K, create: (key: K) => V) => V} getOrCreate
+ */
+/**
+ * The identity axis: a reference-keyed cache whose entries live exactly
+ * as long as their keys. No bound, deliberately — the bound is the
+ * caller's ownership of the key objects.
+ * @template {object} K
+ * @template V
+ * @returns {WeakCache<K, V>}
+ */
+export declare function createWeakCache<K extends object, V>(): WeakCache<K, V>;

package/dist/types/chunk.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Cutting text down to size: the four operations every consumer of a
+ * too-large value needs, in one place.
+ *
+ * They live together because they are one decision made four ways —
+ * *how much of this do I carry?* `sizeOf` answers what it costs,
+ * `excerpt` shows a line of it, `truncate` cuts it at a boundary and
+ * says so, and `chunkText` splits it into pieces that can each be
+ * carried, addressed and fetched on their own.
+ *
+ * Two rules hold across all four:
+ *
+ *  - **Characters, not bytes and not tokens.** Tokens are
+ *    provider-private and bytes depend on an encoding nobody has agreed
+ *    on at this layer; characters are deterministic, and a budget stated
+ *    in them holds exactly.
+ *  - **A cut is always visible.** `excerpt` appends an ellipsis and
+ *    `truncate` a named marker, so nothing downstream — a reader, a
+ *    model, a diff — mistakes a cut tail for the end of the content.
+ *
+ * Nothing here allocates a copy it does not return: `chunkText` slices,
+ * and a caller streaming a corpus can write each piece and drop it.
+ */
+/**
+ * The size of a value as the characters it will occupy in a request: a
+ * string is its own length, anything else is the length of its JSON
+ * encoding. That is the one size rule the suite budgets against — an
+ * agent's history budget, a slot's metadata, a digest's cap — and it is
+ * exact rather than an estimate, which is what makes those budgets hold
+ * to the character instead of approximately.
+ * @param {any} value
+ * @returns {number}
+ */
+export declare function sizeOf(value: any): number;
+/**
+ * A one-line excerpt: whitespace collapsed to single spaces, trimmed,
+ * hard-capped, with an ellipsis when anything was dropped. Total over
+ * `null`/`undefined`/non-strings, because it is called on content a
+ * provider or a store may have left absent.
+ * @param {any} text
+ * @param {number} max - characters kept, before the ellipsis
+ * @returns {string}
+ */
+export declare function excerpt(text: any, max: number): string;
+/**
+ * A hard cut with a named suffix, preserving newlines — what an
+ * oversized result or an over-long generated block is reduced to. The
+ * suffix is part of the contract: a cut that looked like an ending would
+ * be read as one.
+ * @param {string} text
+ * @param {number} max
+ * @param {string} [marker] - the suffix appended when a cut happened
+ * @returns {string}
+ */
+export declare function truncate(text: string, max: number, marker?: string): string;
+export type ChunkStrategy = 'size' | 'line' | 'separator';
+/**
+ * How a text is cut into pieces.
+ *
+ *  - `size` — fixed character windows. The only strategy that will split
+ *    a word, and the only one whose piece count is exactly predictable.
+ *  - `line` — whole lines, grouped up to `size`. A line longer than
+ *    `size` becomes its own oversized piece rather than being split:
+ *    breaking a line is the one thing a line strategy may not do.
+ *  - `separator` — units delimited by `separator` (paragraphs, records),
+ *    grouped up to `size`, separators preserved between units in a
+ *    piece. Same rule for an oversized unit.
+ *
+ * @typedef {'size' | 'line' | 'separator'} ChunkStrategy
+ */
+/**
+ * Split a text into addressable pieces.
+ *
+ * Deterministic and total: the same text and the same options always
+ * produce the same pieces, with the same offsets, which is what lets a
+ * caller name a piece by its index and re-derive that name later instead
+ * of storing a mapping. Empty text produces no pieces at all — an empty
+ * piece is not a thing anyone wants an address for.
+ *
+ * `overlap` (character strategy only) repeats the tail of each piece at
+ * the head of the next, so a match spanning a cut is still found whole
+ * in one piece. It costs storage proportional to `overlap / size` and is
+ * off by default.
+ *
+ * @param {string} text
+ * @param {{ strategy?: ChunkStrategy, size?: number, overlap?: number,
+ *   separator?: string }} [options]
+ * @returns {Array<{ index: number, start: number, end: number, text: string }>}
+ *   `start`/`end` are offsets into the original text, so a piece can be
+ *   located in the source it came from.
+ */
+export declare function chunkText(text: string, options?: {
+    strategy?: ChunkStrategy;
+    size?: number;
+    overlap?: number;
+    separator?: string;
+}): Array<{
+    index: number;
+    start: number;
+    end: number;
+    text: string;
+}>;

package/dist/types/color.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file Pure color helpers — dependency-free numeric math over color
+ * strings, with no view or DOM knowledge. The one home for the suite's
+ * color primitives (currently the hex `#rrggbb` interpolation used by the
+ * calc surface shader).
+ */
+/**
+ * Linear-interpolate two `#rrggbb` hex colors channel-by-channel and
+ * return the result as `#rrggbb`. `t` is the blend factor (0 → `a`,
+ * 1 → `b`); values outside `[0, 1]` extrapolate.
+ *
+ * @param {string} a a `#rrggbb` hex color
+ * @param {string} b a `#rrggbb` hex color
+ * @param {number} t blend factor
+ * @returns {string} the interpolated `#rrggbb` color
+ */
+export declare function lerpColor(a: string, b: string, t: number): string;
+/**
+ * WCAG relative luminance of a `#rrggbb` hex color: 0 for black, 1 for
+ * white. The sRGB channels are linearized (the 2.4-exponent transfer
+ * curve with its linear toe) and weighted per ITU-R BT.709. Use it to
+ * pick a legible ink over an arbitrary fill (light ink below ~0.4,
+ * dark ink above).
+ *
+ * @param {string} hex a `#rrggbb` hex color
+ * @returns {number} relative luminance in [0, 1]
+ */
+export declare function relativeLuminance(hex: string): number;
+/**
+ * A legible ink for text set INSIDE a concrete fill: near-black on light
+ * fills, white on dark ones.
+ *
+ * Keyed off the fill's luminance, **not** the theme. That distinction is the
+ * whole point: a fill the author named is a constant, so it does not follow
+ * light/dark — and if the ink does, a light fill under a dark theme ends up
+ * with light text on it and the label disappears.
+ *
+ * The choice is made by comparing the two candidates' actual WCAG contrast
+ * rather than by a luminance threshold. A threshold is subtly wrong in the
+ * mid-tones: at 0.4 a fill like `#87b496` took dark ink and landed at 2.33:1,
+ * well under AA, because the crossover between the two inks is near 0.179 and
+ * not where a round number puts it. Picking the better of two is optimal by
+ * construction, so the worst case over the whole RGB cube is ~4.6:1 — which
+ * clears AA with nothing to tune.
+ * @param {string} fillHex - The `#rgb` or `#rrggbb` fill under the text
+ * @returns {string} `#1f2020` or `#ffffff`
+ */
+export declare function inkFor(fillHex: string): string;
+/**
+ * The WCAG contrast ratio between two relative luminances, from 1 (identical)
+ * to 21 (black on white).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export declare function contrastOf(a: number, b: number): number;
+/**
+ * Whether a CSS color value is a concrete hex this module can reason about.
+ * A `var(...)`, a named color or a function is not: it may resolve to
+ * anything at paint time, so the caller must fall back to its theme.
+ * @param {string} value
+ * @returns {boolean}
+ */
+export declare function isHexColor(value: string): boolean;

package/dist/types/convert/convert.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file The static conversion engine. Pure, single-pass,
+ * no per-call allocation. Rejects cross-dimension conversions with a
+ * clear error.
+ */
+/**
+ * Convert `value` from unit `fromId` to unit `toId` (same dimension).
+ * Affine through the dimension base: `base = value*factor + offset`,
+ * `target = (base - offset')/factor'`.
+ *
+ * @param {number} value
+ * @param {string} fromId
+ * @param {string} toId
+ * @returns {number}
+ */
+export declare function convert(value: number, fromId: string, toId: string): number;
+/**
+ * The unit list for a dimension (in registry order).
+ * @param {string} dimension
+ * @returns {import('./registry.js').Unit[]}
+ */
+export declare function unitsOf(dimension: string): import('./registry.js').Unit[];
+/**
+ * All dimension names.
+ * @returns {string[]}
+ */
+export declare function dimensions(): string[];
+/**
+ * Look up the dimension a unit belongs to (or `null`).
+ * @param {string} unitId
+ * @returns {string|null}
+ */
+export declare function dimensionOf(unitId: string): string | null;

package/dist/types/convert/currency.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file The pure currency-conversion primitive.
+ * `convertCurrency` is deterministic and side-effect
+ * free: the caller supplies the `{ code: rate }` table; core NEVER
+ * fetches it. This lives in core because the dividing line is **purity**,
+ * not constant-vs-variable factors — this function is exactly as pure as
+ * the fixed-factor path, it just receives its factors as an argument.
+ * Fetching the table is the impure half and stays in the app component.
+ *
+ * Rate convention: `rateTable[code]` is the value of ONE unit of `code`
+ * expressed in the table's base currency (so the base currency has rate
+ * 1). To convert `value` from → to:
+ *
+ *   result = value * rate[from] / rate[to]
+ */
+export type RateTable = {
+    /**
+     * the base currency code (informational)
+     */
+    base?: string;
+    /**
+     * code → value-in-base
+     */
+    rates: Record<string, number>;
+    /**
+     * timestamp of the table (informational)
+     */
+    at?: number | string;
+};
+/**
+ * Convert an amount between currencies using a supplied rate table.
+ * Throws a `RangeError` when either code is missing from the table (the
+ * component decides how to fall back — a static table, a last-good cache).
+ *
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @param {RateTable | Record<string, number>} rateTable
+ * @returns {number}
+ */
+export declare function convertCurrency(value: number, from: string, to: string, rateTable: RateTable | Record<string, number>): number;
+/**
+ * The currency codes available in a rate table.
+ * @param {RateTable | Record<string, number>} rateTable
+ * @returns {string[]}
+ */
+export declare function currenciesOf(rateTable: RateTable | Record<string, number>): string[];

package/dist/types/convert/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file `@jarenjs/core/convert` — pure, deterministic quantity
+ * conversion. Fixed-factor dimensional conversion (`convert`) plus the
+ * pure rate-table primitive `convertCurrency` (the caller supplies the
+ * table; core never fetches). Zero runtime dependencies.
+ */
+export { DIMENSIONS, UNIT_INDEX } from './registry.js';
+export { convert, unitsOf, dimensions, dimensionOf } from './convert.js';
+export { convertCurrency, currenciesOf } from './currency.js';

package/dist/types/convert/registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file Unit registry. Fixed-factor unit definitions per
+ * **dimension**. Conversion is affine through the dimension's base unit:
+ *
+ *   base   = value * factor + offset
+ *   target = (base - offset') / factor'
+ *
+ * Most dimensions are linear (`offset` absent = 0); **temperature** is
+ * affine (°C/°F/K/°R). Digital storage ships both binary (KiB/MiB, 1024)
+ * and decimal (KB/MB, 1000) prefixes.
+ *
+ * Number-base conversion (HEX/DEC/OCT/BIN) is intentionally NOT here — it
+ * is `@jarenjs/core/math/word.js` (`toBase`/`fromBase`), which the
+ * converter delegates to. Fuel-economy (mpg ↔ L/100km) is non-affine and
+ * likewise out of this data-driven model.
+ */
+export type Unit = {
+    /**
+     * unique unit id
+     */
+    id: string;
+    /**
+     * display symbol
+     */
+    symbol: string;
+    /**
+     * multiply to reach the base unit
+     */
+    factor: number;
+    /**
+     * affine offset toward the base unit
+     */
+    offset?: number;
+};
+/**
+ * @typedef {object} Unit
+ * @property {string} id unique unit id
+ * @property {string} symbol display symbol
+ * @property {number} factor multiply to reach the base unit
+ * @property {number} [offset] affine offset toward the base unit
+ */
+/** @type {Record<string, { base: string, units: Unit[] }>} */
+export declare const DIMENSIONS: Record<string, {
+    base: string;
+    units: Unit[];
+}>;
+/**
+ * Reverse index: unit id → `{ dimension, unit }`. Built once at module
+ * load; ids are unique across dimensions.
+ * @type {Map<string, { dimension: string, unit: Unit }>}
+ */
+export declare const UNIT_INDEX: Map<string, {
+    dimension: string;
+    unit: Unit;
+}>;

package/dist/types/dates/civil.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Whether a proleptic Gregorian year is a leap year.
+ * @param {number} year
+ * @returns {boolean}
+ */
+export declare function isLeapYear(year: number): boolean;
+/**
+ * Length of a month in days.
+ * @param {number} year
+ * @param {number} month - 1-12
+ * @returns {number}
+ */
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * Days since 1970-01-01 for a civil date (Howard Hinnant's algorithm).
+ * Exact for every proleptic Gregorian date; no `Date`, no allocation.
+ * @param {number} y - year
+ * @param {number} m - month 1-12
+ * @param {number} d - day 1-31
+ * @returns {number} day number, negative before 1970
+ */
+export declare function daysFromCivil(y: number, m: number, d: number): number;
+/**
+ * The inverse of {@link daysFromCivil}: a civil date from a day number.
+ * @param {number} z - days since 1970-01-01
+ * @returns {{ year: number, month: number, day: number }}
+ */
+export declare function civilFromDays(z: number): {
+    year: number;
+    month: number;
+    day: number;
+};
+/**
+ * Day of the week for a day number: 0 = Sunday … 6 = Saturday, matching
+ * `Date.prototype.getUTCDay`.
+ * @param {number} z - days since 1970-01-01
+ * @returns {number} 0-6
+ */
+export declare function weekdayFromDays(z: number): number;
+/**
+ * ISO 8601 weekday: 1 = Monday … 7 = Sunday.
+ * @param {number} z - days since 1970-01-01
+ * @returns {number} 1-7
+ */
+export declare function isoWeekdayFromDays(z: number): number;
+/**
+ * Day of the year, 1-based (1-366).
+ * @param {{ year: number, month: number, day: number }} parts
+ * @returns {number}
+ */
+export declare function dayOfYear(parts: {
+    year: number;
+    month: number;
+    day: number;
+}): number;
+/**
+ * Calendar quarter, 1-4.
+ * @param {{ month: number }} parts
+ * @returns {number}
+ */
+export declare function quarterOfYear(parts: {
+    month: number;
+}): number;
+/**
+ * ISO 8601 week-numbering week and its year. The ISO year is not always
+ * the calendar year: 2027-01-01 is a Friday and belongs to week 53 of
+ * 2026, so the pair has to be returned together.
+ * @param {{ year: number, month: number, day: number }} parts
+ * @returns {{ year: number, week: number }}
+ */
+export declare function isoWeekOfYear(parts: {
+    year: number;
+    month: number;
+    day: number;
+}): {
+    year: number;
+    week: number;
+};
+/**
+ * The parts record of an instant, the inverse of
+ * `epochOfRFC3339Parts` (rfc3339.js).
+ *
+ * `offset` selects the wall clock the fields are read on: 0 (the
+ * default) gives UTC, 120 gives the clock in `+02:00`. The returned
+ * record carries that offset, so rendering it back with
+ * `formatRFC3339Parts` yields the same instant spelled in that zone.
+ *
+ * @param {number} ms - milliseconds since 1970-01-01T00:00:00Z
+ * @param {number} [offset] - minutes east of UTC to read the clock in
+ * @returns {object} a parts record, always with a time half
+ */
+export declare function partsFromEpoch(ms: number, offset?: number): object;
+/**
+ * The calendar units every unit-taking function in this module accepts.
+ * Ordered coarse to fine, which is the order `startOfParts` truncates in.
+ */
+export declare const DATE_UNITS: readonly string[];
+/**
+ * Whether a string names a calendar unit.
+ * @param {any} unit
+ * @returns {boolean}
+ */
+export declare function isDateUnit(unit: any): boolean;
+/**
+ * Milliseconds in a fixed-width unit, or 0 for the calendar units
+ * (`month`, `quarter`, `year`) that do not have one.
+ * @param {string} unit
+ * @returns {number}
+ */
+export declare function fixedUnitMs(unit: string): number;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @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 {string} unit - a {@link DATE_UNITS} member
+ * @returns {object} a new parts record
+ */
+export declare function addToParts(parts: object, amount: number, unit: string): object;
+/**
+ * Truncate a parts record to the start of a calendar unit, returning a
+ * new one. `week` starts on Monday (ISO 8601).
+ * @param {object} parts - a parts record
+ * @param {string} unit - a {@link DATE_UNITS} member
+ * @returns {object} a new parts record
+ */
+export declare function startOfParts(parts: object, unit: string): object;
+/**
+ * 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.
+ * @param {object} parts - a parts record
+ * @param {string} unit - a {@link DATE_UNITS} member
+ * @returns {object} a new parts record
+ */
+export declare function endOfParts(parts: object, unit: string): object;