@inlang/sdk 0.35.4 → 0.35.6

package/dist/v2/types.js

@@ -67,3 +67,12 @@ export const MessageBundle = Type.Object({
     alias: Type.Record(Type.String(), Type.String()),
     messages: Type.Array(Message),
 });
+export const MessageSlot = Type.Object({
+    locale: LanguageTag,
+    slot: Type.Literal(true),
+});
+export const MessageBundleWithSlots = Type.Object({
+    id: Type.String(),
+    alias: Type.Record(Type.String(), Type.String()),
+    messages: Type.Array(Type.Union([Message, MessageSlot])),
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inlang/sdk",
   "type": "module",
-  "version": "0.35.4",
+  "version": "0.35.6",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -16,7 +16,8 @@
     "./test-utilities": "./dist/test-utilities/index.js",
     "./lint": "./dist/lint/index.js",
     "./messages": "./dist/messages/index.js",
-    "./v2": "./dist/v2/index.js"
+    "./v2": "./dist/v2/index.js",
+    "./v2-mocks": "./dist/v2/mocks/index.js"
   },
   "files": [
     "./dist",
@@ -34,16 +35,16 @@
     "solid-js": "1.6.12",
     "throttle-debounce": "^5.0.0",
     "@inlang/json-types": "1.1.0",
-    "@inlang/message": "2.1.0",
-    "@inlang/module": "1.2.13",
     "@inlang/language-tag": "1.5.1",
+    "@inlang/module": "1.2.13",
+    "@inlang/message": "2.1.0",
     "@inlang/plugin": "2.4.13",
-    "@inlang/result": "1.1.0",
+    "@inlang/project-settings": "2.4.2",
     "@inlang/message-lint-rule": "1.4.7",
+    "@inlang/result": "1.1.0",
+    "@lix-js/fs": "2.1.0",
     "@inlang/translatable": "1.3.1",
-    "@lix-js/client": "2.2.0",
-    "@inlang/project-settings": "2.4.2",
-    "@lix-js/fs": "2.1.0"
+    "@lix-js/client": "2.2.0"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/adapter/solidAdapter.test.ts

@@ -222,7 +222,7 @@ describe("messages", () => {
 		// TODO: how can we await `setConfig` correctly
 		await new Promise((resolve) => setTimeout(resolve, 510))
 
-		expect(effectOnMessagesCounter).toBe(3) // 3 = setSetting, loadMessage (2x - one per message)
+		expect(effectOnMessagesCounter).toBe(2) // 2 = setSetting (clearing the message index), subsequencial loadMessage call
 		expect(Object.values(project.query.messages.getAll()).length).toBe(2)
 	})
 

package/src/api.ts

@@ -10,7 +10,7 @@ import type {
 	MessageLintReport,
 } from "./versionedInterfaces.js"
 import type { ResolvedPluginApi } from "./resolve-modules/plugins/types.js"
-import type * as V2 from "./v2/types.js"
+import type { StoreApi } from "./persistence/storeApi.js"
 
 export type InstalledPlugin = {
 	id: Plugin["id"]
@@ -58,18 +58,7 @@ export type InlangProject = {
 	}
 	// WIP V2 message apis
 	// use with project settings: experimental.persistence = true
-	messageBundles?: Query<V2.MessageBundle>
-	messages?: Query<V2.Message>
-	variants?: Query<V2.Variant>
-}
-
-/**
- * WIP template for async V2 crud interfaces
- * E.g. `await project.messageBundles.get({ id: "..." })`
- **/
-interface Query<T> {
-	get: (args: unknown) => Promise<T>
-	getAll: () => Promise<T[]>
+	store?: StoreApi
 }
 
 // const x = {} as InlangProject

package/src/createMessagesQuery.ts

@@ -1,6 +1,6 @@
 import type { Message } from "@inlang/message"
 import { ReactiveMap } from "./reactivity/map.js"
-import { createEffect, onCleanup } from "./reactivity/solid.js"
+import { createEffect, onCleanup, batch } from "./reactivity/solid.js"
 import { createSubscribable } from "./loadProject.js"
 import type { InlangProject, MessageQueryApi, MessageQueryDelegate } from "./api.js"
 import type { ResolvedPluginApi } from "./resolve-modules/plugins/types.js"
@@ -16,10 +16,6 @@ import { PluginLoadMessagesError, PluginSaveMessagesError } from "./errors.js"
 import { humanIdHash } from "./storage/human-id/human-readable-id.js"
 const debug = _debug("sdk:messages")
 
-function sleep(ms: number) {
-	return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 type MessageState = {
 	messageDirtyFlags: {
 		[messageId: string]: boolean
@@ -278,8 +274,6 @@ export function createMessagesQuery({
 // - saving a message in two different languages would lead to a write in de.json first
 // - This will leads to a load of the messages and since en.json has not been saved yet the english variant in the message would get overritten with the old state again
 
-const maxMessagesPerTick = 500
-
 /**
  * Messsage that loads messages from a plugin - this method synchronizes with the saveMessage funciton.
  * If a save is in progress loading will wait until saving is done. If another load kicks in during this load it will queue the
@@ -326,104 +320,91 @@ async function loadMessagesViaPlugin(
 			})
 		)
 
-		let loadedMessageCount = 0
-
 		const deletedMessages = new Set(messages.keys())
-
-		for (const loadedMessage of loadedMessages) {
-			const loadedMessageClone = structuredClone(loadedMessage)
-
-			const currentMessages = [...messages.values()]
-				// TODO #1585 here we match using the id to support legacy load message plugins - after we introduced import / export methods we will use importedMessage.alias
-				.filter(
-					(message: any) =>
-						(experimentalAliases ? message.alias["default"] : message.id) === loadedMessage.id
-				)
-
-			if (currentMessages.length > 1) {
-				// NOTE: if we happen to find two messages witht the sam alias we throw for now
-				// - this could be the case if one edits the aliase manualy
-				throw new Error("more than one message with the same id or alias found ")
-			} else if (currentMessages.length === 1) {
-				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length has checked beforhand
-				deletedMessages.delete(currentMessages[0]!.id)
-				// update message in place - leave message id and alias untouched
-				loadedMessageClone.alias = {} as any
-
-				// TODO #1585 we have to map the id of the importedMessage to the alias and fill the id property with the id of the existing message - change when import mesage provides importedMessage.alias
-				if (experimentalAliases) {
-					loadedMessageClone.alias["default"] = loadedMessageClone.id
+		batch(() => {
+			for (const loadedMessage of loadedMessages) {
+				const loadedMessageClone = structuredClone(loadedMessage)
+
+				const currentMessages = [...messages.values()]
+					// TODO #1585 here we match using the id to support legacy load message plugins - after we introduced import / export methods we will use importedMessage.alias
+					.filter(
+						(message: any) =>
+							(experimentalAliases ? message.alias["default"] : message.id) === loadedMessage.id
+					)
+
+				if (currentMessages.length > 1) {
+					// NOTE: if we happen to find two messages witht the sam alias we throw for now
+					// - this could be the case if one edits the aliase manualy
+					throw new Error("more than one message with the same id or alias found ")
+				} else if (currentMessages.length === 1) {
 					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length has checked beforhand
-					loadedMessageClone.id = currentMessages[0]!.id
+					deletedMessages.delete(currentMessages[0]!.id)
+					// update message in place - leave message id and alias untouched
+					loadedMessageClone.alias = {} as any
+
+					// TODO #1585 we have to map the id of the importedMessage to the alias and fill the id property with the id of the existing message - change when import mesage provides importedMessage.alias
+					if (experimentalAliases) {
+						loadedMessageClone.alias["default"] = loadedMessageClone.id
+						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length has checked beforhand
+						loadedMessageClone.id = currentMessages[0]!.id
+					}
+
+					// NOTE stringifyMessage encodes messages independent from key order!
+					const importedEnecoded = stringifyMessage(loadedMessageClone)
+
+					// NOTE could use hash instead of the whole object JSON to save memory...
+					if (messageState.messageLoadHash[loadedMessageClone.id] === importedEnecoded) {
+						// debug("skipping upsert!")
+						continue
+					}
+
+					// This logic is preventing cycles - could also be handled if update api had a parameter for who triggered update
+					// e.g. when FS was updated, we don't need to write back to FS
+					// update is synchronous, so update effect will be triggered immediately
+					// NOTE: this might trigger a save before we have the chance to delete - but since save is async and waits for the lock acquired by this method - its save to set the flags afterwards
+					messages.set(loadedMessageClone.id, loadedMessageClone)
+					// NOTE could use hash instead of the whole object JSON to save memory...
+					messageState.messageLoadHash[loadedMessageClone.id] = importedEnecoded
+					delegate?.onMessageUpdate(loadedMessageClone.id, loadedMessageClone, [
+						...messages.values(),
+					])
+				} else {
+					// message with the given alias does not exist so far
+					loadedMessageClone.alias = {} as any
+					// TODO #1585 we have to map the id of the importedMessage to the alias - change when import mesage provides importedMessage.alias
+					if (experimentalAliases) {
+						loadedMessageClone.alias["default"] = loadedMessageClone.id
+
+						let currentOffset = 0
+						let messsageId: string | undefined
+						do {
+							messsageId = humanIdHash(loadedMessageClone.id, currentOffset)
+							if (messages.get(messsageId)) {
+								currentOffset += 1
+								messsageId = undefined
+							}
+						} while (messsageId === undefined)
+
+						// create a humanId based on a hash of the alias
+						loadedMessageClone.id = messsageId
+					}
+
+					const importedEnecoded = stringifyMessage(loadedMessageClone)
+
+					// we don't have to check - done before hand if (messages.has(loadedMessageClone.id)) return false
+					messages.set(loadedMessageClone.id, loadedMessageClone)
+					messageState.messageLoadHash[loadedMessageClone.id] = importedEnecoded
+					delegate?.onMessageUpdate(loadedMessageClone.id, loadedMessageClone, [
+						...messages.values(),
+					])
 				}
-
-				// NOTE stringifyMessage encodes messages independent from key order!
-				const importedEnecoded = stringifyMessage(loadedMessageClone)
-
-				// NOTE could use hash instead of the whole object JSON to save memory...
-				if (messageState.messageLoadHash[loadedMessageClone.id] === importedEnecoded) {
-					// debug("skipping upsert!")
-					continue
-				}
-
-				// This logic is preventing cycles - could also be handled if update api had a parameter for who triggered update
-				// e.g. when FS was updated, we don't need to write back to FS
-				// update is synchronous, so update effect will be triggered immediately
-				// NOTE: this might trigger a save before we have the chance to delete - but since save is async and waits for the lock acquired by this method - its save to set the flags afterwards
-				messages.set(loadedMessageClone.id, loadedMessageClone)
-				// NOTE could use hash instead of the whole object JSON to save memory...
-				messageState.messageLoadHash[loadedMessageClone.id] = importedEnecoded
-				delegate?.onMessageUpdate(loadedMessageClone.id, loadedMessageClone, [...messages.values()])
-				loadedMessageCount++
-			} else {
-				// message with the given alias does not exist so far
-				loadedMessageClone.alias = {} as any
-				// TODO #1585 we have to map the id of the importedMessage to the alias - change when import mesage provides importedMessage.alias
-				if (experimentalAliases) {
-					loadedMessageClone.alias["default"] = loadedMessageClone.id
-
-					let currentOffset = 0
-					let messsageId: string | undefined
-					do {
-						messsageId = humanIdHash(loadedMessageClone.id, currentOffset)
-						if (messages.get(messsageId)) {
-							currentOffset += 1
-							messsageId = undefined
-						}
-					} while (messsageId === undefined)
-
-					// create a humanId based on a hash of the alias
-					loadedMessageClone.id = messsageId
-				}
-
-				const importedEnecoded = stringifyMessage(loadedMessageClone)
-
-				// we don't have to check - done before hand if (messages.has(loadedMessageClone.id)) return false
-				messages.set(loadedMessageClone.id, loadedMessageClone)
-				messageState.messageLoadHash[loadedMessageClone.id] = importedEnecoded
-				delegate?.onMessageUpdate(loadedMessageClone.id, loadedMessageClone, [...messages.values()])
-				loadedMessageCount++
 			}
-			if (loadedMessageCount > maxMessagesPerTick) {
-				// move loading of the next messages to the next ticks to allow solid to cleanup resources
-				// solid needs some time to settle and clean up
-				// https://github.com/solidjs-community/solid-primitives/blob/9ca76a47ffa2172770e075a90695cf933da0ff48/packages/trigger/src/index.ts#L64
-				await sleep(0)
-				loadedMessageCount = 0
-			}
-		}
 
-		loadedMessageCount = 0
-		for (const deletedMessageId of deletedMessages) {
-			messages.delete(deletedMessageId)
-			delegate?.onMessageDelete(deletedMessageId, [...messages.values()])
-			loadedMessageCount++
-			if (loadedMessageCount > maxMessagesPerTick) {
-				await sleep(0)
-				loadedMessageCount = 0
+			for (const deletedMessageId of deletedMessages) {
+				messages.delete(deletedMessageId)
+				delegate?.onMessageDelete(deletedMessageId, [...messages.values()])
 			}
-		}
-
+		})
 		await releaseLock(fs as NodeishFilesystem, lockDirPath, "loadMessage", lockTime)
 		lockTime = undefined
 

package/src/createNewProject.test.ts

@@ -4,10 +4,7 @@ import { mockRepo } from "@lix-js/client"
 import { defaultProjectSettings } from "./defaultProjectSettings.js"
 import { loadProject } from "./loadProject.js"
 import { createMessage } from "./test-utilities/createMessage.js"
-
-function sleep(ms: number) {
-	return new Promise((resolve) => setTimeout(resolve, ms))
-}
+import { sleep } from "./test-utilities/sleep.js"
 
 describe("createNewProject", () => {
 	it("should throw if a path does not end with .inlang", async () => {

package/src/loadProject.test.ts

@@ -278,11 +278,15 @@ describe("initialization", () => {
 		expect(result.data).toBeDefined()
 	})
 
+	// TODO: fix this test
+	// https://github.com/opral/inlang-message-sdk/issues/76
+	// it doesn't work because failure to open the settings file doesn't throw
+	// errors are returned in project.errors()
 	it("should resolve from a windows path", async () => {
 		const repo = await mockRepo()
 		const fs = repo.nodeishFs
-		fs.mkdir("C:\\Users\\user\\project.inlang", { recursive: true })
-		fs.writeFile("C:\\Users\\user\\project.inlang\\settings.json", JSON.stringify(settings))
+		await fs.mkdir("C:\\Users\\user\\project.inlang", { recursive: true })
+		await fs.writeFile("C:\\Users\\user\\project.inlang\\settings.json", JSON.stringify(settings))
 
 		const result = await tryCatch(() =>
 			loadProject({

package/src/loadProject.ts

@@ -4,6 +4,8 @@ import type {
 	InstalledMessageLintRule,
 	InstalledPlugin,
 	Subscribable,
+	MessageQueryApi,
+	MessageLintReportsQueryApi,
 } from "./api.js"
 import { type ImportFunction, resolveModules } from "./resolve-modules/index.js"
 import { TypeCompiler, ValueErrorType } from "@sinclair/typebox/compiler"
@@ -30,6 +32,10 @@ import { maybeCreateFirstProjectId } from "./migrations/maybeCreateFirstProjectI
 import { capture } from "./telemetry/capture.js"
 import { identifyProject } from "./telemetry/groupIdentify.js"
 
+import { stubMessagesQuery, stubMessageLintReportsQuery } from "./v2/stubQueryApi.js"
+import type { StoreApi } from "./persistence/storeApi.js"
+import { openStore } from "./persistence/store.js"
+
 import _debug from "debug"
 const debug = _debug("sdk:loadProject")
 
@@ -80,9 +86,16 @@ export async function loadProject(args: {
 		)
 
 		const [initialized, markInitAsComplete, markInitAsFailed] = createAwaitable()
+		const [loadedSettings, markSettingsAsLoaded, markSettingsAsFailed] = createAwaitable()
 		// -- settings ------------------------------------------------------------
 
 		const [settings, _setSettings] = createSignal<ProjectSettings>()
+		let v2Persistence = false
+		let locales: string[] = []
+
+		// This effect currently has no signals
+		// TODO: replace createEffect with await loadSettings
+		// https://github.com/opral/inlang-message-sdk/issues/77
 		createEffect(() => {
 			// TODO:
 			// if (projectId) {
@@ -92,12 +105,17 @@ export async function loadProject(args: {
 			// }
 
 			loadSettings({ settingsFilePath: projectPath + "/settings.json", nodeishFs })
-				.then((settings) => setSettings(settings))
+				.then((settings) => {
+					setSettings(settings)
+					markSettingsAsLoaded()
+				})
 				.catch((err) => {
 					markInitAsFailed(err)
+					markSettingsAsFailed(err)
 				})
 		})
 		// TODO: create FS watcher and update settings on change
+		// https://github.com/opral/inlang-message-sdk/issues/35
 
 		const writeSettingsToDisk = skipFirst((settings: ProjectSettings) =>
 			_writeSettingsToDisk({ nodeishFs, settings, projectPath })
@@ -106,11 +124,8 @@ export async function loadProject(args: {
 		const setSettings = (settings: ProjectSettings): Result<void, ProjectSettingsInvalidError> => {
 			try {
 				const validatedSettings = parseSettings(settings)
-				if (validatedSettings.experimental?.persistence) {
-					settings["plugin.sdk.persistence"] = {
-						pathPattern: projectPath + "/messages.json",
-					}
-				}
+				v2Persistence = !!validatedSettings.experimental?.persistence
+				locales = validatedSettings.languageTags
 
 				batch(() => {
 					// reset the resolved modules first - since they are no longer valid at that point
@@ -147,40 +162,11 @@ export async function loadProject(args: {
 				.catch((err) => markInitAsFailed(err))
 		})
 
-		// -- messages ----------------------------------------------------------
+		// -- installed items ----------------------------------------------------
 
 		let settingsValue: ProjectSettings
-		createEffect(() => (settingsValue = settings()!)) // workaround to not run effects twice (e.g. settings change + modules change) (I'm sure there exists a solid way of doing this, but I haven't found it yet)
-
-		const [loadMessagesViaPluginError, setLoadMessagesViaPluginError] = createSignal<
-			Error | undefined
-		>()
-
-		const [saveMessagesViaPluginError, setSaveMessagesViaPluginError] = createSignal<
-			Error | undefined
-		>()
-
-		const messagesQuery = createMessagesQuery({
-			projectPath,
-			nodeishFs,
-			settings,
-			resolvedModules,
-			onInitialMessageLoadResult: (e) => {
-				if (e) {
-					markInitAsFailed(e)
-				} else {
-					markInitAsComplete()
-				}
-			},
-			onLoadMessageResult: (e) => {
-				setLoadMessagesViaPluginError(e)
-			},
-			onSaveMessageResult: (e) => {
-				setSaveMessagesViaPluginError(e)
-			},
-		})
-
-		// -- installed items ----------------------------------------------------
+		// workaround to not run effects twice (e.g. settings change + modules change) (I'm sure there exists a solid way of doing this, but I haven't found it yet)
+		createEffect(() => (settingsValue = settings()!))
 
 		const installedMessageLintRules = () => {
 			if (!resolvedModules()) return []
@@ -213,17 +199,69 @@ export async function loadProject(args: {
 			})) satisfies Array<InstalledPlugin>
 		}
 
+		// -- messages ----------------------------------------------------------
+
+		const [loadMessagesViaPluginError, setLoadMessagesViaPluginError] = createSignal<
+			Error | undefined
+		>()
+
+		const [saveMessagesViaPluginError, setSaveMessagesViaPluginError] = createSignal<
+			Error | undefined
+		>()
+
+		let messagesQuery: MessageQueryApi
+		let lintReportsQuery: MessageLintReportsQueryApi
+		let store: StoreApi | undefined
+
+		// wait for seetings to load v2Persistence flag
+		// .catch avoids throwing here if the awaitable is rejected
+		// error is recorded via markInitAsFailed so no need to capture it again
+		await loadedSettings.catch(() => {})
+
+		if (v2Persistence) {
+			messagesQuery = stubMessagesQuery
+			lintReportsQuery = stubMessageLintReportsQuery
+			try {
+				store = await openStore({ projectPath, nodeishFs, locales })
+				markInitAsComplete()
+			} catch (e) {
+				markInitAsFailed(e)
+			}
+		} else {
+			messagesQuery = createMessagesQuery({
+				projectPath,
+				nodeishFs,
+				settings,
+				resolvedModules,
+				onInitialMessageLoadResult: (e) => {
+					if (e) {
+						markInitAsFailed(e)
+					} else {
+						markInitAsComplete()
+					}
+				},
+				onLoadMessageResult: (e) => {
+					setLoadMessagesViaPluginError(e)
+				},
+				onSaveMessageResult: (e) => {
+					setSaveMessagesViaPluginError(e)
+				},
+			})
+
+			lintReportsQuery = createMessageLintReportsQuery(
+				messagesQuery,
+				settings as () => ProjectSettings,
+				installedMessageLintRules,
+				resolvedModules
+			)
+
+			store = undefined
+		}
+
 		// -- app ---------------------------------------------------------------
 
 		const initializeError: Error | undefined = await initialized.catch((error) => error)
 
-		const lintReportsQuery = createMessageLintReportsQuery(
-			messagesQuery,
-			settings as () => ProjectSettings,
-			installedMessageLintRules,
-			resolvedModules
-		)
-
 		/**
 		 * Utility to escape reactive tracking and avoid multiple calls to
 		 * the capture event.
@@ -250,6 +288,8 @@ export async function loadProject(args: {
 					settings: settings(),
 					installedPluginIds: installedPlugins().map((p) => p.id),
 					installedMessageLintRuleIds: installedMessageLintRules().map((r) => r.id),
+					// TODO: fix for v2Persistence
+					// https://github.com/opral/inlang-message-sdk/issues/78
 					numberOfMessages: messagesQuery.includedMessageIds().length,
 				},
 			})
@@ -276,6 +316,7 @@ export async function loadProject(args: {
 				messages: messagesQuery,
 				messageLintReports: lintReportsQuery,
 			},
+			store,
 		} satisfies InlangProject
 	})
 }

package/src/persistence/batchedIO.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from "vitest"
+import { sleep } from "../test-utilities/sleep.js"
+import { batchedIO } from "./batchedIO.js"
+
+let locked = false
+
+const instrumentAquireLockStart = vi.fn()
+
+async function mockAquireLock() {
+	instrumentAquireLockStart()
+	let pollCount = 0
+	while (locked && pollCount++ < 100) {
+		await sleep(10)
+	}
+	if (locked) {
+		throw new Error("Timeout acquiring lock")
+	}
+	await sleep(10)
+	locked = true
+	return 69
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+async function mockReleaseLock(_: number) {
+	sleep(10)
+	locked = false
+}
+
+const instrumentSaveStart = vi.fn()
+const instrumentSaveEnd = vi.fn()
+
+async function mockSave() {
+	instrumentSaveStart()
+	await sleep(50)
+	instrumentSaveEnd()
+}
+
+describe("batchedIO", () => {
+	it("queues 2 requests while waiting for lock and pushes 2 more to the next batch", async () => {
+		const save = batchedIO(mockAquireLock, mockReleaseLock, mockSave)
+		const p1 = save("1")
+		const p2 = save("2")
+		await sleep(5)
+		expect(instrumentAquireLockStart).toHaveBeenCalledTimes(1)
+		expect(instrumentSaveStart).not.toHaveBeenCalled()
+		await sleep(10)
+		expect(instrumentSaveStart).toHaveBeenCalled()
+		expect(instrumentSaveEnd).not.toHaveBeenCalled()
+		const p3 = save("3")
+		const p4 = save("4")
+		expect(instrumentAquireLockStart).toHaveBeenCalledTimes(2)
+		expect(locked).toBe(true)
+		await sleep(50)
+		expect(instrumentSaveEnd).toHaveBeenCalled()
+		expect(await p1).toBe("1")
+		expect(await p2).toBe("2")
+		expect(instrumentSaveStart).toHaveBeenCalledTimes(1)
+		expect(await p3).toBe("3")
+		expect(await p4).toBe("4")
+		expect(instrumentAquireLockStart).toHaveBeenCalledTimes(2)
+		expect(instrumentSaveStart).toHaveBeenCalledTimes(2)
+	})
+})

package/src/persistence/batchedIO.ts

@@ -0,0 +1,64 @@
+import _debug from "debug"
+const debug = _debug("sdk:batchedIO")
+
+/**
+ * State machine to convert async save() into batched async save()
+ * states = idle -> acquiring -> saving -> idle
+ * idle = nothing queued, ready to acquire lock.
+ * aquiring = waiting to acquire a lock: requests go into the queue.
+ * saving = lock is acquired, save has begun: new requests go into the next batch.
+ * The next batch should not acquire the lock while current save is in progress.
+ * Queued requests are only resolved when the save completes.
+ */
+export function batchedIO(
+	acquireLock: () => Promise<number>,
+	releaseLock: (lock: number) => Promise<void>,
+	save: () => Promise<void>
+): (id: string) => Promise<string> {
+	// 3-state machine
+	let state: "idle" | "acquiring" | "saving" = "idle"
+
+	// Hold requests while acquiring, resolve after saving
+	// TODO: rejectQueued if save throws (maybe?)
+	// https://github.com/opral/inlang-message-sdk/issues/79
+	type Queued = {
+		id: string
+		resolve: (value: string) => void
+		reject: (reason: any) => void
+	}
+	const queue: Queued[] = []
+
+	// initialize nextBatch lazily, reset after saving
+	let nextBatch: ((id: string) => Promise<string>) | undefined = undefined
+
+	// batched save function
+	return async (id: string) => {
+		if (state === "idle") {
+			state = "acquiring"
+			const lock = await acquireLock()
+			state = "saving"
+			await save()
+			await releaseLock(lock)
+			resolveQueued()
+			nextBatch = undefined
+			state = "idle"
+			return id
+		} else if (state === "acquiring") {
+			return new Promise<string>((resolve, reject) => {
+				queue.push({ id, resolve, reject })
+			})
+		} else {
+			// state === "saving"
+			nextBatch = nextBatch ?? batchedIO(acquireLock, releaseLock, save)
+			return await nextBatch(id)
+		}
+	}
+
+	function resolveQueued() {
+		debug("batched", queue.length + 1)
+		for (const { id, resolve } of queue) {
+			resolve(id)
+		}
+		queue.length = 0
+	}
+}