Timezone Offset Utility

0.0.2 · abandoned · verified Sun Apr 19

This package, `tz-offset`, provides basic utilities for working with JavaScript timezone offsets. Its current and only stable version is 0.0.2, published many years ago, indicating it is no longer actively maintained. The library calculates offsets based on what is likely a static, outdated internal dataset, meaning it does not receive updates for new timezone rules, historical changes, or changes in Daylight Saving Time (DST) definitions. While it offers a simple API to get offsets, remove offsets, or represent dates in other timezones, its core functionality is severely limited by its lack of maintenance and reliance on potentially inaccurate data. Key differentiators, if any, are its minimal footprint and extreme simplicity, but these come at the significant cost of accuracy and robustness compared to modern alternatives that integrate with IANA timezone databases or leverage native browser APIs.

Common errors

```
TypeError: tzOffset.offsetOf is not a function
```
cause Attempting to call methods on `tzOffset` when it has not been correctly imported or required as the module's default export.

fix Ensure you are using `const tzOffset = require('tz-offset')` for CommonJS environments, or if using a bundler with ESM interop, verify that `import tzOffset from 'tz-offset'` correctly resolves the default export.
```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ECMAScript Module (ESM) context (e.g., a Node.js module with `"type": "module"` in `package.json` or in a modern browser environment) without a bundler to transpile it.

fix If working in a pure ESM Node.js project, this package is not directly compatible. Consider migrating to a modern timezone library that offers native ESM support. If in a browser, use a bundler to process the CommonJS module.

Warnings

breaking The `tz-offset` package is effectively abandoned, with its last release (0.0.2) dating back many years. It no longer receives updates for new timezone definitions, historical changes, or Daylight Saving Time (DST) rule adjustments, leading to potentially inaccurate results, especially for future or past dates.
Fix: Migrate to actively maintained timezone libraries like `date-fns-tz`, `luxon`, or `moment-timezone`. For simple current offsets, consider `Intl.DateTimeFormat` if browser compatibility permits.
gotcha This package is CommonJS-only. Attempting to use `import tzOffset from 'tz-offset'` in a pure ESM environment without proper transpilation or bundler configuration will result in a runtime error.
Fix: Ensure you are using `const tzOffset = require('tz-offset')` in Node.js environments or configure your build system (e.g., Webpack, Rollup, esbuild) to correctly handle CommonJS modules when bundling for ESM contexts.
gotcha The `tz-offset` library does not use the IANA timezone database (also known as the 'Olson database'), which is the global standard for timezone information. This means its internal timezone data is likely hardcoded and static, making it unreliable for complex or precise timezone calculations.
Fix: For accurate timezone handling, especially involving historical data or future DST changes, use libraries that actively integrate and update the IANA database (e.g., `luxon`, `moment-timezone`, `date-fns-tz`).

Install

npm install tz-offset npm
yarn add tz-offset yarn
pnpm add tz-offset pnpm

Imports

tzOffset
```
const tzOffset = require('tz-offset')
```
This package is CommonJS-only.
tzOffset
wrong:
```
import { tzOffset } from 'tz-offset';
```
correct:
```
import tzOffset from 'tz-offset';
```
While a default import *might* work via bundler-specific CJS interop, this package does not provide a named export. It is fundamentally CommonJS.

Quickstart

Demonstrates getting timezone offsets, removing local offsets, and converting a date to another timezone using the `tz-offset` package. Highlights its CommonJS nature.

/**
 * @typedef {import('tz-offset')} TZOffset
 */

/**
 * A basic example demonstrating the use of tz-offset for timezone calculations.
 * Note: This package is very old and likely abandoned. Consider modern alternatives.
 */
function demonstrateTzOffset() {
  // For CommonJS environments (Node.js)
  /** @type {TZOffset} */
  const tzOffset = require('tz-offset');

  // Get the offset for a specific timezone (e.g., America/Sao_Paulo)
  // Returns the offset in minutes. Sao Paulo is UTC-3, so 3 * 60 = 180.
  // Note: This value might not account for DST accurately in a historical context.
  const saoPauloOffset = tzOffset.offsetOf("America/Sao_Paulo");
  console.log(`Offset for America/Sao_Paulo: ${saoPauloOffset} minutes`); // Expected: 180

  // Remove the timezone offset from a given date
  const now = new Date();
  const dateWithoutOffset = tzOffset.removeOffset(now);
  console.log(`Original Date: ${now.toISOString()}`);
  console.log(`Date without local offset: ${dateWithoutOffset.toISOString()} (Note: This creates a new Date object representing the same 'wall-clock' time but in UTC, effectively removing the local offset).`);

  // Represent a given date in another timezone
  const referenceDate = new Date('2023-10-27T10:00:00Z'); // A UTC date
  const londonTime = tzOffset.timeAt(referenceDate, "Europe/London");
  console.log(`Reference Date (UTC): ${referenceDate.toISOString()}`);
  console.log(`Equivalent time in Europe/London: ${londonTime.toISOString()}`); // Will show the date as if it were in London's timezone
}

demonstrateTzOffset();

view raw JSON →