Registry / serialization / rails-timezone

rails-timezone

library1.2.0jsnpmunverified

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.

serialization data

npm install rails-timezone

github ↗package ↗

INSTALL

IMPORT

SIG · RAILS-TIMEZONE

rails-timezone

serializationjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

from

✓ import { from } from 'rails-timezone';

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

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

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

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

Named export for converting an IANA Time Zone Database name to its ActiveSupport equivalent.

RailsTimeZone

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

✗ import { RailsTimeZone } from 'rails-timezone';

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.

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)

Debug

Known issues

breakingThe 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`.

affects: >=1.0.0

gotchaBoth `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 */ }`.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: from is not a function

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'.

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'

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.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/davidwood/rails-timezone-js ↗

packagehttps://www.npmjs.com/package/rails-timezone ↗