Introduction

Have you ever tried to test a Vue composable function (“use" function) and hit this error?

SyntaxError: Must be called at the top of a `setup` function

I sure have. I added in-source tests for composable function in a project I’m working on that does currency formatting, but once I updated that composable to use Vue I18n number formatting, I hit that syntax error.

Why would adding I18n to the function change how it needs to be tested? The Vue documentation explains that certain composable functions can only be used in a setup function:

A composable depends on a host component instance when it uses the following APIs:

- Lifecycle hooks
- Provide / Inject

https://vuejs.org/guide/scaling-up/testing.html#testing-composables

Lo’ and behold, Vue I18n uses provide/inject by default: https://vue-i18n.intlify.dev/guide/advanced/composition.html#implicit-with-injected-properties-and-functions. That means to test a similar composable, we need our test to include a setup function.

So what is the best way to unit test a Vue composable function? Let’s find out.

Info: Looking for a package that does this? Check out github.com/wobsoriano/vue-composable-testing.

First steps

Let’s not reinvent the wheel.

Vue provides an example of how to test a composable, but the example uses vanilla JavaScript and out-of-the box it isn’t type-safe. Let’s check it out:

import { createApp } from 'vue'

export function withSetup(composable) {
  let result
  const app = createApp({
    setup() {
      result = composable()
      // suppress missing template warning
      return () => {}
    }
  })
  app.mount(document.createElement('div'))
  // return the result and the app instance
  // for testing provide/unmount
  return [result, app]
}

I’m a big TypeScript user, so let’s add types to that example (see the T):

import { createApp } from 'vue'

export function withSetup<T>(composable: () => T) {
  let result: T
  const app = createApp({
    setup() {
      result = composable()
      // suppress missing template warning
      return () => {}
    }
  })
  app.mount(document.createElement('div'))
  // return the result and the app instance
  // for testing provide/unmount
  return [result, app]
}

This is looking pretty good! TypeScript knows that the return type of withSetup is the same as the return type of the composable function.

But there’s a wrinkle. Using this code in a test causes the following type error:

Variable 'result' is used before being assigned. ts(2454)

A limitation of using this method to test a composable is that it isn’t fully type-safe because result can be undefined. Because result is only set in the setup() function of createApp() but is returned right away, TypeScript rightly lets us know of a race condition where we're using result while it still might not be set.

“Solution” 1: definite assignment

Because of how Vue works, result likely will be set after app.mount(), though, so we can let TypeScript know this with a definite assignment assertion, which is specified with a ! after a variable name.

import { createApp } from 'vue'

export function withSetup(composable) {
  let result
  const app = createApp({
    setup() {
      result = composable()
      // suppress missing template warning
      return () => {}
    }
  })
  app.mount(document.createElement('div'))
  // return the result and the app instance
  // for testing provide/unmount
  return [result!, app] // <-- JF: TypeScript hack so result is defined
}

Using definite assignment assertions like this can paper over runtime issues in your code, like race conditions. I try to avoid them as a matter of course.

A more type-safe way to do this would be to throw an error if result is undefined:

if (result === undefined) throw new Error('result is undefined')
return [result, app] // <-- no more '!'

Solution 2: Promise

This is the type-safe solution I came up with to test a Vue composable.

This method side-steps the race condition of whether result is defined by using a Promise, which guarantees that result is defined when it is used in a test.

// @/utils/testing.ts
import { createApp } from 'vue'

/**
 * @param getComposableResult Function that returns the value of a composable for testing
 */
export async function testComposable<T>(getComposableResult: () => T): Promise<T> {
  return new Promise((resolve) => {
    const app = createApp({
      setup() {
        resolve(getComposableResult())
        // suppress missing template warning
        return () => {}
      },
    })
    // Install global plugins here with app.use()
    app.mount(document.createElement('div'))
  })
}

If your tests rely on Vue plugins, like for i18n, you can install them in your testComposable function so they're available to use in your tests.

Mounting a Vue application in a test environment requires a DOM implementation, like happy-dom, added to the environment setting of your test Vitest config.

Here’s how we can use our testComposable it in a test for a composable named useFormatCurrency:

import { describe, expect, it } from 'vitest'

import { useFormatCurrency } from '@/composables/currency'
import { testComposable } from '@/utils/testing'

describe('useFormatCurrency', () => {
  it('prepends the correct currency symbol', async () => {
    const result = await testComposable(() => {
      const formatCurrency = useFormatCurrency()
      return formatCurrency(0.20000001)
    })
    expect(result).toEqual('$0.20')
  })
})

Info: The tests are written with Vitest, an excellent test runner for TypeScript and JavaScript projects.

Wrap-up

That’s it! With this quick Promise-based utility, it’s easy to write type-safe unit tests for Vue composables.

This method is great for unit testing composables outside of components. For a component-centric solution where you’re looking to test how a composable works with component props, check out this example from the Vue Test Utils docs: https://test-utils.vuejs.org/guide/advanced/reusability-composition.html#Testing-composables.

Happy testing!

Most of this post was written on November 13th, and as of January 13th, 2025, Pyrfecter’s search performance has gotten even better: 191 clicks in 28 days.

Introduction

In August 2024, Pyrfecter.com reached 20 clicks from Google Search in 28 days for the first time. Three months later, the site is just a click away from reaching 120 clicks in 28 days.

Granted, this isn’t colossal organic search traffic, but it is a pretty big jump considering that almost all of the new traffic can be attributed to one wording change on one page on October 9th.

The steps

Step 1: have good content

This might not need to be said, but if your site doesn’t provide something people are searching for, no amount of SEO can save you.

Step 2: research queries

To optimize for specific queries, you need to know what they are.

“Thanks, Captain Obvious.”

Fair, fair. But how can you find out what keywords to optimize for?

• look at the search terms that are already surfacing your content using tools like Google Search Console and Bing Webmaster Tools
  NB: if your site is very new, the data here will be limited
• do research using a tool like Semrush to see which keywords competing sites are ranking for
• compare keyword popularity using Google Trends

Here are the queries where a Pyfecter page appeared in the Google results for the 3 months ending November 11, 2024 (from Google Search Console):

| Top queries             | Impressions |
| ----------------------- | ----------- |
| python linter           | 553         |
| python linter online    | 532         |
| linting python          | 418         |
| python lint online      | 371         |
| python linting          | 363         |
| walrus operator python  | 279         |
| python walrus operator  | 254         |
| walrus operator         | 203         |
| what is a python linter | 195         |
| linting in python       | 194         |

Table generated with Table to Markdown

And here are the Google Trends over the past 5 years for “python linter” and “lint python”, showing that “python linter” consistently trends higher:

Step 3: incorporate those queries in your page

Now that you know what language people use to find content like yours, it’s time to update your page to use that language. And — I can’t stress this enough — it needs to feel natural.

If your page’s content reads as though it’s cramming in as many keywords as it can, your page may get punished for keyword stuffing:

Keyword stuffing refers to the practice of filling a web page with keywords or numbers in an attempt to manipulate rankings in Google Search results.
- Google Search Central, Spam policies for Google web search

With keywords, a little goes a long way.

Below is the Markdown source code for https://pyrfecter.com/lint/, which is built using my static site generator Blurry.

You’ll notice three changes in the diff (red lines were removed; green lines were added):

1. name TOML front matter, which is used as the page's <title>, updated with the new wording
2. a newer datePublished, which is included in the site's sitemap to tell search engines that the page has changed
3. the page’s top-level heading updated with the new wording (# in Markdown is an <h1> in HTML)

--- a/content/lint.md
+++ b/content/lint.md
@@ -1,12 +1,12 @@
 +++
 "@type" = "WebPage"
-name = "Lint Python code securely in your browser with Pyrfecter"
+name = "Pyrfecter: the secure online Python linter"
 abstract = "With Pyrfecter, you can lint Python code quickly and securely right in your browser. Plus, it's 100% free."
-datePublished = 2024-05-11
+datePublished = 2024-10-09
 _show_code = true
 +++
 
-# Lint Python online with Pyrfecter
+# Pyrfecter: the secure online Python linter

Blurry uses Schema.org types, like WebPage, to describe page content. This describes the content to search engines and can be used to show rich search results like you see for products (Product) and restaurants (Restaurant).

That three-line diff is the whole git commit that kicked off a steady increase in organic search traffic.

Step 4: tell search engines

Before you can see real-world results from your SEO changes, you’ll need to tell search engines that your content has changed and ask them to index the updated pages.

For Google, open Google Cearch Console and navigate to Google’s URL Inspection tool to request indexing for the URL.

The process is similar for Bing: input your updated URL in the Bing Webmaster Tools URL Submission tool.

Bing also supports triggering automatic indexing of updated URLs using IndexNow, but that’s a topic for another day.

Step 5: watch the numbers go up

It can take a couple of days before changes in search performance start to happen, so this step requires a bit of patience.

But, if your SEO work was a success, you’ll soon be able to watch your organic search traffic go up and to the right:

Wrap-up

For search marketers and plenty of developers, the information in this post may be old hat.

As someone who has been learning about and experimenting with SEO for 15 years, though, I’m still surprised at what an impact even one small change can have on search performance.

Granted, when a site doesn’t get much organic search traffic, it’s much easier to see large percentage improvements. But I think this point stands on its own: using the same language as your site’s prospective visitors is fundamental to SEO and can get you measurable results.

Introduction

At each stop in my career, I seem to develop a reputation for being a Fussy Franey with user stories. I’ve seen some eye rolls when I’ve asked for one story to be broken into three, and I’ve faced incredulity when pointing out that one “user story” is actually an entire epic — or even so broad in scope that it could be an entirely separate business.

I like to get things done, and I’ve found that small, well-written user stories are the single biggest enabler of dev velocity.

User stories should be small

Very small. How small?

They should encompass a single user interaction, single visual element, or single application reaction.

Reducing scope for a feature or launch should not require rewriting user stories

What counts as a user interaction?

• Viewing something, like a list of contacts
• Navigating to a page
• Entering a value in a form field
• Submitting a form

Note: submitting a form doesn’t include form submission accoutrements, like showing a loading icon (separate story), showing an error message (separate story), or showing a success message (separate story)

What counts as a visual element?

Viewing is an action, and seeing a visual/UI element counts as a user story. Visual elements can be tiny, too, like a red notification dot you might see on a new menu link.

It might seem like overkill to have an entire user story for a notification dot, but the menu item can exist without the notification dot. Because the notification dot depends on the menu item, it can be implemented separately from the menu item and prioritized separately, too.

What counts as an application reaction?

An application reaction is a change in the application that happens as a result of a user action or as a result of other application logic. The reaction could take place within an application (a toast notification) or across applications (sending an SMS).

Some quick examples:

• Validating an input
• Showing a toast
• Showing a loading element
• Showing a logout warning
• Sending a confirmation email

Q: When is a story not a story?

A: When it’s an epic!

For example, let’s take the following story:

As a user, I can delete a to-do item

Sounds like a small, regular story, right? Not so fast.

A story like that could have a number of requirements before it could be considered done (optional requirements marked with asterisks):

1. Showing a confirmation modal when clicking the delete button*
2. Writing the API delete endpoint
3. Performing the API delete request on click
4. Disabling the button while the request is processing*
5. Removing the to-do item on a success response
6. Showing a success toast*

There’s a lot happening there. There’s enough happening here to make deleting a to-do item an epic rather than a single story.

And what’s an epic? An epic is “a large, high-level piece of work” (ScrumAlliance) that consists of multiple user stories and other pieces of work, like non-user-facing dev tasks.

Atlassian has a helpful explanation of epics as a strategy to break down work into smaller pieces:

Epics are a helpful way to organize your work and to create a hierarchy. The idea is to break work down into shippable pieces so that large projects can actually get done and you can continue to ship value to your customers on a regular basis. Epics help teams break their work down, while continuing to work towards a bigger goal. (Atlassian, “Agile epics: definition, examples, and templates”)

In other words, an epic captures an entire feature flow, like the end-to-end (and frontend-to-backend) process of creating a to-do item, and it consists of one or more user stories and/or dev tasks.

Note: “Managing” something should never be a single user story. If your user story starts, “As a user, I can manage…”, it’s likely a project, and each of the Create, Read, Update, and Delete actions may well be its own epic.

Can stories have multiple acceptance criteria?

They can!

But they still need to be small, and the acceptance criteria need to be so intimately related that separating them would be impossible to implement or impossible to verify. So what is a story that can have multiple acceptance criteria? The second requirement in the epic above is a good example:

As a user, I can confirm whether I want to delete a to-do item

This story might have acceptance criteria like the following:

1. GIVEN I am a user viewing a to-do item
   WHEN I click the delete button
   THEN I am shown a confirmation modal
2. GIVEN I am a user confirming whether to delete a to-do item
   WHEN I click the close button on the confirmation modal
   THEN the modal is closed AND the to-do item is not deleted
3. GIVEN I am a user viewing the delete to-do confirmation modal
   WHEN I confirm my intent to delete the to-do item
   THEN the item is deleted AND the modal is closed

Showing a confirmation modal (application reaction) when clicking the delete button (user action) encompasses two UI elements and one action+reaction, but still makes sense to have in the same user story because there’s no way to validate that the delete button behaves as expected without having a confirmation modal to view.

The story could be broken into subtasks to parallelize development by creating a subtask for the design of the confirmation modal. Ideally, the confirmation modal would be reusable and wouldn’t have to be implemented separately for each action. For more on this, see the “User stories should be new” section below.

Note: Multiple user stories can be coded in a single branch and merged in a single pull request.

For example, showing a success message on a successful form submission and showing an error message on an unsuccessful one could make sense to code together. They are different enough that they should be in separate user stories, though, because one could be done without doing the other.

User stories should be explicit

A story’s definition of “done” should be unambiguous.

Acceptance criteria should be specific and comprehensive, and it should be described in writing rather than being hidden in designs.

If a story involves changing text, for example, include the old and new text in the acceptance criteria. When acceptance criteria read something like “Update wording to match designs”, changes are easy to miss, which can throw off estimates and lead to QA rejections.

Note: Gherkin syntax (GIVEN/WHEN/THEN) is helpful to describe a story’s scope. If a story is difficult to describe in the GIVEN/WHEN/THEN format, it’s also going to be difficult to code, review, and QA.

User stories should be new

Existing capabilities can be acceptance criteria, while new capabilities should be user stories.

If you have a form component that shows an error message on a 500 response, for example, there doesn’t need to be a new user story to use this behaviour in a new form. For another example, if you have a phone numer field and you want to see a phone number input on a mobile device, because this is a built-in capability of an <input type="tel">, it doesn't need to be its own user story.

Note: Subtle changes to existing behaviour should be captured in a separate ticket. It’s a good idea to have one or more developers audit acceptance criteria to identify new features that may be masquerading as acceptance criteria.

Lightning summary ⚡

While it may seem tedious to have stories with such a narrow scope, large user stories often mask complexity in a project, posing challenges to estimating, sequencing, QAing, and descoping work.

User stories that actually get done are small, explicit, and new.

How to write user stories that actually get done was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

AWS has a ton of documentation, and sometimes it misses the mark. Recently, I came across two different examples of AWS documentation either perplexing or frustrating me.

Note:By "frustrating", I mostly mean it in the "hinder or prevent (the efforts, plans, or desires) of" meaning of the word (WordWeb). Mostly.

Now, I don't want to come across as a complainy Franey, but since I've been working on documentation for Blurry, a static site generator I open-sourced (and that builds this site), I've been thinking about what makes good technical documentation good. I don't think I've figured it out quite yet, but I have found two traits of AWS docs that can hurt documentation, and maybe doing the opposite can improve it.

Read on for a break-down of two AWS documentation breakdowns and what I learned therefrom.

Trait 1: perplexing

Video: Installing the AWS VS Code extension from the Lambda console

How many steps does it take to get a direct link to the VS Code extension?

From the Lambda function console page, it took 4 clicks, reading, and scrolling to get to the actual VS Code extension. Even from the AWS Toolkit for Visual Studio Code site, it was still two clicks to get to the page with the direct VS Code link (and that link was below-the-fold).

That's quite a long walk for what ended up being a link that opened the extension in VS Code itself. Four clicks for something that could be one click? That's pretty perplexing.

There's some risk in having that much documentation about a VS Code extension, too.
Having a documentation site separate from the README could mean:

1. You have to maintain documentation in multiple places, which can be difficult to keep in sync
2. If documentation in one of the two places isn't unique enough to have to keep in sync, that means the docs may be general enough to be not that helpful

Info: I do need to give credit where it's due: an earlier version of the VS Code extension documentation didn't have a link that opened the extension in VS Code; after all that clicking, it asked that we open VS Code and search for the extension.

Trait 2: frustrating

It's frustrating when documentation is incomplete — especially in code examples.

Take this Python code sample for AWS CDK's PythonFunction, for instance:

entry = "/path/to/function"
image = DockerImage.from_build(entry)

python.PythonFunction(self, "function",
    entry=entry,
    runtime=Runtime.PYTHON_3_8,
    bundling=python.BundlingOptions(
        build_args={"PIP_INDEX_URL": "https://your.index.url/simple/", "PIP_EXTRA_INDEX_URL": "https://your.extra-index.url/simple/"}
    )
)

Linting the code using Pylint via (Pyrfecter), we can see a number of linting issues:

2:9: undefined name 'DockerImage'
4:1: undefined name 'python'
4:23: undefined name 'self'
6:13: undefined name 'Runtime'
7:14: undefined name 'python'

There are a couple missing imports that were easy to sort out (Runtime, DockerImage), but python? I couldn't find that in the CDK Developer Guide or the CDK API documentation or the AWS CDK Examples.

After getting help from a search engine, I found that the missing python import is:

from aws_cdk import aws_lambda_python_alpha as python

And the PyPI package to install is:

aws-cdk-aws-lambda-python-alpha

And self?
The python.PythonFunction call shoud be inside a CDK Stack.

If we check the documentation for that, we get an example of an App and a Construct, but the Stack classes are stubbed:

from aws_cdk import App, Stack
from constructs import Construct

# imagine these stacks declare a bunch of related resources
class ControlPlane(Stack): pass
class DataPlane(Stack): pass
class Monitoring(Stack): pass

class MyService(Construct):

  def __init__(self, scope: Construct, id: str, *, prod=False):

    super().__init__(scope, id)

    # we might use the prod argument to change how the service is configured
    ControlPlane(self, "cp")
    DataPlane(self, "data")
    Monitoring(self, "mon")

app = App();
MyService(app, "beta")
MyService(app, "prod", prod=True)

app.synth()

There are no linting errors, at least!

For a code example of a Stack, I went to the documentation for App and found this:

class MyFirstStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)

        s3.Bucket(self, "MyFirstBucket")

And the linting output?

1:20: undefined name 'Stack'
3:31: undefined name 'Construct'
6:9: undefined name 's3'

We can get the Stack and Construct imports from the code sample in the Stacks page.

So. After checking the the aws_cdk.aws_lambda_python_alpha API docs, multiple pages of the AWS CDK Developers Guide, the GitHub examples repo, and some searching to find the docs for "@aws-cdk/aws-lambda-python-alpha module" (which is separate from the CDK API docs), we have enough documentation to use these new (and very helpful!) Python CDK constructs.

But, boy, did I have to work for it. I can't remember how much time it took for me to get a complete working example, and I shudder to think of how many dev-hours have been spent in a similar pursuit.

A complete, working code example would save oodles of time, and I'm happy to oblige:

from aws_cdk import Duration, RemovalPolicy, Stack
from aws_cdk import aws_dynamodb as dynamodb
from aws_cdk import aws_lambda as lambda_
from aws_cdk import aws_lambda_event_sources as event_sources
from aws_cdk import aws_lambda_python_alpha as lambda_python
from aws_cdk.aws_lambda_python_alpha import PythonFunction
from constructs import Construct


class WorkingStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Resources
        python_dependencies_layer = lambda_python.PythonLayerVersion(
            self,
            "PoetryLayer",
            entry="./src/layer",
            compatible_runtimes=[lambda_.Runtime.PYTHON_3_10],
        )

        dynamodb_table: dynamodb.Table = dynamodb.Table(
            self,
            "WorkingTable",
            partition_key=dynamodb.Attribute(
                name="PK", type=dynamodb.AttributeType.STRING
            ),
            stream=dynamodb.StreamViewType.NEW_IMAGE,
            sort_key=dynamodb.Attribute(name="SK", type=dynamodb.AttributeType.STRING),
            removal_policy=RemovalPolicy.RETAIN,
            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
        )

        # Functions
        react_to_new_entries_function: PythonFunction = PythonFunction(
            self,
            "ReactToNewEntries",
            entry="./src/functions",
            index="react_to_new_entries.py",
            runtime=lambda_.Runtime.PYTHON_3_10,
            layers=[python_dependencies_layer],
            environment={
                "TABLE_NAME": dynamodb_table.table_name,
            },
            timeout=Duration.seconds(29),
        )

        # Event handling
        react_to_new_entries_function.add_event_source(
            event_sources.DynamoEventSource(
                dynamodb_table,
                starting_position=lambda_.StartingPosition.TRIM_HORIZON,
                batch_size=5,
                bisect_batch_on_error=True,
                retry_attempts=1,
            )
        )

        dynamodb_table.grant_read_write_data(react_to_new_entries_function)

Info: I'm working on another post showing a complete AWS CDK project with typed Python.Stay tuned!

Summary

Documentation should yield more answers than questions

If your documentation requires multiple other (possibly unlinked) documentation sources to be helpful, there's a problem. Code samples, especially, should be complete, to make it easy to get started using your code.

Info: Maintaining complete and accurate code samples can be hard to maintain and verify, which is one of the reasons I once made flake8-markdown, a little package to run flake8 on Python code blocks embedded in Markdown files.

(I should probably be using it on this site, now that I think of it.)

Documentation should anticipate the information a reader is most likely looking for and make that easy to find

If someone clicks a link about a VS Code extension, make the call-to-action to download that extension dead-simple to find. Additional information can be helpful, too, especially for someone learning a new skill or concept, but make it easy for someone who has a good idea what they're looking for.

Last rites writes words

Writing documentation is hard. And it's easy to pick on AWS, not only because they have so much documentation, but also because they have the resources to maintain great docs.

But reading documentation is much easier than writing it, and complaining about documentation is much easier than fixing it. So keep an eye out for things that make documentation great and grody, send up PRs, and write some code...y.

AWS documentation frustrations was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to use Vue to create custom elements that are easy to drop into your static site’s Markdown files

Intro

Recently I rebuilt Table to Markdown, converting it from a Nuxt project to a static site built with Blurry, a pre-release static site generator (“SSG”) I’ve been working on. I wanted the simplicity and performance of a static site, but I still needed interactivity.

Although I use Blurry to generate static sites, this guide will work for any static site generator, like Hugo or Jekyll.

“What simplicity and performance?” you ask? Well, one challenge I had with the Nuxt.js hybrid version of Table to Markdown is that it was hard to accurately count page views since sometimes they would be tracked in server-side code and sometimes they’d be tracked in client-side code — and I didn’t want to count them twice. I had the same challenges with ad impressions, and accidentally counting those more than once could have gotten me in trouble with any ad networks I was using.

With a static site, those page views and ad impressions didn’t require any thought because they would fire when the HTML was loaded, and that was that.

Using Vue for the entire site led to quite a bit of JavaScript for things that I really didn’t need JavaScript for, like site navigation. Using a static site meant I could rely on regular hyperlink navigation without requiring a single line of JS, which meant faster page loads.

But, there was a catch: I still needed the interactivity I got from Vue, so I couldn’t replace all of the Vue code with a static site.

Web Components with Vue

To make it easy to integrate Vue with my static site, rather than using Vue to manage the whole page, I opted to use Vue in a single custom HTML element via Web Components.

For a sneak peak of what we’re building toward, here’s a snippet of a Markdown file from Table to Markdown:

# Convert spreadsheet cells to Markdown

<div class="custom-element-container">
  <table-converter></table-converter>
</div>

Table to Markdown makes it easy to convert cells from Microsoft Excel, [...]<div class="custom-element-container">
  <table-converter></table-converter>
</div>

Table to Markdown makes it easy to convert cells from Microsoft Excel, [...]

Web Components allow you to create custom self-contained HTML elements that can leverage JavaScript to do whatever you want them to. A big benefit is that once you include the JS where the Web Components are defined, you can use them just like you’d use a regular HTML element, like a <p> or <a>.

Sounds good, eh? Almost too good? Well, there are some wrinkles with this approach, but they’re nothing we can’t iron out.

Wrinkles

Layout shift once web component loads

If you follow this blog, you’ll have noticed that I have a thing for PageSpeed scores.

One thing to keep in mind when using Web Components is that their height isn’t taken into account when the page renders.

By matching the height of your Web Components and the height of a web component wrapper, you can avoid content layout shifts, which are disruptive to your visitors:

/* Main stylesheet */
.custom-element-container {
  min-height: 300px;
}

You can use responsive heights in your custom element container so your content corresponds to your visitors’ screen sizes.

CSS scoping

To ensure that your styling is consistent in your static site and your web components, you can use the same CSS file in both places. Simply import your CSS file in your Vue component:

<style>
@import('main.css')
</style>

Keep this CSS file as small as you can since its content may be loaded twice. Include only the necessary styles, and, for a page speed boost, consider inlining this CSS file in your static site’s base template file.

Child component CSS

If your single-file Vue component uses other, non-custom element Vue components with <style> tags, you may be surprised to see those styles disappear when you use your custom element.

For some workarounds:

• @import() relevant CSS in your child components
• Rather than scoping your CSS (<style scoped>) in your top-level component, define CSS rules that will also apply to child components
• Style classes, elements, or use CSS custom properties (variables) in inline style=""/:style="{}" attributes on elements in your child components

Implementation

Now that we’ve identified some wrinkles and ways to smooth them out, it’s time to see how to convert a Vue file into a custom element.

Vite config

First, update the Vue plugin for Vite to generate web components, and configure Vite to place your built components where you want them:

import { fileURLToPath, URL } from 'node:url'
import { resolve } from 'path'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
// https://vitejs.dev/config/
export default defineConfig({
  // Get Vue to output custom elements
  plugins: [vue({ customElement: true })],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  build: {
    // Specify a directory in your SSG's build directory
    outDir: 'dist/elements',
    rollupOptions: {
      // Improvement: loop through files in the elements directory to build this object
      input: {
        'your-component': resolve(__dirname, 'src/elements/your-component.ts'),
      },
      // Use predictable file names
      output: {
        entryFileNames(chunkInfo) {
          return `${chunkInfo.name}.js`
        },
      },
    }
  }
})

For more info on using Vue to build web components, check out the Vue docs.

Custom element file

In a separate file, define your Vue component as a custom element, which will make your component available to use in the HTML DOM:

// src/elements/your-component.ts
import { defineCustomElement } from 'vue'

import YourComponent from '@/components/YourComponent.vue'

customElements.define('your-component', defineCustomElement(YourComponent))

Creating a separate file for each web component can help keep your JavaScript bundles small by including only the required code for that component.

You can also define many custom elements in a single file. See the Vue docs for more info and recommendations for building a library of custom elements.

Include the JS and custom element in your SSG files

Now all that’s left is do is to include your custom element .js file in the relevant template file of your SSG:

<script src="/elements/your-component.js" type="module"></script>

<your-component></your-component>

Wrap-up

That’s a wrap.

This article is wrapped up like a Vue single-file component in a Web Component custom element after following the above steps.

Use Vue in a static site with Web Component custom elements was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

SEO is tricky business — -or used to be, at least. In the history SEO, there were plenty of tricks people would use to try to improve their sites’ Google rankings, like keyword stuffing, the practice of cramming specific words or phrases into site content so it masquerades as a better resource for those search terms than it actually is.

See Google Search Central’s Spam policies for Google web search for a rundown of different SEO “tricks” that sites are punished for nowadays.

With time, search engines got better at sniffing out sites employing these SEO hacks, which led to more and different SEO tricks to try to game search engines’ ranking algorithms. In 2006, Douglas Merrill, who served as Google’s Chief Information Officer and VP of Engineering, summarized:

Spam is an arms race.

— Douglas Merrill of Google in BBC’s Google to stay focused on search

This post isn’t about a shiny new SEO trick. If you’re looking to improve your site’s search performance, there are reams of online resources on how to improve a site’s SEO, and this article doesn’t purport to be another.

Many guides assume that your site’s content already exists and that you need to tweak either your content or your site’s metadata to improve your site’s search performance. In other words, changing content to build search performance.

This post takes the opposite approach: using search results to decide what to build.

The problem

Since first launching tabletomarkdown.com, I described it as a table/spreadsheet to Markdown converter: taking one type of table and converting it into another. With time and once the site got a little bit of traffic, I was able to see in Google Search Console that many more people searched for “markdown table generator” than any search terms I expected, like:

• “excel to markdown”
• “spreadsheet to markdown”
• “web table to markdown”

I did pretty well for those search terms, eventually ranking as the 1st or 2nd Google search result. But I still ranked pretty low for “markdown table generator”, and the search volume for that term is 2x greater than those other three combined.

After adding the ability to format an existing Markdown table, I jumped up in the search results for Markdown table formatting-relating search terms. But still, the biggest opportunity by far was “markdown table generator”.

The experiment

For quite a while, I thought that searchers were using “converter” and “generator” interchangeably, but they are pretty different. For a Markdown table converter to work, you need a table to exist in order to make it into something new. To generate a table, however, you’re starting from scratch.

But to generate a table generator, thankfully I didn’t have to start from scratch.

Generating a table from scratch

The big trick that makes Table to Markdown possible is that when you copy tables from a website or from a spreadsheet application, the table is stored in your clipboard both as both plain text and HTML.

Because Table to Markdown’s code could already convert an HTML table to Markdown, all I needed was an easy way for visitors to build an HTML table. The interactive elements of Table to Markdown are built using Vue.js, and after some poking around, I found developer-friendly, Vue-compatible WYSIWYG (“What You See Is What You Get”) HTML editor with a solid table plugin: Tiptap.

What are the non-interactive aspects of Table to Markdown built with? Good question! I’ll write a post about that soon.

With a table generator in hand, all I had to do was write some content and publish the new page.

The results

The experiment was a success! I launched the new feature on September 19th, 2022, and it didn’t take long before I started getting more clicks for “markdown table generator”:

Before September 19th it was rare to get more than 15 clicks/day for that search term, but shortly afterwards, I was getting 15 clicks/day multiple weekdays a week. (Traffic is reliably slower on weekends when people tend to take time off from tampering with tables.)

I was already appearing in plenty of searches for “markdown table generator”, but after providing that capability to my visitors, I started to creep up in the rankings — -and my click-through rate followed suit:

We can see that impressions (purple line) didn’t change much, but look at how the Click-Through Rate (CTR; green line) jumps up. It went from under 4% to 6%: an increase of over 50%!

In the month following the launch of the new Markdown table generator (October, 2022), “markdown table generator” became Table to Markdown’s fastest growing search query:

Stats for that query continued to look good through November, too, with October growing by 32% and November growing a further 30%.

Put those numbers on a graph and they’re a growth marketer’s dream: up and to the right!

Wrap-up

This post isn’t going to win any awards for cutting-edge SEO techniques or feature development strategies. I hope it serves as a reminder to check out search terms that are related to your site but that may not be directly related.

If there’s a juicy search term that you’re missing out on, with a bit of work, you may not miss out on it for much longer.

Introduction

To see all the code used in this post, check out my blog examples repo. It even has unit tests!

Python has had type hints since version 3.5, released way back in September 2015.

Since then, some pretty cool projects have spun up, like mypyc, which “uses standard Python type hints to generate fast code”, and Microsoft’s Pyright, a static type checker that plays nicely with their Visual Studio Code editor.

Back in 2019, Airbnb mentioned that around 38% of their bugs would have been prevented if they’d been using types in their codebase all along (HackerNews discussion). Although Airbnb was talking about JavaScript bugs that could have been prevented by using TypeScript, the general theme of types preventing errors by catching type issues before they’re exposed in runtime holds true for Python, too.

Type Support

When reading AWS’s Python Code Samples for Amazon DynamoDB or the boto3 documentation, it isn’t clear how to use DynamoDB with Python types because neither source uses type hints. There are third-party projects that look to fill this gap, like boto3-stubs, part of the mypy_boto3_builder project.

boto3-stubs gives us quite a bit of type information and can help speed up development by providing auto-completion in your code editor, but it doesn't know exactly what we're putting into or getting out of a DynamoDB table.

Let’s take a look at the default type for a DynamoDB item, taken here from the return value of table.get_item():

"Item": Dict[
    str,
    Union[
        bytes,
        bytearray,
        str,
        int,
        Decimal,
        bool,
        Set[int],
        Set[Decimal],
        Set[str],
        Set[bytes],
        Set[bytearray],
        Sequence[Any],
        Mapping[str, Any],
        None,
    ],
],

So a DynamoDB item is a dict with strings for keys and values that could be almost anything. Maybe it's an int, or maybe it's a Set of 'em, or maybe even some kind of map of str to int, or, if you can believe it, a sequence of Any! Why not?!

So how can we type individual DynamoDB items? Read on, dear reader. Read on.

Typing a DynamoDB Item

In the spirit of schema first design, to start, we’ll create a type for our DynamoDB item. As we can see above, a DynamoDB item is returned as a dict, and to properly type that dict, we’ll use — contain your surprise — a TypedDict.

A TypedDict "support[s] the use case where a dictionary object has a specific set of string keys, each with a value of a specific type", so we can guarantee both a dict's key names and its value types. This allows us to benefit from typing without having to translate the dict into, say, a Data Class, then back to a dict.

As an example, here’s a type for a news article, something you might find in an RSS feed:

# news/types.py
from typing import TypedDict

class NewsItem(TypedDict):
    PK: str
    SK: str
    title: str
    description: str | None
    published: str
    link: str

This gives us a type we can use in application code, but we still need a way to ensure that the type we’re putting into and pulling out of a DynamoDB table actually matches that type.

To ensure the DynamoDB item matches our more specific NewsItem type, we'll define some type guards (PEP-647) to do type narrowing. This will ensure that the values contained in a DynamoDB item are the types we expect.

This example is a little sparse because a NewsItem has only two different types (str and str | None), but this technique will work for items with more varied types, too.

# news/type_guards.py
from typing import Any

class TypeGuardException(Exception):
    pass

def guard_optional_string(value: Any) -> str | None:
    if value is None:
        return value
    if isinstance(value, str):
        return value
    raise TypeGuardException(
        f"Received unexpected type: "
        f"expected str | None but received value of type {type(value)}: {value}"
    )

def guard_string(value: Any) -> str:
    if isinstance(value, str):
        return value

    raise TypeGuardException(
        f"Received unexpected type: "
        f"expected str but received value of type {type(value)}: {value}"
    )

These functions are pretty simple: they take in a value that can be any type, and they either raise an exception or spit out that same value. The key difference is in the return type, like -> str: now our type checker knows exactly what type value is.

Let’s see how these type guards work in practice:

>>> guard_optional_string('En garde!') == 'En garde!'
True
>>> guard_optional_string(None) is None
True
>>> guard_optional_string(100) is 100
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/john/Code/blog-examples/dynamodb-python-type-hints/news/type_guards.py", line 15, in guard_optional_string
    raise TypeGuardException(
news.type_guards.TypeGuardException: Received unexpected type: expected str | None but received value of type <class 'int'>: 100

Now that we can guarantee the types of individual fields, we can use these type guards to narrow the entire NewsItem dict:

# news/type_guards.py
from news.types import NewsItem

def guard_news_item(item: dict) -> NewsItem:
    return NewsItem(
        PK=guard_string(item.get("PK")),
        SK=guard_string(item.get("SK")),
        title=guard_string(item.get("title")),
        description=guard_optional_string(item.get("description")),
        published=guard_string(item.get("published")),
        link=guard_string(item.get("link")),
    )

The guard_string() and guard_optional_string() functions will throw if there's an issue initializing a NewsItem, so we don't need to throw a separate exception:

>>> from news.type_guards import guard_news_item
>>> guard_news_item({"PK": "News"})

Because we’re trying to create a NewsItem without all the necessary fields, guard_news_item() raises an exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/john/Code/blog-examples/dynamodb-python-type-hints/news/type_guards.py", line 34, in guard_news_item
    SK=guard_string(item.get("SK")),
  File "/home/john/Code/blog-examples/dynamodb-python-type-hints/news/type_guards.py", line 25, in guard_string
    raise TypeGuardException(
news.type_guards.TypeGuardException: Received unexpected type: expected str but received value of type <class 'NoneType'>: None

We can see in the traceback that the error is a TypeGuardException raised because SK is None. That's a required field and needs to be a string, and we'd keep getting type errors for invalid or missing values until the item we created matches NewsItem. Our NewsItem type is safe and sound!

Wrap-up

Sure, Python is a duck-typed language rather than a strictly typed language, but with a bit of upfront work, type guards and TypedDicts can add type safety to your Python AWS project by guaranteeing that your DynamoDB inputs and outputs are the types you expect.

In other words, when it comes to typing, guards give a duck teeth:

Bonus: abstracting DynamoDB logic into a controller

As a bonus, here’s an example of how I’m using this code in a project. The database logic is nicely contained in a controller class, and the class takes a DynamoDB Table instance in its constructor, so it's easy to test the controller logic using unit tests (by passing in a dynalite connection, say).

# news/controllers.py
from typing import Iterator, TypedDict

from boto3.dynamodb.conditions import Key
from mypy_boto3_dynamodb.service_resource import Table

from news.type_guards import guard_news_item
from news.types import NewsItem

class PutNewsItemsResponse(TypedDict):
    saved_item_count: int

class NewsController:
    def __init__(self, dynamo_table: Table):
        self.dynamo_table = dynamo_table

    def get_newest_news_item(self) -> NewsItem | None:
        newest_news_items = self.dynamo_table.query(
            KeyConditionExpression=Key("PK").eq("News"),
            ScanIndexForward=False,
            Limit=1,
        )["Items"]
        if not newest_news_items or not newest_news_items[0]:
            return None
        newest_item = guard_news_item(newest_news_items[0])
        return newest_item

    def put_items(self, items: Iterator[NewsItem]) -> PutNewsItemsResponse:
        saved_item_count = 0
        with self.dynamo_table.batch_writer() as batch:
            for item in items:
                batch.put_item(Item=item)
                saved_item_count += 1
        return {"saved_item_count": saved_item_count}

Technical challenges

Trojan horse CSS

(I almost wrote “Trojan horCSS” but thought better of it.)

When an HTML element says it’s contenteditable="true", it really means it. That element is so editable that it can change an entire page:

Hey! You stole my font!

What’s going on there? On pasting a table from LibreOffice Calc, a secret stylesheet sneaks onto the scene and supersedes some site-wide styling.

// The rest of this Vue.js 2.x class-based component is omitted for brevity
@Component
export default class Editor extends Vue {
  public observer?: MutationObserver = undefined

  mounted() {
   // Prevent adding script and style tags on paste
   this.observer = new MutationObserver(filterForbiddenElements)
   this.observer.observe(this.$refs.pasteBox, { childList: true })
  }

  destroy() {
    if (!this.observer) {
      return
    }
    this.observer.disconnect()
  }
}

To stop this style stick-up, I added a MutationObserver to watch for HTML being added to the paste box and remove any offending elements, like <style> and <script>.

Partial tables

Take a look at this table:

Sure, the table content is selected — but is the table selected? It’s hard to say. When I first coded Table to Markdown, selecting from just to the left of “Measurement” and just to the right of “25%” would result in HTML like this being added to the clipboard:

<th>Measurement</th>  
<th>Value</th>  
<th>Reduction</th>  
<tr>  
  <td>Max width</td>  
  <td>428px</td>  
  <td>32%</td>  
</tr>  
...

If you selected from above the table to below the table? You’d get a full <table> element, complete with a <thead> and <tbody>.

Browsers seem to have gotten better at recognizing partially-selected tables. In my testing for this post, both Firefox and Chromium add a complete <table> element to the clipboard. I could remove the code that builds a full table from a partial one, perhaps, but it's not hurting anyone.

Traffic & SEO

For me, most of the fun of publishing side projects is having numbers to look at. It’s even more fun if the numbers go up, so let’s take a look at some numbers that go up and a couple ways to steer them in that direction.

Web traffic

These numbers show visitors/users rather than page views. Why not page views? Well, I was counting each page view twice for quite a while (oops), so number of users is a more accurate metric.

First, let’s take a look at web traffic since launch. I say “launch”, but that’s not quite true. The first real mention of Table to Markdown was in this blog post from December 9, 2019. That post got a decent amount of traffic, and 41 users decided to check out a “pre-launch version” of Table to Markdown, resulting in the first little spike near the y-axis:

The next big spike is in March 2021, and although I got excited when I first saw that traffic, I’m pretty sure that was bot traffic. Let’s pretend that last spike doesn’t exist.

Take another look at that chart, and look at the numbers going up! It’s a slow and steady climb, but in a bit over a year, the site went from almost no traffic in a day to what looks to be peaks of around 150 users.

Speaking of peaks: what’s up with all those ups and downs? It looks like a chart of yo-yo distance from the ground. It turns out that there is a good reason for those peaks and valleys: weekends.

If we zoom into the four weeks ending April 14, 2021, we can see that Saturday (March 20th & 27th, April 3rd & 10th) is consistently the slowest day of the week, with Sunday right behind:

What can we learn from this? In all likelihood, people are using Table to Markdown at work. Wednesday is often slower than Monday, Tuesday, and Thursday, too. Hump day? More like slump day.

Now that we’ve seen some numbers that go up, let’s check out some more: organic search traffic.

Google traffic

Remember that graph “Users November 28, 2019 — March 31, 2021”? If we ignore that bot spike in March, the user traffic correlates well with the number of clicks per day from Google searches:

It correlates almost too well, doesn’t it? A person might think that virtually all my traffic comes from Google. Well, a person thinking that would be wrong! Well, wrong. Okay: just a little wrong.

Here are the top 8 sources user traffic as of April 14th, 2021:

1. Google (77.4%)
2. Direct (9.5%)
3. Bing (5.5%)
4. DuckDuckGo (3.4%)
5. Bing (China) (0.93%)
6. My blog (0.57%)
7. Ecosia (0.49%)
8. GitHub (0.32%)

More than three out of every four users finds Table to Markdown via Google, and almost one in ten come to the site directly (presumably by copying a link from a search engine or social media instead of clicking it).

At first glance, non-Google, non-direct traffic is coming from all over. Apart from my blog and GitHub, though, there’s sort of one source that accounts for 10% of my traffic: Bing.

Bing? Oh, right. Bing

If website users were money and Bing were a banana stand:

10% of users may not seem like a ton, but Google wasn’t always my top source of traffic. Something I didn’t expect when the site was young is that I got more traffic from Bing than I did from Google. (Good thing I submitted a sitemap to Bing Webmaster Tools!)

In the first three months after launch, I had 21 users from Google, and 34 users from Bing:

What about that other organic search traffic? Well, DuckDuckGo also uses Bing for most of its regular search results, as does Ecosia. Knowing that, Table to Markdown had 3x the traffic from Bing-powered search engines than from Google in the early days, and around 10% overall.

Don’t forget about Bing!

To “convert” or not convert

My web copy focused on “converting” from a number of sources to Markdown, but as we can see from the following impression count, most users search how to generate Markdown tables:

Because of this, my click-through rate (CTR) for queries containing “convert” is pretty solid! I was a bit penny-wise, pound-foolish in this case because I optimized for less-common search terms instead of the most common search term for my content.

Take-aways

1. Clipboard HTML can be a mangled mess, and pasting it into a content editable div can bork your site
2. Submit a sitemap to Bing Webmaster Tools
3. Use language that searchers use to describe your site and content

TL;DR? Test-driven development of DynamoDB queries is difficult, but it’s possible with dynalite.

A working example of this code can be found in my blog-examples repo.

Recently I was working on a little project recently with Python and Chalice, a serverless framework Python. I had a logic error in one of my DynamoDB queries that I didn’t catch until I deployed the project. Because I was new to using DynamoDB with Python, it took a few more deployments over an hour before I fixed the query.

Do you know what would’ve been nice? Having access to DynamoDB locally so I could have written that query using Test-Driven Development (TDD).

Why couldn’t I? Well, code used in serverless development, like with AWS Lambda, isn’t designed to run on your local machine:

Serverless is a cloud-native development model that allows developers to build and run applications without having to manage servers. (Red Hat: “What is serverless?”)

The “cloud-native” descriptor is important here. With serverless development, and Function-as-a-Service (FaaS) development specifically in this case, it’s possible to publish a function without, say, having to set up a webserver, configure a reverse proxy, and add SSL. The servers are still there, of course, but the server management is abstracted away by the cloud hosting provider.

Serverless development being cloud-native is a double-edged sword, however, because although you can build applications without administering servers by leveraging cloud development frameworks, your applications are now designed to run in a cloud environment.

What does this mean? For one, it can be difficult to run your applications on your local machine. What does that mean? Testing complicated queries in a cloud-native database like DynamoDB can be error-prone and cumbersome.

There are services to help with local serverless develoment, like LocalStack, and frameworks that make cloud development feel more like local development, like Serverless Stack, but LocalStack was overkill for me and I didn’t want to refactor my code to work with Serverless Stack. I just needed a way to test functions containing DynamoDB queries since I could test the rest of my application using mocks.

That’s where dynalite comes in.

Setup

To unit test DynamoDB locally, we’re going to use dynalite, an in-memory implementation of DynamoDB, along with boto3 for Python bindings to DynamoDB, and pytest to run the unit tests.

First, install dynalite globally:

npm install -g dynalite

or locally:

npm install -D dynalite

Then, install pytest and boto3, the AWS Python SDK:

poetry add boto3 pytest

I like to use Poetry for package and dependency management, but you could use Pipenv or pip.

Pytest config

Now that we have our dependencies installed, let’s tie things together.

To use dynalite in our unit tests, we’ll need to ensure that dynalite is running before our unit tests start. We could start dynalite in a separate terminal window before running pytest and stop that dynalite process after the tests finish, but that sounds like a lot of work. Instead, we can use a pytest fixture in a file called conftest.py:

# conftest.py
import subprocess

import boto3
from pytest import fixture

TABLE_NAME = "PersonTestTable"
DYNALITE_PORT = "4567"

@fixture(scope="session")
def dynamodb_table(request):
    proc = subprocess.Popen(
        ["dynalite", "--port", DYNALITE_PORT, "--createTableMs", "0"]
    )
    dynamodb = boto3.resource(
        "dynamodb",
        endpoint_url=f"http://localhost:{DYNALITE_PORT}",
    )

    request.addfinalizer(lambda: proc.kill())

    try:
        table = dynamodb.create_table(
            TableName=TABLE_NAME,
            KeySchema=[
                {"AttributeName": "PK", "KeyType": "HASH"},
                {"AttributeName": "SK", "KeyType": "RANGE"},
            ],
            AttributeDefinitions=[
                {"AttributeName": "PK", "AttributeType": "S"},
                {"AttributeName": "SK", "AttributeType": "S"},
            ],
            BillingMode="PAY_PER_REQUEST",
        )
        yield table
    except Exception:
        yield dynamodb.Table(TABLE_NAME)

This feature does a few things.

First, it’s scoped to the pytest session so it will be available to every test that runs in that pytest invocation:

@fixture(scope="session")
def dynamodb_table(request):

You may want to change the scope to function if you want to start with a clean database for each test.

Second, because this fixture runs dynalite in a subprocess, we need to stop that subprocess once the tests have run. To do that, the fixture includes a "finalizer", a callable that contains cleanup/teardown code (docs):

# proc is the subprocess running dynalite
request.addfinalizer(lambda: proc.kill())

Third, the fixture creates a DynamoDB table:

table = dynamodb.create_table(
    TableName=TABLE_NAME,
    KeySchema=[
        {"AttributeName": "PK", "KeyType": "HASH"},
        {"AttributeName": "SK", "KeyType": "RANGE"},
    ],
    AttributeDefinitions=[
        {"AttributeName": "PK", "AttributeType": "S"},
        {"AttributeName": "SK", "AttributeType": "S"},
    ],
    BillingMode="PAY_PER_REQUEST",
)

Finally, with what is admitedly a dirty hack, the fixture creates the table only once by wrapping the dynamodb.create_table() call in a try/except block that returns the table if there's an error creating it:

def dynamodb_table(request):
    # ...
    try:
        table = dynamodb.create_table(
            # arguments omitted for brevity
        )
        yield table
    except Exception:
        yield dynamodb.Table(TABLE_NAME)

Example

Example test using fixture:

def test_find_people_with_middle_initials(dynamodb_table):
    dynamodb_table.put_item(
        Item=dict(
            PK="Person",
            SK="123456",
            first_name="John",
            middle_initial="R",
            last_name="Franey",
        )
    )
    dynamodb_table.put_item(
        Item=dict(
            PK="Person",
            SK="234567",
            first_name="Bilbo",
            last_name="Baggins",
        )
    )
    people_with_middle_initials = find_people_with_middle_initials()
    assert len(people_with_middle_initials) == 1
    assert people_with_middle_initials[0].get("middle_initial") == "R"

Wrap-up

That’s that! With a guest appearance from the Node.js world, dynalite, it's easy to unit test DynamoDB queries in Python on your local machine.

Unit test DynamoDB in Python with pytest and dynalite was originally published in AWS Tip on Medium, where people are continuing the conversation by highlighting and responding to this story.

Part 2: Consuming Metadata

See Part I: Generating API Metadata to get caught up. This post uses the User.json metadata generated using the steps described in that post.

(Un)structured data

The idea of using API metadata in the client code isn’t revolutionary. AutoRest uses OpenAPI schemas to generate code for a number of languages, and Django REST Framework’s docs suggest using metadata to jumpstart client libraries:

API schemas are a useful tool that allow for a range of use cases, including generating reference documentation, or driving dynamic client libraries that can interact with your API.
- https://www.django-rest-framework.org/api-guide/schemas/

Whereas the first part of this post series covered generating metadata to use in a JavaScript/TypeScript client, this post makes good on that promise and uses that user metadata in a Vue frontend.

How? Well, there are a number of ways to use API metadata to power a frontend, like:

• Generating constants
• Creating type-safe forms
• Automatic form generation
• Data class generation

This blog post will cover type-safe and (mostly) automatically-generated forms.

Type-safe forms from JSON metadata

Here’s a simple Vue component containing a form to create a new user:

<template>
  <div id="app">
    <h1>User Form</h1>
    <form @submit.prevent="onSubmit">
      <label>First name</label>
      <input
        v-model="form.firstName"
      >

      <label>Last name</label>
      <input
        v-model="form.lastName"
      >

      <label>Email address</label>
      <input
        v-model="form.firstName"
      >

      <label>Username</label>
      <input
        v-model="form.username"
      >

      <button type="submit">Submit</button>
    </form>
  </div>
</template>
<script lang="ts">
import Vue from 'vue';

export default Vue.extend({
  name: 'App',

  data() {
    return {
      form: {},
    }
  },

  methods: {
    onSubmit() {
      // Pretend a user is created
    },
  },
});
</script>

Notice anything wrong with that form?

Go ahead and take a good look.

At first, it looks like a standard form, certainly. The more you look at it, however, the more you may realize how plain it is. It is unremarkable in whole and in part. There’s so little to it that it could well pass for unobjectionable. After all, there isn’t anything wrong with the form, really — but it isn’t much right with it. Although Vue considers the above form to be correctly typed, we could add a number of useful type-related improvements:

• Required fields
• Typed inputs (like input="email")
• A typed form object

Enter User metadata.

There are a number of ways to use the metadata specified in User.json (described in detail in Part I of this series) to improve this form.

Check out this typed form, and then we’ll look at how each metadata usage is an improvement over the untyped form above:

<template>
  <div id="app">
    <h1>User Form</h1>
    <form @submit.prevent="onSubmit">
      <div>
        <label v-text="userMetadata.first_name.label" />
        <input
          v-model="form[userMetadata.first_name.field_name]"
          :maxlength="userMetadata.first_name.max_length"
          :name="userMetadata.first_name.field_name"
          :required="userMetadata.first_name.required"
        >
      </div>
      <div>
        <label v-text="userMetadata.last_name.label" />
        <input
          v-model="form[userMetadata.last_name.field_name]"
          :maxlength="userMetadata.last_name.max_length"
          :name="userMetadata.last_name.field_name"
          :required="userMetadata.last_name.required"
        >
      </div>
      <div>
        <label v-text="userMetadata.email.label" />
        <input
          v-model="form[userMetadata.email.field_name]"
          :maxlength="userMetadata.email.max_length"
          :name="userMetadata.email.field_name"
          :required="userMetadata.email.required"
          :type="userMetadata.email.format"
        >
      </div>
      <div>
        <label v-text="userMetadata.username.label" />
        <input
          v-model="form[userMetadata.username.field_name]"
          :maxlength="userMetadata.username.max_length"
          :name="userMetadata.username.field_name"
          :required="userMetadata.username.required"
        >
      </div>
      <button type="submit">Submit</button>
    </form>
    <pre v-text="userMetadata" />
  </div>
</template>

<script lang="ts">
import Vue from 'vue'

import User from  './metadata/User.json'

export default Vue.extend({
  name: 'App',

  data() {
    return {
      form: {},
      userMetadata: User,
    }
  },

  methods: {
    onSubmit() {
      // Pretend a user is created
    },
  },
})
</script>

Most changes here are in the template. In the component itself, the only change is userMetadata, which is a typed object created from User.json. (To use JSON files in this way, ensure that your tsconfig.json has resolveJSONModule: true.)

The template includes these changes, all of which help the form reflect the backend user model:

• <label v-text>: Instead of specifying form labels manually, they are pulled from the user metadata.
• <input v-model>: Instead of writing a property accessor in the template, like form.firtsName, we can guarantee that the key for the user form is the same as the database field name, e.g. form[userMetadata.first_name.field_name]. Oh, and did you notice the fristName typo in that property accessor? Using the metadata for field names is more typo-proof.
• <input type>: API metadata can specify which type of input should be used for each field, like email or number. This helps prevent validation errors.
• Input validation attributes (required, maxlength): Speaking of preventing validation errors, database-level constraints for use fields are reflected in the JSON metadata, which we can use directly in <input> elements. User.json even includes pattern, so you can reuse regular expressions defined on the server in your client forms. This is a nice win because writing and maintaining regular expressions isn’t user-friendly.
• <input name>: This is a small change, but it makes it easy to select specific inputs in unit tests.

Now that we’ve got a typed form, why not take things one step further? because our metadata tells us so much about the API endpoint’s expectations, could we use that data to generate a form automatically?

Dear reader, we can.

Automatically-generated forms from JSON metadata

This is where having robust metadata really shines. With some tweaking, we can leverage our metadata as the basis for a fully-typed component with a small, maintainable template.

Take a look:

<template>
  <div id="app">
    <h1>User Form</h1>
    <form @submit.prevent="onSubmit">
      <div v-for="(inputData, inputName) in fields" :key="inputName">
        <label v-text="inputData.label" />
        <input
          v-model="form[inputName]"
          v-bind="inputData.inputAttributes"
        >
      </div>
      <button type="submit">Submit</button>
    </form>
  </div>
</template>

<script lang="ts">
import Vue from 'vue';

import User from  './metadata/User.json'

type UserForm = {
  [UserField in keyof typeof User]?: typeof User[UserField]["initial"]
}

interface InputAttributes {
  [key: string]: boolean | number | string
}

interface InputData {
  inputAttributes: InputAttributes
  label: string
}

function convertFieldMetadataToInputData(fieldMetadata: typeof User[keyof typeof User]): InputData {
  const label = fieldMetadata.label
  const inputAttributes: InputAttributes = {
    name: fieldMetadata.field_name,
    required: fieldMetadata.required,
    type: fieldMetadata.type,
  }
  // Add non-universal properties
  if ('max_length' in fieldMetadata) {
    inputAttributes.maxlength = fieldMetadata.max_length
  }
  if ('pattern' in fieldMetadata) {
    inputAttributes.maxlength = fieldMetadata.pattern
  }
  return {
    inputAttributes,
    label,
  }
}

export default Vue.extend({
  name: 'App',

  data() {
    return {
      fields: {
        [User.first_name.field_name]: convertFieldMetadataToInputData(User.first_name),
        [User.last_name.field_name]: convertFieldMetadataToInputData(User.last_name),
        [User.email.field_name]: convertFieldMetadataToInputData(User.email),
        [User.username.field_name]: convertFieldMetadataToInputData(User.username),
      },
      form: {},
    }
  },

methods: {
    onSubmit() {
      // Pretend a user is created
    },
  },
});
</script>

Although this component is a few more lines than the one preceding it, much of this logic can be removed from this component and shared across every form in your application.

Quite a bit of new is happening in the component, so let’s take a look at the important changes.

First, the form body:

<div v-for="(inputData, inputName) in fields" :key="inputName">
  <label v-text="inputData.label" />
  <input
    v-model="form[inputName]"
    v-bind="inputData.inputAttributes"
  >
</div>

Is that it? You bet. Instead of specifying every field, with a bit of work in the component, we can just loop through fields.

(I should note that this implementation works only an all-<input> form. If your form contains <select> elements, checkboxes, or radio buttons, you may need to create a separate component that will output the correct form field element.)

We’ve also added some extra type interfaces:

• UserForm uses some TypeScript magic (index types and index signatures, specifically) to generate a type that represents a user form, using the initial value from our user metadata.
• For InputAttributes, the HTML attributes we’ve specified in our metadata take one of three types: boolean for attributes such as required; the number for attributes such as maxlength; and string for attributes such as type.
• InputData is an object representing the information we need to generate our form. We use the label property for the<label> element and pass inputAttributes to <input> elements using Vue’s v-bind, like v-bind="inputAttributes". This way we don’t have to specify each prop individually.

To get usable inputAttributes, we need to map the name of the metadata field to the correct HTML attribute name. We also need to do null checking for attributes that aren’t present on every metadata node, and therefore input element. This work is handled by convertFieldMetadataToInputData.

But why do we need convertFieldMetadataToInputData in the first place?

Well, it’s because I didn’t plan ahead. If the API metadata used the strings that these HTML attributes expect, we’d be able to use them directly instead of transforming them. Shame on me for not thinking of that earlier!

Wrap-up

There we have it! With a little massaging, we’re able to generate a fully-typed form using metadata from a REST-like JSON API. This post also served as an example of how difficult it can be to keep the frontend and backend of a web application in sync — even when attempting to show a method for doing just that.

Still, if done with careful planning, leveraging API metadata can simplify SPA applications and reduce boilerplate and difficult-to-sync code in JavaScript web applications. And by “careful planning” I do mean planning that was more careful than was mine.

Happy coding!

Use TypeScript to Synchronize Django REST Framework and Vue.js was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.