p-sw/nestlogged
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Delete page "Dive-Deeper"

p-sw 2025-03-26 22:29:07 +00:00
parent a5514ecde2
commit 9ea75d324b
1 changed files with 0 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
Dive-Deeper.md

@ -1,144 +0,0 @@
_In this page, the deeper understand of decorator will be handled._
# How basic decorators works?
In `nestlogged` package, there are three types of decorator.
1. Class Decorator (`LoggedInjectable`, `LoggedController`)
2. Method Decorator (`LoggedFunction`, `LoggedRoute`, `ShouldScoped`)
3. Parameter Decorator (`LoggedParam`, `InjectLogger`, `ScopeKey`)
There is a [good documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for this in typescriptlang.org.
# How does the logging decorator actually works?
In this section, the internal logic of the logging decorators are explained.
The main logic of this package is placed inside of method decorators.
But before explaining about real logging decorators (method decorators), you have to understand the parameter decorator.
## Metadata Reflection
If you open the package.json file and see what is the dependency, there is a package `reflect-meatadata`.
It is used by nestjs, but also nestlogged uses it very actively.
All `LoggedParam`, `InjectLogger`, `ScopeKey` is powered by `reflect-metadata` package.
It provides **Metadata Reflection API**, which gives functionality to add additional metadatas to a class.
It is pretty useful for saving the metadata in a decorator, and then use it in another decorator.
## Parameter Decorator Implementation Explained
If you look at `src/reflected.ts` file, there is implementations for parameter decorators.
What these decorators have in common is they store metadatas using metadata reflection api.
### `InjectLogger`
Let's look at `InjectLogger` function.
It's pretty small and simple.
What it does is putting the information of parameter to it's target.
When we put the `InjectLogger` to the parameter, the _the prototype of the class for an instance member_ (`target: any`), _The name of the member_ (`propertyKey: string | symbol`), and _The ordinal index of the parameter in the function’s parameter list_ (`parameterIndex: number`) are given to the `InjectLogger` function as the argument.
And call `Reflect.defineMetadata` to save the `parameterIndex` as `ScopedLogger` injection index.
The key (`scopedLogger`) when used to define metadata is defined at the almost top of the file, right bottom to the interfaces, as the constant symbol.
It will be used in both `LoggedFunction` and `LoggedRoute` which will explained later section.
### `LoggedParam`
At the right bottom to the `InjectLogger`, there is a function definition for `LoggedParam`.
It takes parameter name (`name: string`), and options for include or exclude path in object (`options?: {includePath?: ..., excludePath?: ...}`).
It returns parameter decorator function, which has same parameters with InjectLogger.
Since the decorator function is **returned after call**, it should be called to be applied.
```ts
function a(
@InjectLogger logger: ScopedLogger,
@LoggedParam param: string // it's illegal, error
@LoggedParam('param') param: string // Now it returns decorator function to be applied.
) {}
```
`LoggedParam` decorator can be used multiple time in one function.
Because of that, first thing decorator does is getting the existing decorator data.
Right after that, push a new data, then redefine the metadata.
### `ScopeKey`
It is simillar to the `LoggedParam` decorator implementation.
The only different thing is, `ScopeKey` sorts its metadata array by priority.
### `ShouldScoped`
Although `ShouldScoped` is a method decorator, it only defined metadata like `InjectLogger`, and it's very simple.
It just set `forceScopeKey` to true in method metadata.
Getting the metadata value which is not defined is same as undefined, so the default value is falsy.
## Method Decorator Implementation Explained
Now, look at `src/logged.ts`.
This file contains `LoggedFunction`, `LoggedRoute`, `LoggedInjectable`, `LoggedController`.
Most basic implementation is `LoggedFunction`.
Let's look inside of that.
`LoggedFunction` is a method decorator itself, and has three parameters.
1. _the prototype of the class for an instance member_ (`_target: any`) (prototype of the class that owns the method)
2. _The name of the member_ (`key: string`)
3. _The Property Descriptor for the member_ (`descriptor: TypedPropertyDescriptor<(...args: F) => Promise<R>>`)
First of all, it calls `loggerInit` function with _target.
The `loggerInit` function is at the top of file, taking _target: any as the only parameter.
When `loggerInit` is called, if _target (prototype) has no logger, make new logger with their name, and define it as its property.
Then, after loggerInit finished, the LoggedFunction takes initialized _target.logger, and descriptor.value as constant fn.
descriptor.value is the function that LoggedFunction decorator will be applied.
It is ensured to be function. if it is not a function, logger will warn about this, and stop applying the decorator.
The next step is taking all the metadata sets out. It will be explained later, so just keep that in mind.
Next four constants are just getting data of `InjectLogger`, `LoggedParam`, `ScopeKey`, `ShouldScoped` decorators.
and then it creates overrideFunction constant with overrideBuild.
What overrideBuild makes is just a function that has same parameter and return type with original descriptor.value.
But the difference is - it takes all parameter data, original function, logger, etc.
It is really important to understand the inside of the overrideBuild function.
It makes new ScopedLogger, print parameter logs, and injects logger, log return response.
If it catches any error while running original function, it catches and logs with injected logger, and then throws it back.
It takes input, works, and return output same as original function, but internally logging things.
After building core function that will be override on top of original function, it overrides the function.
_target[key] overriding is for class decorators like `LoggedInjectable` or `LoggedController`,
and descriptor.value overriding is for direct decorators like `LoggedRoute` or `LoggedFunction`.
`LoggedRoute` and `LoggedFunction` has almost same implementation, but `LoggedRoute` takes `path` and `method` metadata that is defined by nestjs.
`@nestjs/common` internally uses reflect-metadata, and saves path and method as metadata.
So it gets the metadata from "path" and "method" key, and then use it inside of overrideBuild to build a log.
The logging decorator lastly does save all the metadata previously got.
This is required, because when it overrides function, the metadata which was originally included in function is wiped by new function.
This problem is really serious, because it wipes the path, method, guards, everything it has.
Without redefining step, the function will not behave like you expected.
NestJS will not detect the method as the request handler, or guard does not work, etc.
So, redefining every single original metadata is really important step.