{"id":16667,"library":"rails-timezone","title":"Rails TimeZone Converter","description":"This `rails-timezone` package (version 1.2.0) provides essential utility functions for converting between the time zone names used by Rails' ActiveSupport and the universally recognized IANA Time Zone Database (also known as the Olsen database). Its primary purpose is to bridge the naming discrepancy between these two systems, ensuring compatibility for applications that interface with Rails backends. The library implements the exact mapping found in ActiveSupport's `time_zone.rb`, guaranteeing consistent conversions. While major releases are likely tied to significant changes in Rails' time zone handling, its current version offers stable functionality for both Node.js and browser environments, complete with TypeScript type definitions for improved development. Its key differentiator is its direct and accurate reflection of Rails' specific time zone naming conventions, unlike more general time zone libraries.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/davidwood/rails-timezone-js","tags":["javascript","timezone","rails","activesupport","iana","olsen","typescript"],"install":[{"cmd":"npm install rails-timezone","lang":"bash","label":"npm"},{"cmd":"yarn add rails-timezone","lang":"bash","label":"yarn"},{"cmd":"pnpm add rails-timezone","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Named export for converting an ActiveSupport TimeZone name to its IANA equivalent.","wrong":"import RailsTimeZone from 'rails-timezone'; RailsTimeZone.from(...)","symbol":"from","correct":"import { from } from 'rails-timezone';"},{"note":"Named export for converting an IANA Time Zone Database name to its ActiveSupport equivalent.","wrong":"const RailsTimeZone = require('rails-timezone'); RailsTimeZone.to(...)","symbol":"to","correct":"import { to } from 'rails-timezone';"},{"note":"When included directly in a browser via a script tag, functions are exposed under the global `window.RailsTimeZone` object.","wrong":"import { RailsTimeZone } from 'rails-timezone';","symbol":"RailsTimeZone","correct":"window.RailsTimeZone.from('Eastern Time (US & Canada)');"},{"note":"Standard CommonJS import for Node.js environments. Destructuring is necessary as there is no default export.","symbol":"CommonJS require","correct":"const { from, to } = require('rails-timezone');"}],"quickstart":{"code":"import { from, to } from 'rails-timezone';\n\n// Example 1: Convert from Rails ActiveSupport name to IANA\nconst railsTimeZoneName = 'Eastern Time (US & Canada)';\nconst ianaTimeZone = from(railsTimeZoneName);\nconsole.log(`Rails TimeZone \"${railsTimeZoneName}\" converts to IANA: \"${ianaTimeZone}\"`);\n// Expected output (America/New_York)\n\n// Example 2: Convert from IANA name to Rails ActiveSupport\nconst ianaTimeZoneName = 'Europe/Berlin';\nconst railsTimeZone = to(ianaTimeZoneName);\nconsole.log(`IANA TimeZone \"${ianaTimeZoneName}\" converts to Rails: \"${railsTimeZone}\"`);\n// Expected output (Berlin)\n\n// Example 3: Handling unknown time zones gracefully (returns undefined)\nconst unknownRails = 'Galactic Time';\nconst unknownIana = from(unknownRails);\nconsole.log(`Unknown Rails TimeZone \"${unknownRails}\" converts to IANA: \"${unknownIana}\"`);\n// Expected output (undefined)\n\nconst unknownIanaName = 'Mars/Equatorial';\nconst unknownRailsName = to(unknownIanaName);\nconsole.log(`Unknown IANA TimeZone \"${unknownIanaName}\" converts to Rails: \"${unknownRailsName}\"`);\n// Expected output (undefined)\n","lang":"typescript","description":"Demonstrates converting time zone names between Rails ActiveSupport and IANA formats, including handling unmapped inputs which return `undefined`."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always check the return value for `undefined` before using the result: `const iana = from(railsZone); if (iana) { /* use iana */ } else { /* handle unmapped zone */ }`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ES modules, use named import: `import { from } from 'rails-timezone';`. For CommonJS, use destructuring: `const { from } = require('rails-timezone');`.","cause":"Attempting to call `from` directly on a CommonJS default import or incorrect ES module import syntax.","error":"TypeError: from is not a function"},{"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; }; } }`.","cause":"TypeScript error when accessing `window.RailsTimeZone` in a browser environment without an explicit global type declaration.","error":"Property 'RailsTimeZone' does not exist on type 'Window & typeof globalThis'."},{"fix":"Run `npm install rails-timezone` or `yarn add rails-timezone`. Verify that the import path `'rails-timezone'` is correct.","cause":"The package is not installed in your project's `node_modules` or the import/require path is incorrect.","error":"Cannot find module 'rails-timezone'"}],"ecosystem":"npm"}