Datasource

The core package uses a Datasource abstraction so CLI commands can read and write project entities through one consistent interface. This is one of the main reasons the rest of Messagevisor can stay mostly format-agnostic.

What it exposes#

The datasource can:

list, read, and write locales
list, read, and write messages
list, read, and write attributes
list, read, and write segments
list, read, and write targets
list, read, and write tests
read and write datafiles and revisions
read versioned entity documents for optimistic concurrency
preview and apply serialized batches of writes and deletions with optimistic concurrency
plan reference-aware entity renames

Datasource adapters use an asynchronous contract for every operation, including existence checks. A custom adapter can therefore use a remote store or asynchronous filesystem API without exposing different return types to callers.

Why it exists#

Datasource keeps core workflows from caring too much about:

file layout details
parser implementation details
set-specific path resolution

That makes it easier for the rest of the CLI to focus on Messagevisor semantics instead of filesystem minutiae.

Default filesystem datasource#

Most projects use the default filesystem datasource. It reads entity definitions from the configured project directories:

locales/
messages/
attributes/
segments/
targets/
tests/

The selected parser decides how each file is decoded. That is why the same project model can work with YAML or JSON starters.

Entity keys are derived from their canonical file paths. A key property inside a document cannot spoof that identity and is not persisted when an entity is written. Namespace segments are restricted to letters, numbers, _, and -; path separators and traversal segments are rejected before filesystem access.

Editorial mutations#

The core editorial API is designed for Catalog's development-mode editing workflow and other authoring tools:

readEntityDocument returns the entity plus a content-hash version.
applyEntityMutations accepts expected versions, rejects stale writes, supports dry runs, serializes filesystem mutation batches, and rolls a caught failure back. Individual files are replaced atomically. A filesystem cannot make several file replacements one indivisible operation across a process or machine interruption, so callers should re-read versions after an interrupted editorial operation.
previewEntityMutations validates the projected project before anything is written.
renameEntity updates direct references across messages, segments, locales, targets, and tests in one optimistic-concurrency batch.

This lets a UI detect that a file changed in another editor, show a validation preview, and commit related changes together instead of leaving half-updated references on disk.

When you should care#

Most users do not need to implement a datasource. You should care about it when:

embedding Messagevisor in another tool
experimenting with non-filesystem storage
building an internal CLI plugin that needs to read project entities
debugging custom directory paths or sets behavior

Sets support#

For sets-based projects, the datasource can create a set-specific view while keeping one shared top-level configuration model.