@quereus/quereus 0.16.4 → 0.17.1

package/dist/src/func/builtins/datetime.js

@@ -1,461 +1,545 @@
-import { createLogger } from '../../common/logger.js'; // Import logger
+import { createLogger } from '../../common/logger.js';
 import { Temporal } from 'temporal-polyfill';
 import { StatusCode } from '../../common/types.js';
 import { createScalarFunction } from '../registration.js';
 import { quereusError } from '../../common/errors.js';
-const log = createLogger('func:builtins:datetime'); // Create logger instance
+const log = createLogger('func:builtins:datetime');
 const warnLog = log.extend('warn');
 const errorLog = log.extend('error');
 // --- Constants ---
 const MILLIS_PER_DAY = 86400000;
+const MILLIS_PER_SECOND = 1000;
 const JULIAN_DAY_UNIX_EPOCH = 2440587.5;
-const SQLITE_DEFAULT_DATE = { year: 2000, month: 1, day: 1 }; // Used for time-only inputs
-// --- Parsing Helper (using Temporal) --- //
+const SQLITE_DEFAULT_DATE = { year: 2000, month: 1, day: 1 };
+// Reasonable epoch-seconds range: approx 1900–3000 AD
+const MIN_EPOCH_SECONDS = -2208988800;
+const MAX_EPOCH_SECONDS = 32503680000;
+// Julian day heuristic bounds
+const MIN_JULIAN_DAY = 1000000;
+const MAX_JULIAN_DAY = 4000000;
+// --- Parsing Helpers --- //
+function instantFromEpochSeconds(seconds) {
+    return Temporal.Instant.fromEpochMilliseconds(seconds * MILLIS_PER_SECOND);
+}
+function instantToUtcZoned(instant) {
+    return instant.toZonedDateTimeISO('UTC');
+}
+function plainDateTimeToUtcZoned(pdt) {
+    return pdt.toZonedDateTime('UTC');
+}
+function isInRange(value, min, max) {
+    return value > min && value < max;
+}
+/**
+ * Parses a numeric value as a Julian day number, Unix epoch seconds, or Unix
+ * epoch milliseconds — using heuristics when `isUnixEpoch` is not set.
+ */
+function parseNumericToTemporal(timeVal, isUnixEpoch) {
+    if (isUnixEpoch)
+        return instantToUtcZoned(instantFromEpochSeconds(timeVal));
+    if (isInRange(timeVal, MIN_JULIAN_DAY, MAX_JULIAN_DAY)) {
+        const epochMillis = (timeVal - JULIAN_DAY_UNIX_EPOCH) * MILLIS_PER_DAY;
+        return instantToUtcZoned(Temporal.Instant.fromEpochMilliseconds(epochMillis));
+    }
+    // Prioritize seconds if within reasonable range
+    if (isInRange(timeVal, MIN_EPOCH_SECONDS, MAX_EPOCH_SECONDS)) {
+        try {
+            return instantToUtcZoned(instantFromEpochSeconds(timeVal));
+        }
+        catch { /* fall through to milliseconds */ }
+    }
+    // Fall back to milliseconds
+    if (isInRange(timeVal, MIN_EPOCH_SECONDS * MILLIS_PER_SECOND, MAX_EPOCH_SECONDS * MILLIS_PER_SECOND)) {
+        try {
+            return instantToUtcZoned(Temporal.Instant.fromEpochMilliseconds(timeVal));
+        }
+        catch { /* exhausted */ }
+    }
+    return null;
+}
+/**
+ * Attempts parsing the fractional-seconds portion of a manual time match,
+ * returning {millisecond, microsecond, nanosecond} components.
+ */
+function parseFractionalNanos(fracDigits) {
+    const ns = parseInt(fracDigits.padEnd(9, '0').substring(0, 9));
+    return {
+        millisecond: Math.floor(ns / 1_000_000),
+        microsecond: Math.floor((ns % 1_000_000) / 1_000),
+        nanosecond: ns % 1_000,
+    };
+}
+/** Try parsing with a Temporal type constructor, returning null on failure. */
+function tryParse(parseFn) {
+    try {
+        return parseFn();
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Parses various date/time string formats, Julian day numbers, or Unix timestamps
- * into a Temporal object. Tries to mimic SQLite's lenient parsing.
- * @param timeVal The input value (string, number, null).
- * @param isUnixEpoch Flag indicating if the input number should be treated as Unix epoch seconds.
- * @returns A Temporal.ZonedDateTime (usually UTC) or null if parsing fails.
+ * into a Temporal.ZonedDateTime. Mimics SQLite's lenient parsing.
  */
 function parseToTemporal(timeVal, isUnixEpoch = false) {
     if (timeVal === null || timeVal === undefined)
         return null;
     try {
-        if (typeof timeVal === 'number') {
-            if (isUnixEpoch) {
-                // Assume Unix timestamp in seconds, convert to Instant using milliseconds
-                const instant = Temporal.Instant.fromEpochMilliseconds(timeVal * 1000);
-                return instant.toZonedDateTimeISO('UTC');
-            }
-            else {
-                // Check if it looks like a Julian day number
-                if (timeVal > 1000000 && timeVal < 4000000) { // Heuristic for JD
-                    const epochMillis = (timeVal - JULIAN_DAY_UNIX_EPOCH) * MILLIS_PER_DAY;
-                    const instant = Temporal.Instant.fromEpochMilliseconds(epochMillis);
-                    return instant.toZonedDateTimeISO('UTC');
-                }
-                else {
-                    // Try interpreting as Unix timestamp (seconds or milliseconds) - prioritize seconds if reasonable
-                    try {
-                        // Reasonable range check for seconds (approx 1900-3000 AD)
-                        if (timeVal > -2208988800 && timeVal < 32503680000) {
-                            // Use fromEpochMilliseconds for seconds as fromEpochSeconds might not be in polyfill types
-                            const instant = Temporal.Instant.fromEpochMilliseconds(timeVal * 1000);
-                            return instant.toZonedDateTimeISO('UTC');
-                        }
-                    }
-                    catch { /* continue */ }
-                    // Try milliseconds if seconds failed or out of range
-                    try {
-                        // Reasonable range check for milliseconds (approx 1900-3000 AD)
-                        if (timeVal > -2208988800000 && timeVal < 32503680000000) {
-                            const instant = Temporal.Instant.fromEpochMilliseconds(timeVal);
-                            return instant.toZonedDateTimeISO('UTC');
-                        }
-                    }
-                    catch { /* continue */ }
-                    return null; // Unrecognized number format
-                }
-            }
-        }
+        if (typeof timeVal === 'number')
+            return parseNumericToTemporal(timeVal, isUnixEpoch);
         if (typeof timeVal !== 'string')
             return null;
-        const trimmedVal = timeVal.trim();
-        const lowerTrimmedVal = trimmedVal.toLowerCase();
-        if (lowerTrimmedVal === 'now') {
-            // 'now' typically means the current time in the local timezone in SQL contexts
+        const trimmed = timeVal.trim();
+        if (trimmed.toLowerCase() === 'now')
             return Temporal.Now.zonedDateTimeISO();
-        }
-        // Attempt direct parsing with Temporal.ZonedDateTime (ISO format with timezone)
-        try {
-            if (/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/.test(trimmedVal)) {
-                const instant = Temporal.Instant.from(trimmedVal.replace(' ', 'T') + 'Z');
-                return instant.toZonedDateTimeISO('UTC');
-            }
-            const zdt = Temporal.ZonedDateTime.from(trimmedVal);
-            return zdt;
-        }
-        catch { /* continue */ }
-        // Attempt direct parsing with Temporal.PlainDateTime (ISO format without timezone)
-        try {
-            const pdt = Temporal.PlainDateTime.from(trimmedVal.replace(' ', 'T'));
-            return pdt.toZonedDateTime('UTC');
-        }
-        catch { /* continue */ }
-        // Attempt direct parsing with Temporal.PlainDate (YYYY-MM-DD)
-        try {
-            const pd = Temporal.PlainDate.from(trimmedVal);
-            return pd.toZonedDateTime('UTC'); // Defaults to 00:00:00 UTC
-        }
-        catch { /* continue */ }
-        // Attempt direct parsing with Temporal.PlainTime (HH:MM:SS.SSS)
-        try {
-            const pt = Temporal.PlainTime.from(trimmedVal);
-            // If only time, assume default date (2000-01-01) and UTC
-            // Access individual properties instead of getISOFields
-            return Temporal.PlainDateTime.from({
-                ...SQLITE_DEFAULT_DATE,
-                hour: pt.hour,
-                minute: pt.minute,
-                second: pt.second,
-                millisecond: pt.millisecond,
-                microsecond: pt.microsecond,
-                nanosecond: pt.nanosecond,
-            }).toZonedDateTime('UTC');
-        }
-        catch { /* continue */ }
-        // --- Fallback Manual Parsing for SQLite Lenient Formats ---
-        // YYYYMMDD
-        let match = trimmedVal.match(/^(\d{4})(\d{2})(\d{2})$/);
-        if (match) {
-            const pdt = Temporal.PlainDateTime.from({ year: parseInt(match[1]), month: parseInt(match[2]), day: parseInt(match[3]) });
-            return pdt.toZonedDateTime('UTC');
-        }
-        // HH:MM
-        match = trimmedVal.match(/^(\d{2}):(\d{2})$/);
-        if (match) {
-            const ptArgs = { hour: parseInt(match[1]), minute: parseInt(match[2]) };
-            return Temporal.PlainDateTime.from({ ...SQLITE_DEFAULT_DATE, ...ptArgs }).toZonedDateTime('UTC');
-        }
-        // HH:MM:SS
-        match = trimmedVal.match(/^(\d{2}):(\d{2}):(\d{2})$/);
-        if (match) {
-            const ptArgs = { hour: parseInt(match[1]), minute: parseInt(match[2]), second: parseInt(match[3]) };
-            return Temporal.PlainDateTime.from({ ...SQLITE_DEFAULT_DATE, ...ptArgs }).toZonedDateTime('UTC');
-        }
-        // HH:MM:SS.SSS (handle varying ms digits)
-        match = trimmedVal.match(/^(\d{2}):(\d{2}):(\d{2})\.(\d{1,9})$/);
-        if (match) {
-            const ns = parseInt(match[4].padEnd(9, '0').substring(0, 9)); // Pad/truncate to nanoseconds
-            const ptArgs = {
-                hour: parseInt(match[1]),
-                minute: parseInt(match[2]),
-                second: parseInt(match[3]),
-                millisecond: Math.floor(ns / 1_000_000),
-                microsecond: Math.floor((ns % 1_000_000) / 1_000),
-                nanosecond: ns % 1_000,
-            };
-            return Temporal.PlainDateTime.from({ ...SQLITE_DEFAULT_DATE, ...ptArgs }).toZonedDateTime('UTC');
-        }
-        warnLog('Failed to parse date/time string with Temporal: %s', timeVal);
-        return null;
+        return parseISOString(trimmed)
+            ?? parseLenientFormats(trimmed);
     }
     catch (e) {
         warnLog('Error parsing date/time value "%s": %O', timeVal, e);
         return null;
     }
 }
-// --- Modifier Application (using Temporal) --- //
-// Regex to parse relative time modifiers like '+1 day', '-3 months'
+/** Matches ISO datetime with an explicit offset (Z or ±HH:MM). */
+const ISO_WITH_OFFSET = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+/** Matches ISO datetime without any timezone/offset suffix. */
+const ISO_WITHOUT_OFFSET = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
+/**
+ * Attempts standard ISO 8601 parsing strategies in priority order:
+ * offset datetime, plain datetime, plain date, plain time.
+ */
+function parseISOString(s) {
+    const normalised = s.replace(' ', 'T');
+    // ISO datetime with explicit offset (Z or ±HH:MM) → parse as Instant → UTC
+    if (ISO_WITH_OFFSET.test(s)) {
+        const instant = tryParse(() => Temporal.Instant.from(normalised));
+        if (instant)
+            return instantToUtcZoned(instant);
+    }
+    // ISO datetime without timezone → treat as UTC
+    if (ISO_WITHOUT_OFFSET.test(s)) {
+        const instant = tryParse(() => Temporal.Instant.from(normalised + 'Z'));
+        if (instant)
+            return instantToUtcZoned(instant);
+    }
+    // Full ZonedDateTime (includes bracket timezone notation)
+    const zdt = tryParse(() => Temporal.ZonedDateTime.from(s));
+    if (zdt)
+        return zdt;
+    // PlainDateTime
+    const pdt = tryParse(() => Temporal.PlainDateTime.from(normalised));
+    if (pdt)
+        return plainDateTimeToUtcZoned(pdt);
+    // PlainDate (YYYY-MM-DD)
+    const pd = tryParse(() => Temporal.PlainDate.from(s));
+    if (pd)
+        return pd.toZonedDateTime('UTC');
+    // PlainTime → anchored to default date
+    const pt = tryParse(() => Temporal.PlainTime.from(s));
+    if (pt)
+        return plainTimeToDefaultZoned(pt);
+    return null;
+}
+/** Anchors a PlainTime to the SQLite default date (2000-01-01) at UTC. */
+function plainTimeToDefaultZoned(pt) {
+    return plainDateTimeToUtcZoned(Temporal.PlainDateTime.from({
+        ...SQLITE_DEFAULT_DATE,
+        hour: pt.hour,
+        minute: pt.minute,
+        second: pt.second,
+        millisecond: pt.millisecond,
+        microsecond: pt.microsecond,
+        nanosecond: pt.nanosecond,
+    }));
+}
+/**
+ * Fallback manual parsing for SQLite lenient formats that Temporal doesn't
+ * handle directly: YYYYMMDD, HH:MM, HH:MM:SS, HH:MM:SS.fff
+ */
+function parseLenientFormats(s) {
+    // YYYYMMDD
+    let match = s.match(/^(\d{4})(\d{2})(\d{2})$/);
+    if (match) {
+        const pdt = Temporal.PlainDateTime.from({
+            year: parseInt(match[1]), month: parseInt(match[2]), day: parseInt(match[3]),
+        });
+        return plainDateTimeToUtcZoned(pdt);
+    }
+    // HH:MM
+    match = s.match(/^(\d{2}):(\d{2})$/);
+    if (match) {
+        return plainDateTimeToUtcZoned(Temporal.PlainDateTime.from({
+            ...SQLITE_DEFAULT_DATE,
+            hour: parseInt(match[1]), minute: parseInt(match[2]),
+        }));
+    }
+    // HH:MM:SS
+    match = s.match(/^(\d{2}):(\d{2}):(\d{2})$/);
+    if (match) {
+        return plainDateTimeToUtcZoned(Temporal.PlainDateTime.from({
+            ...SQLITE_DEFAULT_DATE,
+            hour: parseInt(match[1]), minute: parseInt(match[2]), second: parseInt(match[3]),
+        }));
+    }
+    // HH:MM:SS.fff (variable precision)
+    match = s.match(/^(\d{2}):(\d{2}):(\d{2})\.(\d{1,9})$/);
+    if (match) {
+        return plainDateTimeToUtcZoned(Temporal.PlainDateTime.from({
+            ...SQLITE_DEFAULT_DATE,
+            hour: parseInt(match[1]), minute: parseInt(match[2]), second: parseInt(match[3]),
+            ...parseFractionalNanos(match[4]),
+        }));
+    }
+    warnLog('Failed to parse date/time string: %s', s);
+    return null;
+}
+// --- Strict Parsing (for epoch_* functions) --- //
+/**
+ * ISO 8601 date/time pattern for strict parsing.
+ * Accepts: YYYY-MM-DD, YYYY-MM-DDTHH:MM[:SS[.fff]][Z|±HH:MM], and 'now'.
+ * Rejects bare numbers, lenient formats like YYYYMMDD, and time-only strings.
+ */
+const STRICT_ISO_PATTERN = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+function parseStrictTimestring(timeVal) {
+    if (timeVal === null || timeVal === undefined)
+        return null;
+    if (typeof timeVal !== 'string')
+        return null;
+    const trimmed = timeVal.trim();
+    if (trimmed.toLowerCase() === 'now')
+        return Temporal.Now.zonedDateTimeISO();
+    if (!STRICT_ISO_PATTERN.test(trimmed))
+        return null;
+    return parseISOString(trimmed);
+}
+// --- Modifier Application --- //
 const RELATIVE_MODIFIER_REGEX = /^\s*([+-]?\s*\d+(\.\d+)?)\s+(day|hour|minute|second|month|year)s?\s*$/i;
-// Regex for 'weekday N'
-const WEEKDAY_MODIFIER_REGEX = /^\s*weekday\s+([0-6])\s*$/i; // 0=Sun, 1=Mon..6=Sat
+const WEEKDAY_MODIFIER_REGEX = /^\s*weekday\s+([0-6])\s*$/i;
+function applyRelativeShift(dt, value, unit) {
+    const durationLike = {};
+    if (unit === 'year' || unit === 'month' || unit === 'day') {
+        durationLike[`${unit}s`] = Math.trunc(value);
+    }
+    else if (unit === 'second') {
+        durationLike.seconds = Math.trunc(value);
+        const nanoseconds = Math.round((value % 1) * 1e9);
+        if (nanoseconds !== 0)
+            durationLike.nanoseconds = nanoseconds;
+    }
+    else {
+        durationLike[`${unit}s`] = value;
+    }
+    return dt.add(Temporal.Duration.from(durationLike));
+}
+function applyWeekdayAdjustment(dt, targetSqlWeekday) {
+    const targetISO = targetSqlWeekday === 0 ? 7 : targetSqlWeekday;
+    const daysToAdd = targetISO - dt.dayOfWeek;
+    if (daysToAdd > 0)
+        return dt.add({ days: daysToAdd - 7 });
+    if (daysToAdd < 0)
+        return dt.add({ days: daysToAdd });
+    return dt;
+}
 function applyTemporalModifier(dt, modifier) {
-    const trimmedModifier = modifier.trim().toLowerCase();
-    // Group 1: Relative Time Shifts
-    const relativeMatch = trimmedModifier.match(RELATIVE_MODIFIER_REGEX);
+    const trimmed = modifier.trim().toLowerCase();
+    const relativeMatch = trimmed.match(RELATIVE_MODIFIER_REGEX);
     if (relativeMatch) {
-        const valueStr = relativeMatch[1].replace(/\s/g, '');
-        const value = parseFloat(valueStr);
-        const unit = relativeMatch[3]; // unit is guaranteed to be a string here
-        if (isNaN(value)) {
+        const value = parseFloat(relativeMatch[1].replace(/\s/g, ''));
+        if (isNaN(value))
             quereusError(`Invalid number in modifier: ${modifier}`, StatusCode.MISUSE);
-        }
-        // Use Record<string, number> for better type checking with dynamic keys
-        const durationLike = {};
-        if (unit === 'year' || unit === 'month' || unit === 'day') {
-            durationLike[`${unit}s`] = Math.trunc(value);
-        }
-        else if (unit === 'hour' || unit === 'minute' || unit === 'second') {
-            if (unit === 'second') {
-                const seconds = Math.trunc(value);
-                const nanoseconds = Math.round((value % 1) * 1e9);
-                durationLike.seconds = seconds;
-                if (nanoseconds !== 0)
-                    durationLike.nanoseconds = nanoseconds;
-            }
-            else {
-                durationLike[`${unit}s`] = value;
-            }
-        }
-        else {
-            quereusError(`Internal error: Unknown unit ${unit}`, StatusCode.MISUSE);
-        }
-        const duration = Temporal.Duration.from(durationLike);
-        return dt.add(duration);
+        return applyRelativeShift(dt, value, relativeMatch[3]);
     }
-    // Group 2: Start/End of Unit
-    switch (trimmedModifier) {
-        case 'start of day':
-            return dt.startOfDay();
-        case 'start of month':
-            return dt.startOfDay().with({ day: 1 });
-        case 'start of year':
-            return dt.startOfDay().with({ month: 1, day: 1 });
+    switch (trimmed) {
+        case 'start of day': return dt.startOfDay();
+        case 'start of month': return dt.startOfDay().with({ day: 1 });
+        case 'start of year': return dt.startOfDay().with({ month: 1, day: 1 });
     }
-    // Group 3: Weekday Adjustment
-    const weekdayMatch = trimmedModifier.match(WEEKDAY_MODIFIER_REGEX);
-    if (weekdayMatch) {
-        const targetWeekday = parseInt(weekdayMatch[1], 10);
-        const targetWeekdayISO = targetWeekday === 0 ? 7 : targetWeekday;
-        const currentWeekdayISO = dt.dayOfWeek;
-        let daysToAdd = targetWeekdayISO - currentWeekdayISO;
-        if (daysToAdd > 0) {
-            daysToAdd -= 7;
-        }
-        if (daysToAdd !== 0) {
-            return dt.add({ days: daysToAdd });
-        }
-        return dt;
-    }
-    // Group 4: Timezone (Handled before modifier application)
+    const weekdayMatch = trimmed.match(WEEKDAY_MODIFIER_REGEX);
+    if (weekdayMatch)
+        return applyWeekdayAdjustment(dt, parseInt(weekdayMatch[1], 10));
     warnLog('Modifier not implemented or unrecognized: %s', modifier);
     return dt;
 }
-// --- Core Logic --- //
+const _CONTROL_MODIFIERS = new Set(['unixepoch', 'localtime', 'utc', 'subsec']);
+/**
+ * Core argument processor shared by all datetime functions.
+ * Separates control modifiers (unixepoch, localtime, utc, subsec) from
+ * arithmetic modifiers, parses the timestring, applies timezone conversion,
+ * then applies arithmetic modifiers in order.
+ */
 function processDateTimeArgs(args) {
+    if (args.length === 0)
+        return { dt: null, subsec: false };
+    const { timeVal, isUnixEpoch, subsec, targetTimeZoneId, arithmeticModifiers } = classifyArgs(args);
+    let dt = parseToTemporal(timeVal, isUnixEpoch);
+    if (!dt)
+        return { dt: null, subsec };
+    dt = convertTimezone(dt, targetTimeZoneId);
+    if (!dt)
+        return { dt: null, subsec };
+    dt = applyModifiers(dt, arithmeticModifiers);
+    return { dt, subsec };
+}
+/**
+ * Strict variant for epoch_* functions: only accepts ISO 8601 strings and 'now'.
+ * Rejects bare numbers (ambiguous), time-only strings, and YYYYMMDD format.
+ */
+function processStrictArgs(args) {
     if (args.length === 0)
         return null;
-    let initialTimeVal = args[0];
-    let startIndex = 1;
-    let isUnixEpoch = false;
-    let modifiers = [];
-    const unixEpochIndex = args.findIndex(arg => typeof arg === 'string' && arg.trim().toLowerCase() === 'unixepoch');
-    if (unixEpochIndex !== -1) {
-        if (unixEpochIndex === 0) {
-            if (args.length < 2)
-                return null;
-            initialTimeVal = args[1];
-            isUnixEpoch = true;
-            startIndex = 2;
-            modifiers = args.slice(startIndex);
-        }
-        else {
-            initialTimeVal = args[0];
-            isUnixEpoch = true;
-            if (typeof initialTimeVal !== 'number')
-                return null;
-            modifiers = args.slice(1).filter((_, i) => i !== (unixEpochIndex - 1));
-            startIndex = 1;
-        }
+    const timeVal = args[0];
+    const modifiers = args.slice(1).filter((m) => typeof m === 'string');
+    let targetTimeZoneId = 'UTC';
+    const arithmeticModifiers = [];
+    for (const mod of modifiers) {
+        const lower = mod.trim().toLowerCase();
+        if (lower === 'localtime')
+            targetTimeZoneId = Temporal.Now.timeZoneId();
+        else if (lower === 'utc')
+            targetTimeZoneId = 'UTC';
+        else
+            arithmeticModifiers.push(mod);
+    }
+    let dt = parseStrictTimestring(timeVal);
+    if (!dt)
+        return null;
+    dt = convertTimezone(dt, targetTimeZoneId);
+    if (!dt)
+        return null;
+    return applyModifiers(dt, arithmeticModifiers);
+}
+function classifyArgs(args) {
+    const hasUnixEpoch = args.some(a => typeof a === 'string' && a.trim().toLowerCase() === 'unixepoch');
+    let timeVal;
+    let rawModifiers;
+    if (hasUnixEpoch && typeof args[0] === 'string' && args[0].trim().toLowerCase() === 'unixepoch') {
+        timeVal = args.length > 1 ? args[1] : null;
+        rawModifiers = args.slice(2);
     }
     else {
-        initialTimeVal = args[0];
-        modifiers = args.slice(1);
-        startIndex = 1;
+        timeVal = args[0];
+        rawModifiers = args.slice(1);
     }
-    // Determine target timezone from modifiers ('localtime' or 'utc')
-    let targetTimeZoneId = 'UTC'; // Store ID as string, default to UTC
-    const remainingModifiers = [];
-    for (const mod of modifiers) {
+    let targetTimeZoneId = 'UTC';
+    let subsec = false;
+    const arithmeticModifiers = [];
+    for (const mod of rawModifiers) {
         if (typeof mod !== 'string')
             continue;
-        const lowerMod = mod.trim().toLowerCase();
-        if (lowerMod === 'localtime') {
+        const lower = mod.trim().toLowerCase();
+        if (lower === 'unixepoch')
+            continue;
+        if (lower === 'localtime') {
             targetTimeZoneId = Temporal.Now.timeZoneId();
+            continue;
         }
-        else if (lowerMod === 'utc') {
-            targetTimeZoneId = 'UTC'; // Use string literal
+        if (lower === 'utc') {
+            targetTimeZoneId = 'UTC';
+            continue;
         }
-        else {
-            remainingModifiers.push(mod);
+        if (lower === 'subsec') {
+            subsec = true;
+            continue;
         }
+        arithmeticModifiers.push(mod);
+    }
+    const isUnixEpoch = hasUnixEpoch && typeof timeVal === 'number';
+    return { timeVal, isUnixEpoch, subsec, targetTimeZoneId, arithmeticModifiers };
+}
+function convertTimezone(dt, targetTimeZoneId) {
+    if (targetTimeZoneId === dt.timeZoneId)
+        return dt;
+    try {
+        return dt.toInstant().toZonedDateTimeISO(targetTimeZoneId);
     }
-    // Parse the initial value
-    let currentDt = parseToTemporal(initialTimeVal, isUnixEpoch);
-    if (!currentDt)
+    catch (e) {
+        warnLog('Failed to convert to timezone "%s": %O', targetTimeZoneId, e);
         return null;
-    // Adjust initial ZonedDateTime to the target timezone if necessary
-    if (targetTimeZoneId !== currentDt.timeZoneId) {
-        try {
-            currentDt = currentDt.toInstant().toZonedDateTimeISO(targetTimeZoneId);
-        }
-        catch (e) {
-            warnLog('Failed to convert to timezone "%s": %O', targetTimeZoneId, e);
-            return null;
-        }
     }
-    // Apply remaining modifiers
-    for (const modifier of remainingModifiers) {
-        if (typeof modifier !== 'string')
-            continue;
+}
+function applyModifiers(dt, modifiers) {
+    let current = dt;
+    for (const modifier of modifiers) {
         try {
-            currentDt = applyTemporalModifier(currentDt, modifier);
+            current = applyTemporalModifier(current, modifier);
         }
         catch (e) {
             warnLog('Error applying modifier "%s": %O', modifier, e);
             return null;
         }
     }
-    return currentDt;
+    return current;
+}
+// --- Epoch Conversion Helpers --- //
+function toEpochSeconds(dt) {
+    return Math.floor(dt.epochMilliseconds / MILLIS_PER_SECOND);
+}
+function toEpochMilliseconds(dt) {
+    return dt.epochMilliseconds;
+}
+function toEpochSecondsFractional(dt) {
+    return dt.epochMilliseconds / MILLIS_PER_SECOND;
+}
+function toJulianDay(dt) {
+    return (dt.toInstant().epochMilliseconds / MILLIS_PER_DAY) + JULIAN_DAY_UNIX_EPOCH;
+}
+// --- Formatting Helpers --- //
+function formatDate(dt) {
+    return dt.toPlainDate().toString();
+}
+function formatTime(dt, subsec) {
+    if (subsec)
+        return dt.toPlainTime().toString({ smallestUnit: 'millisecond' });
+    return dt.toPlainTime().toString({ smallestUnit: 'second' });
+}
+function formatDateTime(dt, subsec) {
+    return `${formatDate(dt)} ${formatTime(dt, subsec)}`;
 }
 // --- Function Implementations --- //
-// date(timestring, modifier, ...)
-// NOTE: Marked as non-deterministic because it accepts 'now' as a timestring
+// All date/time functions are non-deterministic because they accept 'now'.
 export const dateFunc = createScalarFunction({ name: 'date', numArgs: -1, deterministic: false }, (...args) => {
-    const finalDt = processDateTimeArgs(args);
-    if (!finalDt)
-        return null;
-    return finalDt.toPlainDate().toString();
+    const { dt } = processDateTimeArgs(args);
+    return dt ? formatDate(dt) : null;
 });
-// time(timestring, modifier, ...)
-// NOTE: Marked as non-deterministic because it accepts 'now' as a timestring
 export const timeFunc = createScalarFunction({ name: 'time', numArgs: -1, deterministic: false }, (...args) => {
-    const finalDt = processDateTimeArgs(args);
-    if (!finalDt)
-        return null;
-    return finalDt.toPlainTime().toString({ smallestUnit: 'second' });
+    const { dt, subsec } = processDateTimeArgs(args);
+    return dt ? formatTime(dt, subsec) : null;
 });
-// datetime(timestring, modifier, ...)
-// NOTE: Marked as non-deterministic because it accepts 'now' as a timestring
 export const datetimeFunc = createScalarFunction({ name: 'datetime', numArgs: -1, deterministic: false }, (...args) => {
-    const finalDt = processDateTimeArgs(args);
-    if (!finalDt)
-        return null;
-    const datePart = finalDt.toPlainDate().toString();
-    const timePart = finalDt.toPlainTime().toString({ smallestUnit: 'second' });
-    return `${datePart} ${timePart}`;
+    const { dt, subsec } = processDateTimeArgs(args);
+    return dt ? formatDateTime(dt, subsec) : null;
 });
-// julianday(timestring, modifier, ...)
-// NOTE: Marked as non-deterministic because it accepts 'now' as a timestring
 export const juliandayFunc = createScalarFunction({ name: 'julianday', numArgs: -1, deterministic: false }, (...args) => {
-    const finalDt = processDateTimeArgs(args);
-    if (!finalDt)
-        return null;
-    const epochMillis = finalDt.toInstant().epochMilliseconds;
-    return (epochMillis / MILLIS_PER_DAY) + JULIAN_DAY_UNIX_EPOCH;
+    const { dt } = processDateTimeArgs(args);
+    return dt ? toJulianDay(dt) : null;
+});
+// --- Epoch Functions --- //
+/**
+ * epoch_s(timestring, modifier, ...)
+ * Returns INTEGER Unix epoch seconds. Accepts only ISO 8601 strings and 'now';
+ * rejects bare numbers to avoid ambiguity. All epoch outputs are UTC-based:
+ * the 'localtime' modifier affects how the timestring is interpreted and
+ * modifiers applied, but the returned value is always seconds since
+ * 1970-01-01 00:00:00 UTC.
+ */
+export const epochSFunc = createScalarFunction({ name: 'epoch_s', numArgs: -1, deterministic: false }, (...args) => {
+    const dt = processStrictArgs(args);
+    return dt ? toEpochSeconds(dt) : null;
 });
-// strftime(format, timestring, modifier, ...)
-// NOTE: Marked as non-deterministic because it accepts 'now' as a timestring
+/**
+ * epoch_ms(timestring, modifier, ...)
+ * Returns INTEGER Unix epoch milliseconds. Same strict parsing as epoch_s.
+ * Epoch values are always relative to UTC regardless of timezone modifiers.
+ */
+export const epochMsFunc = createScalarFunction({ name: 'epoch_ms', numArgs: -1, deterministic: false }, (...args) => {
+    const dt = processStrictArgs(args);
+    return dt ? toEpochMilliseconds(dt) : null;
+});
+/**
+ * epoch_s_frac(timestring, modifier, ...)
+ * Returns REAL Unix epoch seconds with fractional (millisecond) precision.
+ * Same strict parsing as epoch_s. Use epoch_s() when integer precision suffices.
+ */
+export const epochSFracFunc = createScalarFunction({ name: 'epoch_s_frac', numArgs: -1, deterministic: false }, (...args) => {
+    const dt = processStrictArgs(args);
+    return dt ? toEpochSecondsFractional(dt) : null;
+});
+// --- strftime --- //
+const ABBREVIATED_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+function pad2(n) { return n.toString().padStart(2, '0'); }
+function pad3(n) { return n.toString().padStart(3, '0'); }
+function pad4(n) { return n.toString().padStart(4, '0'); }
+function space2(n) { return n.toString().padStart(2, ' '); }
+function hour12(h) { return h % 12 || 12; }
+function formatStrftimeSpecifier(spec, dt) {
+    switch (spec) {
+        // Date
+        case '%Y': return pad4(dt.year);
+        case '%m': return pad2(dt.month);
+        case '%d': return pad2(dt.day);
+        case '%j': return pad3(dt.dayOfYear);
+        case '%F': return `${pad4(dt.year)}-${pad2(dt.month)}-${pad2(dt.day)}`;
+        case '%D': return `${pad2(dt.month)}/${pad2(dt.day)}/${dt.year.toString().slice(-2)}`;
+        case '%C': return pad2(Math.floor(dt.year / 100));
+        case '%y': return dt.year.toString().slice(-2);
+        case '%h': return ABBREVIATED_MONTHS[dt.month - 1];
+        case '%e': return space2(dt.day);
+        // Time
+        case '%H': return pad2(dt.hour);
+        case '%M': return pad2(dt.minute);
+        case '%S': return pad2(dt.second);
+        case '%f': return `.${pad3(dt.millisecond)}`;
+        case '%s': return toEpochSeconds(dt).toString();
+        case '%I': return pad2(hour12(dt.hour));
+        case '%k': return space2(dt.hour);
+        case '%l': return space2(hour12(dt.hour));
+        case '%p': return dt.hour < 12 ? 'AM' : 'PM';
+        case '%P': return dt.hour < 12 ? 'am' : 'pm';
+        case '%T': return `${pad2(dt.hour)}:${pad2(dt.minute)}:${pad2(dt.second)}`;
+        case '%R': return `${pad2(dt.hour)}:${pad2(dt.minute)}`;
+        case '%r': return `${pad2(hour12(dt.hour))}:${pad2(dt.minute)}:${pad2(dt.second)} ${dt.hour < 12 ? 'AM' : 'PM'}`;
+        // Weekday / Week Number
+        case '%w': return (dt.dayOfWeek % 7).toString();
+        case '%u': return dt.dayOfWeek.toString();
+        case '%W':
+            warnLog('strftime %%W not fully implemented');
+            return pad2(dt.weekOfYear ?? 0);
+        case '%V': return pad2(dt.weekOfYear ?? 0);
+        case '%g': return (dt.yearOfWeek ?? dt.year).toString().slice(-2);
+        case '%G': return pad4(dt.yearOfWeek ?? dt.year);
+        // Julian Day
+        case '%J': return toJulianDay(dt).toString();
+        // Epoch (new specifiers)
+        case '%E': return toEpochSeconds(dt).toString();
+        case '%Q': return toEpochMilliseconds(dt).toString();
+        // Timezone
+        case '%z': {
+            const sign = dt.offset.startsWith('-') ? '-' : '+';
+            const parts = dt.offset.substring(1).split(':');
+            return `${sign}${parts[0].padStart(2, '0')}${parts[1]?.padStart(2, '0') ?? '00'}`;
+        }
+        // Literal Percent
+        case '%%': return '%';
+        default:
+            warnLog(`Unsupported strftime specifier: ${spec}`);
+            return spec;
+    }
+}
 export const strftimeFunc = createScalarFunction({ name: 'strftime', numArgs: -1, deterministic: false }, (format, ...timeArgs) => {
     if (typeof format !== 'string')
         return null;
-    const finalDt = processDateTimeArgs(timeArgs);
-    if (!finalDt)
+    const { dt } = processDateTimeArgs(timeArgs);
+    if (!dt)
         return null;
-    // Abbreviated month names (SQLite standard)
-    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
     try {
-        let result = format;
-        // Use replace with a callback function for better handling
-        result = result.replace(/%./g, (match) => {
-            switch (match) {
-                // Date
-                case '%Y': return finalDt.year.toString().padStart(4, '0');
-                case '%m': return finalDt.month.toString().padStart(2, '0');
-                case '%d': return finalDt.day.toString().padStart(2, '0');
-                case '%j': return finalDt.dayOfYear.toString().padStart(3, '0');
-                case '%F': return `${finalDt.year.toString().padStart(4, '0')}-${finalDt.month.toString().padStart(2, '0')}-${finalDt.day.toString().padStart(2, '0')}`;
-                case '%D': return `${finalDt.month.toString().padStart(2, '0')}/${finalDt.day.toString().padStart(2, '0')}/${finalDt.year.toString().slice(-2)}`;
-                case '%C': return Math.floor(finalDt.year / 100).toString().padStart(2, '0');
-                case '%y': return finalDt.year.toString().slice(-2);
-                case '%h': return months[finalDt.month - 1];
-                case '%e': return finalDt.day.toString().padStart(2, ' ');
-                // Time
-                case '%H': return finalDt.hour.toString().padStart(2, '0');
-                case '%M': return finalDt.minute.toString().padStart(2, '0');
-                case '%S': return finalDt.second.toString().padStart(2, '0');
-                case '%f': { // SQLite %f is .SSS
-                    const msStr = finalDt.millisecond.toString().padStart(3, '0');
-                    return `.${msStr}`;
-                }
-                case '%s': return Math.floor(finalDt.epochMilliseconds / 1000).toString();
-                case '%I': return (finalDt.hour % 12 || 12).toString().padStart(2, '0'); // 12-hour clock
-                case '%k': return finalDt.hour.toString().padStart(2, ' '); // 24-hour, space padded
-                case '%l': return (finalDt.hour % 12 || 12).toString().padStart(2, ' '); // 12-hour, space padded
-                case '%p': return finalDt.hour < 12 ? 'AM' : 'PM';
-                case '%P': return finalDt.hour < 12 ? 'am' : 'pm';
-                case '%T': return `${finalDt.hour.toString().padStart(2, '0')}:${finalDt.minute.toString().padStart(2, '0')}:${finalDt.second.toString().padStart(2, '0')}`;
-                case '%R': return `${finalDt.hour.toString().padStart(2, '0')}:${finalDt.minute.toString().padStart(2, '0')}`;
-                case '%r': { // 12-hour time hh:mm:ss AM/PM
-                    const hour12 = (finalDt.hour % 12 || 12).toString().padStart(2, '0');
-                    const min = finalDt.minute.toString().padStart(2, '0');
-                    const sec = finalDt.second.toString().padStart(2, '0');
-                    const ampm = finalDt.hour < 12 ? 'AM' : 'PM';
-                    return `${hour12}:${min}:${sec} ${ampm}`;
-                }
-                // Weekday / Week Number
-                case '%w': return (finalDt.dayOfWeek % 7).toString(); // 0=Sunday..6=Saturday (SQLite)
-                case '%u': return finalDt.dayOfWeek.toString(); // 1=Monday..7=Sunday (ISO)
-                // Handle potentially undefined weekOfYear (though Temporal usually provides it)
-                case '%W': // Week number (Sunday start, 00-53) - SQLite specific implementation
-                    warnLog('strftime %W not fully implemented');
-                    return (finalDt.weekOfYear ?? 0).toString().padStart(2, '0'); // Fallback to ISO week
-                case '%V': return (finalDt.weekOfYear ?? 0).toString().padStart(2, '0'); // ISO 8601 week number
-                case '%g': // ISO 8601 week-based year, last two digits
-                    return (finalDt.yearOfWeek ?? finalDt.year).toString().slice(-2);
-                case '%G': // ISO 8601 week-based year, four digits
-                    return (finalDt.yearOfWeek ?? finalDt.year).toString().padStart(4, '0');
-                // Julian Day
-                case '%J': {
-                    const epochMillis = finalDt.toInstant().epochMilliseconds;
-                    const jd = (epochMillis / MILLIS_PER_DAY) + JULIAN_DAY_UNIX_EPOCH;
-                    return jd.toString();
-                }
-                // Timezone
-                case '%z': { // +hhmm or -hhmm
-                    const offsetStr = finalDt.offset;
-                    const sign = offsetStr.startsWith('-') ? '-' : '+';
-                    const parts = offsetStr.substring(1).split(':');
-                    return `${sign}${parts[0].padStart(2, '0')}${parts[1]?.padStart(2, '0') ?? '00'}`;
-                }
-                case '%:z': // +hh:mm or -hh:mm
-                    return finalDt.offset;
-                // case '%Z': // Timezone name - Complex, depends on available data. Skip for now.
-                // Literal Percent
-                case '%%': return '%';
-                // Week numbering formats are complex to implement correctly
-                // Using ISO week numbers as fallback where appropriate
-                default:
-                    warnLog(`Unsupported strftime specifier: ${match}`);
-                    return match; // Return the specifier itself if unsupported
-            }
-        });
-        return result;
+        return format.replace(/%./g, (spec) => formatStrftimeSpecifier(spec, dt));
     }
     catch (e) {
-        errorLog("Error during strftime formatting: %O", e);
+        errorLog('Error during strftime formatting: %O', e);
         return null;
     }
 });
-// IsISODate(text)
+// --- ISO Validation Functions --- //
 export const isISODateFunc = createScalarFunction({ name: 'IsISODate', numArgs: 1, deterministic: true }, (value) => {
     if (typeof value !== 'string')
         return false;
     const s = value.trim();
     if (!/^\d{4}-\d{2}-\d{2}$/.test(s))
         return false;
-    try {
-        const d = Temporal.PlainDate.from(s);
-        return d.toString() === s;
-    }
-    catch {
-        return false;
-    }
+    const d = tryParse(() => Temporal.PlainDate.from(s));
+    return d !== null && d.toString() === s;
 });
-// IsISODateTime(text)
 export const isISODateTimeFunc = createScalarFunction({ name: 'IsISODateTime', numArgs: 1, deterministic: true }, (value) => {
     if (typeof value !== 'string')
         return false;
     const s = value.trim();
-    // YYYY-MM-DDTHH:MM[:SS[.fraction]] [timezone]
     const re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})?$/;
     if (!re.test(s))
         return false;
     const hasZone = /(?:Z|[+-]\d{2}:\d{2})$/.test(s);
-    try {
-        if (hasZone) {
-            // Zoned ISO string
-            void Temporal.Instant.from(s);
-            return true;
-        }
-        // Plain ISO local date-time
-        void Temporal.PlainDateTime.from(s);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    if (hasZone)
+        return tryParse(() => Temporal.Instant.from(s)) !== null;
+    return tryParse(() => Temporal.PlainDateTime.from(s)) !== null;
 });
 //# sourceMappingURL=datetime.js.map