@clementine-solutions/jane-io 1.0.1 → 1.0.2

package/dist/core/validators/common/is-uuid.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is UUID
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates UUIDs (versions 1–4).
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates UUIDs (versions 1–4).
+ *
+ * Enforces canonical hyphenated formatting and correct version/variant bits,
+ * ensuring the identifier is structurally sound and standards‑compliant.
+ */
+export const isUuid = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid UUID.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-4][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.uuid', path, `${safeStringify(value)} is not a valid UUID (v1–v4).`, `Please provide a valid UUID.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/date/before-epoch.js

@@ -0,0 +1,56 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Before Epoch
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that a value is a JavaScript Date occurring before
+ *                  the Unix epoch (January 1, 1970, 00:00:00 UTC).
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates that a value is a JavaScript Date occurring before
+ * the Unix epoch (January 1, 1970, 00:00:00 UTC).
+ *
+ * This rule checks:
+ * - The value is structurally a Date instance
+ * - The date timestamp is strictly less than the Unix epoch
+ *
+ * Emits:
+ * - date.not.date        (value is not a Date)
+ * - date.not.beforeEpoch (date is on or after the Unix epoch)
+ *
+ * This rule is async-compatible and returns a readonly array
+ * of JaneEvent objects.
+ * ----------------------------------------------------------------------------
+ */
+export const beforeEpoch = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!(value instanceof Date)) {
+        return [
+            validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, {
+                value,
+                expected: 'Date',
+                actual: structuralType,
+            }),
+        ];
+    }
+    const unixEpochMilliseconds = 0;
+    const timestamp = value.getTime();
+    if (timestamp >= unixEpochMilliseconds) {
+        return [
+            validationEvent('error', 'date.is.before-epoch', path, `${safeStringify(value)} must be before the Unix epoch.`, `Please provide a date before January 1, 1970.`, {
+                value,
+                expected: '< 1970-01-01T00:00:00.000Z',
+                actual: value.toISOString(),
+            }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/date/date-now-required.js

@@ -0,0 +1,48 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Date Now Required
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance representing today's
+ *                  date.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance representing today's date.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Dates not matching today's year/month/day emit `date.now.undefined`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const dateNowRequired = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!(value instanceof Date)) {
+        return [
+            validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+        ];
+    }
+    const now = new Date();
+    const isSameDay = value.getUTCFullYear() === now.getUTCFullYear() &&
+        value.getUTCMonth() === now.getUTCMonth() &&
+        value.getUTCDate() === now.getUTCDate();
+    if (!isSameDay) {
+        return [
+            validationEvent('error', 'date.now.undefined', path, `${safeStringify(value)} must be today's date.`, `Please provide today's date.`, {
+                value,
+                expected: now.toISOString().slice(0, 10),
+                actual: value.toISOString().slice(0, 10),
+            }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/date/is-date.js

@@ -0,0 +1,47 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Date
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a valid JavaScript Date instance.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a valid JavaScript Date instance.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances (NaN timestamp) emit `date.is.invalid`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const isDate = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a Date instance.
+    // ------------------------------------------------------------
+    if (!(value instanceof Date)) {
+        return [
+            validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Validity check — ensure the Date is not "Invalid Date".
+    // ------------------------------------------------------------
+    if (isNaN(value.getTime())) {
+        return [
+            validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/date/is-far-future.js

@@ -0,0 +1,46 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Far Future
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance representing a year
+ *                  strictly greater than 2100.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance representing a year strictly
+ * greater than 2100.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Dates with year ≤ 2100 emit `date.is.far-future`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const isFarFuture = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!(value instanceof Date)) {
+        return [
+            validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+        ];
+    }
+    if (isNaN(value.getTime())) {
+        return [
+            validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+        ];
+    }
+    if (value.getUTCFullYear() <= 2100) {
+        return [
+            validationEvent('error', 'date.is.far-future', path, `${safeStringify(value)} must be after the year 2100.`, `Please provide a far-future date.`, { value, expected: '> 2100', actual: value.getUTCFullYear() }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/date/is-future.js

@@ -0,0 +1,59 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Future
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance representing a moment
+ *                  strictly after the current system time.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance representing a moment strictly
+ * after the current system time.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances emit `date.is.invalid`.
+ * - Dates ≤ now emit `date.in.past`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const isFuture = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a Date instance.
+    // ------------------------------------------------------------
+    if (!(value instanceof Date)) {
+        return [
+            validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Validity check — reject invalid Date instances.
+    // ------------------------------------------------------------
+    if (isNaN(value.getTime())) {
+        return [
+            validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Future check — must be strictly greater than now.
+    // ------------------------------------------------------------
+    if (value.getTime() <= Date.now()) {
+        return [
+            validationEvent('error', 'date.in.past', path, `${safeStringify(value)} must be in the future.`, `Please provide a future date.`, { value, expected: 'future date', actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/date/is-past.js

@@ -0,0 +1,59 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Past
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance representing a moment
+ *                  strictly before the current system time.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance representing a moment strictly
+ * before the current system time.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances emit `date.is.invalid`.
+ * - Dates ≥ now emit `date.in.future`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const isPast = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a Date instance.
+    // ------------------------------------------------------------
+    if (!(value instanceof Date)) {
+        return [
+            validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Validity check — reject invalid Date instances.
+    // ------------------------------------------------------------
+    if (isNaN(value.getTime())) {
+        return [
+            validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Past check — must be strictly less than now.
+    // ------------------------------------------------------------
+    if (value.getTime() >= Date.now()) {
+        return [
+            validationEvent('error', 'date.in.future', path, `${safeStringify(value)} must be in the past.`, `Please provide a past date.`, { value, expected: 'past date', actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/date/not-after.js

@@ -0,0 +1,66 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Not After
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance that is not after the
+ *                  provided `max` boundary.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance that is not after the
+ * provided `max` boundary. The comparison is strict: value must be
+ * ≤ max.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances emit `date.is.invalid`.
+ * - Dates > max emit `date.too.late`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const notAfter = (max) => {
+    const rule = async (value, path) => {
+        const structuralType = detectStructuralType(value);
+        // ------------------------------------------------------------
+        // Type check — the input must be a Date instance.
+        // ------------------------------------------------------------
+        if (!(value instanceof Date)) {
+            return [
+                validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Validity check — reject invalid Date instances.
+        // ------------------------------------------------------------
+        if (isNaN(value.getTime())) {
+            return [
+                validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Boundary check — must be ≤ max.
+        // ------------------------------------------------------------
+        if (value.getTime() > max.getTime()) {
+            return [
+                validationEvent('error', 'date.too.late', path, `${safeStringify(value)} must not be after ${max.toISOString()}.`, `Please provide an earlier date.`, { value, expected: `<= ${max.toISOString()}`, actual: value.toISOString() }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Valid — return an empty array to indicate success.
+        // ------------------------------------------------------------
+        return [];
+    };
+    // Mark as factory to preserve captured `max` value
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rule.__janeFactory = true;
+    return rule;
+};

package/dist/core/validators/date/not-before.js

@@ -0,0 +1,66 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Not Before
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance that is not before the
+ *                  provided `min` boundary.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance that is not before the
+ * provided `min` boundary. The comparison is inclusive: value must be
+ * ≥ min.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances emit `date.is.invalid`.
+ * - Dates < min emit `date.too.early`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const notBefore = (min) => {
+    const rule = async (value, path) => {
+        const structuralType = detectStructuralType(value);
+        // ------------------------------------------------------------
+        // Type check — the input must be a Date instance.
+        // ------------------------------------------------------------
+        if (!(value instanceof Date)) {
+            return [
+                validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Validity check — reject invalid Date instances.
+        // ------------------------------------------------------------
+        if (isNaN(value.getTime())) {
+            return [
+                validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Boundary check — must be ≥ min.
+        // ------------------------------------------------------------
+        if (value.getTime() < min.getTime()) {
+            return [
+                validationEvent('error', 'date.too.early', path, `${safeStringify(value)} must not be before ${min.toISOString()}.`, `Please provide a later date.`, { value, expected: `>= ${min.toISOString()}`, actual: value.toISOString() }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Valid — return an empty array to indicate success.
+        // ------------------------------------------------------------
+        return [];
+    };
+    // Mark as factory to preserve captured `min` value
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rule.__janeFactory = true;
+    return rule;
+};

package/dist/core/validators/date/same-day.js

@@ -0,0 +1,60 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Same Day
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance representing the same
+ *                  calendar day (year, month, day) as the provided `other`
+ *                  date.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance representing the same
+ * calendar day (year, month, day) as the provided `other` date.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances emit `date.is.invalid`.
+ * - Dates not matching the same Y/M/D emit `date.not.same-day`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const sameDay = (other) => {
+    const rule = async (value, path) => {
+        const structuralType = detectStructuralType(value);
+        if (!(value instanceof Date)) {
+            return [
+                validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+            ];
+        }
+        if (isNaN(value.getTime())) {
+            return [
+                validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+            ];
+        }
+        const isSame = value.getUTCFullYear() === other.getUTCFullYear() &&
+            value.getUTCMonth() === other.getUTCMonth() &&
+            value.getUTCDate() === other.getUTCDate();
+        if (!isSame) {
+            return [
+                validationEvent('error', 'date.not.same-day', path, `${safeStringify(value)} must be the same day as ${other.toISOString()}.`, `Please provide the correct date.`, {
+                    value,
+                    expected: other.toISOString().slice(0, 10),
+                    actual: value.toISOString().slice(0, 10),
+                }),
+            ];
+        }
+        return [];
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rule.__janeFactory = true;
+    return rule;
+};

package/dist/core/validators/date/same-month.js

@@ -0,0 +1,59 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Same Month
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a Date instance representing a date in
+ *                  the same calendar month (year + month) as the provided
+ *                  `other` date.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a Date instance representing a date in the
+ * same calendar month (year + month) as the provided `other` date.
+ *
+ * - Non-Date values emit `date.not.date`.
+ * - Invalid Date instances emit `date.is.invalid`.
+ * - Dates not matching the same Y/M emit `date.not.same-month`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const sameMonth = (other) => {
+    const rule = async (value, path) => {
+        const structuralType = detectStructuralType(value);
+        if (!(value instanceof Date)) {
+            return [
+                validationEvent('error', 'date.not.date', path, `Expected 'Date' but received '${structuralType}'.`, `Please provide a valid date.`, { value, expected: 'Date', actual: structuralType }),
+            ];
+        }
+        if (isNaN(value.getTime())) {
+            return [
+                validationEvent('error', 'date.is.invalid', path, `Date value is invalid.`, `Please provide a valid date.`, { value, expected: 'valid Date', actual: value }),
+            ];
+        }
+        const isSame = value.getUTCFullYear() === other.getUTCFullYear() &&
+            value.getUTCMonth() === other.getUTCMonth();
+        if (!isSame) {
+            return [
+                validationEvent('error', 'date.not.same-month', path, `${safeStringify(value)} must be in the same month as ${other.toISOString()}.`, `Please provide a date in the correct month.`, {
+                    value,
+                    expected: other.toISOString().slice(0, 7), // YYYY-MM
+                    actual: value.toISOString().slice(0, 7),
+                }),
+            ];
+        }
+        return [];
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rule.__janeFactory = true;
+    return rule;
+};