V4.0

HOW_TO_UPGRADE_V4.md

@@ -2,54 +2,141 @@
 
 ---
 
-### 0. Update lemon-core Version
+## 0. Update lemon-core Version
 
 ```sh
-$ npm install lemon-core --save
+npm install lemon-core@^4.0.5 --save
 ```
 
-### 1. Upgrade Node.js Version
+## 1. Upgrade Node.js Version
 
-```sh
-$ nvm install 22
-$ nvm use 22
+```bash
+nvm install 22
+nvm use 22
 ```
 
 * Update `.nvmrc` file to `22`
 
-> #### Note
+```diff
+-  18.19.1
++  22.15.1
+```
+
+* Update `config.js` Node.js runtime version of your profile
+
+```diff
+         lemon: {
+            name: 'lemon-app',
+-            runtime: 'nodejs18.x', // Powered by the V8 JavaScript Engine (used in Chromium)
++            runtime: 'nodejs22.x',
+        },
+```
+
+* Update plugins in serverless.yml
+
+```diff
+  plugins:
+    - serverless-offline
+-   - serverless-offline
++   #WARN - failure in nodejs 22.x due to `serverless-offline` plugin @250627
++   # - serverless-offline
+    - serverless-aws-documentation
+    - serverless-prune-plugin
+    - serverless-plugin-log-retention
+```
+
+> ### Note
+>
+> If you **don’t modify the `plugins` section** in `serverless.yml`, you may encounter the following issues:
 >
 > When running `npm run deploy` in a Node.js 22, you may encounter the following error:
 >
-> ```
+> ```bash
 > Error [ERR_REQUIRE_ASYNC_MODULE]: require() cannot be used on an ESM graph with top-level await. Use import() instead. To see where the top-level await comes from, use --experimental-print-required-tla.
 > ```
 >
 > In this case:
+>
 > * Set only the Lambda runtime (Node.js version) to 22 in your `serverless.yml`.
 > * Execute the deployment command (`npm run deploy`) in a **Node.js 18 (nvm 18)**.
 
+## 2. Install `lemon-devkit`
+
+* Add as a `devDependency`:
+
+  ```bash
+  npm install --save-dev lemon-devkit
+  ```
+
+---
+
+### package.json Key Changes
+
+```diff
+ {
+   "engines": {
+-    "node": ">=14",
++    "node": ">=22"
+   },
+   "dependencies": {
+-    "lemon-core": "^3.x",
++     "lemon-core": "^4.x",
+   },
+   "devDependencies": {
++    "lemon-devkit": "^0.0.3",
+     "typescript": "^4.x",
+     "jest": "^29.x"
+   }
+ }
+```
+
+---
 
-### 2. AWS SDK: v2 to v3 Migration
+## 3. AWS SDK: v2 to v3 Migration
 
 1. **Credential Management**
 
    * Replace legacy `credentials` approach with `asyncCredentials()` from `lemon-core`.
+
    * Example:
 
      ```ts
      import { asyncCredentials } from 'lemon-core';
      const credentials = await asyncCredentials(PROFILE);
      ```
 
+   * **\[express.ts Updates]**
+
+    ```diff
+      //! dynamic loading credentials by profile. (search PROFILE -> NAME)
+      export const credentials = async (name?: string) => {
+          _log(NS, `credentials(${name})..`);
+          const NAME = name || ($engine.environ('NAME', '') as string);
+          const profile = $engine.environ('PROFILE', NAME) as string;
+    -      return $core.tools.credentials(profile);
+    +      return $core.tools.asyncCredentials(profile);
+      };
+    ```
+
+   * **\[Test Updates]**
+      * If you use `loadProfile(process)` to set up environment variables, move it **inside `it()` blocks** and `await` the call
+
+      ```ts
+      it('should initialize credentials', async () => {
+        const PROFILE = await loadProfile(process);
+        const credentials = await asyncCredentials(PROFILE);
+        expect(credentials).toBeDefined();
+      });
+      ```
+
 2. **Client Initialization**
 
    * Use `awsConfig($engine, region)` for initializing v3 clients.
    * Example:
 
      ```ts
      import { SQSClient } from '@aws-sdk/client-sqs';
-     import $engine from 'lemon-core';
+     import $engine, { awsConfig } from 'lemon-core';
 
      async function createSqsClient() {
        const region = 'ap-northeast-2';
@@ -59,51 +146,29 @@ $ nvm use 22
 
 ---
 
-### 3. Install `lemon-devkit`
+## 4. Update src/cores
 
-* Add as a `devDependency`:
-
-  ```sh
-  $ npm install --save-dev lemon-devkit
-  ```
-
----
+To update the src/cores directory in your project using the latest version from [lemon-templates-api](https://github.com/lemoncloud-io/lemon-templates-api), follow these steps:
 
-### package.json Key Changes
-
-```diff
- {
-   "engines": {
--    "node": ">=14",
-+    "node": ">=22"
-   },
-   "dependencies": {
--    "lemon-core": "^3.x",
-+     "lemon-core": "^4.x",
-   },
-   "devDependencies": {
-+    "lemon-devkit": "^0.0.3",
-     "typescript": "^4.x",
-     "jest": "^29.x"
-   }
- }
-```
+1. In your project: Delete the existing src/cores folder.
+2. From lemon-templates-api: Copy the entire src/cores directory.
+3. In your project: Paste the copied src/cores directory into the same path (src/cores).
 
 ---
 
-### At-a-Glance Checklist
+## At-a-Glance Checklist
 
 * [ ] **Upgrade lemon-core**
 * [ ] **Upgrade to Node.js 22**
-
   * Change `nvm` version, update `.nvmrc`
-  * When using Node.js 22, `npm run deploy` may fail due to module loading errors. 
-      For deployment, use Node.js 18 instead.
+  * Change node.js runtime version of your profile, update `config.js`
+  * Update plugins in serverless.yml
+* [ ] **Install lemon-devkit** (devDependency)
 * [ ] **Review AWS SDK v3 migration changes**
 
   * **Credentials**: Replace old `credentials` code with `asyncCredentials()`
   * **Client Initialization**: Use `awsConfig($engine, region)`
-* [ ] **Install lemon-devkit** (devDependency)
+* [ ] **Update src/cores**
 * [ ] **Review CI/CD environments**
 
   * Ensure Node.js 22 is set in `serverless.yml`, `Dockerfile`, etc.

README.md

@@ -2,7 +2,6 @@
 [![npm version](https://badge.fury.io/js/lemon-core.svg)](https://badge.fury.io/js/lemon-core)
 [![GitHub version](https://badge.fury.io/gh/lemoncloud-io%2Flemon-core.svg)](https://badge.fury.io/gh/lemoncloud-io%2Flemon-core)
 
-
 # lemon-core / V4
 
 Lemon Core Bootloader for Serverless Micro-Service
@@ -14,7 +13,6 @@ Lemon Core Bootloader for Serverless Micro-Service
 
     ![](assets/2019-11-26-23-43-47.png)
 
-
 ## Architecture
 
 Basic MicroService Architecutre with `API` + `SNS` + `SQS`.
@@ -25,7 +23,6 @@ Basic MicroService Architecutre with `API` + `SNS` + `SQS`.
 
     ![](assets/lemon-core-ms-arch.png)
 
-
 ### Protocol Service
 
 - support inter-communication between micro services
@@ -51,30 +48,31 @@ const queueId = await service.enqueue(protocol, callback, 30);
 1. install `lemon-core` module (>= 2.1.0).
 
 ```sh
-$ npm install lemon-core --save
+npm install lemon-core --save
 ```
 
 TODO - TBD in detail.
 
-
-
 ## Contribution
 
-Plz, request PR. 
+Plz, request PR.
 
 See [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)
 
-
 ## LICENSE
 
 [MIT](LICENSE) - (C) 2019 LemonCloud Co Ltd. - All Rights Reserved.
 
-
 ----------------
-# VERSION INFO #
+
+## VERSION INFO
 
 | Version   | Description
 |--         |--
+| 4.0.7     | optimized `verifyJWT()` w/ more detail error.
+| 4.0.6     | optimized `loadProfile()` as sync call.
+| 4.0.5     | improve `$protocol` w/ `lambda` invoke.
+| 4.0.0     | optimized with `nodejs22`.
 | 3.2.16    | improve `ALBHandler` to support `elb` event.
 | 3.2.15    | improve `NextContext` to support `referer` and `origin` header.
 | 3.2.13    | improve `createSigV4Proxy()` to support the sig-v4 request to AWS.
@@ -134,4 +132,3 @@ See [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)
 | 2.0.0     | improve `lemon-engine`, and support `typescript` fully.
 | 1.2.15    | improve `doReportError` with error message
 | 1.2.12    | support `doReportMetric()` for saving metric data.
-

data/mocks/mock.error-json.json

@@ -0,0 +1,10 @@
+{
+    "!": "error case with JSON string",
+    "param": {
+        "method": "GET",
+        "endpoint": "https://api.lemoncloud.io/hello/test",
+        "id": "error-json"
+    },
+    "data": null,
+    "error": "{\"message\":\"JSON error\",\"code\":500}"
+}

data/mocks/mock.error-object.json

@@ -0,0 +1,13 @@
+{
+    "!": "error case with error object",
+    "param": {
+        "method": "GET",
+        "endpoint": "https://api.lemoncloud.io/hello/test",
+        "id": "error-object"
+    },
+    "data": null,
+    "error": {
+        "message": "Error object",
+        "statusCode": 400
+    }
+}

data/mocks/mock.error-string.json

@@ -0,0 +1,10 @@
+{
+    "!": "error case with plain string",
+    "param": {
+        "method": "GET",
+        "endpoint": "https://api.lemoncloud.io/hello/test",
+        "id": "error-string"
+    },
+    "data": null,
+    "error": "Plain string error message"
+}