Typescript and decorator ... should we provide a higher order function ?

[flochaz]

Decorator being limited to class level element it might not be that intuitive to use knowing that most lambda handlers are written not in OOP but more functional programming.

So just wondering how to present that in term of doc ...

import {Metrics, MetricUnits} from '@aws-lambda-powertools/metrics';
import { Callback, Context } from 'aws-lambda';

const metrics = new Metrics({namespace:"CDKExample", service:"withDecorator"});

export class MyFunctionWithDecorator {

  @metrics.logMetrics({captureColdStartMetric: true})
  public handler(_event: any, _context: Context, _callback: Callback<any>): void | Promise<any> {
    metrics.addMetric('test-metric', MetricUnits.Count, 10);
    if(_event.throw) {
      throw new Error('Test error');
    }
  }
}

export const handlerClass = new MyFunctionWithDecorator()
export const handler = handlerClass.handler

vs.

import {Metrics, MetricUnits} from '@aws-lambda-powertools/metrics';
import { Context } from 'aws-lambda';

const metrics = new Metrics({namespace: "CDKExample", service: "MyFunction"}); 

export const handler = async (_event: any, _context: Context) => {
  metrics.addMetric('test-metric', MetricUnits.Count, 10);
  metrics.purgeStoredMetrics();
};

vs.

Another way would be to go with a wrapper like they do in aws-embedded-metrics-node :

const { metricScope } = require("aws-embedded-metrics");

const myFunc = metricScope(metrics =>
  async () => {
    // ...
  });

exports.handler = myFunc;

Bottom line : Should we propose a wrapper function for each module ?

[dreamorosi]

Agree with you in that most handlers are written as functions and that decorators needing classes make things a bit awkward. It's also clear that using decorators lead to a better DX since there's much less boilerplate (since we do things behind the scenes in the decorator function).

In terms of documentation I think that we could limit examples written as OOP only to features that require a decorator and also provide a way of achieving the same without decorator (when possible).

All other features that don't involve a decorator could use regular function handlers for the examples. This should clarify that OOP is not a requirement to use Powertools.

I guess the question here is also how much (if any) we want to be opinionated and suggest/recommend one over the other.

[dreamorosi]

After seeing the third option of the wrapper, I really think we should provide one as an alternative for decorators. If we don't, in addition to what I mentioned above, Customers who want to use Javascript (without TS) won't have an alternative for decorators at all.

[flochaz]

Another options would be a set of middlewares :

const handler = powertools((event, context) => {
  // YOUR LOGIC
}).use(
  metricMiddleware({})
)

or we propose at launch a middy one ...

[dreamorosi]

This looks promising, especially if you want to use two or more decorators on the same function:

const handler = powertools((event, context) => {
  // YOUR LOGIC
})
  .use(metricMiddleware({}))
  .use(tracerMiddleware({}))
  .use(loggerMiddleware({}))

vs

const handler = captureLambdaHanlder(injectLambdaContext(logMetrics((event, context) => {
  // YOUR LOGIC
}))))

[flochaz]

But should we go with our own engine or use middy one ? (@dazn was doing middy one ...)

[dreamorosi]

I'm not familiar with middy but I've heard it being mentioned quite a bit since the beginning of this project and additionally I understand that middy might have an ecosystem of middlewares which means Customers might already be using it. Maybe @saragerion can provide more context here

[flochaz]

For documentation, I propose to have a 3 tabs view for each part . Example:

And have that for each feature (in my case for metrics it would be coldstartmetric, raiseOnEmptymetric, addmetadata etc.)

[ijemmy]

I'm in favor of those 3 options.

How much development + maintenance effort do we need to support Middy?

[flochaz]

Not much, the api is straightforward and well documented. The only thing is we will have to follow carefully their updates.

[saragerion]

Personally speaking, my vote goes to create a number of configurable middy middleware in each utility that customers can use to wrap their handlers:
https://middy.js.org/#configurable-middlewares

To add some historical context about decorators vs middleware: when I started working on the libraries my initial plan was to not have decorators and just go for middy middleware directly, as the middy library is well maintained and pretty much the most used one in the node.js ecosystem. No need to reinvent the wheel in my opinion.
The only reason why I gave priority to the decorators pattern and implemented them first is that I talked with @heitorlessa and we think that developers who already use the python library and want to use the node.js one will have the expectation that a similar feature is ported.
So essentially I implemented decorators for feature parity with the python library and to make it easier for python developers to start using the node.js library too.

[saragerion]

Personally speaking, I think we should keep decorators for parity with the python library, but highlight the middleware pattern as default way to go

[flochaz]

Sounds good to me

[flochaz]

I think we should have middleware for beta ...

[saragerion]

Agreed. It shouldn't take much, I can work on the logger middleware today

[dreamorosi]

Thank you for the context Sara, I'm in favor of Middy-based middlewares and agree that this pattern should be highlighted as the default way to go.

[saragerion]

The decision is that we leave it as it is now, and we will let customers share their feedback via issues if they have any.