@inlang/sdk 0.1.0

package/src/createMessagesQuery.test.ts

@@ -0,0 +1,435 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { describe, it, expect } from "vitest"
+import { createMessagesQuery } from "./createMessagesQuery.js"
+import { createEffect, createRoot, createSignal } from "./reactivity/solid.js"
+import type { Message, Text } from "@inlang/message"
+import { createMessage } from "./test-utilities/createMessage.js"
+
+const createChangeListener = async (cb: () => void) => createEffect(cb)
+
+describe("create", () => {
+	it("should create a message", () => {
+		const query = createMessagesQuery(() => [])
+		expect(query.get({ where: { id: "first-message" } })).toBeUndefined()
+
+		const mockMessage = createMessage("first-message", { en: "Hello World" })
+		const created = query.create({ data: mockMessage })
+
+		expect(query.get({ where: { id: "first-message" } })).toEqual(mockMessage)
+		expect(created).toBe(true)
+	})
+
+	it("should return false if message with id already exists", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		expect(query.get({ where: { id: "first-message" } })).toBeDefined()
+
+		const mockMessage = createMessage("first-message", { en: "Some Text" })
+		query.create({ data: mockMessage })
+
+		const created = query.create({ data: mockMessage })
+		expect(created).toBe(false)
+	})
+})
+
+describe("get", () => {
+	it("should return undefined if a message does not exist", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		const message = query.get({ where: { id: "none-existent-message" } })
+		expect(message).toBeUndefined()
+	})
+
+	it("should return an object, not an array", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		const message = query.get({ where: { id: "first-message" } })
+		expect(message).toBeDefined()
+		expect(Array.isArray(message)).toBe(false)
+	})
+
+	// todo: improve the readonly type
+	it.skip("mutating the returned value should not affect subsequent return values", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		const message1 = query.get({ where: { id: "first-message" } })!
+		;(message1.variants.find((v) => v.languageTag === "en")!.pattern![0]! as Text).value =
+			"Hello World 2"
+		const message2 = query.get({ where: { id: "first-message" } })!
+
+		expect(
+			(message1.variants.find((v) => v.languageTag === "en")!.pattern![0]! as Text).value,
+		).toBe("Hello World 2")
+		expect(
+			(message2.variants.find((v) => v.languageTag === "en")!.pattern![0]! as Text).value,
+		).toBe("Hello World")
+	})
+})
+
+describe("getAll", () => {
+	it("should return an empty array if no messages exist", () => {
+		const query = createMessagesQuery(() => [])
+		const messages = query.getAll()
+
+		expect(Object.values(messages!)).toEqual([])
+	})
+
+	it("should return all message objects", () => {
+		const query = createMessagesQuery(() => [])
+		const mockMessage1 = createMessage("first-message", { en: "Hello World" })
+		const mockMessage2 = createMessage("second-message", { en: "Hello World 2" })
+		query.create({ data: mockMessage1 })
+		query.create({ data: mockMessage2 })
+
+		const messages = query.getAll()
+		expect(Object.values(messages!)).toEqual([mockMessage1, mockMessage2])
+	})
+
+	// todo: improve the readonly type
+	it.skip("mutating the returned value should not affect subsequent return values", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		const messages1 = query.getAll()
+		;(
+			Object.values(messages1!)[0]!.variants.find((v) => v.languageTag === "en")!
+				.pattern![0]! as Text
+		).value = "Hello World 2"
+
+		expect(
+			(
+				Object.values(query.getAll()!)[0]!.variants.find((v) => v.languageTag === "en")!
+					.pattern![0]! as Text
+			).value,
+		).toBe("Hello World")
+	})
+})
+
+describe("update", () => {
+	it("should update a message", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		expect(query.get({ where: { id: "first-message" } })).toBeDefined()
+
+		const mockMessage = createMessage("first-message", { en: "Hello World 2" })
+		const updated = query.update({ where: { id: "first-message" }, data: mockMessage })
+
+		expect(query.get({ where: { id: "first-message" } })).toEqual(mockMessage)
+		expect(updated).toBe(true)
+	})
+
+	it("should return false if message with id does not exist exists", () => {
+		const query = createMessagesQuery(() => [])
+		expect(query.get({ where: { id: "first-message" } })).toBeUndefined()
+
+		const mockMessage = createMessage("first-message", { en: "Hello World" })
+		const updated = query.update({ where: { id: "first-message" }, data: mockMessage })
+		expect(updated).toBe(false)
+	})
+})
+
+describe("upsert", () => {
+	it("should create a message if not present yet", () => {
+		const query = createMessagesQuery(() => [])
+		expect(query.get({ where: { id: "first-message" } })).toBeUndefined()
+
+		const mockMessage = createMessage("first-message", { en: "Hello World" })
+		const upserted = query.upsert({ where: { id: "first-message" }, data: mockMessage })
+
+		expect(query.get({ where: { id: "first-message" } })).toEqual(mockMessage)
+		expect(upserted).toBe(true)
+	})
+
+	it("should update message if id already exists", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		expect(query.get({ where: { id: "first-message" } })).toBeDefined()
+
+		const mockMessage = createMessage("first-message", { en: "Hello World 2" })
+		const upserted = query.upsert({ where: { id: "first-message" }, data: mockMessage })
+
+		expect(query.get({ where: { id: "first-message" } })).toEqual(mockMessage)
+		expect(upserted).toBe(true)
+	})
+})
+
+describe("delete", () => {
+	it("should delete a message", () => {
+		const query = createMessagesQuery(() => [createMessage("first-message", { en: "Hello World" })])
+		expect(query.get({ where: { id: "first-message" } })).toBeDefined()
+
+		const deleted = query.delete({ where: { id: "first-message" } })
+
+		expect(query.get({ where: { id: "first-message" } })).toBeUndefined()
+		expect(deleted).toBe(true)
+	})
+
+	it("should return false if message with id does not exist", () => {
+		const query = createMessagesQuery(() => [])
+		expect(query.get({ where: { id: "first-message" } })).toBeUndefined()
+
+		const deleted = query.delete({ where: { id: "first-message" } })
+		expect(deleted).toBe(false)
+	})
+})
+
+describe("reactivity", () => {
+	describe("get", () => {
+		it("should react to `create`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [])
+
+				// eslint-disable-next-line unicorn/no-null
+				let message: Message | undefined | null = null
+				await createChangeListener(() => (message = query.get({ where: { id: "1" } })))
+				expect(message).toBeUndefined()
+
+				query.create({ data: createMessage("1", { en: "before" }) })
+				expect(message).toBeDefined()
+
+				const anotherMessage = query.get({ where: { id: "1" } })
+				expect(anotherMessage).toBeDefined()
+				expect(message).toStrictEqual(anotherMessage)
+			})
+		})
+
+		it("should react to `update`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [createMessage("1", { en: "before" })])
+
+				let message: Message | undefined
+				await createChangeListener(() => (message = query.get({ where: { id: "1" } })))
+				expect(message).toBeDefined()
+				expect(
+					(message?.variants.find((variant) => variant.languageTag === "en")?.pattern[0] as Text)
+						.value,
+				).toBe("before")
+
+				query.update({ where: { id: "1" }, data: createMessage("1", { en: "after" }) })
+				expect(
+					(message?.variants.find((variant) => variant.languageTag === "en")?.pattern[0] as Text)
+						.value,
+				).toBe("after")
+			})
+		})
+
+		it("should react to `upsert`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [])
+
+				let message: Message | undefined
+				await createChangeListener(() => (message = query.get({ where: { id: "1" } })))
+				expect(message).toBeUndefined()
+
+				query.upsert({ where: { id: "1" }, data: createMessage("1", { en: "before" }) })
+				expect(message).toBeDefined()
+				expect(
+					(message?.variants.find((variant) => variant.languageTag === "en")?.pattern[0] as Text)
+						.value,
+				).toBe("before")
+
+				query.upsert({ where: { id: "1" }, data: createMessage("1", { en: "after" }) })
+				expect(
+					(message?.variants.find((variant) => variant.languageTag === "en")?.pattern[0] as Text)
+						.value,
+				).toBe("after")
+			})
+		})
+
+		it("should react to `delete`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [createMessage("1", { en: "" })])
+
+				let message: Message | undefined
+				await createChangeListener(() => (message = query.get({ where: { id: "1" } })))
+				expect(message).toBeDefined()
+
+				query.delete({ where: { id: "1" } })
+				expect(message).toBeUndefined()
+			})
+		})
+
+		it("should react to changes to the input `messages`", async () => {
+			const [messages, setMessages] = createSignal<Message[]>([])
+			const query = createMessagesQuery(messages)
+
+			// eslint-disable-next-line unicorn/no-null
+			let message: Message | undefined | null = null
+			await createChangeListener(() => (message = query.get({ where: { id: "1" } })))
+			expect(message).toBeUndefined()
+
+			query.create({ data: createMessage("1", { en: "before" }) })
+			expect(message).toBeDefined()
+			expect(
+				(message!.variants.find((variant) => variant.languageTag === "en")?.pattern[0] as Text)
+					.value,
+			).toBe("before")
+
+			setMessages([createMessage("1", { en: "after" })])
+			expect(message).toBeDefined()
+			expect(
+				(message!.variants.find((variant) => variant.languageTag === "en")?.pattern[0] as Text)
+					.value,
+			).toBe("after")
+		})
+	})
+
+	describe.todo("subscribe", () => {
+		// TODO: add tests for `subscribe`
+	})
+
+	describe("getAll", () => {
+		it("should react to `create`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [])
+
+				let messages: Readonly<Message[]> | undefined = undefined
+				await createChangeListener(() => (messages = query.getAll()))
+				expect(Object.values(messages!)).toHaveLength(0)
+
+				query.create({ data: createMessage("1", { en: "before" }) })
+				expect(Object.values(messages!)).toHaveLength(1)
+
+				query.create({ data: createMessage("2", { en: "before" }) })
+				expect(Object.values(messages!)).toHaveLength(2)
+
+				query.create({ data: createMessage("3", { en: "before" }) })
+				expect(Object.values(messages!)).toHaveLength(3)
+			})
+		})
+
+		it("should react to `update`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [createMessage("1", { en: "before" })])
+
+				let messages: Readonly<Message[]> | undefined = undefined
+				await createChangeListener(() => (messages = query.getAll()))
+				expect(Object.values(messages!)).toHaveLength(1)
+				expect(
+					(
+						Object.values(messages!)![0]!.variants.find((variant) => variant.languageTag === "en")!
+							.pattern[0]! as Text
+					).value,
+				).toBe("before")
+
+				query.update({ where: { id: "1" }, data: createMessage("1", { en: "after" }) })
+				expect(Object.values(messages!)).toHaveLength(1)
+				expect(
+					(
+						Object.values(messages!)![0]!.variants.find((variant) => variant.languageTag === "en")!
+							.pattern[0]! as Text
+					).value,
+				).toBe("after")
+			})
+		})
+
+		it("should react to `upsert`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [])
+
+				let messages: Readonly<Message[]> | undefined = undefined
+				await createChangeListener(() => (messages = query.getAll()))
+				expect(Object.values(messages!)).toHaveLength(0)
+
+				query.upsert({ where: { id: "1" }, data: createMessage("1", { en: "before" }) })
+				expect(Object.values(messages!)).toHaveLength(1)
+				expect(
+					(
+						Object.values(messages!)![0]!.variants.find((variant) => variant.languageTag === "en")!
+							.pattern[0]! as Text
+					).value,
+				).toBe("before")
+
+				query.upsert({ where: { id: "1" }, data: createMessage("1", { en: "after" }) })
+				expect(
+					(
+						Object.values(messages!)![0]!.variants.find((variant) => variant.languageTag === "en")!
+							.pattern[0]! as Text
+					).value,
+				).toBe("after")
+			})
+		})
+
+		it("should react to `delete`", async () => {
+			await createRoot(async () => {
+				const query = createMessagesQuery(() => [
+					createMessage("1", { en: "" }),
+					createMessage("2", { en: "" }),
+					createMessage("3", { en: "" }),
+				])
+
+				let messages: Readonly<Message[]> | undefined = undefined
+				await createChangeListener(() => (messages = query.getAll()))
+				expect(Object.values(messages!)).toHaveLength(3)
+
+				query.delete({ where: { id: "1" } })
+				expect(Object.values(messages!)).toHaveLength(2)
+
+				// deleting the same id again should not have an effect
+				query.delete({ where: { id: "1" } })
+				expect(Object.values(messages!)).toHaveLength(2)
+
+				query.delete({ where: { id: "2" } })
+				expect(Object.values(messages!)).toHaveLength(1)
+
+				query.delete({ where: { id: "3" } })
+				expect(Object.values(messages!)).toHaveLength(0)
+			})
+		})
+
+		it("should react to changes to the input `messages`", async () => {
+			const [inputMessages, setMessages] = createSignal<Message[]>([
+				createMessage("1", { en: "before" }),
+			])
+			const query = createMessagesQuery(inputMessages)
+
+			let messages: Readonly<Message[]> | undefined = undefined
+			await createChangeListener(() => (messages = query.getAll()))
+			expect(Object.values(messages!)).toHaveLength(1)
+
+			query.create({ data: createMessage("2", { en: "" }) })
+			expect(Object.values(messages!)).toHaveLength(2)
+			expect(
+				(
+					Object.values(messages!)![0]!.variants.find((variant) => variant.languageTag === "en")!
+						.pattern[0]! as Text
+				).value,
+			).toBe("before")
+
+			setMessages([createMessage("1", { en: "after" })])
+			expect(Object.values(messages!)).toHaveLength(1)
+			expect(
+				(
+					Object.values(messages!)![0]!.variants.find((variant) => variant.languageTag === "en")!
+						.pattern[0]! as Text
+				).value,
+			).toBe("after")
+		})
+	})
+})
+
+it("instances should not share state", async () => {
+	await createRoot(async () => {
+		const query1 = createMessagesQuery(() => [createMessage("1", { en: "before" })])
+		const query2 = createMessagesQuery(() => [])
+
+		// eslint-disable-next-line unicorn/no-null
+		let message1: Message | undefined | null = null
+		await createChangeListener(() => (message1 = query1.get({ where: { id: "1" } })))
+		// eslint-disable-next-line unicorn/no-null
+		let message2: Message | undefined | null = null
+		await createChangeListener(() => (message2 = query2.get({ where: { id: "1" } })))
+
+		expect(message1).toBeDefined()
+		expect(message2).toBeUndefined()
+
+		query2.create({ data: createMessage("1", { en: "before" }) })
+		expect(message2).toBeDefined()
+
+		query1.update({ where: { id: "1" }, data: createMessage("1", { en: "after" }) })
+		expect(
+			(message1!.variants.find((variant) => variant.languageTag === "en")!.pattern[0]! as Text)
+				.value,
+		).toBe("after")
+		expect(
+			(message2!.variants.find((variant) => variant.languageTag === "en")!.pattern[0]! as Text)
+				.value,
+		).toBe("before")
+
+		query1.delete({ where: { id: "1" } })
+		expect(message1).toBeUndefined()
+		expect(message2).toBeDefined()
+	})
+})

package/src/createMessagesQuery.ts

@@ -0,0 +1,64 @@
+import type { Message } from "@inlang/message"
+import { ReactiveMap } from "./reactivity/map.js"
+import { createEffect } from "./reactivity/solid.js"
+import { createSubscribable } from "./openInlangProject.js"
+import type { InlangProject, MessageQueryApi } from "./api.js"
+
+/**
+ * Creates a reactive query API for messages.
+ */
+export function createMessagesQuery(
+	messages: () => Array<Message>,
+): InlangProject["query"]["messages"] {
+	// @ts-expect-error
+	const index = new ReactiveMap<string, Message>()
+
+	createEffect(() => {
+		index.clear()
+		for (const message of messages()) {
+			index.set(message.id, message)
+		}
+	})
+
+	const get = (args: Parameters<MessageQueryApi["get"]>[0]) => index.get(args.where.id)
+
+	return {
+		create: ({ data }): boolean => {
+			if (index.has(data.id)) return false
+			index.set(data.id, data)
+			return true
+		},
+		get: Object.assign(get, {
+			subscribe: (
+				args: Parameters<MessageQueryApi["get"]["subscribe"]>[0],
+				callback: Parameters<MessageQueryApi["get"]["subscribe"]>[1],
+			) => createSubscribable(() => get(args)).subscribe(callback),
+		}) as any,
+		includedMessageIds: createSubscribable(() => {
+			return [...index.keys()]
+		}),
+		getAll: createSubscribable(() => {
+			return [...index.values()]
+		}),
+		update: ({ where, data }): boolean => {
+			const message = index.get(where.id)
+			if (message === undefined) return false
+			index.set(where.id, { ...message, ...data })
+			return true
+		},
+		upsert: ({ where, data }) => {
+			const message = index.get(where.id)
+			if (message === undefined) {
+				index.set(where.id, data)
+			} else {
+				index.set(where.id, { ...message, ...data })
+			}
+			return true
+		},
+		delete: ({ where }): boolean => {
+			if (!index.has(where.id)) return false
+			index.delete(where.id)
+			return true
+		},
+	}
+}

package/src/errors.ts

@@ -0,0 +1,46 @@
+export class InvalidConfigError extends Error {
+	constructor(message: string, options: ErrorOptions) {
+		super(message, options)
+		this.name = "InvalidConfigError"
+	}
+}
+
+export class ProjectFileJSONSyntaxError extends Error {
+	constructor(message: string, options: ErrorOptions) {
+		super(message, options)
+		this.name = "ProjectFileJSONSyntaxError"
+	}
+}
+
+export class ProjectFilePathNotFoundError extends Error {
+	constructor(message: string, options: ErrorOptions) {
+		super(message, options)
+		this.name = "ProjectFilePathNotFoundError"
+	}
+}
+
+export class PluginSaveMessagesError extends Error {
+	constructor(message: string, options: ErrorOptions) {
+		super(message, options)
+		this.name = "PluginSaveMessagesError"
+	}
+}
+
+export class PluginLoadMessagesError extends Error {
+	constructor(message: string, options: ErrorOptions) {
+		super(message, options)
+		this.name = "PluginLoadMessagesError"
+	}
+}
+
+/**
+ * Error when no package provides the API to handle messages.
+ */
+export class NoPluginProvidesLoadOrSaveMessagesError extends Error {
+	constructor() {
+		super(
+			"It seems you did not install any plugin that handles messages. Please add one to make inlang work. See https://inlang.com/documentation/plugins/registry.",
+		) // TODO: check if link is correct
+		this.name = "NoPluginProvidesLoadOrSaveMessagesError"
+	}
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ *! PUBLIC API FOR THE INLANG SDK.
+ *!
+ *! EXPORT AS LITTLE AS POSSIBLE TO MINIMIZE THE CHANCE OF BREAKING CHANGES.
+ */
+
+export type {
+	InlangProject,
+	InstalledMessageLintRule,
+	InstalledPlugin,
+	MessageQueryApi,
+	Subscribable,
+} from "./api.js"
+export { type ImportFunction, createImport } from "./resolve-modules/index.js"
+export { openInlangProject } from "./openInlangProject.js"
+export { solidAdapter, type InlangProjectWithSolidAdapter } from "./adapter/solidAdapter.js"
+export { createMessagesQuery } from "./createMessagesQuery.js"
+export {
+	ProjectFilePathNotFoundError,
+	ProjectFileJSONSyntaxError,
+	InvalidConfigError,
+	NoPluginProvidesLoadOrSaveMessagesError,
+	PluginLoadMessagesError,
+	PluginSaveMessagesError,
+} from "./errors.js"
+
+export * from "./messages/variant.js"
+export * from "./versionedInterfaces.js"
+export { InlangModule } from "@inlang/module"

package/src/lint/index.ts

@@ -0,0 +1,2 @@
+export { lintSingleMessage } from "./message/lintSingleMessage.js"
+export { lintMessages } from "./message/lintMessages.js"

package/src/lint/message/errors.ts

@@ -0,0 +1,9 @@
+/**
+ * Error when a lint rule throws during the linting process.
+ */
+export class MessagedLintRuleThrowedError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options)
+		this.name = "MessagedLintRuleThrowedError"
+	}
+}