@venizia/ignis-helpers 0.2.0-9 → 0.2.0

package/dist/esm/modules/temporal/calendar.js

@@ -0,0 +1,138 @@
+import { TemporalUnits } from './common/constants.js';
+/** The years a four-digit `YYYY` spells - the range every method reads and writes. */
+export const MIN_TEMPORAL_YEAR = 1;
+export const MAX_TEMPORAL_YEAR = 9999;
+const MILLISECONDS_PER_MINUTE = 60_000;
+/** A UTC scratch date for calendar math - `Date.UTC` maps years 0-99 onto 1900-1999, `setUTCFullYear` does not. */
+const calendarDate = (opts) => {
+    const date = new Date(0);
+    date.setUTCFullYear(opts.year, opts.month - 1, opts.day);
+    return date;
+};
+export const isSupportedYear = (year) => year >= MIN_TEMPORAL_YEAR && year <= MAX_TEMPORAL_YEAR;
+export const daysInMonth = (opts) => calendarDate({ year: opts.year, month: opts.month + 1, day: 0 }).getUTCDate();
+/** `parts` moved by whole days on the calendar, wall time untouched. */
+export const shiftDays = (opts) => {
+    const { parts, days } = opts;
+    const date = calendarDate({ year: parts.year, month: parts.month, day: parts.day + days });
+    return {
+        ...parts,
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+    };
+};
+/** `parts` moved by whole months, the day clamped to the target month: Jan 31 + 1 month is Feb 28. */
+export const shiftMonths = (opts) => {
+    const { parts, months } = opts;
+    const total = parts.year * 12 + (parts.month - 1) + months;
+    const year = Math.floor(total / 12);
+    const month = total - year * 12 + 1;
+    return { ...parts, year, month, day: Math.min(parts.day, daysInMonth({ year, month })) };
+};
+/** Whether the fields name a day and a time the calendar has - Feb 30, 24:00 and year 0 do not. */
+export const isRealDateTime = (opts) => {
+    const { year, month, day, hour, minute, second, millisecond } = opts.parts;
+    return (isSupportedYear(year) &&
+        month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInMonth({ year, month }) &&
+        hour >= 0 &&
+        hour <= 23 &&
+        minute >= 0 &&
+        minute <= 59 &&
+        second >= 0 &&
+        second <= 59 &&
+        millisecond >= 0 &&
+        millisecond <= 999);
+};
+/** Epoch milliseconds of wall-clock fields read at a fixed offset. */
+export const epochAtOffset = (opts) => {
+    const { parts, offsetMilliseconds } = opts;
+    const date = calendarDate({ year: parts.year, month: parts.month, day: parts.day });
+    date.setUTCHours(parts.hour, parts.minute, parts.second, parts.millisecond);
+    return date.getTime() - offsetMilliseconds;
+};
+/** The wall clock an instant shows at a fixed offset - pure arithmetic, never the host's zone. */
+export const wallClockAt = (opts) => {
+    const { epoch, offsetMilliseconds } = opts;
+    const date = new Date(epoch + offsetMilliseconds);
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+        hour: date.getUTCHours(),
+        minute: date.getUTCMinutes(),
+        second: date.getUTCSeconds(),
+        millisecond: date.getUTCMilliseconds(),
+        // `getUTCDay` counts Sunday as 0; ISO counts Monday as 1 and Sunday as 7.
+        dayOfWeek: ((date.getUTCDay() + 6) % 7) + 1,
+        offsetMinutes: offsetMilliseconds / MILLISECONDS_PER_MINUTE,
+    };
+};
+/** Units that measure elapsed time rather than the calendar - 24 hours is not always a day. */
+export const EXACT_UNIT_MILLISECONDS = {
+    [TemporalUnits.MILLISECOND]: 1,
+    [TemporalUnits.SECOND]: 1_000,
+    [TemporalUnits.MINUTE]: 60_000,
+    [TemporalUnits.HOUR]: 3_600_000,
+};
+/** The wall-clock fields alone, without the weekday and the offset. */
+export const wallClockOf = (opts) => {
+    const { year, month, day, hour, minute, second, millisecond } = opts.parts;
+    return { year, month, day, hour, minute, second, millisecond };
+};
+/** The wall-clock start of the unit holding `parts`. Weeks start on Monday. */
+export const truncateTo = (opts) => {
+    const { parts, unit } = opts;
+    const wall = wallClockOf({ parts });
+    switch (unit) {
+        case TemporalUnits.SECOND: {
+            return { ...wall, millisecond: 0 };
+        }
+        case TemporalUnits.MINUTE: {
+            return { ...wall, second: 0, millisecond: 0 };
+        }
+        case TemporalUnits.HOUR: {
+            return { ...wall, minute: 0, second: 0, millisecond: 0 };
+        }
+        case TemporalUnits.DAY: {
+            return { ...wall, hour: 0, minute: 0, second: 0, millisecond: 0 };
+        }
+        case TemporalUnits.WEEK: {
+            const midnight = { ...wall, hour: 0, minute: 0, second: 0, millisecond: 0 };
+            return shiftDays({ parts: midnight, days: 1 - parts.dayOfWeek });
+        }
+        case TemporalUnits.MONTH: {
+            return { ...wall, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0 };
+        }
+        default: {
+            return { ...wall, month: 1, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0 };
+        }
+    }
+};
+/** `parts` moved by whole units on the wall clock - no time zone involved. */
+export const shiftWallClock = (opts) => {
+    const { parts, amount, unit } = opts;
+    const exact = EXACT_UNIT_MILLISECONDS[unit];
+    if (exact !== undefined) {
+        const epoch = epochAtOffset({ parts, offsetMilliseconds: 0 }) + amount * exact;
+        return wallClockOf({ parts: wallClockAt({ epoch, offsetMilliseconds: 0 }) });
+    }
+    switch (unit) {
+        case TemporalUnits.DAY: {
+            return shiftDays({ parts, days: amount });
+        }
+        case TemporalUnits.WEEK: {
+            return shiftDays({ parts, days: amount * 7 });
+        }
+        case TemporalUnits.MONTH: {
+            return shiftMonths({ parts, months: amount });
+        }
+        default: {
+            return shiftMonths({ parts, months: amount * 12 });
+        }
+    }
+};
+//# sourceMappingURL=calendar.js.map

package/dist/esm/modules/temporal/calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.js","sourceRoot":"","sources":["../../../../src/modules/temporal/calendar.ts"],"names":[],"mappings":"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"}

package/dist/esm/modules/temporal/common/constants.d.ts

@@ -0,0 +1,20 @@
+import type { TConstValue } from '../../../common/types/index.js';
+/** Units `add`, `subtract`, `startOf` and `endOf` accept. Weeks are ISO weeks - they start on Monday. */
+export declare class TemporalUnits {
+    static readonly MILLISECOND = "millisecond";
+    static readonly SECOND = "second";
+    static readonly MINUTE = "minute";
+    static readonly HOUR = "hour";
+    static readonly DAY = "day";
+    static readonly WEEK = "week";
+    static readonly MONTH = "month";
+    static readonly YEAR = "year";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(input: string): input is TTemporalUnit;
+}
+export type TTemporalUnit = TConstValue<typeof TemporalUnits>;
+/** A helper built without a `timeZone` computes in UTC - never in the host's zone, which differs per machine. */
+export declare const DEFAULT_TEMPORAL_TIME_ZONE = "UTC";
+/** `format` with no pattern writes ISO 8601 with the zone's offset: `2026-09-19T12:00:00.000+07:00`. */
+export declare const DEFAULT_TEMPORAL_PATTERN = "YYYY-MM-DDTHH:mm:ss.SSSZ";
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/modules/temporal/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/modules/temporal/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,yGAAyG;AACzG,qBAAa,aAAa;IACxB,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAC5C,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAClC,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAClC,MAAM,CAAC,QAAQ,CAAC,IAAI,UAAU;IAC9B,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;IAC5B,MAAM,CAAC,QAAQ,CAAC,IAAI,UAAU;IAC9B,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,UAAU;IAE9B,MAAM,CAAC,QAAQ,CAAC,UAAU,cASvB;IAEH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa;CAGtD;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAE9D,iHAAiH;AACjH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD,wGAAwG;AACxG,eAAO,MAAM,wBAAwB,6BAA6B,CAAC"}

package/dist/esm/modules/temporal/common/constants.js

@@ -0,0 +1,29 @@
+/** Units `add`, `subtract`, `startOf` and `endOf` accept. Weeks are ISO weeks - they start on Monday. */
+export class TemporalUnits {
+    static { this.MILLISECOND = 'millisecond'; }
+    static { this.SECOND = 'second'; }
+    static { this.MINUTE = 'minute'; }
+    static { this.HOUR = 'hour'; }
+    static { this.DAY = 'day'; }
+    static { this.WEEK = 'week'; }
+    static { this.MONTH = 'month'; }
+    static { this.YEAR = 'year'; }
+    static { this.SCHEME_SET = new Set([
+        this.MILLISECOND,
+        this.SECOND,
+        this.MINUTE,
+        this.HOUR,
+        this.DAY,
+        this.WEEK,
+        this.MONTH,
+        this.YEAR,
+    ]); }
+    static isValid(input) {
+        return this.SCHEME_SET.has(input);
+    }
+}
+/** A helper built without a `timeZone` computes in UTC - never in the host's zone, which differs per machine. */
+export const DEFAULT_TEMPORAL_TIME_ZONE = 'UTC';
+/** `format` with no pattern writes ISO 8601 with the zone's offset: `2026-09-19T12:00:00.000+07:00`. */
+export const DEFAULT_TEMPORAL_PATTERN = 'YYYY-MM-DDTHH:mm:ss.SSSZ';
+//# sourceMappingURL=constants.js.map

package/dist/esm/modules/temporal/common/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/modules/temporal/common/constants.ts"],"names":[],"mappings":"AAEA,yGAAyG;AACzG,MAAM,OAAO,aAAa;aACR,gBAAW,GAAG,aAAa,CAAC;aAC5B,WAAM,GAAG,QAAQ,CAAC;aAClB,WAAM,GAAG,QAAQ,CAAC;aAClB,SAAI,GAAG,MAAM,CAAC;aACd,QAAG,GAAG,KAAK,CAAC;aACZ,SAAI,GAAG,MAAM,CAAC;aACd,UAAK,GAAG,OAAO,CAAC;aAChB,SAAI,GAAG,MAAM,CAAC;aAEd,eAAU,GAAG,IAAI,GAAG,CAAC;QACnC,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,KAAK;QACV,IAAI,CAAC,IAAI;KACV,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAKH,iHAAiH;AACjH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD,wGAAwG;AACxG,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC"}

package/dist/esm/modules/temporal/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/temporal/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/modules/temporal/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/esm/modules/temporal/common/index.js

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/modules/temporal/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/modules/temporal/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/esm/modules/temporal/common/types.d.ts

@@ -0,0 +1,69 @@
+/** What a date-taking method accepts: a `Date`, epoch milliseconds, or an ISO 8601 string. */
+export type TTemporalInput = Date | number | string;
+/** Wall-clock fields. `month` is 1-12, `day` 1-31 - never zero-based. */
+export interface ITemporalParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+}
+/** The wall clock an instant shows in one time zone. `dayOfWeek` is ISO: 1 Monday - 7 Sunday. */
+export interface IZonedTemporalParts extends ITemporalParts {
+    dayOfWeek: number;
+    /** Minutes east of UTC: `420` for `+07:00`. Historic local mean time carries seconds, as a fraction. */
+    offsetMinutes: number;
+}
+/**
+ * The one question a date library answers: which UTC offset a time zone observes at an instant.
+ * Everything else - the wall clock, a time a daylight-saving jump skips or repeats, adding a month,
+ * the start of a week, a pattern - `TemporalHelper` works out once from these answers, so every
+ * adapter shares one behaviour.
+ */
+export interface ITemporalAdapter {
+    /** Milliseconds east of UTC that `timeZone` observes at `value`: `25_200_000` for `+07:00`. */
+    getOffsetMilliseconds(opts: {
+        value: Date;
+        timeZone: string;
+    }): number;
+}
+/** The part of a `Temporal.ZonedDateTime` this adapter reads. */
+export interface ITemporalZonedDateTime {
+    readonly offsetNanoseconds: number;
+}
+/**
+ * The part of the `Temporal` namespace this adapter drives - structural, so neither this package
+ * nor its consumers need Temporal's type definitions, and a polyfill's namespace fits as well.
+ */
+export interface ITemporalNamespace {
+    Instant: {
+        fromEpochMilliseconds(epochMilliseconds: number): {
+            toZonedDateTimeISO(timeZone: string): ITemporalZonedDateTime;
+        };
+    };
+}
+/** The part of a `Dayjs` object this adapter reads. */
+export interface IDayjsInstance {
+    utcOffset(): number;
+    tz(timeZone: string): IDayjsInstance;
+}
+/** The part of the `dayjs` factory this adapter drives - with the `utc` and `timezone` plugins extended. */
+export interface IDayjsFactory {
+    (value?: Date | number): IDayjsInstance;
+    tz: (value: string, timeZone: string) => IDayjsInstance;
+}
+/** The part of a Luxon `DateTime` this adapter reads. */
+export interface ILuxonDateTime {
+    readonly isValid: boolean;
+    readonly invalidReason: string | null;
+    readonly offset: number;
+}
+/** The part of Luxon's `DateTime` class this adapter drives. */
+export interface ILuxonDateTimeFactory {
+    fromMillis(milliseconds: number, options: {
+        zone: string;
+    }): ILuxonDateTime;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/modules/temporal/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/modules/temporal/common/types.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpD,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iGAAiG;AACjG,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,qBAAqB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CACxE;AAID,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE;QACP,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG;YAChD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAAC;SAC9D,CAAC;KACH,CAAC;CACH;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,SAAS,IAAI,MAAM,CAAC;IACpB,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAAC;CACtC;AAED,4GAA4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,cAAc,CAAC;IACxC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,cAAc,CAAC;CACzD;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC;CAC7E"}

package/dist/esm/modules/temporal/common/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/modules/temporal/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/modules/temporal/common/types.ts"],"names":[],"mappings":""}

package/dist/esm/modules/temporal/helper.d.ts

@@ -0,0 +1,120 @@
+import { BaseHelper } from '../base.js';
+import type { TTemporalUnit } from './common/constants.js';
+import type { ITemporalAdapter, IZonedTemporalParts, TTemporalInput } from './common/types.js';
+/**
+ * Dates in one time zone, through whichever library you choose: pass an adapter - the runtime's
+ * `Temporal` (the default), your own dayjs, your own Luxon. The adapter only reports a zone's UTC
+ * offset at an instant; the wall clock, daylight-saving gaps and repeats, and the calendar math all
+ * live here, so every adapter shares one behaviour.
+ *
+ * Values go in as a `Date`, epoch milliseconds or an ISO 8601 string, and come out as a `Date`, so
+ * swapping the adapter never touches a call site. The zone is yours to set: without one this helper
+ * computes in UTC, never in the host's zone. Years run from 1 to 9999.
+ */
+export declare class TemporalHelper extends BaseHelper {
+    /** Validated once per process: `Intl` answers the same for a zone name every time. */
+    private static readonly knownTimeZones;
+    private readonly adapter;
+    private readonly timeZone;
+    constructor(opts?: {
+        adapter?: ITemporalAdapter;
+        timeZone?: string;
+        scope?: string;
+    });
+    private static ensureTimeZone;
+    private static ensureUnit;
+    /** Every result passes here: an overflowing `add` is refused, never an Invalid Date. */
+    private static ensureInstant;
+    private static ensureYear;
+    private resolveTimeZone;
+    /** The adapter's one answer, rounded: an offset is whole milliseconds, a library's float may not be. */
+    private offsetAt;
+    private zonedParts;
+    /**
+     * Every instant whose wall clock reads `parts` in the zone, earliest first: one as a rule, two
+     * when the clock goes back, none when it jumps forward. `forward` is where a skipped time lands -
+     * read with the offset from before the jump, so it moves past the gap.
+     */
+    private instantsOf;
+    /** The instant wall-clock `parts` name: a skipped time moves forward, a repeated one takes the earlier. */
+    private earliestOf;
+    /**
+     * `[start, end)` of the unit holding `epoch`. A day or longer starts at its first instant. An hour
+     * or less repeats when the clock goes back, so it starts at the latest start not after `epoch`,
+     * and ends where the wall clock next shows either the following unit or this one's start again.
+     */
+    private unitBounds;
+    getTimeZone(): string;
+    now(): Date;
+    /** The instant a value names. An ISO string without an offset is read as wall clock in the zone. */
+    toDate(opts: {
+        value: TTemporalInput;
+        timeZone?: string;
+    }): Date;
+    /** The wall clock the value shows in the zone, with its ISO weekday and UTC offset. */
+    parts(opts: {
+        value: TTemporalInput;
+        timeZone?: string;
+    }): IZonedTemporalParts;
+    /**
+     * Reads a string. With a `pattern` (`YYYY YY MM M DD D HH H mm m ss s SSS Z ZZ`, text in
+     * `[brackets]`), the value must match it exactly; without one it must be ISO 8601. An offset in
+     * the value wins; otherwise the fields are wall clock in the zone.
+     */
+    parse(opts: {
+        value: string;
+        pattern?: string;
+        timeZone?: string;
+    }): Date;
+    private readIso;
+    /** Writes the value in the zone. Without a `pattern`: ISO 8601 with the zone's offset. */
+    format(opts: {
+        value: TTemporalInput;
+        pattern?: string;
+        timeZone?: string;
+    }): string;
+    /**
+     * Moves the value by whole units. Hours and smaller are elapsed time; days and larger move the
+     * calendar in the zone, so a day across a daylight-saving jump keeps the wall time, and a month
+     * past a shorter month clamps to its last day.
+     */
+    add(opts: {
+        value: TTemporalInput;
+        amount: number;
+        unit: TTemporalUnit;
+        timeZone?: string;
+    }): Date;
+    subtract(opts: {
+        value: TTemporalInput;
+        amount: number;
+        unit: TTemporalUnit;
+        timeZone?: string;
+    }): Date;
+    /** The first instant of the unit containing the value, in the zone. Weeks start on Monday. */
+    startOf(opts: {
+        value: TTemporalInput;
+        unit: TTemporalUnit;
+        timeZone?: string;
+    }): Date;
+    /** The last millisecond of the unit containing the value, in the zone. */
+    endOf(opts: {
+        value: TTemporalInput;
+        unit: TTemporalUnit;
+        timeZone?: string;
+    }): Date;
+    /** Monday to Friday, read on the wall clock of the zone. */
+    isWeekday(opts: {
+        value: TTemporalInput;
+        timeZone?: string;
+    }): boolean;
+    nextWeekday(opts: {
+        value: TTemporalInput;
+        timeZone?: string;
+    }): Date;
+    previousWeekday(opts: {
+        value: TTemporalInput;
+        timeZone?: string;
+    }): Date;
+    private stepToWeekday;
+}
+//# sourceMappingURL=helper.d.ts.map

package/dist/esm/modules/temporal/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../../src/modules/temporal/helper.ts"],"names":[],"mappings":"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"}