CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jsonata

JSON query and transformation language for extracting, filtering, and transforming JSON data

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

datetime-functions.mddocs/

Date/Time Functions

Functions for working with timestamps, date formatting, and time calculations.

Capabilities

Current Time Functions

Now Function

Returns the current timestamp, optionally formatted according to a picture string.

/**
 * Get current timestamp
 * @param picture - Optional picture string for formatting
 * @param timezone - Optional timezone specification
 * @returns Current timestamp as string (formatted) or milliseconds
 */
function $now(picture, timezone);

Usage Examples:

// Get current timestamp in ISO format
const current = await jsonata('$now()').evaluate({}); // "2023-10-15T14:30:25.123Z"

// Format current time
const formatted = await jsonata('$now("[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]")').evaluate({});
// "2023-10-15 14:30:25"

// With timezone
const utc = await jsonata('$now("[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "+0000")').evaluate({});
const est = await jsonata('$now("[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "-0500")').evaluate({});

// Custom formats
const readable = await jsonata('$now("[MNn] [D1o], [Y]")').evaluate({}); // "October 15th, 2023"
const time = await jsonata('$now("[h]:[m01] [PN]")').evaluate({}); // "2:30 PM"

Millis Function

Returns the current time in milliseconds since the Unix epoch.

/**
 * Get current time in milliseconds
 * @returns Current time as milliseconds since epoch
 */
function $millis();

Usage Examples:

const timestamp = await jsonata('$millis()').evaluate({}); // 1697374225123

// Calculate elapsed time
const data = { startTime: 1697374200000 };
const elapsed = await jsonata('$millis() - startTime').evaluate(data); // Time difference in ms

// Generate unique IDs with timestamp
const uniqueId = await jsonata('"user_" & $string($millis())').evaluate({}); // "user_1697374225123"

Time Conversion Functions

To Millis Function

Converts a timestamp string to milliseconds since the Unix epoch.

/**
 * Convert timestamp to milliseconds
 * @param timestamp - ISO 8601 timestamp string or custom format
 * @param picture - Optional picture string for parsing custom formats
 * @returns Milliseconds since Unix epoch
 */
function $toMillis(timestamp, picture);

Usage Examples:

// Parse ISO 8601 timestamps
const iso = await jsonata('$toMillis("2023-10-15T14:30:25.123Z")').evaluate({}); // 1697374225123
const date = await jsonata('$toMillis("2023-10-15")').evaluate({}); // 1697328000000

// Parse custom formats
const custom = await jsonata('$toMillis("15/10/2023 14:30:25", "[D01]/[M01]/[Y0001] [H01]:[m01]:[s01]")').evaluate({});

// Process array of timestamps
const data = {
  events: [
    { name: "Event 1", time: "2023-10-15T10:00:00Z" },
    { name: "Event 2", time: "2023-10-15T14:30:00Z" }
  ]
};
const withMillis = await jsonata('events.{"name": name, "timestamp": $toMillis(time)}').evaluate(data);

// Calculate time differences
const start = "2023-10-15T10:00:00Z";
const end = "2023-10-15T14:30:00Z";
const duration = await jsonata('$toMillis(end) - $toMillis(start)').evaluate({ start, end }); // Duration in ms

From Millis Function

Converts milliseconds since the Unix epoch to a formatted timestamp string.

/**
 * Convert milliseconds to formatted timestamp
 * @param millis - Milliseconds since Unix epoch
 * @param picture - Optional picture string for formatting
 * @param timezone - Optional timezone specification
 * @returns Formatted timestamp string
 */
function $fromMillis(millis, picture, timezone);

Usage Examples:

// Convert to ISO format (default)
const iso = await jsonata('$fromMillis(1697374225123)').evaluate({}); // "2023-10-15T14:30:25.123Z"

// Custom formatting
const readable = await jsonata('$fromMillis(1697374225123, "[MNn] [D1o], [Y] at [h]:[m01] [PN]")').evaluate({});
// "October 15th, 2023 at 2:30 PM"

// Date only
const dateOnly = await jsonata('$fromMillis(1697374225123, "[Y0001]-[M01]-[D01]")').evaluate({}); // "2023-10-15"

// Time only
const timeOnly = await jsonata('$fromMillis(1697374225123, "[H01]:[m01]:[s01]")').evaluate({}); // "14:30:25"

// With timezone conversion
const utc = await jsonata('$fromMillis(1697374225123, "[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "+0000")').evaluate({});
const est = await jsonata('$fromMillis(1697374225123, "[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "-0500")').evaluate({});

// Format array of timestamps
const data = { 
  events: [
    { name: "Start", timestamp: 1697374200000 },
    { name: "End", timestamp: 1697374800000 }
  ]
};
const formatted = await jsonata('events.{"name": name, "time": $fromMillis(timestamp, "[h]:[m01] [PN]")}').evaluate(data);

Picture String Format

JSONata uses picture strings to specify date/time formatting patterns:

Date Components

  • [Y] - Year (variable width)
  • [Y0001] - Year (4 digits, zero-padded)
  • [M] - Month number (variable width)
  • [M01] - Month number (2 digits, zero-padded)
  • [MNn] - Month name (January, February, etc.)
  • [MN] - Month abbreviation (Jan, Feb, etc.)
  • [D] - Day of month (variable width)
  • [D01] - Day of month (2 digits, zero-padded)
  • [D1o] - Day with ordinal suffix (1st, 2nd, 3rd, etc.)
  • [FNn] - Day of week name (Monday, Tuesday, etc.)
  • [FN] - Day of week abbreviation (Mon, Tue, etc.)

Time Components

  • [H] - Hour (24-hour format, variable width)
  • [H01] - Hour (24-hour format, 2 digits, zero-padded)
  • [h] - Hour (12-hour format, variable width)
  • [h01] - Hour (12-hour format, 2 digits, zero-padded)
  • [m] - Minutes (variable width)
  • [m01] - Minutes (2 digits, zero-padded)
  • [s] - Seconds (variable width)
  • [s01] - Seconds (2 digits, zero-padded)
  • [f] - Fractional seconds (variable width)
  • [f001] - Fractional seconds (3 digits, zero-padded)
  • [PN] - AM/PM indicator
  • [pn] - am/pm indicator (lowercase)

Timezone Components

  • [Z] - Timezone offset from UTC (+0100, -0500, etc.)
  • [z] - Timezone abbreviation (EST, PST, etc.)

Example Usage:

const data = { timestamp: 1697374225123 }; // 2023-10-15T14:30:25.123Z

// Various formatting examples
const formats = {
  iso: await jsonata('$fromMillis(timestamp)').evaluate(data),
  // "2023-10-15T14:30:25.123Z"
  
  readable: await jsonata('$fromMillis(timestamp, "[MNn] [D1o], [Y]")').evaluate(data),
  // "October 15th, 2023"
  
  withTime: await jsonata('$fromMillis(timestamp, "[MNn] [D1o], [Y] at [h]:[m01] [PN]")').evaluate(data),
  // "October 15th, 2023 at 2:30 PM"
  
  technical: await jsonata('$fromMillis(timestamp, "[Y0001]-[M01]-[D01] [H01]:[m01]:[s01].[f001]")').evaluate(data),
  // "2023-10-15 14:30:25.123"
  
  logFormat: await jsonata('$fromMillis(timestamp, "[Y0001]/[M01]/[D01] [H01]:[m01]:[s01]")').evaluate(data),
  // "2023/10/15 14:30:25"
  
  dayOfWeek: await jsonata('$fromMillis(timestamp, "[FNn], [MNn] [D1o]")').evaluate(data)
  // "Sunday, October 15th"
};

Time Calculations

JSONata's date/time functions work well with arithmetic operations for time calculations:

// Add/subtract time
const data = { baseTime: "2023-10-15T10:00:00Z" };

// Add 2 hours (2 * 60 * 60 * 1000 ms)
const later = await jsonata('$fromMillis($toMillis(baseTime) + 7200000)').evaluate(data);

// Subtract 30 minutes
const earlier = await jsonata('$fromMillis($toMillis(baseTime) - 1800000)').evaluate(data);

// Calculate duration between timestamps
const start = "2023-10-15T10:00:00Z";
const end = "2023-10-15T14:30:00Z";
const durationMs = await jsonata('$toMillis(end) - $toMillis(start)').evaluate({ start, end });
const durationHours = durationMs / (1000 * 60 * 60); // Convert to hours

// Find events within time window
const events = {
  events: [
    { name: "Meeting", time: "2023-10-15T09:00:00Z" },
    { name: "Lunch", time: "2023-10-15T12:00:00Z" },
    { name: "Call", time: "2023-10-15T15:00:00Z" }
  ],
  windowStart: "2023-10-15T10:00:00Z",
  windowEnd: "2023-10-15T14:00:00Z"
};

const inWindow = await jsonata(`
  events[$toMillis(time) >= $toMillis(windowStart) and $toMillis(time) <= $toMillis(windowEnd)]
`).evaluate(events);

Integer Formatting Functions

Format Integer Function

Formats a number as a string using a picture string for integer representation.

/**
 * Format integer using picture string
 * @param number - Number to format
 * @param picture - Picture string for formatting
 * @returns Formatted number string
 */
function $formatInteger(number, picture);

Usage Examples:

// Basic number formatting
const num = await jsonata('$formatInteger(123, "000")').evaluate({}); // "123"
const padded = await jsonata('$formatInteger(42, "0000")').evaluate({}); // "0042"

// Roman numerals
const roman = await jsonata('$formatInteger(1984, "I")').evaluate({}); // "MCMLXXXIV"
const romanLower = await jsonata('$formatInteger(42, "i")').evaluate({}); // "xlii"

// Ordinal numbers
const ordinal = await jsonata('$formatInteger(21, "1o")').evaluate({}); // "21st"
const ordinalWord = await jsonata('$formatInteger(3, "Ww")').evaluate({}); // "Third"

Parse Integer Function

Parses a formatted integer string back to a number using a picture string.

/**
 * Parse formatted integer string
 * @param string - Formatted integer string
 * @param picture - Picture string used for formatting
 * @returns Parsed number
 */
function $parseInteger(string, picture);

Usage Examples:

// Parse padded numbers
const parsed = await jsonata('$parseInteger("0042", "0000")').evaluate({}); // 42

// Parse Roman numerals
const fromRoman = await jsonata('$parseInteger("MCMLXXXIV", "I")').evaluate({}); // 1984
const fromRomanLower = await jsonata('$parseInteger("xlii", "i")').evaluate({}); // 42

// Parse ordinal numbers
const fromOrdinal = await jsonata('$parseInteger("21st", "1o")').evaluate({}); // 21

docs

data-manipulation.md

datetime-functions.md

expressions.md

index.md

numeric-functions.md

string-functions.md

utility-functions.md

tile.json