typir

Typir: Core functionality of Typir

Typir is a library for type systems and type checking for software languages in the web.

Typir is OpenSource, written in TypeScript, and follows pragmatic approaches for simplifying type checking in practical language engineering projects by providing default implementations for recurring problems. As a stand-alone library, Typir provides a TypeScript-API for language engineers without an additional, external DSL for formalizing types.

Installation

npm install typir

Documentation

For an overview about the core features of Typir with a simple application example, see the root README.md of the Typir project.

Important design decision: Typir is a stand-alone library and has no dependencies to any existing language workbench.

Examples

Look at the examples in the examples folder of the repo (here). There we have some demo projects for you to get started.

License

MIT License

Changelog

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).