@abinnovision/nestjs-i18n 0.1.0-beta.4 → 0.1.0-beta.5

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 CHANGED
@@ -65,6 +65,8 @@ export class AppModule {}
65
65
 
66
66
  `forRootAsync({ inject, useFactory })` is available as well. The module throws at startup when `defaultLocale` has no catalog.
67
67
 
68
+ `I18nModule` shares its name with the NestJS i18n packages. Alias the import (`import { I18nModule as NestI18nModule }`) or name your own module differently, e.g. `LocalizationModule`.
69
+
68
70
  ### 4. Translate
69
71
 
70
72
  ```typescript
@@ -126,6 +128,35 @@ export class AppModule {}
126
128
 
127
129
  Codes without a message keep the English `details`.
128
130
 
131
+ ### Exception coverage
132
+
133
+ `ExceptionsOf` turns the exports of a module into the union of its exception classes, so a new class is covered once it is exported:
134
+
135
+ ```typescript
136
+ import type * as userExceptions from "./user.exceptions.js";
137
+
138
+ export const en = defineCatalog({
139
+ ...defaultExceptionMessages,
140
+ "exceptions.USER__EMAIL_TAKEN": "Email ''{email}'' is already taken",
141
+ }) satisfies ExceptionMessages<ExceptionsOf<typeof userExceptions>>;
142
+ ```
143
+
144
+ Only exported exception classes with a literal `code` count. Non-exception exports and bases with a wide `code: string` are excluded.
145
+
146
+ ### Entity messages
147
+
148
+ `EntityMessages` requires an `entities.<name>` message per entity name. Combine it with `ExceptionMessages` using `&`:
149
+
150
+ ```typescript
151
+ export const en = defineCatalog({
152
+ ...defaultExceptionMessages,
153
+ "entities.user": "User",
154
+ }) satisfies ExceptionMessages<ExceptionsOf<typeof userExceptions>> &
155
+ EntityMessages;
156
+ ```
157
+
158
+ It checks nothing until `EntityRegistry` is augmented. Use `EntityMessages<"user" | "org">` to name the entities explicitly.
159
+
129
160
  ## Testing
130
161
 
131
162
  ```typescript
@@ -136,4 +167,6 @@ it("has complete catalogs", () => {
136
167
  });
137
168
  ```
138
169
 
170
+ Missing messages: `CatalogShape` enforces keys only when `I18nRegistry` is augmented and the catalogs are not cast. `verifyCatalogs` covers the rest in tests. At runtime, a fallback from a non-default locale is logged at debug level, which is visible when debug logging is enabled (the default with Nest's `ConsoleLogger`).
171
+
139
172
  `verifyCatalogs` reports missing keys, extra keys, messages that fail to parse, and arguments that the default-locale message does not have (for example a `{nmae}` typo).
@@ -1,4 +1,5 @@
1
1
  import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exceptions";
2
+ import { EntityName } from "@abinnovision/nestjs-exceptions/entity";
2
3
 
3
4
  //#region src/exceptions/exception-messages.d.ts
4
5
  /**
@@ -16,5 +17,22 @@ import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exception
16
17
  * ```
17
18
  */
18
19
  type ExceptionMessages<E extends AppExceptionClass> = { [K in `exceptions.${ExceptionCode<E>}`]: string };
20
+ /**
21
+ * The exception classes among the exports of a module type. Excludes
22
+ * non-exception exports and classes whose `code` is not a literal.
23
+ *
24
+ * @example
25
+ * ```typescript
26
+ * import type * as userExceptions from "./user.exceptions.js";
27
+ *
28
+ * type Messages = ExceptionMessages<ExceptionsOf<typeof userExceptions>>;
29
+ * ```
30
+ */
31
+ type ExceptionsOf<M> = { [K in keyof M]: M[K] extends AppExceptionClass ? string extends ExceptionCode<M[K]> ? never : M[K] : never }[keyof M];
32
+ /**
33
+ * Requires an `entities.<name>` message per entity name. Requires nothing
34
+ * while `EntityRegistry` is not augmented.
35
+ */
36
+ type EntityMessages<E extends string = EntityName> = string extends E ? Record<never, never> : { [K in `entities.${E}`]: string };
19
37
  //#endregion
20
- export { ExceptionMessages };
38
+ export { EntityMessages, ExceptionMessages, ExceptionsOf };
@@ -1,4 +1,5 @@
1
1
  import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exceptions";
2
+ import { EntityName } from "@abinnovision/nestjs-exceptions/entity";
2
3
 
3
4
  //#region src/exceptions/exception-messages.d.ts
4
5
  /**
@@ -16,5 +17,22 @@ import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exception
16
17
  * ```
17
18
  */
18
19
  type ExceptionMessages<E extends AppExceptionClass> = { [K in `exceptions.${ExceptionCode<E>}`]: string };
20
+ /**
21
+ * The exception classes among the exports of a module type. Excludes
22
+ * non-exception exports and classes whose `code` is not a literal.
23
+ *
24
+ * @example
25
+ * ```typescript
26
+ * import type * as userExceptions from "./user.exceptions.js";
27
+ *
28
+ * type Messages = ExceptionMessages<ExceptionsOf<typeof userExceptions>>;
29
+ * ```
30
+ */
31
+ type ExceptionsOf<M> = { [K in keyof M]: M[K] extends AppExceptionClass ? string extends ExceptionCode<M[K]> ? never : M[K] : never }[keyof M];
32
+ /**
33
+ * Requires an `entities.<name>` message per entity name. Requires nothing
34
+ * while `EntityRegistry` is not augmented.
35
+ */
36
+ type EntityMessages<E extends string = EntityName> = string extends E ? Record<never, never> : { [K in `entities.${E}`]: string };
19
37
  //#endregion
20
- export { ExceptionMessages };
38
+ export { EntityMessages, ExceptionMessages, ExceptionsOf };
@@ -1,4 +1,4 @@
1
1
  import { I18nExceptionLocalizer } from "./exceptions/i18n-exception-localizer.cjs";
2
2
  import { defaultExceptionMessages } from "./exceptions/default-messages.cjs";
3
- import { ExceptionMessages } from "./exceptions/exception-messages.cjs";
4
- export { ExceptionMessages, I18nExceptionLocalizer, defaultExceptionMessages };
3
+ import { EntityMessages, ExceptionMessages, ExceptionsOf } from "./exceptions/exception-messages.cjs";
4
+ export { EntityMessages, ExceptionMessages, ExceptionsOf, I18nExceptionLocalizer, defaultExceptionMessages };
@@ -1,4 +1,4 @@
1
1
  import { I18nExceptionLocalizer } from "./exceptions/i18n-exception-localizer.mjs";
2
2
  import { defaultExceptionMessages } from "./exceptions/default-messages.mjs";
3
- import { ExceptionMessages } from "./exceptions/exception-messages.mjs";
4
- export { ExceptionMessages, I18nExceptionLocalizer, defaultExceptionMessages };
3
+ import { EntityMessages, ExceptionMessages, ExceptionsOf } from "./exceptions/exception-messages.mjs";
4
+ export { EntityMessages, ExceptionMessages, ExceptionsOf, I18nExceptionLocalizer, defaultExceptionMessages };
@@ -82,6 +82,7 @@ var I18nService = class I18nService {
82
82
  let target = locale;
83
83
  let message = catalogs[locale]?.[key];
84
84
  if (message === void 0) {
85
+ if (locale !== this.config.defaultLocale) this.logger.debug(`Message '${key}' is missing in locale '${locale}'`);
85
86
  target = this.config.defaultLocale;
86
87
  message = catalogs[target]?.[key];
87
88
  }
@@ -82,6 +82,7 @@ var I18nService = class I18nService {
82
82
  let target = locale;
83
83
  let message = catalogs[locale]?.[key];
84
84
  if (message === void 0) {
85
+ if (locale !== this.config.defaultLocale) this.logger.debug(`Message '${key}' is missing in locale '${locale}'`);
85
86
  target = this.config.defaultLocale;
86
87
  message = catalogs[target]?.[key];
87
88
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "@abinnovision/nestjs-i18n",
4
- "version": "0.1.0-beta.4",
4
+ "version": "0.1.0-beta.5",
5
5
  "description": "Type-safe backend i18n for NestJS with ICU MessageFormat catalogs, request locale resolution, and localized exceptions.",
6
6
  "keywords": [
7
7
  "nestjs",