From c6f914651cbfb55e1a248f7e895e7d2f7826a1fa Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Tue, 8 Jul 2025 23:18:28 +0200 Subject: [PATCH] docs(idempotency): simplify snippets --- docs/features/idempotency.md | 14 +++++------ .../advancedBringYourOwnPersistenceLayer.ts | 6 +++-- ...vancedBringYourOwnPersistenceLayerUsage.ts | 18 ++++++------- .../idempotency/customKeyPrefixDecorator.ts | 16 +++++------- .../idempotency/customKeyPrefixFnWrapper.ts | 16 +++++------- .../idempotency/customKeyPrefixMiddleware.ts | 16 +++++------- .../idempotency/customizePersistenceLayer.ts | 16 +++++------- .../idempotency/makeHandlerIdempotent.ts | 16 +++++------- .../idempotency/makeIdempotentAnyFunction.ts | 21 +++++++--------- .../idempotency/makeIdempotentBase.ts | 16 +++++------- .../idempotency/makeIdempotentJmes.ts | 22 +++++++--------- .../makeIdempotentLambdaContext.ts | 19 ++++++-------- .../idempotency/workingWithCompositeKey.ts | 16 +++++------- .../idempotency/workingWithCustomClient.ts | 16 +++++------- .../idempotency/workingWithCustomConfig.ts | 16 +++++------- .../idempotency/workingWithExceptions.ts | 4 +-- .../workingWithIdempotencyRequiredKey.ts | 16 +++++------- .../idempotency/workingWithLocalCache.ts | 16 +++++------- .../workingWithPayloadValidation.ts | 25 ++++++++----------- .../workingWithRecordExpiration.ts | 16 +++++------- .../idempotency/workingWithResponseHook.ts | 16 +++++------- 21 files changed, 135 insertions(+), 202 deletions(-) diff --git a/docs/features/idempotency.md b/docs/features/idempotency.md index 811a409672..9e107738e4 100644 --- a/docs/features/idempotency.md +++ b/docs/features/idempotency.md @@ -144,7 +144,7 @@ You can quickly start by initializing the `DynamoDBPersistenceLayer` class and u === "index.ts" - ```typescript hl_lines="2-3 21 35-38" + ```typescript hl_lines="2-3 21 31-33" --8<-- "examples/snippets/idempotency/makeIdempotentBase.ts" ``` @@ -206,7 +206,7 @@ Similar to the `makeIdempotent` function wrapper, you can quickly make your Lamb === "index.ts" - ```typescript hl_lines="22 36-40" + ```typescript hl_lines="22 33-35" --8<-- "examples/snippets/idempotency/makeHandlerIdempotent.ts" ``` @@ -237,7 +237,7 @@ Imagine the function executes successfully, but the client never receives the re === "index.ts" - ```typescript hl_lines="4 27 49" + ```typescript hl_lines="4 27" --8<-- "examples/snippets/idempotency/makeIdempotentJmes.ts" ``` @@ -304,7 +304,7 @@ If an error is thrown _outside_ the scope of the decorated function and after yo === "Handling exceptions" - ```typescript hl_lines="39-40 47-48" + ```typescript --8<-- "examples/snippets/idempotency/workingWithExceptions.ts" ``` @@ -774,7 +774,7 @@ You can use the `keyPrefix` parameter in any of the idempotency configurations t === "Using a custom prefix with function wrapper" - ```typescript hl_lines="25" + ```typescript hl_lines="21" --8<-- "examples/snippets/idempotency/customKeyPrefixFnWrapper.ts" ``` @@ -864,7 +864,7 @@ Below an example implementation of a custom persistence layer backed by a generi === "CustomPersistenceLayer" - ```typescript hl_lines="9 19 28 35 52 95" + ```typescript hl_lines="9 19 28 35 54 97" --8<-- "examples/snippets/idempotency/advancedBringYourOwnPersistenceLayer.ts" ``` @@ -891,7 +891,7 @@ You can set up a `responseHook` in the `IdempotentConfig` class to manipulate th === "Using an Idempotent Response Hook" - ```typescript hl_lines="16 19 27 56" + ```typescript hl_lines="16 19 27" --8<-- "examples/snippets/idempotency/workingWithResponseHook.ts" ``` diff --git a/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayer.ts b/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayer.ts index f13527ce63..025ebdf884 100644 --- a/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayer.ts +++ b/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayer.ts @@ -44,8 +44,10 @@ class CustomPersistenceLayer extends BasePersistenceLayer { return new IdempotencyRecord({ ...(item as unknown as IdempotencyRecordOptions), }); - } catch (_error) { - throw new IdempotencyItemNotFoundError(); + } catch (error) { + throw new IdempotencyItemNotFoundError('Item not found in store', { + cause: error, + }); } } diff --git a/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayerUsage.ts b/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayerUsage.ts index 6164d8b421..ab0edb8196 100644 --- a/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayerUsage.ts +++ b/examples/snippets/idempotency/advancedBringYourOwnPersistenceLayerUsage.ts @@ -38,16 +38,12 @@ export const handler = async ( ): Promise => { config.registerLambdaContext(context); - try { - const transactionId = randomUUID(); - const payment = await createSubscriptionPayment(transactionId, event); + const transactionId = randomUUID(); + const payment = await createSubscriptionPayment(transactionId, event); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }; diff --git a/examples/snippets/idempotency/customKeyPrefixDecorator.ts b/examples/snippets/idempotency/customKeyPrefixDecorator.ts index 4e7ecf72fc..e83a64331a 100644 --- a/examples/snippets/idempotency/customKeyPrefixDecorator.ts +++ b/examples/snippets/idempotency/customKeyPrefixDecorator.ts @@ -13,17 +13,13 @@ class Lambda { keyPrefix: 'createSubscriptionPayment', }) async handler(_event: unknown, _context: Context) { - try { - // ... create payment + // ... create payment - return { - paymentId: randomUUID(), - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: randomUUID(), + message: 'success', + statusCode: 200, + }; } } diff --git a/examples/snippets/idempotency/customKeyPrefixFnWrapper.ts b/examples/snippets/idempotency/customKeyPrefixFnWrapper.ts index bc3a9b083d..75bbea4f99 100644 --- a/examples/snippets/idempotency/customKeyPrefixFnWrapper.ts +++ b/examples/snippets/idempotency/customKeyPrefixFnWrapper.ts @@ -8,17 +8,13 @@ const persistenceStore = new DynamoDBPersistenceLayer({ export const handler = makeIdempotent( async () => { - try { - // ... create payment + // ... create payment - return { - paymentId: randomUUID(), - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: randomUUID(), + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/customKeyPrefixMiddleware.ts b/examples/snippets/idempotency/customKeyPrefixMiddleware.ts index 00bf3e8595..f93a2df657 100644 --- a/examples/snippets/idempotency/customKeyPrefixMiddleware.ts +++ b/examples/snippets/idempotency/customKeyPrefixMiddleware.ts @@ -15,15 +15,11 @@ export const handler = middy() }) ) .handler(async () => { - try { - // ... create payment + // ... create payment - return { - paymentId: randomUUID(), - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: randomUUID(), + message: 'success', + statusCode: 200, + }; }); diff --git a/examples/snippets/idempotency/customizePersistenceLayer.ts b/examples/snippets/idempotency/customizePersistenceLayer.ts index 11438d37dc..effbc7f06a 100644 --- a/examples/snippets/idempotency/customizePersistenceLayer.ts +++ b/examples/snippets/idempotency/customizePersistenceLayer.ts @@ -16,17 +16,13 @@ const persistenceStore = new DynamoDBPersistenceLayer({ export const handler = middy( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '1234567890', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '1234567890', + message: 'success', + statusCode: 200, + }; } ).use( makeHandlerIdempotent({ diff --git a/examples/snippets/idempotency/makeHandlerIdempotent.ts b/examples/snippets/idempotency/makeHandlerIdempotent.ts index dcbcb21569..07dea5402b 100644 --- a/examples/snippets/idempotency/makeHandlerIdempotent.ts +++ b/examples/snippets/idempotency/makeHandlerIdempotent.ts @@ -21,17 +21,13 @@ const createSubscriptionPayment = async ( export const handler = middy( async (event: Request, _context: Context): Promise => { - try { - const payment = await createSubscriptionPayment(event); + const payment = await createSubscriptionPayment(event); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; } ).use( makeHandlerIdempotent({ diff --git a/examples/snippets/idempotency/makeIdempotentAnyFunction.ts b/examples/snippets/idempotency/makeIdempotentAnyFunction.ts index 659db0e798..a54304c9bd 100644 --- a/examples/snippets/idempotency/makeIdempotentAnyFunction.ts +++ b/examples/snippets/idempotency/makeIdempotentAnyFunction.ts @@ -42,18 +42,15 @@ export const handler = async ( context: Context ): Promise => { config.registerLambdaContext(context); - try { - const transactionId = randomUUID(); - const payment = await createSubscriptionPayment(transactionId, event); - await reportSubscriptionMetrics(transactionId, event.user); + const transactionId = randomUUID(); + const payment = await createSubscriptionPayment(transactionId, event); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + await reportSubscriptionMetrics(transactionId, event.user); + + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }; diff --git a/examples/snippets/idempotency/makeIdempotentBase.ts b/examples/snippets/idempotency/makeIdempotentBase.ts index c8e17f1022..7a40118b9f 100644 --- a/examples/snippets/idempotency/makeIdempotentBase.ts +++ b/examples/snippets/idempotency/makeIdempotentBase.ts @@ -20,17 +20,13 @@ const createSubscriptionPayment = async ( export const handler = makeIdempotent( async (event: Request, _context: Context): Promise => { - try { - const payment = await createSubscriptionPayment(event); + const payment = await createSubscriptionPayment(event); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/makeIdempotentJmes.ts b/examples/snippets/idempotency/makeIdempotentJmes.ts index ddf66af693..c3a569cfe7 100644 --- a/examples/snippets/idempotency/makeIdempotentJmes.ts +++ b/examples/snippets/idempotency/makeIdempotentJmes.ts @@ -29,20 +29,16 @@ const config = new IdempotencyConfig({ export const handler = makeIdempotent( async (event: Request, _context: Context): Promise => { - try { - const payment = await createSubscriptionPayment( - event.user, - event.productId - ); + const payment = await createSubscriptionPayment( + event.user, + event.productId + ); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/makeIdempotentLambdaContext.ts b/examples/snippets/idempotency/makeIdempotentLambdaContext.ts index 0e7c9d472f..a2de43f6a8 100644 --- a/examples/snippets/idempotency/makeIdempotentLambdaContext.ts +++ b/examples/snippets/idempotency/makeIdempotentLambdaContext.ts @@ -36,16 +36,13 @@ export const handler = async ( ): Promise => { // Register the Lambda context to the IdempotencyConfig instance config.registerLambdaContext(context); - try { - const transactionId = randomUUID(); - const payment = await createSubscriptionPayment(transactionId, event); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + const transactionId = randomUUID(); + const payment = await createSubscriptionPayment(transactionId, event); + + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }; diff --git a/examples/snippets/idempotency/workingWithCompositeKey.ts b/examples/snippets/idempotency/workingWithCompositeKey.ts index 233ba92179..1a2242dc54 100644 --- a/examples/snippets/idempotency/workingWithCompositeKey.ts +++ b/examples/snippets/idempotency/workingWithCompositeKey.ts @@ -11,17 +11,13 @@ const persistenceStore = new DynamoDBPersistenceLayer({ export const handler = middy( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '12345', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '12345', + message: 'success', + statusCode: 200, + }; } ).use( makeHandlerIdempotent({ diff --git a/examples/snippets/idempotency/workingWithCustomClient.ts b/examples/snippets/idempotency/workingWithCustomClient.ts index ab73d1594c..5e7fe78394 100644 --- a/examples/snippets/idempotency/workingWithCustomClient.ts +++ b/examples/snippets/idempotency/workingWithCustomClient.ts @@ -14,17 +14,13 @@ const persistenceStore = new DynamoDBPersistenceLayer({ export const handler = makeIdempotent( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '12345', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '12345', + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/workingWithCustomConfig.ts b/examples/snippets/idempotency/workingWithCustomConfig.ts index 83d2b07159..7dfe3a23d7 100644 --- a/examples/snippets/idempotency/workingWithCustomConfig.ts +++ b/examples/snippets/idempotency/workingWithCustomConfig.ts @@ -12,17 +12,13 @@ const persistenceStore = new DynamoDBPersistenceLayer({ export const handler = makeIdempotent( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '12345', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '12345', + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/workingWithExceptions.ts b/examples/snippets/idempotency/workingWithExceptions.ts index 5114c083b9..4d4a966a79 100644 --- a/examples/snippets/idempotency/workingWithExceptions.ts +++ b/examples/snippets/idempotency/workingWithExceptions.ts @@ -53,7 +53,7 @@ export const handler = async ( message: 'success', statusCode: 200, }; - } catch (_error) { - throw new Error('Error creating payment'); + } catch (error) { + throw new Error('Error creating payment', { cause: error }); } }; diff --git a/examples/snippets/idempotency/workingWithIdempotencyRequiredKey.ts b/examples/snippets/idempotency/workingWithIdempotencyRequiredKey.ts index 20094ecf8e..6096ccf3a6 100644 --- a/examples/snippets/idempotency/workingWithIdempotencyRequiredKey.ts +++ b/examples/snippets/idempotency/workingWithIdempotencyRequiredKey.ts @@ -17,17 +17,13 @@ const config = new IdempotencyConfig({ export const handler = makeIdempotent( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '12345', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '12345', + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/workingWithLocalCache.ts b/examples/snippets/idempotency/workingWithLocalCache.ts index 4de44697f3..f29e56a578 100644 --- a/examples/snippets/idempotency/workingWithLocalCache.ts +++ b/examples/snippets/idempotency/workingWithLocalCache.ts @@ -15,17 +15,13 @@ const config = new IdempotencyConfig({ export const handler = middy( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '1234567890', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '1234567890', + message: 'success', + statusCode: 200, + }; } ).use( makeHandlerIdempotent({ diff --git a/examples/snippets/idempotency/workingWithPayloadValidation.ts b/examples/snippets/idempotency/workingWithPayloadValidation.ts index eaccb2de3c..7f7cb4e37d 100644 --- a/examples/snippets/idempotency/workingWithPayloadValidation.ts +++ b/examples/snippets/idempotency/workingWithPayloadValidation.ts @@ -40,19 +40,16 @@ export const handler = async ( context: Context ): Promise => { config.registerLambdaContext(context); - try { - const productAmount = await fetchProductAmount(event.productId); - const payment = await createSubscriptionPayment({ - ...event, - amount: productAmount, - }); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + const productAmount = await fetchProductAmount(event.productId); + const payment = await createSubscriptionPayment({ + ...event, + amount: productAmount, + }); + + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }; diff --git a/examples/snippets/idempotency/workingWithRecordExpiration.ts b/examples/snippets/idempotency/workingWithRecordExpiration.ts index 7af76c256f..a93cd985db 100644 --- a/examples/snippets/idempotency/workingWithRecordExpiration.ts +++ b/examples/snippets/idempotency/workingWithRecordExpiration.ts @@ -16,17 +16,13 @@ const config = new IdempotencyConfig({ export const handler = makeIdempotent( async (_event: Request, _context: Context): Promise => { - try { - // ... create payment + // ... create payment - return { - paymentId: '12345', - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: '12345', + message: 'success', + statusCode: 200, + }; }, { persistenceStore, diff --git a/examples/snippets/idempotency/workingWithResponseHook.ts b/examples/snippets/idempotency/workingWithResponseHook.ts index d61497b362..59ac14caff 100644 --- a/examples/snippets/idempotency/workingWithResponseHook.ts +++ b/examples/snippets/idempotency/workingWithResponseHook.ts @@ -39,17 +39,13 @@ const createSubscriptionPayment = async ( export const handler = makeIdempotent( async (event: Request, _context: Context): Promise => { - try { - const payment = await createSubscriptionPayment(event); + const payment = await createSubscriptionPayment(event); - return { - paymentId: payment.id, - message: 'success', - statusCode: 200, - }; - } catch (_error) { - throw new Error('Error creating payment'); - } + return { + paymentId: payment.id, + message: 'success', + statusCode: 200, + }; }, { persistenceStore,