@worldware/msg 0.12.0 → 0.13.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.
- package/README.md +45 -10
- package/dist/{chunk-CRT2A2HP.mjs → chunk-HQMBNFN5.mjs} +137 -16
- package/dist/classes/MsgMessage/MsgMessage.d.cts +5 -2
- package/dist/classes/MsgMessage/MsgMessage.d.ts +5 -2
- package/dist/classes/MsgResource/MsgResource.cjs +137 -16
- package/dist/classes/MsgResource/MsgResource.d.cts +1 -1
- package/dist/classes/MsgResource/MsgResource.d.ts +1 -1
- package/dist/classes/MsgResource/MsgResource.mjs +1 -1
- package/dist/classes/index.cjs +137 -16
- package/dist/classes/index.d.cts +125 -10
- package/dist/classes/index.d.ts +125 -10
- package/dist/classes/index.mjs +1 -1
- package/dist/index.cjs +137 -16
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.mjs +1 -1
- package/package.json +1 -1
package/dist/classes/index.cjs
CHANGED
|
@@ -255,16 +255,52 @@ function pseudoLocalize(source, format, options) {
|
|
|
255
255
|
}
|
|
256
256
|
|
|
257
257
|
// src/classes/MsgResource/MsgResource.ts
|
|
258
|
+
function branchPrefixes(key) {
|
|
259
|
+
const prefixes = [];
|
|
260
|
+
for (let i = key.indexOf("."); i !== -1; i = key.indexOf(".", i + 1)) {
|
|
261
|
+
prefixes.push(key.slice(0, i));
|
|
262
|
+
}
|
|
263
|
+
return prefixes;
|
|
264
|
+
}
|
|
258
265
|
var MsgResource = class _MsgResource extends Map {
|
|
259
266
|
_attributes = {};
|
|
260
267
|
_notes = [];
|
|
261
268
|
_title;
|
|
262
269
|
_project;
|
|
270
|
+
/**
|
|
271
|
+
* For every key prefix that is a branch in the tree (`a` and `a.b` for key
|
|
272
|
+
* `a.b.c`), how many stored keys pass through it. Keeps collision checks
|
|
273
|
+
* proportional to key depth instead of resource size.
|
|
274
|
+
*/
|
|
275
|
+
_branches = /* @__PURE__ */ new Map();
|
|
263
276
|
/**
|
|
264
277
|
* Builds a resource from {@link MsgResourceData} and an owning project.
|
|
265
278
|
*
|
|
266
279
|
* When `messages` is provided, each entry is added to the resource.
|
|
267
280
|
* When omitted, the resource starts empty.
|
|
281
|
+
*
|
|
282
|
+
* **Typed keys are opt-in with `as const`.** When `messages` (or the whole
|
|
283
|
+
* definition) is `as const`, the resource's key type is the union of its
|
|
284
|
+
* message keys, so `get()`, `has()` and `toTree()` reject unknown keys.
|
|
285
|
+
* Without `as const` the key type is `string`, exactly as before, so a
|
|
286
|
+
* resource can keep growing through `add()`.
|
|
287
|
+
*
|
|
288
|
+
* ```ts
|
|
289
|
+
* const typed = MsgResource.create({
|
|
290
|
+
* title: 'Home',
|
|
291
|
+
* attributes: { lang: 'en' },
|
|
292
|
+
* messages: [{ key: 'home.title', value: 'Welcome' }] as const
|
|
293
|
+
* }, project);
|
|
294
|
+
* typed.get('home.titel'); // compile error
|
|
295
|
+
* ```
|
|
296
|
+
*
|
|
297
|
+
* `as const` data is a tuple, so inference also scales to large resources:
|
|
298
|
+
* up to TypeScript's ~10,000-element tuple limit.
|
|
299
|
+
*
|
|
300
|
+
* @typeParam M - The message list; its `key` types become the resource's
|
|
301
|
+
* key type.
|
|
302
|
+
* @throws {TypeError} When one key is a dot-separated prefix of another
|
|
303
|
+
* (for example `a` and `a.b`).
|
|
268
304
|
*/
|
|
269
305
|
static create(data, project) {
|
|
270
306
|
const { title, attributes, notes, messages } = data;
|
|
@@ -272,7 +308,7 @@ var MsgResource = class _MsgResource extends Map {
|
|
|
272
308
|
if (messages) {
|
|
273
309
|
messages.forEach((messageData) => {
|
|
274
310
|
const { key, value, attributes: attributes2, notes: notes2 } = messageData;
|
|
275
|
-
res.add(key, value, attributes2, notes2);
|
|
311
|
+
res.add(key, value, attributes2, notes2 && [...notes2]);
|
|
276
312
|
});
|
|
277
313
|
} else {
|
|
278
314
|
res.clear();
|
|
@@ -358,7 +394,11 @@ var MsgResource = class _MsgResource extends Map {
|
|
|
358
394
|
* Unspecified `lang`, `dir`, and `dnt` inherit from this resource; explicit
|
|
359
395
|
* values on the message win.
|
|
360
396
|
*
|
|
397
|
+
* Accepts any string key and does not change the resource's key type.
|
|
398
|
+
*
|
|
361
399
|
* @returns This resource, for chaining.
|
|
400
|
+
* @throws {TypeError} When `key` and an existing key are dot-separated
|
|
401
|
+
* prefixes of one another (for example `a` and `a.b`).
|
|
362
402
|
*/
|
|
363
403
|
add(key, value, attributes, notes) {
|
|
364
404
|
const merged = { ...this.attributes, ...attributes };
|
|
@@ -371,12 +411,89 @@ var MsgResource = class _MsgResource extends Map {
|
|
|
371
411
|
this.set(key, msg);
|
|
372
412
|
return this;
|
|
373
413
|
}
|
|
414
|
+
/**
|
|
415
|
+
* Stores a message under `key`.
|
|
416
|
+
*
|
|
417
|
+
* @throws {TypeError} When `key` and an existing key are dot-separated
|
|
418
|
+
* prefixes of one another (for example `a` and `a.b`), since a tree node
|
|
419
|
+
* cannot be both a message and a branch.
|
|
420
|
+
*/
|
|
421
|
+
set(key, value) {
|
|
422
|
+
if (!this.has(key)) {
|
|
423
|
+
this.assertNoCollision(key);
|
|
424
|
+
this.updateBranches(key, 1);
|
|
425
|
+
}
|
|
426
|
+
return super.set(key, value);
|
|
427
|
+
}
|
|
428
|
+
/** Removes the message stored under `key`. */
|
|
429
|
+
delete(key) {
|
|
430
|
+
const deleted = super.delete(key);
|
|
431
|
+
if (deleted) {
|
|
432
|
+
this.updateBranches(key, -1);
|
|
433
|
+
}
|
|
434
|
+
return deleted;
|
|
435
|
+
}
|
|
436
|
+
/** Removes every message from this resource. */
|
|
437
|
+
clear() {
|
|
438
|
+
super.clear();
|
|
439
|
+
this._branches.clear();
|
|
440
|
+
}
|
|
441
|
+
/**
|
|
442
|
+
* Throws when `key` would be both a message and a branch in the tree.
|
|
443
|
+
*/
|
|
444
|
+
assertNoCollision(key) {
|
|
445
|
+
if (this._branches.has(key)) {
|
|
446
|
+
const descendant = [...this.keys()].find((existing) => existing.startsWith(`${key}.`));
|
|
447
|
+
throw new TypeError(`Message key "${key}" collides with "${descendant}": a key cannot also be a prefix of another key.`);
|
|
448
|
+
}
|
|
449
|
+
const leaf = branchPrefixes(key).find((prefix) => this.has(prefix));
|
|
450
|
+
if (leaf !== void 0) {
|
|
451
|
+
throw new TypeError(`Message key "${key}" collides with "${leaf}": a key cannot also be a prefix of another key.`);
|
|
452
|
+
}
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* Adds `delta` to the count of every branch `key` passes through,
|
|
456
|
+
* dropping branches that no key uses any more.
|
|
457
|
+
*/
|
|
458
|
+
updateBranches(key, delta) {
|
|
459
|
+
for (const prefix of branchPrefixes(key)) {
|
|
460
|
+
const count = (this._branches.get(prefix) ?? 0) + delta;
|
|
461
|
+
if (count > 0) {
|
|
462
|
+
this._branches.set(prefix, count);
|
|
463
|
+
} else {
|
|
464
|
+
this._branches.delete(prefix);
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
}
|
|
468
|
+
/**
|
|
469
|
+
* Returns a nested, read-only view of this resource's messages, splitting
|
|
470
|
+
* keys on `.`: `resource.toTree().home.cta.label` is the message stored
|
|
471
|
+
* under `'home.cta.label'`.
|
|
472
|
+
*
|
|
473
|
+
* The key type comes from `this` rather than the class parameter so that a
|
|
474
|
+
* typed resource stays assignable to a plain `MsgResource`.
|
|
475
|
+
*/
|
|
476
|
+
toTree() {
|
|
477
|
+
const root = /* @__PURE__ */ Object.create(null);
|
|
478
|
+
for (const [key, msg] of this) {
|
|
479
|
+
const segments = key.split(".");
|
|
480
|
+
const leaf = segments.pop();
|
|
481
|
+
let node = root;
|
|
482
|
+
for (const segment of segments) {
|
|
483
|
+
node = node[segment] ??= /* @__PURE__ */ Object.create(null);
|
|
484
|
+
}
|
|
485
|
+
node[leaf] = msg;
|
|
486
|
+
}
|
|
487
|
+
return root;
|
|
488
|
+
}
|
|
374
489
|
/**
|
|
375
490
|
* Builds a translated copy of this resource from translation data.
|
|
376
491
|
*
|
|
377
492
|
* Messages present in the translation replace the source; missing keys keep
|
|
378
|
-
* the source message.
|
|
379
|
-
*
|
|
493
|
+
* the source message. Keys that are not in this resource are ignored, so the
|
|
494
|
+
* translated resource has the same keys (and key type) as the source. Notes
|
|
495
|
+
* are carried over from the source. Unspecified message `lang`, `dir`, and
|
|
496
|
+
* `dnt` inherit from the translated resource.
|
|
380
497
|
*
|
|
381
498
|
* @throws {TypeError} When the translation title does not match this resource.
|
|
382
499
|
*/
|
|
@@ -385,24 +502,28 @@ var MsgResource = class _MsgResource extends Map {
|
|
|
385
502
|
if (title !== this.title) {
|
|
386
503
|
throw new TypeError("Title of resource and translations do not match.");
|
|
387
504
|
}
|
|
388
|
-
const translated = _MsgResource
|
|
505
|
+
const translated = new _MsgResource(
|
|
389
506
|
title,
|
|
390
507
|
// preserve the source resource's format unless the translation overrides it
|
|
391
|
-
|
|
392
|
-
|
|
508
|
+
this.preserveFormat(attributes, this.attributes.format),
|
|
509
|
+
this._project,
|
|
510
|
+
this.notes
|
|
393
511
|
// transfer the notes
|
|
394
|
-
|
|
395
|
-
this.forEach((msg) => {
|
|
396
|
-
translated.set(
|
|
512
|
+
);
|
|
513
|
+
this.forEach((msg, key) => {
|
|
514
|
+
translated.set(key, msg);
|
|
397
515
|
});
|
|
398
516
|
messages?.forEach((messageData) => {
|
|
399
517
|
const { key, value, attributes: attributes2 } = messageData;
|
|
400
518
|
const source = this.get(key);
|
|
519
|
+
if (!source) {
|
|
520
|
+
return;
|
|
521
|
+
}
|
|
401
522
|
translated.add(
|
|
402
523
|
key,
|
|
403
524
|
value,
|
|
404
|
-
this.preserveFormat(attributes2, source
|
|
405
|
-
source
|
|
525
|
+
this.preserveFormat(attributes2, source.attributes.format),
|
|
526
|
+
source.notes
|
|
406
527
|
);
|
|
407
528
|
});
|
|
408
529
|
return translated;
|
|
@@ -432,8 +553,8 @@ var MsgResource = class _MsgResource extends Map {
|
|
|
432
553
|
const project = this._project;
|
|
433
554
|
const pseudoLocale = project.locales.pseudoLocale;
|
|
434
555
|
if (lang === pseudoLocale) {
|
|
435
|
-
const messages = [...this.
|
|
436
|
-
key
|
|
556
|
+
const messages = [...this.entries()].map(([key, msg]) => ({
|
|
557
|
+
key,
|
|
437
558
|
value: pseudoLocalize(msg.value, this.resolveFormat(msg.attributes)),
|
|
438
559
|
attributes: { ...msg.attributes, lang: pseudoLocale }
|
|
439
560
|
}));
|
|
@@ -473,16 +594,16 @@ var MsgResource = class _MsgResource extends Map {
|
|
|
473
594
|
const resourceFormat = this.resolveFormat(this.attributes);
|
|
474
595
|
const projectFormat = this._project.format;
|
|
475
596
|
const messages = [];
|
|
476
|
-
this.forEach((msg) => {
|
|
597
|
+
this.forEach((msg, key) => {
|
|
477
598
|
if (this.hasMatchingAttributes(msg)) {
|
|
478
599
|
const data = {
|
|
479
|
-
key
|
|
600
|
+
key,
|
|
480
601
|
value: msg.value,
|
|
481
602
|
notes: !stripNotes && msg.notes.length > 0 ? msg.notes : void 0
|
|
482
603
|
};
|
|
483
604
|
messages.push(data);
|
|
484
605
|
} else {
|
|
485
|
-
const data = msg.getData(stripNotes);
|
|
606
|
+
const data = { ...msg.getData(stripNotes), key };
|
|
486
607
|
if (data.attributes && this.resolveFormat(data.attributes) === resourceFormat) {
|
|
487
608
|
const { format, ...rest } = data.attributes;
|
|
488
609
|
data.attributes = rest;
|
package/dist/classes/index.d.cts
CHANGED
|
@@ -5,8 +5,10 @@ import 'messageformat';
|
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Plain data used to create or describe a {@link MsgResource}.
|
|
8
|
+
*
|
|
9
|
+
* @typeParam K - Union of message keys. Defaults to `string`.
|
|
8
10
|
*/
|
|
9
|
-
type MsgResourceData = {
|
|
11
|
+
type MsgResourceData<K extends string = string> = {
|
|
10
12
|
/** Title that identifies this resource within a project. */
|
|
11
13
|
title: string;
|
|
12
14
|
/** Locale and formatting metadata for the resource. */
|
|
@@ -14,26 +16,103 @@ type MsgResourceData = {
|
|
|
14
16
|
/** Optional notes for translators and tooling. */
|
|
15
17
|
notes?: MsgNote[];
|
|
16
18
|
/** Optional list of messages in this resource. */
|
|
17
|
-
messages?: MsgMessageData[];
|
|
19
|
+
messages?: MsgMessageData<K>[];
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* The tree shape of an untyped resource (`MsgResource<string>`): every node is
|
|
23
|
+
* either a message or another branch.
|
|
24
|
+
*/
|
|
25
|
+
type MsgTreeNode = {
|
|
26
|
+
readonly [segment: string]: MsgMessage | MsgTreeNode;
|
|
27
|
+
};
|
|
28
|
+
/** First dot-separated segment of a key: `'home.cta.label'` → `'home'`. */
|
|
29
|
+
type MsgKeyHead<K extends string> = K extends `${infer H}.${string}` ? H : K;
|
|
30
|
+
/** Remainder of a key after the segment `H`: `('home.cta.label', 'home')` → `'cta.label'`. */
|
|
31
|
+
type MsgKeyRest<K extends string, H extends string> = K extends `${H}.${infer R}` ? R : never;
|
|
32
|
+
/**
|
|
33
|
+
* Nested view of a resource's dot-separated message keys.
|
|
34
|
+
*
|
|
35
|
+
* For keys `'home.title' | 'home.cta.label' | 'footer'` this is
|
|
36
|
+
* `{ home: { title: MsgMessage; cta: { label: MsgMessage } }; footer: MsgMessage }`.
|
|
37
|
+
* When `K` is `string`, it is {@link MsgTreeNode}, so typed trees stay
|
|
38
|
+
* assignable to untyped ones.
|
|
39
|
+
*
|
|
40
|
+
* @typeParam K - Union of message keys.
|
|
41
|
+
*/
|
|
42
|
+
type MsgTree<K extends string> = string extends K ? MsgTreeNode : {
|
|
43
|
+
readonly [H in MsgKeyHead<K>]: H extends K ? MsgMessage : MsgTree<MsgKeyRest<K, H>>;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* A message as {@link MsgResource.create} accepts it: {@link MsgMessageData}
|
|
47
|
+
* with readonly properties, so `as const` data is accepted.
|
|
48
|
+
*/
|
|
49
|
+
type MsgMessageInput = {
|
|
50
|
+
readonly key: string;
|
|
51
|
+
readonly value: string;
|
|
52
|
+
readonly attributes?: Readonly<MsgAttributes>;
|
|
53
|
+
readonly notes?: readonly Readonly<MsgNote>[];
|
|
18
54
|
};
|
|
55
|
+
/**
|
|
56
|
+
* Key union of the messages passed to {@link MsgResource.create}. Keys are
|
|
57
|
+
* literal types only for `as const` data; an empty list yields `string` so
|
|
58
|
+
* the resource stays usable.
|
|
59
|
+
*/
|
|
60
|
+
type MsgMessageKeys<M extends readonly MsgMessageInput[]> = M extends readonly [] ? string : M[number]['key'];
|
|
19
61
|
/**
|
|
20
62
|
* A named collection of messages belonging to a {@link MsgProject}.
|
|
21
63
|
*
|
|
22
64
|
* Resources inherit format defaults from their project, support translation
|
|
23
65
|
* loading (including pseudo-localization), and can serialize to plain data.
|
|
66
|
+
*
|
|
67
|
+
* @typeParam K - Union of message keys. Inferred by {@link MsgResource.create}
|
|
68
|
+
* when its messages are `as const`; otherwise `string`.
|
|
24
69
|
*/
|
|
25
|
-
declare class MsgResource extends Map<
|
|
70
|
+
declare class MsgResource<K extends string = string> extends Map<K, MsgMessage> implements MsgInterface {
|
|
26
71
|
private _attributes;
|
|
27
72
|
private _notes;
|
|
28
73
|
private _title;
|
|
29
74
|
private _project;
|
|
75
|
+
/**
|
|
76
|
+
* For every key prefix that is a branch in the tree (`a` and `a.b` for key
|
|
77
|
+
* `a.b.c`), how many stored keys pass through it. Keeps collision checks
|
|
78
|
+
* proportional to key depth instead of resource size.
|
|
79
|
+
*/
|
|
80
|
+
private _branches;
|
|
30
81
|
/**
|
|
31
82
|
* Builds a resource from {@link MsgResourceData} and an owning project.
|
|
32
83
|
*
|
|
33
84
|
* When `messages` is provided, each entry is added to the resource.
|
|
34
85
|
* When omitted, the resource starts empty.
|
|
86
|
+
*
|
|
87
|
+
* **Typed keys are opt-in with `as const`.** When `messages` (or the whole
|
|
88
|
+
* definition) is `as const`, the resource's key type is the union of its
|
|
89
|
+
* message keys, so `get()`, `has()` and `toTree()` reject unknown keys.
|
|
90
|
+
* Without `as const` the key type is `string`, exactly as before, so a
|
|
91
|
+
* resource can keep growing through `add()`.
|
|
92
|
+
*
|
|
93
|
+
* ```ts
|
|
94
|
+
* const typed = MsgResource.create({
|
|
95
|
+
* title: 'Home',
|
|
96
|
+
* attributes: { lang: 'en' },
|
|
97
|
+
* messages: [{ key: 'home.title', value: 'Welcome' }] as const
|
|
98
|
+
* }, project);
|
|
99
|
+
* typed.get('home.titel'); // compile error
|
|
100
|
+
* ```
|
|
101
|
+
*
|
|
102
|
+
* `as const` data is a tuple, so inference also scales to large resources:
|
|
103
|
+
* up to TypeScript's ~10,000-element tuple limit.
|
|
104
|
+
*
|
|
105
|
+
* @typeParam M - The message list; its `key` types become the resource's
|
|
106
|
+
* key type.
|
|
107
|
+
* @throws {TypeError} When one key is a dot-separated prefix of another
|
|
108
|
+
* (for example `a` and `a.b`).
|
|
35
109
|
*/
|
|
36
|
-
static create
|
|
110
|
+
static create<M extends readonly MsgMessageInput[] = MsgMessageData[]>(data: {
|
|
111
|
+
readonly title: string;
|
|
112
|
+
readonly attributes: Readonly<MsgAttributes>;
|
|
113
|
+
readonly notes?: readonly Readonly<MsgNote>[];
|
|
114
|
+
readonly messages?: M;
|
|
115
|
+
}, project: MsgProject): MsgResource<MsgMessageKeys<M>>;
|
|
37
116
|
/**
|
|
38
117
|
* Creates a resource bound to a project. Prefer {@link MsgResource.create}.
|
|
39
118
|
*/
|
|
@@ -80,19 +159,55 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
|
|
|
80
159
|
* Unspecified `lang`, `dir`, and `dnt` inherit from this resource; explicit
|
|
81
160
|
* values on the message win.
|
|
82
161
|
*
|
|
162
|
+
* Accepts any string key and does not change the resource's key type.
|
|
163
|
+
*
|
|
83
164
|
* @returns This resource, for chaining.
|
|
165
|
+
* @throws {TypeError} When `key` and an existing key are dot-separated
|
|
166
|
+
* prefixes of one another (for example `a` and `a.b`).
|
|
84
167
|
*/
|
|
85
168
|
add(key: string, value: string, attributes?: MsgAttributes, notes?: MsgNote[]): this;
|
|
169
|
+
/**
|
|
170
|
+
* Stores a message under `key`.
|
|
171
|
+
*
|
|
172
|
+
* @throws {TypeError} When `key` and an existing key are dot-separated
|
|
173
|
+
* prefixes of one another (for example `a` and `a.b`), since a tree node
|
|
174
|
+
* cannot be both a message and a branch.
|
|
175
|
+
*/
|
|
176
|
+
set(key: K, value: MsgMessage): this;
|
|
177
|
+
/** Removes the message stored under `key`. */
|
|
178
|
+
delete(key: K): boolean;
|
|
179
|
+
/** Removes every message from this resource. */
|
|
180
|
+
clear(): void;
|
|
181
|
+
/**
|
|
182
|
+
* Throws when `key` would be both a message and a branch in the tree.
|
|
183
|
+
*/
|
|
184
|
+
private assertNoCollision;
|
|
185
|
+
/**
|
|
186
|
+
* Adds `delta` to the count of every branch `key` passes through,
|
|
187
|
+
* dropping branches that no key uses any more.
|
|
188
|
+
*/
|
|
189
|
+
private updateBranches;
|
|
190
|
+
/**
|
|
191
|
+
* Returns a nested, read-only view of this resource's messages, splitting
|
|
192
|
+
* keys on `.`: `resource.toTree().home.cta.label` is the message stored
|
|
193
|
+
* under `'home.cta.label'`.
|
|
194
|
+
*
|
|
195
|
+
* The key type comes from `this` rather than the class parameter so that a
|
|
196
|
+
* typed resource stays assignable to a plain `MsgResource`.
|
|
197
|
+
*/
|
|
198
|
+
toTree<T extends string>(this: MsgResource<T>): MsgTree<T>;
|
|
86
199
|
/**
|
|
87
200
|
* Builds a translated copy of this resource from translation data.
|
|
88
201
|
*
|
|
89
202
|
* Messages present in the translation replace the source; missing keys keep
|
|
90
|
-
* the source message.
|
|
91
|
-
*
|
|
203
|
+
* the source message. Keys that are not in this resource are ignored, so the
|
|
204
|
+
* translated resource has the same keys (and key type) as the source. Notes
|
|
205
|
+
* are carried over from the source. Unspecified message `lang`, `dir`, and
|
|
206
|
+
* `dnt` inherit from the translated resource.
|
|
92
207
|
*
|
|
93
208
|
* @throws {TypeError} When the translation title does not match this resource.
|
|
94
209
|
*/
|
|
95
|
-
translate(data: MsgResourceData): MsgResource
|
|
210
|
+
translate(data: MsgResourceData): MsgResource<K>;
|
|
96
211
|
/**
|
|
97
212
|
* Merge a `format` into an attribute set unless one is already present,
|
|
98
213
|
* so translations inherit the source's format without overriding an
|
|
@@ -112,7 +227,7 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
|
|
|
112
227
|
*
|
|
113
228
|
* @throws {Error} When the locale is unsupported or its language chain is empty.
|
|
114
229
|
*/
|
|
115
|
-
getTranslation(lang?: string): Promise<MsgResource
|
|
230
|
+
getTranslation(lang?: string): Promise<MsgResource<K>>;
|
|
116
231
|
/**
|
|
117
232
|
* Returns a plain data object for this resource and its messages.
|
|
118
233
|
*
|
|
@@ -121,7 +236,7 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
|
|
|
121
236
|
*
|
|
122
237
|
* @param stripNotes - When true, notes are omitted from the result.
|
|
123
238
|
*/
|
|
124
|
-
getData(stripNotes?: boolean): MsgResourceData
|
|
239
|
+
getData(stripNotes?: boolean): MsgResourceData<K>;
|
|
125
240
|
/**
|
|
126
241
|
* Serializes this resource to a formatted JSON string.
|
|
127
242
|
*
|
|
@@ -211,4 +326,4 @@ declare class MsgProject {
|
|
|
211
326
|
getTargetLocale(locale: string): string[] | undefined;
|
|
212
327
|
}
|
|
213
328
|
|
|
214
|
-
export { MsgAttributes, MsgFormat, MsgInterface, type MsgLocalesSettings, MsgMessage, MsgMessageData, MsgNote, MsgProject, type MsgProjectData, type MsgProjectSettings, MsgResource, type MsgResourceData, type MsgTargetLocalesSettings, type MsgTranslationLoader, NoteTypes };
|
|
329
|
+
export { MsgAttributes, MsgFormat, MsgInterface, type MsgLocalesSettings, MsgMessage, MsgMessageData, MsgNote, MsgProject, type MsgProjectData, type MsgProjectSettings, MsgResource, type MsgResourceData, type MsgTargetLocalesSettings, type MsgTranslationLoader, type MsgTree, type MsgTreeNode, NoteTypes };
|
package/dist/classes/index.d.ts
CHANGED
|
@@ -5,8 +5,10 @@ import 'messageformat';
|
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Plain data used to create or describe a {@link MsgResource}.
|
|
8
|
+
*
|
|
9
|
+
* @typeParam K - Union of message keys. Defaults to `string`.
|
|
8
10
|
*/
|
|
9
|
-
type MsgResourceData = {
|
|
11
|
+
type MsgResourceData<K extends string = string> = {
|
|
10
12
|
/** Title that identifies this resource within a project. */
|
|
11
13
|
title: string;
|
|
12
14
|
/** Locale and formatting metadata for the resource. */
|
|
@@ -14,26 +16,103 @@ type MsgResourceData = {
|
|
|
14
16
|
/** Optional notes for translators and tooling. */
|
|
15
17
|
notes?: MsgNote[];
|
|
16
18
|
/** Optional list of messages in this resource. */
|
|
17
|
-
messages?: MsgMessageData[];
|
|
19
|
+
messages?: MsgMessageData<K>[];
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* The tree shape of an untyped resource (`MsgResource<string>`): every node is
|
|
23
|
+
* either a message or another branch.
|
|
24
|
+
*/
|
|
25
|
+
type MsgTreeNode = {
|
|
26
|
+
readonly [segment: string]: MsgMessage | MsgTreeNode;
|
|
27
|
+
};
|
|
28
|
+
/** First dot-separated segment of a key: `'home.cta.label'` → `'home'`. */
|
|
29
|
+
type MsgKeyHead<K extends string> = K extends `${infer H}.${string}` ? H : K;
|
|
30
|
+
/** Remainder of a key after the segment `H`: `('home.cta.label', 'home')` → `'cta.label'`. */
|
|
31
|
+
type MsgKeyRest<K extends string, H extends string> = K extends `${H}.${infer R}` ? R : never;
|
|
32
|
+
/**
|
|
33
|
+
* Nested view of a resource's dot-separated message keys.
|
|
34
|
+
*
|
|
35
|
+
* For keys `'home.title' | 'home.cta.label' | 'footer'` this is
|
|
36
|
+
* `{ home: { title: MsgMessage; cta: { label: MsgMessage } }; footer: MsgMessage }`.
|
|
37
|
+
* When `K` is `string`, it is {@link MsgTreeNode}, so typed trees stay
|
|
38
|
+
* assignable to untyped ones.
|
|
39
|
+
*
|
|
40
|
+
* @typeParam K - Union of message keys.
|
|
41
|
+
*/
|
|
42
|
+
type MsgTree<K extends string> = string extends K ? MsgTreeNode : {
|
|
43
|
+
readonly [H in MsgKeyHead<K>]: H extends K ? MsgMessage : MsgTree<MsgKeyRest<K, H>>;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* A message as {@link MsgResource.create} accepts it: {@link MsgMessageData}
|
|
47
|
+
* with readonly properties, so `as const` data is accepted.
|
|
48
|
+
*/
|
|
49
|
+
type MsgMessageInput = {
|
|
50
|
+
readonly key: string;
|
|
51
|
+
readonly value: string;
|
|
52
|
+
readonly attributes?: Readonly<MsgAttributes>;
|
|
53
|
+
readonly notes?: readonly Readonly<MsgNote>[];
|
|
18
54
|
};
|
|
55
|
+
/**
|
|
56
|
+
* Key union of the messages passed to {@link MsgResource.create}. Keys are
|
|
57
|
+
* literal types only for `as const` data; an empty list yields `string` so
|
|
58
|
+
* the resource stays usable.
|
|
59
|
+
*/
|
|
60
|
+
type MsgMessageKeys<M extends readonly MsgMessageInput[]> = M extends readonly [] ? string : M[number]['key'];
|
|
19
61
|
/**
|
|
20
62
|
* A named collection of messages belonging to a {@link MsgProject}.
|
|
21
63
|
*
|
|
22
64
|
* Resources inherit format defaults from their project, support translation
|
|
23
65
|
* loading (including pseudo-localization), and can serialize to plain data.
|
|
66
|
+
*
|
|
67
|
+
* @typeParam K - Union of message keys. Inferred by {@link MsgResource.create}
|
|
68
|
+
* when its messages are `as const`; otherwise `string`.
|
|
24
69
|
*/
|
|
25
|
-
declare class MsgResource extends Map<
|
|
70
|
+
declare class MsgResource<K extends string = string> extends Map<K, MsgMessage> implements MsgInterface {
|
|
26
71
|
private _attributes;
|
|
27
72
|
private _notes;
|
|
28
73
|
private _title;
|
|
29
74
|
private _project;
|
|
75
|
+
/**
|
|
76
|
+
* For every key prefix that is a branch in the tree (`a` and `a.b` for key
|
|
77
|
+
* `a.b.c`), how many stored keys pass through it. Keeps collision checks
|
|
78
|
+
* proportional to key depth instead of resource size.
|
|
79
|
+
*/
|
|
80
|
+
private _branches;
|
|
30
81
|
/**
|
|
31
82
|
* Builds a resource from {@link MsgResourceData} and an owning project.
|
|
32
83
|
*
|
|
33
84
|
* When `messages` is provided, each entry is added to the resource.
|
|
34
85
|
* When omitted, the resource starts empty.
|
|
86
|
+
*
|
|
87
|
+
* **Typed keys are opt-in with `as const`.** When `messages` (or the whole
|
|
88
|
+
* definition) is `as const`, the resource's key type is the union of its
|
|
89
|
+
* message keys, so `get()`, `has()` and `toTree()` reject unknown keys.
|
|
90
|
+
* Without `as const` the key type is `string`, exactly as before, so a
|
|
91
|
+
* resource can keep growing through `add()`.
|
|
92
|
+
*
|
|
93
|
+
* ```ts
|
|
94
|
+
* const typed = MsgResource.create({
|
|
95
|
+
* title: 'Home',
|
|
96
|
+
* attributes: { lang: 'en' },
|
|
97
|
+
* messages: [{ key: 'home.title', value: 'Welcome' }] as const
|
|
98
|
+
* }, project);
|
|
99
|
+
* typed.get('home.titel'); // compile error
|
|
100
|
+
* ```
|
|
101
|
+
*
|
|
102
|
+
* `as const` data is a tuple, so inference also scales to large resources:
|
|
103
|
+
* up to TypeScript's ~10,000-element tuple limit.
|
|
104
|
+
*
|
|
105
|
+
* @typeParam M - The message list; its `key` types become the resource's
|
|
106
|
+
* key type.
|
|
107
|
+
* @throws {TypeError} When one key is a dot-separated prefix of another
|
|
108
|
+
* (for example `a` and `a.b`).
|
|
35
109
|
*/
|
|
36
|
-
static create
|
|
110
|
+
static create<M extends readonly MsgMessageInput[] = MsgMessageData[]>(data: {
|
|
111
|
+
readonly title: string;
|
|
112
|
+
readonly attributes: Readonly<MsgAttributes>;
|
|
113
|
+
readonly notes?: readonly Readonly<MsgNote>[];
|
|
114
|
+
readonly messages?: M;
|
|
115
|
+
}, project: MsgProject): MsgResource<MsgMessageKeys<M>>;
|
|
37
116
|
/**
|
|
38
117
|
* Creates a resource bound to a project. Prefer {@link MsgResource.create}.
|
|
39
118
|
*/
|
|
@@ -80,19 +159,55 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
|
|
|
80
159
|
* Unspecified `lang`, `dir`, and `dnt` inherit from this resource; explicit
|
|
81
160
|
* values on the message win.
|
|
82
161
|
*
|
|
162
|
+
* Accepts any string key and does not change the resource's key type.
|
|
163
|
+
*
|
|
83
164
|
* @returns This resource, for chaining.
|
|
165
|
+
* @throws {TypeError} When `key` and an existing key are dot-separated
|
|
166
|
+
* prefixes of one another (for example `a` and `a.b`).
|
|
84
167
|
*/
|
|
85
168
|
add(key: string, value: string, attributes?: MsgAttributes, notes?: MsgNote[]): this;
|
|
169
|
+
/**
|
|
170
|
+
* Stores a message under `key`.
|
|
171
|
+
*
|
|
172
|
+
* @throws {TypeError} When `key` and an existing key are dot-separated
|
|
173
|
+
* prefixes of one another (for example `a` and `a.b`), since a tree node
|
|
174
|
+
* cannot be both a message and a branch.
|
|
175
|
+
*/
|
|
176
|
+
set(key: K, value: MsgMessage): this;
|
|
177
|
+
/** Removes the message stored under `key`. */
|
|
178
|
+
delete(key: K): boolean;
|
|
179
|
+
/** Removes every message from this resource. */
|
|
180
|
+
clear(): void;
|
|
181
|
+
/**
|
|
182
|
+
* Throws when `key` would be both a message and a branch in the tree.
|
|
183
|
+
*/
|
|
184
|
+
private assertNoCollision;
|
|
185
|
+
/**
|
|
186
|
+
* Adds `delta` to the count of every branch `key` passes through,
|
|
187
|
+
* dropping branches that no key uses any more.
|
|
188
|
+
*/
|
|
189
|
+
private updateBranches;
|
|
190
|
+
/**
|
|
191
|
+
* Returns a nested, read-only view of this resource's messages, splitting
|
|
192
|
+
* keys on `.`: `resource.toTree().home.cta.label` is the message stored
|
|
193
|
+
* under `'home.cta.label'`.
|
|
194
|
+
*
|
|
195
|
+
* The key type comes from `this` rather than the class parameter so that a
|
|
196
|
+
* typed resource stays assignable to a plain `MsgResource`.
|
|
197
|
+
*/
|
|
198
|
+
toTree<T extends string>(this: MsgResource<T>): MsgTree<T>;
|
|
86
199
|
/**
|
|
87
200
|
* Builds a translated copy of this resource from translation data.
|
|
88
201
|
*
|
|
89
202
|
* Messages present in the translation replace the source; missing keys keep
|
|
90
|
-
* the source message.
|
|
91
|
-
*
|
|
203
|
+
* the source message. Keys that are not in this resource are ignored, so the
|
|
204
|
+
* translated resource has the same keys (and key type) as the source. Notes
|
|
205
|
+
* are carried over from the source. Unspecified message `lang`, `dir`, and
|
|
206
|
+
* `dnt` inherit from the translated resource.
|
|
92
207
|
*
|
|
93
208
|
* @throws {TypeError} When the translation title does not match this resource.
|
|
94
209
|
*/
|
|
95
|
-
translate(data: MsgResourceData): MsgResource
|
|
210
|
+
translate(data: MsgResourceData): MsgResource<K>;
|
|
96
211
|
/**
|
|
97
212
|
* Merge a `format` into an attribute set unless one is already present,
|
|
98
213
|
* so translations inherit the source's format without overriding an
|
|
@@ -112,7 +227,7 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
|
|
|
112
227
|
*
|
|
113
228
|
* @throws {Error} When the locale is unsupported or its language chain is empty.
|
|
114
229
|
*/
|
|
115
|
-
getTranslation(lang?: string): Promise<MsgResource
|
|
230
|
+
getTranslation(lang?: string): Promise<MsgResource<K>>;
|
|
116
231
|
/**
|
|
117
232
|
* Returns a plain data object for this resource and its messages.
|
|
118
233
|
*
|
|
@@ -121,7 +236,7 @@ declare class MsgResource extends Map<string, MsgMessage> implements MsgInterfac
|
|
|
121
236
|
*
|
|
122
237
|
* @param stripNotes - When true, notes are omitted from the result.
|
|
123
238
|
*/
|
|
124
|
-
getData(stripNotes?: boolean): MsgResourceData
|
|
239
|
+
getData(stripNotes?: boolean): MsgResourceData<K>;
|
|
125
240
|
/**
|
|
126
241
|
* Serializes this resource to a formatted JSON string.
|
|
127
242
|
*
|
|
@@ -211,4 +326,4 @@ declare class MsgProject {
|
|
|
211
326
|
getTargetLocale(locale: string): string[] | undefined;
|
|
212
327
|
}
|
|
213
328
|
|
|
214
|
-
export { MsgAttributes, MsgFormat, MsgInterface, type MsgLocalesSettings, MsgMessage, MsgMessageData, MsgNote, MsgProject, type MsgProjectData, type MsgProjectSettings, MsgResource, type MsgResourceData, type MsgTargetLocalesSettings, type MsgTranslationLoader, NoteTypes };
|
|
329
|
+
export { MsgAttributes, MsgFormat, MsgInterface, type MsgLocalesSettings, MsgMessage, MsgMessageData, MsgNote, MsgProject, type MsgProjectData, type MsgProjectSettings, MsgResource, type MsgResourceData, type MsgTargetLocalesSettings, type MsgTranslationLoader, type MsgTree, type MsgTreeNode, NoteTypes };
|