duration

Commentary

added in 1.7.0

Constructs a quatity of time, expressed in hours, days, minutes, seconds, and milliseconds. ¹ The output of this function is a UNIX millisecond value intended to be used with other date/time functions. ²

Use this function when you want to name a span of time, like 14 days, instead of hardcoding its opaque millisecond value equivelent (1209600000).

Note that this function doesn't perform calendar method. For example, subtracting 900 days from now won't take into account things like leap years. It's intended purpose is to specify instances of wallclock time.

---

Examples

Passing in parameters

Supply any time units, with days being the largest and milliseconds being the smallest. Any unsupplied units default to 0.

{
    "_gen": "duration",
    "days": 4,
    "hours": 3,
    "minutes": 32,
    "seconds": 45,
    "milliseconds": 250
}

[
    {
        "headers": null,
        "topic": "sandbox",
        "value": 358365000,
        "key": null
    }
]

Performing time math

duration works with other functions that expect Unix millisecond values, like formatDateTime.

{
    "_gen": "formatDateTime",
    "ms": {
        "_gen": "math",
        "expr": "now - offset",
        "names": {
            "now": {
                "_gen": "now"
            },
            "offset": {
                "_gen": "duration",
                "days": 7
            }
        }
    }
}

[
    {
        "headers": null,
        "topic": "sandbox",
        "value": "2024-04-18T13:28:47.263-07:00",
        "key": null
    }
]

---

Specification

JSON schema

{
    "type": "object",
    "properties": {
        "days": {
            "oneOf": [
                {
                    "type": "number"
                },
                {
                    "type": "object",
                    "properties": {
                        "_gen": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "_gen"
                    ]
                }
            ]
        },
        "hours": {
            "oneOf": [
                {
                    "type": "number"
                },
                {
                    "type": "object",
                    "properties": {
                        "_gen": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "_gen"
                    ]
                }
            ]
        },
        "minutes": {
            "oneOf": [
                {
                    "type": "number"
                },
                {
                    "type": "object",
                    "properties": {
                        "_gen": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "_gen"
                    ]
                }
            ]
        },
        "seconds": {
            "oneOf": [
                {
                    "type": "number"
                },
                {
                    "type": "object",
                    "properties": {
                        "_gen": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "_gen"
                    ]
                }
            ]
        },
        "ms": {
            "oneOf": [
                {
                    "type": "number"
                },
                {
                    "type": "object",
                    "properties": {
                        "_gen": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "_gen"
                    ]
                }
            ]
        }
    }
}