education.school-year-group

export function schoolYearGroup(birthDate: string, onDate: string, nation: UkNation): SchoolYearGroup

export type UkNation = "england" | "wales" | "scotland" | "northern-ireland";

/** Where a child of that age sits in the school system on a date. */
export interface SchoolYearGroup {
  /** first day of the school year containing onDate, for this calculation */
  readonly schoolYearStart: string;
  /** calendar year the child's cohort starts Reception or P1 */
  readonly entryYear: number;
  /** years since that start: 0 is Reception or P1, negative before it */
  readonly index: number;
  /** Reception, Year 1 ... Year 13; P1 ... S6; P1 ... Year 14; null before or after school */
  readonly yearGroup: string | null;
  /** primary or secondary; null when yearGroup is */
  readonly stage: string | null;
}

import { schoolYearGroup } from "#fune/education.school-year-group@^1";

import { parseIsoDate } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { COHORT_RULES, YEAR_GROUPS } from "./education_school_year_group_data.ts";  ← this capability’s own data, compiled from data/cohort-rules.json into the same file by fune build
import { type SchoolYearGroup, type UkNation } from "./education_school_year_group_types.ts";

/**
 * The year group a child is in on a date, placed by their birth date.
 *
 * The cohort comes from the birth date itself (born on or after the cohort
 * start joins a year later), never from an age on a cut-off date, which
 * misplaces 29 February births where the cohort starts on 1 March.
 */
export function schoolYearGroup(birthDate: string, onDate: string, nation: UkNation): SchoolYearGroup {
  const birth = parseIsoDate(birthDate);
  const on = parseIsoDate(onDate);
  if (onDate < birthDate) {
    throw new RangeError(`onDate ${onDate} is before birthDate ${birthDate}`);
  }
  const rule = COHORT_RULES.find((r) => r.nation === nation);
  if (rule === undefined) {
    throw new RangeError(`unknown nation "${nation}": use england, wales, scotland or northern-ireland`);
  }
  const birthMonthDay = birthDate.slice(5);
  const onMonthDay = onDate.slice(5);
  const entryYear = birth.year + rule.entryAge + (birthMonthDay >= rule.cohortStart ? 1 : 0);
  const startYear = onMonthDay >= rule.schoolYearStart ? on.year : on.year - 1;
  const index = startYear - entryYear;
  const name = YEAR_GROUPS.find((g) => g.nation === nation && g.index === index);
  return {
    schoolYearStart: `${String(startYear).padStart(4, "0")}-${rule.schoolYearStart}`,
    entryYear,
    index,
    yearGroup: name === undefined ? null : name.label,
    stage: name === undefined ? null : name.stage,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, 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 education.school-year-group

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./education.school-year-group-1.0.1-typescript.fune, or fetch it from a terminal with fune pull education.school-year-group@1.0.1:typescript.

The whole function, every language, is one file too: education.school-year-group-1.0.1.fune, 25,255 bytes, sha256 f3210b5447a1609ada7aa234b73029f9222291daf2c7c1cdc506f4556ffe4ef4. It installs into a project of any language.

// fune: before education.school-year-group

// fune: after education.school-year-group

// fune: replace dates.add-days in education.school-year-group

// fune: step education.school-year-group after <n|label>

More from the author

## How it works, and the leap-day trap

The cohort is decided from the birth date itself: a child born on or after the nation's cohort start date (1 September, 1 March, 2 July) joins the class that starts the year after four years on; one born before it, the year before. The school year containing `onDate` then gives how many years along they are.

Working from the child's *age* on a cut-off date instead goes wrong on 29 February in Scotland: a child born 29 February 2020 is in the cohort born 1 March 2019 to 29 February 2020, but has the same age as the 1 March 2020 children on every late-February date in later years (a birthday of 29 February counts as 1 March in common years). A vector pins it.

## Decisions

- **School year boundaries** are 1 September (England, Wales, Northern Ireland) and 1 August (Scotland, whose schools go back mid-August; each council sets the exact day). A date between that boundary and the first day of term is placed in the new year group. - `index` is always returned; `yearGroup` is null before Reception or P1 (nursery and pre-school are not named) and after the last year. - Deferred entry (Scotland's January and February births, summer-born children in England, Northern Ireland's 1 April to 1 July births) and children educated out of their year group are the caller's to apply: shift `index` by the years deferred. - The rules are long-standing conventions rather than dated rates, so the tables carry no `effective` columns and always ship whole.

## Sources

- GOV.UK, "School admissions: school starting age" ("Most children start reception full-time in September after their fourth birthday"): https://www.gov.uk/schools-admissions/school-starting-age - mygov.scot, "Choosing a school for your child", and Education Scotland Parentzone, "Starting school" (a year group is born between the start of March and the end of February; P1 starts in August): https://www.mygov.scot/register-your-child-for-a-school , https://education.gov.scot/parentzone/my-child/transitions/starting-school - nidirect, "Deferral of pre-school or primary school places", and Department of Education NI, "Compulsory education" (children aged 4 on or before 1 July start P1 that September): https://www.nidirect.gov.uk/articles/deferral-pre-school-or-primary-school-places , https://www.education-ni.gov.uk/articles/compulsory-education

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files