@messagevisor/sdk 0.0.1 → 0.1.0

package/src/evaluation-edges.spec.ts

@@ -0,0 +1,294 @@
+import type { Context, DatafileContent, Segment } from "@messagevisor/types";
+
+import { evaluateCondition, evaluateGroupSegment } from "./conditions";
+import { createMessagevisor } from "./index";
+
+const edgeContext: Context = {
+  zero: 0,
+  falseValue: false,
+  emptyString: "",
+  nested: {
+    zero: {
+      value: 0,
+    },
+    falseValue: {
+      value: false,
+    },
+    emptyString: {
+      value: "",
+    },
+  },
+  numericString: "42",
+  nonNumericString: "forty-two",
+  list: ["alpha", "beta"],
+};
+
+const datafile: DatafileContent = {
+  schemaVersion: "1",
+  messagevisorVersion: "0.0.1",
+  revision: "1",
+  target: "web",
+  locale: "en-US",
+  formats: {},
+  segments: {
+    "zero-segment": {
+      conditions: { attribute: "zero", operator: "equals", value: 0 },
+    },
+    "false-segment": {
+      conditions: { attribute: "falseValue", operator: "equals", value: false },
+    },
+    "empty-string-segment": {
+      conditions: { attribute: "emptyString", operator: "equals", value: "" },
+    },
+  },
+  messages: {
+    "empty.translation": {},
+    "zero.override": {
+      overrides: [
+        {
+          key: "zero",
+          segments: "zero-segment",
+          translation: "Zero matched",
+        },
+      ],
+    },
+    "false.override": {
+      overrides: [
+        {
+          key: "false",
+          segments: "false-segment",
+          translation: "False matched",
+        },
+      ],
+    },
+    "empty.override": {
+      overrides: [
+        {
+          key: "empty",
+          segments: "empty-string-segment",
+          translation: "Empty matched",
+        },
+      ],
+    },
+    "empty.override.withFallback": {
+      overrides: [
+        {
+          key: "empty",
+          segments: "empty-string-segment",
+          translation: "",
+        },
+      ],
+    },
+    "deprecated.override": {
+      deprecated: true,
+      deprecationWarning: "Use replacement.override.",
+      overrides: [
+        {
+          key: "zero",
+          segments: "zero-segment",
+          translation: "Deprecated override",
+        },
+      ],
+    },
+  },
+  translations: {
+    "empty.translation": "",
+    "zero.override": "Zero default",
+    "false.override": "False default",
+    "empty.override": "Empty default",
+    "empty.override.withFallback": "Empty override default",
+    "deprecated.override": "Deprecated default",
+  },
+};
+
+describe("condition and evaluation edge cases", function () {
+  let consoleInfoSpy: jest.SpyInstance;
+  let consoleErrorSpy: jest.SpyInstance;
+
+  beforeEach(function () {
+    consoleInfoSpy = jest.spyOn(console, "info").mockImplementation(function () {});
+    consoleErrorSpy = jest.spyOn(console, "error").mockImplementation(function () {});
+  });
+
+  afterEach(function () {
+    consoleInfoSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("treats top-level falsy values as valid condition values", function () {
+    expect(
+      evaluateCondition(
+        { attribute: "zero", operator: "equals", value: 0 },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "falseValue", operator: "equals", value: false },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "emptyString", operator: "equals", value: "" },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition({ attribute: "zero", operator: "exists" }, { context: edgeContext }),
+    ).toEqual(true);
+    expect(
+      evaluateCondition({ attribute: "falseValue", operator: "exists" }, { context: edgeContext }),
+    ).toEqual(true);
+    expect(
+      evaluateCondition({ attribute: "emptyString", operator: "exists" }, { context: edgeContext }),
+    ).toEqual(true);
+  });
+
+  it("documents nested falsy traversal behavior for future SDK ports", function () {
+    expect(
+      evaluateCondition(
+        { attribute: "nested.zero.value", operator: "equals", value: 0 },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "nested.falseValue.value", operator: "equals", value: false },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "nested.emptyString.value", operator: "equals", value: "" },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+  });
+
+  it("uses JavaScript number coercion for numeric comparisons", function () {
+    expect(
+      evaluateCondition(
+        { attribute: "numericString", operator: "greaterThan", value: 41 },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "numericString", operator: "lessThanOrEquals", value: 42 },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "nonNumericString", operator: "greaterThan", value: 1 },
+        { context: edgeContext },
+      ),
+    ).toEqual(false);
+  });
+
+  it("evaluates array conditions as all-of and group segment arrays as all-of", function () {
+    const segments: Record<string, Segment> = {
+      a: { conditions: { attribute: "zero", operator: "equals", value: 0 } },
+      b: { conditions: { attribute: "falseValue", operator: "equals", value: false } },
+      c: { conditions: { attribute: "emptyString", operator: "equals", value: "not-empty" } },
+    };
+
+    expect(
+      evaluateCondition(
+        [
+          { attribute: "zero", operator: "equals", value: 0 },
+          { attribute: "falseValue", operator: "equals", value: false },
+        ],
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(evaluateGroupSegment(["a", "b"], { context: edgeContext, segments })).toEqual(true);
+    expect(evaluateGroupSegment(["a", "c"], { context: edgeContext, segments })).toEqual(false);
+  });
+
+  it("returns empty datafile translations as explicit values", function () {
+    const m = createMessagevisor({
+      datafile,
+      logLevel: "fatal",
+    });
+
+    expect(m.translate("empty.translation")).toEqual("");
+    expect(
+      m.translate("empty.translation", undefined, {
+        defaultTranslation: "Default",
+      }),
+    ).toEqual("");
+  });
+
+  it("uses falsy context values when evaluating message overrides", function () {
+    const m = createMessagevisor({
+      datafile,
+      context: {
+        zero: 0,
+        falseValue: false,
+        emptyString: "",
+      },
+      logLevel: "fatal",
+    });
+
+    expect(m.translate("zero.override")).toEqual("Zero matched");
+    expect(m.translate("false.override")).toEqual("False matched");
+    expect(m.translate("empty.override")).toEqual("Empty matched");
+  });
+
+  it("returns empty matching overrides as explicit values", function () {
+    const m = createMessagevisor({
+      datafile,
+      context: { emptyString: "" },
+      defaultTranslations: {
+        "en-US": {
+          "empty.override.withFallback": "Fallback override",
+        },
+      },
+      logLevel: "fatal",
+    });
+
+    expect(m.translate("empty.override.withFallback")).toEqual("");
+  });
+
+  it("emits deprecated diagnostics when a deprecated message resolves through an override", function () {
+    const diagnostics: any[] = [];
+    const m = createMessagevisor({
+      datafile,
+      context: { zero: 0 },
+      logLevel: "warn",
+      onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
+    });
+
+    expect(m.translate("deprecated.override")).toEqual("Deprecated override");
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        code: "deprecated_message",
+        messageKey: "deprecated.override",
+        deprecationWarning: "Use replacement.override.",
+      }),
+    ]);
+  });
+
+  it("documents nested traversal through primitive falsy parents", function () {
+    expect(
+      evaluateCondition(
+        { attribute: "zero.value", operator: "notExists" },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "falseValue.value", operator: "notExists" },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+    expect(
+      evaluateCondition(
+        { attribute: "emptyString.value", operator: "notExists" },
+        { context: edgeContext },
+      ),
+    ).toEqual(true);
+  });
+});

package/src/formatters.spec.ts

@@ -0,0 +1,295 @@
+import type { DatafileContent } from "@messagevisor/types";
+
+import { createMessagevisor, createMessagevisorCache } from "./index";
+
+const datafile: DatafileContent = {
+  schemaVersion: "1",
+  messagevisorVersion: "0.0.1",
+  revision: "1",
+  target: "web",
+  locale: "en-US",
+  direction: "ltr",
+  formats: {
+    number: {
+      currencyCode: { style: "currency", currency: "USD", currencyDisplay: "code" },
+      runtimeCurrency: { style: "currency", currencyDisplay: "code" },
+      precise: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+      significant3: { minimumSignificantDigits: 3, maximumSignificantDigits: 3 },
+      signAlways: { signDisplay: "always", maximumFractionDigits: 0 },
+      percent: { style: "percent", maximumFractionDigits: 1 },
+      compactShort: { notation: "compact", compactDisplay: "short" },
+      compactLong: { notation: "compact", compactDisplay: "long" },
+      unitKilometerLong: { style: "unit", unit: "kilometer", unitDisplay: "long" },
+      moneyGbp: { style: "currency", currency: "GBP" },
+      moneyJpy: { style: "currency", currency: "JPY" },
+    },
+    date: {
+      utcDate: { year: "numeric", month: "2-digit", day: "2-digit", timeZone: "UTC" },
+      runtimeDate: { year: "numeric", month: "2-digit", day: "2-digit" },
+      long: { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" },
+    },
+    time: {
+      utcTime: { hour: "2-digit", minute: "2-digit", hour12: false, timeZone: "UTC" },
+      runtimeTime: { hour: "2-digit", minute: "2-digit", hour12: false },
+      utc: { hour: "numeric", minute: "2-digit", timeZone: "UTC" },
+      zoneShort: { hour: "numeric", minute: "2-digit", timeZone: "UTC", timeZoneName: "short" },
+      zoneShortGeneric: {
+        hour: "numeric",
+        minute: "2-digit",
+        timeZone: "America/New_York",
+        timeZoneName: "shortGeneric",
+      },
+    },
+    dateTimeRange: {
+      utcRange: {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        timeZone: "UTC",
+      },
+    },
+    relative: {
+      longAuto: { numeric: "auto", style: "long" },
+      narrowAlways: { numeric: "always", style: "narrow" },
+    },
+  },
+  segments: {},
+  messages: {},
+  translations: {},
+};
+
+describe("Intl formatter helpers", function () {
+  let consoleInfoSpy: jest.SpyInstance;
+  let consoleWarnSpy: jest.SpyInstance;
+
+  beforeEach(function () {
+    consoleInfoSpy = jest.spyOn(console, "info").mockImplementation(function () {});
+    consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation(function () {});
+  });
+
+  afterEach(function () {
+    consoleInfoSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
+  });
+
+  it("reuses caller-provided cache buckets across helper methods", function () {
+    const cache = createMessagevisorCache();
+    const m = createMessagevisor({ datafile, cache, logLevel: "fatal" });
+    const date = new Date("2026-05-12T08:30:00Z");
+
+    expect(Object.keys(cache.numberFormat)).toHaveLength(0);
+    expect(Object.keys(cache.dateTimeFormat)).toHaveLength(0);
+    expect(Object.keys(cache.relativeTimeFormat)).toHaveLength(0);
+    expect(Object.keys(cache.pluralRules)).toHaveLength(0);
+
+    expect(m.formatNumber(12, "precise")).toEqual("12.00");
+    expect(m.formatNumberToParts(12, "precise").map((part) => part.type)).toContain("integer");
+    expect(Object.keys(cache.numberFormat)).toHaveLength(1);
+
+    expect(m.formatDate(date, "utcDate")).toEqual("05/12/2026");
+    expect(m.formatTime(date, "utcTime")).toEqual("08:30");
+    expect(m.formatDateToParts(date, "utcDate").map((part) => part.type)).toContain("year");
+    expect(m.formatTimeToParts(date, "utcTime").map((part) => part.type)).toContain("hour");
+    expect(Object.keys(cache.dateTimeFormat)).toHaveLength(2);
+
+    expect(m.formatRelativeTime(-1, "day", "longAuto")).toEqual("yesterday");
+    expect(m.formatRelativeTime(3, "day", "narrowAlways")).toContain("3");
+    expect(Object.keys(cache.relativeTimeFormat)).toHaveLength(2);
+
+    expect(m.formatPlural(1)).toEqual("one");
+    expect(m.formatPlural(2)).toEqual("other");
+    expect(Object.keys(cache.pluralRules)).toHaveLength(1);
+  });
+
+  it("partitions formatter caches by locale and resolved options", function () {
+    const cache = createMessagevisorCache();
+    const m = createMessagevisor({ datafile, cache, logLevel: "fatal" });
+
+    m.formatNumber(12, "precise");
+    m.formatNumber(12, "percent");
+    expect(Object.keys(cache.numberFormat)).toHaveLength(2);
+
+    m.setDatafile({ ...datafile, locale: "nl-NL", revision: "nl-1" });
+    m.setLocale("nl-NL");
+    m.formatNumber(12, "precise");
+    expect(Object.keys(cache.numberFormat)).toHaveLength(3);
+
+    m.formatDate("2026-05-12T00:00:00Z", "runtimeDate", { timeZone: "UTC" });
+    m.formatDate("2026-05-12T00:00:00Z", "runtimeDate", { timeZone: "Asia/Tokyo" });
+    expect(Object.keys(cache.dateTimeFormat)).toHaveLength(2);
+  });
+
+  it("falls back to default Intl options for unknown presets", function () {
+    const m = createMessagevisor({ datafile, logLevel: "fatal" });
+
+    expect(m.formatNumber(1200, "missing")).toEqual("1,200");
+    expect(m.formatNumberToParts(1200, "missing").map((part) => part.type)).toContain("integer");
+    expect(m.formatDate("2026-05-12T00:00:00Z", "missing", { timeZone: "UTC" })).toEqual(
+      "5/12/2026",
+    );
+    expect(m.formatTime("2026-05-12T08:30:00Z", "missing", { timeZone: "UTC" })).toEqual(
+      "5/12/2026",
+    );
+    expect(m.formatRelativeTime(-1, "day", "missing")).toEqual("1 day ago");
+  });
+
+  it("supports locale-keyed default formats before any datafile is loaded", function () {
+    const m = createMessagevisor({
+      locale: "nl-NL",
+      currency: "EUR",
+      timeZone: "UTC",
+      defaultFormats: {
+        "nl-NL": {
+          number: {
+            money: { style: "currency", currencyDisplay: "symbol" },
+          },
+          date: {
+            short: { year: "numeric", month: "2-digit", day: "2-digit" },
+          },
+          time: {
+            short: { hour: "2-digit", minute: "2-digit", hour12: false },
+          },
+        },
+      },
+      logLevel: "fatal",
+    });
+
+    expect(m.formatNumber(12, "money")).toEqual("\u20ac\u00a012,00");
+    expect(m.formatDate("2026-05-12T00:00:00Z", "short")).toEqual("12-05-2026");
+    expect(m.formatTime("2026-05-12T08:30:00Z", "short")).toEqual("08:30");
+  });
+
+  it("applies currency precedence consistently across number helpers", function () {
+    const m = createMessagevisor({ datafile, currency: "GBP", logLevel: "fatal" });
+
+    expect(m.formatNumber(12, "currencyCode")).toContain("USD");
+    expect(m.formatNumberToParts(12, "currencyCode").some((part) => part.value === "USD")).toEqual(
+      true,
+    );
+    expect(m.formatNumber(12, "runtimeCurrency")).toContain("GBP");
+    expect(m.formatNumber(12, "runtimeCurrency", { currency: "EUR" })).toContain("EUR");
+    expect(m.formatNumber(12, "runtimeCurrency")).toContain("GBP");
+    expect(m.formatNumber(12, "runtimeCurrency", { currency: "JPY" })).toContain("JPY");
+  });
+
+  it("applies time zone precedence consistently across date and time helpers", function () {
+    const m = createMessagevisor({ datafile, timeZone: "Asia/Tokyo", logLevel: "fatal" });
+    const value = "2026-05-12T23:30:00Z";
+
+    expect(m.formatDate(value, "utcDate")).toEqual("05/12/2026");
+    expect(m.formatDate(value, "runtimeDate")).toEqual("05/13/2026");
+    expect(m.formatDate(value, "runtimeDate", { timeZone: "America/New_York" })).toEqual(
+      "05/12/2026",
+    );
+    expect(m.formatTime(value, "utcTime")).toEqual("23:30");
+    expect(m.formatTime(value, "runtimeTime")).toEqual("08:30");
+    expect(m.formatTime(value, "runtimeTime", { timeZone: "America/New_York" })).toEqual("19:30");
+  });
+
+  it("formats range, list, list parts, display names, and plural categories", function () {
+    const m = createMessagevisor({ datafile, logLevel: "fatal" });
+    const start = "2026-05-12T08:00:00Z";
+    const end = "2026-05-12T09:30:00Z";
+
+    expect(m.formatDateTimeRange(start, end, "utcRange")).toContain("May 12, 2026");
+    expect(m.formatList(["A", "B", "C"], { type: "conjunction" })).toEqual("A, B, and C");
+    expect(
+      m.formatListToParts(["A", "B"], { type: "conjunction" }).map((part: any) => part.type),
+    ).toContain("element");
+    expect(m.formatDisplayName("NL", { type: "region" })).toEqual("Netherlands");
+    expect(m.formatPlural(1, { type: "ordinal" })).toEqual("one");
+    expect(m.formatPlural(2, { type: "ordinal" })).toEqual("two");
+  });
+
+  it("keeps the portable formatter contract stable across direct helpers", function () {
+    const m = createMessagevisor({ datafile, logLevel: "fatal" });
+    const when = "2026-05-12T08:30:45.678Z";
+
+    expect(m.formatNumber(1234567.891)).toEqual("1,234,567.891");
+    expect(m.formatNumber(12, "precise")).toEqual("12.00");
+    expect(m.formatNumber(12345.678, "significant3")).toEqual("12,300");
+    expect(m.formatNumber(5, "signAlways")).toEqual("+5");
+    expect(m.formatNumber(12500, "compactShort")).toEqual("13K");
+    expect(m.formatNumber(12500, "compactLong")).toEqual("13 thousand");
+    expect(m.formatNumber(42, "unitKilometerLong")).toEqual("42 kilometers");
+    expect(m.formatNumber(99.5, "moneyGbp")).toEqual("\u00a399.50");
+    expect(m.formatNumber(1999.99, "moneyJpy")).toEqual("\u00a52,000");
+    expect(m.formatNumber(0.0575, "percent")).toEqual("5.8%");
+    expect(m.formatDate(when, "utcDate")).toEqual("05/12/2026");
+    expect(m.formatDate(when, "long")).toEqual("May 12, 2026");
+    expect(m.formatTime(when, "utc")).toEqual("8:30 AM");
+    expect(m.formatTime(when, "zoneShort")).toEqual("8:30 AM UTC");
+    expect(m.formatTime(when, "zoneShortGeneric")).toEqual("4:30 AM ET");
+    expect(m.formatList(["A", "B", "C"], { type: "conjunction" })).toEqual("A, B, and C");
+    expect(m.formatDisplayName("NL", { type: "region" })).toEqual("Netherlands");
+    expect(m.formatRelativeTime(-2, "day", "longAuto")).toEqual("2 days ago");
+  });
+
+  it("uses Intl for non-Latin locale formatter output", function () {
+    const m = createMessagevisor({
+      datafile: { ...datafile, locale: "bn-BD" },
+      timeZone: "UTC",
+      logLevel: "fatal",
+    });
+    const when = "2026-05-12T08:30:45.678Z";
+
+    expect(m.formatNumber(1234567.891)).toEqual("১২,৩৪,৫৬৭.৮৯১");
+    expect(m.formatNumber(12500, "compactShort")).toEqual("১৩\u00a0হা");
+    expect(m.formatNumber(42, "unitKilometerLong")).toEqual("৪২ কিলোমিটার");
+    expect(m.formatDate(when, "utcDate")).toEqual("১২/০৫/২০২৬");
+    expect(m.formatTime(when, "zoneShort")).toEqual("৮:৩০ AM UTC");
+  });
+
+  it("falls back and reports diagnostics when optional Intl helpers are unavailable", function () {
+    const originalListFormat = (Intl as any).ListFormat;
+    const originalDisplayNames = (Intl as any).DisplayNames;
+    const diagnostics: any[] = [];
+    const m = createMessagevisor({
+      datafile,
+      logLevel: "warn",
+      onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
+    });
+
+    try {
+      (Intl as any).ListFormat = undefined;
+      (Intl as any).DisplayNames = undefined;
+
+      expect(m.formatList(["A", "B"])).toEqual("A, B");
+      expect(m.formatListToParts(["A", "B"])).toEqual(["A", "B"]);
+      expect(m.formatDisplayName("NL", { type: "region" })).toEqual("NL");
+      expect(m.formatDisplayName("NL", { type: "region", fallback: "none" })).toEqual(undefined);
+    } finally {
+      (Intl as any).ListFormat = originalListFormat;
+      (Intl as any).DisplayNames = originalDisplayNames;
+    }
+
+    expect(diagnostics).toEqual([
+      expect.objectContaining({ code: "unsupported_formatter", level: "warn" }),
+      expect.objectContaining({ code: "unsupported_formatter", level: "warn" }),
+      expect.objectContaining({ code: "unsupported_formatter", level: "warn" }),
+      expect.objectContaining({ code: "unsupported_formatter", level: "warn" }),
+    ]);
+    expect(consoleWarnSpy).not.toHaveBeenCalled();
+  });
+
+  it("uses console warnings for unsupported optional Intl helpers when no diagnostic handler exists", function () {
+    const originalDisplayNames = (Intl as any).DisplayNames;
+    const m = createMessagevisor({ datafile, logLevel: "warn" });
+
+    try {
+      (Intl as any).DisplayNames = undefined;
+      consoleWarnSpy.mockClear();
+
+      expect(m.formatDisplayName("NL", { type: "region" })).toEqual("NL");
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        "[Messagevisor]",
+        "Intl.DisplayNames is not available in this environment.",
+        expect.objectContaining({ code: "unsupported_formatter", level: "warn", locale: "en-US" }),
+      );
+    } finally {
+      (Intl as any).DisplayNames = originalDisplayNames;
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./conditions";
+export * from "./instance";