Pardon Scripting

This tutorial expands on Pardon scripting. Defining scripts and importing them into collections, as well as exporting them.

The exercies here requires that some products are created, if you haven’t created any, you can follow the Steps in the first exercise in the dataflow tutorial to make a few.

Pardon Dataflow How data flows through templates.

Scripts

Pardon scripts are javascript/typescript ECMA script modules (esm / esmodule). Consider our example service, we’ll be adding an example-helper.ts support script.

• Directoryexample/

  • service.yaml
  • example-helper.ts
  • Directoryproducts/

    • list.https
    • …

We’ll have this script provide a “serviceToken”, using a slow connection to an authorization server with a timeout: and we are also appending a time-based value so we can see the result changing.

example/example-helper.ts

export async function serviceToken(env: string) {
  await new Promise((resolve) => setTimeout(resolve, 700));

  return `service-token-${env}-${`${Date.now()}`.slice(-5)}`
}

To use this script from an template expression, we’ll use export and import.

export

In order to import from ‘pardon:example’, as in

import { serviceToken } from 'pardon:example';

we need to define what the example collection exports. This is one line in the service.yaml:

example/service.yaml

export: ./example-helper.ts
config:
  origin:
    env:
      prod: https://example.com
      stage: https://stage.example.com
mixin:
  - pardon:example/auth.mix.https

import

Then we can import named values from the

example/auth.mix.https

import:
  pardon:example:
    - serviceToken
config:
  authorization: token
>>>
ANY //
Authorization: {{ @auth = serviceToken(env) }}

Feel free to experiment with the usual env=stage/env=prod changes, (notice that pardon takes a moment to update now.)

Loading Pardon Playground...

The imported scripts are loaded through the node-module import mechanism and may import other dependencies (including npm-installed packages).

Note

The key pardon:example is a pardon-relative import. You can import external packages too, for instance if you want to customize your User-Agent based on os.platform() you could do this

example/user-agent.mix.https

import:
  node:os: os
>>>
ANY //
User-Agent: {{= `pardon/1.0 (${os.platform()})` }}

The non-listed import form is equivalent to

import * as os from 'node:os'

pardon-in-pardon

We’ve got a new requirement, the business wants our ordering system to be available to the front-end, and we’ll need to do some validation:

The price of products change frequently, and when a customer places an order, the price on the screen might not match the price in the system: so we need to send the price-on-the-screen and check if it’s still correct.

That’s fair, but also totally annoying for the backend developers on the order system who have to add more data to every request and make sure it’s correct.

Well, pardon supports making pardon requests in scripts, and using the results in expressions. (We could techincally put this code in an expression, but it’s more readable to put non-trivial code in scripts).

To demonstrate this, first we need to define how to get this data from our products/get endpoint:

extract product data

example/products/get.https

>>>
GET https://example.com/products/{{product}}

<<<
200 OK

{
  "name": "{{?name}}",
  "price": "{{?price}}"
}

use output in a script

Then we can make a helper function that could extract the name and price from the product respones.

For the following exercise, we’ll be using the following script:

example/products/products-helper.ts

import { pardon } from 'pardon';

export async function price({ product, env }: { product: string, env: string }) {
  const {
    inbound: {
      values: { price }
    }
  } = await pardon({ product, env })`https://example.com/products/{{product}}`();

  return price;
}

Note

This price script isn’t editable here (it’s hacked into the demo system).

Exercises

Dynamic data

See what is returned in values.

Confirm the data extracted for products P1001, P1002, etc…

Script integration

Integrate a script.

This is a multi-step process, first we can define the script as the export of pardon:example/products, to do this, we’ll make a few changes:

1. Setup export

First we add a config.yaml in products to define its export.

example/products/config.yaml

export: ./products-helper.ts

Note

Be sure to edit the example/products/config.https file here.

2. Use in expression

Next we import the info method inside the endpoint we’d like to use it from and add.

example/orders/create.https

import:
  pardon:example/products:
    - price
>>>
POST https://example.com/orders

{
  "cart": [{
    "product": "{{items.product}}",
    "quantity": number("{{items.quantity=1}}"),
    "cost": "{{items.cost = price({ product, env })}}"
  }]
}

Note

Be sure to edit the example/orders/create.https file here.

3. Make the Call

Set the input data.

items=[{ product: P1001 }, { product: P1002 }]

And select the correct endpoint:

POST https://example.com/orders

And now we automatically pass the price as cost in the requests.

Loading Pardon Playground...

Tip

We have to be careful with having different names for our functions since the items.cost value and our price function share a namespace (cost and price).

As in javascript module imports can use as to rename imports in pardon as well.

import:
  pardon:example/products:
    - price as productPrice

We have one more thing to fix, though. The price is per-unit but the cost needs to be the price multiplied by the quantity for each item.

Exercises

setup quantities

Assign quantities to order items

First let’s set some quantity on these products:

items=[
  { product: P1001, quantity: 15 },
  { product: P1003, quantity: 15 }
]

Notice the costs are not updated yet.

multiply

multiply the price by quantity to get the cost

Here we need to await the result since it’s an asynchronous request, and then multiply by the quantity. (otherwise Javascript attempts to multiply a Promise by a number and that simply doesn’t work.)

example/orders/create.https

import:
  ../products/products-helper.ts:
    - price
>>>
POST https://example.com/orders

{
  "cart": [{
    "product": "{{items.product}}",
    "quantity": number("{{items.quantity=1}}"),
    "cost": "{{items.cost = await price({ product, env }) * quantity}}"
  }]
}

Now the costs are multiplied by the quantities.

Tip

In pardon JavaScript, we can also write:

price({ product, env }).await * quantity

This doesn’t help us in this example, but it’s a tiny additonal feature of Pardon-script.

productInfo({ product, env }).await.price
/* or */
(await productInfo({ product, env })).price

Loading Pardon Playground...

With this kind of scriptable data flow, we can use pardon to automate the toil of computing some fields so we focus on the data we care about.

(Remember we can always provide a cost value directly to skip the script.)

Next Steps

We’re ready to start descripting testcases and collection layering. Layering allows a base collection structure to be extended with team-specific mixins and defaults, allowing the use of an API to be described differently from the definition.

Pardon Collection Layering How to organize collections across teams

These next two sections are functionally independent, but pardon tests leverage collections and layering collections allows us to share collection layers and operational needs.

Pardon Testcases Using pardon for tests