df-script 1.6.0 → 1.8.0

package/dist/columnExpressions/mixins/TemporalExpr.d.ts

@@ -1,43 +1,620 @@
-import type { TimeUnit } from "../../types";
+import type { TimeUnit, DatetimeTimeUnit, StrftimeOptions, IsBusinessDayOptions, DayOffsetOptions, UtcOffsetOptions, ReplaceDateOptions } from "../../types";
 import { ExprBase } from "../ExprBase";
+/**
+ * @namespace $df.col.dt
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).dt.{symbol}(...)
+ *
+ * **Implementation Notes**
+ *
+ * _TimeUnit_: `Date` objects are always millisecond-based, so `timeUnit` is schema
+ * metadata only. Sub-millisecond precision (`us`, `ns`) cannot be stored; methods such
+ * as `microsecond()` and `nanosecond()` always scale from milliseconds. Migrating to
+ * raw `BigInt` arrays would be required for true sub-ms storage.
+ *
+ * _Timezone enforcement_: `convert_time_zone` can only validate that the column is
+ * timezone-aware when `_castType` is explicitly set within the expression chain
+ * (e.g. after `cast_time_unit`). Enforcement against a column whose type is unknown
+ * at expression-build time requires schema-level checks in DataFrame operations.
+ */
 export declare class DateTimeExprNamespace {
     expr: any;
     constructor(expr: any);
+    /** Returns the column's schema timezone from a prior convert_time_zone call, or null. */
+    _colTz(): string | null;
+    /** Returns the column's schema time unit from a prior cast_time_unit call, or null. */
+    _colTu(): DatetimeTimeUnit | null;
     _deriveDate(fn: (d: Date) => any): any;
-    _deriveDuration(fn: (v: number) => number): any;
+    /**
+     * Casts the schema time unit of a Datetime column (`"ms"`, `"us"`, `"ns"`).
+     * This is a metadata-only operation — underlying millisecond Date timestamps are preserved.
+     * @param unit Target time unit: `"ms"` (milliseconds), `"us"` (microseconds), or `"ns"` (nanoseconds).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:00:00.123Z"] })
+     * >>> df.with_columns($df.col("ts").dt.cast_time_unit("us").alias("ts_us"))
+     * shape: (1, 2)
+     * ┌──────────────────────────┬──────────────────────────┐
+     * │ ts                       │ ts_us                    │
+     * ├──────────────────────────┼──────────────────────────┤
+     * │ 2026-05-20T10:00:00.123Z │ 2026-05-20T10:00:00.123Z │
+     * └──────────────────────────┴──────────────────────────┘
+     */
+    cast_time_unit(unit: DatetimeTimeUnit): any;
+    /**
+     * Extracts the 1-indexed century component (e.g. 21 for 2026) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.century().alias("century"))
+     * shape: (1, 2)
+     * ┌────────────┬─────────┐
+     * │ d          │ century │
+     * ├────────────┼─────────┤
+     * │ 2026-05-20 │ 21      │
+     * └────────────┴─────────┘
+     */
     century(): any;
+    /**
+     * Converts a Datetime column to a different IANA timezone.
+     * Preserves the exact UTC epoch instant while changing the timezone label, affecting
+     * how local wall-clock component extractors (`hour()`, `day()`, etc.) and `strftime` interpret values.
+     * Requires the column to already be timezone-aware; use `replace({ timeZone })`
+     * to assign a timezone to a naive column first.
+     * @param timeZone Target IANA timezone identifier (e.g. `"UTC"`, `"America/New_York"`, `"Europe/London"`).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-06-01T00:00:00.000Z"] })
+     * >>> df.with_columns($df.col("ts").dt.convert_time_zone("America/New_York").alias("ts_ny"))
+     * shape: (1, 2)
+     * ┌──────────────────────────┬───────────────────────────────┐
+     * │ ts                       │ ts_ny                         │
+     * ├──────────────────────────┼───────────────────────────────┤
+     * │ 2026-06-01T00:00:00.000Z │ 2026-05-31 20:00:00.000 EDT   │
+     * └──────────────────────────┴───────────────────────────────┘
+     */
+    convert_time_zone(timeZone: string): any;
+    /**
+     * Extracts the Date object component from a Datetime column, truncating time to 00:00:00.000 UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:30:00Z"] })
+     * >>> df.with_columns($df.col("ts").dt.date().alias("date_only"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬──────────────────────────┐
+     * │ ts                   │ date_only                │
+     * ├──────────────────────┼──────────────────────────┤
+     * │ 2026-05-20T10:30:00Z │ 2026-05-20T00:00:00.000Z │
+     * └──────────────────────┴──────────────────────────┘
+     */
     date(): any;
-    datetime(): any;
-    day(): any;
+    /**
+     * Extracts the calendar day component (1-31) from a Datetime column.
+     * @param timeZone Optional IANA timezone identifier. Defaults to the column timezone or UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.day().alias("day"))
+     * shape: (1, 2)
+     * ┌────────────┬─────┐
+     * │ d          │ day │
+     * ├────────────┼─────┤
+     * │ 2026-05-20 │ 20  │
+     * └────────────┴─────┘
+     */
+    day(timeZone?: string): any;
+    /**
+     * Extracts the total number of days in the month (28-31) for each Datetime value.
+     * @param timeZone Optional IANA timezone identifier. Defaults to the column timezone or UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2024-02-15"] })
+     * >>> df.with_columns($df.col("d").dt.days_in_month().alias("dim"))
+     * shape: (1, 2)
+     * ┌────────────┬─────┐
+     * │ d          │ dim │
+     * ├────────────┼─────┤
+     * │ 2024-02-15 │ 29  │
+     * └────────────┴─────┘
+     */
+    days_in_month(timeZone?: string): any;
+    /**
+     * Returns the epoch duration timestamp offset in the specified time resolution unit.
+     * @param unit Time resolution unit (`"ms"`, `"us"`, `"ns"`, `"s"`). Defaults to `"ms"`.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-01-01T00:00:00Z"] })
+     * >>> df.with_columns($df.col("d").dt.epoch("s").alias("epoch_s"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬────────────┐
+     * │ d                    │ epoch_s    │
+     * ├──────────────────────┼────────────┤
+     * │ 2026-01-01T00:00:00Z │ 1767225600 │
+     * └──────────────────────┴────────────┘
+     */
     epoch(unit?: TimeUnit): any;
-    hour(): any;
+    /**
+     * Extracts the local hour component (0-23) from a Datetime column.
+     * @param timeZone Optional IANA timezone identifier. Defaults to the column timezone or UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T14:30:00Z"] })
+     * >>> df.with_columns($df.col("ts").dt.hour().alias("hr"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬────┐
+     * │ ts                   │ hr │
+     * ├──────────────────────┼────┤
+     * │ 2026-05-20T14:30:00Z │ 14 │
+     * └──────────────────────┴────┘
+     */
+    hour(timeZone?: string): any;
+    /**
+     * Evaluates whether each Datetime value falls on a business day.
+     * Supports custom weekend day definitions and holiday arrays or timestamp sets.
+     * @param options Business day rules and custom holiday configuration options.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-18"] })
+     * >>> df.with_columns($df.col("d").dt.is_business_day().alias("is_bday"))
+     * shape: (1, 2)
+     * ┌────────────┬─────────┐
+     * │ d          │ is_bday │
+     * ├────────────┼─────────┤
+     * │ 2026-05-18 │ true    │
+     * └────────────┴─────────┘
+     */
+    is_business_day(options?: IsBusinessDayOptions): any;
+    /**
+     * Checks if the calendar year of a Datetime value is a leap year (366 days).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2024-01-01", "2026-01-01"] })
+     * >>> df.with_columns($df.col("d").dt.is_leap_year().alias("leap"))
+     * shape: (2, 2)
+     * ┌────────────┬───────┐
+     * │ d          │ leap  │
+     * ├────────────┼───────┤
+     * │ 2024-01-01 │ true  │
+     * │ 2026-01-01 │ false │
+     * └────────────┴───────┘
+     */
     is_leap_year(): any;
+    /**
+     * Extracts the ISO 8601 week number (1-53) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.iso_week().alias("week"))
+     * shape: (1, 2)
+     * ┌────────────┬──────┐
+     * │ d          │ week │
+     * ├────────────┼──────┤
+     * │ 2026-05-20 │ 21   │
+     * └────────────┴──────┘
+     */
+    iso_week(): any;
+    /**
+     * Extracts the ISO 8601 week-numbering year from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.iso_year().alias("iso_yr"))
+     * shape: (1, 2)
+     * ┌────────────┬────────┐
+     * │ d          │ iso_yr │
+     * ├────────────┼────────┤
+     * │ 2026-05-20 │ 2026   │
+     * └────────────┴────────┘
+     */
+    iso_year(): any;
+    /**
+     * Extracts the microsecond component (0-999,000) scaled from Datetime millisecond precision.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:00:00.123Z"] })
+     * >>> df.with_columns($df.col("ts").dt.microsecond().alias("us"))
+     * shape: (1, 2)
+     * ┌──────────────────────────┬────────┐
+     * │ ts                       │ us     │
+     * ├──────────────────────────┼────────┤
+     * │ 2026-05-20T10:00:00.123Z │ 123000 │
+     * └──────────────────────────┴────────┘
+     */
     microsecond(): any;
+    /**
+     * Extracts the 1-indexed millennium component index (e.g. 3 for the year 2026) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.millennium().alias("mil"))
+     * shape: (1, 2)
+     * ┌────────────┬─────┐
+     * │ d          │ mil │
+     * ├────────────┼─────┤
+     * │ 2026-05-20 │ 3   │
+     * └────────────┴─────┘
+     */
     millennium(): any;
+    /**
+     * Extracts the millisecond component (0-999) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:00:00.456Z"] })
+     * >>> df.with_columns($df.col("ts").dt.millisecond().alias("ms"))
+     * shape: (1, 2)
+     * ┌──────────────────────────┬─────┐
+     * │ ts                       │ ms  │
+     * ├──────────────────────────┼─────┤
+     * │ 2026-05-20T10:00:00.456Z │ 456 │
+     * └──────────────────────────┴─────┘
+     */
     millisecond(): any;
-    minute(): any;
-    month(): any;
+    /**
+     * Extracts the minute component (0-59) from a Datetime column.
+     * @param timeZone Optional IANA timezone identifier. Defaults to the column timezone or UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:45:00Z"] })
+     * >>> df.with_columns($df.col("ts").dt.minute().alias("min"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬─────┐
+     * │ ts                   │ min │
+     * ├──────────────────────┼─────┤
+     * │ 2026-05-20T10:45:00Z │ 45  │
+     * └──────────────────────┴─────┘
+     */
+    minute(timeZone?: string): any;
+    /**
+     * Extracts the calendar month component (1-12) from a Datetime column.
+     * @param timeZone Optional IANA timezone identifier. Defaults to the column timezone or UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.month().alias("m"))
+     * shape: (1, 2)
+     * ┌────────────┬───┐
+     * │ d          │ m │
+     * ├────────────┼───┤
+     * │ 2026-05-20 │ 5 │
+     * └────────────┴───┘
+     */
+    month(timeZone?: string): any;
+    /**
+     * Returns a Datetime column shifted to the last calendar day of the month at 00:00:00.000 UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.month_end().alias("m_end"))
+     * shape: (1, 2)
+     * ┌────────────┬──────────────────────────┐
+     * │ d          │ m_end                    │
+     * ├────────────┼──────────────────────────┤
+     * │ 2026-05-20 │ 2026-05-31T00:00:00.000Z │
+     * └────────────┴──────────────────────────┘
+     */
     month_end(): any;
+    /**
+     * Returns a Datetime column shifted to the first calendar day of the month at 00:00:00.000 UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.month_start().alias("m_start"))
+     * shape: (1, 2)
+     * ┌────────────┬──────────────────────────┐
+     * │ d          │ m_start                  │
+     * ├────────────┼──────────────────────────┤
+     * │ 2026-05-20 │ 2026-05-01T00:00:00.000Z │
+     * └────────────┴──────────────────────────┘
+     */
     month_start(): any;
+    /**
+     * Extracts the nanosecond component (0-999,000,000) scaled from Datetime millisecond precision.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:00:00.001Z"] })
+     * >>> df.with_columns($df.col("ts").dt.nanosecond().alias("ns"))
+     * shape: (1, 2)
+     * ┌──────────────────────────┬─────────┐
+     * │ ts                       │ ns      │
+     * ├──────────────────────────┼─────────┤
+     * │ 2026-05-20T10:00:00.001Z │ 1000000 │
+     * └──────────────────────────┴─────────┘
+     */
     nanosecond(): any;
+    /**
+     * Offsets a Datetime column by N calendar days (numeric constant, column reference, or expression).
+     * Reuses $df.duration({ days: n }) and expression addition math under the hood.
+     * @param n Number of calendar days to offset (positive or negative).
+     * @param options Day offset configuration options.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.offset_day(5).alias("later"))
+     * shape: (1, 2)
+     * ┌────────────┬──────────────────────────┐
+     * │ d          │ later                    │
+     * ├────────────┼──────────────────────────┤
+     * │ 2026-05-20 │ 2026-05-25T00:00:00.000Z │
+     * └────────────┴──────────────────────────┘
+     */
+    offset_day(n: number | any, options?: DayOffsetOptions): any;
+    /**
+     * Extracts the day of the year (1-366) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-02-01"] })
+     * >>> df.with_columns($df.col("d").dt.ordinal_day().alias("doy"))
+     * shape: (1, 2)
+     * ┌────────────┬─────┐
+     * │ d          │ doy │
+     * ├────────────┼─────┤
+     * │ 2026-02-01 │ 32  │
+     * └────────────┴─────┘
+     */
     ordinal_day(): any;
+    /**
+     * Extracts the calendar quarter of the year (1-4) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.quarter().alias("qtr"))
+     * shape: (1, 2)
+     * ┌────────────┬─────┐
+     * │ d          │ qtr │
+     * ├────────────┼─────┤
+     * │ 2026-05-20 │ 2   │
+     * └────────────┴─────┘
+     */
     quarter(): any;
+    /**
+     * Replaces specific date and time components (`year`, `month`, `day`, `hour`, `minute`, `second`, `ms`, `timeZone`) of a Datetime column.
+     * Unspecified components are preserved from the original value.
+     * When `timeZone` is provided in options, components are interpreted in that timezone.
+     * Note: `month` is 1-indexed (1 = January, 12 = December); `day` is 1-indexed (1-31).
+     * @param options Object specifying which components to replace.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T14:30:00Z"] })
+     * >>> df.with_columns($df.col("ts").dt.replace({ year: 2030, month: 1, day: 1 }).alias("replaced"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬──────────────────────────┐
+     * │ ts                   │ replaced                 │
+     * ├──────────────────────┼──────────────────────────┤
+     * │ 2026-05-20T14:30:00Z │ 2030-01-01T14:30:00.000Z │
+     * └──────────────────────┴──────────────────────────┘
+     */
+    replace(options: ReplaceDateOptions): any;
+    /**
+     * Extracts the second component (0-59) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:00:45Z"] })
+     * >>> df.with_columns($df.col("ts").dt.second().alias("sec"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬─────┐
+     * │ ts                   │ sec │
+     * ├──────────────────────┼─────┤
+     * │ 2026-05-20T10:00:45Z │ 45  │
+     * └──────────────────────┴─────┘
+     */
     second(): any;
-    strftime(format: string, locale?: string): any;
+    /**
+     * Formats Datetime values into custom formatted strings using strftime directive pattern tokens.
+     * Automatically applies the column's assigned timezone unless explicitly overridden in options.
+     * @param options Formatting pattern string (e.g. `"%Y-%m-%d %H:%M:%S"`) or configuration object.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.strftime("%Y/%m/%d").alias("formatted"))
+     * shape: (1, 2)
+     * ┌────────────┬────────────┐
+     * │ d          │ formatted  │
+     * ├────────────┼────────────┤
+     * │ 2026-05-20 │ 2026/05/20 │
+     * └────────────┴────────────┘
+     */
+    strftime(options: StrftimeOptions): any;
+    /**
+     * Extracts the time component formatted string (`"HH:MM:SS.mmm"`) from a Datetime column.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ ts: ["2026-05-20T10:30:00Z"] })
+     * >>> df.with_columns($df.col("ts").dt.time().alias("time"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬──────────────┐
+     * │ ts                   │ time         │
+     * ├──────────────────────┼──────────────┤
+     * │ 2026-05-20T10:30:00Z │ 10:30:00.000 │
+     * └──────────────────────┴──────────────┘
+     */
     time(): any;
+    /**
+     * Returns numeric timestamp relative to Epoch. Alias for epoch.
+     * @param unit Time unit resolution.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-01-01T00:00:00Z"] })
+     * >>> df.with_columns($df.col("d").dt.timestamp("s").alias("ts"))
+     * shape: (1, 2)
+     * ┌──────────────────────┬────────────┐
+     * │ d                    │ ts         │
+     * ├──────────────────────┼────────────┤
+     * │ 2026-01-01T00:00:00Z │ 1767225600 │
+     * └──────────────────────┴────────────┘
+     */
     timestamp(unit?: TimeUnit): any;
-    to_string(format: string, locale?: string): any;
+    /**
+     * Converts a Duration value (in milliseconds) to total days count.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [86400000] })
+     * >>> df.with_columns($df.col("dur").dt.total_days().alias("days"))
+     * shape: (1, 2)
+     * ┌──────────┬──────┐
+     * │ dur      │ days │
+     * ├──────────┼──────┤
+     * │ 86400000 │ 1    │
+     * └──────────┴──────┘
+     */
     total_days(): any;
+    /**
+     * Converts a Duration value (in milliseconds) to total hours count.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [3600000] })
+     * >>> df.with_columns($df.col("dur").dt.total_hours().alias("hrs"))
+     * shape: (1, 2)
+     * ┌─────────┬─────┐
+     * │ dur     │ hrs │
+     * ├─────────┼─────┤
+     * │ 3600000 │ 1   │
+     * └─────────┴─────┘
+     */
     total_hours(): any;
+    /**
+     * Converts Duration to microsecond count.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [10] })
+     * >>> df.with_columns($df.col("dur").dt.total_microseconds().alias("us"))
+     * shape: (1, 2)
+     * ┌─────┬───────┐
+     * │ dur │ us    │
+     * ├─────┼───────┤
+     * │ 10  │ 10000 │
+     * └─────┴───────┘
+     */
     total_microseconds(): any;
+    /**
+     * Converts Duration to millisecond count.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [500] })
+     * >>> df.with_columns($df.col("dur").dt.total_milliseconds().alias("ms"))
+     * shape: (1, 2)
+     * ┌─────┬─────┐
+     * │ dur │ ms  │
+     * ├─────┼─────┤
+     * │ 500 │ 500 │
+     * └─────┴─────┘
+     */
     total_milliseconds(): any;
+    /**
+     * Converts Duration to floating point minutes.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [60000] })
+     * >>> df.with_columns($df.col("dur").dt.total_minutes().alias("mins"))
+     * shape: (1, 2)
+     * ┌───────┬──────┐
+     * │ dur   │ mins │
+     * ├───────┼──────┤
+     * │ 60000 │ 1    │
+     * └───────┴──────┘
+     */
     total_minutes(): any;
+    /**
+     * Converts Duration to nanosecond count.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [1] })
+     * >>> df.with_columns($df.col("dur").dt.total_nanoseconds().alias("ns"))
+     * shape: (1, 2)
+     * ┌─────┬─────────┐
+     * │ dur │ ns      │
+     * ├─────┼─────────┤
+     * │ 1   │ 1000000 │
+     * └─────┴─────────┘
+     */
     total_nanoseconds(): any;
+    /**
+     * Converts Duration to floating point seconds.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ dur: [1000] })
+     * >>> df.with_columns($df.col("dur").dt.total_seconds().alias("secs"))
+     * shape: (1, 2)
+     * ┌──────┬──────┐
+     * │ dur  │ secs │
+     * ├──────┼──────┤
+     * │ 1000 │ 1    │
+     * └──────┴──────┘
+     */
     total_seconds(): any;
+    /**
+     * Returns the UTC offset of a timezone for a given Datetime value.
+     * Supports returning the total offset, the standard (base) offset, or just the
+     * daylight saving time component, in multiple output formats.
+     * @param timeZone Optional IANA timezone identifier. Defaults to the system local timezone.
+     * @param options Output configuration: `type` selects which offset component to return
+     *   (`"total"` | `"standardTime"` | `"daylightSavingTime"`), and `format` controls the
+     *   output unit (`"milliseconds"` | `"minutes"` | `"hours"` | `"iso"` | `"basic"`).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.utc_offset("UTC").alias("offset"))
+     * shape: (1, 2)
+     * ┌────────────┬────────┐
+     * │ d          │ offset │
+     * ├────────────┼────────┤
+     * │ 2026-05-20 │ 0      │
+     * └────────────┴────────┘
+     */
+    utc_offset(timeZone?: string, options?: UtcOffsetOptions): any;
+    /**
+     * Extracts ISO week index. Alias for iso_week.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.week().alias("week"))
+     * shape: (1, 2)
+     * ┌────────────┬──────┐
+     * │ d          │ week │
+     * ├────────────┼──────┤
+     * │ 2026-05-20 │ 21   │
+     * └────────────┴──────┘
+     */
     week(): any;
-    weekday(): any;
-    year(): any;
+    /**
+     * Extracts weekday component (1=Monday, 7=Sunday).
+     * @param timeZone Optional IANA timezone identifier. Defaults to UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-18"] })
+     * >>> df.with_columns($df.col("d").dt.weekday().alias("wd"))
+     * shape: (1, 2)
+     * ┌────────────┬────┐
+     * │ d          │ wd │
+     * ├────────────┼────┤
+     * │ 2026-05-18 │ 1  │
+     * └────────────┴────┘
+     */
+    weekday(timeZone?: string): any;
+    /**
+     * Extracts the year component from a Datetime column.
+     * @param timeZone Optional IANA timezone identifier. Defaults to UTC.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ d: ["2026-05-20"] })
+     * >>> df.with_columns($df.col("d").dt.year().alias("yr"))
+     * shape: (1, 2)
+     * ┌────────────┬──────┐
+     * │ d          │ yr   │
+     * ├────────────┼──────┤
+     * │ 2026-05-20 │ 2026 │
+     * └────────────┴──────┘
+     */
+    year(timeZone?: string): any;
 }
 export declare class TemporalExpr extends ExprBase {
+    /**
+     * Datetime namespace accessor for date, time, and duration operations.
+     * @namespace $df.col
+     * @category ColumnExpression
+     * @syntax $df.col(<column_name>).dt
+     * @returns DateTimeExprNamespace
+     * @example
+     * >>> df.select($df.col("date").dt.year())
+     */
     get dt(): DateTimeExprNamespace;
 }