@actuarial-ts/core 0.6.0 → 0.7.0

package/src/diagnosticPeriodAxis.ts

@@ -0,0 +1,92 @@
+import type { DiagnosticPeriodAxis } from "./diagnosticDefinitions.js";
+
+export interface NormalizedDiagnosticAxisPeriod {
+  readonly label: string;
+  readonly coordinate: number;
+}
+
+export type DiagnosticPeriodSide = "origin" | "valuation";
+
+function calendarCoordinate(
+  label: string,
+  cadence: "month" | "quarter" | "year",
+  anchor: "start" | "end",
+): number | null {
+  let year: number;
+  let start: number;
+  let width: number;
+  if (cadence === "year") {
+    const match = /^(\d{4})$/.exec(label);
+    if (!match) return null;
+    year = Number(match[1]);
+    start = year * 12;
+    width = 12;
+  } else if (cadence === "month") {
+    const match = /^(\d{4})-(0[1-9]|1[0-2])$/.exec(label);
+    if (!match) return null;
+    year = Number(match[1]);
+    start = year * 12 + Number(match[2]) - 1;
+    width = 1;
+  } else {
+    const compact = /^(\d{4})Q([1-4])$/.exec(label);
+    const hyphenated = /^(\d{4})-Q([1-4])$/.exec(label);
+    const first = /^Q([1-4]) (\d{4})$/.exec(label);
+    const match = compact ?? hyphenated ?? first;
+    if (!match) return null;
+    const quarterFirst = match === first;
+    year = Number(match[quarterFirst ? 2 : 1]);
+    const quarter = Number(match[quarterFirst ? 1 : 2]);
+    start = year * 12 + (quarter - 1) * 3;
+    width = 3;
+  }
+  if (year < 1 || year > 9999) return null;
+  return start + (anchor === "end" ? width : 0);
+}
+
+/** Pure axis-level period normalization shared by compilation and execution. */
+export function normalizeDiagnosticPeriodWithAxis(
+  axis: DiagnosticPeriodAxis,
+  side: DiagnosticPeriodSide,
+  label: unknown,
+): NormalizedDiagnosticAxisPeriod | null {
+  if (typeof label !== "string" || axis === null || typeof axis !== "object")
+    return null;
+  if (axis.kind === "calendar") {
+    const cadence =
+      side === "origin" ? axis.originCadence : axis.valuationCadence;
+    const anchor = side === "origin" ? axis.originAnchor : axis.valuationAnchor;
+    if (
+      !["month", "quarter", "year"].includes(cadence) ||
+      !["start", "end"].includes(anchor)
+    )
+      return null;
+    const coordinate = calendarCoordinate(label, cadence, anchor);
+    if (coordinate === null) return null;
+    const canonicalLabel =
+      cadence === "quarter"
+        ? (() => {
+            const startCoordinate = calendarCoordinate(
+              label,
+              cadence,
+              "start",
+            )!;
+            const year = Math.floor(startCoordinate / 12);
+            return `${String(year).padStart(4, "0")}-Q${Math.floor((startCoordinate % 12) / 3) + 1}`;
+          })()
+        : label;
+    return { label: canonicalLabel, coordinate };
+  }
+  if (
+    axis.kind !== "ordered" ||
+    !Array.isArray(axis[side === "origin" ? "origins" : "valuations"])
+  )
+    return null;
+  const catalog = side === "origin" ? axis.origins : axis.valuations;
+  const item = catalog.find(
+    (coordinate) =>
+      coordinate?.label === label || coordinate?.aliases?.includes(label),
+  );
+  return item && typeof item.coordinate === "number"
+    ? { label: item.label, coordinate: item.coordinate }
+    : null;
+}

package/src/diagnosticPeriods.ts

@@ -1,5 +1,12 @@
-import type { CompiledDiagnosticDefinition, DiagnosticPeriodAxis } from "./diagnosticDefinitions.js";
+import type {
+  CompiledDiagnosticDefinition,
+  DiagnosticPeriodAxis,
+} from "./diagnosticDefinitions.js";
 import { assertCompiledDiagnosticDefinition } from "./diagnosticDefinitions.js";
+import {
+  normalizeDiagnosticPeriodWithAxis,
+  type DiagnosticPeriodSide,
+} from "./diagnosticPeriodAxis.js";
 import { DiagnosticValidationError } from "./types.js";
 
 export interface DiagnosticNormalizedPeriod {
@@ -7,103 +14,75 @@ export interface DiagnosticNormalizedPeriod {
   readonly coordinate: number;
 }
 
-type PeriodSide = "origin" | "valuation";
-
-function calendarCoordinate(
-  label: string,
-  cadence: "month" | "quarter" | "year",
-  anchor: "start" | "end",
-): number | null {
-  let year: number;
-  let start: number;
-  let width: number;
-  if (cadence === "year") {
-    const match = /^(\d{4})$/.exec(label);
-    if (!match) return null;
-    year = Number(match[1]);
-    start = year * 12;
-    width = 12;
-  } else if (cadence === "month") {
-    const match = /^(\d{4})-(0[1-9]|1[0-2])$/.exec(label);
-    if (!match) return null;
-    year = Number(match[1]);
-    start = year * 12 + Number(match[2]) - 1;
-    width = 1;
-  } else {
-    const compact = /^(\d{4})Q([1-4])$/.exec(label);
-    const hyphenated = /^(\d{4})-Q([1-4])$/.exec(label);
-    const first = /^Q([1-4]) (\d{4})$/.exec(label);
-    const match = compact ?? hyphenated ?? first;
-    if (!match) return null;
-    const quarterFirst = match === first;
-    year = Number(match[quarterFirst ? 2 : 1]);
-    const quarter = Number(match[quarterFirst ? 1 : 2]);
-    start = year * 12 + (quarter - 1) * 3;
-    width = 3;
-  }
-  if (year < 1 || year > 9999) return null;
-  return start + (anchor === "end" ? width : 0);
-}
-
 function normalizeWithAxis(
   axis: DiagnosticPeriodAxis,
-  side: PeriodSide,
+  side: DiagnosticPeriodSide,
   label: string,
 ): DiagnosticNormalizedPeriod {
-  if (axis.kind === "calendar") {
-    const cadence = side === "origin" ? axis.originCadence : axis.valuationCadence;
-    const anchor = side === "origin" ? axis.originAnchor : axis.valuationAnchor;
-    const coordinate = calendarCoordinate(label, cadence, anchor);
-    if (coordinate === null) throw new DiagnosticValidationError([{
-      domain: "input",
-      code: "invalid-period",
-      path: `$.${side}`,
-      message: `Invalid ${cadence} ${side} label ${JSON.stringify(label)}`,
-    }]);
-    const canonicalLabel = cadence === "quarter"
-      ? (() => {
-          const startCoordinate = calendarCoordinate(label, cadence, "start")!;
-          const year = Math.floor(startCoordinate / 12);
-          return `${String(year).padStart(4, "0")}Q${Math.floor((startCoordinate % 12) / 3) + 1}`;
-        })()
-      : label;
-    return Object.freeze({ label: canonicalLabel, coordinate });
-  }
-  const catalog = side === "origin" ? axis.origins : axis.valuations;
-  const item = catalog.find((coordinate) => coordinate.label === label || coordinate.aliases?.includes(label));
-  if (!item) throw new DiagnosticValidationError([{
-    domain: "input",
-    code: "invalid-period",
-    path: `$.${side}`,
-    message: `Unknown ordered-axis ${side} label ${JSON.stringify(label)}`,
-  }]);
-  return Object.freeze({ label: item.label, coordinate: item.coordinate });
+  const normalized = normalizeDiagnosticPeriodWithAxis(axis, side, label);
+  if (!normalized)
+    throw new DiagnosticValidationError([
+      {
+        domain: "input",
+        code: "invalid-period",
+        path: `$.${side}`,
+        message:
+          axis.kind === "calendar"
+            ? `Invalid ${side === "origin" ? axis.originCadence : axis.valuationCadence} ${side} label ${JSON.stringify(label)}`
+            : `Unknown ordered-axis ${side} label ${JSON.stringify(label)}`,
+      },
+    ]);
+  return Object.freeze(normalized);
 }
 
 export function normalizeDiagnosticPeriod(
   definition: CompiledDiagnosticDefinition,
-  side: PeriodSide,
+  side: DiagnosticPeriodSide,
   label: string,
 ): DiagnosticNormalizedPeriod {
   assertCompiledDiagnosticDefinition(definition);
-  return normalizeWithAxis(definition.definition.periodAxis as DiagnosticPeriodAxis, side, label);
+  return normalizeWithAxis(
+    definition.definition.periodAxis as DiagnosticPeriodAxis,
+    side,
+    label,
+  );
 }
 
 export function diagnosticDevelopmentAge(
   definition: CompiledDiagnosticDefinition,
   origin: string,
   valuation: string,
-): { readonly origin: DiagnosticNormalizedPeriod; readonly valuation: DiagnosticNormalizedPeriod; readonly developmentAge: number; readonly ageUnit: string } {
-  const normalizedOrigin = normalizeDiagnosticPeriod(definition, "origin", origin);
-  const normalizedValuation = normalizeDiagnosticPeriod(definition, "valuation", valuation);
+): {
+  readonly origin: DiagnosticNormalizedPeriod;
+  readonly valuation: DiagnosticNormalizedPeriod;
+  readonly developmentAge: number;
+  readonly ageUnit: string;
+} {
+  const normalizedOrigin = normalizeDiagnosticPeriod(
+    definition,
+    "origin",
+    origin,
+  );
+  const normalizedValuation = normalizeDiagnosticPeriod(
+    definition,
+    "valuation",
+    valuation,
+  );
   const axis = definition.definition.periodAxis;
-  const developmentAge = normalizedValuation.coordinate - normalizedOrigin.coordinate + axis.ageOffset;
-  if (!Number.isSafeInteger(developmentAge) || developmentAge < 0) throw new DiagnosticValidationError([{
-    domain: "input",
-    code: "invalid-period",
-    path: "$.valuation",
-    message: "Valuation period precedes origin period or development age is unsafe",
-  }]);
+  const developmentAge =
+    normalizedValuation.coordinate -
+    normalizedOrigin.coordinate +
+    axis.ageOffset;
+  if (!Number.isSafeInteger(developmentAge) || developmentAge < 0)
+    throw new DiagnosticValidationError([
+      {
+        domain: "input",
+        code: "invalid-period",
+        path: "$.valuation",
+        message:
+          "Valuation period precedes origin period or development age is unsafe",
+      },
+    ]);
   return Object.freeze({
     origin: normalizedOrigin,
     valuation: normalizedValuation,
@@ -112,6 +91,12 @@ export function diagnosticDevelopmentAge(
   });
 }
 
-export function compareDiagnosticPeriods(left: DiagnosticNormalizedPeriod, right: DiagnosticNormalizedPeriod): number {
-  return left.coordinate - right.coordinate || (left.label < right.label ? -1 : left.label > right.label ? 1 : 0);
+export function compareDiagnosticPeriods(
+  left: DiagnosticNormalizedPeriod,
+  right: DiagnosticNormalizedPeriod,
+): number {
+  return (
+    left.coordinate - right.coordinate ||
+    (left.label < right.label ? -1 : left.label > right.label ? 1 : 0)
+  );
 }