Date-Time Operators

Date and time operators for the JSON Expression Operators library. This package provides operators for evaluating date and time-based expressions, powered by luxon.

Installation

npm install @jexop/date-time
# or
pnpm add @jexop/date-time

Basic Usage

First, import the dateTimeOperators and add them to the registry:

import { evaluate, registry } from '@jexop/core';
import { dateTimeOperators } from '@jexop/date-time';

// register date-time operators
registry.add(dateTimeOperators);

Now you can use date and time operators in your expressions:

const expression = {
  op: 'age',
  timestamp: '2024-01-15',
};

const result = evaluate(expression);
// result will be a Duration representing the time elapsed since 2024-01-15

Operators

The @jexop/date-time package provides date and time-related operators. These operators allow you to work with timestamps, calculate durations, and compare dates relative to the current time.

For a complete list of operators and their usage, see src/README.md.

More Information

For more information about JSON Expression Operators and other operator packages, visit the @jexop/core package.

Additional operator packages:

• @jexop/color: Color manipulation operators powered by chroma-js.

Date-Time Operators

Available Operators

now

Returns the current date and time in UTC.

| Property | Description | | -------- | ----------- | | (none) | No parameters |

Example:

{
  "op": "now"
}

age

Calculates the duration from a given timestamp to now.

| Property | Description | | ----------- | ---------------------------------------------- | | timestamp | Date/time value (string, number, or DateTime) |

Example:

{
  "op": "age",
  "timestamp": "2024-01-15T10:30:00"
}

start-of & end-of

Returns the start or end of a time period relative to now.

| Property | Description | | -------- | ------------------------------------------------------- | | unit | Time unit: hour, day, week, month, or year |

Example:

{
  "op": "start-of",
  "unit": "day"
}

Age Comparison Operators

Compare a timestamp against a relative time offset from now.

before-past

Check if a timestamp is before a duration in the past.

| Property | Description | | ----------- | ---------------------------------------------- | | timestamp | Date/time value (string, number, or DateTime) | | duration | Duration value (string, number, or object) |

after-past

Check if a timestamp is after a duration in the past.

| Property | Description | | ----------- | ---------------------------------------------- | | timestamp | Date/time value (string, number, or DateTime) | | duration | Duration value (string, number, or object) |

before-future

Check if a timestamp is before a duration in the future.

| Property | Description | | ----------- | ---------------------------------------------- | | timestamp | Date/time value (string, number, or DateTime) | | duration | Duration value (string, number, or object) |

after-future

Check if a timestamp is after a duration in the future.

| Property | Description | | ----------- | ---------------------------------------------- | | timestamp | Date/time value (string, number, or DateTime) | | duration | Duration value (string, number, or object) |

Example:

{
  "op": "before-past",
  "timestamp": "2024-06-15",
  "duration": "30 days"
}

to-duration

Converts a value to a Duration object.

| Property | Description | | -------- | --------------------------------------- | | (value) | Value to convert to Duration (string or object) |

Example:

{
  "op": "to-duration",
  "value": "2 weeks"
}