Generating from MyFPL’s structure

Share
💡
This is post 10 in my blog series on MyFPL — see the index/table of contents.

The code in this and previous blog posts can also be found here, on Codeberg. Check out the repo at the commit marked “blog 10”.

In this blog post, we’re going to generate some helper code directly from MyFPL’s structure. I consulted my crystal ball again, and it told me that that’s going to be beneficial. Specifically: it would be good to have type predicates for some of the types we generated from MyFPL’s structure (using the @lionweb/clas-core-generator package). We’ll also determine which classifiers in MyFPL’s structure are not tied to, or dependent on, any of the four central classifiers of MyFPL’s structure.

💡
TL;DR This is a long, and code-heavy blog post. Although it provides a good example of generating (additional) code from a language’s structure, it doesn’t contain essential insights into how to implement MyFPL. That means you could check out the code from the Codeberg repo, and be done with it.

Type predicates

In TypeScript, a type predicate is a function that takes one argument, and returns a boolean that asserts whether that argument is “of” – or rather: is considered to be compatible – with a certain, specific TypeScript type. This is specifically useful for types that are not classes, but interfaces or types defined through TypeScript’s type <identifier> = … construct. Such types are “transpiled away” during TypeScript compilation. As a consequence, they’re not referable/addressable at runtime, or as runtime values.

As an example, suppose we want to check whether an AST node is a Literal. This Literal type is defined (in the packages/my-fpl/src/gen/MyFPL.g.ts file) as a TypeScript interface, because in MyFPL’s structure it’s defined as an instance of LionCore’s Interface type. That means we can’t simply say node instanceof Literal: TypeScript’s instanceof-operator only works with a class as right-hand operand.

But what we can do is check that node is an instance of any of the (non-abstract) classes that implement the Literal interface. (Such classes correspond to non-abstract concepts or annotations in MyFPL’s structure that implement – either directly or indirectly – the Literal interface.) So far, there’s only one class that implements Literal: BooleanLiteral.

import { INodeBase } from "@lionweb/class-core"
import * as myFPL from "./gen/MyFPL.g.js" ➊

const isLiteral = (node: INodeBase): node is myFPL.Literal => ➋
    node instanceof myFPL.BooleanLiteral ➌

Listing 10. 1. Implementing a type predicate for Literal (in the packages/my-fpl/src/reflection.g.ts file)

  1. Import the generated types from the packages/my-fpl/src/gen/MyFPL.g.ts file, but grouped together as part of a MyFPL alias. This means we don’t need to separately mention any type we need to refer to later.
  2. Define the isLiteral type predicate, which takes an AST node – of the general INodeBase type – and returns whether node is of Literal type. The node is myFPL.Literal notation not only means that the effective return type of this function is boolean, but also that the TypeScript compiler can narrow the type of node to Literal in every code path where isLiteral returned true.
  3. For every non-abstract class that implements the Literal interface, perform an instanceof-check. Currently, that’s only BooleanLiteral, but in the future, we’ll have – potentially: many – more. As soon as that happens, we’ll join all instanceof-checks together using the || logical or operator.
💡
Type predicates have existed under various names throughout the history of TypeScript, such as “type guards”, or “type guard functions”. I’ll stick with the latest term from the official documentation.

Generating type predicates

Now, we’d like to generate the code in listing 10.1 above, because we anticipate – even without needing a crystal ball – that implementing all required type predicates is going to be tedious and error-prone, certainly while evolving MyFPL’s structure. Because of the correspondence between the classifiers in MyFPL’s structure and the TypeScript classes and interfaces generated from that structure, we’re going to work with MyFPL’s structure, rather than trying to perform some kind of reflection on the generated TypeScript code.

To generate a type predicate for a particular interface, we need to know what the specializations of that interface are. Assuming that we generate type predicates for all interfaces, we can focus on the direct specialization. We’re going to build a map mapping any interface in MyFPL’s structure to a list of its direct specializations. Further below, it’ll turn out beneficial to know what direct specializations any classifier has, so we’re going to compute a map mapping all classifiers – not just the interfaces – to their direct specialization.

const classifiers = myFplStructure.entities.filter((entity) => entity instanceof Classifier) ❶

// build a map: classifier -> the classifiers that specialize from it
const specializationMap = new Map<Classifier, Classifier[]>() ❷
for (const classifier of classifiers) { ➌
    specializationMap.set(classifier, [])
}
for (const classifier of classifiers) {
    inheritsDirectlyFrom(classifier).forEach((supertype) => { ❹
        if (specializationMap.has(supertype)) { ❺
            specializationMap.get(supertype)!.push(classifier)
        } else {
            console.info(`supertype "${supertype.name}" of classifier "${classifier.name}" in language "${classifier.language.name}" is not a classifier of MyFPL’s structure`) ❻
        }
    })
}

Listing 10. 2. Computing the specializations of all classifiers (in the packages/build/src/build.ts file)

  1. Compute a list of all classifiers in MyFPL’s structure. Be sure to import Classifier type from @lionweb/core, and the myFplStructure from structure.ts.
  2. Instantiate a Map that will map classifiers to lists of their specializations, i.e.: their subtypes.
  3. Initialize the map to have an entry for every of MyFPL’s classifiers, with empty arrays [] as values.
  4. Loop over all classifiers (again), and for each compute their supertypes using the inheritsDirectlyFrom function — to be imported from @lionweb/core. The classifier is now a specialization of each of those supertypes. Loop over those supertypes, and for each:
  5. If the supertype is a key in the specialization map, add the classifier to the list of specializations of the supertype.
  6. If the supertype is not a key in that map, then supertype is apparently a classifier in another LionWeb language than MyFPL’s structure. (Remember we initialized the map to have an entry for every classifier — in step ➌.) For completeness, we output that information on the console.

Next, we’ll implement a function that generates the code for a type predicate. More precisely, given an instance of LionCore’s Interface type, it returns an array of code lines making up the code for the type predicate for the TypeScript interface corresponding to that Interface (instance).

const typePredicateFunction = (interface_: Interface) => { ❶
    const instanceCheck = (specialization: Classifier) => ❷
        specialization instanceof Interface ❸
            ? `is${specialization.name}(node)`
            : `node instanceof myFPL.${specialization.name}` ❹
    const specializations = specializationMap.get(interface_)! ❺
    const orderedSpecializations = [ ❻
        ...(specializations.filter((classifier) => !(classifier instanceof Interface))),
        ...(specializations.filter((classifier) => classifier instanceof Interface))
    ]
    return [ ❼
        `export const is${interface_.name} = (node: INodeBase): node is myFPL.${interface_.name} =>`, ❽
        `\t${orderedSpecializations.length > 1 ? "   " : ""}${instanceCheck(orderedSpecializations[0])}`, ❾
        ...(orderedSpecializations.slice(1).map((specialization) => `\t|| ${instanceCheck(specialization)}`)), ❿
        `` ???
    ]
}

Listing 10. 3. Implement a function to generate the code for an interface’s type predicate (in the packages/build/src/build.ts file)

  1. Define a function to generate the code for a type predicate for a given Interface instance. Import the Interface type from @lionweb/core. We postfix “interface” with an underscore to make it a valid TypeScript identifier.
  2. Define a local function to generate a code fragment that checks whether node is an instance of the given specialization.
  3. If specialization is a LionCore Interface, we have to use the type predicate corresponding to the specialization, assuming it’s generated as well.
  4. If specialization is not a LionCore Interface, we may assume that it’s a Concept, and that a corresponding class is generated for it. That means we can use the instanceof-operator, pointing to that corresponding class as its right-hand side.
  5. Obtain the interface’s specializations (again using the ! operator).
  6. Re-order those specializations: first all non-interfaces (so Concepts and Annotations), and then all interfaces. This is necessary because TypeScript refuses to compile mixtures of node instanceof <class> and is<Interface>(node) joined by ||.
  7. Return code lines as an array of strings.
  8. Generate the definition of the type predicate as a function with its signature.
  9. Generate the instance check for the first item of orderedSpecializations.
  10. Generate the instance check for the remaining items of orderedSpecializations, prefixing these with ||, each on a separate, indented line.
  11. Generate an empty line.

Now, we can put the typePredicateFunction function to good use, to generate the packages/my-fpl/src/reflection.g.ts file, as follows:

const interfaces = classifiers ❶
    .filter((classifier) => classifier instanceof Interface)

const tsLines = [
    `import { INodeBase } from "@lionweb/class-core"`,
    `import * as myFPL from "./MyFPL.g.js"`,
    ``,
    ``,
    ...(nameSorted(interfaces).flatMap(typePredicateFunction)), ❷
    ``,
    // ...more code to come...
]

writeFileSync("../my-fpl/src/reflection.g.ts", tsLines.join(EOL)) ❸

Listing 10. 4. Generate the packages/my-fpl/src/reflection.g.ts file (in the packages/build/src/build.ts file)

  1. Compute a list of interfaces by selecting – i.e.: filtering using the Array.filter function – them from the classifiers constant.
  2. Generate the lines of code for the type predicate function of each interface, in alphabetical order of the interfaces’ names. Because the typePredicateFunction function returns an array of strings, we use Array.flatMap to concatenate these string arrays into one array. Then, we use the …​ array spread operator to inject that array into the tsLines array.
  3. Write all lines of code, joined by newlines, to the packages/my-fpl/src/reflection.g.ts file. We use the EOL constant from node:os to produce OS-dependent newlines.
💡
I tend to generate code in which the order of the code’s members – think: constants, types, functions – is stable. That makes it easier to compare versions of a generated code file. The easiest way to stabilize code generation is to sort those members alphabetically by their names.

Generating a list of all concrete concepts

For convenience, we compute a list of all concrete concepts.

const concreteConcepts = classifiers ❶
    .filter((classifier) => classifier instanceof Concept && !classifier.abstract)

const tsLines = [
    // ...more existing code...
    `/* concrete concepts:`,    ❷
    ...(nameSorted(concreteConcepts).map(({ name }) => `   ${name}`)),
    ` */`,
    ``,
    ``,
// ...more existing code...

Listing 10. 5. Generate the list of all concrete concepts in the packages/my-fpl/src/reflection.g.ts file (from the packages/build/src/build.ts file)

  1. Compute a list of all – i.e.: non-abstract – concrete concepts, by filtering the classifiers constant accordingly. (This would be the same as computing all concrete classifiers and then removing the annotations.)
  2. Generate a comment listing all concrete concepts, in alphabetical order of the concepts’ names.

Note that you have to look where the code in listing 10.5 needs to go in the the packages/build/src/build.ts file — it’s not a matter of simply appending it at the end!

Generating a list of standalone, concrete classifiers

By now, we’ve divided the classifiers in MyFPL’s structure into interfaces and concrete concepts. There’s one more category that may be interesting: that of “standalone”, concrete classifiers. “Standalone” means that a classifier is not a subtype/specialization of any of the interfaces. Because we’re also filtering for concreteness, we skip abstract concepts, which leaves us with classifiers that are not tied to, or dependent on, any of the four central classifiers of MyFPL’s structure: the Value, Literal, Operation, and Type interfaces.

const standaloneConcreteClassifiers = myFplStructure ❶
    .entities
    .filter(isConcrete) ❷
    .filter((classifier) => ❸
        interfaces.every((supertype) =>
            specializationMap.get(supertype)!.indexOf(classifier) === -1 ❹
        )
    )

const tsLines = [
    // ...more existing code...
    `/* standalone, concrete classifiers:`, ❺
    ...(nameSorted(standaloneConcreteClassifiers).map(
        (classifier) =>
            `   ${classifier instanceof Annotation ? "@" : ""}${classifier.name}` ❻
    )),
    ``,
    ``
// ...more existing code...

Listing 10. 7. Generate the list of standalone, concrete classifiers in packages/my-fpl/src/reflection.g.ts file (from the packages/build/src/build.ts file)

  1. Compute a list of “standalone and concrete” classifiers, according to the following steps:
  2. From all language entities in MyFPL’s structure, select all concrete classifiers using the isConcrete function imported from @lionweb/core. A classifier is concrete if it’s instantiable, i.e.: not an interface, nor an abstract concept.
  3. From the concrete classifiers, select all that are standalone in the sense that they’re not a subtype of any of the interfaces.
  4. We check the latter condition by looping over all interfaces and asserting that for every interface, the classifier under scrutiny isn’t among that the specializations of that interface.
  5. Generate a comment block listing all standalone, concrete classifiers, again in alphabetical order of the classifiers’ names.
  6. For convenience, we prefix (the names of) all annotations with the @ character. We need (to import) the Annotation type from @lionweb/core for checking for annotations.

Again, instead of simply appending the code in listing 10.7 to the the packages/build/src/build.ts file, you need to figure out where each block of code goes. In case of doubt: check the repository at commit blog10 of the main branch, or check against listing 10.8 below.

The end result

After running the generate task inside the packages/build directory, we’re rewarded with a new packages/my-fpl/src/reflection.g.ts file.

import { INodeBase } from "@lionweb/class-core"
import * as myFPL from "./MyFPL.g.js"

export const isLiteral = (node: INodeBase): node is myFPL.Literal =>
        node instanceof myFPL.BooleanLiteral

export const isOperation = (node: INodeBase): node is myFPL.Operation =>
        node instanceof myFPL.BinaryOperation

export const isType = (node: INodeBase): node is myFPL.Type =>
        node instanceof myFPL.BooleanType

export const isValue = (node: INodeBase): node is myFPL.Value =>
           isLiteral(node)
        || isOperation(node)

/* concrete concepts: ❶
   BinaryOperation
   BooleanLiteral
   BooleanType
   Program
 */

/* standalone, concrete classifiers: ❷
   Program
   @Reduction
 */

Listing 10. 8. The resulting packages/my-fpl/src/reflection.g.ts file

  1. A list of all concrete concepts. This list is purely informational, and may be helpful to check whether we handle all concrete concepts in the Projection function, or – later on – in the type computer and constraints checker — see e.g. blog post 11 and onwards.
  2. A list of all standalone, concrete classifiers. This list is purely informational. It’s quite short, and we actually expect it to remain short, because most classifiers in MyFPL’s structure would be concrete concepts that we need to handle in all four key aspects of a DSL. Currently, that’s the Program concept (which is not Value even though it contains them), and the Reduction annotation.
💡
In this blog post, we generated helper code directly from MyFPL’s structure — and also used some of it. In the next blog post, we’re going to start implementing MyFPL’s type system — which we’ll probably only finish a couple of posts later, though.

© 2026 Meinte Boersma (DSL Consultancy)