Improve lambda documentation

[mooreds]

Improve lambda documentation

Description

Some more nuance about the lambda functionality would benefit from documentation:

• Only one lambda of one will run even if multiple lambdas are added
• console.log (or the other calls to console are not the standard console.log('something', 'something else', some more strings'); but rather they can only take one argument: console.info('something' + 'something else');
• only the populate / reconcile function is allowed on the top level of a lambda, so if someone wants to write a function, they’ll have to stick it into that “main” function

For example:

function populate(jwt, user, registration) {
  var object2String = function(obj) {
    if (typeof obj === 'number' || typeof obj === 'bigint' || typeof obj === 'boolean') return ('' + obj);
    if (typeof obj === 'string') return ('"' + obj.replace('"', '\\"') + '"');
    if (typeof obj === 'function') return ('[function]');
    if (obj === null) return 'null';
    if (obj === undefined) return 'undefined';
    if (Array.isArray(obj)) return '[' + obj.map(function(elem) { return  object2String(elem); }).join(', ') + ']';
    return '{ ' + Object.keys(obj).map(function (key) { return '"' + key + '": ' + object2String(obj[key]); }).join(', ') + ' }';
  };
  console.info('Lambda called');
  console.info('jwt:' + object2String(jwt));
  console.info('user:' + object2String(user));
  console.info('registration' + object2String(registration));
  if (user.fullName) jwt.name = user.fullName;
}

[mooreds]

See also #571

[robotdan]

Can we clarify the items in the description?

Only one lambda of one will run even if multiple lambdas are added

You cannot configure more than one lambda for any particular use. What does 'added' mean?

If this applies to assignment, each lambda does have an "assigning lambda" section that describes what to do with the lambda after you create one. ( https://fusionauth.io/docs/v1/tech/lambdas/jwt-populate ) Perhaps this section needs to be enhanced.

console.log...

The console options are documented here https://fusionauth.io/docs/v1/tech/lambdas/#console it does indicate this is provided by FusionAuth. We could make this clearer that this is not the same console API provided in most browsers. The primary reason for this is that the console object is not part of the ECMAScript standard and not provided in Nashorn. However even once we ditch Nashorn, we may keep this because we use this to write event logs.

We could also explore making ours confirm to the entire Console API spec.

https://console.spec.whatwg.org/
https://developer.mozilla.org/en-US/docs/Web/API/console

only the populate / reconcile function is allowed on the top level of a lambda, so if someone wants to write a function, they’ll have to stick it into that “main” function

Not sure if I understand this one. If I understand correct, writing a function inside of the lambda, but outside if the documented lambda body it doesn't work?

function: foo() {
   return "bar";
}

function populate(jwt, user, registration) {

  var s = foo(); // doesn't work?
}

I believe this to be correct. We could clarify that additionally defined functions in the lambda body are not bound and cannot be called from within our lambda. This may change once we ditch Nashorn.

[gordody]

only one lambda runs but multiple can be "added"

There is a plus button to add lambdas, it should grey out if one is already there

console.log

It was not immediately clear from the intro doc that there is more or that this console is not the same as the "normal".

only one function in the lambda

I haven't tried the object notation above, I just tried to declare another function outside of populate and that failed. I didn't see any other options in the docs, maybe I should maybe looked harder...

[robotdan]

Thanks for the clarification @gordody .

[mooreds]

Closing because I added these in in PR #1127.