Rails TimeZone Converter

Common errors

• TypeError: from is not a function

  cause Attempting to call `from` directly on a CommonJS default import or incorrect ES module import syntax.
  fix For ES modules, use named import: `import { from } from 'rails-timezone';`. For CommonJS, use destructuring: `const { from } = require('rails-timezone');`.

• Property 'RailsTimeZone' does not exist on type 'Window & typeof globalThis'.

  cause TypeScript error when accessing `window.RailsTimeZone` in a browser environment without an explicit global type declaration.
  fix Add a declaration file (`.d.ts`) to your project or augment the `Window` interface: `declare global { interface Window { RailsTimeZone: { from: (tz: string) => string | undefined; to: (tz: string) => string | undefined; }; } }`.

• Cannot find module 'rails-timezone'

  cause The package is not installed in your project's `node_modules` or the import/require path is incorrect.
  fix Run `npm install rails-timezone` or `yarn add rails-timezone`. Verify that the import path `'rails-timezone'` is correct.

Warnings

• breaking The library's internal time zone mapping is a static snapshot derived from a specific version of ActiveSupport's `time_zone.rb`. If Rails updates its time zone names or mappings in a future version, this library might return outdated or incorrect conversions. Users relying on precise synchronization with the latest Rails definitions should monitor for `rails-timezone` updates.
  Fix: Always pin the `rails-timezone` package version in your project to ensure consistent behavior. Check release notes for updates when upgrading your Rails backend or `rails-timezone`.
• gotcha Both `from` and `to` functions return `undefined` when an input time zone name (either ActiveSupport or IANA) is not found in the internal mapping. This is by design and not an error, but it requires explicit handling to prevent downstream issues.
  Fix: Always check the return value for `undefined` before using the result: `const iana = from(railsZone); if (iana) { /* use iana */ } else { /* handle unmapped zone */ }`.
• gotcha When used directly in a browser environment via a `<script>` tag, the library exposes its functions on the global `window.RailsTimeZone` object. This could lead to naming collisions if another script defines a global object with the same name.
  Fix: If a collision is suspected or to avoid it proactively, consider using a module bundler (like Webpack, Rollup, or Vite) to scope the library's imports, or ensure careful management of global namespaces in your application.

Install

• npm install rails-timezone npm
• yarn add rails-timezone yarn
• pnpm add rails-timezone pnpm

Imports

• from
  wrong:

  import RailsTimeZone from 'rails-timezone'; RailsTimeZone.from(...)

  correct:

  import { from } from 'rails-timezone';

  Named export for converting an ActiveSupport TimeZone name to its IANA equivalent.
• to
  wrong:

  const RailsTimeZone = require('rails-timezone'); RailsTimeZone.to(...)

  correct:

  import { to } from 'rails-timezone';

  Named export for converting an IANA Time Zone Database name to its ActiveSupport equivalent.
• RailsTimeZone
  wrong:

  import { RailsTimeZone } from 'rails-timezone';

  correct:

  window.RailsTimeZone.from('Eastern Time (US & Canada)');

  When included directly in a browser via a script tag, functions are exposed under the global `window.RailsTimeZone` object.
• CommonJS require

  const { from, to } = require('rails-timezone');

  Standard CommonJS import for Node.js environments. Destructuring is necessary as there is no default export.

Quickstart

Demonstrates converting time zone names between Rails ActiveSupport and IANA formats, including handling unmapped inputs which return `undefined`.

import { from, to } from 'rails-timezone';

// Example 1: Convert from Rails ActiveSupport name to IANA
const railsTimeZoneName = 'Eastern Time (US & Canada)';
const ianaTimeZone = from(railsTimeZoneName);
console.log(`Rails TimeZone "${railsTimeZoneName}" converts to IANA: "${ianaTimeZone}"`);
// Expected output (America/New_York)

// Example 2: Convert from IANA name to Rails ActiveSupport
const ianaTimeZoneName = 'Europe/Berlin';
const railsTimeZone = to(ianaTimeZoneName);
console.log(`IANA TimeZone "${ianaTimeZoneName}" converts to Rails: "${railsTimeZone}"`);
// Expected output (Berlin)

// Example 3: Handling unknown time zones gracefully (returns undefined)
const unknownRails = 'Galactic Time';
const unknownIana = from(unknownRails);
console.log(`Unknown Rails TimeZone "${unknownRails}" converts to IANA: "${unknownIana}"`);
// Expected output (undefined)

const unknownIanaName = 'Mars/Equatorial';
const unknownRailsName = to(unknownIanaName);
console.log(`Unknown IANA TimeZone "${unknownIanaName}" converts to Rails: "${unknownRailsName}"`);
// Expected output (undefined)