ts-time-utils 0.0.1

package/dist/esm/performance.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Async time utilities for delays, timeouts, and performance
+ */
+/**
+ * Sleep for a specified number of milliseconds
+ * @param ms - milliseconds to sleep
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Add a timeout to any promise
+ * @param promise - promise to add timeout to
+ * @param ms - timeout in milliseconds
+ * @param timeoutMessage - optional timeout error message
+ */
+export declare function timeout<T>(promise: Promise<T>, ms: number, timeoutMessage?: string): Promise<T>;
+/**
+ * Debounce function - delays execution until after delay has passed since last call
+ * @param fn - function to debounce
+ * @param delay - delay in milliseconds
+ */
+export declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle function - limits execution to once per delay period
+ * @param fn - function to throttle
+ * @param delay - delay in milliseconds
+ */
+export declare function throttle<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Retry a promise-returning function with exponential backoff
+ * @param fn - function that returns a promise
+ * @param maxAttempts - maximum number of attempts
+ * @param baseDelay - base delay in milliseconds
+ * @param maxDelay - maximum delay in milliseconds
+ */
+export declare function retry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelay?: number, maxDelay?: number): Promise<T>;
+/**
+ * Stopwatch for measuring elapsed time
+ */
+export declare class Stopwatch {
+    private startTime;
+    private endTime;
+    private pausedTime;
+    private pauseStart;
+    /**
+     * Start the stopwatch
+     */
+    start(): void;
+    /**
+     * Stop the stopwatch
+     */
+    stop(): number;
+    /**
+     * Pause the stopwatch
+     */
+    pause(): void;
+    /**
+     * Resume the stopwatch
+     */
+    resume(): void;
+    /**
+     * Reset the stopwatch
+     */
+    reset(): void;
+    /**
+     * Get elapsed time without stopping
+     */
+    getElapsed(): number;
+    /**
+     * Check if stopwatch is running
+     */
+    isRunning(): boolean;
+    /**
+     * Check if stopwatch is paused
+     */
+    isPaused(): boolean;
+}
+/**
+ * Create a new stopwatch instance
+ */
+export declare function createStopwatch(): Stopwatch;
+/**
+ * Measure execution time of a synchronous function
+ * @param fn - function to measure
+ * @returns tuple of [result, elapsed time in ms]
+ */
+export declare function measureTime<T>(fn: () => T): [T, number];
+/**
+ * Measure execution time of an asynchronous function
+ * @param fn - async function to measure
+ * @returns promise that resolves to tuple of [result, elapsed time in ms]
+ */
+export declare function measureAsync<T>(fn: () => Promise<T>): Promise<[T, number]>;
+/**
+ * Benchmark result interface
+ */
+export interface BenchmarkResult {
+    totalTime: number;
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    iterations: number;
+    opsPerSecond: number;
+}
+/**
+ * Benchmark a function by running it multiple times
+ * @param fn - function to benchmark
+ * @param iterations - number of iterations to run
+ */
+export declare function benchmark(fn: () => void, iterations?: number): BenchmarkResult;
+//# sourceMappingURL=performance.d.ts.map

package/dist/esm/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../src/performance.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,cAAc,SAAwB,GACrC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,MAAM,GACZ,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAOlC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,MAAM,GACZ,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAUlC;AAED;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAAU,EACvB,SAAS,GAAE,MAAa,EACxB,QAAQ,GAAE,MAAc,GACvB,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAuB;IAEzC;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,IAAI,IAAI,MAAM;IAed;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,MAAM,IAAI,IAAI;IAQd;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,UAAU,IAAI,MAAM;IAepB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGpB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAKvD;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAKhF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,UAAU,GAAE,MAAa,GAAG,eAAe,CAsBpF"}

package/dist/esm/performance.js

@@ -0,0 +1,222 @@
+/**
+ * Async time utilities for delays, timeouts, and performance
+ */
+/**
+ * Sleep for a specified number of milliseconds
+ * @param ms - milliseconds to sleep
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Add a timeout to any promise
+ * @param promise - promise to add timeout to
+ * @param ms - timeout in milliseconds
+ * @param timeoutMessage - optional timeout error message
+ */
+export function timeout(promise, ms, timeoutMessage = 'Operation timed out') {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(timeoutMessage)), ms))
+    ]);
+}
+/**
+ * Debounce function - delays execution until after delay has passed since last call
+ * @param fn - function to debounce
+ * @param delay - delay in milliseconds
+ */
+export function debounce(fn, delay) {
+    let timeoutId;
+    return (...args) => {
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => fn(...args), delay);
+    };
+}
+/**
+ * Throttle function - limits execution to once per delay period
+ * @param fn - function to throttle
+ * @param delay - delay in milliseconds
+ */
+export function throttle(fn, delay) {
+    let lastCall = 0;
+    return (...args) => {
+        const now = Date.now();
+        if (now - lastCall >= delay) {
+            lastCall = now;
+            fn(...args);
+        }
+    };
+}
+/**
+ * Retry a promise-returning function with exponential backoff
+ * @param fn - function that returns a promise
+ * @param maxAttempts - maximum number of attempts
+ * @param baseDelay - base delay in milliseconds
+ * @param maxDelay - maximum delay in milliseconds
+ */
+export async function retry(fn, maxAttempts = 3, baseDelay = 1000, maxDelay = 10000) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxAttempts) {
+                throw lastError;
+            }
+            // Exponential backoff with jitter
+            const delay = Math.min(baseDelay * Math.pow(2, attempt - 1) + Math.random() * 1000, maxDelay);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Stopwatch for measuring elapsed time
+ */
+export class Stopwatch {
+    constructor() {
+        this.startTime = null;
+        this.endTime = null;
+        this.pausedTime = 0;
+        this.pauseStart = null;
+    }
+    /**
+     * Start the stopwatch
+     */
+    start() {
+        if (this.startTime !== null) {
+            throw new Error('Stopwatch is already running');
+        }
+        this.startTime = performance.now();
+        this.endTime = null;
+        this.pausedTime = 0;
+        this.pauseStart = null;
+    }
+    /**
+     * Stop the stopwatch
+     */
+    stop() {
+        if (this.startTime === null) {
+            throw new Error('Stopwatch is not running');
+        }
+        if (this.pauseStart !== null) {
+            this.pausedTime += performance.now() - this.pauseStart;
+            this.pauseStart = null;
+        }
+        this.endTime = performance.now();
+        const elapsed = this.endTime - this.startTime - this.pausedTime;
+        return elapsed;
+    }
+    /**
+     * Pause the stopwatch
+     */
+    pause() {
+        if (this.startTime === null) {
+            throw new Error('Stopwatch is not running');
+        }
+        if (this.pauseStart !== null) {
+            throw new Error('Stopwatch is already paused');
+        }
+        this.pauseStart = performance.now();
+    }
+    /**
+     * Resume the stopwatch
+     */
+    resume() {
+        if (this.pauseStart === null) {
+            throw new Error('Stopwatch is not paused');
+        }
+        this.pausedTime += performance.now() - this.pauseStart;
+        this.pauseStart = null;
+    }
+    /**
+     * Reset the stopwatch
+     */
+    reset() {
+        this.startTime = null;
+        this.endTime = null;
+        this.pausedTime = 0;
+        this.pauseStart = null;
+    }
+    /**
+     * Get elapsed time without stopping
+     */
+    getElapsed() {
+        if (this.startTime === null) {
+            return 0;
+        }
+        const now = performance.now();
+        let pausedTime = this.pausedTime;
+        if (this.pauseStart !== null) {
+            pausedTime += now - this.pauseStart;
+        }
+        return now - this.startTime - pausedTime;
+    }
+    /**
+     * Check if stopwatch is running
+     */
+    isRunning() {
+        return this.startTime !== null && this.endTime === null && this.pauseStart === null;
+    }
+    /**
+     * Check if stopwatch is paused
+     */
+    isPaused() {
+        return this.pauseStart !== null;
+    }
+}
+/**
+ * Create a new stopwatch instance
+ */
+export function createStopwatch() {
+    return new Stopwatch();
+}
+/**
+ * Measure execution time of a synchronous function
+ * @param fn - function to measure
+ * @returns tuple of [result, elapsed time in ms]
+ */
+export function measureTime(fn) {
+    const start = performance.now();
+    const result = fn();
+    const elapsed = performance.now() - start;
+    return [result, elapsed];
+}
+/**
+ * Measure execution time of an asynchronous function
+ * @param fn - async function to measure
+ * @returns promise that resolves to tuple of [result, elapsed time in ms]
+ */
+export async function measureAsync(fn) {
+    const start = performance.now();
+    const result = await fn();
+    const elapsed = performance.now() - start;
+    return [result, elapsed];
+}
+/**
+ * Benchmark a function by running it multiple times
+ * @param fn - function to benchmark
+ * @param iterations - number of iterations to run
+ */
+export function benchmark(fn, iterations = 1000) {
+    const times = [];
+    for (let i = 0; i < iterations; i++) {
+        const [, elapsed] = measureTime(fn);
+        times.push(elapsed);
+    }
+    const totalTime = times.reduce((sum, time) => sum + time, 0);
+    const averageTime = totalTime / iterations;
+    const minTime = Math.min(...times);
+    const maxTime = Math.max(...times);
+    const opsPerSecond = 1000 / averageTime;
+    return {
+        totalTime,
+        averageTime,
+        minTime,
+        maxTime,
+        iterations,
+        opsPerSecond
+    };
+}

package/dist/esm/rangePresets.d.ts

@@ -0,0 +1,45 @@
+/** Predefined date range helpers (returns [start,end]) */
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+export declare function today(now?: Date): DateRange;
+export declare function yesterday(now?: Date): DateRange;
+export declare function tomorrow(now?: Date): DateRange;
+export declare function lastNDays(n: number, now?: Date): DateRange;
+export declare function nextNDays(n: number, now?: Date): DateRange;
+export declare function thisWeek(now?: Date): DateRange;
+export declare function lastWeek(now?: Date): DateRange;
+export declare function nextWeek(now?: Date): DateRange;
+export declare function thisMonth(now?: Date): DateRange;
+export declare function lastMonth(now?: Date): DateRange;
+export declare function nextMonth(now?: Date): DateRange;
+export declare function thisYear(now?: Date): DateRange;
+export declare function lastYear(now?: Date): DateRange;
+export declare function nextYear(now?: Date): DateRange;
+export declare function rollingWindowDays(days: number, now?: Date): DateRange;
+export declare function quarterRange(date?: Date): DateRange;
+export declare function lastQuarter(date?: Date): DateRange;
+export declare function nextQuarter(date?: Date): DateRange;
+/** Map of preset functions for dynamic access */
+export declare const RANGE_PRESETS: {
+    today: typeof today;
+    yesterday: typeof yesterday;
+    tomorrow: typeof tomorrow;
+    last7Days: (now?: Date) => DateRange;
+    last30Days: (now?: Date) => DateRange;
+    next7Days: (now?: Date) => DateRange;
+    thisWeek: typeof thisWeek;
+    lastWeek: typeof lastWeek;
+    nextWeek: typeof nextWeek;
+    thisMonth: typeof thisMonth;
+    lastMonth: typeof lastMonth;
+    nextMonth: typeof nextMonth;
+    thisYear: typeof thisYear;
+    lastYear: typeof lastYear;
+    nextYear: typeof nextYear;
+    quarter: typeof quarterRange;
+    lastQuarter: typeof lastQuarter;
+    nextQuarter: typeof nextQuarter;
+};
+//# sourceMappingURL=rangePresets.d.ts.map

package/dist/esm/rangePresets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rangePresets.d.ts","sourceRoot":"","sources":["../../src/rangePresets.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAE1D,MAAM,WAAW,SAAS;IAAG,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;CAAE;AAQtD,wBAAgB,KAAK,CAAC,GAAG,OAAa,GAAG,SAAS,CAA4B;AAC9E,wBAAgB,SAAS,CAAC,GAAG,OAAa,GAAG,SAAS,CAKrD;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAKpD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,OAAa,GAAG,SAAS,CAIhE;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,OAAa,GAAG,SAAS,CAIhE;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAOpD;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAKpD;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAKpD;AAED,wBAAgB,SAAS,CAAC,GAAG,OAAa,GAAG,SAAS,CAIrD;AAED,wBAAgB,SAAS,CAAC,GAAG,OAAa,GAAG,SAAS,CAKrD;AAED,wBAAgB,SAAS,CAAC,GAAG,OAAa,GAAG,SAAS,CAKrD;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAIpD;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAKpD;AAED,wBAAgB,QAAQ,CAAC,GAAG,OAAa,GAAG,SAAS,CAKpD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAa,GAAG,SAAS,CAI3E;AAED,wBAAgB,YAAY,CAAC,IAAI,OAAa,GAAG,SAAS,CAKzD;AAED,wBAAgB,WAAW,CAAC,IAAI,OAAa,GAAG,SAAS,CAKxD;AAED,wBAAgB,WAAW,CAAC,IAAI,OAAa,GAAG,SAAS,CAKxD;AAED,iDAAiD;AACjD,eAAO,MAAM,aAAa;;;;sBAEN,IAAI;uBACH,IAAI;sBACL,IAAI;;;;;;;;;;;;;CAKvB,CAAC"}

package/dist/esm/rangePresets.js

@@ -0,0 +1,124 @@
+/** Predefined date range helpers (returns [start,end]) */
+function todayRange(now = new Date()) {
+    const start = new Date(now);
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(start);
+    end.setDate(end.getDate() + 1);
+    return { start, end };
+}
+export function today(now = new Date()) { return todayRange(now); }
+export function yesterday(now = new Date()) {
+    const t = todayRange(now);
+    const end = new Date(t.start); // yesterday end equals today start
+    const start = new Date(end);
+    start.setDate(start.getDate() - 1);
+    return { start, end };
+}
+export function tomorrow(now = new Date()) {
+    const t = todayRange(now);
+    t.start.setDate(t.start.getDate() + 1);
+    t.end.setDate(t.end.getDate() + 1);
+    return t;
+}
+export function lastNDays(n, now = new Date()) {
+    const end = new Date(now);
+    const start = new Date(end);
+    start.setDate(start.getDate() - n);
+    return { start, end };
+}
+export function nextNDays(n, now = new Date()) {
+    const start = new Date(now);
+    const end = new Date(start);
+    end.setDate(end.getDate() + n);
+    return { start, end };
+}
+export function thisWeek(now = new Date()) {
+    const start = new Date(now);
+    const day = start.getDay(); // 0 Sunday
+    start.setHours(0, 0, 0, 0);
+    start.setDate(start.getDate() - day); // start of week Sunday
+    const end = new Date(start);
+    end.setDate(end.getDate() + 7);
+    return { start, end };
+}
+export function lastWeek(now = new Date()) {
+    const w = thisWeek(now);
+    w.start.setDate(w.start.getDate() - 7);
+    w.end.setDate(w.end.getDate() - 7);
+    return w;
+}
+export function nextWeek(now = new Date()) {
+    const w = thisWeek(now);
+    w.start.setDate(w.start.getDate() + 7);
+    w.end.setDate(w.end.getDate() + 7);
+    return w;
+}
+export function thisMonth(now = new Date()) {
+    const start = new Date(now.getFullYear(), now.getMonth(), 1);
+    const end = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+    return { start, end };
+}
+export function lastMonth(now = new Date()) {
+    const m = thisMonth(now);
+    m.start.setMonth(m.start.getMonth() - 1);
+    m.end.setMonth(m.end.getMonth() - 1);
+    return m;
+}
+export function nextMonth(now = new Date()) {
+    const m = thisMonth(now);
+    m.start.setMonth(m.start.getMonth() + 1);
+    m.end.setMonth(m.end.getMonth() + 1);
+    return m;
+}
+export function thisYear(now = new Date()) {
+    const start = new Date(now.getFullYear(), 0, 1);
+    const end = new Date(now.getFullYear() + 1, 0, 1);
+    return { start, end };
+}
+export function lastYear(now = new Date()) {
+    const y = thisYear(now);
+    y.start.setFullYear(y.start.getFullYear() - 1);
+    y.end.setFullYear(y.end.getFullYear() - 1);
+    return y;
+}
+export function nextYear(now = new Date()) {
+    const y = thisYear(now);
+    y.start.setFullYear(y.start.getFullYear() + 1);
+    y.end.setFullYear(y.end.getFullYear() + 1);
+    return y;
+}
+export function rollingWindowDays(days, now = new Date()) {
+    const end = new Date(now);
+    const start = new Date(end);
+    start.setDate(start.getDate() - days);
+    return { start, end };
+}
+export function quarterRange(date = new Date()) {
+    const q = Math.floor(date.getMonth() / 3); // 0-3
+    const start = new Date(date.getFullYear(), q * 3, 1);
+    const end = new Date(date.getFullYear(), q * 3 + 3, 1);
+    return { start, end };
+}
+export function lastQuarter(date = new Date()) {
+    const q = quarterRange(date);
+    q.start.setMonth(q.start.getMonth() - 3);
+    q.end.setMonth(q.end.getMonth() - 3);
+    return q;
+}
+export function nextQuarter(date = new Date()) {
+    const q = quarterRange(date);
+    q.start.setMonth(q.start.getMonth() + 3);
+    q.end.setMonth(q.end.getMonth() + 3);
+    return q;
+}
+/** Map of preset functions for dynamic access */
+export const RANGE_PRESETS = {
+    today, yesterday, tomorrow,
+    last7Days: (now) => lastNDays(7, now),
+    last30Days: (now) => lastNDays(30, now),
+    next7Days: (now) => nextNDays(7, now),
+    thisWeek, lastWeek, nextWeek,
+    thisMonth, lastMonth, nextMonth,
+    thisYear, lastYear, nextYear,
+    quarter: quarterRange, lastQuarter, nextQuarter,
+};

package/dist/esm/timezone.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Timezone utilities (rely on Intl API, fallbacks where possible)
+ */
+export interface ZonedTime {
+    date: Date;
+    zone: string;
+    offsetMinutes: number;
+}
+/** Get offset (minutes) for a zone at a given date */
+export declare function getTimezoneOffset(zone: string, date?: Date): number | null;
+/** Format date/time in a zone */
+export declare function formatInTimeZone(date: Date, zone: string, options?: Intl.DateTimeFormatOptions): string;
+/** Get a lightweight ZonedTime object */
+export declare function getZonedTime(date: Date, zone: string): ZonedTime | null;
+/** Convert a date (treated as absolute moment) to another zone's clock components */
+export declare function convertDateToZone(date: Date, zone: string): {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+} | null;
+/** Check if provided zone string is a valid IANA zone */
+export declare function isValidTimeZone(zone: string): boolean;
+/** List a subset of common timezones (cannot enumerate all via API) */
+export declare const COMMON_TIMEZONES: string[];
+/** Get current local offset in minutes */
+export declare function getLocalOffset(): number;
+/** Compare two timezones offset at given date */
+export declare function compareZoneOffsets(zoneA: string, zoneB: string, date?: Date): number | null;
+/** Shift a date by target zone offset difference relative to current local zone.
+ * This does not change the absolute moment; instead returns a new Date representing
+ * the same wall clock time in the target zone interpreted as local.
+ * For example useful for naive scheduling.
+ */
+export declare function reinterpretAsZone(date: Date, targetZone: string): Date | null;
+//# sourceMappingURL=timezone.d.ts.map

package/dist/esm/timezone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E"}

package/dist/esm/timezone.js

@@ -0,0 +1,99 @@
+/**
+ * Timezone utilities (rely on Intl API, fallbacks where possible)
+ */
+/** Get offset (minutes) for a zone at a given date */
+export function getTimezoneOffset(zone, date = new Date()) {
+    try {
+        const dtf = new Intl.DateTimeFormat('en-US', { timeZone: zone, timeZoneName: 'shortOffset', hour: '2-digit' });
+        const parts = dtf.formatToParts(date);
+        const tzPart = parts.find(p => p.type === 'timeZoneName');
+        if (!tzPart)
+            return null;
+        // Examples: "GMT+2", "UTC-05:00"
+        const match = tzPart.value.match(/([+-])(\d{1,2})(?::?(\d{2}))?/);
+        if (!match)
+            return 0; // could be GMT or UTC with no offset
+        const sign = match[1] === '-' ? -1 : 1;
+        const hours = parseInt(match[2], 10);
+        const mins = match[3] ? parseInt(match[3], 10) : 0;
+        return sign * (hours * 60 + mins);
+    }
+    catch {
+        return null;
+    }
+}
+/** Format date/time in a zone */
+export function formatInTimeZone(date, zone, options = {}) {
+    const fmt = new Intl.DateTimeFormat('en-US', { timeZone: zone, ...options });
+    return fmt.format(date);
+}
+/** Get a lightweight ZonedTime object */
+export function getZonedTime(date, zone) {
+    const offset = getTimezoneOffset(zone, date);
+    if (offset == null)
+        return null;
+    return { date: new Date(date), zone, offsetMinutes: offset };
+}
+/** Convert a date (treated as absolute moment) to another zone's clock components */
+export function convertDateToZone(date, zone) {
+    try {
+        const fmt = new Intl.DateTimeFormat('en-US', {
+            timeZone: zone,
+            year: 'numeric', month: '2-digit', day: '2-digit',
+            hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false
+        });
+        const parts = fmt.formatToParts(date);
+        const get = (type) => parseInt(parts.find(p => p.type === type)?.value || '0', 10);
+        return {
+            year: get('year'),
+            month: get('month'),
+            day: get('day'),
+            hour: get('hour'),
+            minute: get('minute'),
+            second: get('second')
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Check if provided zone string is a valid IANA zone */
+export function isValidTimeZone(zone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** List a subset of common timezones (cannot enumerate all via API) */
+export const COMMON_TIMEZONES = [
+    'UTC', 'Etc/UTC', 'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Europe/Madrid', 'Europe/Rome',
+    'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles', 'America/Toronto', 'America/Sao_Paulo',
+    'Asia/Tehran', 'Asia/Dubai', 'Asia/Tokyo', 'Asia/Shanghai', 'Asia/Singapore', 'Asia/Kolkata', 'Asia/Hong_Kong',
+    'Australia/Sydney', 'Pacific/Auckland'
+];
+/** Get current local offset in minutes */
+export function getLocalOffset() {
+    return -new Date().getTimezoneOffset();
+}
+/** Compare two timezones offset at given date */
+export function compareZoneOffsets(zoneA, zoneB, date = new Date()) {
+    const a = getTimezoneOffset(zoneA, date);
+    const b = getTimezoneOffset(zoneB, date);
+    if (a == null || b == null)
+        return null;
+    return a - b; // positive if A ahead of B
+}
+/** Shift a date by target zone offset difference relative to current local zone.
+ * This does not change the absolute moment; instead returns a new Date representing
+ * the same wall clock time in the target zone interpreted as local.
+ * For example useful for naive scheduling.
+ */
+export function reinterpretAsZone(date, targetZone) {
+    const target = convertDateToZone(date, targetZone);
+    if (!target)
+        return null;
+    return new Date(Date.UTC(target.year, target.month - 1, target.day, target.hour, target.minute, target.second));
+}