temporal-fmt 0.8.97 → 0.8.98

package/README.md

@@ -834,7 +834,7 @@ A handful of functions exist specifically to feed editor tooling — autocomplet
 
 ## CLI
 
-The CLI ships in this package (`scripts/cli.mjs`) and reads/writes stdin/stdout. Run it via `npm run cli` inside a checkout of this repo, or `node scripts/cli.mjs` directly:
+The CLI ships in this package (`scripts/cli.mjs`) and reads/writes stdin/stdout. Run it via `npm run cli` inside a checkout of this repo, or `node scripts/cli.mjs` directly. Called with a subcommand it runs once and exits, same as any Unix tool — fine for scripts and CI:
 
 ```sh
 temporal-fmt format "2026-08-04T15:45:30" "yyyy-MM-dd HH:mm:ss"
@@ -852,7 +852,23 @@ temporal-fmt translate dayjs "YYYY-MM-DD HH:mm:ss"
 | `validate <format-string>` | Prints `valid` or `invalid`. |
 | `translate <source-lib> <format-string>` | Translates a Day.js or date-fns format string to `temporal-fmt` tokens. |
 
-The `translate` subcommand imports a separate `temporal-fmt-codemod` package at runtime — it isn't bundled in this repo, so `translate` will fail with a module-not-found error unless that package is installed and resolvable. Every other subcommand works standalone.
+`translate` is implemented in-repo (`src/codemod.ts`) against the same token tables the IDE tooling data uses — no external package, no runtime dependency beyond this library itself. It throws on tokens with no `temporal-fmt` equivalent (`Do`/`P`/etc. — see the [migration table](#token-mapping)) rather than guessing.
+
+### Interactive mode
+
+Run `temporal-fmt` with no arguments to start a REPL:
+
+```
+$ temporal-fmt
+temporal-fmt interactive mode. Type a subcommand, "help", or "exit".
+temporal-fmt> format
+ISO input: 2026-08-04T15:45:30
+Format string: yyyy-MM-dd HH:mm:ss
+2026-08-04 15:45:30
+temporal-fmt> exit
+```
+
+Type a subcommand with all its arguments inline (`validate yyyy-MM-dd`) or just the subcommand name — the REPL prompts for whatever's missing, one field at a time. Errors print and the session keeps going; `exit`, `quit`, or Ctrl+D ends it. This is the same subcommand logic as one-shot mode, just wrapped in a loop that asks instead of exiting on a missing argument — one-shot stays there for scripting, and doesn't touch the REPL machinery.
 
 ## Subpath imports
 
@@ -977,7 +993,7 @@ Migrate file by file, dropping the wrapper once nothing calls the old path anymo
 Neither of these ships as part of this repository — separate packages, install them on their own:
 
 - [`eslint-plugin-temporal-fmt`](https://www.npmjs.com/package/eslint-plugin-temporal-fmt) — lints format strings for common mistakes (e.g. `hh` without `a`). This is what backs the `analyzeFormat(formatStr).warnings` check mentioned in [Introspection and the analyzer](#introspection-and-the-analyzer) — same underlying metadata, surfaced as a lint diagnostic instead of a runtime call.
-- [`temporal-fmt-codemod`](https://www.npmjs.com/package/temporal-fmt-codemod) — one-time migration tool that rewrites Day.js/date-fns calls to `temporal-fmt`. The CLI's `translate` subcommand (see [CLI](#cli)) imports this package at runtime, so `translate` needs it installed to work.
+- [`temporal-fmt-codemod`](https://github.com/DirazCoder/temporal-fmt-codemod) — a jscodeshift AST codemod that rewrites `dayjs(x).format(...)`/date-fns `format(...)` *call sites* across a codebase, not just format-string literals. A different job from the CLI's `translate` subcommand (see [CLI](#cli)), which only translates a format string you hand it and doesn't touch call sites; use this instead if you're migrating an entire codebase and want the calls themselves rewritten.
 
 ## Testing
 

package/dist/codemod.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Translates a Day.js format string to the equivalent temporal-fmt
+ * token string.
+ *
+ * ```js
+ * translateDayjsFormatString('YYYY-MM-DD HH:mm:ss'); // "yyyy-MM-dd HH:mm:ss"
+ * translateDayjsFormatString('[Q]Q YYYY');            // "'Q'Q yyyy" (bracketed text stays literal)
+ * ```
+ *
+ * Throws if the format string uses a Day.js token with no temporal-fmt
+ * equivalent (`Do`, `Mo`, `Qo`, `k`, `kk`, `X`, `x`, the localized
+ * `L`-family tokens) — these need to be rewritten by hand, since
+ * there's no single temporal-fmt token that means the same thing.
+ *
+ * Note: `Do`/`Mo`/`Qo`/`k`/`kk`/`X`/`x` only have meaning in Day.js
+ * once the `AdvancedFormat` (and, for `X`/`x`, base) plugins are
+ * loaded — without them Day.js silently glues the parts together or
+ * passes the letters through unrendered instead of erroring. This
+ * function assumes the plugin is loaded, since that's the common case
+ * for anyone who put these tokens in a format string on purpose.
+ */
+export declare function translateDayjsFormatString(formatStr: string): string;
+/**
+ * Translates a date-fns format string to the equivalent temporal-fmt
+ * token string. date-fns already uses Unicode-style tokens close to
+ * temporal-fmt's own, so most strings pass through with only a case
+ * change on the weekday tokens; the notable divergences are date-fns's
+ * `D`/`DD` (day-of-year, matches temporal-fmt already) versus its `d`/
+ * `dd` (day-of-month, also matches already) and the locale-dependent
+ * `P`/`p` composite tokens, which have no single temporal-fmt token
+ * and throw.
+ */
+export declare function translateDateFnsFormatString(formatStr: string): string;

package/dist/codemod.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Translates a Day.js format string to the equivalent temporal-fmt
+ * token string.
+ *
+ * ```js
+ * translateDayjsFormatString('YYYY-MM-DD HH:mm:ss'); // "yyyy-MM-dd HH:mm:ss"
+ * translateDayjsFormatString('[Q]Q YYYY');            // "'Q'Q yyyy" (bracketed text stays literal)
+ * ```
+ *
+ * Throws if the format string uses a Day.js token with no temporal-fmt
+ * equivalent (`Do`, `Mo`, `Qo`, `k`, `kk`, `X`, `x`, the localized
+ * `L`-family tokens) — these need to be rewritten by hand, since
+ * there's no single temporal-fmt token that means the same thing.
+ *
+ * Note: `Do`/`Mo`/`Qo`/`k`/`kk`/`X`/`x` only have meaning in Day.js
+ * once the `AdvancedFormat` (and, for `X`/`x`, base) plugins are
+ * loaded — without them Day.js silently glues the parts together or
+ * passes the letters through unrendered instead of erroring. This
+ * function assumes the plugin is loaded, since that's the common case
+ * for anyone who put these tokens in a format string on purpose.
+ */
+export declare function translateDayjsFormatString(formatStr: string): string;
+/**
+ * Translates a date-fns format string to the equivalent temporal-fmt
+ * token string. date-fns already uses Unicode-style tokens close to
+ * temporal-fmt's own, so most strings pass through with only a case
+ * change on the weekday tokens; the notable divergences are date-fns's
+ * `D`/`DD` (day-of-year, matches temporal-fmt already) versus its `d`/
+ * `dd` (day-of-month, also matches already) and the locale-dependent
+ * `P`/`p` composite tokens, which have no single temporal-fmt token
+ * and throw.
+ */
+export declare function translateDateFnsFormatString(formatStr: string): string;

package/dist/ideData.d.cts

@@ -25,7 +25,7 @@ export interface InlineDiagnostic {
 export declare function getInlineDiagnostics(formatStr: string): InlineDiagnostic[];
 export interface TokenConversionHint {
     from: string;
-    to: string;
+    to: string | null;
     notes?: string;
 }
 export declare const DAYJS_TO_TEMPORAL_FMT: TokenConversionHint[];

package/dist/ideData.d.ts

@@ -25,7 +25,7 @@ export interface InlineDiagnostic {
 export declare function getInlineDiagnostics(formatStr: string): InlineDiagnostic[];
 export interface TokenConversionHint {
     from: string;
-    to: string;
+    to: string | null;
     notes?: string;
 }
 export declare const DAYJS_TO_TEMPORAL_FMT: TokenConversionHint[];

package/dist/index.cjs

@@ -224,6 +224,8 @@ __export(index_exports, {
   tokenInfo: () => tokenInfo,
   tokenizeFormat: () => tokenizeFormat,
   totalDuration: () => totalDuration,
+  translateDateFnsFormatString: () => translateDateFnsFormatString,
+  translateDayjsFormatString: () => translateDayjsFormatString,
   truncate: () => truncate,
   tryParse: () => tryParse,
   union: () => union,
@@ -6197,19 +6199,102 @@ var DAYJS_TO_TEMPORAL_FMT = [
   { from: "M", to: "M" },
   { from: "DD", to: "dd" },
   { from: "D", to: "d" },
+  { from: "Do", to: null, notes: `Ordinal day (AdvancedFormat) \u2014 use temporal-fmt's own "do" token instead.` },
   { from: "dddd", to: "EEEE" },
   { from: "ddd", to: "EEE" },
+  { from: "dd", to: null, notes: 'Min-name weekday (e.g. "Tu") \u2014 temporal-fmt has no equivalent width.' },
+  { from: "d", to: null, notes: 'Numeric weekday (0-6) \u2014 no temporal-fmt equivalent; not the same as "d" here, which is day-of-month.' },
   { from: "HH", to: "HH" },
+  { from: "H", to: "H" },
+  { from: "hh", to: "hh" },
+  { from: "h", to: "h" },
+  { from: "kk", to: null, notes: "Hour 1-24 (AdvancedFormat) \u2014 no temporal-fmt equivalent." },
+  { from: "k", to: null, notes: "Hour 1-24 (AdvancedFormat) \u2014 no temporal-fmt equivalent." },
   { from: "mm", to: "mm" },
+  { from: "m", to: "m" },
   { from: "ss", to: "ss" },
-  { from: "A", to: "a" },
+  { from: "s", to: "s" },
+  { from: "SSS", to: "SSS" },
+  { from: "A", to: "a", notes: "Uppercase AM/PM in Day.js \u2014 temporal-fmt is always lowercase." },
   { from: "a", to: "a" },
-  { from: "Z", to: "XXX" }
+  { from: "ZZ", to: "XX", notes: "Numeric UTC offset, no colon." },
+  { from: "Z", to: "XXX", notes: "Numeric UTC offset with colon." },
+  { from: "X", to: null, notes: "Unix timestamp (seconds) \u2014 use fromUnixSeconds() instead." },
+  { from: "x", to: null, notes: "Unix timestamp (ms) \u2014 use fromUnixMilliseconds() instead." },
+  { from: "Qo", to: null, notes: "Ordinal quarter (AdvancedFormat) \u2014 no temporal-fmt equivalent." },
+  { from: "Q", to: "Q" },
+  { from: "Mo", to: null, notes: "Ordinal month (AdvancedFormat) \u2014 no temporal-fmt equivalent." },
+  { from: "ww", to: "ww" },
+  { from: "wo", to: null, notes: "Ordinal ISO week (AdvancedFormat) \u2014 no temporal-fmt equivalent." },
+  { from: "w", to: null, notes: `Unpadded ISO week \u2014 temporal-fmt's "ww" is always 2-digit.` },
+  { from: "gggg", to: "RRRR", notes: "Week-numbering year, not the calendar year \u2014 same caveat as temporal-fmt's RRRR." },
+  { from: "L", to: null, notes: "Localized date format (AdvancedFormat) \u2014 write the format string out explicitly." },
+  { from: "LL", to: null, notes: "Localized date format (AdvancedFormat) \u2014 write the format string out explicitly." },
+  { from: "LLL", to: null, notes: "Localized date format (AdvancedFormat) \u2014 write the format string out explicitly." },
+  { from: "LLLL", to: null, notes: "Localized date format (AdvancedFormat) \u2014 write the format string out explicitly." },
+  { from: "LT", to: null, notes: "Localized time format (AdvancedFormat) \u2014 write the format string out explicitly." },
+  { from: "LTS", to: null, notes: "Localized time format (AdvancedFormat) \u2014 write the format string out explicitly." }
 ];
 var DATE_FNS_TO_TEMPORAL_FMT = [
-  ...DAYJS_TO_TEMPORAL_FMT
-  // most tokens are identical
-  // date-fns-specific differences noted inline.
+  { from: "yyyy", to: "yyyy" },
+  { from: "yy", to: "yy" },
+  { from: "y", to: null, notes: 'Unpadded calendar year, opt-in via useAdditionalWeekYearTokens \u2014 temporal-fmt has no unpadded-year token; use "yyyy".' },
+  { from: "MMMM", to: "MMMM" },
+  { from: "MMM", to: "MMM" },
+  { from: "MM", to: "MM" },
+  { from: "M", to: "M" },
+  { from: "LLLL", to: "LLLL" },
+  { from: "LLL", to: "LLL" },
+  { from: "dd", to: "dd" },
+  { from: "d", to: "d" },
+  { from: "do", to: "do" },
+  { from: "DDD", to: "DDD" },
+  { from: "DD", to: "DD" },
+  { from: "D", to: "D", notes: `Day-of-year, opt-in via useAdditionalDayOfYearTokens \u2014 matches temporal-fmt's own "D" already.` },
+  { from: "EEEE", to: "EEEE" },
+  { from: "EEE", to: "EEE" },
+  { from: "eeee", to: null, notes: "Locale-aware numeric weekday \u2014 no temporal-fmt equivalent." },
+  { from: "cccc", to: "cccc" },
+  { from: "ccc", to: "ccc" },
+  { from: "HH", to: "HH" },
+  { from: "H", to: "H" },
+  { from: "hh", to: "hh" },
+  { from: "h", to: "h" },
+  { from: "mm", to: "mm" },
+  { from: "m", to: "m" },
+  { from: "ss", to: "ss" },
+  { from: "s", to: "s" },
+  { from: "SSS", to: "SSS" },
+  { from: "a", to: "a" },
+  { from: "aaa", to: "a" },
+  { from: "XXX", to: "XXX" },
+  { from: "XX", to: "XX" },
+  { from: "X", to: "X", notes: `Opt-in via useAdditionalDayOfYearTokens-adjacent rules in date-fns v3+; matches temporal-fmt's own "X" already.` },
+  { from: "xxx", to: "xxx" },
+  { from: "xx", to: "xx" },
+  { from: "x", to: "x" },
+  { from: "zzzz", to: "zzzz" },
+  { from: "zzz", to: "zzz" },
+  { from: "z", to: "z" },
+  { from: "QQQ", to: "QQQ" },
+  { from: "Q", to: "Q" },
+  { from: "GGGG", to: "GGGG" },
+  { from: "GGG", to: null, notes: 'Abbreviated era \u2014 temporal-fmt only has "G" (short) and "GGGG" (long).' },
+  { from: "GG", to: null, notes: 'Abbreviated era \u2014 temporal-fmt only has "G" (short) and "GGGG" (long).' },
+  { from: "G", to: "G" },
+  { from: "ww", to: "ww" },
+  { from: "w", to: null, notes: `Unpadded local week number \u2014 temporal-fmt's "ww" is ISO-week and always 2-digit.` },
+  { from: "RRRR", to: "RRRR" },
+  { from: "R", to: null, notes: `Unpadded ISO week-numbering year \u2014 temporal-fmt's "RRRR" is always 4-digit.` },
+  { from: "Y", to: null, notes: 'Week-numbering year (locale week rules), opt-in \u2014 no temporal-fmt equivalent; "RRRR" is ISO week-numbering, a different rule set.' },
+  { from: "PPPP", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "PPP", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "PP", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "P", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "pppp", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "ppp", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "pp", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." },
+  { from: "p", to: null, notes: "Localized composite format \u2014 write the format string out explicitly." }
 ];
 function previewFormat(formatStr, sample) {
   const value = sample ?? {
@@ -6231,6 +6316,83 @@ function getDocUrl(tokenName) {
   void tokenName;
   return "README.md#token-reference";
 }
+
+// src/codemod.ts
+function splitOnBrackets(source) {
+  const pieces = [];
+  let i = 0;
+  while (i < source.length) {
+    if (source[i] === "[") {
+      const end = source.indexOf("]", i + 1);
+      if (end === -1) {
+        pieces.push({ kind: "token", value: source.slice(i) });
+        break;
+      }
+      pieces.push({ kind: "literal", value: source.slice(i + 1, end) });
+      i = end + 1;
+    } else {
+      let j = i;
+      while (j < source.length && source[j] !== "[") j += 1;
+      pieces.push({ kind: "token", value: source.slice(i, j) });
+      i = j;
+    }
+  }
+  return pieces;
+}
+function splitIntoRuns(span, sortedFrom) {
+  const pieces = [];
+  let i = 0;
+  while (i < span.length) {
+    const match = sortedFrom.find((tok) => span.startsWith(tok, i));
+    if (match) {
+      pieces.push({ kind: "token", value: match });
+      i += match.length;
+      continue;
+    }
+    const last = pieces[pieces.length - 1];
+    if (last && last.kind === "literal") {
+      last.value += span[i];
+    } else {
+      pieces.push({ kind: "literal", value: span[i] });
+    }
+    i += 1;
+  }
+  return pieces;
+}
+function translate(source, table, sourceLibLabel) {
+  const byFrom = new Map(table.map((hint) => [hint.from, hint.to]));
+  const sortedFrom = [...byFrom.keys()].sort((a, b) => b.length - a.length);
+  const bracketPieces = splitOnBrackets(source);
+  let out = "";
+  for (const piece of bracketPieces) {
+    if (piece.kind === "literal") {
+      out += `'${piece.value.replace(/'/g, "''")}'`;
+      continue;
+    }
+    for (const run of splitIntoRuns(piece.value, sortedFrom)) {
+      if (run.kind === "token") {
+        const mapped = byFrom.get(run.value);
+        if (mapped === void 0 || mapped === null) {
+          throw new Error(
+            `temporal-fmt: "${run.value}" has no ${sourceLibLabel} -> temporal-fmt mapping (in format string "${source}"). Write the equivalent temporal-fmt token in by hand, or wrap it in brackets if it was meant as literal text.`
+          );
+        }
+        out += mapped;
+      } else if (/[a-zA-Z]/.test(run.value)) {
+        out += `'${run.value.replace(/'/g, "''")}'`;
+      } else {
+        out += run.value;
+      }
+    }
+  }
+  return out;
+}
+function translateDayjsFormatString(formatStr) {
+  return translate(formatStr, DAYJS_TO_TEMPORAL_FMT, "Day.js");
+}
+function translateDateFnsFormatString(formatStr) {
+  return translate(formatStr, DATE_FNS_TO_TEMPORAL_FMT, "date-fns");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_TOKEN_NAMES,
@@ -6437,6 +6599,8 @@ function getDocUrl(tokenName) {
   tokenInfo,
   tokenizeFormat,
   totalDuration,
+  translateDateFnsFormatString,
+  translateDayjsFormatString,
   truncate,
   tryParse,
   union,