week-identifier

Unique, sequential week number for any date. Zero dependencies, with a CLI.

Week #1 starts on Monday, January 5, 1970. Weeks run Monday to Sunday and are counted in local time, so a week always changes at Monday 00:00 on the user's clock, daylight saving time included.

Handy as a stable key for weekly data: 2949 is easier to store, sort and compare than "year + ISO week".

Install

npm install week-identifier

Requires Node.js 22 or later.

API

const weekIdentifier = require('week-identifier');
// or: import weekIdentifier, { dateFromWeek } from 'week-identifier';

weekIdentifier(date?)

Returns the week identifier for a date.

• date {string|Date|number} – any date string new Date() understands, a Date, or a millisecond timestamp. Optional; defaults to now.
• returns {number} – sequential week identifier (1 = week of January 5, 1970)
• throws {Error} – when the string or Date is invalid

weekIdentifier();                            //=> current week, e.g. 2964
weekIdentifier('January 5, 1970');           //=> 1
weekIdentifier('January 12, 1970');          //=> 2
weekIdentifier('August 12, 2016');           //=> 2432
weekIdentifier('08/12/2016');                //=> 2432
weekIdentifier(new Date('August 12, 2016')); //=> 2432
weekIdentifier(Date.now());                  //=> current week

weekIdentifier('invalid date');
//=> throws Error: Invalid date string: "invalid date"

Note

JavaScript parses date-only ISO strings such as '2026-07-06' as UTC midnight, not local midnight. West of UTC, that can land on the previous day and therefore the previous week. Use '2026-07-06T00:00' or new Date(2026, 6, 6) for a local date.

weekIdentifier.dateFromWeek(weekId)

Returns the Monday (00:00 local time) that starts the given week.

• weekId {number|string} – week identifier
• returns {Date} – Monday of that week; identifiers ≤ 0 return January 5, 1970
• throws {Error} – when weekId is not a number ('12abc' is rejected); {RangeError} when the date would exceed the JavaScript Date range

weekIdentifier.dateFromWeek(2433); //=> Mon Aug 15 2016 00:00:00
weekIdentifier.dateFromWeek(1);    //=> Mon Jan 05 1970 00:00:00
weekIdentifier.dateFromWeek(0);    //=> Mon Jan 05 1970 00:00:00

weekIdentifier.dateFromWeek('abc');
//=> throws Error: Invalid week identifier: "abc"

CLI

npx week-identifier                    # current week
npx week-identifier "January 5, 1970"  #=> 1
npx week-identifier "02/17/2012"       #=> 2198
npx week-identifier --from 2432        #=> 2016-08-08 (Monday of that week)
npx week-identifier --help
npx week-identifier --version

Invalid input prints an error to stderr and exits with code 1:

npx week-identifier --from abc
#=> Error: Invalid week identifier: "abc"
#=> Use --help for usage information.

Install globally with npm install -g week-identifier to drop the npx.

Development

npm ci
npm test          # mocha + nyc coverage
npm run lint
npm run format

More examples in test.js and test-cli.js.

License

Copyright (c) 2016-2026 Clément Billiot and contributors. Released under the MIT license.