inviton-powerduck 0.0.153 → 0.0.155

package/common/temporal-helpers.ts

@@ -0,0 +1,551 @@
+// import { Temporal } from '@js-temporal/polyfill';
+// import PowerduckState from '../app/powerduck-state';
+
+// /**
+//  * Helper functions for Temporal dates, maintaining compatibility with DateWrapper behavior
+//  */
+
+// // Type alias for cleaner code
+// type TemporalDate = Temporal.PlainDateTime;
+
+// /**
+//  * Create Temporal date from wire format string
+//  */
+// export const fromWire = (value: string): TemporalDate | null => {
+// 	if (value != null && value.length > 0) {
+// 		if (value.includes('T')) {
+// 			let year: number, month: number, day: number, hour: number, minute: number, second: string | number;
+// 			const dtSplit = value.split('T');
+// 			const dateSplit = dtSplit[0].split('-');
+// 			const timeSplit = dtSplit[1].split(':');
+
+// 			if (dateSplit.length == 3) {
+// 				year = Number(dateSplit[0]);
+// 				month = Number(dateSplit[1]); // Keep 1-based for Temporal
+// 				day = Number(dateSplit[2]);
+
+// 				if (timeSplit.length > 1) {
+// 					hour = Number(timeSplit[0]);
+// 					minute = Number(timeSplit[1]);
+// 					second = timeSplit[2] || 0;
+
+// 					if (second != null && second != 0) {
+// 						try {
+// 							if (typeof second === 'string' && second.includes('.')) {
+// 								second = Number(second.split('.')[0]);
+// 							} else {
+// 								second = Number(second);
+// 							}
+// 						} catch (e) { }
+// 					}
+
+// 					if (isNaN(second as number)) {
+// 						second = 0;
+// 					}
+
+// 					return new Temporal.PlainDateTime(
+// 						year,
+// 						month,
+// 						day,
+// 						hour,
+// 						minute,
+// 						second as number,
+// 						0,
+// 					);
+// 				}
+// 			}
+// 		} else {
+// 			const splitVal = value.split('-');
+// 			if (splitVal.length == 3) {
+// 				return new Temporal.PlainDateTime(
+// 					Number(splitVal[0]),
+// 					Number(splitVal[1]), // Keep 1-based for Temporal
+// 					Number(splitVal[2]),
+// 					0,
+// 					0,
+// 					0,
+// 					0,
+// 				);
+// 			} else if (splitVal.length == 5) {
+// 				// TODO: Handle this case
+// 			}
+// 		}
+// 	}
+
+// 	return null;
+// };
+
+// /**
+//  * Convert to wire format string
+//  */
+// export const toWire = (
+// 	date: TemporalDate,
+// 	includeTime?: boolean,
+// 	includeMs?: boolean,
+// ): string => {
+// 	const formatDatePart = (v: number) => {
+// 		if (v < 10) {
+// 			return `0${v.toString()}`;
+// 		} else {
+// 			return v.toString();
+// 		}
+// 	};
+
+// 	let datePart = `${date.year}-${formatDatePart(date.month)}-${formatDatePart(date.day)}`;
+// 	if (includeTime) {
+// 		datePart += `T${formatDatePart(date.hour)}:${formatDatePart(date.minute)}:${formatDatePart(date.second)}`;
+// 	}
+
+// 	if (includeMs) {
+// 		let ms = date.millisecond.toString();
+// 		if (ms.length == 1) {
+// 			ms = `00${ms}`;
+// 		} else if (ms.length == 2) {
+// 			ms = `0${ms}`;
+// 		}
+
+// 		datePart += `.${ms}Z`;
+// 	}
+
+// 	return datePart;
+// };
+
+// /**
+//  * Create a new Temporal date with individual components (0-based month for compatibility)
+//  */
+// export const createDate = (
+// 	year: number,
+// 	month: number,
+// 	date?: number,
+// 	hours?: number,
+// 	minutes?: number,
+// 	seconds?: number,
+// 	ms?: number,
+// ): TemporalDate => {
+// 	const plusYears = Math.floor(month / 12);
+// 	return new Temporal.PlainDateTime(
+// 		year + plusYears,
+// 		(month % 12) + 1, // Convert from 0-based to 1-based month
+// 		date || 1,
+// 		hours || 0,
+// 		minutes || 0,
+// 		seconds || 0,
+// 		ms || 0,
+// 	);
+// };
+
+// /**
+//  * Create Temporal date from epoch milliseconds
+//  */
+// export const dateFromEpochMilliseconds = (timestamp: number): TemporalDate => {
+// 	const instant = Temporal.Instant.fromEpochMilliseconds(timestamp);
+// 	return instant.toZonedDateTimeISO('UTC').toPlainDateTime();
+// };
+
+// /**
+//  * Create Temporal date from wire format string
+//  */
+// export const dateFromString = (value: string): TemporalDate | null => fromWire(value);
+
+// /**
+//  * Create Temporal date from JS Date object
+//  */
+// export const dateFromJSDate = (jsDate: Date): TemporalDate => new Temporal.PlainDateTime(
+// 	jsDate.getFullYear(),
+// 	jsDate.getMonth() + 1, // Convert to 1-based month
+// 	jsDate.getDate(),
+// 	jsDate.getHours(),
+// 	jsDate.getMinutes(),
+// 	jsDate.getSeconds(),
+// 	jsDate.getMilliseconds(),
+// );
+
+// /**
+//  * Get current date/time as Temporal date
+//  */
+// export const dateNow = (): TemporalDate => Temporal.Now.plainDateTimeISO();
+
+// /**
+//  * Universal date creator - accepts any format and decides based on input (for easy migration)
+//  * Supports:
+//  * - No params: current date
+//  * - Single number: epoch milliseconds
+//  * - Single string: wire format string
+//  * - Single Date: JS Date object
+//  * - Single Temporal: returns as-is
+//  * - Multiple numbers: year, month, date, etc. (0-based month)
+//  */
+// export function createDateUniversal(): TemporalDate;
+// export function createDateUniversal(temporal: TemporalDate): TemporalDate;
+// export function createDateUniversal(timestamp: number): TemporalDate;
+// export function createDateUniversal(dateString: string): TemporalDate | null;
+// export function createDateUniversal(jsDate: Date): TemporalDate;
+// export function createDateUniversal(temporalDate: TemporalDate): TemporalDate;
+// export function createDateUniversal(year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number): TemporalDate;
+// export function createDateUniversal(
+// 	input?: number | string | Date | TemporalDate,
+// 	month?: number,
+// 	date?: number,
+// 	hours?: number,
+// 	minutes?: number,
+// 	seconds?: number,
+// 	ms?: number,
+// ): TemporalDate | null {
+// 	// No parameters - current date
+// 	if (input === undefined) {
+// 		return dateNow();
+// 	}
+
+// 	// Multiple parameters - individual components
+// 	if (month !== undefined) {
+// 		return createDate(
+// 			input as number,
+// 			month, // Convert from 0-based to 1-based month
+// 			date,
+// 			hours,
+// 			minutes,
+// 			seconds,
+// 			ms,
+// 		);
+// 	}
+
+// 	// Single parameter - determine type
+// 	if (typeof input === 'number') {
+// 		return dateFromEpochMilliseconds(input);
+// 	}
+
+// 	if (typeof input === 'string') {
+// 		return dateFromString(input);
+// 	}
+
+// 	if (input instanceof Date) {
+// 		return dateFromJSDate(input);
+// 	}
+
+// 	if (input instanceof Temporal.PlainDateTime) {
+// 		return input; // Already a Temporal date
+// 	}
+
+// 	return null; // Unknown input type
+// }
+
+// /**
+//  * Clone a Temporal date (returns the same instance since Temporal dates are immutable)
+//  */
+// export const cloneDate = (date: TemporalDate): TemporalDate => date;
+
+// /**
+//  * Serialize date to string
+//  */
+// export const serializeDate = (date: TemporalDate): string => toWire(date, true);
+
+// /**
+//  * Convert to JSON string
+//  */
+// export const toJSON = (date: TemporalDate, key?: any): string => date.toZonedDateTime('UTC').toInstant().toJSON();
+
+// /**
+//  * Convert to locale date string
+//  */
+// export const toLocaleDateString = (
+// 	date: TemporalDate,
+// 	locale?: string,
+// 	opts?: Intl.DateTimeFormatOptions & { language?: string },
+// ): string => {
+// 	const options = { ...opts, timeZone: 'UTC' };
+
+// 	try {
+// 		return new Intl.DateTimeFormat(locale ?? opts?.language, options).format(date as any);
+// 	} catch (e) {
+// 		return date.toString();
+// 	}
+// };
+
+// /**
+//  * Convert to display string
+//  */
+// export function toDisplayString(date: TemporalDate): string;
+// export function toDisplayString(date: TemporalDate, showTime?: boolean, showSeconds?: boolean, monthLong?: boolean): string;
+// export function toDisplayString(date: TemporalDate, options: {
+// 	showTime?: boolean;
+// 	showSeconds?: boolean;
+// 	monthLong?: boolean;
+// 	dayLong?: boolean;
+// 	hideDay?: boolean;
+// 	hideMonth?: boolean;
+// 	hideYear?: boolean;
+// 	language?: string;
+// }): string;
+// export function toDisplayString(
+// 	date: TemporalDate,
+// 	optionsOrShowTime?: boolean | {
+// 		showTime?: boolean;
+// 		showSeconds?: boolean;
+// 		monthLong?: boolean;
+// 		dayLong?: boolean;
+// 		hideDay?: boolean;
+// 		hideMonth?: boolean;
+// 		hideYear?: boolean;
+// 		language?: string;
+// 	},
+// 	showTime?: boolean,
+// 	showSeconds?: boolean,
+// 	monthLong?: boolean,
+// ): string {
+// 	let opts = {} as any;
+// 	if (typeof optionsOrShowTime === 'object') {
+// 		opts = optionsOrShowTime;
+// 	} else {
+// 		opts = {
+// 			showTime: optionsOrShowTime,
+// 			showSeconds,
+// 			monthLong,
+// 		};
+// 	}
+
+// 	const args = {
+// 		year: !opts.hideYear ? 'numeric' : undefined,
+// 		month: !opts.hideMonth ? (opts.monthLong ? 'long' : 'numeric') : undefined,
+// 		day: !opts.hideDay && !opts.dayLong ? 'numeric' : undefined,
+// 		weekday: opts.dayLong ? 'long' : undefined,
+// 		timeZone: 'UTC',
+// 	} as any as Intl.DateTimeFormatOptions;
+
+// 	if (showTime || opts.showTime) {
+// 		args.hour = 'numeric';
+// 		args.minute = '2-digit';
+// 	}
+
+// 	if (showSeconds || opts.showSeconds) {
+// 		args.second = '2-digit';
+// 	}
+
+// 	try {
+// 		return toLocaleDateString(
+// 			date,
+// 			opts.language || PowerduckState.getCurrentLanguage(),
+// 			args,
+// 		);
+// 	} catch (e) {
+// 		return date?.toString();
+// 	}
+// }
+
+// /**
+//  * Convert to locale time string
+//  */
+// export const toLocaleTimeString = (date: TemporalDate, opts: Intl.DateTimeFormatOptions & { language?: string }): string => {
+// 	const options = { ...opts, timeZone: 'UTC' };
+
+// 	try {
+// 		// eslint-disable-next-line no-restricted-syntax
+// 		const jsDate = new Date(date.toZonedDateTime('UTC').epochMilliseconds);
+// 		return jsDate.toLocaleTimeString(opts.language || PowerduckState.getCurrentLanguage(), options);
+// 	} catch (e) {
+// 		return date.toString();
+// 	}
+// };
+
+// /**
+//  * Convert to display string without UTC (uses local timezone)
+//  */
+// export const toDisplayStringNonUtc = (
+// 	date: TemporalDate,
+// 	showTime?: boolean,
+// 	showSeconds?: boolean,
+// 	monthLong?: boolean,
+// ): string => {
+// 	const args = {
+// 		year: 'numeric',
+// 		month: monthLong ? 'long' : 'numeric',
+// 		day: 'numeric',
+// 	} as any as Intl.DateTimeFormatOptions;
+
+// 	if (showTime) {
+// 		args.hour = 'numeric';
+// 		args.minute = '2-digit';
+// 	}
+
+// 	if (showSeconds) {
+// 		args.second = '2-digit';
+// 	}
+
+// 	try {
+// 		// eslint-disable-next-line no-restricted-syntax
+// 		const jsDate = new Date(date.toZonedDateTime('UTC').epochMilliseconds);
+// 		return jsDate.toLocaleDateString(PowerduckState.getCurrentLanguage(), args);
+// 	} catch (e) {
+// 		return date.toString();
+// 	}
+// };
+
+// /**
+//  * Get time as milliseconds since epoch
+//  */
+// export const getTime = (date: TemporalDate): number => date?.toZonedDateTime?.('UTC')?.epochMilliseconds;
+
+// /**
+//  * Get full year
+//  */
+// export const getFullYear = (date: TemporalDate): number => date.year;
+
+// /**
+//  * Get month (0-based to match DateWrapper behavior)
+//  */
+// export const getMonth = (date: TemporalDate): number => date.month - 1;
+
+// /**
+//  * Get date
+//  */
+// export const getDate = (date: TemporalDate): number => date.day;
+
+// /**
+//  * Get day of week (0 = Sunday)
+//  */
+// export const getDay = (date: TemporalDate): number => date.dayOfWeek % 7;
+
+// /**
+//  * Get hours
+//  */
+// export const getHours = (date: TemporalDate): number => date.hour;
+
+// /**
+//  * Get minutes
+//  */
+// export const getMinutes = (date: TemporalDate): number => date.minute;
+
+// /**
+//  * Get seconds
+//  */
+// export const getSeconds = (date: TemporalDate): number => date.second;
+
+// /**
+//  * Get milliseconds
+//  */
+// export const getMilliseconds = (date: TemporalDate): number => date.millisecond;
+
+// /**
+//  * Get timezone offset (always 0 since we work in UTC)
+//  */
+// export const getTimezoneOffset = (_date: TemporalDate): number => 0;
+
+// /**
+//  * Get current date
+//  */
+// export const getCurrent = (): TemporalDate => dateNow();
+
+// /**
+//  * Set time from milliseconds since epoch
+//  */
+// export const setTime = (date: TemporalDate, time: number): TemporalDate => {
+// 	const instant = Temporal.Instant.fromEpochMilliseconds(time);
+// 	return instant.toZonedDateTimeISO('UTC').toPlainDateTime();
+// };
+
+// /**
+//  * Set seconds
+//  */
+// export const setSeconds = (
+// 	date: TemporalDate,
+// 	sec: number,
+// 	ms?: number,
+// ): TemporalDate => date.with({
+// 	second: sec,
+// 	millisecond: ms ?? date.millisecond,
+// });
+
+// /**
+//  * Set minutes
+//  */
+// export const setMinutes = (
+// 	date: TemporalDate,
+// 	min: number,
+// 	sec?: number,
+// 	ms?: number,
+// ): TemporalDate => date.with({
+// 	minute: min,
+// 	second: sec ?? date.second,
+// 	millisecond: ms ?? date.millisecond,
+// });
+
+// /**
+//  * Set hours
+//  */
+// export const setHours = (
+// 	date: TemporalDate,
+// 	hours: number,
+// 	min?: number,
+// 	sec?: number,
+// 	ms?: number,
+// ): TemporalDate => date.with({
+// 	hour: hours,
+// 	minute: min ?? date.minute,
+// 	second: sec ?? date.second,
+// 	millisecond: ms ?? date.millisecond,
+// });
+
+// /**
+//  * Set date
+//  */
+// export const setDate = (date: TemporalDate, day: number): TemporalDate => date.with({ day });
+
+// /**
+//  * Set month (0-based input to match DateWrapper behavior)
+//  */
+// export const setMonth = (
+// 	date: TemporalDate,
+// 	month: number,
+// 	day?: number,
+// ): TemporalDate => date.with({
+// 	month: month + 1, // Convert from 0-based to 1-based
+// 	day: day ?? date.day,
+// });
+
+// /**
+//  * Set full year
+//  */
+// export const setFullYear = (
+// 	date: TemporalDate,
+// 	year: number,
+// 	month?: number,
+// 	day?: number,
+// ): TemporalDate => date.with({
+// 	year,
+// 	month: month != null ? month + 1 : date.month, // Convert from 0-based to 1-based if provided
+// 	day: day ?? date.day,
+// });
+
+// /**
+//  * Convert to ISO string
+//  */
+// export const toISOString = (date: TemporalDate): string => toWire(
+// 	date,
+// 	true,
+// 	true,
+// );
+
+// /**
+//  * Check if date is in DST (always false since we work in UTC)
+//  */
+// export const isDST = (date: TemporalDate): boolean => false;
+
+// /**
+//  * Get inner Date object (for compatibility)
+//  */
+// // eslint-disable-next-line no-restricted-syntax
+// export const getInnerDate = (date: TemporalDate): Date => new Date(date.toZonedDateTime('UTC').epochMilliseconds);
+
+// /**
+//  * Check if string is a serialized date
+//  */
+// export const isSerializedDate = (str: string): boolean => str != null && str.length > 18 && str.length < 29 && str.indexOf('T') == 10;
+
+// /**
+//  * Deserialize string to Temporal date
+//  */
+// export const deserialize = (str: string): TemporalDate => fromWire(str);
+
+// /**
+//  * Create Temporal date from regular JS Date (alias for compatibility)
+//  */
+// export const fromNonUtcDate = (d: Date): TemporalDate => dateFromJSDate(d);

package/common/throttled-api-caller.ts

@@ -0,0 +1,149 @@
+/**
+ * Utility for deduplicating concurrent async calls and optionally caching results for a short TTL.
+ *
+ * - Deduplication: If multiple calls are made with the same arguments while one is in-flight,
+ *   they will all share the same Promise instead of creating multiple requests.
+ *
+ * - Caching: If a TTL (time-to-live) is specified, the last successful (or optionally failed) result
+ *   will be reused for repeated calls within the TTL window.
+ *
+ * Example usage:
+ *
+ * const apiCaller = new ThrottledApiCaller(fetchCart, { ttlMs: 5000 });
+ * const result = await apiCaller.call({ userId: "abc" });
+ */
+export class ThrottledApiCaller<TArgs, TResult> {
+    /**
+     * Stores in-flight Promises keyed by args hash.
+     * Ensures that simultaneous calls with the same args share the same Promise.
+     */
+    private inflight = new Map<string, Promise<TResult>>();
+
+    /**
+     * Stores cached results (or errors) along with expiration timestamps.
+     * Only used if ttlMs > 0.
+     */
+    private cache = new Map<
+        string,
+        { value?: TResult; error?: unknown; expiresAt: number }
+    >();
+
+    /** Function used to create a cache key from args. */
+    private readonly keyFn: (args: TArgs) => string;
+
+    /** Time-to-live (ms) for caching results. If 0, no result caching is applied. */
+    private readonly ttlMs: number;
+
+    /** Whether to cache failed results (errors). */
+    private readonly cacheErrors: boolean;
+
+    /**
+     * @param fn The async function you want to call in a deduped/cached manner.
+     * @param opts Options:
+     *   - keyFn: custom function to turn args into a cache key (default: stable JSON stringify).
+     *   - ttlMs: cache result duration in ms (default: 0, disabled).
+     *   - cacheErrors: if true, errors are cached within TTL window (default: false).
+     */
+    constructor(
+        private readonly fn: (args: TArgs) => Promise<TResult>,
+        opts: {
+            keyFn?: (args: TArgs) => string;
+            ttlMs?: number;
+            cacheErrors?: boolean;
+        } = {}
+    ) {
+        this.keyFn = opts.keyFn ?? stableKey;
+        this.ttlMs = Math.max(0, opts.ttlMs ?? 0);
+        this.cacheErrors = !!opts.cacheErrors;
+    }
+
+    /**
+     * Executes the wrapped function in a deduplicated and optionally cached manner.
+     * - If a cached result is still fresh, return it immediately.
+     * - If an in-flight request exists for the same args, return that Promise.
+     * - Otherwise, run the function, store its Promise in inflight, and cache its result.
+     */
+    async call(args: TArgs): Promise<TResult> {
+        const key = this.keyFn(args);
+        const now = Date.now();
+
+        // 1. Serve from cache if still valid
+        if (this.ttlMs > 0) {
+            const hit = this.cache.get(key);
+            if (hit && hit.expiresAt > now) {
+                if (hit.error !== undefined) throw hit.error;
+                return hit.value as TResult;
+            }
+        }
+
+        // 2. Share ongoing in-flight call if one exists
+        const existing = this.inflight.get(key);
+        if (existing) return existing;
+
+        // 3. Run new request
+        const promise = (async () => {
+            try {
+                const result = await this.fn(args);
+                // Cache the result if TTL is set
+                if (this.ttlMs > 0) {
+                    this.cache.set(key, {
+                        value: result,
+                        expiresAt: now + this.ttlMs,
+                    });
+                }
+                return result;
+            } catch (err) {
+                // Optionally cache the error too
+                if (this.ttlMs > 0 && this.cacheErrors) {
+                    this.cache.set(key, {
+                        error: err,
+                        expiresAt: now + this.ttlMs,
+                    });
+                }
+                throw err;
+            } finally {
+                // Always clear inflight entry when done
+                this.inflight.delete(key);
+            }
+        })();
+
+        this.inflight.set(key, promise);
+        return promise;
+    }
+
+    /**
+     * Invalidate cache for a specific args set.
+     * Next call with these args will trigger a fresh request.
+     */
+    invalidate(args: TArgs): void {
+        this.cache.delete(this.keyFn(args));
+    }
+
+    /**
+     * Clear all cache and in-flight requests.
+     */
+    clear(): void {
+        this.cache.clear();
+        this.inflight.clear();
+    }
+}
+
+/**
+ * Default stable key generator for args.
+ * Produces a deterministic string even if object keys are in different order.
+ */
+function stableKey(v: unknown): string {
+    const seen = new WeakSet();
+    const encode = (x: any): any => {
+        if (x && typeof x === "object") {
+            if (seen.has(x)) return "__cycle__";
+            seen.add(x);
+            if (Array.isArray(x)) return x.map(encode);
+            const out: Record<string, any> = {};
+            for (const k of Object.keys(x).sort()) out[k] = encode(x[k]);
+            return out;
+        }
+        return x;
+    };
+    return JSON.stringify(encode(v));
+}