Hello World! tutorial

Learn the basics of CodeSquared by building your first code generator.

Before you start, make sure you

Join the CodeSquared Discord to get support if you get stuck
Install the CodeSquared and Deno VS Code extensions

In this tutorial we are going to create a TypeScript generator that converts a basic OpenAPI schema into a TypeScript fetch function. We've kept the example deliberately simple to focus on core CodeSquared concepts rather than try to address all edge cases we would do with code going into production.

Overview

The purpose of CodeSquared is to convert data representing an API schema into TypeScript code. It does this using a three phase process

Parse simplifies working with the OpenAPI schema by converting it into an OasDocument, which streamlines the structure and adds helper methods.
Generate handles the transformation from schema data into objects representing output code and assigns each to their respective file object.
Render receives the file objects, converts their contents to strings and formats them.

config.ts

HelloWorldFetch.ts

mod.ts

deno.json

schema.json

import { OperationInsertable } from './config.ts'
import type { OperationInsertableArgs } from '@skmtc/core'

export class HelloWorldFetch extends OperationInsertable {
  constructor({ context, operation, settings }: OperationInsertableArgs) {
    super({ context, operation, settings })
  }

  override toString(): string {
    return `async () => {
      const response = await fetch('${this.operation.path}');
      const data = await response.json();
      return data
    }`
  }
}

The project repo already has a hello-world-fetch folder for our generator. Let's create a file at .codesquared/hello-world-fetch/src/HelloWorldFetch.ts and insert the HelloWorldFetch transformer code.

Stringable objects

JavaScript has a powerful feature that makes CodeSquared possible. It allows us to specify how any object should be rendered to string, using the return value of its toString() method.

We refer to objects that use this pattern as Stringables and we use them to convert any value to TypeScript.

This pattern is particularly useful because it allows us to create complex structures, where each object is responsible for its own output. We can convert the entire structure to its string representation, without additional libraries, just by calling the toString() method of its root object.

Configuration

Now let's add a config.ts file to our generator. We use it to programmatically create variable names and export paths for the the code we generate.

We use the toOperationInsertable function to create a base class called OperationInsertable. Each transformer in the generator can then extend it to access its properties and outputs of its methods.

Add mod.ts file

Deno uses a mod.ts file in the root folder of a package to aggregate its exports.

Let's export the HelloWorldFetch transformer here as default to use it as the main point of entry.

Add deno.json

The last file we need to add to our generator is deno.json with our generator id, version and export path.

Run the generator

Our generator is now ready to run. To make getting started with new projects easier, we have added a CODESQUARED SETUP view to our VS Code extension. It contains a progress indicator and buttons to trigger each step.

Let's click Deploy generator stack button to deploy.

Once project is deployed, we can Create settings. This will instantiate the CODESQUARED SETTINGS view and allow us to select what output we want to generate from each generator.

Once you have created settings and selected the GET /hello-world operation, click Generate code.

The output code will appear in dist/getHelloWorld.ts