Date/Time Functions¶
Functions for working with dates and times: parsing, formatting, arithmetic, and timezone handling.
Summary¶
| Function | Signature | Description |
|---|---|---|
business_days_between |
number, number -> number |
Count business days (weekdays) between two timestamps |
date_add |
number, number, string -> number |
Add time to timestamp |
date_diff |
number, number, string -> number |
Difference between timestamps |
duration_since |
number\|string -> object |
Get detailed duration object from timestamp to now |
end_of_day |
number\|string -> string |
Get ISO 8601 string for end of day (23:59:59) |
epoch_ms |
-> number |
Current Unix timestamp in milliseconds (alias for now_ms) |
format_date |
number, string -> string |
Format timestamp to string |
from_epoch |
number -> string |
Convert Unix timestamp (seconds) to ISO 8601 string |
from_epoch_ms |
number -> string |
Convert Unix timestamp (milliseconds) to ISO 8601 string |
is_after |
number\|string, number\|string -> boolean |
Check if first date is after second date (accepts timestamps or date strings) |
is_before |
number\|string, number\|string -> boolean |
Check if first date is before second date (accepts timestamps or date strings) |
is_between |
number\|string, number\|string, number\|string -> boolean |
Check if date is between start and end (inclusive, accepts timestamps or date strings) |
is_same_day |
number\|string, number\|string -> boolean |
Check if two timestamps/dates are on the same day |
is_weekday |
number -> boolean |
Check if timestamp falls on weekday (Monday-Friday) |
is_weekend |
number -> boolean |
Check if timestamp falls on weekend (Saturday or Sunday) |
parse_date |
string, string? -> number |
Parse date string to timestamp |
quarter |
number -> number |
Get quarter of year (1-4) from timestamp |
relative_time |
number -> string |
Human-readable relative time from timestamp |
start_of_day |
number\|string -> string |
Get ISO 8601 string for start of day (00:00:00) |
start_of_month |
number\|string -> string |
Get ISO 8601 string for start of month |
start_of_week |
number\|string -> string |
Get ISO 8601 string for start of week (Monday 00:00:00) |
start_of_year |
number\|string -> string |
Get ISO 8601 string for start of year |
time_ago |
number\|string -> string |
Human-readable time since date (accepts timestamps or date strings) |
timezone_convert |
string, string, string -> string |
Convert timestamp between timezones (IANA timezone names) |
to_epoch |
number\|string -> number |
Convert date string or timestamp to Unix timestamp (seconds) |
to_epoch_ms |
number\|string -> number |
Convert date string or timestamp to Unix timestamp (milliseconds) |
Functions¶
business_days_between¶
Count business days (weekdays) between two timestamps
Signature: number, number -> number
Examples:
# Count weekdays
business_days_between(`1704067200`, `1705276800`) -> 10
# Between two timestamps
business_days_between(start_ts, end_ts) -> count
# One week = 5 days
business_days_between(`0`, `604800`) -> 5
# Same day
business_days_between(`0`, `0`) -> 0
CLI Usage:
date_add¶
Add time to timestamp
Signature: number, number, string -> number
Examples:
# Add 1 day
date_add(`0`, `1`, 'days') -> 86400
# Add 2 hours
date_add(`0`, `2`, 'hours') -> 7200
# Add 1 week
date_add(timestamp, `7`, 'days') -> next week
# Add 30 minutes
date_add(`0`, `30`, 'minutes') -> 1800
CLI Usage:
date_diff¶
Difference between timestamps
Signature: number, number, string -> number
Examples:
# Diff in days
date_diff(`86400`, `0`, 'days') -> 1
# Diff in hours
date_diff(`7200`, `0`, 'hours') -> 2
# Diff in minutes
date_diff(end_ts, start_ts, 'minutes') -> minutes
# Diff in weeks
date_diff(`604800`, `0`, 'weeks') -> 1
CLI Usage:
duration_since¶
Get detailed duration object from timestamp to now
Signature: number|string -> object
Examples:
# From timestamp
duration_since(`1702396800`) -> {days: 1, hours: 0, ...}
# From date string
duration_since('2023-01-01') -> {days: N, ...}
# Time since creation
duration_since(created_at) -> elapsed time
# One hour ago
duration_since(now() - 3600) -> {hours: 1, ...}
CLI Usage:
end_of_day¶
Get ISO 8601 string for end of day (23:59:59)
Signature: number|string -> string
Examples:
# From ISO string
end_of_day('2023-12-13T15:30:00Z') -> \"2023-12-13T23:59:59Z\"
# From timestamp
end_of_day(`1702483200`) -> end of that day
# From date only
end_of_day('2024-01-01') -> last second of day
# End of today
end_of_day(now()) -> today end
CLI Usage:
epoch_ms¶
Current Unix timestamp in milliseconds (alias for now_ms)
Signature: -> number
Examples:
# Current time in ms
epoch_ms() -> 1702483200000
# Convert to seconds
epoch_ms() / `1000` -> seconds
# Calculate duration
epoch_ms() - start_ms -> elapsed
CLI Usage:
format_date¶
Format timestamp to string
Signature: number, string -> string
Examples:
# ISO date format
format_date(`1705276800`, '%Y-%m-%d') -> \"2024-01-15\"
# Long date format
format_date(ts, '%B %d, %Y') -> \"January 15, 2024\"
# Time only
format_date(ts, '%H:%M:%S') -> \"10:30:00\"
# Full ISO 8601
format_date(ts, '%Y-%m-%dT%H:%M:%SZ') -> ISO string
CLI Usage:
from_epoch¶
Convert Unix timestamp (seconds) to ISO 8601 string
Signature: number -> string
Examples:
# Convert seconds
from_epoch(`1702483200`) -> \"2023-12-13T16:00:00Z\"
# Unix epoch
from_epoch(`0`) -> \"1970-01-01T00:00:00Z\"
# Convert field
from_epoch(created_at) -> ISO string
# Current time
from_epoch(now()) -> current ISO
CLI Usage:
from_epoch_ms¶
Convert Unix timestamp (milliseconds) to ISO 8601 string
Signature: number -> string
Examples:
# From milliseconds
from_epoch_ms(`1702483200000`) -> \"2023-12-13T16:00:00Z\"
# Unix epoch
from_epoch_ms(`0`) -> \"1970-01-01T00:00:00Z\"
# JS timestamp
from_epoch_ms(js_timestamp) -> ISO
# Current time
from_epoch_ms(epoch_ms()) -> current
CLI Usage:
is_after¶
Check if first date is after second date (accepts timestamps or date strings)
Signature: number|string, number|string -> boolean
Examples:
# String comparison
is_after('2024-07-15', '2024-01-01') -> true
# Timestamp comparison
is_after(`1705276800`, `1704067200`) -> true
# Field comparison
is_after(end_date, start_date) -> true/false
# Same date
is_after('2024-01-01', '2024-01-01') -> false
CLI Usage:
is_before¶
Check if first date is before second date (accepts timestamps or date strings)
Signature: number|string, number|string -> boolean
Examples:
# String comparison
is_before('2024-01-01', '2024-07-15') -> true
# Timestamp comparison
is_before(`1704067200`, `1705276800`) -> true
# Field comparison
is_before(start_date, end_date) -> true/false
# Same date
is_before('2024-01-01', '2024-01-01') -> false
CLI Usage:
is_between¶
Check if date is between start and end (inclusive, accepts timestamps or date strings)
Signature: number|string, number|string, number|string -> boolean
Examples:
# Within range
is_between('2024-06-15', '2024-01-01', '2024-12-31') -> true
# Before range
is_between('2023-06-15', '2024-01-01', '2024-12-31') -> false
# Check event date
is_between(event_date, start, end) -> true/false
# Inclusive start
is_between('2024-01-01', '2024-01-01', '2024-12-31') -> true
CLI Usage:
is_same_day¶
Check if two timestamps/dates are on the same day
Signature: number|string, number|string -> boolean
Examples:
# Same day, different time
is_same_day('2023-12-13T10:00:00Z', '2023-12-13T23:00:00Z') -> true
# Different days
is_same_day('2023-12-13', '2023-12-14') -> false
# Compare fields
is_same_day(created_at, updated_at) -> true/false
# Today check
is_same_day(now(), event_time) -> true/false
CLI Usage:
is_weekday¶
Check if timestamp falls on weekday (Monday-Friday)
Signature: number -> boolean
Examples:
# Monday is weekday
is_weekday(`1705276800`) -> true
# Check current day
is_weekday(now()) -> true/false
# Check event day
is_weekday(event_timestamp) -> true/false
# Saturday is not weekday
is_weekday(`1705104000`) -> false
CLI Usage:
is_weekend¶
Check if timestamp falls on weekend (Saturday or Sunday)
Signature: number -> boolean
Examples:
# Saturday is weekend
is_weekend(`1705104000`) -> true
# Check current day
is_weekend(now()) -> true/false
# Monday is not weekend
is_weekend(`1705276800`) -> false
# Check event day
is_weekend(event_timestamp) -> true/false
CLI Usage:
parse_date¶
Parse date string to timestamp
Signature: string, string? -> number
Examples:
# ISO date format
parse_date('2024-01-15', '%Y-%m-%d') -> 1705276800
# US date format
parse_date('01/15/2024', '%m/%d/%Y') -> timestamp
# Named month
parse_date('15-Jan-2024', '%d-%b-%Y') -> timestamp
# With time
parse_date('2024-01-15T10:30:00', '%Y-%m-%dT%H:%M:%S') -> timestamp
CLI Usage:
quarter¶
Get quarter of year (1-4) from timestamp
Signature: number -> number
Examples:
# April is Q2
quarter(`1713139200`) -> 2
# January is Q1
quarter(`1704067200`) -> 1
# July is Q3
quarter(`1719792000`) -> 3
# November is Q4
quarter(`1730419200`) -> 4
CLI Usage:
relative_time¶
Human-readable relative time from timestamp
Signature: number -> string
Examples:
# One hour ago
relative_time(now() - 3600) -> \"1 hour ago\"
# One minute ago
relative_time(now() - 60) -> \"1 minute ago\"
# One day ago
relative_time(now() - 86400) -> \"1 day ago\"
# From field
relative_time(created_at) -> human readable
CLI Usage:
start_of_day¶
Get ISO 8601 string for start of day (00:00:00)
Signature: number|string -> string
Examples:
# From ISO string
start_of_day('2023-12-13T15:30:00Z') -> \"2023-12-13T00:00:00Z\"
# From timestamp
start_of_day(`1702483200`) -> start of that day
# Today start
start_of_day(now()) -> today midnight
# From date only
start_of_day('2024-01-15') -> midnight
CLI Usage:
start_of_month¶
Get ISO 8601 string for start of month
Signature: number|string -> string
Examples:
# From ISO string
start_of_month('2023-12-13T15:30:00Z') -> \"2023-12-01T00:00:00Z\"
# Current month start
start_of_month(now()) -> first of month
# From timestamp
start_of_month(`1702483200`) -> month start
# March start
start_of_month('2024-03-15') -> \"2024-03-01T00:00:00Z\"
CLI Usage:
start_of_week¶
Get ISO 8601 string for start of week (Monday 00:00:00)
Signature: number|string -> string
Examples:
# Wednesday to Monday
start_of_week('2023-12-13T15:30:00Z') -> \"2023-12-11T00:00:00Z\"
# Current week start
start_of_week(now()) -> this Monday
# From timestamp
start_of_week(`1702483200`) -> week start
# Monday stays Monday
start_of_week('2024-01-15') -> \"2024-01-15T00:00:00Z\"
CLI Usage:
start_of_year¶
Get ISO 8601 string for start of year
Signature: number|string -> string
Examples:
# From ISO string
start_of_year('2023-12-13T15:30:00Z') -> \"2023-01-01T00:00:00Z\"
# Current year start
start_of_year(now()) -> Jan 1st
# From timestamp
start_of_year(`1702483200`) -> year start
# Mid-year to Jan 1
start_of_year('2024-06-15') -> \"2024-01-01T00:00:00Z\"
CLI Usage:
time_ago¶
Human-readable time since date (accepts timestamps or date strings)
Signature: number|string -> string
Examples:
# From date string
time_ago('2020-01-01') -> \"4 years ago\"
# One hour ago
time_ago(now() - 3600) -> \"1 hour ago\"
# From field
time_ago(created_at) -> human readable
# Months ago
time_ago('2023-12-01') -> \"X months ago\"
CLI Usage:
timezone_convert¶
Convert timestamp between timezones (IANA timezone names)
Signature: string, string, string -> string
Examples:
# NY to London
timezone_convert('2024-01-15T10:00:00', 'America/New_York', 'Europe/London') -> \"2024-01-15T15:00:00\"
# UTC to Pacific
timezone_convert(time, 'UTC', 'America/Los_Angeles') -> PST time
# Tokyo to UTC
timezone_convert(time, 'Asia/Tokyo', 'UTC') -> UTC time
# Paris to Chicago
timezone_convert(time, 'Europe/Paris', 'America/Chicago') -> CST time
CLI Usage:
echo '{}' | jpx 'timezone_convert(`"2024-01-15T10:00:00"`, `"America/New_York"`, `"Europe/London"`)'
to_epoch¶
Convert date string or timestamp to Unix timestamp (seconds)
Signature: number|string -> number
Examples:
# From ISO string
to_epoch('2023-12-13T16:00:00Z') -> 1702483200
# From date only
to_epoch('2024-01-01') -> timestamp
# Convert field
to_epoch(date_field) -> seconds
# Unix epoch
to_epoch('1970-01-01T00:00:00Z') -> 0
CLI Usage:
to_epoch_ms¶
Convert date string or timestamp to Unix timestamp (milliseconds)
Signature: number|string -> number
Examples:
# From ISO string
to_epoch_ms('2023-12-13T16:00:00Z') -> 1702483200000
# From date only
to_epoch_ms('2024-01-01') -> timestamp_ms
# Convert field
to_epoch_ms(date_field) -> milliseconds
# Unix epoch
to_epoch_ms('1970-01-01T00:00:00Z') -> 0
CLI Usage: