{"id":15004,"library":"tz-offset","title":"Timezone Offset Utility","description":"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.","status":"abandoned","version":"0.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/merencia/tz-offset","tags":["javascript","timezone","offset","time","zone"],"install":[{"cmd":"npm install tz-offset","lang":"bash","label":"npm"},{"cmd":"yarn add tz-offset","lang":"bash","label":"yarn"},{"cmd":"pnpm add tz-offset","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only.","symbol":"tzOffset","correct":"const tzOffset = require('tz-offset')"},{"note":"While a default import *might* work via bundler-specific CJS interop, this package does not provide a named export. It is fundamentally CommonJS.","wrong":"import { tzOffset } from 'tz-offset';","symbol":"tzOffset","correct":"import tzOffset from 'tz-offset';"}],"quickstart":{"code":"/**\n * @typedef {import('tz-offset')} TZOffset\n */\n\n/**\n * A basic example demonstrating the use of tz-offset for timezone calculations.\n * Note: This package is very old and likely abandoned. Consider modern alternatives.\n */\nfunction demonstrateTzOffset() {\n  // For CommonJS environments (Node.js)\n  /** @type {TZOffset} */\n  const tzOffset = require('tz-offset');\n\n  // Get the offset for a specific timezone (e.g., America/Sao_Paulo)\n  // Returns the offset in minutes. Sao Paulo is UTC-3, so 3 * 60 = 180.\n  // Note: This value might not account for DST accurately in a historical context.\n  const saoPauloOffset = tzOffset.offsetOf(\"America/Sao_Paulo\");\n  console.log(`Offset for America/Sao_Paulo: ${saoPauloOffset} minutes`); // Expected: 180\n\n  // Remove the timezone offset from a given date\n  const now = new Date();\n  const dateWithoutOffset = tzOffset.removeOffset(now);\n  console.log(`Original Date: ${now.toISOString()}`);\n  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).`);\n\n  // Represent a given date in another timezone\n  const referenceDate = new Date('2023-10-27T10:00:00Z'); // A UTC date\n  const londonTime = tzOffset.timeAt(referenceDate, \"Europe/London\");\n  console.log(`Reference Date (UTC): ${referenceDate.toISOString()}`);\n  console.log(`Equivalent time in Europe/London: ${londonTime.toISOString()}`); // Will show the date as if it were in London's timezone\n}\n\ndemonstrateTzOffset();","lang":"typescript","description":"Demonstrates getting timezone offsets, removing local offsets, and converting a date to another timezone using the `tz-offset` package. Highlights its CommonJS nature."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<=0.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.0.2"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"<=0.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to call methods on `tzOffset` when it has not been correctly imported or required as the module's default export.","error":"TypeError: tzOffset.offsetOf is not a function"},{"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.","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.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}