feat(validation): add isoDateTime with a refusal counter for instants without seconds

This commit is contained in:
Marc-André Bombeck committed 2026-10-16 03:57:45 +02:00
1 parent b1c19dcfa4
commit 92b361c3c6
5 files changed
+293

No files matched your search

@@ -0,0 +1,58 @@
import { describe, expect, it, vi } from "vitest";
import {
DATETIME_NO_SECONDS_MESSAGE,
isoDateTime,
registerDatetimeNoSecondsObserver,
} from "@/lib/validations/datetime";
describe("isoDateTime", () => {
it("accepts an instant with seconds, with or without fraction and offset", () => {
const s = isoDateTime();
for (const v of [
"2026-10-15T06:15:00Z",
"2026-10-15T06:15:00.000Z",
"2026-10-15T06:15:00.123456Z",
"2026-10-15T06:15:00+02:00",
]) {
expect(s.safeParse(v).success, v).toBe(true);
}
});
it("refuses a minute-precision instant and says seconds are missing", () => {
for (const v of ["2026-10-15T06:15Z", "2026-10-15T06:15+02:00"]) {
const r = isoDateTime().safeParse(v);
expect(r.success, v).toBe(false);
expect(r.error?.issues[0].message).toBe(DATETIME_NO_SECONDS_MESSAGE);
}
});
it("keeps the caller's message for every other refusal", () => {
const s = isoDateTime({ offset: false, message: "takenAt is bad" });
expect(s.safeParse("yesterday").error?.issues[0].message).toBe(
"takenAt is bad",
);
expect(s.safeParse("2026-10-15T06:15Z").error?.issues[0].message).toBe(
DATETIME_NO_SECONDS_MESSAGE,
);
});
it("offset: false accepts only Z and does not count an offset form", () => {
const s = isoDateTime({ offset: false });
expect(s.safeParse("2026-10-15T06:15:00Z").success).toBe(true);
expect(s.safeParse("2026-10-15T06:15:00+02:00").success).toBe(false);
expect(
s.safeParse("2026-10-15T06:15+02:00").error?.issues[0].message,
).not.toBe(DATETIME_NO_SECONDS_MESSAGE);
});
it("tells the observer about minute-precision refusals only", () => {
const seen = vi.fn();
registerDatetimeNoSecondsObserver(seen);
const s = isoDateTime();
s.safeParse("2026-10-15T06:15Z");
s.safeParse("not a date");
s.safeParse("2026-10-15T06:15:00Z");
expect(seen).toHaveBeenCalledTimes(1);
});
});
+89
View File
@@ -0,0 +1,89 @@
/**
* The one ISO 8601 instant validator every schema uses.
*
* Since v1.43 an instant must carry seconds: `2026-10-15T06:15:00Z`,
* `2026-10-15T06:15:00.000Z` and `2026-10-15T06:15:00+02:00` pass,
* `2026-10-15T06:15Z` is refused. zod 4.5 made that the behaviour of
* `z.iso.datetime()`; routing every call site through this helper keeps the
* rule in one place, gives the refusal a message that says what is missing,
* and counts each refusal so a client that still sends minute-precision
* instants shows up in the logs before its users do.
*
* `src/__tests__/datetime-helper-guard.test.ts` forbids a direct
* `z.iso.datetime(` or `z.string().datetime(` anywhere else under `src/`.
*
* Client-safe: the counter goes through an observer the server logging module
* registers on import (the same pattern as `registerSourcePriorityParseObserver`),
* so a form that validates with these schemas never pulls `node:async_hooks`
* into the browser bundle.
*/
import { z } from "zod/v4";
/** Wide-event meta key: how many instants this request refused for lacking seconds. */
export const DATETIME_NO_SECONDS_COUNTER = "validation.datetime.no_seconds";
/** Message for an instant that would be valid if it carried seconds. */
export const DATETIME_NO_SECONDS_MESSAGE =
"Invalid ISO datetime: seconds are required (YYYY-MM-DDTHH:mm:ssZ)";
// Date, hours and minutes, then an optional zone and nothing else: the shape a
// minute-precision encoder produces. Only this shape counts, so the counter
// measures exactly the clients the seconds rule turned away and not every
// malformed string. A field that requires `Z` does not count an offset form,
// which it would refuse with seconds too.
const MINUTE_PRECISION_OFFSET =
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})$/;
const MINUTE_PRECISION_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z$/;
type NoSecondsObserver = () => void;
let noSecondsObserver: NoSecondsObserver = () => {};
/**
* Server-side opt-in for the refusal counter. Called once from
* `@/lib/logging/context`; the browser keeps the no-op default.
*/
export function registerDatetimeNoSecondsObserver(
observer: NoSecondsObserver,
): void {
noSecondsObserver = observer;
}
export interface IsoDateTimeOptions {
/**
* Accept a numeric UTC offset (`+02:00`) besides `Z`. Default `true`;
* `false` keeps the handful of fields that have always required `Z`.
*/
offset?: boolean;
/** Message for every other refusal; zod's default when omitted. */
message?: string;
}
/**
* An ISO 8601 instant with seconds. Use it for every timestamp a schema
* accepts or publishes; chain `.optional()`, `.nullable()`, `.describe()` and
* `.meta()` as on any zod string.
*/
export function isoDateTime(options: IsoDateTimeOptions = {}) {
const { offset = true, message } = options;
const minutePrecision = offset
? MINUTE_PRECISION_OFFSET
: MINUTE_PRECISION_UTC;
return (
z.iso
.datetime({
offset,
// zod builds issue messages lazily, when a caller first reads them,
// so this callback only words the refusal; it cannot count it.
error: (issue) =>
typeof issue.input === "string" && minutePrecision.test(issue.input)
? DATETIME_NO_SECONDS_MESSAGE
: message,
})
// The count runs here instead: a refinement runs on every parse of a
// string, even after the format check failed, and adds no issue.
.refine((value) => {
if (minutePrecision.test(value)) noSecondsObserver();
return true;
})
);
}