@hazeljs/i18n 0.2.0-beta.57 → 0.2.0-beta.58

package/dist/decorators/lang.decorator.d.ts

@@ -1,23 +1,33 @@
 import 'reflect-metadata';
+/**
+ * Internal query key used to pass the resolved locale through the HazelJS
+ * request context so the router can inject it via @Lang().
+ *
+ * The proxy handler in main.ts writes this key into context.query before
+ * route matching; @Lang() reads it back using the standard 'query' injection
+ * type that the router already handles.
+ */
+export declare const LANG_QUERY_KEY = "__hazel_i18n_locale__";
 /**
  * Parameter decorator that injects the detected locale string into a
  * controller method parameter.
  *
- * The locale is set by LocaleMiddleware earlier in the request lifecycle.
- * When the middleware is not applied, the parameter will be `undefined`.
+ * Requires LocaleMiddleware (via addProxyHandler) to run before routing so
+ * the locale is resolved and stored in context.query[LANG_QUERY_KEY].
+ * When the middleware is not applied, the parameter will be undefined.
  *
  * @example
  * ```ts
  * @Get('/hello')
  * greet(@Lang() locale: string) {
- *   return this.i18n.t('welcome', { locale });
+ *   return this.i18n.t('welcome', { locale, vars: { name: 'World' } });
  * }
  * ```
  */
 export declare function Lang(): ParameterDecorator;
 /**
- * Reads the locale injected by @Lang() from the raw request object.
- * Exposed for use in custom parameter resolvers.
+ * Reads the locale injected by LocaleMiddleware from the raw request object.
+ * Useful outside of controller parameters (e.g. in exception filters).
  */
 export declare function extractLang(req: Record<string, unknown>): string | undefined;
 //# sourceMappingURL=lang.decorator.d.ts.map

package/dist/decorators/lang.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lang.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/lang.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAK1B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,IAAI,kBAAkB,CAezC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAE5E"}
+{"version":3,"file":"lang.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/lang.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAK1B;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,IAAI,kBAAkB,CAiBzC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAE5E"}

package/dist/decorators/lang.decorator.js

@@ -1,22 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LANG_QUERY_KEY = void 0;
 exports.Lang = Lang;
 exports.extractLang = extractLang;
 require("reflect-metadata");
 const i18n_middleware_1 = require("../i18n.middleware");
 const INJECT_METADATA_KEY = 'hazel:inject';
+/**
+ * Internal query key used to pass the resolved locale through the HazelJS
+ * request context so the router can inject it via @Lang().
+ *
+ * The proxy handler in main.ts writes this key into context.query before
+ * route matching; @Lang() reads it back using the standard 'query' injection
+ * type that the router already handles.
+ */
+exports.LANG_QUERY_KEY = '__hazel_i18n_locale__';
 /**
  * Parameter decorator that injects the detected locale string into a
  * controller method parameter.
  *
- * The locale is set by LocaleMiddleware earlier in the request lifecycle.
- * When the middleware is not applied, the parameter will be `undefined`.
+ * Requires LocaleMiddleware (via addProxyHandler) to run before routing so
+ * the locale is resolved and stored in context.query[LANG_QUERY_KEY].
+ * When the middleware is not applied, the parameter will be undefined.
  *
  * @example
  * ```ts
  * @Get('/hello')
  * greet(@Lang() locale: string) {
- *   return this.i18n.t('welcome', { locale });
+ *   return this.i18n.t('welcome', { locale, vars: { name: 'World' } });
  * }
  * ```
  */
@@ -27,13 +38,15 @@ function Lang() {
         }
         const constructor = target.constructor;
         const injections = Reflect.getMetadata(INJECT_METADATA_KEY, constructor, propertyKey) ?? [];
-        injections[parameterIndex] = { type: 'custom', key: i18n_middleware_1.LOCALE_KEY, source: 'request' };
+        // Use the router's built-in 'query' injection — the proxy handler seeds
+        // context.query[LANG_QUERY_KEY] with the detected locale before routing.
+        injections[parameterIndex] = { type: 'query', name: exports.LANG_QUERY_KEY };
         Reflect.defineMetadata(INJECT_METADATA_KEY, injections, constructor, propertyKey);
     };
 }
 /**
- * Reads the locale injected by @Lang() from the raw request object.
- * Exposed for use in custom parameter resolvers.
+ * Reads the locale injected by LocaleMiddleware from the raw request object.
+ * Useful outside of controller parameters (e.g. in exception filters).
  */
 function extractLang(req) {
     return req[i18n_middleware_1.LOCALE_KEY];

package/dist/decorators/lang.decorator.test.js

@@ -19,7 +19,7 @@ describe('Lang() decorator', () => {
         decorator(target, 'greet', 0);
         const metadata = Reflect.getMetadata(INJECT_METADATA_KEY, TestController, 'greet');
         expect(metadata).toBeDefined();
-        expect(metadata[0]).toEqual({ type: 'custom', key: i18n_middleware_1.LOCALE_KEY, source: 'request' });
+        expect(metadata[0]).toEqual({ type: 'query', name: lang_decorator_1.LANG_QUERY_KEY });
     });
     it('stores metadata at the correct parameter index', () => {
         class TwoParamController {
@@ -28,7 +28,7 @@ describe('Lang() decorator', () => {
         const decorator = (0, lang_decorator_1.Lang)();
         decorator(TwoParamController.prototype, 'doSomething', 1);
         const metadata = Reflect.getMetadata(INJECT_METADATA_KEY, TwoParamController, 'doSomething');
-        expect(metadata[1]).toEqual({ type: 'custom', key: i18n_middleware_1.LOCALE_KEY, source: 'request' });
+        expect(metadata[1]).toEqual({ type: 'query', name: lang_decorator_1.LANG_QUERY_KEY });
         expect(metadata[0]).toBeUndefined();
     });
     it('merges with existing metadata at other indices', () => {
@@ -41,7 +41,7 @@ describe('Lang() decorator', () => {
         decorator(MultiController.prototype, 'action', 2);
         const metadata = Reflect.getMetadata(INJECT_METADATA_KEY, MultiController, 'action');
         expect(metadata[0]).toEqual({ type: 'body' });
-        expect(metadata[2]).toEqual({ type: 'custom', key: i18n_middleware_1.LOCALE_KEY, source: 'request' });
+        expect(metadata[2]).toEqual({ type: 'query', name: lang_decorator_1.LANG_QUERY_KEY });
     });
     it('throws when propertyKey is undefined (constructor usage)', () => {
         const decorator = (0, lang_decorator_1.Lang)();

package/dist/i18n.middleware.d.ts

@@ -24,7 +24,11 @@ export declare class LocaleMiddleware {
     /**
      * Run through each configured strategy in priority order and return the
      * first valid locale found, or the default locale as a fallback.
+     *
+     * Exposed publicly so proxy handlers (e.g. addProxyHandler in main.ts) can
+     * call locale detection without going through the full middleware pipeline.
      */
+    resolveLocale(req: Request): string;
     private detect;
     /**
      * Parse the Cookie header and extract the value for the given name.

package/dist/i18n.middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.middleware.d.ts","sourceRoot":"","sources":["../src/i18n.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,mBAAmB;IAEzD,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI;IAQ3D;;;OAGG;IACH,OAAO,CAAC,MAAM;IAwBd;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;OAGG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,OAAO,EAAE,mBAAmB,GAC3B,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI;CAI3D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAErE"}
+{"version":3,"file":"i18n.middleware.d.ts","sourceRoot":"","sources":["../src/i18n.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,mBAAmB;IAEzD,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI;IAQ3D;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM;IAInC,OAAO,CAAC,MAAM;IAwBd;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;OAGG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,OAAO,EAAE,mBAAmB,GAC3B,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI;CAI3D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAErE"}

package/dist/i18n.middleware.js

@@ -33,7 +33,13 @@ class LocaleMiddleware {
     /**
      * Run through each configured strategy in priority order and return the
      * first valid locale found, or the default locale as a fallback.
+     *
+     * Exposed publicly so proxy handlers (e.g. addProxyHandler in main.ts) can
+     * call locale detection without going through the full middleware pipeline.
      */
+    resolveLocale(req) {
+        return this.detect(req);
+    }
     detect(req) {
         for (const strategy of this.options.detection) {
             switch (strategy) {

package/dist/i18n.module.d.ts

@@ -57,7 +57,7 @@ export declare class I18nModule {
      * ```
      */
     static forRootAsync(options: {
-        useFactory: (...args: unknown[]) => Promise<I18nOptions> | I18nOptions;
+        useFactory: (...args: any[]) => I18nOptions;
         inject?: unknown[];
     }): {
         module: typeof I18nModule;

package/dist/i18n.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.module.d.ts","sourceRoot":"","sources":["../src/i18n.module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAuB,MAAM,SAAS,CAAC;AAuB3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAIa,UAAU;IACrB;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG;QACzC,MAAM,EAAE,OAAO,UAAU,CAAC;QAC1B,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,MAAM,GAAG,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC;YAC/D,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;SACnB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,CAAC;KACjB;IAmCD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE;QAC3B,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC;QACvE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;KACpB,GAAG;QACF,MAAM,EAAE,OAAO,UAAU,CAAC;QAC1B,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,MAAM,GAAG,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC;YAC/D,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAC5C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;SACpB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,CAAC;KACjB;CAoCF"}
+{"version":3,"file":"i18n.module.d.ts","sourceRoot":"","sources":["../src/i18n.module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAuB,MAAM,SAAS,CAAC;AAuB3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAIa,UAAU;IACrB;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG;QACzC,MAAM,EAAE,OAAO,UAAU,CAAC;QAC1B,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,MAAM,GAAG,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC;YAC/D,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;SACnB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,CAAC;KACjB;IAmCD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE;QAE3B,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,WAAW,CAAC;QAC5C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;KACpB,GAAG;QACF,MAAM,EAAE,OAAO,UAAU,CAAC;QAC1B,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,MAAM,GAAG,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC;YAC/D,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAC5C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;SACpB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,WAAW,GAAG,OAAO,gBAAgB,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,CAAC;KACjB;CAoCF"}

package/dist/i18n.module.js

@@ -71,9 +71,9 @@ let I18nModule = I18nModule_1 = class I18nModule {
                 },
                 {
                     provide: i18n_service_1.I18nService,
-                    useFactory: async (...args) => {
+                    useFactory: (...args) => {
                         const opts = args[0];
-                        const store = await translation_loader_1.TranslationLoader.load(opts.translationsPath);
+                        const store = translation_loader_1.TranslationLoader.load(opts.translationsPath);
                         const service = new i18n_service_1.I18nService();
                         service.initialize(store, opts);
                         return service;
@@ -114,17 +114,17 @@ let I18nModule = I18nModule_1 = class I18nModule {
             providers: [
                 {
                     provide: I18N_OPTIONS_TOKEN,
-                    useFactory: async (...args) => {
-                        const userOptions = await options.useFactory(...args);
+                    useFactory: (...args) => {
+                        const userOptions = options.useFactory(...args);
                         return resolveOptions(userOptions);
                     },
                     inject: options.inject ?? [],
                 },
                 {
                     provide: i18n_service_1.I18nService,
-                    useFactory: async (...args) => {
+                    useFactory: (...args) => {
                         const opts = args[0];
-                        const store = await translation_loader_1.TranslationLoader.load(opts.translationsPath);
+                        const store = translation_loader_1.TranslationLoader.load(opts.translationsPath);
                         const service = new i18n_service_1.I18nService();
                         service.initialize(store, opts);
                         return service;

package/dist/i18n.module.test.js

@@ -7,7 +7,7 @@ jest.mock('@hazeljs/core', () => ({
 }));
 jest.mock('./translation.loader', () => ({
     TranslationLoader: {
-        load: jest.fn().mockResolvedValue(new Map()),
+        load: jest.fn().mockReturnValue(new Map()),
     },
 }));
 const i18n_module_1 = require("./i18n.module");
@@ -18,7 +18,7 @@ const mockLoad = translation_loader_1.TranslationLoader.load;
 describe('I18nModule', () => {
     beforeEach(() => {
         jest.clearAllMocks();
-        mockLoad.mockResolvedValue(new Map());
+        mockLoad.mockReturnValue(new Map());
     });
     describe('forRoot()', () => {
         it('returns module reference', () => {
@@ -57,14 +57,14 @@ describe('I18nModule', () => {
             const optionsProvider = result.providers.find((p) => p.provide === 'I18N_OPTIONS');
             expect(optionsProvider?.useValue?.fallbackLocale).toBe('en');
         });
-        it('I18nService factory creates and initializes service', async () => {
+        it('I18nService factory creates and initializes service', () => {
             const store = new Map([['en', { hello: 'Hello' }]]);
-            mockLoad.mockResolvedValue(store);
+            mockLoad.mockReturnValue(store);
             const result = i18n_module_1.I18nModule.forRoot({ translationsPath: './trans' });
             const serviceProvider = result.providers.find((p) => p.provide === i18n_service_1.I18nService);
             const optionsProvider = result.providers.find((p) => p.provide === 'I18N_OPTIONS');
             const opts = optionsProvider?.useValue;
-            const service = await serviceProvider?.useFactory?.(opts);
+            const service = serviceProvider?.useFactory?.(opts);
             expect(service).toBeInstanceOf(i18n_service_1.I18nService);
             expect(mockLoad).toHaveBeenCalled();
         });
@@ -92,39 +92,39 @@ describe('I18nModule', () => {
     });
     describe('forRootAsync()', () => {
         it('returns module reference', () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             expect(result.module).toBe(i18n_module_1.I18nModule);
         });
         it('exports I18nService and LocaleMiddleware', () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             expect(result.exports).toContain(i18n_service_1.I18nService);
             expect(result.exports).toContain(i18n_middleware_1.LocaleMiddleware);
         });
         it('sets global to true', () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             expect(result.global).toBe(true);
         });
         it('provides 3 providers', () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             expect(result.providers).toHaveLength(3);
         });
-        it('OPTIONS factory resolves and applies defaults', async () => {
+        it('OPTIONS factory resolves and applies defaults', () => {
             const result = i18n_module_1.I18nModule.forRootAsync({
-                useFactory: async () => ({ defaultLocale: 'ja' }),
+                useFactory: () => ({ defaultLocale: 'ja' }),
             });
             const optionsProvider = result.providers.find((p) => p.provide === 'I18N_OPTIONS');
-            const resolved = await optionsProvider?.useFactory?.();
+            const resolved = optionsProvider?.useFactory?.();
             expect(resolved.defaultLocale).toBe('ja');
         });
-        it('passes inject args through to useFactory', async () => {
-            const factory = jest.fn().mockResolvedValue({ defaultLocale: 'ko' });
+        it('passes inject args through to useFactory', () => {
+            const factory = jest.fn().mockReturnValue({ defaultLocale: 'ko' });
             const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: factory, inject: ['CONFIG'] });
             const optionsProvider = result.providers.find((p) => p.provide === 'I18N_OPTIONS');
-            await optionsProvider?.useFactory?.('some-config-value');
+            optionsProvider?.useFactory?.('some-config-value');
             expect(factory).toHaveBeenCalledWith('some-config-value');
         });
-        it('I18nService factory creates and initializes service', async () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+        it('I18nService factory creates and initializes service', () => {
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             const serviceProvider = result.providers.find((p) => p.provide === i18n_service_1.I18nService);
             const resolvedOpts = {
                 defaultLocale: 'en',
@@ -135,11 +135,11 @@ describe('I18nModule', () => {
                 cookieName: 'locale',
                 isGlobal: true,
             };
-            const service = await serviceProvider?.useFactory?.(resolvedOpts);
+            const service = serviceProvider?.useFactory?.(resolvedOpts);
             expect(service).toBeInstanceOf(i18n_service_1.I18nService);
         });
-        it('LocaleMiddleware factory creates middleware', async () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+        it('LocaleMiddleware factory creates middleware', () => {
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             const mwProvider = result.providers.find((p) => p.provide === i18n_middleware_1.LocaleMiddleware);
             const resolvedOpts = {
                 defaultLocale: 'en',
@@ -150,11 +150,11 @@ describe('I18nModule', () => {
                 cookieName: 'locale',
                 isGlobal: true,
             };
-            const mw = await mwProvider?.useFactory?.(resolvedOpts);
+            const mw = mwProvider?.useFactory?.(resolvedOpts);
             expect(mw).toBeInstanceOf(i18n_middleware_1.LocaleMiddleware);
         });
         it('uses empty array for inject when not specified', () => {
-            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: async () => ({}) });
+            const result = i18n_module_1.I18nModule.forRootAsync({ useFactory: () => ({}) });
             const optionsProvider = result.providers.find((p) => p.provide === 'I18N_OPTIONS');
             expect(optionsProvider?.inject).toEqual([]);
         });

package/dist/index.d.ts

@@ -22,6 +22,6 @@ export { I18nService, I18nFormatter } from './i18n.service';
 export { LocaleMiddleware, getLocaleFromRequest, LOCALE_KEY } from './i18n.middleware';
 export { I18nInterceptor } from './i18n.interceptor';
 export { TranslationLoader } from './translation.loader';
-export { Lang, extractLang } from './decorators/lang.decorator';
+export { Lang, extractLang, LANG_QUERY_KEY } from './decorators/lang.decorator';
 export type { I18nOptions, ResolvedI18nOptions, TranslateOptions, TranslationMap, TranslationValue, LocaleStore, LocaleDetectionStrategy, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAChE,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,uBAAuB,GACxB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAChF,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,uBAAuB,GACxB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -19,7 +19,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractLang = exports.Lang = exports.TranslationLoader = exports.I18nInterceptor = exports.LOCALE_KEY = exports.getLocaleFromRequest = exports.LocaleMiddleware = exports.I18nFormatter = exports.I18nService = exports.I18nModule = void 0;
+exports.LANG_QUERY_KEY = exports.extractLang = exports.Lang = exports.TranslationLoader = exports.I18nInterceptor = exports.LOCALE_KEY = exports.getLocaleFromRequest = exports.LocaleMiddleware = exports.I18nFormatter = exports.I18nService = exports.I18nModule = void 0;
 var i18n_module_1 = require("./i18n.module");
 Object.defineProperty(exports, "I18nModule", { enumerable: true, get: function () { return i18n_module_1.I18nModule; } });
 var i18n_service_1 = require("./i18n.service");
@@ -36,3 +36,4 @@ Object.defineProperty(exports, "TranslationLoader", { enumerable: true, get: fun
 var lang_decorator_1 = require("./decorators/lang.decorator");
 Object.defineProperty(exports, "Lang", { enumerable: true, get: function () { return lang_decorator_1.Lang; } });
 Object.defineProperty(exports, "extractLang", { enumerable: true, get: function () { return lang_decorator_1.extractLang; } });
+Object.defineProperty(exports, "LANG_QUERY_KEY", { enumerable: true, get: function () { return lang_decorator_1.LANG_QUERY_KEY; } });

package/dist/translation.loader.d.ts

@@ -5,12 +5,16 @@ import { LocaleStore } from './types';
  * Each file must be named <locale>.json (e.g. en.json, fr.json, zh-TW.json).
  * Nested objects in the JSON are kept as-is; key lookup via dot-notation is
  * resolved at translation time inside I18nService.
+ *
+ * Synchronous I/O is intentional: HazelJS's DI container resolves providers
+ * synchronously, so async factories would result in a Promise being stored
+ * as the service instance rather than the resolved value.
  */
 export declare class TranslationLoader {
     /**
-     * Read all *.json files from the given directory.
+     * Read all *.json files from the given directory synchronously.
      * Returns a Map keyed by locale code (the filename without extension).
      */
-    static load(translationsPath: string): Promise<LocaleStore>;
+    static load(translationsPath: string): LocaleStore;
 }
 //# sourceMappingURL=translation.loader.d.ts.map

package/dist/translation.loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translation.loader.d.ts","sourceRoot":"","sources":["../src/translation.loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B;;;OAGG;WACU,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAmClE"}
+{"version":3,"file":"translation.loader.d.ts","sourceRoot":"","sources":["../src/translation.loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,WAAW;CAiCnD"}

package/dist/translation.loader.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TranslationLoader = void 0;
-const promises_1 = require("fs/promises");
+const fs_1 = require("fs");
 const path_1 = require("path");
 /**
  * Loads JSON translation files from a directory and returns a locale store.
@@ -9,17 +9,21 @@ const path_1 = require("path");
  * Each file must be named <locale>.json (e.g. en.json, fr.json, zh-TW.json).
  * Nested objects in the JSON are kept as-is; key lookup via dot-notation is
  * resolved at translation time inside I18nService.
+ *
+ * Synchronous I/O is intentional: HazelJS's DI container resolves providers
+ * synchronously, so async factories would result in a Promise being stored
+ * as the service instance rather than the resolved value.
  */
 class TranslationLoader {
     /**
-     * Read all *.json files from the given directory.
+     * Read all *.json files from the given directory synchronously.
      * Returns a Map keyed by locale code (the filename without extension).
      */
-    static async load(translationsPath) {
+    static load(translationsPath) {
         const store = new Map();
         let entries;
         try {
-            entries = await (0, promises_1.readdir)(translationsPath);
+            entries = (0, fs_1.readdirSync)(translationsPath);
         }
         catch {
             // Directory does not exist — return an empty store so the service starts
@@ -27,11 +31,11 @@ class TranslationLoader {
             return store;
         }
         const jsonFiles = entries.filter((file) => (0, path_1.extname)(file) === '.json');
-        await Promise.all(jsonFiles.map(async (file) => {
+        for (const file of jsonFiles) {
             const locale = (0, path_1.basename)(file, '.json');
             const filePath = (0, path_1.join)(translationsPath, file);
             try {
-                const raw = await (0, promises_1.readFile)(filePath, 'utf-8');
+                const raw = (0, fs_1.readFileSync)(filePath, 'utf-8');
                 const translations = JSON.parse(raw);
                 store.set(locale, translations);
             }
@@ -40,7 +44,7 @@ class TranslationLoader {
                 const message = err instanceof Error ? err.message : String(err);
                 process.stderr.write(`[@hazeljs/i18n] Failed to load translation file "${filePath}": ${message}\n`);
             }
-        }));
+        }
         return store;
     }
 }

package/dist/translation.loader.test.js

@@ -1,82 +1,86 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const translation_loader_1 = require("./translation.loader");
-jest.mock('fs/promises', () => ({
-    readdir: jest.fn(),
-    readFile: jest.fn(),
+jest.mock('fs', () => ({
+    readdirSync: jest.fn(),
+    readFileSync: jest.fn(),
 }));
-const promises_1 = require("fs/promises");
-const mockReaddir = promises_1.readdir;
-const mockReadFile = promises_1.readFile;
+const fs_1 = require("fs");
+const mockReaddirSync = fs_1.readdirSync;
+const mockReadFileSync = fs_1.readFileSync;
 describe('TranslationLoader', () => {
     beforeEach(() => {
         jest.clearAllMocks();
     });
     describe('load()', () => {
-        it('returns an empty store when directory does not exist', async () => {
-            mockReaddir.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
-            const store = await translation_loader_1.TranslationLoader.load('/nonexistent/path');
+        it('returns an empty store when directory does not exist', () => {
+            mockReaddirSync.mockImplementation(() => {
+                throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+            });
+            const store = translation_loader_1.TranslationLoader.load('/nonexistent/path');
             expect(store.size).toBe(0);
         });
-        it('returns an empty store when directory is empty', async () => {
-            mockReaddir.mockResolvedValue([]);
-            const store = await translation_loader_1.TranslationLoader.load('/empty/dir');
+        it('returns an empty store when directory is empty', () => {
+            mockReaddirSync.mockReturnValue([]);
+            const store = translation_loader_1.TranslationLoader.load('/empty/dir');
             expect(store.size).toBe(0);
         });
-        it('ignores non-JSON files', async () => {
-            mockReaddir.mockResolvedValue(['README.md', 'notes.txt']);
-            const store = await translation_loader_1.TranslationLoader.load('/some/dir');
+        it('ignores non-JSON files', () => {
+            mockReaddirSync.mockReturnValue(['README.md', 'notes.txt']);
+            const store = translation_loader_1.TranslationLoader.load('/some/dir');
             expect(store.size).toBe(0);
-            expect(mockReadFile).not.toHaveBeenCalled();
+            expect(mockReadFileSync).not.toHaveBeenCalled();
         });
-        it('loads a single JSON file and stores translations by locale', async () => {
-            mockReaddir.mockResolvedValue(['en.json']);
-            mockReadFile.mockResolvedValue('{"hello":"Hello","bye":"Goodbye"}');
-            const store = await translation_loader_1.TranslationLoader.load('/translations');
+        it('loads a single JSON file and stores translations by locale', () => {
+            mockReaddirSync.mockReturnValue(['en.json']);
+            mockReadFileSync.mockReturnValue('{"hello":"Hello","bye":"Goodbye"}');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
             expect(store.has('en')).toBe(true);
             expect(store.get('en')).toEqual({ hello: 'Hello', bye: 'Goodbye' });
         });
-        it('loads multiple JSON files into separate locale entries', async () => {
-            mockReaddir.mockResolvedValue(['en.json', 'fr.json']);
-            mockReadFile
-                .mockResolvedValueOnce('{"hello":"Hello"}')
-                .mockResolvedValueOnce('{"hello":"Bonjour"}');
-            const store = await translation_loader_1.TranslationLoader.load('/translations');
+        it('loads multiple JSON files into separate locale entries', () => {
+            mockReaddirSync.mockReturnValue(['en.json', 'fr.json']);
+            mockReadFileSync
+                .mockReturnValueOnce('{"hello":"Hello"}')
+                .mockReturnValueOnce('{"hello":"Bonjour"}');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
             expect(store.size).toBe(2);
             expect(store.get('en')).toEqual({ hello: 'Hello' });
             expect(store.get('fr')).toEqual({ hello: 'Bonjour' });
         });
-        it('handles locale codes with hyphens (zh-TW.json)', async () => {
-            mockReaddir.mockResolvedValue(['zh-TW.json']);
-            mockReadFile.mockResolvedValue('{"greeting":"你好"}');
-            const store = await translation_loader_1.TranslationLoader.load('/translations');
+        it('handles locale codes with hyphens (zh-TW.json)', () => {
+            mockReaddirSync.mockReturnValue(['zh-TW.json']);
+            mockReadFileSync.mockReturnValue('{"greeting":"你好"}');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
             expect(store.has('zh-TW')).toBe(true);
         });
-        it('skips malformed JSON files and writes to stderr', async () => {
+        it('skips malformed JSON files and writes to stderr', () => {
             const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
-            mockReaddir.mockResolvedValue(['en.json', 'bad.json']);
-            mockReadFile
-                .mockResolvedValueOnce('{"ok":true}')
-                .mockResolvedValueOnce('{ invalid json');
-            const store = await translation_loader_1.TranslationLoader.load('/translations');
+            mockReaddirSync.mockReturnValue(['en.json', 'bad.json']);
+            mockReadFileSync
+                .mockReturnValueOnce('{"ok":true}')
+                .mockReturnValueOnce('{ invalid json');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
             expect(store.has('en')).toBe(true);
             expect(store.has('bad')).toBe(false);
             expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('[@hazeljs/i18n]'));
             stderrSpy.mockRestore();
         });
-        it('writes non-Error exception to stderr as string', async () => {
+        it('writes non-Error exception to stderr as string', () => {
             const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
-            mockReaddir.mockResolvedValue(['broken.json']);
-            mockReadFile.mockRejectedValue('string error');
-            const store = await translation_loader_1.TranslationLoader.load('/translations');
+            mockReaddirSync.mockReturnValue(['broken.json']);
+            mockReadFileSync.mockImplementation(() => {
+                throw 'string error';
+            });
+            const store = translation_loader_1.TranslationLoader.load('/translations');
             expect(store.has('broken')).toBe(false);
             expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('string error'));
             stderrSpy.mockRestore();
         });
-        it('loads nested translation objects', async () => {
-            mockReaddir.mockResolvedValue(['en.json']);
-            mockReadFile.mockResolvedValue(JSON.stringify({ errors: { notFound: 'Not found', invalid: 'Invalid' } }));
-            const store = await translation_loader_1.TranslationLoader.load('/translations');
+        it('loads nested translation objects', () => {
+            mockReaddirSync.mockReturnValue(['en.json']);
+            mockReadFileSync.mockReturnValue(JSON.stringify({ errors: { notFound: 'Not found', invalid: 'Invalid' } }));
+            const store = translation_loader_1.TranslationLoader.load('/translations');
             expect(store.get('en')).toEqual({
                 errors: { notFound: 'Not found', invalid: 'Invalid' },
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazeljs/i18n",
-  "version": "0.2.0-beta.57",
+  "version": "0.2.0-beta.58",
   "description": "Internationalization (i18n) module for HazelJS framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,5 +47,5 @@
   "peerDependencies": {
     "@hazeljs/core": ">=0.2.0-beta.0"
   },
-  "gitHead": "98c84683e8f487c660e344c2beda3a8dcaaff07f"
+  "gitHead": "ce3821b373043284ac4847315371efb137dc860d"
 }