CHANGELOG.md

Typir Change Log

We roughly follow the ideas of semantic versioning. Note that the versions "0.x.0" probably will include breaking changes. For each minor and major version, there is a corresponding milestone on GitHub.

v0.4.0 (2025-??-??)

Linked issues and PRs for v0.4.0

New features

Breaking changes

Fixed bugs

v0.3.3 (2026-02-10)

New features

• Updated Typir-Langium to Langium v4.2.0 (#103).

v0.3.2 (2026-01-13)

Fixed bugs

• Use browser-safe isSet and isMap implementation to fix #96 (#98, #97).

v0.3.1 (2025-11-27)

New features

• The TypeScript type of properties for custom types might use undefined now (#94).
• Updated Typir-Langium to Langium v4.1.2 (#95).

Fixed bugs

• Initializing optional properties of custom types with undefined failed, as reported in #77 (#94).
• When checking the equality of custom types, the values for the same property might have different TypeScript types, since optional properties might be set to undefined (#94).

v0.3.0 (2025-08-15)

Linked issues and PRs for v0.3.0

New features

• New example how to use Typir (core) for a simple expression language with a handwritten parser (#59)
• New API to support custom types, i.e. types which are not predefined by Typir, but are created by users of Typir and tailored to the current language (#73):
  • Supports custom properties with arrays, sets, maps, primitives and types
  • Create a new CustomKind and use it to create corresponding CustomTypes, which support the desired custom properties in TypeScript-safe way
  • Type-specific names, user representations, inference rules and validation rules
  • Specific rules for conversion and sub-type which are applied to all custom types
  • Builtin support for dependencies between probably delayed (custom) types and unique custom types
  • See some examples in packages/typir/test/kinds/custom/custom-matrix.test.ts and packages/typir/test/kinds/custom/custom-restricted.test.ts
• If you try to create a function type, class type or custom type a second time, the existing implementation already ensured, that the already existing type is reused and no new type is created (#73):
  • For the type-specific inference rules, there is now an additional property skipThisRuleIfThisTypeAlreadyExists (in InferCurrentTypeRule) to control, whether these given inference rules for the "second new type" should be added to the existing type or whether they should be skipped.
  • The default value is false, meaning that these type-specific inference (and validation) rules are attached to the existing type. That conforms to the behaviour before introducing this new property.
• Create Typir services with additional services, which are specific for the current application (#78):
  • Typir core: createTypirServicesWithAdditionalServices<..., AdditionalServices>(Module<AdditionalServices>, ...), see customization-example.test.ts for examples and explanations
  • Typir-Langium: createTypirLangiumServicesWithAdditionalServices<..., AdditionalServices>(..., Module<AdditionalServices>, ...) works in the same way
  • Internal testing in Typir (core): createTypirServicesForTestingWithAdditionalServices<AdditionalServices>(Module<AdditionalServices>, ...)
• The $names of kinds/factories are configurable now (#78).
• Typir-Langium: The Langium services are stored in the TypirLangiumAddedServices now as services.langium.LangiumServices in order to make them available for all Typir services (#78).
• The <LanguageType> generic is replaced by <Specifics extends TypirSpecifics> (in Typir-Langium: <Specifics extends TypirLangiumSpecifics>) everywhere in order to support multiple, customizable TypeScript types in the Typir API (#90):

  • LanguageType is now part of TypirSpecifics and is usable with <TypirSpecifics['LanguageType']>:

    export interface TypirSpecifics {
       LanguageType: unknown;
    }

  • TypirLangiumSpecifics extends the Typir specifics for Langium, concretizes the language type and enables to register the available AST types of the current Langium grammar as AstTypes:

    export interface TypirLangiumSpecifics extends TypirSpecifics {
        LanguageType: AstNode;
        AstTypes: LangiumAstTypes;
    }

  • It is possible to customize the ValidationMessageProperties now, which is used to provide the Langium-specific validation properties in Typir-Langium, e.g. to support code actions for validation issues reported by Typir (see lox-type-checking-operators.test.ts for LOX).

• Inside the predefined validations for classes and functions, protected methods are extracted which create the actual validation hints in order to ease their customization by overriding (#90).
• Updated Typir-Langium to Langium v4.0 (#90)

Breaking changes

• Typir-Langium: LangiumLanguageNodeInferenceCaching and DefaultLangiumTypeCreator use the TypirLangiumServices parameter to retrieve the LangiumSharedCoreServices now (#78).
• The <LanguageType> generic is replaced by <Specifics extends TypirSpecifics> (in Typir-Langium: <Specifics extends TypirLangiumSpecifics>) everywhere (see details above) (#90).
• Moved some utilities for testing, requiring to update their imports (#90):
  • Moved utilities from test-utils.ts to predefined-language-nodes.ts
  • Moved test-utils.ts into the folder packages/typir/src/test/
• The TypeSelector is renamed to TypeDescriptor (and BasicTypeDescriptor, TypeDescriptorForCustomTypes are renamed accordingly) (#90).

Fixed bugs

• Clear edges from invalid types, which are never added into the type graph (#73)
• The properties of all types are readonly now (#73)
• The logic to ensure that types are not created multiple times needs to check that the kind of the types is the same. Otherwise a collision of duplicated identifiers of types needs to be reported (#78).
• Specified sub-super-relationships of language keys for the predefined test fixtures in predefined-language-nodes.ts (#78)
• Fixed the implementation for merging modules for dependency injection (DI), it is exactly the same fix from Langium, since we reused its DI implementation (#79).

v0.2.2 (2025-08-01)

• Fixed wrong imports of assertUnreachable (#86)
• Copy instead of reuse arrays with language keys to prevent side effects (#87)
• Updated Typir-Langium to Langium v3.5 (#88)

v0.2.1 (2025-04-09)

• Export test-utils.ts which are using vitest via the new namespace 'typir/test' in order to not pollute production code with vitest dependencies (#68)

v0.2.0 (2025-03-31)

Linked issues and PRs for v0.2.0

New features

• Users of Typir are able to explicitly define sub-type relationships via the SubTypeService.markAsSubType(subType, superType) now (#58)
• Arbitrary paths of implicit conversion and sub-type relationships are considered for assignability now (#58)
• Control the behaviour in case of multiple matching overloads of functions (and operators) (#58)
• Moved the existing graph algorithms into its own dedicated service in order to reuse and to customize them (#58)
• New service LanguageService to provide Typir some static information about the currently type-checked language/DSL (#64)
• Associate validation rules with language keys for an improved performance (#64)
• Typir-Langium: new API to register validations to the $type of the AstNode to validate, e.g. addValidationsRulesForAstNodes({ ReturnStatement: <ValidationRule1>, VariableDeclaration: <ValidationRule2>, ... }), see (L)OX for some examples (#64)
• Associate inference rules with language keys for an improved performance (#64)
• Typir-Langium: new API to register inference rules to the $type of the AstNode to validate, e.g. addInferenceRulesForAstNodes({ MemberCall: <InferenceRule1>, VariableDeclaration: <InferenceRule2>, ...}), see (L)OX for some examples (#64)
• Thanks to the new chaining API for defining types (see corresponding breaking changes below), they can be annotated in TypeScript-type-safe way with multiple inference rules, e.g. multiple inference rules for class literals with typir.factory.Classes.create({...}).inferenceRuleForClassLiterals({...}).inferenceRuleForClassLiterals({...}).finish(); (#64).
• Provide new expectValidationIssues*(...) utilities for developers to ease the writing of test cases for Typir-based type systems (#64).
• Create the predefined validations using the factory API, e.g. typir.factory.Functions.createUniqueFunctionValidation() and typir.factory.Classes.createNoSuperClassCyclesValidation(), see LOX for examples. Benefits of this design decision: the returned rule is easier to exchange, users can use the known factory API with auto-completion (no need to remember the names of the validations) (#64)
• Updated Typir-Langium to Langium v3.4 (#65)

Breaking changes

• TypeConversion.markAsConvertible accepts only one type for source and target now in order to simplify the API (#58): Users need to write for loops themselves now
• Methods in listeners (TypeGraphListener, TypeStateListener) are prefixed with on (#58)
• Reworked the API of validation rules to create validation issues: Instead of returning ValidationProblems, they need to be given to the ValidationProblemAcceptor now, which is provided as additional argument inside validation rules (#64).
• Reworked the API to add/remove validation rules in the ValidationCollector service (#64):
  • Additional arguments need to be specified with an options object now
  • Unified validation API by renaming and defining ValidationRule = ValidationRuleFunctional | ValidationRuleLifecycle and removed dedicated add/removeValidationRuleWithBeforeAndAfter methods accordingly
• Reworked the API to add/remove rules for type inference in the TypeInferenceCollector service (#64):
  • Additional arguments need to be specified with an options object now
• Reworked the APIs to create types by introducing a chaining API to define optional inference rules. Don't forget to call .finish(); at the end in order to complete the definition and to create the defined type! Typir will not inform you about forgotten calls of finish()! This counts for all provided type factories (#64).
• Validations for the types of the arguments for function (and operator) calls need to be explicitly requested with the new property validateArgumentsOfCalls in the inference rules for calls now. In previous versions, these validations were active by default (#64).
• The default Typir module was provided as const DefaultTypirServiceModule, now it is provided as function createDefaultTypirServiceModule() (#64).
• Most parts of Typir have the additional <LanguageType> generic in order to replace unknown by your current LanguageType (#64).
  • Use the base type of your AST node implementations as LanguageType, e.g. AstNode in Typir-Langium or TestLanguageNode for the internal test cases of Typir.
  • Therefore, your LanguageType might need to be sometimes specified, e.g. for createDefaultTypirServiceModule<LanguageType>(...) and createTypirServices<LanguageType>(...).
• The management of services, modules and instantiations in Typir-Langium is reworked (#65):
  • The Langium-specific service TypeCreator is moved into the new group langium, which groups all new Langium-specific services.
  • Typir modules which are specific for Langium have the new generic type <AstTypes extends LangiumAstTypes> now, the expected AstTypes are generated by Langium in the ast.ts files, e.g. use <LoxAstType> in the LOX example.
  • The LangiumTypeCreator interface is split into two services: The new one is called LangiumTypeSystemDefinition and contains the definitions of the language-specific type system (this simplifies the definition of the type system, see e.g. ox-type-checking.ts and lox-type-checking.ts). The existing LangiumTypeCreator service focuses on integrating the LangiumTypeSystemDefinition into the Langium build infrastructure only.
  • Use the new utility createTypirLangiumServices(...) to integrate Typir-Langium into your Langium module (which is usually done in *-module.ts). The existing utility createLangiumModuleForTypirBinding is removed.
  • Some renamings in typir-langium.ts: createDefaultTypirLangiumServices() to createDefaultTypirLangiumServicesModule(), TypirLangiumServices to TypirLangiumAddedServices, LangiumServicesForTypirBinding to TypirLangiumServices
• Renamed utility function createDefaultTypirServiceModule to createDefaultTypirServicesModule in typir.ts (#65).
• Renamed the test utility assertType to assertTypirType in order to prevent accidental name collisions with assertType from vitest (#65).

Fixed bugs

• Clear the cache for inferred types, when an inference rule is removed, since the inferred type might be produced by the removed inference rule (#64).
• Remove removed functions from its internal storage in FunctionKind (#64).
• Update the returned function type during a performance optimization, when adding or removing some signatures of overloaded functions (#64).
• When inferring the types of accessing fields of classes, the properties filter and match were ignored (#64).
• The inference logic in case of zero arguments (e.g. for function calls or class literals) was not accurate enough (#64).

v0.1.2 (2024-12-20)

• Replaced absolute paths in READMEs by relative paths, which is a requirement for correct links on NPM
• Edit: Note that the tag for this release was accidentally added on the branch jm/v0.1.2, not on the main branch.

v0.1.1 (2024-12-20)

• Improved the READMEs in the packages typir and typir-langium.
• Improved the CONTRIBUTING.md.
• Improved source code for Tiny Typir in api-example.test.ts.

v0.1.0 (2024-12-20)

This is the first official release of Typir. It serves as first version to experiment with Typir and to gather feedback to guide and improve the upcoming versions. We are looking forward to your feedback!

• Linked issues and PRs for v0.1.0
• Core implementations of the following type-checking services:
  • Assignability
  • Equality
  • Conversion (implicit/coercion and explicit/casting)
  • Type inference
  • Sub-typing
  • Validation
  • Caching
• Predefined types to reuse:
  • Primitives
  • Functions (with overloading)
  • Classes (nominally typed)
  • Top, bottom
  • (some more are under development)
  • Operators (which are mapped to Functions, with overloading)
• Application examples:
  • LOX (without lambdas)
  • OX