Generating from MyFPL’s structure
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.
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)
- Import the generated types from the
packages/my-fpl/src/gen/MyFPL.g.tsfile, but grouped together as part of aMyFPLalias. This means we don’t need to separately mention any type we need to refer to later. - Define the
isLiteraltype predicate, which takes an AST node – of the generalINodeBasetype – and returns whethernodeis ofLiteraltype. Thenode is myFPL.Literalnotation not only means that the effective return type of this function isboolean, but also that the TypeScript compiler can narrow the type ofnodetoLiteralin every code path whereisLiteralreturnedtrue. - For every non-abstract class that implements the
Literalinterface, perform aninstanceof-check. Currently, that’s onlyBooleanLiteral, but in the future, we’ll have – potentially: many – more. As soon as that happens, we’ll join allinstanceof-checks together using the||logical or operator.
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)
- Compute a list of all classifiers in MyFPL’s structure. Be sure to import
Classifiertype from@lionweb/core, and themyFplStructurefromstructure.ts. - Instantiate a
Mapthat will map classifiers to lists of their specializations, i.e.: their subtypes. - Initialize the map to have an entry for every of MyFPL’s classifiers, with empty arrays
[]as values. - Loop over all classifiers (again), and for each compute their supertypes using the
inheritsDirectlyFromfunction — to be imported from@lionweb/core. Theclassifieris now a specialization of each of those supertypes. Loop over those supertypes, and for each: - If the
supertypeis a key in the specialization map, add theclassifierto the list of specializations of thesupertype. - If the
supertypeis not a key in that map, thensupertypeis 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)
- Define a function to generate the code for a type predicate for a given
Interfaceinstance. Import theInterfacetype from@lionweb/core. We postfix “interface” with an underscore to make it a valid TypeScript identifier. - Define a local function to generate a code fragment that checks whether
nodeis an instance of the givenspecialization. - If
specializationis a LionCoreInterface, we have to use the type predicate corresponding to thespecialization, assuming it’s generated as well. - If
specializationis not a LionCoreInterface, we may assume that it’s aConcept, and that a corresponding class is generated for it. That means we can use theinstanceof-operator, pointing to that corresponding class as its right-hand side. - Obtain the interface’s specializations (again using the
!operator). - Re-order those specializations: first all non-interfaces (so
Concepts andAnnotations), and then all interfaces. This is necessary because TypeScript refuses to compile mixtures ofnode instanceof <class>andis<Interface>(node)joined by||. - Return code lines as an array of strings.
- Generate the definition of the type predicate as a function with its signature.
- Generate the instance check for the first item of
orderedSpecializations. - Generate the instance check for the remaining items of
orderedSpecializations, prefixing these with||, each on a separate, indented line. - 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)
- Compute a list of interfaces by selecting – i.e.: filtering using the
Array.filterfunction – them from theclassifiersconstant. - Generate the lines of code for the type predicate function of each interface, in alphabetical order of the interfaces’ names. Because the
typePredicateFunctionfunction returns an array of strings, we useArray.flatMapto concatenate these string arrays into one array. Then, we use the…array spread operator to inject that array into thetsLinesarray. - Write all lines of code, joined by newlines, to the
packages/my-fpl/src/reflection.g.tsfile. We use theEOLconstant fromnode:osto produce OS-dependent newlines.
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)
- Compute a list of all – i.e.: non-abstract – concrete concepts, by filtering the
classifiersconstant accordingly. (This would be the same as computing all concrete classifiers and then removing the annotations.) - 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)
- Compute a list of “standalone and concrete” classifiers, according to the following steps:
- From all language entities in MyFPL’s structure, select all concrete classifiers using the
isConcretefunction imported from@lionweb/core. A classifier is concrete if it’s instantiable, i.e.: not an interface, nor an abstract concept. - From the concrete classifiers, select all that are standalone in the sense that they’re not a subtype of any of the
interfaces. - We check the latter condition by looping over all interfaces and asserting that for every interface, the
classifierunder scrutiny isn’t among that the specializations of that interface. - Generate a comment block listing all standalone, concrete classifiers, again in alphabetical order of the classifiers’ names.
- For convenience, we prefix (the names of) all annotations with the
@character. We need (to import) theAnnotationtype from@lionweb/corefor 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
- 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
Projectionfunction, or – later on – in the type computer and constraints checker — see e.g. blog post 11 and onwards. - 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
Programconcept (which is notValueeven though it contains them), and theReductionannotation.
© 2026 Meinte Boersma (DSL Consultancy)