@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/functions/date.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Date / Time Functions — Native RuntimeValue implementation.
+ *
+ * All Date objects returned by `excelToDate()` represent an Excel serial on
+ * the UTC timeline (midnight UTC for the corresponding date). Consequently
+ * every field accessor must be the UTC variant (`getUTCFullYear`,
+ * `getUTCMonth`, …) and every `Date` constructed from y/m/d components must
+ * be built with `Date.UTC(...)`. Using local-time accessors would make
+ * results depend on the host timezone — e.g. `YEAR(DATE(2024,1,1))` would
+ * return 2023 when evaluated on a machine west of UTC at midnight UTC.
+ *
+ * Exceptions (intentionally use local time):
+ * - `TODAY` / `NOW` — read the user's wall clock, which is genuinely in the
+ *   local timezone. The Excel serial is then constructed using
+ *   `Date.UTC(year, month, day)` so that the resulting serial round-trips
+ *   correctly through `excelToDate()`.
+ */
+import type { RuntimeValue } from "../runtime/values.js";
+type NativeFn = (args: RuntimeValue[]) => RuntimeValue;
+/**
+ * TODAY — today's date (at the user's local timezone).
+ *
+ * The user's concept of "today" is based on their wall clock, so we read
+ * local-time fields from `new Date()`. The resulting y/m/d components are
+ * then packed into a UTC serial so downstream date arithmetic is consistent.
+ */
+export declare const fnTODAY: NativeFn;
+/**
+ * NOW — current date and time.
+ *
+ * Excel stores the result as an untimezoned serial, but the user expects
+ * their local wall-clock reading. `dateToExcel(new Date())` effectively
+ * takes `Date.now()` in UTC-ms; any conversion to the user's timezone
+ * would require tz metadata we do not have. We therefore keep the current
+ * UTC-ms based conversion, matching historical behaviour.
+ */
+export declare const fnNOW: NativeFn;
+export declare const fnYEAR: NativeFn;
+export declare const fnMONTH: NativeFn;
+export declare const fnDAY: NativeFn;
+export declare const fnDATE: NativeFn;
+export declare const fnTIME: NativeFn;
+export declare const fnHOUR: NativeFn;
+export declare const fnMINUTE: NativeFn;
+export declare const fnSECOND: NativeFn;
+export declare const fnWEEKDAY: NativeFn;
+export declare const fnEOMONTH: NativeFn;
+export declare const fnEDATE: NativeFn;
+export declare const fnDATEDIF: NativeFn;
+export declare const fnDAYS: NativeFn;
+export declare const fnISOWEEKNUM: NativeFn;
+export declare const fnWEEKNUM: NativeFn;
+export declare const fnNETWORKDAYS: NativeFn;
+export declare const fnWORKDAY: NativeFn;
+export declare const fnYEARFRAC: NativeFn;
+export declare const fnDATEVALUE: NativeFn;
+export declare const fnTIMEVALUE: NativeFn;
+export declare const fnDAYS360: NativeFn;
+export declare const fnNETWORKDAYS_INTL: NativeFn;
+export declare const fnWORKDAY_INTL: NativeFn;
+export {};