@inlang/sdk 0.1.0

package/src/messages/variant.test.ts

@@ -0,0 +1,444 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { createVariant, getVariant, updateVariantPattern } from "./variant.js"
+import { describe, test, expect } from "vitest"
+import {
+	MessagePatternsForLanguageTagDoNotExistError,
+	MessageVariantAlreadyExistsError,
+	MessageVariantDoesNotExistError,
+} from "./errors.js"
+import type { Message, Variant } from "../versionedInterfaces.js"
+
+describe("getVariant", () => {
+	test("should return the correct variant of a message", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: { gender: "female", guestOther: "1" },
+			},
+		})
+
+		expect(variant?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "{$hostName} invites {$guestName} to her party.",
+		})
+	})
+
+	test("should return the correct fallback because the exact match does not exist", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: { gender: "female", guestOther: "0" },
+			},
+		})
+		expect(variant?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "{$hostName} invites {$guestName} and {$guestsOther} other people to her party.",
+		})
+	})
+
+	test("it should return undefined (but never throw an error) if selectors is an empty array", () => {
+		const mockMessage: Message = {
+			id: "mockMessage",
+			selectors: [],
+			variants: [
+				{
+					languageTag: "en",
+					pattern: [{ type: "Text", value: "Gender male" }],
+					match: {
+						gender: "male",
+					},
+				},
+				{
+					languageTag: "de",
+					pattern: [{ type: "Text", value: "Veraltete Übersetzung" }],
+					match: {},
+				},
+			],
+		}
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "fr",
+				selectors: {},
+			},
+		})
+		expect(variant).toBeUndefined()
+	})
+
+	test("the matcher should resolve not existing selectors to '*'", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: { guestOther: "0" },
+			},
+		})
+		expect(variant?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "{$hostName} does not give a party.",
+		})
+	})
+
+	test("empty selector should result in '*','*'", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: {},
+			},
+		})
+		expect(variant?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "{$hostName} invites {$guestName} and {$guestsOther} other people to their party.",
+		})
+	})
+
+	test("non existing selector values should be resolved", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: { gender: "trans", guestOther: "2" },
+			},
+		})
+		expect(variant?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "{$hostName} invites {$guestName} and one other person to their party.",
+		})
+
+		const variant2 = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: { gender: "male", guestOther: "8" },
+			},
+		})
+		expect(variant2?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "{$hostName} invites {$guestName} and {$guestsOther} other people to his party.",
+		})
+	})
+
+	test("should return undefined of no variant matches", () => {
+		const mockMessage: Message = getMockMessage()
+		mockMessage.variants = [
+			...mockMessage.variants!.filter(
+				(v) => v.languageTag === "en" && (v.match.gender !== "*" || v.match.guestOther !== "*"),
+			),
+		]
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: {},
+			},
+		})
+		expect(variant).toBeUndefined()
+	})
+
+	test("should return undefined if a variant for specific language does not exist", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "de",
+				selectors: { gender: "female", guestOther: "1" },
+			},
+		})
+		expect(variant).toBeUndefined()
+	})
+
+	test("should return the catch all variant if no selector defined", () => {
+		const mockMessage: Message = {} as any
+		mockMessage.variants = [
+			{
+				languageTag: "en",
+				match: {},
+				pattern: [
+					{
+						type: "Text",
+						value: "test",
+					},
+				],
+			},
+		]
+
+		const variant = getVariant(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: {},
+			},
+		})
+		// should return the female variant
+		expect(variant?.pattern[0]).toStrictEqual({
+			type: "Text",
+			value: "test",
+		})
+	})
+})
+
+describe("createVariant", () => {
+	test("should create a variant for a message", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const newVariant: Variant = {
+			languageTag: "en",
+			match: { gender: "female", guestOther: "0" },
+			pattern: [],
+		}
+		const message = createVariant(mockMessage, {
+			data: newVariant,
+		})
+		// should return the female variant
+		expect(
+			message.data!.variants.find(
+				(v) => v.languageTag === "en" && v.match.gender === "female" && v.match.guestOther === "0",
+			)?.pattern,
+		).toStrictEqual([])
+	})
+
+	test("should create a variant, also if matcher are not full defined", () => {
+		const mockMessage: Message = getMockMessage()
+		mockMessage.variants = [
+			...mockMessage.variants!.filter(
+				(v) => v.languageTag === "en" && (v.match.gender !== "*" || v.match.guestOther !== "*"),
+			),
+		]
+
+		const message = createVariant(mockMessage, {
+			data: {
+				languageTag: "en",
+				match: {},
+				pattern: [],
+			},
+		})
+		// should return the female variant
+		expect(
+			message.data!.variants.find(
+				(v) => v.languageTag === "en" && v.match.gender === "*" && v.match.guestOther === "*",
+			)?.pattern,
+		).toStrictEqual([])
+	})
+
+	test("should return error if variant matches", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = createVariant(mockMessage, {
+			data: {
+				languageTag: "en",
+				match: { gender: "male", guestOther: "1" },
+				pattern: [],
+			},
+		})
+		// should return the female variant
+		expect(variant.data).toBeUndefined()
+		expect(variant.error).toBeInstanceOf(MessageVariantAlreadyExistsError)
+	})
+
+	test("should not return error if set of variants for specific language does not exist", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = createVariant(mockMessage, {
+			data: {
+				languageTag: "de",
+				match: { gender: "female", guestOther: "1" },
+				pattern: [],
+			},
+		})
+		// should return the female variant
+		expect(variant.data).toBeDefined()
+		expect(variant.error).toBeUndefined()
+	})
+})
+
+describe("updateVariant", () => {
+	test("should update a variant of a message", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const message = updateVariantPattern(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: { gender: "female", guestOther: "1" },
+			},
+			data: [],
+		})
+		// should return the female variant
+		expect(
+			message.data!.variants.find(
+				(v) => v.languageTag === "en" && v.match.gender === "female" && v.match.guestOther === "1",
+			)?.pattern,
+		).toStrictEqual([])
+	})
+
+	test("should update a variant, also if matcher are not full defined", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const message = updateVariantPattern(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: {},
+			},
+			data: [],
+		})
+		// should return the female variant
+		expect(
+			message.data!.variants.find(
+				(v) => v.languageTag === "en" && v.match.gender === "*" && v.match.guestOther === "*",
+			)?.pattern,
+		).toStrictEqual([])
+	})
+
+	test("should return error if no variant matches", () => {
+		const mockMessage: Message = getMockMessage()
+
+		mockMessage.variants = [
+			...mockMessage.variants!.filter(
+				(v) => v.languageTag === "en" && (v.match.gender !== "*" || v.match.guestOther !== "*"),
+			),
+		]
+
+		const variant = updateVariantPattern(mockMessage, {
+			where: {
+				languageTag: "en",
+				selectors: {},
+			},
+			data: [],
+		})
+		// should return the female variant
+		expect(variant.data).toBeUndefined()
+		expect(variant.error).toBeInstanceOf(MessageVariantDoesNotExistError)
+	})
+
+	test("should return error if set of variants for specific language does not exist", () => {
+		const mockMessage: Message = getMockMessage()
+
+		const variant = updateVariantPattern(mockMessage, {
+			where: {
+				languageTag: "de",
+				selectors: {},
+			},
+			data: [],
+		})
+		// should return the female variant
+		expect(variant.data).toBeUndefined()
+		expect(variant.error).toBeInstanceOf(MessagePatternsForLanguageTagDoNotExistError)
+	})
+})
+
+const getMockMessage = (): Message => {
+	return {
+		id: "first-message",
+		selectors: [
+			{ type: "VariableReference", name: "gender" },
+			{ type: "VariableReference", name: "guestOther" },
+		],
+		variants: [
+			{
+				languageTag: "en",
+				match: { gender: "female", guestOther: "1" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} to her party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "female", guestOther: "2" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} and one other person to her party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "female", guestOther: "*" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} and {$guestsOther} other people to her party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "male", guestOther: "1" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} to his party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "male", guestOther: "2" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} and one other person to his party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "male", guestOther: "*" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} and {$guestsOther} other people to his party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "*", guestOther: "0" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} does not give a party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "*", guestOther: "1" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} to their party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "*", guestOther: "2" },
+				pattern: [
+					{
+						type: "Text",
+						value: "{$hostName} invites {$guestName} and one other person to their party.",
+					},
+				],
+			},
+			{
+				languageTag: "en",
+				match: { gender: "*", guestOther: "*" },
+				pattern: [
+					{
+						type: "Text",
+						value:
+							"{$hostName} invites {$guestName} and {$guestsOther} other people to their party.",
+					},
+				],
+			},
+		],
+	}
+}

package/src/messages/variant.ts

@@ -0,0 +1,242 @@
+import type { LanguageTag, Message, Variant } from "../versionedInterfaces.js"
+import type { Result } from "@inlang/result"
+import {
+	MessagePatternsForLanguageTagDoNotExistError,
+	MessageVariantAlreadyExistsError,
+	MessageVariantDoesNotExistError,
+} from "./errors.js"
+
+/**
+ * Tries to match the most specific variant of a message.
+ *
+ * The selectors determine the specificity of a variant. If no selectors are provided,
+ * or if the selectors do not match any variant, the catch all variant is returned
+ * (if it exists).
+ *
+ * @example
+ * 	const variant = getVariant(message, { where: { languageTag: "en", selectors: { gender: "male" }}});
+ */
+export function getVariant(
+	message: Message,
+	args: {
+		where: {
+			languageTag: LanguageTag
+			selectors?: Variant["match"]
+		}
+	},
+): Variant | undefined {
+	const variant = matchMostSpecificVariant(message, args.where.languageTag, args.where.selectors)
+	if (variant) {
+		//! do not return a reference to the message in a resource
+		//! modifications to the returned message will leak into the
+		//! resource which is considered to be immutable.
+		return structuredClone(variant)
+	}
+	return undefined
+}
+
+/**
+ * Create a variant for a message
+ *
+ * All actions are immutable.
+ *
+ * @example
+ *  const message = createVariant(message, { languageTag: "en", data: variant })
+ */
+export function createVariant(
+	message: Message,
+	args: {
+		data: Variant
+	},
+): Result<Message, MessageVariantAlreadyExistsError> {
+	const copy = structuredClone(message)
+
+	// check if variant already exists
+	if (matchVariant(copy, args.data.languageTag, args.data.match)) {
+		return { error: new MessageVariantAlreadyExistsError(message.id, args.data.languageTag) }
+	}
+
+	// need to resolve selectors to match length and order of message selectors
+	copy.variants.push({
+		...args.data,
+		match: resolveSelector(copy.selectors, args.data.match),
+	})
+	return { data: copy }
+}
+
+/**
+ * Update a variant of a message
+ *
+ * All actions are immutable.
+ *
+ * @example
+ *  const message = updateVariant(message, { languageTag: "en", selectors: { gender: "male" }, pattern: []})
+ */
+export function updateVariantPattern(
+	message: Message,
+	args: {
+		where: {
+			languageTag: LanguageTag
+			selectors: Record<string, string>
+		}
+		data: Variant["pattern"]
+	},
+): Result<Message, MessageVariantDoesNotExistError | MessagePatternsForLanguageTagDoNotExistError> {
+	const copy = structuredClone(message)
+
+	const containsLanguageTag = message.variants.some(
+		(variant) => variant.languageTag === args.where.languageTag,
+	)
+	if (!containsLanguageTag) {
+		return {
+			error: new MessagePatternsForLanguageTagDoNotExistError(message.id, args.where.languageTag),
+		}
+	}
+
+	const variant = matchVariant(copy, args.where.languageTag, args.where.selectors)
+	if (variant === undefined) {
+		return { error: new MessageVariantDoesNotExistError(message.id, args.where.languageTag) }
+	}
+	if (variant) {
+		variant.pattern = args.data
+		return { data: copy }
+	}
+	return { error: new MessageVariantDoesNotExistError(message.id, args.where.languageTag) }
+}
+
+/**
+ * Returns the specific variant defined by selectors or undefined
+ *
+ * @example
+ *  const variant = matchVariant(message, languageTag: "en", selectors: { gender: "male" })
+ */
+const matchVariant = (
+	message: Message,
+	languageTag: LanguageTag,
+	selectors: Record<string, string>,
+): Variant | undefined => {
+	// resolve preferenceSelectors to match length and order of message selectors
+	const resolvedSelectors = resolveSelector(message.selectors, selectors)
+
+	const languageVariants = message.variants.filter((variant) => variant.languageTag === languageTag)
+	if (languageVariants.length === 0) return undefined
+
+	for (const variant of languageVariants) {
+		let isMatch = true
+		//check if vaiant is a match
+		for (const [key, value] of Object.entries(variant.match)) {
+			if (resolvedSelectors[key] !== value) {
+				isMatch = false
+			}
+		}
+		if (isMatch) {
+			return variant
+		}
+	}
+	return undefined
+}
+
+/**
+ * Returns the most specific variant of a message.
+ *
+ * @example
+ *  const variant = matchMostSpecificVariant(message, languageTag: "en", selectors: { gender: "male" })
+ */
+const matchMostSpecificVariant = (
+	message: Message,
+	languageTag: LanguageTag,
+	selectors?: Record<string, string>,
+): Variant | undefined => {
+	// make selector undefined if empty object
+	selectors = JSON.stringify(selectors) === "{}" ? undefined : selectors
+
+	// resolve preferenceSelectors to match length and order of message selectors
+	const resolvedSelectors = resolveSelector(message.selectors, selectors)
+	const index: Record<string, any> = {}
+
+	const languageVariants = message.variants.filter((variant) => variant.languageTag === languageTag)
+	if (languageVariants.length === 0) return undefined
+
+	for (const variant of languageVariants) {
+		let isMatch = true
+
+		//check if variant is a match
+		for (const [key, value] of Object.entries(variant.match)) {
+			if (resolvedSelectors[key] !== value && value !== "*") {
+				isMatch = false
+			}
+		}
+		if (isMatch && selectors) {
+			// add variant to nested index
+			// eslint-disable-next-line no-inner-declarations
+			function recursiveAddToIndex(
+				currentIndex: Record<string, any>,
+				currentKeys: Message["selectors"],
+				variant: Variant,
+			) {
+				if (currentKeys[0]?.name) {
+					const key = variant.match[currentKeys[0].name]
+					if (key) {
+						if (currentKeys.length === 1) {
+							currentIndex[key] = variant
+						} else {
+							if (!currentIndex[key]) {
+								currentIndex[key] = {}
+							}
+							recursiveAddToIndex(currentIndex[key], currentKeys.slice(1), variant)
+						}
+					}
+				}
+			}
+			recursiveAddToIndex(index, message.selectors, variant)
+		} else if (isMatch && !selectors) {
+			return variant
+		}
+	}
+
+	//find the most specific variant
+	const findOptimalMatch = (
+		index: Record<string, any>,
+		selectors: string[],
+	): Variant | undefined => {
+		const keys = Object.keys(index)
+
+		for (const key of keys) {
+			if (key === selectors[0] || key === "*") {
+				const nextOptimal = selectors.slice(1)
+
+				if (nextOptimal.length === 0) {
+					return (index[key] as Variant) || undefined
+				}
+
+				const match = findOptimalMatch(index[key] as Record<string, any>, nextOptimal)
+
+				if (match !== undefined) {
+					return match
+				}
+			}
+		}
+		return undefined
+	}
+
+	return findOptimalMatch(index, Object.values(resolvedSelectors))
+}
+
+/**
+ * Returns resolved selector.
+ * -> Adds all possible selectors, if not defined it adds '*'. Order is determined by messageSelectors
+ *
+ * @example
+ *  const variant = resolveSelector(["gender","count"], selector: {count: "2"})
+ */
+const resolveSelector = (
+	messageSelectors: Message["selectors"],
+	selectors?: Record<string, string>,
+): Record<string, string> => {
+	const resolvedSelectors: Record<string, string> = {}
+	if (!selectors) return {}
+	for (const messageSelector of messageSelectors) {
+		resolvedSelectors[messageSelector.name] = selectors[messageSelector.name] ?? "*"
+	}
+	return resolvedSelectors
+}