agentfootprint/dist/esm/time/duration.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * time/duration — the ONE duration grammar, with a unit set per use.
 *
 * Pattern: one grammar, units narrowed per use (never a second regex). A
 *          duration is a MACHINE spelling an author declared — a tool's
 *          `-40m` argument, a `retention: '30d'`, a dataset's `interval:
 *          '5m'` — never a person's words ("the last 40 minutes" is read only
 *          by an armed reader). This is the T-spellings law of the time
 *          design (`docs/design/time/README.md`, § 5.4).
 * Role:    L0 leaf (the time layer's one owner). Imports nothing. Asked by
 *          `tools/declare.ts` · `parsesUnderSpelling` for a look-back.
 * Emits:   N/A.
 *
 * ## The grammar
 *
 * `^[1-9][0-9]*[smhdw]$` — a positive integer with no leading zero, then one
 * unit. NO digit cap: `1000000m` is a look-back today and stays one. The UNIT
 * SET is named by every caller, because widening it is a behaviour change:
 *
 * | Use | Units | Why |
 * |-----|-------|-----|
 * | a look-back argument ({@link LOOKBACK_UNITS}) | `mhdw` | today's spelling; a backend that never took seconds is never sent `30s` unless its tool declares `units: 'smhdw'` |
 * | a dataset's interval ({@link AXIS_UNITS}) | `smhdw` | a series can be bucketed by the second |
 *
 * `d` is 24 hours and `w` is 7 days: a machine duration, not a calendar day
 * (a calendar day in a zone with DST is `zone.ts`'s question).
 *
 * @example
 * ```ts
 * isDuration('30m', LOOKBACK_UNITS);        // true
 * isDuration('30s', LOOKBACK_UNITS);        // false — seconds are opt-in
 * isDuration('30s', AXIS_UNITS);            // true
 * durationMs('2h', LOOKBACK_UNITS);         // 7200000
 * spellDuration(7_200_000, LOOKBACK_UNITS); // '2h' — the smallest exact spelling
 * ```
 */
/** The one duration grammar's text: `^[1-9][0-9]*[smhdw]$`, units narrowed per use. */
export type DurationText = string;
/** One unit: second, minute, hour, day (24 h), week (7 d). */
export type DurationUnit = 's' | 'm' | 'h' | 'd' | 'w';
/** Every unit, smallest first. */
export declare const DURATION_UNITS: readonly DurationUnit[];
/** A look-back's units — today's `mhdw`; `s` only by the tool's own opt-in. */
export declare const LOOKBACK_UNITS = "mhdw";
/** A dataset interval's units. */
export declare const AXIS_UNITS = "smhdw";
/**
 * Whether `units` is a unit set: a non-empty string of distinct letters from
 * `smhdw`, in any order.
 */
export declare function isUnitSet(units: unknown): units is string;
/** The count (as written, digits) and unit of a duration, or `undefined` when it is not one under `units`. */
export declare function durationParts(value: unknown, units: string): {
    readonly digits: string;
    readonly unit: DurationUnit;
} | undefined;
/** Whether `value` is a duration under `units`. A format check: any number of digits. */
export declare function isDuration(value: unknown, units: string): value is DurationText;
/**
 * The milliseconds a duration names, or `undefined` when it is not a duration
 * under `units` — or names more milliseconds than a double holds exactly (the
 * spelling is still a duration; it just cannot be measured).
 */
export declare function durationMs(value: unknown, units: string): number | undefined;
/**
 * The smallest exact spelling of `ms` in `units` — the largest unit that
 * divides it — or `undefined` when no unit in the set divides it (or `ms` is
 * not a positive whole number of milliseconds). `durationMs(spellDuration(x))`
 * is `x` whenever it is defined.
 */
export declare function spellDuration(ms: number, units: string): DurationText | undefined;