@htilabs/platform-common-models 0.39.0 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +86 -0
  2. package/dist/age/index.cjs +136 -0
  3. package/dist/age/index.cjs.map +1 -0
  4. package/dist/age/index.d.cts +136 -0
  5. package/dist/age/index.d.ts +136 -0
  6. package/dist/age/index.js +105 -0
  7. package/dist/age/index.js.map +1 -0
  8. package/dist/index.cjs +159 -0
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.cts +2 -1
  11. package/dist/index.d.ts +2 -1
  12. package/dist/index.js +150 -0
  13. package/dist/index.js.map +1 -1
  14. package/dist/share-rules/index.cjs +822 -0
  15. package/dist/share-rules/index.cjs.map +1 -0
  16. package/dist/share-rules/index.d.cts +804 -0
  17. package/dist/share-rules/index.d.ts +804 -0
  18. package/dist/share-rules/index.js +736 -0
  19. package/dist/share-rules/index.js.map +1 -0
  20. package/dist/sharing-ceiling/index.cjs +51 -0
  21. package/dist/sharing-ceiling/index.cjs.map +1 -1
  22. package/dist/sharing-ceiling/index.d.cts +87 -1
  23. package/dist/sharing-ceiling/index.d.ts +87 -1
  24. package/dist/sharing-ceiling/index.js +47 -0
  25. package/dist/sharing-ceiling/index.js.map +1 -1
  26. package/package.json +12 -1
  27. package/src/age/__tests__/ageFromDob.test.ts +192 -0
  28. package/src/age/ageFromDob.ts +269 -0
  29. package/src/age/index.ts +8 -0
  30. package/src/index.ts +4 -0
  31. package/src/shareRules/__tests__/caseShareLane.test.ts +259 -0
  32. package/src/shareRules/__tests__/magicLinkAddresses.test.ts +107 -0
  33. package/src/shareRules/__tests__/platformApps.test.ts +133 -0
  34. package/src/shareRules/__tests__/releaseTerms.test.ts +358 -0
  35. package/src/shareRules/__tests__/senderRoiPosture.test.ts +284 -0
  36. package/src/shareRules/__tests__/sharingMethods.test.ts +105 -0
  37. package/src/shareRules/caseShareLane.ts +289 -0
  38. package/src/shareRules/index.ts +31 -0
  39. package/src/shareRules/magicLinkAddresses.ts +185 -0
  40. package/src/shareRules/platformApps.ts +168 -0
  41. package/src/shareRules/releaseTerms.ts +359 -0
  42. package/src/shareRules/reportPurposes.ts +50 -0
  43. package/src/shareRules/senderRoiPosture.ts +296 -0
  44. package/src/shareRules/sharingMethods.ts +204 -0
  45. package/src/sharingCeiling/__tests__/threadLift.test.ts +353 -0
  46. package/src/sharingCeiling/coverage.ts +63 -0
  47. package/src/sharingCeiling/defaults.ts +106 -0
  48. package/src/sharingCeiling/index.ts +7 -0
package/README.md CHANGED
@@ -16,6 +16,92 @@ Package exports are organized into a public root API and a small number of
16
16
  dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
17
17
  authoritative `exports` map.
18
18
 
19
+ ## share-rules + sharing-ceiling defaults / 0.41.0 (additive)
20
+
21
+ PAVE is adopting the shared Next Steps share window Thread already uses. The
22
+ app-independent share rules it needs lived in Thread's `@thread/shared`; this
23
+ release LIFTS them here so both apps and both servers run one copy.
24
+ **Behaviour and copy are Thread's, unchanged** (thread develop `f021be2`); the
25
+ Thread unit tests for each function are ported beside it.
26
+
27
+ `@htilabs/platform-common-models/sharing-ceiling` (and the root) gains:
28
+
29
+ - `shareDefaultScopeFor(edits, purpose, { starter?, purposeOverrides? })` →
30
+ `{ off, accountDefault }` — the account's per-purpose default (the
31
+ prototype's name): the account's `__default__` cell for the purpose, else
32
+ the platform starter's `scopeByPurpose[purpose]`; `[]` when the purpose is
33
+ off or the store could not be read (`edits === null`). Thread's
34
+ `accountSharePurposePolicy` is the same function (an alias, not a wrapper).
35
+ - `isPermittedByCeiling(scope, ceiling, code)` and
36
+ `intersectSharingCeilingLists(scope, a, b)` — Thread's two coverage
37
+ readers, with the tree passed as `scope` like every other reader here
38
+ (Thread bound its own resolver; its re-point keeps the two-argument forms).
39
+
40
+ New subpath `@htilabs/platform-common-models/share-rules` (not on the root;
41
+ pure — no mongoose, no I/O, no React, no SOT import):
42
+
43
+ - magic link: `derivesOffPlatformRecipient`, `magicLinkAddresses`,
44
+ `magicLinkAddressOverflow`, `magicLinkToText`,
45
+ `magicLinkConfidentialOverflow`, `magicLinkPocHasVisibleAddress`,
46
+ `magicLinkConfidentialOnly`, `MAGIC_LINK_MAX_ADDRESSES` (25);
47
+ - release terms (R19 method / R21 end date): `operativeReleaseOf`,
48
+ `releaseListedMethods`, `releaseMethodRefusal`, `shareExpiryUnderRelease`,
49
+ `releaseEndOfDay` / `releaseEndDay`, `shareMethodOf`,
50
+ `isBrokeredSharingMethod`, the exemptions;
51
+ - the CaseShare lane: `caseShareLandingLane`, `pickDefaultShareTeam`,
52
+ `caseShareLaneMismatch`, the refusal codes and sentences (Thread's, which
53
+ name Thread, and Thread's recorded LEADS deviation — unchanged);
54
+ - the sender's release posture: `readAuthoredRoiPosture`,
55
+ `resolveAgencyRoiPosture`, `senderRoiPostureForTeam`,
56
+ `resolveSenderRoiPosture`, `vspReleasePosture`;
57
+ - what they stand on, moved with them: `recipientPlatformFromApps`,
58
+ `recipientUsesApp`, `agencyIdKey`, `teamLandingApp` / `teamLandsIn*`;
59
+ the share-method vocabulary `SHARING_METHOD` / `SHARING_METHOD_LABELS` and
60
+ the CVC-332 release-method reading (`RELEASE_METHOD*`,
61
+ `normalizeReleaseMethod`, `readReleaseMethods`,
62
+ `sharingMethodOfReleaseMethod`, …; Thread's zod write schema stays in
63
+ Thread); the report purposes `ROI_WAIVER_EXEMPT_PURPOSES` /
64
+ `isRoiWaiverExemptPurpose`.
65
+
66
+ Release-basis codes are NOT converged here: the one basis reason these rules
67
+ read, `roi_on_file` (Thread's `on_file`; CVC-331 `signed_release`), is kept
68
+ and marked `CVC-331 convergence owed (Kickoff 12)`.
69
+
70
+ ## age / 0.40.0 (additive)
71
+
72
+ New subpath `@htilabs/platform-common-models/age` (also on the package root):
73
+ the ONE age-from-date-of-birth rule every app uses. Before it, Thread and PAVE
74
+ computed age in six hand-kept places that disagreed on an incomplete date of
75
+ birth — a person entered with birth year 2008 and no month showed as 17 (a
76
+ minor) on PAVE's profile and as 18 to PAVE's risk calculation, so the minor
77
+ risk input never fired.
78
+
79
+ - `ageFromDob(dob, today)` — whole years on the calendar date `today`, or
80
+ `null` (no year; year before 1850; birth after today at the precision it is
81
+ known). A person known to be born is never "no age": birth year = this year
82
+ with the month unknown is **0**, not `null`.
83
+ `today` is `{ y, m, d }` (or a `Date`, read as a calendar date — see
84
+ `calendarDateOf`). **Pass `today` explicitly as `{ y, m, d }` in servers**,
85
+ computed for the zone you mean — `new Date()` on a UTC server is the UTC day,
86
+ and the server and the browser would disagree on a birthday evening.
87
+ When it cannot be told whether this year's birthday has passed (month
88
+ unknown, or the birth month with the day unknown) the person is counted
89
+ **younger** — the prototype's `deriveYearsFromDob` rule (Crysta 2026-04-28),
90
+ which PAVE already carried in `packages/domain/src/personAge.ts`.
91
+ - `normalizeDob(dobLike)` — `{ m, d, y }` from the partial object, ISO
92
+ `"YYYY-MM-DD"` (read by parts, never through `new Date()`, so no time-zone
93
+ shift), partial ISO `"YYYY"` / `"YYYY-MM"`, a JS `Date` (a full date), or
94
+ `"MM/DD/YYYY"` with any part blank; `null` for anything else.
95
+ - `ageInputFromStoredDob({ dobYear, dobMonth, dobDay })` — the demographics
96
+ sub-schema's stored strings as the `ageFromDob` input; use it instead of
97
+ mapping the fields by hand.
98
+ - `calendarDateOf(date)` — the calendar date a `Date` stands for: UTC parts
99
+ when it is exactly UTC midnight (how a stored date comes back), local parts
100
+ otherwise. A `Date` date of birth must be stored as UTC midnight: a
101
+ local-midnight `Date` made east of UTC reads one day early on a UTC server
102
+ (counting the person older the day before the birthday). Prefer `{ y, m, d }`
103
+ or `ageInputFromStoredDob`.
104
+
19
105
  ## coreFunctions 1.4.0 / 0.39.0 (additive)
20
106
 
21
107
  CVC-133 `core_functions` 1.4.0: canon now marks `case_needs_action_flag_manage`
@@ -0,0 +1,136 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/age/index.ts
21
+ var age_exports = {};
22
+ __export(age_exports, {
23
+ DOB_MIN_YEAR: () => DOB_MIN_YEAR,
24
+ ageFromDob: () => ageFromDob,
25
+ ageInputFromStoredDob: () => ageInputFromStoredDob,
26
+ calendarDateOf: () => calendarDateOf,
27
+ normalizeDob: () => normalizeDob
28
+ });
29
+ module.exports = __toCommonJS(age_exports);
30
+
31
+ // src/age/ageFromDob.ts
32
+ var DOB_MIN_YEAR = 1850;
33
+ function toNullableNumber(v) {
34
+ if (v == null) return null;
35
+ if (typeof v === "string" && v.trim() === "") return null;
36
+ const n = typeof v === "number" ? v : Number(v);
37
+ return Number.isFinite(n) ? n : null;
38
+ }
39
+ function toNullableMonth(v) {
40
+ const n = toNullableNumber(v);
41
+ return n != null && n >= 1 && n <= 12 ? n : null;
42
+ }
43
+ function toNullableDay(v) {
44
+ const n = toNullableNumber(v);
45
+ return n != null && n >= 1 && n <= 31 ? n : null;
46
+ }
47
+ function toNullableYear(v) {
48
+ const n = toNullableNumber(v);
49
+ return n != null && Number.isInteger(n) && n > 0 ? n : null;
50
+ }
51
+ function isDate(v) {
52
+ return v instanceof Date || Object.prototype.toString.call(v) === "[object Date]";
53
+ }
54
+ function calendarDateOf(date) {
55
+ if (Number.isNaN(date.getTime())) return null;
56
+ const utcMidnight = date.getUTCHours() === 0 && date.getUTCMinutes() === 0 && date.getUTCSeconds() === 0 && date.getUTCMilliseconds() === 0;
57
+ return utcMidnight ? { y: date.getUTCFullYear(), m: date.getUTCMonth() + 1, d: date.getUTCDate() } : { y: date.getFullYear(), m: date.getMonth() + 1, d: date.getDate() };
58
+ }
59
+ function ageInputFromStoredDob(stored) {
60
+ return { y: stored?.dobYear ?? null, m: stored?.dobMonth ?? null, d: stored?.dobDay ?? null };
61
+ }
62
+ function normalizeDob(dobLike) {
63
+ if (dobLike == null) return null;
64
+ if (isDate(dobLike)) return calendarDateOf(dobLike);
65
+ if (typeof dobLike === "object") {
66
+ const m = toNullableMonth(dobLike.m);
67
+ const d = toNullableDay(dobLike.d);
68
+ const y = toNullableYear(dobLike.y);
69
+ if (m == null && d == null && y == null) return null;
70
+ return { m, d, y };
71
+ }
72
+ if (typeof dobLike === "string") {
73
+ const s = dobLike.trim();
74
+ if (!s) return null;
75
+ const iso = /^(\d{4})-(\d{1,2})-(\d{1,2})/.exec(s);
76
+ if (iso) {
77
+ return {
78
+ y: toNullableYear(iso[1]),
79
+ m: toNullableMonth(iso[2]),
80
+ d: toNullableDay(iso[3])
81
+ };
82
+ }
83
+ const isoPartial = /^(\d{4})(?:-(\d{1,2}))?$/.exec(s);
84
+ if (isoPartial) {
85
+ const y = toNullableYear(isoPartial[1]);
86
+ return y == null ? null : { y, m: toNullableMonth(isoPartial[2]), d: null };
87
+ }
88
+ const slash = /^(\d{0,2})\/(\d{0,2})\/(\d{0,4})$/.exec(s);
89
+ if (slash) {
90
+ const m = toNullableMonth(slash[1]);
91
+ const d = toNullableDay(slash[2]);
92
+ const y = toNullableYear(slash[3]);
93
+ if (m == null && d == null && y == null) return null;
94
+ return { m, d, y };
95
+ }
96
+ return null;
97
+ }
98
+ return null;
99
+ }
100
+ function ageFromDob(dob, today) {
101
+ const parts = normalizeDob(dob);
102
+ if (!parts || parts.y == null) return null;
103
+ const t = isDate(today) ? calendarDateOf(today) : today;
104
+ if (t == null || !Number.isInteger(t.y) || toNullableMonth(t.m) == null || toNullableDay(t.d) == null) {
105
+ return null;
106
+ }
107
+ const todayY = t.y;
108
+ const todayM = t.m;
109
+ const todayD = t.d;
110
+ if (parts.y < DOB_MIN_YEAR) return null;
111
+ if (parts.y > todayY) return null;
112
+ if (parts.y === todayY && parts.m != null) {
113
+ if (parts.m > todayM) return null;
114
+ if (parts.m === todayM && parts.d != null && parts.d > todayD) return null;
115
+ }
116
+ let birthdayPassed;
117
+ if (parts.m == null) {
118
+ birthdayPassed = false;
119
+ } else if (parts.m < todayM) {
120
+ birthdayPassed = true;
121
+ } else if (parts.m > todayM) {
122
+ birthdayPassed = false;
123
+ } else {
124
+ birthdayPassed = parts.d == null ? false : parts.d <= todayD;
125
+ }
126
+ return Math.max(0, todayY - parts.y - (birthdayPassed ? 0 : 1));
127
+ }
128
+ // Annotate the CommonJS export names for ESM import in node:
129
+ 0 && (module.exports = {
130
+ DOB_MIN_YEAR,
131
+ ageFromDob,
132
+ ageInputFromStoredDob,
133
+ calendarDateOf,
134
+ normalizeDob
135
+ });
136
+ //# sourceMappingURL=index.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../../src/age/index.ts","../../src/age/ageFromDob.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models/age\n *\n * The one age-from-date-of-birth rule every HTI app uses (see\n * `ageFromDob.ts`). Pure TypeScript: no mongoose, no I/O. Also re-exported\n * from the package root.\n */\nexport * from \"./ageFromDob.js\";\n","/**\n * Age from a date of birth — the ONE rule every HTI app uses.\n *\n * Before this module, Thread and PAVE computed age from a date of birth in six\n * hand-kept places with three different answers when the date of birth was\n * incomplete. A person entered with birth year 2008 and no month showed as 17\n * (a minor) on PAVE's profile but as 18 to PAVE's risk calculation, so the\n * minor risk input never fired. Every app now calls {@link ageFromDob}.\n *\n * The rule is the prototype's `deriveYearsFromDob` (HTI-LEADS-PAVE-Thread\n * prototype, Crysta directive 2026-04-28), which PAVE ported verbatim to\n * `packages/domain/src/personAge.ts`:\n *\n * - Whole years between the birth date and `today`.\n * - When we cannot tell whether this year's birthday has happened yet —\n * the month is unknown, or it is the birth month and the day is unknown —\n * count the person YOUNGER (assume the birthday has not happened). At the\n * 12/13 and 17/18 boundaries this picks the cautious, protective reading.\n * - No year → no age.\n * - A person who is known to be born is never \"no age\": counting younger\n * never takes the age below 0 (an infant entered with only this year as\n * the birth year is 0, a minor). Only a date of birth that is after\n * `today` — at the precision it is known — has no age.\n *\n * `today` is a calendar date the CALLER chooses (Crysta's date rule: moments\n * are stored as UTC, calendar days are local — so which day it is depends on\n * whose day you mean). Pass `{ y, m, d }`; in a server, compute it for the\n * zone you mean rather than passing `new Date()`, so the server and the\n * browser agree on a birthday evening. A `Date` is also accepted and read as\n * a calendar date (see {@link calendarDateOf}).\n *\n * A date-of-birth string is parsed into its year / month / day parts, never\n * through `new Date(string)` — that anchors \"YYYY-MM-DD\" to UTC midnight and,\n * read back with local getters, lands one day early in every negative-UTC\n * zone (the prototype's DATE-CANON note, 2026-08-25).\n *\n * Pure TypeScript: no mongoose, no I/O. Browser consumers import it from the\n * `@htilabs/platform-common-models/age` subpath.\n */\n\n/** A date of birth that may be partial: any of month, day and year can be unknown. */\nexport interface PartialDob {\n /** Month 1–12, or `null` when unknown. */\n m: number | null;\n /** Day 1–31, or `null` when unknown. */\n d: number | null;\n /** Four-digit year, or `null` when unknown. */\n y: number | null;\n}\n\n/**\n * Loose partial-DOB input: any subset of `{ m, d, y }`, as numbers or numeric\n * strings (what a form control hands back). A blank string is \"unknown\".\n */\nexport interface PartialDobLike {\n m?: number | string | null;\n d?: number | string | null;\n y?: number | string | null;\n}\n\n/**\n * Every date-of-birth shape {@link ageFromDob} accepts: the partial object; a\n * JS `Date` (a full date, read as a calendar date — see {@link calendarDateOf});\n * an ISO string `\"YYYY\"`, `\"YYYY-MM\"` or `\"YYYY-MM-DD\"` (precision by length; a\n * time suffix after the day is ignored); or the app-persisted `\"MM/DD/YYYY\"`\n * string with any part blank (`\"/05/1990\"`, `\"//2008\"`).\n */\nexport type DobLike = PartialDobLike | Date | string | null | undefined;\n\n/** A full calendar date: year, month 1–12, day 1–31. */\nexport interface CalendarDate {\n y: number;\n m: number;\n d: number;\n}\n\n/** The `today` argument of {@link ageFromDob}: a calendar date, or a `Date` read as one. */\nexport type CalendarDateLike = CalendarDate | Date;\n\n/** Earliest birth year the rule accepts (the prototype's floor). */\nexport const DOB_MIN_YEAR = 1850;\n\nfunction toNullableNumber(v: number | string | null | undefined): number | null {\n if (v == null) return null;\n if (typeof v === \"string\" && v.trim() === \"\") return null;\n const n = typeof v === \"number\" ? v : Number(v);\n return Number.isFinite(n) ? n : null;\n}\n\n/** A month outside 1–12 is not a month. */\nfunction toNullableMonth(v: number | string | null | undefined): number | null {\n const n = toNullableNumber(v);\n return n != null && n >= 1 && n <= 12 ? n : null;\n}\n\n/** A day outside 1–31 is not a day. */\nfunction toNullableDay(v: number | string | null | undefined): number | null {\n const n = toNullableNumber(v);\n return n != null && n >= 1 && n <= 31 ? n : null;\n}\n\n/** A year must be a positive whole number. */\nfunction toNullableYear(v: number | string | null | undefined): number | null {\n const n = toNullableNumber(v);\n return n != null && Number.isInteger(n) && n > 0 ? n : null;\n}\n\nfunction isDate(v: unknown): v is Date {\n return v instanceof Date || Object.prototype.toString.call(v) === \"[object Date]\";\n}\n\n/**\n * The calendar date a `Date` stands for, or `null` for an invalid `Date`.\n *\n * A `Date` at exactly UTC midnight is read by its UTC parts: that is how a\n * calendar date is stored (mongoose / JSON `\"2008-03-01T00:00:00.000Z\"`), and\n * local getters would land a day early west of UTC. Any other `Date` is read\n * by its local parts — `new Date(2008, 2, 1)` is 1 March in every zone, and\n * `new Date()` is the local day of the process that made it.\n *\n * A `Date` date of birth must be stored as UTC midnight. A local-midnight\n * `Date` made in a zone east of UTC is NOT supported: `new Date(2000, 2, 1)`\n * made in Berlin is `2000-02-29T23:00Z` and reads as 29 February on a UTC\n * server — one day early, so the person is counted older the day before the\n * birthday. The zone it was made in is lost, so no rule can recover it; prefer\n * `{ y, m, d }` or {@link ageInputFromStoredDob}.\n */\nexport function calendarDateOf(date: Date): CalendarDate | null {\n if (Number.isNaN(date.getTime())) return null;\n const utcMidnight =\n date.getUTCHours() === 0 &&\n date.getUTCMinutes() === 0 &&\n date.getUTCSeconds() === 0 &&\n date.getUTCMilliseconds() === 0;\n return utcMidnight\n ? { y: date.getUTCFullYear(), m: date.getUTCMonth() + 1, d: date.getUTCDate() }\n : { y: date.getFullYear(), m: date.getMonth() + 1, d: date.getDate() };\n}\n\n/**\n * The `{ dobYear, dobMonth, dobDay }` strings as stored on the demographics\n * sub-schema (`schemas/common.ts`), lifted into the `{ y, m, d }` input of\n * {@link ageFromDob}. Use it instead of mapping the fields by hand.\n */\nexport function ageInputFromStoredDob(stored: {\n dobYear?: string | number | null;\n dobMonth?: string | number | null;\n dobDay?: string | number | null;\n} | null | undefined): PartialDobLike {\n return { y: stored?.dobYear ?? null, m: stored?.dobMonth ?? null, d: stored?.dobDay ?? null };\n}\n\n/**\n * Lifts any accepted date-of-birth shape into `{ m, d, y }` (each part a number\n * or `null`), or `null` when nothing usable is present. An unrecognised string\n * returns `null` rather than risking an engine-dependent `new Date()` parse.\n */\nexport function normalizeDob(dobLike: DobLike): PartialDob | null {\n if (dobLike == null) return null;\n\n if (isDate(dobLike)) return calendarDateOf(dobLike);\n\n if (typeof dobLike === \"object\") {\n const m = toNullableMonth(dobLike.m);\n const d = toNullableDay(dobLike.d);\n const y = toNullableYear(dobLike.y);\n if (m == null && d == null && y == null) return null;\n return { m, d, y };\n }\n\n if (typeof dobLike === \"string\") {\n const s = dobLike.trim();\n if (!s) return null;\n\n const iso = /^(\\d{4})-(\\d{1,2})-(\\d{1,2})/.exec(s);\n if (iso) {\n return {\n y: toNullableYear(iso[1]),\n m: toNullableMonth(iso[2]),\n d: toNullableDay(iso[3]),\n };\n }\n\n // Partial ISO: \"YYYY-MM\" (day unknown) and \"YYYY\" (month and day unknown).\n const isoPartial = /^(\\d{4})(?:-(\\d{1,2}))?$/.exec(s);\n if (isoPartial) {\n const y = toNullableYear(isoPartial[1]);\n return y == null ? null : { y, m: toNullableMonth(isoPartial[2]), d: null };\n }\n\n const slash = /^(\\d{0,2})\\/(\\d{0,2})\\/(\\d{0,4})$/.exec(s);\n if (slash) {\n const m = toNullableMonth(slash[1]);\n const d = toNullableDay(slash[2]);\n const y = toNullableYear(slash[3]);\n if (m == null && d == null && y == null) return null;\n return { m, d, y };\n }\n\n return null;\n }\n\n return null;\n}\n\n/**\n * Whole years of age on `today`, from a full or partial date of birth — or\n * `null` when there is no usable year, the year is before {@link DOB_MIN_YEAR},\n * or the birth is after `today` at the precision it is known (a later year; this\n * year and a later month; this month and a later day). `null` also for an\n * invalid `today`.\n *\n * When it cannot be told whether this year's birthday has passed (no month, or\n * the birth month with no day), the person is counted younger — but never below\n * 0: a person known to be born is age 0 at least.\n *\n * A `Date` date of birth must be stored as UTC midnight (see\n * {@link calendarDateOf}); prefer `{ y, m, d }` or {@link ageInputFromStoredDob}.\n *\n * `today` is the calendar date the caller means — `{ y, m, d }`, or a `Date`\n * read by {@link calendarDateOf}. In a server, pass `{ y, m, d }` for the zone\n * you mean, not `new Date()` (which is the server's local, usually UTC, day).\n *\n * @example\n * // On 2026-10-24:\n * ageFromDob({ y: 2008 }, today) // 17 — month unknown, count younger\n * ageFromDob({ y: 2008, m: 10 }, today) // 17 — birth month, day unknown\n * ageFromDob({ y: 2008, m: 10, d: 24 }, today) // 18 — birthday is today\n * ageFromDob(\"2008-03-01\", today) // 18\n */\nexport function ageFromDob(dob: DobLike, today: CalendarDateLike): number | null {\n const parts = normalizeDob(dob);\n if (!parts || parts.y == null) return null;\n\n const t = isDate(today) ? calendarDateOf(today) : today;\n if (\n t == null ||\n !Number.isInteger(t.y) ||\n toNullableMonth(t.m) == null ||\n toNullableDay(t.d) == null\n ) {\n return null;\n }\n const todayY = t.y;\n const todayM = t.m;\n const todayD = t.d;\n if (parts.y < DOB_MIN_YEAR) return null;\n\n // Born after today, at the precision the date of birth is known → no age.\n if (parts.y > todayY) return null;\n if (parts.y === todayY && parts.m != null) {\n if (parts.m > todayM) return null;\n if (parts.m === todayM && parts.d != null && parts.d > todayD) return null;\n }\n\n let birthdayPassed: boolean;\n if (parts.m == null) {\n birthdayPassed = false; // month unknown → count younger\n } else if (parts.m < todayM) {\n birthdayPassed = true;\n } else if (parts.m > todayM) {\n birthdayPassed = false;\n } else {\n birthdayPassed = parts.d == null ? false : parts.d <= todayD; // day unknown → count younger\n }\n\n // Known to be born (checked above), so counting younger stops at 0.\n return Math.max(0, todayY - parts.y - (birthdayPassed ? 0 : 1));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgFO,IAAM,eAAe;AAE5B,SAAS,iBAAiB,GAAsD;AAC9E,MAAI,KAAK,KAAM,QAAO;AACtB,MAAI,OAAO,MAAM,YAAY,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,MAAM,WAAW,IAAI,OAAO,CAAC;AAC9C,SAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAClC;AAGA,SAAS,gBAAgB,GAAsD;AAC7E,QAAM,IAAI,iBAAiB,CAAC;AAC5B,SAAO,KAAK,QAAQ,KAAK,KAAK,KAAK,KAAK,IAAI;AAC9C;AAGA,SAAS,cAAc,GAAsD;AAC3E,QAAM,IAAI,iBAAiB,CAAC;AAC5B,SAAO,KAAK,QAAQ,KAAK,KAAK,KAAK,KAAK,IAAI;AAC9C;AAGA,SAAS,eAAe,GAAsD;AAC5E,QAAM,IAAI,iBAAiB,CAAC;AAC5B,SAAO,KAAK,QAAQ,OAAO,UAAU,CAAC,KAAK,IAAI,IAAI,IAAI;AACzD;AAEA,SAAS,OAAO,GAAuB;AACrC,SAAO,aAAa,QAAQ,OAAO,UAAU,SAAS,KAAK,CAAC,MAAM;AACpE;AAkBO,SAAS,eAAe,MAAiC;AAC9D,MAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,EAAG,QAAO;AACzC,QAAM,cACJ,KAAK,YAAY,MAAM,KACvB,KAAK,cAAc,MAAM,KACzB,KAAK,cAAc,MAAM,KACzB,KAAK,mBAAmB,MAAM;AAChC,SAAO,cACH,EAAE,GAAG,KAAK,eAAe,GAAG,GAAG,KAAK,YAAY,IAAI,GAAG,GAAG,KAAK,WAAW,EAAE,IAC5E,EAAE,GAAG,KAAK,YAAY,GAAG,GAAG,KAAK,SAAS,IAAI,GAAG,GAAG,KAAK,QAAQ,EAAE;AACzE;AAOO,SAAS,sBAAsB,QAIA;AACpC,SAAO,EAAE,GAAG,QAAQ,WAAW,MAAM,GAAG,QAAQ,YAAY,MAAM,GAAG,QAAQ,UAAU,KAAK;AAC9F;AAOO,SAAS,aAAa,SAAqC;AAChE,MAAI,WAAW,KAAM,QAAO;AAE5B,MAAI,OAAO,OAAO,EAAG,QAAO,eAAe,OAAO;AAElD,MAAI,OAAO,YAAY,UAAU;AAC/B,UAAM,IAAI,gBAAgB,QAAQ,CAAC;AACnC,UAAM,IAAI,cAAc,QAAQ,CAAC;AACjC,UAAM,IAAI,eAAe,QAAQ,CAAC;AAClC,QAAI,KAAK,QAAQ,KAAK,QAAQ,KAAK,KAAM,QAAO;AAChD,WAAO,EAAE,GAAG,GAAG,EAAE;AAAA,EACnB;AAEA,MAAI,OAAO,YAAY,UAAU;AAC/B,UAAM,IAAI,QAAQ,KAAK;AACvB,QAAI,CAAC,EAAG,QAAO;AAEf,UAAM,MAAM,+BAA+B,KAAK,CAAC;AACjD,QAAI,KAAK;AACP,aAAO;AAAA,QACL,GAAG,eAAe,IAAI,CAAC,CAAC;AAAA,QACxB,GAAG,gBAAgB,IAAI,CAAC,CAAC;AAAA,QACzB,GAAG,cAAc,IAAI,CAAC,CAAC;AAAA,MACzB;AAAA,IACF;AAGA,UAAM,aAAa,2BAA2B,KAAK,CAAC;AACpD,QAAI,YAAY;AACd,YAAM,IAAI,eAAe,WAAW,CAAC,CAAC;AACtC,aAAO,KAAK,OAAO,OAAO,EAAE,GAAG,GAAG,gBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,KAAK;AAAA,IAC5E;AAEA,UAAM,QAAQ,oCAAoC,KAAK,CAAC;AACxD,QAAI,OAAO;AACT,YAAM,IAAI,gBAAgB,MAAM,CAAC,CAAC;AAClC,YAAM,IAAI,cAAc,MAAM,CAAC,CAAC;AAChC,YAAM,IAAI,eAAe,MAAM,CAAC,CAAC;AACjC,UAAI,KAAK,QAAQ,KAAK,QAAQ,KAAK,KAAM,QAAO;AAChD,aAAO,EAAE,GAAG,GAAG,EAAE;AAAA,IACnB;AAEA,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AA2BO,SAAS,WAAW,KAAc,OAAwC;AAC/E,QAAM,QAAQ,aAAa,GAAG;AAC9B,MAAI,CAAC,SAAS,MAAM,KAAK,KAAM,QAAO;AAEtC,QAAM,IAAI,OAAO,KAAK,IAAI,eAAe,KAAK,IAAI;AAClD,MACE,KAAK,QACL,CAAC,OAAO,UAAU,EAAE,CAAC,KACrB,gBAAgB,EAAE,CAAC,KAAK,QACxB,cAAc,EAAE,CAAC,KAAK,MACtB;AACA,WAAO;AAAA,EACT;AACA,QAAM,SAAS,EAAE;AACjB,QAAM,SAAS,EAAE;AACjB,QAAM,SAAS,EAAE;AACjB,MAAI,MAAM,IAAI,aAAc,QAAO;AAGnC,MAAI,MAAM,IAAI,OAAQ,QAAO;AAC7B,MAAI,MAAM,MAAM,UAAU,MAAM,KAAK,MAAM;AACzC,QAAI,MAAM,IAAI,OAAQ,QAAO;AAC7B,QAAI,MAAM,MAAM,UAAU,MAAM,KAAK,QAAQ,MAAM,IAAI,OAAQ,QAAO;AAAA,EACxE;AAEA,MAAI;AACJ,MAAI,MAAM,KAAK,MAAM;AACnB,qBAAiB;AAAA,EACnB,WAAW,MAAM,IAAI,QAAQ;AAC3B,qBAAiB;AAAA,EACnB,WAAW,MAAM,IAAI,QAAQ;AAC3B,qBAAiB;AAAA,EACnB,OAAO;AACL,qBAAiB,MAAM,KAAK,OAAO,QAAQ,MAAM,KAAK;AAAA,EACxD;AAGA,SAAO,KAAK,IAAI,GAAG,SAAS,MAAM,KAAK,iBAAiB,IAAI,EAAE;AAChE;","names":[]}
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Age from a date of birth — the ONE rule every HTI app uses.
3
+ *
4
+ * Before this module, Thread and PAVE computed age from a date of birth in six
5
+ * hand-kept places with three different answers when the date of birth was
6
+ * incomplete. A person entered with birth year 2008 and no month showed as 17
7
+ * (a minor) on PAVE's profile but as 18 to PAVE's risk calculation, so the
8
+ * minor risk input never fired. Every app now calls {@link ageFromDob}.
9
+ *
10
+ * The rule is the prototype's `deriveYearsFromDob` (HTI-LEADS-PAVE-Thread
11
+ * prototype, Crysta directive 2026-04-28), which PAVE ported verbatim to
12
+ * `packages/domain/src/personAge.ts`:
13
+ *
14
+ * - Whole years between the birth date and `today`.
15
+ * - When we cannot tell whether this year's birthday has happened yet —
16
+ * the month is unknown, or it is the birth month and the day is unknown —
17
+ * count the person YOUNGER (assume the birthday has not happened). At the
18
+ * 12/13 and 17/18 boundaries this picks the cautious, protective reading.
19
+ * - No year → no age.
20
+ * - A person who is known to be born is never "no age": counting younger
21
+ * never takes the age below 0 (an infant entered with only this year as
22
+ * the birth year is 0, a minor). Only a date of birth that is after
23
+ * `today` — at the precision it is known — has no age.
24
+ *
25
+ * `today` is a calendar date the CALLER chooses (Crysta's date rule: moments
26
+ * are stored as UTC, calendar days are local — so which day it is depends on
27
+ * whose day you mean). Pass `{ y, m, d }`; in a server, compute it for the
28
+ * zone you mean rather than passing `new Date()`, so the server and the
29
+ * browser agree on a birthday evening. A `Date` is also accepted and read as
30
+ * a calendar date (see {@link calendarDateOf}).
31
+ *
32
+ * A date-of-birth string is parsed into its year / month / day parts, never
33
+ * through `new Date(string)` — that anchors "YYYY-MM-DD" to UTC midnight and,
34
+ * read back with local getters, lands one day early in every negative-UTC
35
+ * zone (the prototype's DATE-CANON note, 2026-08-25).
36
+ *
37
+ * Pure TypeScript: no mongoose, no I/O. Browser consumers import it from the
38
+ * `@htilabs/platform-common-models/age` subpath.
39
+ */
40
+ /** A date of birth that may be partial: any of month, day and year can be unknown. */
41
+ interface PartialDob {
42
+ /** Month 1–12, or `null` when unknown. */
43
+ m: number | null;
44
+ /** Day 1–31, or `null` when unknown. */
45
+ d: number | null;
46
+ /** Four-digit year, or `null` when unknown. */
47
+ y: number | null;
48
+ }
49
+ /**
50
+ * Loose partial-DOB input: any subset of `{ m, d, y }`, as numbers or numeric
51
+ * strings (what a form control hands back). A blank string is "unknown".
52
+ */
53
+ interface PartialDobLike {
54
+ m?: number | string | null;
55
+ d?: number | string | null;
56
+ y?: number | string | null;
57
+ }
58
+ /**
59
+ * Every date-of-birth shape {@link ageFromDob} accepts: the partial object; a
60
+ * JS `Date` (a full date, read as a calendar date — see {@link calendarDateOf});
61
+ * an ISO string `"YYYY"`, `"YYYY-MM"` or `"YYYY-MM-DD"` (precision by length; a
62
+ * time suffix after the day is ignored); or the app-persisted `"MM/DD/YYYY"`
63
+ * string with any part blank (`"/05/1990"`, `"//2008"`).
64
+ */
65
+ type DobLike = PartialDobLike | Date | string | null | undefined;
66
+ /** A full calendar date: year, month 1–12, day 1–31. */
67
+ interface CalendarDate {
68
+ y: number;
69
+ m: number;
70
+ d: number;
71
+ }
72
+ /** The `today` argument of {@link ageFromDob}: a calendar date, or a `Date` read as one. */
73
+ type CalendarDateLike = CalendarDate | Date;
74
+ /** Earliest birth year the rule accepts (the prototype's floor). */
75
+ declare const DOB_MIN_YEAR = 1850;
76
+ /**
77
+ * The calendar date a `Date` stands for, or `null` for an invalid `Date`.
78
+ *
79
+ * A `Date` at exactly UTC midnight is read by its UTC parts: that is how a
80
+ * calendar date is stored (mongoose / JSON `"2008-03-01T00:00:00.000Z"`), and
81
+ * local getters would land a day early west of UTC. Any other `Date` is read
82
+ * by its local parts — `new Date(2008, 2, 1)` is 1 March in every zone, and
83
+ * `new Date()` is the local day of the process that made it.
84
+ *
85
+ * A `Date` date of birth must be stored as UTC midnight. A local-midnight
86
+ * `Date` made in a zone east of UTC is NOT supported: `new Date(2000, 2, 1)`
87
+ * made in Berlin is `2000-02-29T23:00Z` and reads as 29 February on a UTC
88
+ * server — one day early, so the person is counted older the day before the
89
+ * birthday. The zone it was made in is lost, so no rule can recover it; prefer
90
+ * `{ y, m, d }` or {@link ageInputFromStoredDob}.
91
+ */
92
+ declare function calendarDateOf(date: Date): CalendarDate | null;
93
+ /**
94
+ * The `{ dobYear, dobMonth, dobDay }` strings as stored on the demographics
95
+ * sub-schema (`schemas/common.ts`), lifted into the `{ y, m, d }` input of
96
+ * {@link ageFromDob}. Use it instead of mapping the fields by hand.
97
+ */
98
+ declare function ageInputFromStoredDob(stored: {
99
+ dobYear?: string | number | null;
100
+ dobMonth?: string | number | null;
101
+ dobDay?: string | number | null;
102
+ } | null | undefined): PartialDobLike;
103
+ /**
104
+ * Lifts any accepted date-of-birth shape into `{ m, d, y }` (each part a number
105
+ * or `null`), or `null` when nothing usable is present. An unrecognised string
106
+ * returns `null` rather than risking an engine-dependent `new Date()` parse.
107
+ */
108
+ declare function normalizeDob(dobLike: DobLike): PartialDob | null;
109
+ /**
110
+ * Whole years of age on `today`, from a full or partial date of birth — or
111
+ * `null` when there is no usable year, the year is before {@link DOB_MIN_YEAR},
112
+ * or the birth is after `today` at the precision it is known (a later year; this
113
+ * year and a later month; this month and a later day). `null` also for an
114
+ * invalid `today`.
115
+ *
116
+ * When it cannot be told whether this year's birthday has passed (no month, or
117
+ * the birth month with no day), the person is counted younger — but never below
118
+ * 0: a person known to be born is age 0 at least.
119
+ *
120
+ * A `Date` date of birth must be stored as UTC midnight (see
121
+ * {@link calendarDateOf}); prefer `{ y, m, d }` or {@link ageInputFromStoredDob}.
122
+ *
123
+ * `today` is the calendar date the caller means — `{ y, m, d }`, or a `Date`
124
+ * read by {@link calendarDateOf}. In a server, pass `{ y, m, d }` for the zone
125
+ * you mean, not `new Date()` (which is the server's local, usually UTC, day).
126
+ *
127
+ * @example
128
+ * // On 2026-10-24:
129
+ * ageFromDob({ y: 2008 }, today) // 17 — month unknown, count younger
130
+ * ageFromDob({ y: 2008, m: 10 }, today) // 17 — birth month, day unknown
131
+ * ageFromDob({ y: 2008, m: 10, d: 24 }, today) // 18 — birthday is today
132
+ * ageFromDob("2008-03-01", today) // 18
133
+ */
134
+ declare function ageFromDob(dob: DobLike, today: CalendarDateLike): number | null;
135
+
136
+ export { type CalendarDate, type CalendarDateLike, DOB_MIN_YEAR, type DobLike, type PartialDob, type PartialDobLike, ageFromDob, ageInputFromStoredDob, calendarDateOf, normalizeDob };
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Age from a date of birth — the ONE rule every HTI app uses.
3
+ *
4
+ * Before this module, Thread and PAVE computed age from a date of birth in six
5
+ * hand-kept places with three different answers when the date of birth was
6
+ * incomplete. A person entered with birth year 2008 and no month showed as 17
7
+ * (a minor) on PAVE's profile but as 18 to PAVE's risk calculation, so the
8
+ * minor risk input never fired. Every app now calls {@link ageFromDob}.
9
+ *
10
+ * The rule is the prototype's `deriveYearsFromDob` (HTI-LEADS-PAVE-Thread
11
+ * prototype, Crysta directive 2026-04-28), which PAVE ported verbatim to
12
+ * `packages/domain/src/personAge.ts`:
13
+ *
14
+ * - Whole years between the birth date and `today`.
15
+ * - When we cannot tell whether this year's birthday has happened yet —
16
+ * the month is unknown, or it is the birth month and the day is unknown —
17
+ * count the person YOUNGER (assume the birthday has not happened). At the
18
+ * 12/13 and 17/18 boundaries this picks the cautious, protective reading.
19
+ * - No year → no age.
20
+ * - A person who is known to be born is never "no age": counting younger
21
+ * never takes the age below 0 (an infant entered with only this year as
22
+ * the birth year is 0, a minor). Only a date of birth that is after
23
+ * `today` — at the precision it is known — has no age.
24
+ *
25
+ * `today` is a calendar date the CALLER chooses (Crysta's date rule: moments
26
+ * are stored as UTC, calendar days are local — so which day it is depends on
27
+ * whose day you mean). Pass `{ y, m, d }`; in a server, compute it for the
28
+ * zone you mean rather than passing `new Date()`, so the server and the
29
+ * browser agree on a birthday evening. A `Date` is also accepted and read as
30
+ * a calendar date (see {@link calendarDateOf}).
31
+ *
32
+ * A date-of-birth string is parsed into its year / month / day parts, never
33
+ * through `new Date(string)` — that anchors "YYYY-MM-DD" to UTC midnight and,
34
+ * read back with local getters, lands one day early in every negative-UTC
35
+ * zone (the prototype's DATE-CANON note, 2026-08-25).
36
+ *
37
+ * Pure TypeScript: no mongoose, no I/O. Browser consumers import it from the
38
+ * `@htilabs/platform-common-models/age` subpath.
39
+ */
40
+ /** A date of birth that may be partial: any of month, day and year can be unknown. */
41
+ interface PartialDob {
42
+ /** Month 1–12, or `null` when unknown. */
43
+ m: number | null;
44
+ /** Day 1–31, or `null` when unknown. */
45
+ d: number | null;
46
+ /** Four-digit year, or `null` when unknown. */
47
+ y: number | null;
48
+ }
49
+ /**
50
+ * Loose partial-DOB input: any subset of `{ m, d, y }`, as numbers or numeric
51
+ * strings (what a form control hands back). A blank string is "unknown".
52
+ */
53
+ interface PartialDobLike {
54
+ m?: number | string | null;
55
+ d?: number | string | null;
56
+ y?: number | string | null;
57
+ }
58
+ /**
59
+ * Every date-of-birth shape {@link ageFromDob} accepts: the partial object; a
60
+ * JS `Date` (a full date, read as a calendar date — see {@link calendarDateOf});
61
+ * an ISO string `"YYYY"`, `"YYYY-MM"` or `"YYYY-MM-DD"` (precision by length; a
62
+ * time suffix after the day is ignored); or the app-persisted `"MM/DD/YYYY"`
63
+ * string with any part blank (`"/05/1990"`, `"//2008"`).
64
+ */
65
+ type DobLike = PartialDobLike | Date | string | null | undefined;
66
+ /** A full calendar date: year, month 1–12, day 1–31. */
67
+ interface CalendarDate {
68
+ y: number;
69
+ m: number;
70
+ d: number;
71
+ }
72
+ /** The `today` argument of {@link ageFromDob}: a calendar date, or a `Date` read as one. */
73
+ type CalendarDateLike = CalendarDate | Date;
74
+ /** Earliest birth year the rule accepts (the prototype's floor). */
75
+ declare const DOB_MIN_YEAR = 1850;
76
+ /**
77
+ * The calendar date a `Date` stands for, or `null` for an invalid `Date`.
78
+ *
79
+ * A `Date` at exactly UTC midnight is read by its UTC parts: that is how a
80
+ * calendar date is stored (mongoose / JSON `"2008-03-01T00:00:00.000Z"`), and
81
+ * local getters would land a day early west of UTC. Any other `Date` is read
82
+ * by its local parts — `new Date(2008, 2, 1)` is 1 March in every zone, and
83
+ * `new Date()` is the local day of the process that made it.
84
+ *
85
+ * A `Date` date of birth must be stored as UTC midnight. A local-midnight
86
+ * `Date` made in a zone east of UTC is NOT supported: `new Date(2000, 2, 1)`
87
+ * made in Berlin is `2000-02-29T23:00Z` and reads as 29 February on a UTC
88
+ * server — one day early, so the person is counted older the day before the
89
+ * birthday. The zone it was made in is lost, so no rule can recover it; prefer
90
+ * `{ y, m, d }` or {@link ageInputFromStoredDob}.
91
+ */
92
+ declare function calendarDateOf(date: Date): CalendarDate | null;
93
+ /**
94
+ * The `{ dobYear, dobMonth, dobDay }` strings as stored on the demographics
95
+ * sub-schema (`schemas/common.ts`), lifted into the `{ y, m, d }` input of
96
+ * {@link ageFromDob}. Use it instead of mapping the fields by hand.
97
+ */
98
+ declare function ageInputFromStoredDob(stored: {
99
+ dobYear?: string | number | null;
100
+ dobMonth?: string | number | null;
101
+ dobDay?: string | number | null;
102
+ } | null | undefined): PartialDobLike;
103
+ /**
104
+ * Lifts any accepted date-of-birth shape into `{ m, d, y }` (each part a number
105
+ * or `null`), or `null` when nothing usable is present. An unrecognised string
106
+ * returns `null` rather than risking an engine-dependent `new Date()` parse.
107
+ */
108
+ declare function normalizeDob(dobLike: DobLike): PartialDob | null;
109
+ /**
110
+ * Whole years of age on `today`, from a full or partial date of birth — or
111
+ * `null` when there is no usable year, the year is before {@link DOB_MIN_YEAR},
112
+ * or the birth is after `today` at the precision it is known (a later year; this
113
+ * year and a later month; this month and a later day). `null` also for an
114
+ * invalid `today`.
115
+ *
116
+ * When it cannot be told whether this year's birthday has passed (no month, or
117
+ * the birth month with no day), the person is counted younger — but never below
118
+ * 0: a person known to be born is age 0 at least.
119
+ *
120
+ * A `Date` date of birth must be stored as UTC midnight (see
121
+ * {@link calendarDateOf}); prefer `{ y, m, d }` or {@link ageInputFromStoredDob}.
122
+ *
123
+ * `today` is the calendar date the caller means — `{ y, m, d }`, or a `Date`
124
+ * read by {@link calendarDateOf}. In a server, pass `{ y, m, d }` for the zone
125
+ * you mean, not `new Date()` (which is the server's local, usually UTC, day).
126
+ *
127
+ * @example
128
+ * // On 2026-10-24:
129
+ * ageFromDob({ y: 2008 }, today) // 17 — month unknown, count younger
130
+ * ageFromDob({ y: 2008, m: 10 }, today) // 17 — birth month, day unknown
131
+ * ageFromDob({ y: 2008, m: 10, d: 24 }, today) // 18 — birthday is today
132
+ * ageFromDob("2008-03-01", today) // 18
133
+ */
134
+ declare function ageFromDob(dob: DobLike, today: CalendarDateLike): number | null;
135
+
136
+ export { type CalendarDate, type CalendarDateLike, DOB_MIN_YEAR, type DobLike, type PartialDob, type PartialDobLike, ageFromDob, ageInputFromStoredDob, calendarDateOf, normalizeDob };
@@ -0,0 +1,105 @@
1
+ // src/age/ageFromDob.ts
2
+ var DOB_MIN_YEAR = 1850;
3
+ function toNullableNumber(v) {
4
+ if (v == null) return null;
5
+ if (typeof v === "string" && v.trim() === "") return null;
6
+ const n = typeof v === "number" ? v : Number(v);
7
+ return Number.isFinite(n) ? n : null;
8
+ }
9
+ function toNullableMonth(v) {
10
+ const n = toNullableNumber(v);
11
+ return n != null && n >= 1 && n <= 12 ? n : null;
12
+ }
13
+ function toNullableDay(v) {
14
+ const n = toNullableNumber(v);
15
+ return n != null && n >= 1 && n <= 31 ? n : null;
16
+ }
17
+ function toNullableYear(v) {
18
+ const n = toNullableNumber(v);
19
+ return n != null && Number.isInteger(n) && n > 0 ? n : null;
20
+ }
21
+ function isDate(v) {
22
+ return v instanceof Date || Object.prototype.toString.call(v) === "[object Date]";
23
+ }
24
+ function calendarDateOf(date) {
25
+ if (Number.isNaN(date.getTime())) return null;
26
+ const utcMidnight = date.getUTCHours() === 0 && date.getUTCMinutes() === 0 && date.getUTCSeconds() === 0 && date.getUTCMilliseconds() === 0;
27
+ return utcMidnight ? { y: date.getUTCFullYear(), m: date.getUTCMonth() + 1, d: date.getUTCDate() } : { y: date.getFullYear(), m: date.getMonth() + 1, d: date.getDate() };
28
+ }
29
+ function ageInputFromStoredDob(stored) {
30
+ return { y: stored?.dobYear ?? null, m: stored?.dobMonth ?? null, d: stored?.dobDay ?? null };
31
+ }
32
+ function normalizeDob(dobLike) {
33
+ if (dobLike == null) return null;
34
+ if (isDate(dobLike)) return calendarDateOf(dobLike);
35
+ if (typeof dobLike === "object") {
36
+ const m = toNullableMonth(dobLike.m);
37
+ const d = toNullableDay(dobLike.d);
38
+ const y = toNullableYear(dobLike.y);
39
+ if (m == null && d == null && y == null) return null;
40
+ return { m, d, y };
41
+ }
42
+ if (typeof dobLike === "string") {
43
+ const s = dobLike.trim();
44
+ if (!s) return null;
45
+ const iso = /^(\d{4})-(\d{1,2})-(\d{1,2})/.exec(s);
46
+ if (iso) {
47
+ return {
48
+ y: toNullableYear(iso[1]),
49
+ m: toNullableMonth(iso[2]),
50
+ d: toNullableDay(iso[3])
51
+ };
52
+ }
53
+ const isoPartial = /^(\d{4})(?:-(\d{1,2}))?$/.exec(s);
54
+ if (isoPartial) {
55
+ const y = toNullableYear(isoPartial[1]);
56
+ return y == null ? null : { y, m: toNullableMonth(isoPartial[2]), d: null };
57
+ }
58
+ const slash = /^(\d{0,2})\/(\d{0,2})\/(\d{0,4})$/.exec(s);
59
+ if (slash) {
60
+ const m = toNullableMonth(slash[1]);
61
+ const d = toNullableDay(slash[2]);
62
+ const y = toNullableYear(slash[3]);
63
+ if (m == null && d == null && y == null) return null;
64
+ return { m, d, y };
65
+ }
66
+ return null;
67
+ }
68
+ return null;
69
+ }
70
+ function ageFromDob(dob, today) {
71
+ const parts = normalizeDob(dob);
72
+ if (!parts || parts.y == null) return null;
73
+ const t = isDate(today) ? calendarDateOf(today) : today;
74
+ if (t == null || !Number.isInteger(t.y) || toNullableMonth(t.m) == null || toNullableDay(t.d) == null) {
75
+ return null;
76
+ }
77
+ const todayY = t.y;
78
+ const todayM = t.m;
79
+ const todayD = t.d;
80
+ if (parts.y < DOB_MIN_YEAR) return null;
81
+ if (parts.y > todayY) return null;
82
+ if (parts.y === todayY && parts.m != null) {
83
+ if (parts.m > todayM) return null;
84
+ if (parts.m === todayM && parts.d != null && parts.d > todayD) return null;
85
+ }
86
+ let birthdayPassed;
87
+ if (parts.m == null) {
88
+ birthdayPassed = false;
89
+ } else if (parts.m < todayM) {
90
+ birthdayPassed = true;
91
+ } else if (parts.m > todayM) {
92
+ birthdayPassed = false;
93
+ } else {
94
+ birthdayPassed = parts.d == null ? false : parts.d <= todayD;
95
+ }
96
+ return Math.max(0, todayY - parts.y - (birthdayPassed ? 0 : 1));
97
+ }
98
+ export {
99
+ DOB_MIN_YEAR,
100
+ ageFromDob,
101
+ ageInputFromStoredDob,
102
+ calendarDateOf,
103
+ normalizeDob
104
+ };
105
+ //# sourceMappingURL=index.js.map