@magmacomputing/tempo-plugin-dialects

The Dialects Plugin enables Tempo to seamlessly format and parse dates using established external formatting standards, including Unicode LDML / UTS #35 (Luxon, date-fns), POSIX strftime (C, Python, Linux), Moment.js / Day.js, and Oracle / SQL TO_CHAR (PostgreSQL, Snowflake, Redshift).

It provides transparent drop-in compatibility shims, multi-candidate fallback parsing, an automated .explain() ingestion engine, .export() for emitting dialect models from Tempo tokens, and .convert() for direct bidirectional transpilation between external ecosystems.

---

Key Features

• Drop-In Formatter Compatibility: t.toFormat(mask) (Luxon), t.dialects.strftime(mask) (POSIX), t.dialects.oracle(mask) (SQL), t.dialects.moment(mask) (Moment/Day.js), and more.
• Multi-Candidate Fallback Parsing: Tempo.fromFormats(input, masks[]) tries candidates in order and returns on first successful match.
• Automated Dialect Ingestion: .explain(mask) translates any legacy format mask into equivalent native Tempo {token} syntax with reasoning metadata.
• Bidirectional Transpilation: .convert(mask, from, to) converts format strings directly between any two supported dialects.
• 9 Supported Dialects: LDML (Luxon/date-fns), strftime (POSIX/C/Python), Moment/Day.js, Oracle/SQL, PHP, Go, MySQL, .NET, and Spreadsheet (Excel/Sheets).
• Lazy-Evaluated & Immutable: Zero overhead until invoked; Tempo.dialects is recursively frozen against tampering.

---

Installation

npm install @magmacomputing/tempo-plugin-dialects

---

Quickstart

Interactive Demo (@magmacomputing/tempo-plugin-dialects)

Open in Full REPL↗

// 🌐 External Dialect Formatting, Parsing & Transpilation
// Dynamic import of @magmacomputing/tempo-plugin-dialects
const { DialectsPlugin, DIALECT } = await import('@magmacomputing/tempo-plugin-dialects');
Tempo.use(DialectsPlugin);

const t = new Tempo('2026-10-24T15:30:45.123');

// 1. Format across external ecosystems
console.log('Luxon / LDML:', t.toFormat('dd LLL yyyy, HH:mm'));
console.log('POSIX strftime:', t.dialects.strftime('%Y-%m-%d %H:%M:%S'));
console.log('Oracle / SQL TO_CHAR:', t.dialects.oracle('YYYY-MM-DD HH24:MI:SS'));
console.log('.NET DateTime:', t.dialects.dotnet('yyyy-MM-dd HH:mm:ss.fff'));
console.log('MySQL DATE_FORMAT:', t.dialects.mysql('%Y-%m-%d %H:%i:%s'));
console.log('Excel / Sheets:', t.dialects.sheet('yyyy-mm-dd hh:mm:ss'));

// 2. Ingest & Explain legacy masks into native Tempo {token} syntax
const inspection = Tempo.dialects.explain('[Report for] MMMM Do, YYYY [at] hh:mm A', DIALECT.Moment);
console.log('Explained Moment -> Tempo IR:', inspection.pattern);

// 3. Export canonical Tempo templates to external dialect models
const sqlExport = Tempo.dialects.export('{yyyy}-{mm}-{dd} {hh}:{mi}:{ss}', DIALECT.Oracle);
console.log('Exported Tempo -> SQL TO_CHAR model:', sqlExport.pattern);
const sheetExport = Tempo.dialects.export('{yyyy}-{mm}-{dd} {hh}:{mi}:{ss}', DIALECT.Sheet);
console.log('Exported Tempo -> Spreadsheet mask:', sheetExport.pattern);

// 4. Universal Cross-Dialect Transpilation (.convert)
const posixToOracle = Tempo.dialects.convert('%Y-%m-%d %H:%M:%S', DIALECT.Strftime, DIALECT.Oracle);
console.log('Converted POSIX -> Oracle:', posixToOracle.pattern);

// 5. Multi-candidate fallback parser
const parsed = Tempo.fromFormats('24/10/2026 15:30', [
	'yyyy-MM-dd HH:mm',
	'dd/MM/yyyy HH:mm',
]);
console.log('Parsed multi-candidate ISO:', parsed.iso);

return `Transpiled POSIX to Oracle: ${posixToOracle.pattern}`;

Executes 100% in browser via native ESM sandbox

import { Tempo } from '@magmacomputing/tempo';
import { DialectsPlugin, DIALECT } from '@magmacomputing/tempo-plugin-dialects';

Tempo.use(DialectsPlugin);

const t = new Tempo('2026-10-24T15:30:45');

// Format using external dialect masks
console.log(t.format('yyyy-MM-dd HH:mm:ss', { dialect: DIALECT.Ldml })); // "2026-10-24 15:30:45"
console.log(t.format('%Y-%m-%d %H:%M:%S', { dialect: DIALECT.Strftime })); // "2026-10-24 15:30:45"
console.log(t.format('[Recorded on] MMMM Do YYYY', { dialect: DIALECT.Moment })); // "Recorded on October 24th 2026"

Auto-Installation (Side-Effect Import)

import { Tempo } from '@magmacomputing/tempo';
import '@magmacomputing/tempo-plugin-dialects/install';

const t = new Tempo('2026-10-24T15:30:45');
console.log(t.toFormat('dd LLL yyyy')); // "24 Oct 2026"

---

Supported Dialects

Dialect Identifier	Canonical Constant	Common Aliases	Format Example	Primary Ecosystems
'ldml'	DIALECT.Ldml	'luxon', 'datefns', 'cldr'	yyyy-MM-dd HH:mm:ss.SSS	Luxon, date-fns, CLDR, Unicode UTS #35
'strftime'	DIALECT.Strftime	'posix', 'c', 'python'	%Y-%m-%d %H:%M:%S	POSIX C, Python datetime, Linux Syslog
'moment'	DIALECT.Moment	'dayjs'	YYYY-MM-DD HH:mm:ss	Moment.js, Day.js
'oracle'	DIALECT.Oracle	'sql', 'postgres', 'postgresql', 'snowflake', 'redshift', 'to_char'	YYYY-MM-DD HH24:MI:SS	Oracle, PostgreSQL, Snowflake, AWS Redshift
'php'	DIALECT.Php	'laravel', 'wordpress'	Y-m-d H:i:s	PHP, Laravel, WordPress, Symfony
'go'	DIALECT.Go	'golang'	2006-01-02 15:04:05	Go (time.Format, time.Parse)
'mysql'	DIALECT.Mysql	'mariadb'	%Y-%m-%d %H:%i:%s	MySQL, MariaDB (DATE_FORMAT)
'dotnet'	DIALECT.DotNet	'csharp', '.net', 'c#'	yyyy-MM-dd HH:mm:ss.fff	.NET, C#, PowerShell (DateTime.ToString)
'sheet'	DIALECT.Sheet	'spreadsheet', 'excel', 'sheets'	yyyy-mm-dd hh:mm:ss AM/PM	Microsoft Excel, Google Sheets, LibreOffice Calc

TIP

Native Tempo Syntax is Optimal While the Dialects plugin provides seamless interoperability with legacy format masks, native Tempo braced syntax ({token}) remains the most performant, lightweight, and expressive choice. Native Tempo syntax runs in Core with zero plugin dependencies, and provides rich capabilities unavailable in external token systems—including custom Terms, dynamic dot namespaces ({geo.city}), localized modifiers ({dow:locale}, {hh:locale:raw}), and regional {intl.*} property interpolation.

---

API Reference

The Dialects plugin mounts cohesive static tools onto Tempo.dialects, instance utilities onto t.dialects, and attaches convenience shims directly onto Tempo:

API / Method	Target	Input	Returns	Description
t.toFormat(mask, options?)	Instance	Format mask string, options	string	Luxon Drop-In Formatter. Formats the instance using LDML (or explicit dialect).
t.dialects.ldml(mask)	Instance	Unicode LDML mask	string	Fast-path formatter for Unicode LDML / Luxon / date-fns masks.
t.dialects.strftime(mask)	Instance	POSIX strftime mask	string	Fast-path formatter for POSIX strftime specifiers (%Y, %m, %d, etc.).
t.dialects.oracle(mask)	Instance	Oracle / SQL mask	string	Fast-path formatter for Oracle / PostgreSQL / Snowflake format models (YYYY, HH24, MI, etc.).
t.dialects.sql(mask)	Instance	SQL / Oracle mask	string	Convenience alias for t.dialects.oracle(mask).
t.dialects.php(mask)	Instance	PHP date mask	string	Fast-path formatter for PHP date() specifiers (Y, m, d, H, i, s, etc.).
t.dialects.go(mask)	Instance	Go reference mask	string	Fast-path formatter for Go reference time layout (2006, 01, 02, 15, 04, 05).
t.dialects.mysql(mask)	Instance	MySQL format mask	string	Fast-path formatter for MySQL / MariaDB DATE_FORMAT specifiers (%Y, %m, %d, %H, %i, %s, etc.).
t.dialects.dotnet(mask)	Instance	.NET format mask	string	Fast-path formatter for .NET / C# DateTime.ToString custom format strings (yyyy, MM, dd, HH, mm, ss, fff, etc.).
t.dialects.sheet(mask)	Instance	Spreadsheet mask	string	Fast-path formatter for Excel / Google Sheets custom format strings (yyyy, mm, dd, hh, ss, AM/PM, etc.).
t.dialects.format(mask, dialect?)	Instance	Mask, dialect identifier	string	Generic dialect instance formatter with auto-detection for %, Go, SQL, MySQL, .NET, and Sheet specifiers.
t.dialects.explain(mask, dialectOrOptions?)	Instance	External format mask, dialect name or { dialect }	ExplainResult	Analyzes mask and returns equivalent native Tempo {token} pattern and metadata.
t.dialects.export(pattern, dialectOrOptions?)	Instance	Native Tempo pattern, target dialect name or { dialect }	ExportResult	Exports a native Tempo {token} pattern into an external dialect format model.
t.dialects.convert(mask, toOrOptions) / convert(mask, from, to)	Instance	Mask, target dialect, or { from, to } options	ConvertResult	Converts a format mask directly from one dialect to another (source dialect auto-inferred if omitted).
Tempo.fromFormat(input, mask, options?)	Static	Date string, mask, options	Tempo	Luxon Drop-In Parser. Parses an input string using an LDML mask (or auto-detected dialect).
Tempo.fromFormats(input, masks[], options?)	Static	Date string, candidate masks	Tempo	Multi-candidate fallback parser with auto-dialect detection (first matching mask succeeds).
Tempo.dialects.parse(input, mask, dialect?)	Static	Date string, mask, dialect	Tempo	Explicit dialect parser.
Tempo.dialects.fromFormats(input, masks[], ...)	Static	Date string, candidate masks	Tempo	Explicit multi-candidate fallback parser.
Tempo.dialects.explain(mask, dialectOrOptions?)	Static	External format mask, dialect name or { dialect }	ExplainResult	AST analyzer translating legacy masks into native Tempo {token} syntax.
Tempo.dialects.export(pattern, dialectOrOptions?)	Static	Native Tempo pattern, target dialect name or { dialect }	ExportResult	Exports a native Tempo {token} pattern into an external dialect format model.
Tempo.dialects.convert(mask, toOrOptions) / convert(mask, from, to)	Static	Mask, target dialect, or { from, to } options	ConvertResult	Transpiles a format mask directly between dialects (source dialect auto-inferred if omitted).

Performance & Lazy Evaluation

1. Pre-Compiled Formatters: Formatting masks are tokenized and compiled into high-speed closure interpolators on first run and cached in memory. Subsequent executions bypass tokenization and compilation overhead, evaluating directly through cached closures.
2. Lazy-Evaluated Namespace: Accessing t.dialects utilizes Tempo's zero-overhead proxy pattern, consuming zero CPU cycles until explicitly invoked on an instance.
3. Immutable Static Namespace: Tempo.dialects is recursively frozen via deepFreeze() to protect the host class against runtime tampering.

---

Topic Guides

To explore technical deep-dives, token compatibility matrices, and production patterns, consult the dedicated guides below:

• Design Strategy & Deliberate Omissions: Why Tempo engineered {token:modifier} over historical dialects, benefits of all-lowercase tokens and getter symmetry, and why specific legacy features were omitted.
• Migration & Legacy Compatibility: Resolving the YYYY vs yyyy year trap, handling bracketed/quoted escaping, using .explain() for automated codemods, and performance benchmarks.
• Token Specification & Cross-Ecosystem Matrix: Exhaustive token lookup table mapping LDML, Moment, strftime, and native Tempo tokens across years, months, days, sub-seconds, and timezones.
• Production Use Cases & Architectural Patterns: Multi-candidate webhook ingestion pipelines, enterprise POSIX syslog formatting, and zero-downtime gradual modernization recipes.

---

License

This is a Community plugin. It is completely free and open-source for personal and commercial use under the MIT license.