node-red-contrib-jalali

Table of Contents

• Overview
• Requirements
• Installation
• Quick Start
• Configuration
• Input and Output
• Formatting
• Error Handling
• License

Overview

A Node-RED node that converts the current time or a message timestamp into Jalali (Persian/Shamsi) calendar date and time.

Built with JavaScript's Intl.DateTimeFormat, with no external dependencies.

Features

• Current time, ISO date strings, and Unix timestamps.
• Configurable time zone and output format.
• Latin or Persian digits.
• Formatted string or structured object output.
• Configurable error handling.

Requirements

• Node.js 22 or later, with Persian calendar support in Intl.
• A working Node-RED installation.

Installation

Run the following command in your Node-RED user directory, usually ~/.node-red:

cd ~/.node-red
npm install node-red-contrib-jalali

Restart Node-RED after installation.

For Docker installations using /data as the user directory:

docker exec -it <container_name> sh -c \
  'cd /data && npm install node-red-contrib-jalali'

docker restart <container_name>

Quick Start

1. Add Inject, jalali, and Debug nodes.
2. Connect them:

Inject → jalali → Debug

3. Keep the Jalali node's default settings.
4. Configure Debug to display msg.jalali or the complete message.
5. Click Deploy, then trigger Inject.

The node writes the current Jalali date and time to msg.jalali, using the Asia/Tehran time zone.

In Current time mode, each incoming message triggers a conversion. Its timestamp fields are ignored.

Configuration

| Setting | Description | Default | |---|---|---| | Date source | Current time or a message field | Current time | | Input field | Message property containing the date | payload.timestamp | | Input type | ISO 8601, Unix milliseconds, or Unix seconds | ISO 8601 | | Time zone | Display time zone | Asia/Tehran | | Custom format | Custom date/time format | YYYY/MM/DD HH:mm:ss | | Digits | Latin (latn) or Persian (arabext) | Latin | | Output mode | Structured object or formatted string | Structured object | | Output field | Message property to receive the result | jalali | | On error | Stop and report, or pass through unchanged | Stop |

Enter message property paths without the msg. prefix, for example:

payload.timestamp

or:

jalali

Input field and Input type apply only when Date source is set to Message field.

Input and Output

Convert a Message Date

Set:

• Date source: Message field
• Input field: payload.timestamp
• Input type: ISO 8601

Example Input

{
  "payload": {
    "timestamp": "2025-03-21T00:00:00Z"
  }
}

With default formatting, time zone, digits, and output settings, msg.jalali contains:

{
  "date": "1404/01/01",
  "time": "03:30:00",
  "datetime": "1404/01/01 03:30:00",
  "formatted": "1404/01/01 03:30:00",
  "timezone": "Asia/Tehran",
  "calendar": "persian",
  "timestamp": 1742515200000
}

With Output mode set to Formatted string, msg.jalali contains:

1404/01/01 03:30:00

Supported Inputs

| Input type | Example | |---|---| | ISO 8601 | "2025-03-21T00:00:00Z" | | ISO 8601 with offset | "2025-03-21T03:30:00+03:30" | | Unix seconds | 1742515200 | | Unix milliseconds | 1742515200000 |

ISO input requires:

YYYY-MM-DDTHH:mm:ss

with optional fractional seconds of 1–3 digits, and either Z or an explicit ±HH:mm offset.

Unix input accepts numbers or decimal numeric strings. Select seconds or milliseconds explicitly; units are not auto-detected.

For nested MQTT payload fields, decode the payload into an object first using MQTT JSON output or a JSON node.

Output Behavior

• The selected output field is overwritten if it already exists; other message properties are preserved.
• Use a separate output field to keep the original input date.
• The time zone affects the displayed date and time, not the underlying timestamp.
• timestamp always remains a numeric Unix timestamp in milliseconds, even with Persian digits enabled.
• The custom format controls string output and the object's formatted datetime.

Formatting

| Token | Meaning | |---|---| | YYYY | Jalali year | | MM | Month | | DD | Day | | HH | Hour, 24-hour clock | | mm | Minute | | ss | Second |

Examples

YYYY/MM/DD

YYYY-MM-DD HH:mm

[Date:] YYYY/MM/DD [Time:] HH:mm:ss

Wrap literal text in square brackets to prevent token replacement.

Selecting Persian digits converts generated date/time digits to:

۰۱۲۳۴۵۶۷۸۹

Literal text remains unchanged.

Error Handling

Stop

Does not forward the message and reports the error to Node-RED.

Use a Catch node to handle it.

Pass Through

Forwards the original message unchanged and logs a warning.

Missing input fields, invalid dates, unsupported time zones, and invalid configuration are handled using the selected error mode.

License

Apache-2.0 — Farzin Bidokhti.