dates.week-number

export function weekNumber(iso: string): IsoWeek

/** A date's ISO 8601 week. */
export interface IsoWeek {
  /** the ISO week-numbering year; differs from the calendar year for a few days around 1 January */
  readonly weekYear: number;
  /** 1 to 52 or 53 */
  readonly week: number;
  /** ISO week form, e.g. 2026-W39 */
  readonly label: string;
}

import { weekNumber } from "#fune/dates.week-number@^1";

import { civilFromDays, daysFromCivil, epochDayFromIso } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { dayOfWeek } from "./dates_day_of_week.ts";  ← from dates.day-of-week ^1.0.0 · built alongside by fune
import { type IsoWeek } from "./dates_week_number_types.ts";

/**
 * The ISO 8601 week of a date. The Thursday of the date's Monday-to-Sunday
 * week decides everything: its calendar year is the week-year, and its day of
 * that year gives the week number.
 */
export function weekNumber(iso: string): IsoWeek {
  const thursday = epochDayFromIso(iso) + (4 - dayOfWeek(iso));
  const weekYear = civilFromDays(thursday).year;
  const week = Math.floor((thursday - daysFromCivil(weekYear, 1, 1)) / 7) + 1;
  return {
    weekYear,
    week,
    label: `${String(weekYear).padStart(4, "0")}-W${String(week).padStart(2, "0")}`,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add dates.week-number

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./dates.week-number-1.0.0-typescript.fune, or fetch it from a terminal with fune pull dates.week-number@1.0.0:typescript.

The whole function, every language, is one file too: dates.week-number-1.0.0.fune, 8,545 bytes, sha256 57419625d710371dddc8e6db21a61c341ada81dd0670f975210cf019b72de781. It installs into a project of any language.

// fune: before dates.week-number

// fune: after dates.week-number

// fune: replace dates.add-days in dates.week-number
// fune: replace dates.day-of-week in dates.week-number

// fune: step dates.week-number after <n|label>

More from the author

This is the ISO scheme only. US-style week numbers (weeks starting Sunday, week 1 containing 1 January) and "week of the month" are different questions.

The week is found from the Thursday of the date's week, whose calendar year is by definition the week-year, using the dates.add-days kernel and dates.day-of-week, so it is exact for every date from 0001-01-01 to 9999-12-31.

Files