@messagevisor/types 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.2.0](https://github.com/messagevisor/messagevisor/compare/v0.1.0...v0.2.0) (2026-06-02)
+
+**Note:** Version bump only for package @messagevisor/types
+
+
+
+
+
+# [0.1.0](https://github.com/messagevisor/messagevisor/compare/v0.0.2...v0.1.0) (2026-05-31)
+
+
+### Features
+
+* trigger publish ([4699bda](https://github.com/messagevisor/messagevisor/commit/4699bdad7d077858e90aa754afefb4815c9d58c1))
+* trigger publish ([fb7ad48](https://github.com/messagevisor/messagevisor/commit/fb7ad48f01986e683588c298acdebfbcc58346d8))
+* type updates ([4006311](https://github.com/messagevisor/messagevisor/commit/4006311d2269e11342327b4c7da9572c93b64a24))
+
+
+
+
+
+## 0.0.2 (2026-05-31)
+
+**Note:** Version bump only for package @messagevisor/types

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Fahad Heylaal (https://fahad19.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @messagevisor/types
+
+> Common TypeScript typings for Messagevisor packages
+
+Visit [https://messagevisor.com](https://messagevisor.com) for more information.
+
+## License
+
+MIT © [Fahad Heylaal](https://fahad19.com)

package/package.json

@@ -1,15 +1,41 @@
 {
-	"name": "@messagevisor/types",
-	"version": "0.0.1",
-	"description": "Messagevisor package",
-	"license": "ISC",
-	"author": "",
-	"type": "commonjs",
-	"main": "index.js",
-	"publishConfig": {
-		"access": "public"
-	},
-	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
-	}
+  "name": "@messagevisor/types",
+  "version": "0.2.0",
+  "description": "Common Typescript types for Messagevisor",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "transpile": "echo 'Nothing to transpile'",
+    "dist": "echo 'Nothing to dist'",
+    "build": "tsc ./src/index.d.ts",
+    "test": "echo 'Nothing to test in types package'",
+    "typecheck": "tsc --noEmit --skipLibCheck -p tsconfig.json"
+  },
+  "author": {
+    "name": "Fahad Heylaal",
+    "url": "https://fahad19.com"
+  },
+  "homepage": "https://messagevisor.com",
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/messagevisor/messagevisor.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bugs": {
+    "url": "https://github.com/messagevisor/messagevisor/issues"
+  },
+  "license": "MIT",
+  "gitHead": "53cfef1a5ae28724b24226dd3a32ff813b063ce3"
 }

package/src/datafile.d.ts

@@ -0,0 +1,49 @@
+import type {
+  Condition,
+  GroupSegment,
+  TargetKey,
+  SegmentKey,
+  LocaleKey,
+  LocaleDirection,
+  MessageKey,
+  MessageMeta,
+  Segment,
+  Translation,
+} from "./entities";
+import type { FormatPresets } from "./format";
+
+export interface MessageOverride {
+  key: string;
+
+  // one of them need to be provided
+  conditions?: Condition | Condition[] | "*"; // string can be "*" or stringified datafile condition
+  segments?: GroupSegment | GroupSegment[] | "*"; // string can be "*", segment key, or stringified datafile segment group
+
+  translation: Translation;
+}
+
+export interface DatafileMessage {
+  deprecated?: boolean;
+  deprecationWarning?: string;
+  meta?: MessageMeta;
+  overrides?: MessageOverride[];
+}
+
+export interface DatafileContent {
+  schemaVersion: string;
+  messagevisorVersion: string;
+  revision: string;
+  target: TargetKey;
+  locale: LocaleKey;
+  direction?: LocaleDirection;
+  formats?: FormatPresets;
+  segments: {
+    [key: SegmentKey]: Segment;
+  };
+  messages: {
+    [key: MessageKey]: DatafileMessage;
+  };
+  translations: {
+    [key: MessageKey]: Translation;
+  };
+}

package/src/entities.d.ts

@@ -0,0 +1,312 @@
+import type { FormatPresets } from "./format";
+
+/**
+ * Common
+ */
+export type Matrix = Record<string, unknown[]>;
+
+export type ExampleKey = string;
+
+export interface ExampleBase {
+  matrix?: Matrix;
+  index?: number; // based on matrix
+
+  description?: string;
+  values?: Record<string, unknown>;
+  context?: Context;
+  formats?: FormatPresets;
+  timeZone?: string;
+  currency?: string;
+}
+
+/**
+ * Locales
+ */
+export type LocaleKey = string;
+export type LocaleDirection = "ltr" | "rtl";
+
+export type LocaleExample = ExampleBase & {
+  // one of them below needs to be provided
+  rawMessage?: string;
+  message?: MessageKey;
+};
+
+export interface Locale {
+  key?: LocaleKey;
+  promotable?: boolean;
+  description?: string;
+  direction?: LocaleDirection;
+  inheritFormatsFrom?: string;
+  inheritTranslationsFrom?: string;
+  mergeExamplesFrom?: string;
+  formats?: FormatPresets;
+  examples?: LocaleExample[];
+}
+
+/**
+ * Attributes
+ */
+export type AttributeKey = string;
+
+export interface AttributeObjectValue {
+  [key: AttributeKey]: AttributeValue;
+}
+
+export type AttributeValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined
+  | string[]
+  | AttributeObjectValue
+  | Record<string, unknown>;
+
+export type AttributeType =
+  | "boolean"
+  | "string"
+  | "integer"
+  | "double"
+  | "date"
+  | "object"
+  | "array";
+
+export interface AttributeSchema {
+  description?: string; // only available in YAML files
+  enum?: AttributeValue[];
+  const?: AttributeValue;
+  maximum?: number;
+  minimum?: number;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  items?: AttributeSchema;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  required?: string[];
+  properties?: {
+    [key: AttributeKey]: AttributeSchema;
+  };
+  additionalProperties?: AttributeSchema;
+  oneOf?: AttributeSchema[];
+}
+
+export type Attribute = AttributeSchema & {
+  key?: AttributeKey;
+  archived?: boolean; // only available in YAML files
+  promotable?: boolean;
+  type?: AttributeType; // required when not using oneOf
+};
+
+/**
+ * Context
+ */
+export interface Context {
+  [key: AttributeKey]: AttributeValue;
+}
+
+/**
+ * Conditions
+ */
+export type Operator =
+  | "equals"
+  | "notEquals"
+  | "exists"
+  | "notExists"
+
+  // numeric
+  | "greaterThan"
+  | "greaterThanOrEquals"
+  | "lessThan"
+  | "lessThanOrEquals"
+
+  // string
+  | "contains"
+  | "notContains"
+  | "startsWith"
+  | "endsWith"
+
+  // date comparisons
+  | "before"
+  | "after"
+
+  // array of strings
+  | "includes"
+  | "notIncludes"
+
+  // feature
+  | "isEnabled"
+  | "isDisabled"
+
+  // experiment
+  | "hasVariation"
+
+  // array of strings
+  | "in"
+  | "notIn";
+
+export type ConditionValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined
+  | Array<string | number | boolean | null>;
+
+export interface AttributeCondition {
+  attribute: AttributeKey;
+
+  operator:
+    | "equals"
+    | "notEquals"
+    | "exists"
+    | "notExists"
+    | "greaterThan"
+    | "greaterThanOrEquals"
+    | "lessThan"
+    | "lessThanOrEquals"
+    | "contains"
+    | "notContains"
+    | "startsWith"
+    | "endsWith"
+    | "before"
+    | "after"
+    | "includes"
+    | "notIncludes"
+    | "in"
+    | "notIn";
+  value?: ConditionValue; // for all operators, except for "exists" and "notExists"
+  regexFlags?: string; // for regex operators only (matches, notMatches)
+}
+
+export interface FeatureCondition {
+  feature: string;
+  operator: "isEnabled" | "isDisabled";
+}
+
+export interface ExperimentCondition {
+  experiment: string;
+  operator: "hasVariation";
+  value: string;
+}
+
+export type PlainCondition = AttributeCondition | FeatureCondition | ExperimentCondition;
+
+export interface AndCondition {
+  and: Condition[];
+}
+
+export interface OrCondition {
+  or: Condition[];
+}
+
+export interface NotCondition {
+  not: Condition[];
+}
+
+export type AndOrNotCondition = AndCondition | OrCondition | NotCondition;
+
+export type Condition = PlainCondition | AndOrNotCondition | string;
+
+/**
+ * Segments
+ */
+
+export type SegmentKey = string;
+
+export interface Segment {
+  archived?: boolean; // only available in YAML files
+  key?: SegmentKey; // needed for supporting v1 datafile generation
+  promotable?: boolean;
+  conditions: Condition | Condition[]; // string can be "*" or stringified for datafile
+  description?: string; // only available in YAML files
+}
+
+export type PlainGroupSegment = SegmentKey;
+
+export interface AndGroupSegment {
+  and: GroupSegment[];
+}
+
+export interface OrGroupSegment {
+  or: GroupSegment[];
+}
+
+export interface NotGroupSegment {
+  not: GroupSegment[];
+}
+
+export type AndOrNotGroupSegment = AndGroupSegment | OrGroupSegment | NotGroupSegment;
+
+// group of segment keys with and/or conditions, or just string
+export type GroupSegment = PlainGroupSegment | AndOrNotGroupSegment;
+
+/**
+ * Overrides
+ */
+export interface Override {
+  key: string;
+  description?: string;
+  summary?: string;
+
+  // one of them need to be provided
+  conditions?: Condition | Condition[] | "*"; // string can be "*" or stringified datafile condition
+  segments?: GroupSegment | GroupSegment[] | "*"; // string can be "*", segment key, or stringified datafile segment group
+
+  translations: {
+    [locale: LocaleKey]: Translation;
+  };
+}
+
+/**
+ * Messages
+ */
+export type MessageKey = string;
+
+export type Translation = string;
+export type MessageMeta = Record<string, unknown>;
+
+export type MessageExample = ExampleBase & {
+  locale: LocaleKey;
+};
+
+export interface Message {
+  key?: MessageKey;
+
+  // only in YAML files
+  archived?: boolean;
+  promotable?: boolean;
+  deprecated?: boolean;
+  deprecationWarning?: string;
+  description?: string;
+  summary?: string;
+  meta?: MessageMeta;
+  examples?: MessageExample[];
+
+  // rest
+  translations: {
+    [locale: LocaleKey]: Translation;
+  };
+  overrides?: Override[];
+}
+
+/**
+ * Targets
+ */
+export type TargetKey = string;
+
+export interface Target {
+  key?: TargetKey;
+  promotable?: boolean;
+  stringify?: boolean;
+  pretty?: boolean;
+  revisionFromHash?: boolean;
+  includeMessages?: string[];
+  excludeMessages?: string[];
+  locales?: LocaleKey[];
+  context?: Context;
+  formats?: { [locale: LocaleKey]: FormatPresets };
+}

package/src/format.d.ts

@@ -0,0 +1,184 @@
+/**
+ * ECMA-402 / ICU-related format preset types (for `Intl.*Format` and skeleton strings).
+ */
+
+/**
+ * Digit, grouping, notation, and rounding fields shared by all `Intl.NumberFormat` style variants (ECMA-402).
+ */
+export interface FormatNumberPresetShared {
+  useGrouping?: boolean | "min2" | "auto" | "always";
+  minimumIntegerDigits?: number;
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+  minimumSignificantDigits?: number;
+  maximumSignificantDigits?: number;
+  notation?: "standard" | "scientific" | "engineering" | "compact";
+  compactDisplay?: "short" | "long";
+  signDisplay?: "auto" | "never" | "always" | "exceptZero" | "negative";
+  roundingPriority?: "auto" | "morePrecision" | "lessPrecision";
+  roundingIncrement?:
+    | 1
+    | 2
+    | 5
+    | 10
+    | 20
+    | 25
+    | 50
+    | 100
+    | 200
+    | 250
+    | 500
+    | 1000
+    | 2000
+    | 2500
+    | 5000;
+  roundingMode?:
+    | "ceil"
+    | "floor"
+    | "expand"
+    | "trunc"
+    | "halfCeil"
+    | "halfFloor"
+    | "halfExpand"
+    | "halfTrunc"
+    | "halfEven";
+  trailingZeroDisplay?: "auto" | "stripIfInteger";
+  numberingSystem?: string;
+}
+
+/**
+ * Default / plain number formatting (`style` omitted or `"decimal"`). Do not set `currency` or `unit` here — use {@link FormatNumberCurrencyPreset} or {@link FormatNumberUnitPreset}.
+ */
+export type FormatNumberDecimalPreset = FormatNumberPresetShared & {
+  style?: "decimal";
+  currency?: never;
+  currencyDisplay?: never;
+  currencySign?: never;
+  unit?: never;
+  unitDisplay?: never;
+};
+
+/**
+ * Currency formatting. `currency` may be omitted when the application supplies one at runtime.
+ */
+export type FormatNumberCurrencyPreset = FormatNumberPresetShared & {
+  style: "currency";
+  currency?: string;
+  currencyDisplay?: "code" | "symbol" | "narrowSymbol" | "name";
+  currencySign?: "standard" | "accounting";
+  unit?: never;
+  unitDisplay?: never;
+};
+
+/**
+ * Percent formatting (`style: "percent"`). Values are fractional (e.g. `0.12` → `"12%"` in `en-US`).
+ */
+export type FormatNumberPercentPreset = FormatNumberPresetShared & {
+  style: "percent";
+  currency?: never;
+  currencyDisplay?: never;
+  currencySign?: never;
+  unit?: never;
+  unitDisplay?: never;
+};
+
+/**
+ * Unit formatting (`style: "unit"`). Requires a [sanctioned unit identifier](https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers) in `unit`.
+ */
+export type FormatNumberUnitPreset = FormatNumberPresetShared & {
+  style: "unit";
+  unit: string;
+  unitDisplay?: "short" | "narrow" | "long";
+  currency?: never;
+  currencyDisplay?: never;
+  currencySign?: never;
+};
+
+/**
+ * Discriminated union on `style` so currency / unit options are valid only when applicable. Assignable to `Intl.NumberFormatOptions`.
+ */
+export type FormatNumberPresetOptions =
+  | FormatNumberDecimalPreset
+  | FormatNumberCurrencyPreset
+  | FormatNumberPercentPreset
+  | FormatNumberUnitPreset;
+
+/**
+ * Fields shared by both date/time preset shapes (time zone, calendar, etc.).
+ */
+export interface FormatDateTimePresetShared {
+  timeZone?: string;
+  calendar?: string;
+  numberingSystem?: string;
+  hour12?: boolean;
+  hourCycle?: "h11" | "h12" | "h23" | "h24";
+}
+
+/**
+ * Use granular date/time fields (`year`, `hour`, …).
+ */
+export type FormatDateTimeFieldsPreset = FormatDateTimePresetShared & {
+  dateStyle?: never;
+  timeStyle?: never;
+  formatMatcher?: "basic" | "best fit";
+  weekday?: "long" | "short" | "narrow";
+  era?: "long" | "short" | "narrow";
+  year?: "numeric" | "2-digit";
+  month?: "numeric" | "2-digit" | "long" | "short" | "narrow";
+  day?: "numeric" | "2-digit";
+  dayPeriod?: "long" | "short" | "narrow";
+  hour?: "numeric" | "2-digit";
+  minute?: "numeric" | "2-digit";
+  second?: "numeric" | "2-digit";
+  fractionalSecondDigits?: 1 | 2 | 3;
+  timeZoneName?: "long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+};
+
+export type FormatDateTimeStylePreset = FormatDateTimePresetShared & {
+  dateStyle?: "full" | "long" | "medium" | "short";
+  timeStyle?: "full" | "long" | "medium" | "short";
+  formatMatcher?: never;
+  weekday?: never;
+  era?: never;
+  year?: never;
+  month?: never;
+  day?: never;
+  dayPeriod?: never;
+  hour?: never;
+  minute?: never;
+  second?: never;
+  fractionalSecondDigits?: never;
+  timeZoneName?: never;
+};
+
+/**
+ * Assignable to the portable Messagevisor date/time subset and broadly compatible with `Intl.DateTimeFormatOptions`.
+ */
+export type FormatDateTimePresetOptions = FormatDateTimeFieldsPreset | FormatDateTimeStylePreset;
+
+/**
+ * `Intl.RelativeTimeFormat` only exposes `numeric` and `style`; they are independent, so a single interface stays clearest.
+ * Same keys as `Intl.RelativeTimeFormatOptions` without `localeMatcher`.
+ */
+export interface FormatRelativeTimePresetOptions {
+  numeric?: "always" | "auto";
+  style?: "long" | "short" | "narrow";
+}
+
+export interface FormatPresets {
+  number?: Record<string, FormatNumberPresetOptions>;
+  date?: Record<string, FormatDateTimePresetOptions>;
+  time?: Record<string, FormatDateTimePresetOptions>;
+  relative?: Record<string, FormatRelativeTimePresetOptions>;
+  dateTimeRange?: Record<string, FormatDateTimePresetOptions>;
+}
+
+/**
+ * Named ICU skeleton / compact format strings (e.g. UTS #35 date/time skeletons, compact number tokens for `::` in messages).
+ */
+// export interface IcuSkeletonFormats {
+//   number?: Record<string, string>;
+//   date?: Record<string, string>;
+//   time?: Record<string, string>;
+//   dateTime?: Record<string, string>;
+// }

package/src/index.d.ts

@@ -0,0 +1,5 @@
+// export all
+export * from "./entities";
+export * from "./format";
+export * from "./datafile";
+export * from "./tests";

package/src/index.js

@@ -0,0 +1 @@
+// empty line

package/src/tests.d.ts

@@ -0,0 +1,124 @@
+import type {
+  Context,
+  Matrix,
+  MessageKey,
+  SegmentKey,
+  TargetKey,
+  LocaleKey,
+  Translation,
+} from "./entities";
+import type { FormatPresets } from "./format";
+
+export type ExpectedByRuntime = Record<string, string>;
+
+/**
+ * MessageTest
+ */
+export interface MessageAssertion {
+  matrix?: Matrix;
+  description?: string;
+  context?: Context;
+  locale: LocaleKey;
+  target?: TargetKey;
+  values?: Record<string, unknown>;
+  withFlags?: Record<string, boolean>;
+  withVariations?: Record<string, string>;
+  currency?: string;
+  timeZone?: string;
+  formats?: FormatPresets;
+  expectedTranslation: Translation;
+  expectedByRuntime?: ExpectedByRuntime;
+}
+
+export interface MessageTest {
+  promotable?: boolean;
+  message: MessageKey;
+  assertions: MessageAssertion[];
+}
+
+/**
+ * SegmentTest
+ */
+export interface SegmentAssertion {
+  matrix?: Matrix;
+  description?: string;
+  segment: SegmentKey;
+  context?: Context;
+  expectedToMatch: boolean;
+}
+
+export interface SegmentTest {
+  promotable?: boolean;
+  segment: SegmentKey;
+  assertions: SegmentAssertion[];
+}
+
+/**
+ * LocaleTest
+ */
+export interface LocaleAssertion {
+  matrix?: Matrix;
+  description?: string;
+  target?: TargetKey;
+  expectedFormats?: FormatPresets;
+
+  /**
+   * When asserting raw message translation
+   */
+  // optional, but need to be used together if one is used
+  rawMessage?: string;
+  expectedTranslation?: string;
+  expectedByRuntime?: ExpectedByRuntime;
+
+  // other optional params
+  values?: Record<string, unknown>;
+  context?: Record<string, unknown>;
+  formats?: FormatPresets;
+  currency?: string;
+  timeZone?: string;
+}
+
+export interface LocaleTest {
+  promotable?: boolean;
+  locale: LocaleKey;
+  assertions: LocaleAssertion[];
+}
+
+/**
+ * TargetTest
+ */
+export interface TargetAssertion {
+  matrix?: Matrix;
+  description?: string;
+  locale: LocaleKey;
+  expectedToIncludeMessages?: MessageKey[];
+  expectedToNotIncludeMessages?: MessageKey[];
+  expectedFormats?: FormatPresets;
+
+  /**
+   * When asserting raw message or message translation
+   */
+  // optional, but need to be used together if one is used
+  rawMessage?: string; // either rawMessage or message must be used
+  message?: MessageKey;
+  expectedTranslation?: string; // if rawMessage or message is used, expectedTranslation must be used
+  expectedByRuntime?: ExpectedByRuntime;
+
+  // other optional params
+  values?: Record<string, unknown>;
+  context?: Record<string, unknown>;
+  formats?: FormatPresets;
+  currency?: string;
+  timeZone?: string;
+}
+
+export interface TargetTest {
+  promotable?: boolean;
+  target: TargetKey;
+  assertions: TargetAssertion[];
+}
+
+/**
+ * Combined
+ */
+export type Test = MessageTest | SegmentTest | LocaleTest | TargetTest;

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.esm.json",
+  "compilerOptions": {
+    "outDir": "./lib",
+    "lib": ["ES2023", "DOM"]
+  },
+  "include": ["./src/**/*.ts", "./src/**/*.d.ts"]
+}