@vouchington/localization 0.0.0 → 0.0.1

package/README.md

@@ -5,5 +5,12 @@ normalization (`en` aliases `en-US`), exact and terminal-prefix selector validat
 fallback, consumer membership, and deterministic catalog serialization. It does not load catalogs,
 open SQLite, or interpolate message text.
 
-`@vouchington/localization-compiler` compiles namespace-sharded JSON into an immutable SQLite
-artifact and resolves the same selectors locally.
+Catalog shards on disk are a JSON array with **one compact message object per line**. `id` is the
+first key so git and line editors can add, remove, or update a message without parsing the file.
+`parseCatalogShardText` rejects pretty-printed JSON, `{ messages }` wrappers, and unsorted ids.
+
+`@vouchington/localization-compiler` compiles those shards into an immutable SQLite artifact,
+resolves the same selectors locally, and ships `upsert` / `remove` / `git-merge` for the line
+format. `git-merge` is 3-way: union independent ids, then merge consumers, descriptor, and
+each locale. Same-locale edits conflict and write `<<<<<<< ours` markers; adding `es` on one
+side and `fr` on the other does not.

package/dist/catalog.d.mts

@@ -1,3 +1,7 @@
 import type { CatalogMessage } from './types.mts';
 export declare function serializeCatalogMessages(messages: readonly CatalogMessage[]): string;
+export declare function serializeCatalogLine(message: CatalogMessage): string;
+export declare function serializeCatalogShard(messages: readonly CatalogMessage[]): string;
+export declare function serializeCatalogShardFromLines(lines: readonly string[]): string;
+export declare function catalogLineId(line: string): string;
 export declare function catalogMessageFromRecord(value: unknown): CatalogMessage;

package/dist/catalog.mjs

@@ -1,10 +1,12 @@
 import { uniqueConsumers } from './consumers.mjs';
+import { compareCodePoints } from './compare.mjs';
 import { parseDescriptor } from './descriptors.mjs';
 import { canonicalJson } from './serialize.mjs';
 import { isMessageId } from './selectors.mjs';
+const ID_PREFIX = '{"id":"';
 export function serializeCatalogMessages(messages) {
     return canonicalJson([...messages]
-        .toSorted((left, right) => (left.id < right.id ? -1 : 1))
+        .toSorted((left, right) => compareCodePoints(left.id, right.id))
         .map((message) => ({
         consumers: uniqueConsumers(message.consumers),
         descriptor: message.descriptor,
@@ -12,6 +14,36 @@ export function serializeCatalogMessages(messages) {
         translations: message.translations,
     })));
 }
+export function serializeCatalogLine(message) {
+    const normalized = catalogMessageFromRecord(message);
+    // id first for line edits; not canonicalJson key order (revision hashing uses that).
+    return `{"id":${canonicalJson(normalized.id)},"consumers":${canonicalJson(normalized.consumers)},"descriptor":${canonicalJson(normalized.descriptor)},"translations":${canonicalJson(normalized.translations)}}`;
+}
+export function serializeCatalogShard(messages) {
+    return serializeCatalogShardFromLines([...messages]
+        .toSorted((left, right) => compareCodePoints(left.id, right.id))
+        .map(serializeCatalogLine));
+}
+export function serializeCatalogShardFromLines(lines) {
+    if (lines.length === 0)
+        return '[]\n';
+    for (const line of lines) {
+        if (line.includes('\n') || line.includes('\r')) {
+            throw new TypeError('Catalog line must not contain newlines');
+        }
+    }
+    return `[\n${lines.map((line, index) => (index < lines.length - 1 ? `${line},` : line)).join('\n')}\n]\n`;
+}
+export function catalogLineId(line) {
+    const body = line.endsWith(',') ? line.slice(0, -1) : line;
+    if (!body.startsWith(ID_PREFIX)) {
+        throw new TypeError('Catalog line must start with {"id":');
+    }
+    const end = body.indexOf('"', ID_PREFIX.length);
+    if (end === -1)
+        throw new TypeError('Catalog line is missing a message id');
+    return body.slice(ID_PREFIX.length, end);
+}
 export function catalogMessageFromRecord(value) {
     if (!isPlainObject(value) || typeof value.id !== 'string' || !isMessageId(value.id)) {
         throw new TypeError('Catalog message is missing a valid id');

package/dist/descriptors.d.mts

@@ -2,5 +2,6 @@ import { type MessageDescriptor, type PluralForms, type TranslationValue } from
 export declare function isPluralForms(value: unknown): value is PluralForms;
 export declare function isSelectPluralCases(value: unknown): value is Readonly<Record<string, PluralForms>>;
 export declare function isTranslationValue(value: unknown): value is TranslationValue;
+export declare function translationMatchesDescriptor(descriptor: MessageDescriptor | null, value: unknown): boolean;
 export declare function descriptorSignature(descriptor: MessageDescriptor): string;
 export declare function parseDescriptor(value: unknown): MessageDescriptor | null;

package/dist/descriptors.mjs

@@ -14,6 +14,15 @@ export function isSelectPluralCases(value) {
 export function isTranslationValue(value) {
     return typeof value === 'string' || isPluralForms(value) || isSelectPluralCases(value);
 }
+export function translationMatchesDescriptor(descriptor, value) {
+    if (descriptor === null)
+        return typeof value === 'string';
+    if (descriptor.kind === 'plural')
+        return isPluralForms(value);
+    return (isSelectPluralCases(value) &&
+        descriptorSignature({ ...descriptor, cases: Object.keys(value) }) ===
+            descriptorSignature(descriptor));
+}
 export function descriptorSignature(descriptor) {
     return JSON.stringify({
         kind: descriptor.kind,

package/dist/index.d.mts

@@ -7,8 +7,11 @@ export { dedupeSelectors, isMessageId, parseSelector, prefixRange, selectorMatch
 export { assertMessageCount, assertPayloadBytes, normalizeLocalizationRequest } from './request.mts';
 export { firstAvailableTranslation, leafForTranslation, selectedIds } from './selection.mts';
 export { assertSamePlaceholders, placeholdersIn, uniquePlaceholders } from './placeholders.mts';
-export { descriptorSignature, isPluralForms, isSelectPluralCases, isTranslationValue, parseDescriptor, } from './descriptors.mts';
+export { descriptorSignature, isPluralForms, isSelectPluralCases, isTranslationValue, parseDescriptor, translationMatchesDescriptor, } from './descriptors.mts';
 export { canonicalJson } from './serialize.mts';
 export { compareCodePoints } from './compare.mts';
-export { catalogMessageFromRecord, serializeCatalogMessages } from './catalog.mts';
+export { catalogLineId, catalogMessageFromRecord, serializeCatalogLine, serializeCatalogMessages, serializeCatalogShard, serializeCatalogShardFromLines, } from './catalog.mts';
+export { catalogShardLines, parseCatalogShardText } from './shard-text.mts';
+export { removeCatalogLine, upsertCatalogLine } from './shard-edit.mts';
+export { CatalogMergeConflict, mergeCatalogShards } from './shard-merge.mts';
 export { createLocalizationBatch, etagMatches, localizationEtag, serializeLocalizationBatch, } from './wire.mts';

package/dist/index.mjs

@@ -6,8 +6,11 @@ export { dedupeSelectors, isMessageId, parseSelector, prefixRange, selectorMatch
 export { assertMessageCount, assertPayloadBytes, normalizeLocalizationRequest } from './request.mjs';
 export { firstAvailableTranslation, leafForTranslation, selectedIds } from './selection.mjs';
 export { assertSamePlaceholders, placeholdersIn, uniquePlaceholders } from './placeholders.mjs';
-export { descriptorSignature, isPluralForms, isSelectPluralCases, isTranslationValue, parseDescriptor, } from './descriptors.mjs';
+export { descriptorSignature, isPluralForms, isSelectPluralCases, isTranslationValue, parseDescriptor, translationMatchesDescriptor, } from './descriptors.mjs';
 export { canonicalJson } from './serialize.mjs';
 export { compareCodePoints } from './compare.mjs';
-export { catalogMessageFromRecord, serializeCatalogMessages } from './catalog.mjs';
+export { catalogLineId, catalogMessageFromRecord, serializeCatalogLine, serializeCatalogMessages, serializeCatalogShard, serializeCatalogShardFromLines, } from './catalog.mjs';
+export { catalogShardLines, parseCatalogShardText } from './shard-text.mjs';
+export { removeCatalogLine, upsertCatalogLine } from './shard-edit.mjs';
+export { CatalogMergeConflict, mergeCatalogShards } from './shard-merge.mjs';
 export { createLocalizationBatch, etagMatches, localizationEtag, serializeLocalizationBatch, } from './wire.mjs';

package/dist/shard-edit.d.mts

@@ -0,0 +1,2 @@
+export declare function upsertCatalogLine(shardText: string, messageJson: string): string;
+export declare function removeCatalogLine(shardText: string, id: string): string;

package/dist/shard-edit.mjs

@@ -0,0 +1,20 @@
+import { catalogLineId, catalogMessageFromRecord, serializeCatalogLine, serializeCatalogShardFromLines, } from './catalog.mjs';
+import { compareCodePoints } from './compare.mjs';
+import { catalogShardLines } from './shard-text.mjs';
+export function upsertCatalogLine(shardText, messageJson) {
+    const line = serializeCatalogLine(catalogMessageFromRecord(JSON.parse(messageJson)));
+    const id = catalogLineId(line);
+    const next = catalogShardLines(shardText).filter((current) => catalogLineId(current) !== id);
+    next.push(line);
+    return serializeCatalogShardFromLines(sortedLines(next));
+}
+export function removeCatalogLine(shardText, id) {
+    const lines = catalogShardLines(shardText);
+    const next = lines.filter((line) => catalogLineId(line) !== id);
+    if (next.length === lines.length)
+        throw new TypeError(`Catalog does not contain "${id}"`);
+    return serializeCatalogShardFromLines(sortedLines(next));
+}
+function sortedLines(lines) {
+    return [...lines].toSorted((left, right) => compareCodePoints(catalogLineId(left), catalogLineId(right)));
+}

package/dist/shard-merge.d.mts

@@ -0,0 +1,6 @@
+export declare class CatalogMergeConflict extends Error {
+    readonly ids: readonly string[];
+    readonly text: string;
+    constructor(ids: readonly string[], text: string);
+}
+export declare function mergeCatalogShards(ancestor: string, ours: string, theirs: string): string;

package/dist/shard-merge.mjs

@@ -0,0 +1,147 @@
+import { catalogLineId, catalogMessageFromRecord, serializeCatalogLine, serializeCatalogShardFromLines, } from './catalog.mjs';
+import { compareCodePoints } from './compare.mjs';
+import { uniqueConsumers } from './consumers.mjs';
+import { canonicalJson } from './serialize.mjs';
+import { catalogShardLines } from './shard-text.mjs';
+import { translationMatchesDescriptor } from './descriptors.mjs';
+import { LOCALIZATION_CONSUMERS } from './types.mjs';
+const CONFLICT = Symbol('conflict');
+export class CatalogMergeConflict extends Error {
+    ids;
+    text;
+    constructor(ids, text) {
+        super(`Catalog merge conflict for ${ids.map((id) => `"${id}"`).join(', ')}`);
+        this.name = 'CatalogMergeConflict';
+        this.ids = ids;
+        this.text = text;
+    }
+}
+export function mergeCatalogShards(ancestor, ours, theirs) {
+    const base = lineMap(ancestor);
+    const left = lineMap(ours);
+    const right = lineMap(theirs);
+    const ids = [...new Set([...base.keys(), ...left.keys(), ...right.keys()])].toSorted(compareCodePoints);
+    const lines = [];
+    const entries = [];
+    const conflicts = [];
+    for (const id of ids) {
+        const oursLine = left.get(id);
+        const theirsLine = right.get(id);
+        const kept = mergeLine(base.get(id), oursLine, theirsLine);
+        if (kept === false) {
+            conflicts.push(id);
+            entries.push({ ours: oursLine, theirs: theirsLine });
+        }
+        else if (kept !== undefined) {
+            lines.push(kept);
+            entries.push(kept);
+        }
+    }
+    if (conflicts.length > 0)
+        throw new CatalogMergeConflict(conflicts, serializeConflicted(entries));
+    return serializeCatalogShardFromLines(lines);
+}
+function lineMap(text) {
+    const map = new Map();
+    for (const line of catalogShardLines(text)) {
+        const id = catalogLineId(line);
+        if (map.has(id))
+            throw new TypeError(`Duplicate message id "${id}"`);
+        map.set(id, line);
+    }
+    return map;
+}
+function serializeConflicted(entries) {
+    const chunks = ['['];
+    for (const [index, entry] of entries.entries()) {
+        const suffix = index < entries.length - 1 ? ',' : '';
+        if (typeof entry === 'string') {
+            chunks.push(`${entry}${suffix}`);
+            continue;
+        }
+        chunks.push('<<<<<<< ours');
+        if (entry.ours !== undefined)
+            chunks.push(`${entry.ours}${suffix}`);
+        chunks.push('=======');
+        if (entry.theirs !== undefined)
+            chunks.push(`${entry.theirs}${suffix}`);
+        chunks.push('>>>>>>> theirs');
+    }
+    chunks.push(']');
+    return `${chunks.join('\n')}\n`;
+}
+function mergeLine(ancestor, ours, theirs) {
+    if (ours === theirs)
+        return ours;
+    if (ours === ancestor)
+        return theirs;
+    if (theirs === ancestor)
+        return ours;
+    if (ours === undefined || theirs === undefined)
+        return false;
+    return mergeEditedLines(ancestor, ours, theirs);
+}
+function mergeEditedLines(ancestor, ours, theirs) {
+    const base = ancestor === undefined ? emptyDraft(ours) : messageFromLine(ancestor);
+    const left = messageFromLine(ours);
+    const right = messageFromLine(theirs);
+    const consumers = mergeConsumers(base.consumers, left.consumers, right.consumers);
+    const descriptor = mergeValue(base.descriptor, left.descriptor, right.descriptor);
+    const translations = mergeTranslations(base.translations, left.translations, right.translations);
+    if (descriptor === CONFLICT || translations === CONFLICT)
+        return false;
+    if (!Object.values(translations).every((value) => translationMatchesDescriptor(descriptor, value))) {
+        return false;
+    }
+    try {
+        return serializeCatalogLine(catalogMessageFromRecord({ id: left.id, consumers, descriptor, translations }));
+    }
+    catch {
+        return false;
+    }
+}
+function emptyDraft(line) {
+    return { id: catalogLineId(line), descriptor: null, consumers: [], translations: {} };
+}
+function messageFromLine(line) {
+    return catalogMessageFromRecord(JSON.parse(line));
+}
+function mergeConsumers(ancestor, ours, theirs) {
+    const kept = [];
+    for (const consumer of LOCALIZATION_CONSUMERS) {
+        if (mergeValue(ancestor.includes(consumer), ours.includes(consumer), theirs.includes(consumer)) === true) {
+            kept.push(consumer);
+        }
+    }
+    return uniqueConsumers(kept);
+}
+function mergeTranslations(ancestor, ours, theirs) {
+    const locales = new Set([...Object.keys(ancestor), ...Object.keys(ours), ...Object.keys(theirs)]);
+    const translations = {};
+    for (const locale of [...locales].toSorted(compareCodePoints)) {
+        const value = mergeValue(ancestor[locale], ours[locale], theirs[locale]);
+        if (value === CONFLICT)
+            return CONFLICT;
+        if (value !== undefined)
+            translations[locale] = value;
+    }
+    return translations;
+}
+function mergeValue(ancestor, ours, theirs) {
+    if (same(ours, theirs))
+        return ours;
+    if (same(ours, ancestor))
+        return theirs;
+    if (same(theirs, ancestor))
+        return ours;
+    return CONFLICT;
+}
+function same(left, right) {
+    if (left === right)
+        return true;
+    if (left === undefined || right === undefined || left === null || right === null)
+        return false;
+    if (typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    return canonicalJson(left) === canonicalJson(right);
+}

package/dist/shard-text.d.mts

@@ -0,0 +1,3 @@
+import type { CatalogMessage } from './types.mts';
+export declare function catalogShardLines(text: string): string[];
+export declare function parseCatalogShardText(text: string): CatalogMessage[];

package/dist/shard-text.mjs

@@ -0,0 +1,48 @@
+import { catalogLineId, catalogMessageFromRecord, serializeCatalogLine } from './catalog.mjs';
+import { compareCodePoints } from './compare.mjs';
+export function catalogShardLines(text) {
+    if (text === '[]\n' || text === '')
+        return [];
+    if (!text.startsWith('[\n') || !text.endsWith('\n]\n')) {
+        throw new TypeError(text.includes('\r')
+            ? 'Catalog shard must use LF line endings'
+            : 'Catalog shard must be a JSON array with one message per line');
+    }
+    const raw = text.slice(2, -3).split('\n');
+    if (raw.length === 1 && raw[0] === '') {
+        throw new TypeError('Empty catalog shard must be written []\n');
+    }
+    return raw.map((line, index) => {
+        const needsComma = index < raw.length - 1;
+        if (line.endsWith(',') !== needsComma) {
+            throw new TypeError('Catalog shard commas must appear on every line except the last');
+        }
+        const body = needsComma ? line.slice(0, -1) : line;
+        if (body.length === 0) {
+            throw new TypeError('Catalog shard messages must be exactly one line each');
+        }
+        catalogLineId(body);
+        return body;
+    });
+}
+export function parseCatalogShardText(text) {
+    const lines = catalogShardLines(text);
+    const messages = lines.map((line) => {
+        const message = catalogMessageFromRecord(JSON.parse(line));
+        const canonical = serializeCatalogLine(message);
+        if (canonical !== line) {
+            throw new TypeError(`Catalog line for "${message.id}" is not canonical; expected ${canonical}. Run format to rewrite.`);
+        }
+        return message;
+    });
+    for (let index = 1; index < messages.length; index++) {
+        const previous = messages[index - 1].id;
+        const current = messages[index].id;
+        if (previous === current)
+            throw new TypeError(`Duplicate message id "${current}"`);
+        if (compareCodePoints(previous, current) > 0) {
+            throw new TypeError('Catalog shard ids must be sorted');
+        }
+    }
+    return messages;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/localization",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Browser-safe localization catalog contracts, locale fallback, and selector validation.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/localization#readme",
   "bugs": {
@@ -31,11 +31,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "prepack": "pnpm run build"
-  },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json"
   }
-}
+}