feat: add custom transformer docs

[attilah]

Description of changes:

Adding a paragraph about custom GraphQL transformer registration.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[hisham]

If it helps, I just released a simple @lowercase graphql transformer to convert strings to lower case before saving to dynamodb. Should serve as a good "hello world" type example of a standalone graphql transformer but does something actually useful:

https://github.com/hisham/graphql-lowercase-transformer
https://www.npmjs.com/package/graphql-lowercase-transformer

DynamoDB does not support case insensitive string search, so this transformer forces searchable strings to be in lowercase in the backend (see aws-amplify/amplify-cli#526).

[hisham]

I also had the following feedback when building this transformer. I followed your documentation plus the VersionedModelTransformer as my example but ran into the following issues:

• Custom transformer libs should have a 'default' exported class, see the imported.default code at Custom Transformers base support amplify-cli#1396 (comment). If the lib did not have a default export then you get an unhelpful error message which is something like "TypeError: Can't call 'call' on undefined'. Had to spend some time going through amplify code to see where this error was coming from.
• I could not get my transformer to work if it called any class methods. I would get errors such as 'assertModelDirective' is not a method. All functions had to be property arrow functions. See my code https://github.com/hisham/graphql-lowercase-transformer/blob/master/src/LowercaseTransformer.ts. It's probably some kind of ts/js/es5 nuance but I wasn't able to resolve. So I converted all my private methods to private property arrow functions. It seems @ambientlight mentions something like this with this being undefined: Custom Transformers base support amplify-cli#1396 (comment)

[hisham]

Also graphql transformers to be looked up via npm registry need to be installed globally or else you'll get Cannot find module error:

i.e. npm install -g lowercase-graphql-transformer

This wasn't immediately clear to me.

[ambientlight]

I could not get my transformer to work if it called any class methods. I would get errors such as 'assertModelDirective' is not a method. All functions had to be property arrow functions. See my code https://github.com/hisham/graphql-lowercase-transformer/blob/master/src/LowercaseTransformer.ts. It's probably some kind of ts/js/es5 nuance but I wasn't able to resolve. So I converted all my private methods to private property arrow functions

@hisham: same thing for me, will be great to have these docs mentioning this.
@attilah: I am wondering, since the deployment target is node, are we really required ts to emit es5?

Also graphql transformers to be looked up via npm registry need to be installed globally or else you'll get Cannot find module error

@hisham: hm strange, you are using globally installed amplify right? I wonder if this changes if you use amplify as local project dependency

Can you also run:
$ node module.paths

to check the paths that node looks up when resolving modules.

[hisham]

@ambientlight yes I am using globally installed amplify. If amplify was installed locally I think it would look it it up locally. Looks like @attilah recently did a PR offering option for both globally installed and locally installed custom transformer packages, see aws-amplify/amplify-cli#2814

[attilah]

@hisham @ambientlight Yes, I changed the loading a bit, it has issues about location and initialization as you also faced, I even enabled the pojo scenario, a single object with a method on it and a required properties to work. I've more ideas around it that will come in future changes.

[mauerbac]

Outdated. Closing