@vuu-ui/vuu-utils 3.4.1 → 3.5.0-beta.1

package/src/date/time-zone.js

@@ -0,0 +1,56 @@
+import { CalendarDate, CalendarDateTime, fromAbsolute, getLocalTimeZone, toCalendarDate, toZoned } from "@internationalized/date";
+let defaultTimeZone = "local";
+const setDefaultTimeZone = (timeZone)=>{
+    defaultTimeZone = timeZone;
+};
+const getDefaultTimeZone = ()=>defaultTimeZone;
+const resolveTimeZone = (timeZone = defaultTimeZone)=>"local" === timeZone ? getLocalTimeZone() : timeZone;
+const getDateTimeFields = (epochMillis, timeZone)=>{
+    const { year, month, day, hour, minute, second, millisecond } = fromAbsolute(epochMillis, resolveTimeZone(timeZone));
+    return {
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        millisecond
+    };
+};
+const fromDateTimeFields = ({ year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0 }, timeZone)=>toZoned(new CalendarDateTime(year, month, day, hour, minute, second, millisecond), resolveTimeZone(timeZone), "compatible").toDate().getTime();
+const calendarDateOf = (epochMillis, timeZone)=>toCalendarDate(fromAbsolute(epochMillis, resolveTimeZone(timeZone)));
+const startOfCalendarDay = (date, timeZone)=>toZoned(date, resolveTimeZone(timeZone)).toDate().getTime();
+const startOfDay = (epochMillis, timeZone)=>startOfCalendarDay(calendarDateOf(epochMillis, timeZone), timeZone);
+const startOfNextDay = (epochMillis, timeZone)=>startOfCalendarDay(calendarDateOf(epochMillis, timeZone).add({
+        days: 1
+    }), timeZone);
+const isStartOfDay = (epochMillis, timeZone)=>startOfDay(epochMillis, timeZone) === epochMillis;
+const isoDatePattern = /^(\d{4})-(\d{2})-(\d{2})$/;
+const resolveRelativeDate = (date = "today", timeZone)=>{
+    if (date instanceof Date) return calendarDateOf(date.getTime(), timeZone);
+    {
+        if ("today" === date) return calendarDateOf(Date.now(), timeZone);
+        if ("yesterday" === date) return calendarDateOf(Date.now(), timeZone).subtract({
+            days: 1
+        });
+        const match = isoDatePattern.exec(date);
+        if (match) return new CalendarDate(parseInt(match[1]), parseInt(match[2]), parseInt(match[3]));
+        throw Error(`[time-zone] invalid date ${date}`);
+    }
+};
+const timeOfDayToEpochMillis = (timeString, date = "today", timeZone)=>{
+    const { year, month, day } = resolveRelativeDate(date, timeZone);
+    const [hms, fraction = ""] = timeString.split(".");
+    const [hour, minute, second] = hms.split(":").map((v)=>parseInt(v, 10));
+    const millisecond = parseInt(fraction.padEnd(3, "0").slice(0, 3), 10);
+    return fromDateTimeFields({
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        millisecond
+    }, timeZone);
+};
+export { fromDateTimeFields, getDateTimeFields, getDefaultTimeZone, isStartOfDay, resolveRelativeDate, resolveTimeZone, setDefaultTimeZone, startOfDay, startOfNextDay, timeOfDayToEpochMillis };

package/src/filters/filter-utils.js

@@ -1,4 +1,6 @@
 import { ScaledDecimal } from "../ScaledDecimal.js";
+import { isTimeDataValueWithMilliseconds } from "../column-utils.js";
+import { getTemporalInfo } from "../date/temporal.js";
 const singleValueFilterOps = new Set([
     "=",
     "!=",
@@ -64,6 +66,13 @@ const collectFiltersForColumn = (filter, columnName)=>{
     };
 };
 const stringifyBoolean = (value)=>"boolean" == typeof value ? "${filter.value}" : value;
+const getDefaultTimeRange = (column)=>isTimeDataValueWithMilliseconds(column) ? [
+        "00:00:00.000",
+        "23:59:59.999"
+    ] : [
+        "00:00:00",
+        "23:59:59"
+    ];
 const getColumnValueFromFilter = (column, operator, filter)=>{
     if (isSingleValueFilter(filter)) {
         if (filter.column === column.name) {
@@ -72,7 +81,7 @@ const getColumnValueFromFilter = (column, operator, filter)=>{
                 `${filter.value}`,
                 ""
             ];
-            else if ("<" === filter.op) return [
+            else if ("<" === filter.op || "<=" === filter.op) return [
                 "",
                 `${filter.value}`
             ];
@@ -97,10 +106,7 @@ const getColumnValueFromFilter = (column, operator, filter)=>{
         }
     }
     if (!operator.startsWith("between")) return "";
-    if ("time" === column.type) return [
-        "00:00:00",
-        "23:59:59"
-    ];
+    if (getTemporalInfo(column)?.kind === "time") return getDefaultTimeRange(column);
     return [
         "",
         ""
@@ -133,4 +139,4 @@ const filtersAreEqual = (f1, f2)=>{
     }
     return false;
 };
-export { applyFilterToColumns, extractFilterForColumn, filtersAreEqual, getColumnValueFromFilter, isAndFilter, isBetweenFilter, isBetweenOperator, isCompleteFilter, isExtendedFilter, isFilter, isFilterClause, isFilteredColumn, isInFilter, isMultiClauseFilter, isMultiValueFilter, isNamedFilter, isOrFilter, isScaledDecimalFilterClause, isSerializableFilter, isSingleValueFilter, isValidFilterClauseOp, stripFilterFromColumns };
+export { applyFilterToColumns, extractFilterForColumn, filtersAreEqual, getColumnValueFromFilter, getDefaultTimeRange, isAndFilter, isBetweenFilter, isBetweenOperator, isCompleteFilter, isExtendedFilter, isFilter, isFilterClause, isFilteredColumn, isInFilter, isMultiClauseFilter, isMultiValueFilter, isNamedFilter, isOrFilter, isScaledDecimalFilterClause, isSerializableFilter, isSingleValueFilter, isValidFilterClauseOp, stripFilterFromColumns };

package/src/filters/filterAsQuery.js

@@ -1,4 +1,6 @@
-import { isDateTimeDataValue } from "../column-utils.js";
+import { EpochTimestamp } from "../date/EpochTimestamp.js";
+import { getTemporalInfo } from "../date/temporal.js";
+import { isStartOfDay, startOfDay, startOfNextDay, timeOfDayToEpochMillis } from "../date/time-zone.js";
 import { stringIsValidLong } from "../data-utils.js";
 import { isMultiClauseFilter, isMultiValueFilter, isSerializableFilter } from "./filter-utils.js";
 import { ScaledDecimal } from "../ScaledDecimal.js";
@@ -8,7 +10,9 @@ const filterValue = (value, columnType)=>{
             const isNumericType = [
                 "int",
                 "long",
-                "double"
+                "double",
+                "epochtimestamp",
+                "epochtimestampnano"
             ].includes(columnType);
             return isNumericType ? value : `"${value}"`;
         }
@@ -24,64 +28,118 @@ const filterAsQueryCore = (f, opts)=>{
         const multiClauseFilter = f.filters.map((filter)=>filterAsQueryCore(filter, opts)).join(` ${f.op} `);
         return `(${multiClauseFilter})`;
     }
-    if (isMultiValueFilter(f)) return `${f.column} ${f.op} [${f.values.map(quotedStrings).join(",")}]`;
-    return singleValueFilterAsQuery(f, opts);
+    if (!isMultiValueFilter(f)) return singleValueFilterAsQuery(f, opts);
+    {
+        const column = opts?.columnsByName?.[f.column];
+        const temporalInfo = getTemporalInfo(column);
+        const values = f.values;
+        if (temporalInfo) {
+            const literals = values.map((v)=>EpochTimestamp.fromWire(v, temporalInfo.encoding)?.toLiteral(temporalInfo.encoding) ?? quotedStrings(v));
+            return `${f.column} ${f.op} [${literals.join(",")}]`;
+        }
+        return `${f.column} ${f.op} [${values.map(quotedStrings).join(",")}]`;
+    }
 };
 function singleValueFilterAsQuery(f, opts) {
     if (isSerializableFilter(f)) return f.asQuery();
     {
         const column = opts?.columnsByName?.[f.column];
-        if (column && isDateTimeDataValue(column)) return dateFilterAsQuery(f, opts);
+        const temporalInfo = getTemporalInfo(column);
+        if (temporalInfo) return temporalFilterAsQuery(f, temporalInfo);
         return defaultSingleValueFilterAsQuery(f, opts);
     }
 }
 const ONE_DAY_IN_MILLIS = 86400000;
-function dateFilterAsQuery(f, opts) {
-    switch(f.op){
+const timeOfDayPattern = /^\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?$/;
+const resolveTemporalFilterValue = (value, { encoding, kind, timeZone }, date = "today")=>{
+    if ("string" == typeof value && timeOfDayPattern.test(value)) {
+        const [hms, fraction = ""] = value.split(".");
+        const millis = timeOfDayToEpochMillis(hms, date, timeZone);
+        const nanos = parseInt(fraction.padEnd(9, "0"), 10);
+        const ts = EpochTimestamp.fromMillis(millis + Math.floor(nanos / 1000000), "epochNanos" === encoding ? nanos % 1000000 : 0);
+        return [
+            ts,
+            fraction ? "exact" : "second"
+        ];
+    }
+    const ts = EpochTimestamp.fromWire(value instanceof ScaledDecimal ? value.asLong : value, encoding);
+    if (void 0 === ts) return [
+        void 0,
+        "exact"
+    ];
+    const isWholeDay = 0 === ts.subMilliNanos && isStartOfDay(ts.epochMillis, timeZone);
+    if ("date" === kind || "datetime" === kind && isWholeDay) return [
+        ts,
+        "day"
+    ];
+    if ("time" === kind && 0 === ts.subMilliNanos && ts.epochMillis % 1000 === 0) return [
+        ts,
+        "second"
+    ];
+    return [
+        ts,
+        "exact"
+    ];
+};
+function temporalFilterAsQuery(f, temporalInfo, options) {
+    const { column, op } = f;
+    const { encoding, timeZone } = temporalInfo;
+    const [ts, granularity] = resolveTemporalFilterValue(f.value, temporalInfo, options?.date);
+    if (void 0 === ts) return `${column} ${op} ${filterValue(f.value, "long")}`;
+    if ("exact" === granularity) return `${column} ${op} ${ts.toLiteral(encoding)}`;
+    const [start, end] = "day" === granularity ? [
+        EpochTimestamp.fromMillis(startOfDay(ts.epochMillis, timeZone)),
+        EpochTimestamp.fromMillis(startOfNextDay(ts.epochMillis, timeZone))
+    ] : [
+        ts,
+        EpochTimestamp.fromMillis(ts.epochMillis + 1000)
+    ];
+    const from = start.toLiteral(encoding);
+    const to = end.toLiteral(encoding);
+    switch(op){
         case "=":
-            {
-                const filters = [
-                    {
-                        op: ">=",
-                        column: f.column,
-                        value: f.value
-                    },
-                    {
-                        op: "<",
-                        column: f.column,
-                        value: f.value + ONE_DAY_IN_MILLIS
-                    }
-                ];
-                return filterAsQueryCore({
-                    op: "and",
-                    filters
-                }, opts);
-            }
+            return `(${column} >= ${from} and ${column} < ${to})`;
         case "!=":
-            {
-                const filters = [
-                    {
-                        op: "<",
-                        column: f.column,
-                        value: f.value
-                    },
-                    {
-                        op: ">=",
-                        column: f.column,
-                        value: f.value + ONE_DAY_IN_MILLIS
-                    }
-                ];
-                return filterAsQueryCore({
-                    op: "or",
-                    filters
-                }, opts);
-            }
+            return `(${column} < ${from} or ${column} >= ${to})`;
+        case ">":
+            return `${column} >= ${to}`;
+        case ">=":
+            return `${column} >= ${from}`;
+        case "<":
+            return `${column} < ${from}`;
+        case "<=":
+            return `${column} < ${to}`;
         default:
-            return defaultSingleValueFilterAsQuery(f, opts);
+            return `${column} ${op} ${ts.toLiteral(encoding)}`;
     }
 }
+function dateFilterAsQuery(f, opts) {
+    const temporalInfo = getTemporalInfo(opts?.columnsByName?.[f.column] ?? {
+        type: "date/time"
+    });
+    return temporalFilterAsQuery(f, temporalInfo);
+}
 const defaultSingleValueFilterAsQuery = (f, opts)=>{
     const columnType = opts?.columnsByName?.[f.column]?.serverDataType;
     return `${f.column} ${f.op} ${filterValue(f.value, columnType)}`;
 };
-export { ONE_DAY_IN_MILLIS, dateFilterAsQuery, filterAsQuery };
+const getColumnsByName = (columns)=>columns.reduce((map, column)=>{
+        map[column.name] = column;
+        return map;
+    }, {});
+const getColumnsByNameForFilter = (tableSchema, columnsByName)=>{
+    if (void 0 === tableSchema) return columnsByName;
+    const result = {};
+    for (const column of tableSchema.columns)result[column.name] = {
+        ...column,
+        ...columnsByName?.[column.name]
+    };
+    if (columnsByName) for (const [name, column] of Object.entries(columnsByName))result[name] ??= column;
+    return result;
+};
+const filterRequiresResolution = (filter, columnsByName)=>{
+    if (isMultiClauseFilter(filter)) return filter.filters.some((f)=>filterRequiresResolution(f, columnsByName));
+    if (isSerializableFilter(filter)) return true;
+    return void 0 !== getTemporalInfo(columnsByName?.[filter.column]);
+};
+export { ONE_DAY_IN_MILLIS, dateFilterAsQuery, filterAsQuery, filterRequiresResolution, getColumnsByName, getColumnsByNameForFilter, temporalFilterAsQuery };

package/src/form-utils.js

@@ -1,5 +1,8 @@
 import { stringIsValidDecimal, stringIsValidInt, stringIsValidLong } from "./data-utils.js";
-import { Time, isValidTimeString } from "./date/index.js";
+import { Time, isValidTimeString, isValidTimeStringMillis, normaliseTimeString } from "./date/date-utils.js";
+import { getTemporalInfo, parseTemporalInput } from "./date/temporal.js";
+import { getDefaultTimeZone } from "./date/time-zone.js";
+import { isTypeDescriptor } from "./column-utils.js";
 import { queryClosest } from "./html-utils.js";
 import { ScaledDecimal2, ScaledDecimal4, ScaledDecimal6, ScaledDecimal8 } from "./ScaledDecimal.js";
 class DataValidationError extends Error {
@@ -19,7 +22,9 @@ const getFieldName = (target)=>{
 };
 const isNumber = (type, value)=>"number" === type;
 const isValidRange = ([val1, val2])=>{
-    if (isValidTimeString(val1) && isValidTimeString(val2)) return val2 > val1;
+    const time1 = normaliseTimeString(val1, true);
+    const time2 = normaliseTimeString(val2, true);
+    if (time1 && time2) return time2 > time1;
     return true;
 };
 function getTypedRange([value1, value2], dataType, options) {
@@ -62,8 +67,24 @@ function getTypedValue(value, type, throwIfInvalid = false, options) {
             throw new DataValidationError(`value ${value} is not a valid ${type}`, "decimal", getActualType(value));
         case "boolean":
             return "true" === value;
+        case "epochtimestamp":
+        case "epochtimestampnano":
+        case "date/time":
+        case "date":
+            {
+                const encoding = "epochtimestampnano" === type ? "epochNanos" : "epochMillis";
+                const timestamp = parseTemporalInput(value, {
+                    kind: "date" === type ? "date" : "datetime",
+                    encoding,
+                    precision: "epochNanos" === encoding ? "ns" : "ms",
+                    timeZone: getDefaultTimeZone()
+                });
+                if (timestamp) return timestamp.toWire(encoding);
+                if (!throwIfInvalid) return;
+                throw new DataValidationError(`value ${value} is not a valid ${type}`, "date/time", getActualType(value));
+            }
         case "time":
-            if (isValidTimeString(value)) if (options?.type === "TimeString") return value;
+            if (isValidTimeString(value) || isValidTimeStringMillis(value)) if (options?.type === "TimeString") return value;
             else return +Time(value).asDate();
             if (value.length > 0 && Time.isDateInMillis(value)) return Number(value);
             if (!throwIfInvalid) return;
@@ -72,4 +93,17 @@ function getTypedValue(value, type, throwIfInvalid = false, options) {
             return value;
     }
 }
-export { DataValidationError, getFieldName, getTypedRange, getTypedValue, isNumber, isValidRange };
+function getTypedTemporalValue(value, temporalInfo, throwIfInvalid = false, baseValue) {
+    if ("" === value) return;
+    const timestamp = parseTemporalInput(value, temporalInfo, baseValue);
+    if (timestamp) return timestamp.toWire(temporalInfo.encoding);
+    if (throwIfInvalid) throw new DataValidationError(`value ${value} is not a valid ${temporalInfo.kind}`, temporalInfo.kind, getActualType(value));
+}
+function getTypedValueForDescriptor(value, descriptor, throwIfInvalid = false) {
+    const temporalInfo = getTemporalInfo(descriptor);
+    if (temporalInfo) return getTypedTemporalValue(value, temporalInfo, throwIfInvalid);
+    const { serverDataType = "string", type } = descriptor;
+    const dataType = isTypeDescriptor(type) ? type.name : type ?? serverDataType;
+    return throwIfInvalid ? getTypedValue(value, dataType, true) : getTypedValue(value, dataType, false);
+}
+export { DataValidationError, getFieldName, getTypedRange, getTypedTemporalValue, getTypedValue, getTypedValueForDescriptor, isNumber, isValidRange };

package/src/formatting-utils.js

@@ -1,31 +1,45 @@
-import { isDateTimeDataValue, isMappedValueTypeRenderer, isNanoTimestampColumn, isTimeDataValue, isTypeDescriptor } from "./column-utils.js";
-import { dateTimePattern, formatDate } from "./date/index.js";
+import { isMappedValueTypeRenderer, isTypeDescriptor } from "./column-utils.js";
+import { dateTimePattern, defaultPatternsByType } from "./date/dateTimePattern.js";
+import { isStartOfDay } from "./date/time-zone.js";
+import { EpochTimestamp } from "./date/EpochTimestamp.js";
+import { formatTimestamp } from "./date/formatter.js";
+import { getTemporalInfo } from "./date/temporal.js";
 import { roundDecimal, roundScaledDecimal } from "./round-decimal.js";
 import { isNumericType } from "./protocol-message-utils.js";
 const DEFAULT_NUMERIC_FORMAT = {};
 const defaultValueFormatter = (value)=>null == value ? "" : "string" == typeof value ? value : value.toString();
-const dateFormatter = (column)=>{
-    if (isNanoTimestampColumn(column)) {
-        const pattern = dateTimePattern(column.type);
-        const formatter = formatDate(pattern);
-        return (value)=>{
-            if ("string" != typeof value || "" === value) return "";
-            {
-                const bigIntValue = BigInt(value);
-                const dateTimeValue = Number(bigIntValue / 1000000n);
-                const nanoSeconds = (bigIntValue % 1000000n).toString().padStart(9, "0");
-                return `${formatter(new Date(dateTimeValue))}.${nanoSeconds}`;
-            }
-        };
-    }
-    {
-        const pattern = dateTimePattern(column.type);
-        const formatter = formatDate(pattern);
-        return (value)=>{
-            if ("number" == typeof value && 0 !== value) return formatter(new Date(value));
-            return "";
-        };
+const temporalFormatter = (column, temporalInfo = getTemporalInfo(column))=>{
+    if (void 0 === temporalInfo) return defaultValueFormatter;
+    const { encoding, kind, precision, timeZone } = temporalInfo;
+    const formatting = isTypeDescriptor(column.type) ? column.type.formatting ?? DEFAULT_NUMERIC_FORMAT : DEFAULT_NUMERIC_FORMAT;
+    const pattern = dateTimePattern(column.type, kind);
+    const fractionalSecondDigits = formatting.fractionalSecondDigits ?? ("hh:mm:ss.ms" === pattern.time ? 3 : "ns" === precision && pattern.time ? 9 : 0);
+    const formatter = formatTimestamp(pattern, {
+        fractionalSecondDigits,
+        locale: formatting.locale,
+        timeZone
+    });
+    return (value)=>{
+        const timestamp = EpochTimestamp.fromWire(value, encoding);
+        return timestamp ? formatter(timestamp) : "";
+    };
+};
+const timeOfDayPattern = /^\d{2}:\d{2}:\d{2}(\.\d{1,9})?$/;
+const formatTemporalFilterValue = (value, column)=>{
+    const temporalInfo = getTemporalInfo(column);
+    if ("string" == typeof value && timeOfDayPattern.test(value)) return value;
+    if (void 0 === temporalInfo) return defaultValueFormatter(value);
+    const timestamp = EpochTimestamp.fromWire(value, temporalInfo.encoding);
+    if (void 0 === timestamp) return defaultValueFormatter(value);
+    if ("datetime" === temporalInfo.kind && 0 === timestamp.subMilliNanos && isStartOfDay(timestamp.epochMillis, temporalInfo.timeZone)) {
+        const { date = defaultPatternsByType.date } = dateTimePattern(column.type, "date");
+        return formatTimestamp({
+            date
+        }, {
+            timeZone: temporalInfo.timeZone
+        })(timestamp);
     }
+    return temporalFormatter(column, temporalInfo)(value);
 };
 const numericFormatter = ({ align = "right", serverDataType, type })=>{
     if (void 0 === type || "string" == typeof type) return defaultValueFormatter;
@@ -47,7 +61,8 @@ const NumericTypes = [
 ];
 const getValueFormatter = (column)=>{
     const { serverDataType = "string" } = column;
-    if (isDateTimeDataValue(column) || isTimeDataValue(column)) return dateFormatter(column);
+    const temporalInfo = getTemporalInfo(column);
+    if (temporalInfo) return temporalFormatter(column, temporalInfo);
     const { type } = column;
     if (isTypeDescriptor(type) && isMappedValueTypeRenderer(type?.renderer)) return mapFormatter(type.renderer.map);
     if (isNumericType(serverDataType) || isTypeDescriptor(type) && NumericTypes.includes(type.name)) return numericFormatter(column);
@@ -55,4 +70,4 @@ const getValueFormatter = (column)=>{
     return defaultValueFormatter;
 };
 const lowerCase = (str)=>str.toLowerCase();
-export { defaultValueFormatter, getValueFormatter, lowerCase, numericFormatter };
+export { defaultValueFormatter, formatTemporalFilterValue, getValueFormatter, lowerCase, numericFormatter, temporalFormatter };

package/src/nanoid/index.js

@@ -1,12 +1,12 @@
 const uuid = (size = 21)=>{
-    let id = '';
+    let id = "";
     const bytes = crypto.getRandomValues(new Uint8Array(size));
     while(size--){
         const byte = 63 & bytes[size];
         if (byte < 36) id += byte.toString(36);
         else if (byte < 62) id += (byte - 26).toString(36).toUpperCase();
-        else if (byte < 63) id += '_';
-        else id += '-';
+        else if (byte < 63) id += "_";
+        else id += "-";
     }
     return id;
 };

package/types/column-utils.d.ts

@@ -32,13 +32,48 @@ export type CalculatedColumn = {
 };
 export declare const isVuuColumnDataType: (value: string | undefined | null) => value is VuuColumnDataType;
 export declare const fromServerDataType: (serverDataType: VuuColumnDataType) => DataValueTypeSimple;
+/**
+ * Returns true if serverDataType is epochtimestampnano. Note: prefer
+ * getTemporalInfo, which describes encoding, kind and time zone.
+ */
 export declare const isNanoTimestampColumn: ({ serverDataType, }: DataValueDescriptor) => boolean;
-export declare const isTimestampColumn: (column: ColumnDescriptor) => boolean;
-export declare const isNumericColumn: ({ serverDataType, type }: ColumnDescriptor) => boolean;
-export declare const isDateTimeDataType: (column: ColumnDescriptor) => column is DateTimeDataValueDescriptor;
-export declare const isTimeDataType: (column: ColumnDescriptor) => column is TimeDataValueDescriptor;
-export declare const isDateTimeDataValue: (column: ColumnDescriptor) => boolean;
-export declare const isTimeDataValue: (column?: ColumnDescriptor) => column is TimeDataValueDescriptor;
+/**
+ * Returns true if serverDataType is epochtimestamp or epochtimestampnano.
+ * Note: this does not recognise legacy columns (long with a date/time type),
+ * use isTemporalColumn for that.
+ */
+export declare const isTimestampColumn: (column: DataValueDescriptor) => boolean;
+/**
+ * Returns true for any column holding a temporal value, see getTemporalInfo.
+ */
+export declare const isTemporalColumn: (column?: DataValueDescriptor) => boolean;
+/**
+ * Numeric columns, excluding those that hold temporal values.
+ */
+export declare const isNumericColumn: (column: ColumnDescriptor) => boolean;
+/**
+ * Checks the 'type' only, returns true for 'date/time' (or 'date').
+ * @deprecated use getTemporalInfo or isDateTimeDataValue
+ */
+export declare const isDateTimeDataType: (column: DataValueDescriptor) => column is DateTimeDataValueDescriptor;
+/**
+ * Checks the 'type' only, returns true for 'time'.
+ * @deprecated use getTemporalInfo or isTimeDataValue
+ */
+export declare const isTimeDataType: (column: DataValueDescriptor) => column is TimeDataValueDescriptor;
+/**
+ * Temporal value of kind 'datetime' or 'date' (i.e has a meaningful date component)
+ */
+export declare const isDateTimeDataValue: (column?: DataValueDescriptor) => boolean;
+/**
+ * Temporal value of kind 'time' (time of day)
+ */
+export declare const isTimeDataValue: (column?: DataValueDescriptor) => column is TimeDataValueDescriptor;
+/**
+ * A time column is edited/filtered with millisecond precision if its
+ * formatting pattern includes milliseconds.
+ */
+export declare const isTimeDataValueWithMilliseconds: (column?: ColumnDescriptor) => column is TimeDataValueDescriptor;
 export declare const isPinned: (column: ColumnDescriptor) => boolean;
 export declare const hasHeadings: (column: ColumnDescriptor) => boolean;
 export declare const isResizing: (column: RuntimeColumnDescriptor) => boolean | undefined;

package/types/datasource/BaseDataSource.d.ts

@@ -1,4 +1,4 @@
-import type { DataSource, DataSourceConstructorProps, DataSourceEvents, DataSourceFilter, DataSourceSubscribeCallback, DataSourceSubscribeProps, DataSourceSuspenseProps, WithBaseFilter, WithFullConfig } from "@vuu-ui/vuu-data-types";
+import type { DataSource, DataSourceConstructorProps, DataSourceEvents, DataSourceFilter, DataSourceSubscribeCallback, DataSourceSubscribeProps, DataSourceSuspenseProps, SetFilterOptions, WithBaseFilter, WithFullConfig } from "@vuu-ui/vuu-data-types";
 import { LinkDescriptorWithLabel, VuuAggregation, VuuRange, VuuSort } from "@vuu-ui/vuu-protocol-types";
 import { EventEmitter } from "../event-emitter";
 import { Range } from "../range-utils";
@@ -28,7 +28,7 @@ export declare abstract class BaseDataSource extends EventEmitter<DataSourceEven
     set columns(columns: string[]);
     get filter(): DataSourceFilter;
     set filter(filter: DataSourceFilter);
-    setFilter(filter: Filter): void;
+    setFilter(filter: Filter, options?: SetFilterOptions): void;
     clearFilter(): void;
     get isAwaitingConfirmationOfConfigChange(): boolean;
     protected confirmConfigChange(): void;

package/types/date/EpochTimestamp.d.ts

@@ -0,0 +1,63 @@
+import { type DateTimeFields, type TimeZoneSpec } from "./time-zone";
+/**
+ * How a temporal value is encoded on the wire (i.e in rows received from,
+ * and values sent to, the server).
+ * - epochMillis, a number (epochtimestamp, or legacy long with a date/time type)
+ * - epochNanos, a string of digits (epochtimestampnano). Nanosecond values
+ *   cannot be represented safely as JavaScript numbers. A bigint is also
+ *   accepted where values are generated locally.
+ */
+export type TemporalEncoding = "epochMillis" | "epochNanos";
+/**
+ * A timestamp with nanosecond precision. Internally represented as epoch
+ * millis (floored) plus nanos within the milli, so the common millisecond
+ * case requires no bigint arithmetic.
+ *
+ * Note: an empty value (null, undefined, '', 0, '0') is treated as 'no value'
+ * by fromWire. The Vuu server uses 0 to represent an unset timestamp, so
+ * the epoch itself (1970-01-01T00:00:00.000Z) cannot be represented.
+ */
+export declare class EpochTimestamp {
+    readonly epochMillis: number;
+    /** nanoseconds within the millisecond, 0 - 999,999 */
+    readonly subMilliNanos: number;
+    private constructor();
+    static fromMillis(epochMillis: number, subMilliNanos?: number): EpochTimestamp;
+    static fromNanos(epochNanos: bigint | string | number): EpochTimestamp;
+    static fromDate(date: Date): EpochTimestamp;
+    static fromFields(fields: Partial<DateTimeFields> & Pick<DateTimeFields, "year" | "month" | "day">, timeZone?: TimeZoneSpec, subMilliNanos?: number): EpochTimestamp;
+    /**
+     * Returns true if value represents 'no value'.
+     */
+    static isEmpty(value: unknown): value is 0 | "" | "0" | 0n | null | undefined;
+    /**
+     * Decode a value as received from the server, or held in a filter,
+     * in the given encoding. Returns undefined for an empty or invalid value.
+     */
+    static fromWire(value: unknown, encoding: TemporalEncoding): EpochTimestamp | undefined;
+    get epochNanos(): bigint;
+    toDate(): Date;
+    /**
+     * Fraction of second, truncated to the requested number of digits
+     */
+    fractionalSecond(digits: number): string;
+    getFields(timeZone?: TimeZoneSpec): DateTimeFields;
+    /**
+     * Encode for the wire. epochMillis => number, epochNanos => string
+     */
+    toWire(encoding: "epochMillis"): number;
+    toWire(encoding: "epochNanos"): string;
+    toWire(encoding: TemporalEncoding): number | string;
+    /**
+     * Encode as a literal in a filter query (never quoted)
+     */
+    toLiteral(encoding: TemporalEncoding): string;
+    /**
+     * Add a number of the smallest unit for the encoding, i.e 1 milli or 1 nano.
+     * Useful to convert inclusive to exclusive bounds.
+     */
+    addUnits(units: number, encoding: TemporalEncoding): EpochTimestamp;
+    compare(other: EpochTimestamp): number;
+    equals(other?: EpochTimestamp): boolean;
+    toString(): string;
+}