nicot-simple-user 1.0.5 → 1.0.6

package/README.md

@@ -170,6 +170,151 @@ import { AppUser } from './entities/app-user.entity'
 export class AppModule {}
 ```
 
+---
+
+## ⚠️ About `registerAsync`, request-scoped providers, and Aragami
+
+When using `registerAsync`, **be careful about injecting request-scoped providers**
+(directly or indirectly) into the options factory.
+
+**The core rule**
+
+In NestJS, provider scope is *contagious*:
+
+> If a provider depends on a request-scoped provider, it must also become request-scoped.
+
+This implies:
+
+- If **any token in `registerAsync.inject` is request-scoped**
+- Then the internal `MODULE_OPTIONS_TOKEN` of `nicot-simple-user` **will also become request-scoped**
+- As a result, **the entire dependency chain of this module may be upgraded to request scope**
+
+This can happen *silently*, without any warning.
+
+---
+
+**A common real-world example**
+
+Consider this pattern:
+
+```ts
+SimpleUserModule.registerAsync({
+  imports: [SmtpModule],
+  inject: [SmtpService],
+  useFactory: async (smtp: SmtpService) => ({
+    sendCodeGenerator: async (ctx) => {
+      // ...
+    },
+  }),
+})
+```
+
+At first glance, `SmtpService` looks harmless.
+
+However, in many real projects:
+
+- `SmtpService` depends on an email template renderer
+- which depends on an i18n service
+- which uses a ParamResolver or request context
+- which is **request-scoped**
+
+Once that happens, **the entire `SimpleUserModule` options provider becomes request-scoped**.
+
+---
+
+**Why this is dangerous**
+
+`nicot-simple-user` internally integrates with **Aragami** for:
+
+- sessions
+- verification code storage
+- cooldown / risk control
+- locks and counters
+
+Aragami is designed to be **singleton infrastructure**.
+
+If it is accidentally instantiated or resolved through a request-scoped provider chain,
+you may observe:
+
+- multiple Aragami runtimes
+- duplicated Redis connections
+- inconsistent lock / cooldown behavior
+- subtle bugs that only appear under concurrency
+
+These issues are extremely hard to debug once they occur.
+
+---
+
+**Recommended approach: use an existing Aragami instance**
+
+To avoid scope pollution, the **recommended and safest approach** is:
+
+> **Register Aragami at the application level, and tell `nicot-simple-user` to reuse it.**
+
+That is what `useExistingAragami` is for.
+
+```ts
+@Module({
+  imports: [
+    AragamiModule.registerAsync({
+      isGlobal: true,
+      inject: [ConfigService],
+      useFactory: async (config: ConfigService) => ({
+        redis: { uri: config.getOrThrow('REDIS_URL') },
+      }),
+    }),
+
+    SimpleUserModule.registerAsync({
+      useExistingAragami: true,
+
+      imports: [SmtpModule],
+      inject: [SmtpService],
+      useFactory: async (smtp: SmtpService) => ({
+        sendCodeGenerator: async (ctx) => {
+          // ...
+        },
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+With this setup:
+
+- Aragami remains **singleton and global**
+- `nicot-simple-user` does **not** attempt to create or configure Aragami
+- even if `sendCodeGenerator` depends on request-scoped services,
+  **Aragami itself is not affected**
+
+---
+
+**Design guideline**
+
+- Module options (`register` / `registerAsync`) should be treated as **startup-time configuration**
+- Request-specific data should flow through **method parameters**, such as:
+  - `SendCodeDto`
+  - request context objects
+  - runtime services resolved at request time
+
+As a rule of thumb:
+
+> If something depends on request context (i18n, tenant, locale, user agent, IP),
+> it should **not** be injected into a module options factory.
+
+---
+
+**Summary**
+
+- Injecting request-scoped providers into `registerAsync` can silently upgrade the entire module to request scope
+- This can break Aragami’s singleton assumptions
+- **The current best practice is:**
+  - register Aragami once at the application level
+  - set `useExistingAragami: true` in `nicot-simple-user`
+
+This keeps infrastructure stable and avoids extremely subtle scope-related bugs.
+
+
 ---
 
 ## Request Headers

package/dist/simple-user/aragami-init.d.ts

@@ -1,2 +1,3 @@
 import { DynamicModule } from '@nestjs/common';
-export declare function attachAragamiWithBridge(base: DynamicModule, reexport?: boolean): DynamicModule;
+import { SimpleUserExtraOptions } from './options';
+export declare function attachAragamiWithBridge(base: DynamicModule, options: SimpleUserExtraOptions): DynamicModule;

package/dist/simple-user/aragami-init.js

@@ -23,7 +23,9 @@ function deriveAragamiOptions(o) {
     };
 }
 const ARAGAMI_OPTIONS = Symbol('ARAGAMI_OPTIONS');
-function attachAragamiWithBridge(base, reexport = false) {
+function attachAragamiWithBridge(base, options) {
+    if (options.useExistingAragami)
+        return base;
     const baseImports = base.imports ?? [];
     const baseProviders = base.providers ?? [];
     const bridge = {
@@ -49,7 +51,10 @@ function attachAragamiWithBridge(base, reexport = false) {
                 useFactory: (aragamiOptions) => aragamiOptions,
             }),
         ],
-        exports: [...(base.exports || []), ...(reexport ? [nestjs_aragami_1.AragamiModule] : [])],
+        exports: [
+            ...(base.exports || []),
+            ...(options.reexportAragami ? [nestjs_aragami_1.AragamiModule] : []),
+        ],
     };
 }
 //# sourceMappingURL=aragami-init.js.map

package/dist/simple-user/aragami-init.js.map

@@ -1 +1 @@
-{"version":3,"file":"aragami-init.js","sourceRoot":"","sources":["../../src/simple-user/aragami-init.ts"],"names":[],"mappings":";;;;;;;;AAmBA,0DAoCC;AAvDD,2CAAuD;AAGvD,iCAAuC;AACvC,qDAAwD;AACxD,mDAA+C;AAG/C,IAAM,6BAA6B,GAAnC,MAAM,6BAA6B;CAAG,CAAA;AAAhC,6BAA6B;IADlC,IAAA,eAAM,EAAC,EAAE,CAAC;GACL,6BAA6B,CAAG;AAEtC,SAAS,oBAAoB,CAAC,CAAoB;IAChD,OAAO;QACL,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAElD,SAAgB,uBAAuB,CACrC,IAAmB,EACnB,QAAQ,GAAG,KAAK;IAEhB,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACvC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IAE3C,MAAM,MAAM,GAAkB;QAC5B,MAAM,EAAE,6BAA6B;QACrC,OAAO,EAAE,WAAW;QACpB,SAAS,EAAE;YACT,GAAG,aAAa;YAChB,IAAA,sBAAc,EACZ;gBACE,OAAO,EAAE,eAAe;gBACxB,MAAM,EAAE,CAAC,qCAAoB,CAAC;aAC/B,EACD,CAAC,CAAoB,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAClD;SACF;QACD,OAAO,EAAE,CAAC,eAAe,CAAC;KAC3B,CAAC;IAEF,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE;YACP,GAAG,WAAW;YACd,MAAM;YACN,8BAAa,CAAC,aAAa,CAAC;gBAC1B,OAAO,EAAE,CAAC,MAAM,CAAC;gBACjB,MAAM,EAAE,CAAC,eAAe,CAAC;gBACzB,UAAU,EAAE,CAAC,cAA8B,EAAE,EAAE,CAAC,cAAc;aAC/D,CAAC;SACH;QACD,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,8BAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KACzE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"aragami-init.js","sourceRoot":"","sources":["../../src/simple-user/aragami-init.ts"],"names":[],"mappings":";;;;;;;;AAmBA,0DAwCC;AA3DD,2CAAuD;AAGvD,iCAAuC;AACvC,qDAAwD;AACxD,mDAA+C;AAG/C,IAAM,6BAA6B,GAAnC,MAAM,6BAA6B;CAAG,CAAA;AAAhC,6BAA6B;IADlC,IAAA,eAAM,EAAC,EAAE,CAAC;GACL,6BAA6B,CAAG;AAEtC,SAAS,oBAAoB,CAAC,CAAoB;IAChD,OAAO;QACL,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAElD,SAAgB,uBAAuB,CACrC,IAAmB,EACnB,OAA+B;IAE/B,IAAI,OAAO,CAAC,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACvC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IAE3C,MAAM,MAAM,GAAkB;QAC5B,MAAM,EAAE,6BAA6B;QACrC,OAAO,EAAE,WAAW;QACpB,SAAS,EAAE;YACT,GAAG,aAAa;YAChB,IAAA,sBAAc,EACZ;gBACE,OAAO,EAAE,eAAe;gBACxB,MAAM,EAAE,CAAC,qCAAoB,CAAC;aAC/B,EACD,CAAC,CAAoB,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAClD;SACF;QACD,OAAO,EAAE,CAAC,eAAe,CAAC;KAC3B,CAAC;IAEF,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE;YACP,GAAG,WAAW;YACd,MAAM;YACN,8BAAa,CAAC,aAAa,CAAC;gBAC1B,OAAO,EAAE,CAAC,MAAM,CAAC;gBACjB,MAAM,EAAE,CAAC,eAAe,CAAC;gBACzB,UAAU,EAAE,CAAC,cAA8B,EAAE,EAAE,CAAC,cAAc;aAC/D,CAAC;SACH;QACD,OAAO,EAAE;YACP,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YACvB,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,8BAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACpD;KACF,CAAC;AACJ,CAAC"}

package/dist/simple-user/index.d.ts

@@ -4,3 +4,4 @@ export * from './simple-user/simple-user.service';
 export * from './resolver';
 export * from './simple-user.entity';
 export * from 'aragami';
+export * from 'nestjs-aragami';

package/dist/simple-user/index.js

@@ -20,4 +20,5 @@ __exportStar(require("./simple-user/simple-user.service"), exports);
 __exportStar(require("./resolver"), exports);
 __exportStar(require("./simple-user.entity"), exports);
 __exportStar(require("aragami"), exports);
+__exportStar(require("nestjs-aragami"), exports);
 //# sourceMappingURL=index.js.map

package/dist/simple-user/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/simple-user/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,uDAAqC;AACrC,oEAAkD;AAClD,6CAA2B;AAC3B,uDAAqC;AACrC,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/simple-user/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,uDAAqC;AACrC,oEAAkD;AAClD,6CAA2B;AAC3B,uDAAqC;AACrC,0CAAwB;AACxB,iDAA+B"}

package/dist/simple-user/options.d.ts

@@ -9,6 +9,7 @@ export interface SimpleUserExtraOptions {
     userConnectionName?: string;
     isGlobal?: boolean;
     reexportAragami?: boolean;
+    useExistingAragami?: boolean;
 }
 export interface SimpleUserOptions {
     allowAnonymousUsers?: boolean;

package/dist/simple-user/simple-user.module.js

@@ -30,7 +30,7 @@ let SimpleUserModule = class SimpleUserModule extends module_builder_1.Configura
     static register(options) {
         const base = super.register(options);
         patchUserCenterControllerMeWithDynamicModule(base);
-        return (0, aragami_init_1.attachAragamiWithBridge)(base, options.reexportAragami);
+        return (0, aragami_init_1.attachAragamiWithBridge)(base, options);
     }
     static registerAsync(options) {
         const base = super.registerAsync(options);
@@ -44,7 +44,7 @@ let SimpleUserModule = class SimpleUserModule extends module_builder_1.Configura
                 }
             }
         }
-        return (0, aragami_init_1.attachAragamiWithBridge)(base, options.reexportAragami);
+        return (0, aragami_init_1.attachAragamiWithBridge)(base, options);
     }
 };
 exports.SimpleUserModule = SimpleUserModule;

package/dist/simple-user/simple-user.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"simple-user.module.js","sourceRoot":"","sources":["../../src/simple-user/simple-user.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAKwB;AACxB,qDAG0B;AAC1B,iDAAyD;AACzD,2EAAsE;AACtE,qEAAgE;AAChE,2EAAsE;AACtE,+DAA2D;AAC3D,iFAA4E;AAC5E,yCAGoB;AACpB,qCAA0C;AAE1C,qDAAqE;AACrE,iCAAkE;AAUlE,MAAM,4CAA4C,GAAG,CACnD,MAAqB,EACrB,EAAE;IACF,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,EAAE,IAAI,CAC3C,CAAC,CAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,uBAAc,CAClC,CAAC;IACnB,IAAI,cAAc,EAAE,QAAQ,EAAE,CAAC;QAC7B,IAAA,sCAA2B,EAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,yCAAkB,EAAE,kCAAe,EAAE,6CAAoB,CAAC,CAAC;AAgBzE,IAAM,gBAAgB,GAAtB,MAAM,gBAAiB,SAAQ,wCAAuB;IAC3D,MAAM,CAAC,QAAQ,CAAC,OAAkC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,4CAA4C,CAAC,IAAI,CAAC,CAAC;QACnD,OAAO,IAAA,sCAAuB,EAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,OAAuC;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC1C,4CAA4C,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAE,CAA+B,EAAE,KAAK,IAAI,CAAC,CAAmB,CACxE,CAAC;YACF,IAAA,gCAAwB,EAAC,qCAAoB,EAAE,gBAAgB,CAAC,CAAC;YACjE,KAAK,MAAM,KAAK,IAAI,gBAAgB,EAAE,CAAC;gBACrC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;oBACrC,IAAA,uBAAe,EAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,IAAA,sCAAuB,EAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAChE,CAAC;CACF,CAAA;AAvBY,4CAAgB;2BAAhB,gBAAgB;IAd5B,IAAA,eAAM,EAAC;QACN,SAAS,EAAE;YACT,uCAAiB;YACjB,mCAAe;YACf,+BAAoB,CAAC,QAAQ;YAC7B,0CAA+B,CAAC,QAAQ;SACzC;QACD,OAAO,EAAE;YACP,uCAAiB;YACjB,+BAAoB,CAAC,QAAQ;YAC7B,0CAA+B,CAAC,QAAQ;SACzC;QACD,WAAW;KACZ,CAAC;GACW,gBAAgB,CAuB5B"}
+{"version":3,"file":"simple-user.module.js","sourceRoot":"","sources":["../../src/simple-user/simple-user.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAKwB;AACxB,qDAG0B;AAC1B,iDAAyD;AACzD,2EAAsE;AACtE,qEAAgE;AAChE,2EAAsE;AACtE,+DAA2D;AAC3D,iFAA4E;AAC5E,yCAGoB;AACpB,qCAA0C;AAE1C,qDAAqE;AACrE,iCAAkE;AAUlE,MAAM,4CAA4C,GAAG,CACnD,MAAqB,EACrB,EAAE;IACF,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,EAAE,IAAI,CAC3C,CAAC,CAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,uBAAc,CAClC,CAAC;IACnB,IAAI,cAAc,EAAE,QAAQ,EAAE,CAAC;QAC7B,IAAA,sCAA2B,EAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,yCAAkB,EAAE,kCAAe,EAAE,6CAAoB,CAAC,CAAC;AAgBzE,IAAM,gBAAgB,GAAtB,MAAM,gBAAiB,SAAQ,wCAAuB;IAC3D,MAAM,CAAC,QAAQ,CAAC,OAAkC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,4CAA4C,CAAC,IAAI,CAAC,CAAC;QACnD,OAAO,IAAA,sCAAuB,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,OAAuC;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC1C,4CAA4C,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAE,CAA+B,EAAE,KAAK,IAAI,CAAC,CAAmB,CACxE,CAAC;YACF,IAAA,gCAAwB,EAAC,qCAAoB,EAAE,gBAAgB,CAAC,CAAC;YACjE,KAAK,MAAM,KAAK,IAAI,gBAAgB,EAAE,CAAC;gBACrC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;oBACrC,IAAA,uBAAe,EAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,IAAA,sCAAuB,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAA;AAvBY,4CAAgB;2BAAhB,gBAAgB;IAd5B,IAAA,eAAM,EAAC;QACN,SAAS,EAAE;YACT,uCAAiB;YACjB,mCAAe;YACf,+BAAoB,CAAC,QAAQ;YAC7B,0CAA+B,CAAC,QAAQ;SACzC;QACD,OAAO,EAAE;YACP,uCAAiB;YACjB,+BAAoB,CAAC,QAAQ;YAC7B,0CAA+B,CAAC,QAAQ;SACzC;QACD,WAAW;KACZ,CAAC;GACW,gBAAgB,CAuB5B"}