@worldware/msg 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/dist/{chunk-NWJ7MVVV.mjs → chunk-DJFPVXQ5.mjs} +15 -0
  2. package/dist/{chunk-HCR2UNSE.mjs → chunk-F3VAAZJZ.mjs} +39 -0
  3. package/dist/{chunk-X6CRKSNU.mjs → chunk-IMOOTZIK.mjs} +68 -1
  4. package/dist/chunk-PU7ZZ5XH.mjs +13 -0
  5. package/dist/classes/MsgInterface/MsgInterface.d.cts +24 -1
  6. package/dist/classes/MsgInterface/MsgInterface.d.ts +24 -1
  7. package/dist/classes/MsgMessage/MsgMessage.cjs +39 -0
  8. package/dist/classes/MsgMessage/MsgMessage.d.cts +51 -0
  9. package/dist/classes/MsgMessage/MsgMessage.d.ts +51 -0
  10. package/dist/classes/MsgMessage/MsgMessage.mjs +1 -1
  11. package/dist/classes/MsgProject/MsgProject.cjs +15 -0
  12. package/dist/classes/MsgProject/MsgProject.d.cts +1 -1
  13. package/dist/classes/MsgProject/MsgProject.d.ts +1 -1
  14. package/dist/classes/MsgProject/MsgProject.mjs +1 -1
  15. package/dist/classes/MsgResource/MsgResource.cjs +106 -0
  16. package/dist/classes/MsgResource/MsgResource.d.cts +124 -2
  17. package/dist/classes/MsgResource/MsgResource.d.ts +124 -2
  18. package/dist/classes/MsgResource/MsgResource.mjs +2 -2
  19. package/dist/classes/index.cjs +121 -0
  20. package/dist/classes/index.d.cts +2 -2
  21. package/dist/classes/index.d.ts +2 -2
  22. package/dist/classes/index.mjs +5 -5
  23. package/dist/index.cjs +121 -0
  24. package/dist/index.d.cts +2 -2
  25. package/dist/index.d.ts +2 -2
  26. package/dist/index.mjs +5 -5
  27. package/dist/lib/index.cjs +40 -0
  28. package/dist/lib/index.d.cts +1 -0
  29. package/dist/lib/index.d.ts +1 -0
  30. package/dist/lib/index.mjs +8 -0
  31. package/dist/lib/lang-utils.cjs +38 -0
  32. package/dist/lib/lang-utils.d.cts +14 -0
  33. package/dist/lib/lang-utils.d.ts +14 -0
  34. package/dist/lib/lang-utils.mjs +8 -0
  35. package/package.json +1 -1
package/dist/index.cjs CHANGED
@@ -45,6 +45,9 @@ var MsgMessage = class _MsgMessage {
45
45
  _mf;
46
46
  _attributes;
47
47
  _notes = [];
48
+ /**
49
+ * Creates a message from its parts. Prefer {@link MsgMessage.create}.
50
+ */
48
51
  constructor(key, value, attributes, notes) {
49
52
  this._key = key;
50
53
  this._value = value;
@@ -53,23 +56,33 @@ var MsgMessage = class _MsgMessage {
53
56
  notes.forEach((note) => this.addNote(note));
54
57
  }
55
58
  }
59
+ /**
60
+ * Builds a message from {@link MsgMessageData}.
61
+ */
56
62
  static create(data) {
57
63
  const { key, value, attributes, notes } = data;
58
64
  const message = new _MsgMessage(key, value, attributes, notes);
59
65
  return message;
60
66
  }
67
+ /** Unique key that identifies this message within a resource. */
61
68
  get key() {
62
69
  return this._key;
63
70
  }
71
+ /** The message string, possibly in MessageFormat syntax. */
64
72
  get value() {
65
73
  return this._value;
66
74
  }
75
+ /** Locale and formatting metadata for this message. */
67
76
  get attributes() {
68
77
  return this._attributes;
69
78
  }
79
+ /** Notes attached to this message for translators and tooling. */
70
80
  get notes() {
71
81
  return this._notes;
72
82
  }
83
+ /**
84
+ * Appends a note to this message.
85
+ */
73
86
  addNote(note) {
74
87
  this.notes.push(note);
75
88
  }
@@ -79,24 +92,42 @@ var MsgMessage = class _MsgMessage {
79
92
  resolveFormat() {
80
93
  return this.attributes.format ?? MSG_DEFAULT_FORMAT;
81
94
  }
95
+ /**
96
+ * Returns a cached MessageFormat formatter for this message's value.
97
+ */
82
98
  getFormatter(options) {
83
99
  if (!this._mf) {
84
100
  this._mf = this.resolveFormat() === "MF1" ? (0, import_icu_messageformat_1.mf1ToMessage)(this.attributes.lang, this.value, options) : new import_messageformat.MessageFormat(this.attributes.lang, this.value, options);
85
101
  }
86
102
  return this._mf;
87
103
  }
104
+ /**
105
+ * Formats the message with the given placeholder data.
106
+ *
107
+ * For `NONE` format messages, returns the raw value unchanged.
108
+ */
88
109
  format(data, options) {
89
110
  if (this.resolveFormat() === "NONE") {
90
111
  return this.value;
91
112
  }
92
113
  return this.getFormatter(options).format(data);
93
114
  }
115
+ /**
116
+ * Formats the message into structured parts with the given placeholder data.
117
+ *
118
+ * For `NONE` format messages, returns a single text part with the raw value.
119
+ */
94
120
  formatToParts(data, options) {
95
121
  if (this.resolveFormat() === "NONE") {
96
122
  return [{ type: "text", value: this.value }];
97
123
  }
98
124
  return this.getFormatter(options).formatToParts(data);
99
125
  }
126
+ /**
127
+ * Returns a plain data object for this message.
128
+ *
129
+ * @param stripNotes - When true, notes are omitted from the result.
130
+ */
100
131
  getData(stripNotes = false) {
101
132
  return {
102
133
  key: this.key,
@@ -105,9 +136,17 @@ var MsgMessage = class _MsgMessage {
105
136
  notes: !stripNotes && this.notes.length > 0 ? this.notes : void 0
106
137
  };
107
138
  }
139
+ /**
140
+ * Returns the message value as a string.
141
+ */
108
142
  toString() {
109
143
  return this.value;
110
144
  }
145
+ /**
146
+ * Serializes this message to a formatted JSON string.
147
+ *
148
+ * @param stripNotes - When true, notes are omitted from the serialized data.
149
+ */
111
150
  toJSON(stripNotes = false) {
112
151
  return JSON.stringify(this.getData(stripNotes), null, 2);
113
152
  }
@@ -121,6 +160,12 @@ var MsgResource = class _MsgResource extends Map {
121
160
  _notes = [];
122
161
  _title;
123
162
  _project;
163
+ /**
164
+ * Builds a resource from {@link MsgResourceData} and an owning project.
165
+ *
166
+ * When `messages` is provided, each entry is added to the resource.
167
+ * When omitted, the resource starts empty.
168
+ */
124
169
  static create(data, project) {
125
170
  const { title, attributes, notes, messages } = data;
126
171
  const res = new _MsgResource(title, attributes, project, notes);
@@ -134,6 +179,9 @@ var MsgResource = class _MsgResource extends Map {
134
179
  }
135
180
  return res;
136
181
  }
182
+ /**
183
+ * Creates a resource bound to a project. Prefer {@link MsgResource.create}.
184
+ */
137
185
  constructor(title, attributes, project, notes) {
138
186
  super();
139
187
  this._title = title;
@@ -143,14 +191,23 @@ var MsgResource = class _MsgResource extends Map {
143
191
  notes.forEach((note) => this.addNote(note));
144
192
  }
145
193
  }
194
+ /**
195
+ * Returns true when the message's attributes match this resource's attributes.
196
+ */
146
197
  hasMatchingAttributes(message) {
147
198
  const res = this.attributes;
148
199
  const msg = message.attributes;
149
200
  return res.lang === msg.lang && res.dir === msg.dir && res.dnt === msg.dnt && this.resolveFormat(res) === this.resolveFormat(msg);
150
201
  }
202
+ /**
203
+ * Resolves a format from attributes, falling back to the library default.
204
+ */
151
205
  resolveFormat(attributes) {
152
206
  return attributes.format ?? MSG_DEFAULT_FORMAT;
153
207
  }
208
+ /**
209
+ * Pseudo-localizes an MF2 message by localizing only literal text parts.
210
+ */
154
211
  pseudoLocalizeMF2(source, options) {
155
212
  const msg = (0, import_messageformat2.parseMessage)(source);
156
213
  (0, import_messageformat2.visit)(msg, {
@@ -165,30 +222,47 @@ var MsgResource = class _MsgResource extends Map {
165
222
  });
166
223
  return (0, import_messageformat2.stringifyMessage)(msg);
167
224
  }
225
+ /** Locale and formatting metadata for this resource. */
168
226
  get attributes() {
169
227
  return this._attributes;
170
228
  }
229
+ /** Replaces the resource's locale and formatting metadata. */
171
230
  set attributes(attributes) {
172
231
  this._attributes = attributes;
173
232
  }
233
+ /** Notes attached to this resource for translators and tooling. */
174
234
  get notes() {
175
235
  return this._notes;
176
236
  }
237
+ /** Replaces the notes attached to this resource. */
177
238
  set notes(notes) {
178
239
  this._notes = notes;
179
240
  }
241
+ /**
242
+ * Appends a note to this resource.
243
+ */
180
244
  addNote(note) {
181
245
  this.notes.push(note);
182
246
  }
247
+ /** Title that identifies this resource within a project. */
183
248
  get title() {
184
249
  return this._title;
185
250
  }
251
+ /** Sets the title that identifies this resource within a project. */
186
252
  set title(title) {
187
253
  this._title = title;
188
254
  }
255
+ /**
256
+ * Returns the project this resource belongs to.
257
+ */
189
258
  getProject() {
190
259
  return this._project;
191
260
  }
261
+ /**
262
+ * Adds a message to this resource, merging resource attributes with any overrides.
263
+ *
264
+ * @returns This resource, for chaining.
265
+ */
192
266
  add(key, value, attributes, notes) {
193
267
  const merged = { ...this.attributes, ...attributes };
194
268
  const msg = MsgMessage.create({
@@ -200,6 +274,14 @@ var MsgResource = class _MsgResource extends Map {
200
274
  this.set(key, msg);
201
275
  return this;
202
276
  }
277
+ /**
278
+ * Builds a translated copy of this resource from translation data.
279
+ *
280
+ * Messages present in the translation replace the source; missing keys keep
281
+ * the source message. Notes are carried over from the source.
282
+ *
283
+ * @throws {TypeError} When the translation title does not match this resource.
284
+ */
203
285
  translate(data) {
204
286
  const { title, attributes, messages } = data;
205
287
  if (title !== this.title) {
@@ -237,7 +319,18 @@ var MsgResource = class _MsgResource extends Map {
237
319
  }
238
320
  return { ...attributes, format };
239
321
  }
322
+ /**
323
+ * Loads and applies translations for a locale via the project loader.
324
+ *
325
+ * When `lang` is the project's pseudo-locale, returns a pseudo-localized
326
+ * copy without calling the loader.
327
+ *
328
+ * @throws {Error} When the locale is unsupported or its language chain is empty.
329
+ */
240
330
  async getTranslation(lang) {
331
+ if (!lang) {
332
+ return _MsgResource.create(this.getData(), this.getProject());
333
+ }
241
334
  const project = this._project;
242
335
  const pseudoLocale = project.locales.pseudoLocale;
243
336
  if (lang === pseudoLocale) {
@@ -272,6 +365,14 @@ var MsgResource = class _MsgResource extends Map {
272
365
  }
273
366
  return translated;
274
367
  }
368
+ /**
369
+ * Returns a plain data object for this resource and its messages.
370
+ *
371
+ * Attributes that match the resource or project defaults are omitted where
372
+ * possible to keep the output compact.
373
+ *
374
+ * @param stripNotes - When true, notes are omitted from the result.
375
+ */
275
376
  getData(stripNotes = false) {
276
377
  const resourceFormat = this.resolveFormat(this.attributes);
277
378
  const projectFormat = this._project.format;
@@ -304,6 +405,11 @@ var MsgResource = class _MsgResource extends Map {
304
405
  messages
305
406
  };
306
407
  }
408
+ /**
409
+ * Serializes this resource to a formatted JSON string.
410
+ *
411
+ * @param stripNotes - When true, notes are omitted from the serialized data.
412
+ */
307
413
  toJSON(stripNotes = false) {
308
414
  return JSON.stringify(this.getData(stripNotes), null, 2);
309
415
  }
@@ -323,24 +429,36 @@ var defaultLocalesSettings = {
323
429
  }
324
430
  };
325
431
  var MsgProject = class _MsgProject {
432
+ /** Project name, version, and default format. */
326
433
  _project;
434
+ /** Source, pseudo, and target locale settings. */
327
435
  _locales;
436
+ /** Function used to load translations for a locale. */
328
437
  _loader;
438
+ /**
439
+ * Builds a project from {@link MsgProjectData}.
440
+ */
329
441
  static create(data) {
330
442
  const { project, locales, loader } = data;
331
443
  return new _MsgProject(project, locales, loader);
332
444
  }
445
+ /**
446
+ * Creates a project from its settings and loader. Prefer {@link MsgProject.create}.
447
+ */
333
448
  constructor(projectSettings, localesSettings, loader) {
334
449
  this._project = { ...defaultProjectSettings, ...projectSettings };
335
450
  this._locales = { ...defaultLocalesSettings, ...localesSettings };
336
451
  this._loader = loader;
337
452
  }
453
+ /** Project name, version, and default format. */
338
454
  get project() {
339
455
  return this._project;
340
456
  }
457
+ /** Source, pseudo, and target locale settings. */
341
458
  get locales() {
342
459
  return this._locales;
343
460
  }
461
+ /** Function used to load translations for a locale. */
344
462
  get loader() {
345
463
  return this._loader;
346
464
  }
@@ -351,6 +469,9 @@ var MsgProject = class _MsgProject {
351
469
  get format() {
352
470
  return this._project.format ?? MSG_DEFAULT_FORMAT;
353
471
  }
472
+ /**
473
+ * Returns the translation load chain for a locale, or `undefined` if unsupported.
474
+ */
354
475
  getTargetLocale(locale) {
355
476
  return this._locales.targetLocales[locale];
356
477
  }
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote } from './classes/MsgInterface/MsgInterface.cjs';
1
+ export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote, NoteTypes } from './classes/MsgInterface/MsgInterface.cjs';
2
2
  export { MsgMessage, MsgMessageData } from './classes/MsgMessage/MsgMessage.cjs';
3
- export { M as MsgProject, a as MsgProjectData, MsgResource, MsgResourceData, b as MsgTranslationLoader } from './classes/MsgResource/MsgResource.cjs';
3
+ export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, MsgResource, MsgResourceData, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from './classes/MsgResource/MsgResource.cjs';
4
4
  import 'messageformat';
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote } from './classes/MsgInterface/MsgInterface.js';
1
+ export { DEFAULT_ATTRIBUTES, MSG_DEFAULT_FORMAT, MsgAttributes, MsgFormat, MsgInterface, MsgNote, NoteTypes } from './classes/MsgInterface/MsgInterface.js';
2
2
  export { MsgMessage, MsgMessageData } from './classes/MsgMessage/MsgMessage.js';
3
- export { M as MsgProject, a as MsgProjectData, MsgResource, MsgResourceData, b as MsgTranslationLoader } from './classes/MsgResource/MsgResource.js';
3
+ export { M as MsgLocalesSettings, a as MsgProject, b as MsgProjectData, c as MsgProjectSettings, MsgResource, MsgResourceData, d as MsgTargetLocalesSettings, e as MsgTranslationLoader } from './classes/MsgResource/MsgResource.js';
4
4
  import 'messageformat';
package/dist/index.mjs CHANGED
@@ -1,13 +1,13 @@
1
1
  import "./chunk-ORHP7HGX.mjs";
2
+ import {
3
+ MsgProject
4
+ } from "./chunk-DJFPVXQ5.mjs";
2
5
  import {
3
6
  MsgResource
4
- } from "./chunk-X6CRKSNU.mjs";
7
+ } from "./chunk-IMOOTZIK.mjs";
5
8
  import {
6
9
  MsgMessage
7
- } from "./chunk-HCR2UNSE.mjs";
8
- import {
9
- MsgProject
10
- } from "./chunk-NWJ7MVVV.mjs";
10
+ } from "./chunk-F3VAAZJZ.mjs";
11
11
  import {
12
12
  DEFAULT_ATTRIBUTES,
13
13
  MSG_DEFAULT_FORMAT
@@ -0,0 +1,40 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/lib/index.ts
21
+ var lib_exports = {};
22
+ __export(lib_exports, {
23
+ getLang: () => getLang,
24
+ setLang: () => setLang
25
+ });
26
+ module.exports = __toCommonJS(lib_exports);
27
+
28
+ // src/lib/lang-utils.ts
29
+ var lang;
30
+ function setLang(tag) {
31
+ lang = tag;
32
+ }
33
+ function getLang() {
34
+ return lang;
35
+ }
36
+ // Annotate the CommonJS export names for ESM import in node:
37
+ 0 && (module.exports = {
38
+ getLang,
39
+ setLang
40
+ });
@@ -0,0 +1 @@
1
+ export { getLang, setLang } from './lang-utils.cjs';
@@ -0,0 +1 @@
1
+ export { getLang, setLang } from './lang-utils.js';
@@ -0,0 +1,8 @@
1
+ import {
2
+ getLang,
3
+ setLang
4
+ } from "../chunk-PU7ZZ5XH.mjs";
5
+ export {
6
+ getLang,
7
+ setLang
8
+ };
@@ -0,0 +1,38 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/lib/lang-utils.ts
21
+ var lang_utils_exports = {};
22
+ __export(lang_utils_exports, {
23
+ getLang: () => getLang,
24
+ setLang: () => setLang
25
+ });
26
+ module.exports = __toCommonJS(lang_utils_exports);
27
+ var lang;
28
+ function setLang(tag) {
29
+ lang = tag;
30
+ }
31
+ function getLang() {
32
+ return lang;
33
+ }
34
+ // Annotate the CommonJS export names for ESM import in node:
35
+ 0 && (module.exports = {
36
+ getLang,
37
+ setLang
38
+ });
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Set value of lang
3
+ *
4
+ * @param tag string
5
+ */
6
+ declare function setLang(tag: string): void;
7
+ /**
8
+ * Returns value of lang;
9
+ *
10
+ * @returns string | undefined
11
+ */
12
+ declare function getLang(): string | undefined;
13
+
14
+ export { getLang, setLang };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Set value of lang
3
+ *
4
+ * @param tag string
5
+ */
6
+ declare function setLang(tag: string): void;
7
+ /**
8
+ * Returns value of lang;
9
+ *
10
+ * @returns string | undefined
11
+ */
12
+ declare function getLang(): string | undefined;
13
+
14
+ export { getLang, setLang };
@@ -0,0 +1,8 @@
1
+ import {
2
+ getLang,
3
+ setLang
4
+ } from "../chunk-PU7ZZ5XH.mjs";
5
+ export {
6
+ getLang,
7
+ setLang
8
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@worldware/msg",
3
- "version": "0.8.1",
3
+ "version": "0.9.0",
4
4
  "description": "Message localization tooling",
5
5
  "license": "MIT",
6
6
  "author": "Joel Sahleen",