feat(time): parse POSIX locale datestamps. Add TZA to fixed UTC offsets lookups.

Author: mceachen

.claude/settings.local.json

@@ -25,7 +25,7 @@
       "WebFetch(domain:www.color.org)",
       "WebFetch(domain:www.iptc.org)",
       "WebFetch(domain:photostructure.com)",
-      "WebSearch",
+      "WebSearch"
     ],
     "deny": [],
     "ask": [],

CHANGELOG.md

@@ -35,6 +35,12 @@ vendored versions of ExifTool match the version that they vendor.
 
 ## History
 
+### v35.14.1
+
+- 🐞 Fixed parsing of POSIX locale date strings like `"Tue 17 Jun 2025 09:29:01 PM PDT"` (emitted by gnome-screenshot's `CreationTime` tag). Previously these fell through to raw strings, losing the time and timezone.
+- ✨ `extractZone()` now resolves common unambiguous timezone abbreviations (PDT, EST, CEST, JST, NZDT, etc.) to fixed UTC offsets (e.g. PDT → `UTC-7`) as a last-resort fallback when no numeric UTC offset is present. Ambiguous abbreviations (CST, IST, BST, AST) are intentionally omitted.
+- ✨ New `Settings.tzAbbreviationOffsets` allows users to resolve ambiguous abbreviations for their region (e.g. `{ CST: -6 * 60 }` for US Central, `{ IST: 5 * 60 + 30 }` for India).
+
 ### v35.14.0
 
 - 🌱 Upgraded ExifTool to version [13.53](https://exiftool.org/history.html#13.53).

src/ExifDateTime.spec.ts

@@ -242,6 +242,62 @@ describe("ExifDateTime", () => {
     expect(dt.zone).to.eql("UTC-7");
   });
 
+  describe("POSIX locale date parsing (gnome-screenshot, etc.)", () => {
+    it("parses 12-hour POSIX locale with PDT", () => {
+      const raw = "Tue 17 Jun 2025 09:29:01 PM PDT";
+      const dt = ExifDateTime.from(raw)!;
+      expect(dt).to.not.eql(undefined);
+      expect(dt.year).to.eql(2025);
+      expect(dt.month).to.eql(6);
+      expect(dt.day).to.eql(17);
+      expect(dt.hour).to.eql(21); // 9 PM = 21
+      expect(dt.minute).to.eql(29);
+      expect(dt.second).to.eql(1);
+      expect(dt.zone).to.eql("UTC-7");
+      expect(dt.tzoffsetMinutes).to.eql(-420);
+      expect(dt.inferredZone).to.eql(false);
+    });
+
+    it("parses 12-hour POSIX locale with PST", () => {
+      const raw = "Thu 16 Jan 2025 10:00:00 AM PST";
+      const dt = ExifDateTime.from(raw)!;
+      expect(dt).to.not.eql(undefined);
+      expect(dt.year).to.eql(2025);
+      expect(dt.month).to.eql(1);
+      expect(dt.day).to.eql(16);
+      expect(dt.hour).to.eql(10);
+      expect(dt.minute).to.eql(0);
+      expect(dt.second).to.eql(0);
+      expect(dt.zone).to.eql("UTC-8");
+      expect(dt.tzoffsetMinutes).to.eql(-480);
+    });
+
+    it("parses 24-hour POSIX locale with CEST", () => {
+      const raw = "Tue 15 Jul 2025 14:30:00 CEST";
+      const dt = ExifDateTime.from(raw)!;
+      expect(dt).to.not.eql(undefined);
+      expect(dt.year).to.eql(2025);
+      expect(dt.month).to.eql(7);
+      expect(dt.day).to.eql(15);
+      expect(dt.hour).to.eql(14);
+      expect(dt.minute).to.eql(30);
+      expect(dt.second).to.eql(0);
+      expect(dt.zone).to.eql("UTC+2");
+      expect(dt.tzoffsetMinutes).to.eql(120);
+    });
+
+    it("parses POSIX locale without weekday prefix", () => {
+      const raw = "17 Jun 2025 09:29:01 PM PDT";
+      const dt = ExifDateTime.from(raw)!;
+      expect(dt).to.not.eql(undefined);
+      expect(dt.year).to.eql(2025);
+      expect(dt.month).to.eql(6);
+      expect(dt.day).to.eql(17);
+      expect(dt.hour).to.eql(21);
+      expect(dt.zone).to.eql("UTC-7");
+    });
+  });
+
   it("try to repro issue #46", () => {
     const edt = new ExifDateTime(2019, 3, 8, 14, 24, 54, 0, -480);
     const dt = edt.toDateTime();

src/ExifDateTime.ts

@@ -143,6 +143,13 @@ export class ExifDateTime {
       "MMM d y, HH:mm:ss",
       // Thu Oct 13 00:12:27 2016:
       "ccc MMM d HH:mm:ss y",
+      // POSIX locale dates from gnome-screenshot, etc.
+      // "Tue 17 Jun 2025 09:29:01 PM" (after TZA stripping):
+      "ccc d MMM y h:mm:ss a",
+      "ccc d MMM y HH:mm:ss",
+      // Without weekday prefix:
+      "d MMM y h:mm:ss a",
+      "d MMM y HH:mm:ss",
     ];
     const zone = notBlank(defaultZone) ? defaultZone : UnsetZone;
     for (const fmt of formats) {

src/Settings.ts

@@ -129,6 +129,38 @@ export const Settings = {
    */
   maxValidOffsetMinutes: new Setting(30),
 
+  /**
+   * Additional timezone abbreviation → UTC offset (in minutes) mappings.
+   *
+   * These are merged on top of the built-in table, with user values taking
+   * precedence. This allows you to:
+   * - Resolve ambiguous abbreviations for your region
+   * - Override built-in mappings
+   * - Add abbreviations not in the default table
+   *
+   * Keys must be uppercase. Values are UTC offset in minutes.
+   *
+   * @default `{}` (only built-in unambiguous mappings are used)
+   *
+   * @example
+   * ```typescript
+   * import { Settings } from "exiftool-vendored"
+   *
+   * // US Central Standard Time (UTC-6):
+   * Settings.tzAbbreviationOffsets.value = { CST: -6 * 60 }
+   *
+   * // India Standard Time (UTC+5:30):
+   * Settings.tzAbbreviationOffsets.value = { IST: 5 * 60 + 30 }
+   *
+   * // Multiple at once:
+   * Settings.tzAbbreviationOffsets.value = {
+   *   CST: -6 * 60,
+   *   IST: 5 * 60 + 30,
+   * }
+   * ```
+   */
+  tzAbbreviationOffsets: new Setting<Readonly<Record<string, number>>>({}),
+
   /**
    * Logger instance used throughout exiftool-vendored.
    *

src/Timezones.spec.ts

@@ -240,6 +240,131 @@ describe("Timezones", () => {
     }
   });
 
+  describe("TZA abbreviation resolution", () => {
+    it("resolves PDT to UTC-7 from POSIX locale timestamp", () => {
+      const result = extractZone("Tue 17 Jun 2025 09:29:01 PM PDT");
+      expect(result?.zone).to.equal("UTC-7");
+      expect(result?.src).to.equal("tzAbbreviation");
+      expect(result?.leftovers).to.equal("Tue 17 Jun 2025 09:29:01 PM");
+    });
+
+    it("resolves PST to UTC-8 from POSIX locale timestamp", () => {
+      const result = extractZone("Thu 16 Jan 2025 10:00:00 AM PST");
+      expect(result?.zone).to.equal("UTC-8");
+      expect(result?.src).to.equal("tzAbbreviation");
+      expect(result?.leftovers).to.equal("Thu 16 Jan 2025 10:00:00 AM");
+    });
+
+    it("resolves EST to UTC-5", () => {
+      const result = extractZone("2025:01:15 10:30:00 EST");
+      expect(result?.zone).to.equal("UTC-5");
+      expect(result?.src).to.equal("tzAbbreviation");
+      expect(result?.leftovers).to.equal("2025:01:15 10:30:00");
+    });
+
+    it("resolves CEST to UTC+2", () => {
+      const result = extractZone("2025:07:15 14:00:00 CEST");
+      expect(result?.zone).to.equal("UTC+2");
+      expect(result?.src).to.equal("tzAbbreviation");
+    });
+
+    it("resolves NZDT to UTC+13", () => {
+      const result = extractZone("2025:01:15 10:30:00 NZDT");
+      expect(result?.zone).to.equal("UTC+13");
+      expect(result?.src).to.equal("tzAbbreviation");
+    });
+
+    it("resolves NST to UTC-3:30 (Newfoundland)", () => {
+      const result = extractZone("2025:01:15 10:30:00 NST");
+      expect(result?.zone).to.equal("UTC-3:30");
+      expect(result?.src).to.equal("tzAbbreviation");
+    });
+
+    it("resolves JST to UTC+9", () => {
+      const result = extractZone("2025:07:15 14:00:00 JST");
+      expect(result?.zone).to.equal("UTC+9");
+      expect(result?.src).to.equal("tzAbbreviation");
+    });
+
+    it("does not resolve ambiguous CST", () => {
+      const result = extractZone("2025:01:15 10:30:00 CST");
+      expect(result).to.eql(undefined);
+    });
+
+    it("does not resolve ambiguous IST", () => {
+      const result = extractZone("2025:01:15 10:30:00 IST");
+      expect(result).to.eql(undefined);
+    });
+
+    it("does not resolve ambiguous BST", () => {
+      const result = extractZone("2025:01:15 10:30:00 BST");
+      expect(result).to.eql(undefined);
+    });
+
+    it("prefers numeric offset over TZA when both present", () => {
+      // This already had a numeric offset — TZA is just stripped
+      const result = extractZone("2014:07:17 08:46:27-07:00 DST");
+      expect(result?.zone).to.equal("UTC-7");
+      expect(result?.src).to.equal("offsetMinutesToZoneName");
+    });
+
+    it("returns undefined for unknown abbreviations", () => {
+      const result = extractZone("2025:01:15 10:30:00 XYZW");
+      expect(result).to.eql(undefined);
+    });
+
+    it("does not resolve TZA when stripTZA is false", () => {
+      const result = extractZone("Tue 17 Jun 2025 09:29:01 PM PDT", {
+        stripTZA: false,
+      });
+      expect(result).to.eql(undefined);
+    });
+
+    describe("Settings.tzAbbreviationOffsets", () => {
+      afterEach(() => Settings.reset());
+
+      it("resolves ambiguous CST when user provides override", () => {
+        Settings.tzAbbreviationOffsets.value = { CST: -6 * 60 };
+        const result = extractZone("2025:01:15 10:30:00 CST");
+        expect(result?.zone).to.equal("UTC-6");
+        expect(result?.src).to.equal("tzAbbreviation");
+      });
+
+      it("resolves ambiguous IST to India when user provides override", () => {
+        Settings.tzAbbreviationOffsets.value = { IST: 5 * 60 + 30 };
+        const result = extractZone("2025:01:15 10:30:00 IST");
+        expect(result?.zone).to.equal("UTC+5:30");
+        expect(result?.src).to.equal("tzAbbreviation");
+      });
+
+      it("user override takes precedence over built-in", () => {
+        // PDT is built-in as UTC-7; override to something else
+        Settings.tzAbbreviationOffsets.value = { PDT: -8 * 60 };
+        const result = extractZone("Tue 17 Jun 2025 09:29:01 PM PDT");
+        expect(result?.zone).to.equal("UTC-8");
+      });
+
+      it("reverts to built-in after reset", () => {
+        Settings.tzAbbreviationOffsets.value = { PDT: -8 * 60 };
+        Settings.reset();
+        const result = extractZone("Tue 17 Jun 2025 09:29:01 PM PDT");
+        expect(result?.zone).to.equal("UTC-7");
+      });
+
+      it("does not affect unrelated abbreviations", () => {
+        Settings.tzAbbreviationOffsets.value = { CST: -6 * 60 };
+        const result = extractZone("2025:01:15 10:30:00 EST");
+        expect(result?.zone).to.equal("UTC-5");
+      });
+
+      it("rejects invalid offset from user override", () => {
+        Settings.tzAbbreviationOffsets.value = { CST: 99999 };
+        const result = extractZone("2025:01:15 10:30:00 CST");
+        expect(result).to.eql(undefined);
+      });
+    });
+  });
+
   describe("Unicode timezone signs", () => {
     it("should handle Unicode minus sign (U+2212) in offset", () => {
       const result = extractZone("−08:00"); // Unicode minus