aws-cloudformation / aws-cloudformation/cloudformation-cli-typescript-plugin

Migrate away from class-transfomer

オープン
#100 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
TypeScript
スター
46
フォーク
18
PR マージ指標
30日以内にマージされた PR はありません

説明

This is a rethought version of my previous ticket https://github.com/aws-cloudformation/cloudformation-cli-typescript-plugin/issues/68

To resummarize the issues with `class-transformer`:

* The serialization breaks down in the face of unsupported CloudFormation JSON Schema Features, and increases complexity since JSON Schema features must be manually mapped to the Class Transformer equivalent.
* It ties the implementation to TypeScript's decorators which are soon to be completely deprecated and redesigned entirely, and results in a data model that might be foreign to a lot of JavaScript developers today (outside angular and nestjs)
* Because of the above, it prevents JavaScript from working (though I'd personally always encourage TS over JS) (https://github.com/aws-cloudformation/cloudformation-cli-typescript-plugin/issues/8)
* ~The project isn't also super alive right now: https://github.com/typestack/class-transformer/issues/1272~ Possibly no longer as valid, it looks like the projects might be getting new maintainers.

The updated proposal proposes swapping `class-transformer` with three components:

* The package [camelcase-keys](https://www.npmjs.com/package/camelcase-keys) to handle the CloudFormation-to-JS object key camelcasing.
* The package [AJV](https://www.npmjs.com/package/ajv) to handle validating the incoming event properties, provide friendly(er) error messages, as well as [automatic type conversion](https://ajv.js.org/coercion.html)
* The package [json-schema-to-typescript](https://www.npmjs.com/package/json-schema-to-typescript) to handle consuming the resource definition and outputting type information for a richer experience.

While a very large change, it would uncouple this plugin from TypeScript and an unmaintained library while hopefully simplifying the Dev UX of developing a resource in typescript.

For example, a simple handler like the template default would become (example greatly appreviated):

```typescript
// handlers.ts
import { Resource, TypeConfiguration } from "./.generated/models";
import { createResource, ProgressEvent, exceptions } from '@amazon-web-services-cloudformation/cloudformation-cli-typescript-lib';

const { entrypoint, testEntrypoint } = createResource({
typeName: Resource.TypeName,
schema: Resource.Schema,
// Type information for all the below is automatically infered
async create({ session, properties, request, logger, typeConfiguration }) {
// Example:
try {
const { apiKey } = typeConfiguration;
const response = await fetch(`https://api.someservice.com`, {
method: 'POST',
headers: { 'x-api-key': apiKey },
body: { ...properties },
});
const { id } = await response.json();
properties.id = id;
// else handle error
} catch(err) {
logger.log(err);
// exceptions module lets CloudFormation know the type of failure that occurred
throw new exceptions.InternalFailure(err.message);
// this can also be done by returning a failed progress event
// return ProgressEvent.failed(HandlerErrorCode.InternalFailure, err.message);
}
return properties;
},
/* more handlers.... */
async list({ properties, typeConfiguration }) {
/* ...some list code... */
// Just return a plain array of models, validate via typescript & ajv
return [/* list of plain old javascript models */];
},
});

export { entrypoint, testEntrypoint };

```

This also externalizes a lot of concerns unnecessary to the user code, infers a lot more of type information automatically, and makes developing resource types much less mentally onerous allowing developers to focus on business logic.

It would require more work with the SDK and generated code however.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

まず Issue 68 と提案されている handlers.ts の例を確認し、その後、Issue で変更が必要になるとされている SDK と生成コードを調査します。camelcase-keys、AJV、json-schema-to-typescript を評価する前に、現在の class-transformer 統合を追跡し、影響を受けるエントリーポイントを特定します。完了条件は、plugin が class-transformer に依存しなくなり、提案されている JavaScript および TypeScript のワークフローをサポートし、必要な SDK と生成コードの変更を含むことです。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
javascript, nodejs, typescript
領域
developer-experience, tooling
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
説明が足りない
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。