High-Performance Enterprise TypeScript

Deepkit has developed a type compiler that leaves type information in place, allowing dynamic types to be computed at runtime and existing type information to be read at runtime. With this paradigm shift, completely new ways of working are possible, providing the required information for the aforementioned use cases, radically simplifying the development of complex software, and giving the code more expressiveness. It is thus possible for the first time to use the full power and expressiveness of TypeScript at runtime as well.

Based on this paradigm shift, Deepkit has developed a whole set of libraries for use cases that can be found in just about any program: Validation, Serialization, Database Abstraction, CLI parser, HTTP Router, RPC Framework, Logger, Template System, Event System and many more. The fundamental difference from other libraries is that type information is at the core of the functionality and as much TypeScript as possible should be reused at runtime, so less boilerplate needs to be written by the developer and even complex programs can be seen at a glance what they are doing. Finally, one of the key features of TypeScript is to give expression to even complex code, and Deepkit brings these expressiveness benefits to the runtime in the form of a powerful framework to now better scale application architecture with appropriate enterprise patterns.

Deepkit consists of two large areas: One is the Deepkit Libraries and the Deepkit Framework. The Deepkit Libraries are a whole family of standalone TypeScript libraries (NPM packages) that are good at one topic and are optimized, well tested, and designed to complement each other optimally. A project can use individual Deepkit libraries, or the entire Deepkit framework, which brings together all the capabilities of the libraries and complements them with additional tools such as the debugger. All together, it allows the developer to create complex, fast, and production-ready applications. Deepkit supports a wide range of use cases. From simple command-line tools (CLI programs) to web applications and micro-services to desktop or mobile applications. The code is designed to run in any known JavaScript engine (browser as well as NodeJS) and integrates beautifully with other frameworks such as Angular, React, and Vue. The claim behind Deepkit Framework is to apply clean code, SOLID principles, and enterprise design patterns to not only offer correspondingly high code quality, but to allow the user to apply them as well. Deepkit also tries to promote these same principles in its documentation and examples, but does not force the developer to follow them themselves.

One of the most difficult problems in software development is to maintain a high development speed even after months or years, especially when the code and the team grow. There are many frameworks that promise to get you started quickly and allow you to cobble together more complex applications on your own in a very short time. However, these usually have the common problem that the development speed decreases drastically the older the project or the larger the team becomes. It is not uncommon that even after a few months and only a handful of developers, the development speed collapses to such an extent that it drops to 1% of the original speed. To counteract this phenomenon, it is necessary to apply established design patterns and use the right framework and libraries in advance. Enterprise design patterns have established themselves for the reason that they scale excellently even with larger applications and large teams. Correctly applied, they develop their capabilities especially when a project is to be developed over a longer period of time (several months to years).

Design patterns have their advantages in theory, but in practice almost every pattern also has its disadvantages. These disadvantages vary depending on the language and framework, since the language and framework themselves determine how ergonomically a pattern can be applied. Just because a certain pattern can be used in a language, it does not mean that it automatically makes development better and faster. Some languages are better suited than others for applying certain patterns. With JavaScript or even TypeScript itself, various design patterns are often usable in the core, but there are limitations here that massively affect the user experience and thus speed. For example, Typescript decorators with all their idiosyncrasies may become necessary if a dependency injection framework specifies and is based on them. Deepkit’s runtime type system ensures that these design patterns can be applied in the most ergonomic way and with as little boilerplate as possible, unlocking their power to maintain high development speed not only initially, but also over the long term.

One of the biggest advantages of TypeScript is that complex code can be written better in many use cases. This includes frontend, backend, CLI tools, mobile and desktop apps, and much more. When a project spans these use cases and relies almost exclusively on TypeScript, it is called Isomorphic TypeScript. Using TypeScript in as much code as possible can massively increase development speed. So the following advantages are then suddenly available:

Deepkit framework and its runtime type system are designed to exploit these and more advantages of Isomorphic TypeScript to the utmost, so that its maximum powers are revealed.

Old approaches such as the dual stack (frontend and backend in different languages) can no longer keep up by far, since the context switch between the languages alone already costs an enormous amount of energy and time. All the other advantages that have already been explained even make it an unfair comparison. An isomorphic tech stack like TypeScript, properly applied, is many times faster in development time on a fundamental level than any combination of a dual stack for backend/frontend like Java/JavaScript, PHP/JavaScript, or even JavaScript/JavaScript. Since faster development speed also means less time needed for the same features, it also means that Isomorphic TypeScript saves cash. Besides all the advantages already presented, this is the killer argument to use Isomorphic TypeScript in all the next especially commercial projects.

To install Deepkit’s runtime type system two packages are needed. The type compiler in @deepkit/type-compiler and the runtime in @deepkit/type. The type compiler can be installed in package.json devDependencies, because it is only needed at build time.

Runtime type information is not generated by default. It must be set "reflection": true in the tsconfig.json file to enable it in all files in the same folder of this file or in all subfolders. If decorators are to be used, "experimentalDecorators": true must be enabled in tsconfig.json. This is not strictly necessary to work with @deepkit/type, but necessary for certain functions of other deepkit libraries and in @deepkit/framework.

file: tsconfig.json

Type decorators are normal TypeScript types that contain meta-information to change the behavior of various functions at runtime. Deepkit already provides some type decorators that cover some use cases. For example, a class property can be marked as primary key, reference, or index. The database library can use this information at runtime to create the correct SQL queries without prior code generation. Validator constraints such as MaxLength, Maximum, or Positive can also be added to any type. It is also possible to tell the serializer how to serialize or deserialize a particular value. In addition, it is possible to create completely custom type decorators and read them at runtime, in order to use the type system at runtime in a very individual way.

Deepkit comes with a whole set of type decorators, all of which can be used directly from @deepkit/type. They are designed not to come from multiple libraries, so as not to tie code directly to a particular library such as Deepkit RPC or Deepkit Database. This allows easier reuse of types, even in the frontend, although database type decorators are used for example.

The following is a list of existing type decorators. The validator and serializer of @deepkit/type and @deepkit/bson as well as Deepkit Database of @deepkit/orm used this information differently. See the corresponding chapters to learn more about this.

Since TypeScript does not include type information by default, imported types/classes from other packages (that did not use @deepkit/type-compiler) will not have type information available.

To annotate types for an external class, use annotateClass and make sure this function is executed in the bootstrap phase of your application before the imported class is used somewhere else.

MyExternalClass` can now be used in serialization functions and in the reflection API.

To following shows how to annotate generic classes:

To work directly with the type information itself, there are two basic variants: Type objects and Reflection classes. Reflection classes are discussed below. The function typeOf returns type objects, which are very simple object literals. It always contains a kind which is a number and gets its meaning from the enum ReflectionKind. ReflectionKind is defined in the @deepkit/type package as follows:

There are a number of possible type objects that can be returned. The simplest ones are never, any, unknown, void, null, and undefined, which are represented as follows:

For example, number 0 is the first entry of the ReflectionKind enum, in this case never, number 1 is the second entry, here any, and so on. Accordingly, primitive types like string, number, boolean are represented as follows:

These rather simple types have no further information at the type object, because they were passed directly as type argument to typeOf. However, if types are passed via type aliases, additional information can be found at the type object.

In this case, the name of the type alias 'Title' is also available. If a type alias is a generic, the types passed will also be available at the type object.

If the type passed is the result of an index access operator, the container and the index type are present:

Interfaces and object literals are both output as Reflection.objectLiteral and contain the properties and methods in the types array.

Index signatures are also in the types array.

Classes are similar to object literals and also have their properties and methods under a types array in addition to classType which is a reference to the class itself.

Note that the type of Reflection.propertySignature has changed to Reflection.property and Reflection.methodSignature has changed to Reflection.method. Since properties and methods on classes have additional attributes, this information can also be retrieved. The latter additionally include visibility, abstract, and default. Type objects of classes contain only the properties and methods of the class itself and not of the super-classes. This is contrary to type objects of interfaces/object-literals, which have all property signatures and method signatures of all parents resolved into types. To resolve the property and method of the super-classes, either ReflectionClass and its ReflectionClass.getProperties() (see following sections) or resolveTypeMembers() of @deepkit/type can be used.

There is a whole plethora of type objects. For example for literal, template literals, promise, enum, union, array, tuple, and many more. To find out which ones all exist and what information is available, it is recommended to import type from @deepkit/type. It is a union with all possible subtypes like TypeAny, TypeUnknonwn, TypeVoid, TypeString, TypeNumber, TypeObjectLiteral, TypeArray, TypeClass, and many more. There you can find the exact structure.

To learn in detail how Deepkit encodes and reads the type information in JavaScript, this chapter is intended. It explains how the types are actually converted into bytecode, emitted in JavaScript, and then interpreted at runtime.

The basic function of the validator is to check a value for its type. For example, whether a value is a string. This is not about what the string contains, but only about its type. There are many types in Typescript: string, number, boolean, bigint, objects, classes, interface, generics, mapped types, and many more. Due to Typescript’s powerful type system, a large variety of different types are available.

In JavaScript itself, primitive types can be parsed with the typeof operator. For more complex types like interfaces, mapped types, or generic set/map this is not so easy anymore and a validator library like @deepkit/type becomes necessary. Deepkit is the only solution that allows to validate all TypesScript types directly without any detours.

In Deepkit, type validation can be done using either the validate, is, or assert function. The function is is a so-called type guard and assert is a type assertion. Both will be explained in the next section. The function validate returns an array of found errors and on success an empty array. Each entry in this array describes the exact error code and the error message as well as the path when more complex types like objects or arrays are validated.

All three functions are used in roughly the same way. The type is specified or referenced as the first type argument and the data is passed as the first function argument.

If you work with more complex types like classes or interfaces, the array can also contain several entries.

The validator also supports deep recursive types. Paths are then separated with a dot.

Take advantage of the benefits that TypeScript offers you. For example, more complex types such as a user can be reused in multiple places without having to declare it again and again. For example, if a user is to be validated without its id, TypeScript utitilies can be used to quickly and efficiently create derived subtypes. Very much in the spirit of DRY (Don’t Repeat Yourself).

Deepkit is the only major framework that has the ability to access TypeScripts types in this way at runtime. If you want to use types in frontend and backend, types can be swapped out to a separate file and thus imported anywhere. Use this option to your advantage to keep the code efficient and clean.

A type cast (contrary to type guard) in TypeScript is not a construct at runtime, but is only handled in the type system itself. It is not a safe way to assign a type to unknown data.

The as string code is not safe. The variable data could have literally any value, for example {username: 123}, or even {}, and would have the consequence that username is not a string, but something completely different and therefore the code username.startsWith('@') will lead to an error, so that in the worst case the program crashes. To guarantee at runtime that data here has a property username with the type string, type-guards must be used.

Type guards are functions that give TypeScript a hint about what type the passed data is guaranteed to have at runtime. Armed with this knowledge, TypeScript then "narrows" the type as the code progresses. For example, any can be made into a string, or any other type in a safe way. So if there is data of which the type is not known (any or unknown), a type guard helps to narrow it down more precisely based on the data itself. However, the type guard is only as safe as its implementation. If you make a mistake, this can have severe consequences, because fundamental assumptions suddenly turn out to be untrue.

A type guard on the above used type User could look in simplest form as follows. Note that the above explained special features with NaN are not part here and thus this type guard is not quite correct.

A type guard always returns a Boolean and is usually used directly in an If operation.

Writing a separate function for each type guard, especially for more complex types, and then adapting it every time a type changes is extremely tedious, error-prone, and not efficient. Therefore, Deepkit provides the function is, which automatically provides a Type-Guard for any TypeScript type. This then also automatically takes into account special features such as the above-mentioned problem with NaN. The function is does the same as validate, but instead of an array of errors it simply returns a boolean.

A pattern that can be found more often is to return an error directly in case of incorrect validation, so that subsequent code is not executed. This can be used in various places without changing the complete flow of the code.

Alternatively, a TypeScript type assertion can be used. The assert function automatically throws an error if the given data does not validate correctly to a type. The special signature of the function, which distinguishes TypeScript type assertions, helps TypeScript to automatically narrow the passed variable.

Here, too, take advantage of the benefits that TypeScript offers you. Types can be reused or customized using various TypeScript functions.

The functions is, assert and validates return a boolean as result. To get exact information about failed validation rules, the validate function can be used. It returns an empty array if everything was validated successfully. In case of errors the array will contain one or more entries with the following structure:

The function receives as first type argument any TypeScript type and as first argument the data to validate.

Complex types such as interfaces, classes, or generics can also be used.

In addition to checking the types, other arbitrary constraints can be added to a type. The validation of these additional content constraints is done automatically after the types themselves have been validated. This is done in all validation functions like validate, is, and assert. For example, a constraint can be that a string must have a certain minimum or maximum length. These constraints are added to the actual types via the type decorators. There is a whole variety of decorators that can be used. Own decorators can be defined and used at will in case of extended needs.

With & any number of type decorators can be added to the actual type. The result, here username, can then be used in all validation functions but also in other types.

The function validate gives useful error messages coming from the constraints.

These information can be represented for example wonderfully also at a form automatically and be translated by means of the code. Through the existing path for objects and arrays, fields in a form can filter out and display the appropriate error.

An often useful use case is also to define an email with a RegExp constraint. Once the type is defined, it can be used anywhere.

Any number of constraints can be added.

Todo

The function serialize converts the passed data by default with the JSON serializer into a JSON object, that is: String, Number, Boolean, Object, or Array. The result of this can then be safely converted to a JSON using JSON.stringify.

The function deserialize converts the passed data per default with the JSON serializer into the corresponding specified types. The JSON serializer expects a JSON object, i.e.: string, number, boolean, object, or array. This is usually obtained from a JSON.parse call.

If the correct data type is already passed (for example, a Date object in the case of created), then this is taken as it is.

Not only a class, but any TypeScript type can be specified as the first type argument. So even primitives or very complex types can be passed:

By default, @deepkit/type comes with a JSON serializer and type validation for TypeScript types. You can extend this and add or remove the serialization functionality or change the way validation is done, since validation is also linked to the serializer.

In the thought of Inversion of Control (IoC) is the following alternative variant that sets the HttpClient as an explicit dependency in the constructor (also known as constructor injection).

Now UserRepository is no longer responsible for creating the HttpClient, but the user of UserRepository. This is Inversion of Control (IoC). The control has been reversed or inverted. Specifically, this code applies dependency injection, because dependencies are received (injected) and no longer created or requested. Dependency Injection is only one variant of IoC.

Besides DI, Service Locator (SL) is also a way to apply the IoC principle. This is commonly considered the counterpart to Dependency Injection, as it requests dependencies rather than receiving them. If HttpClient were requested in the above code as follows, it would be called a Service Locator pattern.

The function locator.getHttpClient can have any name. Alternatives would be function calls like useContext(HttpClient), getHttpClient(), await import("client"), or a container call like container.get(HttpClient). An import of a global is a slightly different variant of a service locator, using the module system itself as the locator:

All these variants have in common that they explicitly request the HttpClient dependency. This request can happen not only to properties as a default value, but also somewhere in the middle of the code. Since in the middle of the code means that it is not part of a type interface, the use of the HttpClient is hidden. Depending on the variant of how the HttpClient is requested, it can sometimes be very difficult or completely impossible to replace it with another implementation. Especially in the area of unit tests and for the sake of clarity, difficulties can arise here, so that the service locator is now classified as an anti-pattern in certain situations.

With Dependency Injection, nothing is requested, but it is explicitly provided by the user or received by the code. As can be seen in the example of Inversion of Control, the dependency injection pattern has already been applied there. Specifically, constructor injection can be seen there, since the dependency is declared in the constructor. So UserRepository must now be used as follows.

The code that wants to use UserRepository must also provide (inject) all its dependencies. Whether HttpClient should be created each time or the same one should be used each time is now decided by the user of the class and no longer by the class itself. It is no longer requested (from the class’s point of view) as in the case of the service locator, or created entirely by itself in the initial example. This inversion of the flow has various advantages:

But an obvious disadvantage can also be recognized directly: Do I really need to create or manage all dependencies like the HttpClient myself? Yes and No. Yes, there are many cases where it is perfectly legitimate to manage the dependencies yourself. The hallmark of a good API is that dependencies don’t get out of hand, and that even then they are pleasant to use. For many applications or complex libraries, this may well be the case. To provide a very complex low-level API with many dependencies in a simplified way to the user, facades are wonderfully suitable.

For more complex applications, however, it is not necessary to manage all dependencies yourself, because that is exactly what a so-called dependency injection container is for. This not only creates all objects automatically, but also "injects" the dependencies automatically, so that a manual "new" call is no longer necessary. There are various types of injection, such as constructor injection, method injection, or property injection. This makes it easy to manage even complicated constructions with many dependencies.

A dependency injection container (also called DI container or IoC container) brings Deepkit in @deepkit/injector or already ready integrated via app modules in the Deepkit framework. The above code would look like this using a low-level API from the @deepkit/injector package.

The injector object in this case is the dependency injection container. Instead of using "new UserRepository", the container returns an instance of UserRepository using get(UserRepository). To initialize the container statically a list of providers is passed to the function InjectorContext.forProviders (in this case simply the classes). Since DI is all about providing dependencies, the dependencies are provided to the container, hence the technical term "provider". There are various types of providers: ClassProvider, ValueProvider, ExistingProvider, FactoryProvider. All together, they allow very flexible architectures to be mapped with a DI container.

All dependencies between providers are automatically resolved and as soon as an injector.get() call occurs, the objects and dependencies are created, cached, and correctly passed either as a constructor argument (constructor injection), set as a property (property injection), or passed to a method call (method injection).

Now to exchange the HttpClient with another one, another provider (here the ValueProvider) can be defined for HttpClient:

As soon as UserRepository is requested via injector.get(UserRepository), it receives the AnotherHttpClient object. Alternatively, a ClassProvider can be used here very well, so that all dependencies of AnotherHttpClient are also managed by the DI container.

All types of providers are listed and explained in the Dependency Injection Providers section.

It should be mentioned here that Deepkit’s DI container only works with Deepkit’s runtime types. This means that any code that contains classes, types, interfaces, and functions must be compiled by the Deepkit Type Compiler in order to have the type information available at runtime. See the chapter Runtime Types.

The example of UserRepository under Inversion of Control shows that UserRepository depends on a lower level HTTP library. In addition, a concrete implementation (class) is declared as a dependency instead of an abstraction (interface). At first glance, this may seem to be in line with the object-oriented paradigms, but it can lead to problems, especially in complex and large architectures.

An alternative variant would be to convert the HttpClient dependency into an abstraction (interface) and thus not import code from an HTTP library into UserRepository.

This is called the dependency inversion principle. UserRepository no longer has a dependency directly on an HTTP library and is instead based on an abstraction (interface). It thus solves two fundamental goals in this principle:

Merging the two implementations (UserRepository with an HTTP library) can now be done via the DI container.

Since Deepkit’s DI container is capable of resolving abstract dependencies (interfaces) like this one of HttpClientInterface, UserRepository automatically gets the implementation of HttpClient since HttpClient implemented the interface HttpClientInterface. This is done either by HttpClient specifically implementing HttpClientInterface (class HttpClient implements HttpClientInterface), or by HttpClient’s API simply being compatible with HttpClientInterface. As soon as HttpClient modifies its API (for example, removes the get method) and is thus no longer compatible with HttpClientInterface, the DI container throws an error ("the HttpClientInterface dependency was not provided"). Here the user, who wants to bring both implementations together, is in the obligation to find a solution. As an example, an adapter class could be registered here that implements HttpClientInterface and correctly forwards the method calls to HttpClient.

It should be noted here that although in theory the dependency inversion principle has its advantages, in practice it also has significant disadvantages. It not only leads to more code (since more interfaces have to be written), but also to more complexity (since each implementation now has an interface for each dependency). This price to pay is only worth it when the application reaches a certain size and this flexibility is needed. Like any design pattern and principle, this one has its cost-use factor, which should be thought through before it is applied. Design patterns should not be used blindly and across the board for even the simplest code. However, if the prerequisites such as a complex architecture, large applications, or a scaling team are given, dependency inversion and other design patterns only unfold their true strength.

Since Dependency Injection in Deepkit is based on Runtime Types, it is necessary to have @deepkit/type already installed correctly. See Runtime Type Installation.

If this is done successfully, @deepkit/injector can be installed by itself or the Deepkit framework which already uses the library under the hood.

Once the library is installed, the API of it can be used directly.

To use Dependency Injection now, there are three ways.

If @deepkit/injector is to be used without the deepkit framework, the first two variants are recommended.

There are several ways to provide dependencies in the Dependency Injection container. The simplest variant is simply the specification of a class. This is also known as short ClassProvider.

This represents a special provider, since only the class is specified. All other providers must be specified as object literals.

By default, all providers are marked as singletons, so only one instance exists at any given time. To create a new instance each time a provider is deployed, the transient option can be used. This will cause classes to be recreated each time or factories to be executed each time.

In most cases, constructor injection is used. All dependencies are specified as constructor arguments and are automatically injected by the DI container.

Optional dependencies should be marked as such, otherwise an error could be triggered if no provider can be found.

An alternative to constructor injection is property injection. This is usually used when the dependency is optional or the constructor is otherwise too full. The properties are automatically assigned once the instance is created (and thus the constructor is executed).

The dependency injection container also allows configuration options to be injected. This configuration injection can be received via constructor injection or property injection.

The Module API supports the definition of a configuration definition, which is a regular class. By providing such a class with properties, each property acts as a configuration option. Because of the way classes can be defined in TypeScript, this allows defining a type and default values per property.

The configuration options domain and debug can now be used quite conveniently type-safe in providers.

The values of the options themselves can be set via configure().

Options that do not have a default value but are still necessary can be provided with a !. This forces the user of the module to provide the value, otherwise an error will occur.

By default, all providers of the DI container are singletons and are therefore instantiated only once. This means that in the example of UserRepository there is always only one instance of UserRepository during the entire runtime. At no time is a second instance created, unless the user does this manually with the "new" keyword.

However, there are various use cases where a provider should only be instantiated for a short time or only during a specific event. Such an event could be, for example, an HTTP request or an RPC call. This would mean that a new instance is created for each event and after this instance is no longer used it is automatically removed (by the garbage collector).

An HTTP request is a classic example of a scope. For example, providers such as a session, a user object, or other request-related providers can be registered to this scope. To create a scope, simply choose an arbitrary scope name and then specify it with the providers.

Once a scope is specified, this provider cannot be obtained directly from the DI container, so the following call will fail:

Instead, a scoped DI container must be created. This would happen every time an HTTP request comes in:

Providers that are also registered in this scope can now be requested on this scoped DI container, as well as all providers that have not defined a scope.

Since all providers are singleton by default, each call to get(UserSession) will always return the same instance per scoped container. If you create multiple scoped containers, multiple UserSessions will be created.

Scoped DI containers have the ability to set values dynamically from the outside. For example, in an HTTP scope, it is easy to set the HttpRequest and HttpResponse objects.

Applications using the Deepkit framework have by default an http, an rpc, and a cli scope. See respectively the chapter CLI, HTTP, or RPC.

Setup calls allow to manipulate the result of a provider. This is useful for example to use another dependency injection variant, the method injection.

Setup calls can only be used with the module API or the app API and are registered above the module.

The setupProvider method thereby returns a proxy object of UserRepository on which its methods can be called. It should be noted that these method calls are merely placed in a queue and are not executed at this time. Accordingly, no return value is returned.

In addition to method calls, properties can also be set.

This assignment is also simply placed in a queue.

The calls or the assignments in the queue are then executed on the actual result of the provider as soon as this is created. That is with a ClassProvider these are applied to the class instance, as soon as the instance is created, with a FactoryProvider on the result of the Factory, and with a ValueProvider on the Provider.

To reference not only static values, but also other providers, the function injectorReference can be used. This function returns a reference to a provider, which is also requested by the DI container when the setup calls are executed.

Abstractions/Interfaces

Setup calls can also be assigned to an interface.

Since Deepkit’s event system is based on Runtime Types, it is necessary to have @deepkit/type already installed correctly. See Runtime Type Installation.

If this is done successfully, @deepkit/event can be installed or the Deepkit framework which already uses the library under the hood.

Note that @deepkit/event for the controller API is based on TypeScript decorators and this feature must be enabled accordingly with experimentalDecorators once the controller API is used.

file: tsconfig.json

Once the library is installed, the API of it can be used directly.

At the heart of the event system are the event tokens. They are objects that define the unique event ID and the event type. An event can be triggered and an event can be listened to via an event token. Conceptually, the person who triggers the event of an event token is also the owner of this event token. The event token decides accordingly which data is available at the event and whether asynchronous event listeners are allowed.

TODO asynchronous

TODO

TODO. event.stop()

TODO

Since CLI programs in Deepkit are based on Runtime Types, it is necessary to have @deepkit/type already installed correctly. See Runtime Type Installation.

If this is done successfully, @deepkit/app can be installed or the Deepkit framework which already uses the library under the hood.

Note that @deepkit/app is based on TypeScript decorators and this feature must be enabled accordingly with experimentalDecorators.

file: tsconfig.json

Once the library is installed, the API of it can be used directly.

To create a command for your application, you need to create a CLI controller. This is a simple class that has an exeecute method and is equipped with information about the command.

File: app.ts

In the decorator @cli.controller the unique name of the CLI application is defined as the first argument. Further options like a description can be optionally added in the object at the second position.

This code is already a complete CLI application and can be started this way:

You can see that a "test" command is available. To execute this, the name must be passed as an argument:

It is also possible to make the file executable using chmod +x app.ts, so that the command ./app.ts is already sufficient to start it. Note that then a so-called Shebang is necessary. Shebang denotes the character combination #! at the beginning of a script program. In the example above this is already present: #!/usr/bin/env ts-node-script and uses the script mode of ts-node.

In this way, any number of commands can be created and registered. The unique name specified in @cli.controller should be well chosen and allows grouping of commands with the : character (e.g. user:create, user:remove, etc).

To add arguments, new parameters are added to the execute method and decorated with the @arg decorator.

If you execute this command now without specifying a name, an error will be issued:

By using --help you will get more information about the required arguments:

Once the name is passed as an argument, the execute method in TestCommand is executed and the name is passed correctly.

Flags are another way to pass values to your command. Mostly these are optional, but they don`t have to be. Parameters decorated with @flag name can be passed via --name value or --name=value.

In the help view you can see in the "OPTIONS" that a --id flag is necessary. If you enter this flag correctly, the command will receive this value.

The signature of the method execute defines which arguments or flags are optional. If the parameter is optional in the type system, the user does not have to provide it.

The same for parameters with a default value:

This also applies to flags in the same way.

All arguments and flags are automatically deserialized based on its types, validated and can be provided with additional constraints.

Thus, arguments defined as numbers are always guaranteed to be real numbers in the controller, even though the command-line interface is based on text and thus strings. The conversion happens automatically with the feature xref:serialization.adoc#serialization-loosely-conversion.

Additional constraints can be defined with the type decorators from @deepkit/type.

The type Postive in id indicates that only positive numbers are wanted. If the user now passes a negative number, the code in execute will not be executed at all and an error message will be presented.

If the number is positive, this works again as before. This additional validation, which is very easy to do, makes the command much more robust against wrong entries. See the chapter Validation for more information.

To describe a flag or argument, @flag.description or @arg.description can be used respectively.

In the help view, this description appears after the flag or argument:

The exit code is 0 by default, which means that the command was executed successfully. To change the exit code, a number other than 0 should be returned in the exucute method.

The class of the command is managed by the DI Container, so dependencies can be defined that are resolved via the DI Container.

Since CLI programs in Deepkit are based on Runtime Types, it is necessary to have @deepkit/type already installed correctly. See Runtime Type Installation.

If this is done successfully, @deepkit/app can be installed or the Deepkit framework which already uses the library under the hood.

Note that @deepkit/http for the controller API is based on TypeScript decorators and this feature must be enabled accordingly with experimentalDecorators once the controller API is used.

file: tsconfig.json

Once the library is installed, the API of it can be used directly.

The functional API is based on functions and can be registered via the router registry, which can be obtained via the DI container of the app.

The router registry can also be obtained in Event Listener or in the bootstrap, so that based on modules, configurations and other providers various routes are registered.

Once modules are used, functional routes can also be provided dynamically by modules.

See Framework Modules to learn more about App Modules.

The controller API is based on classes and can be registered via the App-API under the option controllers.

Once modules are used, controllers can also be provided by modules.

To provide controllers dynamically (depending on the configuration option, for example), the process hook can be used.

See Framework Modules to learn more about App Modules.

If Deepkit Framework is used, an HTTP server is already built in. However, the HTTP library can also be used with its own HTTP server without using the Deepkit framework.

todo: fetch API, validation, and cast.

Routes can be given a unique name that can be referenced when forwarding. Depending on the API, the way a name is defined differs.

From all routes with a name the URL can be requested by Router.resolveUrl().

The router functions as well as the controller classes and controller methods can define arbitrary dependencies, which are resolved by the dependency injection container. For example, it is possible to conveniently get to a database abstraction or logger.

For example, if a database has been provided as a provider, it can be injected:

Functional API:

Controller API:

See Dependency Injection for more information.

All of the following input variations function in the same way for both the functional and the controller API. They allow to read data from an HTTP request in a type-safe and decoupled way. This leads not only to significantly increased security, but also easier unit testing, since, strictly speaking, not even an HTTP request object needs to exist to test the route.

All parameters are automatically converted (deserialized) to the defined TypeScript type and validated. This is done via the @deepkit/type package and its Serialization and Validation features.

For simplicity, all examples with the functional API are shown below.

Validation in an HTTP server is a mandatory functionality, because almost always work with data that is not trustworthy. The more places data is validated, the more stable the server is. Validation in HTTP routes can be conveniently used via types and validation constraints and is checked with a highly optimized validator from @deepkit/type, so there are no performance problems in this regard. It is therefore highly recommended to use these validation capabilities as well. Better one time too much, than one time too little.

All inputs such as path parameters, query parameters, and body parameters are automatically validated for the specified TypeScript type. If additional constraints are specified via @deepkit/type types, these are also checked.

See Validation for more information on this.

A route can return various data structures. Some of them are handled in a special way, such as redirects and templates, and others, such as simple objects, are simply sent as JSON.

All HTTP controllers and functional routes are managed within the http dependency injection scope. HTTP controllers are instantiated accordingly for each HTTP request. This also means that both can access providers registered for the http scope. So additionally HttpRequest and HttpResponse from @deepkit/http are usable as dependencies. If Deepkit Framework is used, SessionHandler from @deepkit/framework is also available.

It can be useful to place providers in the http scope, for example to instantiate services for each HTTP request. Once the HTTP request has been processed, the http scoped DI container is deleted, thus cleaning up all its provider instances from the garbage collector (GC).

See Dependency Injection Scopes to learn how to place providers in the http scope.

The HTTP module is based on a workflow engine that provides various event tokens that can be used to hook into the entire process of processing an HTTP request.

The workflow engine is a finite state machine that creates a new state machine instance for each HTTP request and then jumps from position to position. The first position is the start and the last one the response. Additional code can be executed in each position.

Each event token has its own event type with additional information.

Since all HTTP events are based on the workflow engine, its behavior can be modified by using the specified event and jumping there with the event.next() method.

The HTTP module uses its own event listeners on these event tokens to implement HTTP request processing. All these event listeners have a priority of 100, which means that when you listen for an event, your listener is executed first by default (since the default priority is 0). Add a priority above 100 to run after the HTTP module’s event listeners.

For example, suppose you want to catch the event when a controller is invoked. If a particular controller is to be invoked, we check if the user has access to it. If the user has access, we continue. But if not, we jump to the next workflow item accessDenied. There, the procedure of an access-denied is then automatically processed further.

HTTP middlewares allow you to hook into the request/response cycle as an alternative to HTTP events. Its API allows you to use all middlewares from the Express/Connect framework.

Middleware A middleware can either be a class (which is instantiated by the dependency injection container) or a simple function.

Router supports a way to resolve complex parameter types. For example, given a route such as /user/:id, this id can be resolved to a user object outside the route using a resolver. This further decouples HTTP abstraction and route code, further simplifying testing and modularity.

The decorator in @http.resolveParameter specifies which class is to be resolved with the UserResolver. As soon as the specified class User is specified as a parameter in the function or method, the resolver is used to provide it.

If @http.resolveParameter is specified at the class, all methods of this class get this resolver. The decorator can also be applied per method:

Also, the functional API can be used:

The User object does not necessarily have to depend on a parameter. It could just as well depend on a session or an HTTP header, and only be provided when the user is logged in. In RouteParameterResolverContext a lot of information about the HTTP request is available, so that many use cases can be mapped.

In principle, it is also possible to have complex parameter types provided via the Dependency Injection container from the http scope, since these are also available in the route function or method. However, this has the disadvantage that no asynchronous function calls can be used, since the DI container is synchronous throughout.

As soon as a project uses TypeScript in the client (mostly frontend) and server (backend), it is called Isomorphic TypeScript. A type-safe RPC framework based on TypeScript’s types is then particularly profitable for such a project, since types can be shared between client and server.

To take advantage of this, types that are used on both sides should be swapped out into a separate file or package. Importing on the respective side will then merge them again.

The interface UserControllerApi acts here as a contract between client and server. The server must implement this correctly and the client can consume it.

Backward compatibility can be implemented in the same way as for a normal local API: either new parameters are marked as optional or a new method is added.

While it is also possible to directly import UserController via import type { UserController } from './server.ts, this has other disadvantages like no support for nominal types (which means that class instances cannot be checked with instanceof).

Since Deepkit RPC is based on Runtime Types, it is necessary to have @deepkit/type already installed correctly. See Runtime Type Installation.

If this is done successfully, @deepkit/rpc can be installed or the Deepkit framework which already uses the library under the hood.

Note that controller classes in @deepkit/rpc are based on TypeScript decorators and this feature must be enabled accordingly with experimentalDecorators.

The @deepkit/rpc package must be installed on the server and client if both have their own package.json.

To communicate with the server via TCP, the @deepkit/rpc-tcp package must be installed in the client and server.

For a WebSocket communication it needs the package on the server as well. The client in the browser, on the other hand, uses WebSocket from the official standard.

As soon as the client is to be used via WebSocket in an environment where WebSocket is not available (for example NodeJS), the package ws is required in the client.

Below is a fully functional example based on WebSockets and the low-level API of @deepkit/rpc. Once the Deepkit framework is used, controllers are provided via app modules and no RpcKernel is instantiated manually.

file: server.ts

file: client.ts

The "Procedure" in Remote Procedure Call is also called Action. Such an action is defined as a method in a class and marked with the @rpc.action decorator. The class itself is marked as controller by the @rpc.controller decorator and assigned a unique name. This name is then referenced in the client to address the correct controller. Any number of controllers can be defined and registered.

Only methods that are also marked as @rpc.action() can be accessed by a client.

Types must be explicitly specified and cannot be inferred. This is important because the serializer needs to know exactly what the types are in order to convert them to binary data (BSON) or JSON.

The normal flow in RPC is that the client can perform functions on the server. However, it is also possible in Deepkit RPC for the server to perform functions on the client. To allow this, the client can also register a controller.

TODO

The controller classes are managed by the dependency injection container of @deepkit/injector. When the Deepkit framework is used, these controllers automatically have access to the module’s providers that deploy the controller.

Controllers are instantiated in the Deepkit framework in the dependency injection scope rpc so that all controllers automatically have access to various providers from this scope. These additional providers are HttpRequest (optional), RpcInjectorContext, SessionState, RpcKernelConnection, and ConnectionWriter.

However, as soon as a RpcKernel is instantiated manually, a DI container can also be passed there. The RPC controller is then instantiated via this DI container.

See Dependency Injection to learn more.

When data is received on the client from the function call, it was previously serialized on the server and then deserialized on the client. If classes are now used in the return type of the function, they are reconstructed in the client, but lose their nominal identity and all methods. To counteract this behavior, classes can be registered as nominal types via a unique ID. This should be done for all classes used in an RPC API.

To register a class it is necessary to use the decorator @entity.name('id').

As soon as this class is now used as the result of a function, its identity is preserved.

RPC functions can throw errors. These errors are forwarded to the client by default and thrown again there. If custom error classes are used, their nominal type should be enabled. See RPC Nominal Types.

By default, all RPC functions can be called from any client. Also the feature Peer-To-Peer communication is activated by default. To be able to set exactly which client is allowed to do what, the class RpcKernelSecurity can be overridden.

To use this either the RpcKernel is passed an instance of it:

Or in the case of a Deepkit Framework application the class RpcKernelSecurity is overwritten with a provider.

TODO

Deepkit RPC supports several transport protocols. WebSockets is the protocol that has the best compatibility (since browsers support it) while supporting all features like streaming. TCP is usually faster and is great for communication between servers (microservices) or non-browser clients.

Deepkit’s RPC HTTP protocol is a variant that is particularly easy to debug in the browser, as each function call is an HTTP request, but has its limitations such as no support for RxJS streaming.

TODO

Since Deepkit ORM is based on Runtime Types, it is necessary to have @deepkit/type already installed correctly. See Runtime Type Installation.

If this is done successfully, @deepkit/orm itself and a database adapter can be installed.

If classes are to be used as entities, experimentalDecorators must be enabled in tsconfig.json:

Once the library is installed, a database adapter can be installed and the API of it can be used directly.

Primarily the Database object is used. Once instantiated, it can be used throughout the application to query or manipulate data. The connection to the database is initialized lazy.

The Database object is passed an adapter, which comes from the database adapters libraries.

An entity is either a class or object literal (interface) and always has a primary key. The entity is decorated with all necessary information using type decorators from @deepkit/type. For example, a primary key is defined as well as various fields and their validation constraints. These fields reflect the database structure, usually a table or a collection.

Special type decorators such as Mapped<'name'> can also be used to map a field name to another name in the database.

A session is something like a unit of work. It keeps track of everything you do and automatically records the changes whenever commit() is called. It is the preferred way to execute changes in the database because it bundles statements in a way that makes it very fast. A session is very lightweight and can easily be created in a request-response lifecycle, for example.

Add new instance to the session with session.add(T) or remove existing instances with session.remove(T). Once you are done with the Session object, simply dereference it everywhere so that the garbage collector can remove it.

Changes are automatically detected for entity instances fetched via the Session object.

A query is an object that describes how to retrieve or modify data from the database. It has several methods to describe the query and termination methods that execute them. The database adapter can extend the query API in many ways to support database specific features.

You can create a query using Database.query(T) or Session.query(T). We recommend Sessions as it improves performance.

Relationships allow you to connect two entities in a certain way. This is usually done in databases using the concept of foreign keys. Deepkit ORM supports relations for all official database adapters.

A relation is annotated with the Reference decorator. Normally a relation also has a reverse relation, which is annotated with the BackReference type, but is only needed if the reverse relation is to be used in a database query. Back references are only virtual.

Events are a way to hook into Deepkit ORM and allow you to write powerful plugins. There are two categories of events: Query events and Unit-of-Work events. Plugin authors typically use both to support both ways of manipulating data.

Events are registered via Database.listen with an event token. It is also possible to register short-lived event listeners on sessions.

A transaction is a sequential group of statements, queries, or operations such as select, insert, update, or delete that are executed as a single unit of work that can be committed or rolled back.

Deepkit supports transactions for all officially supported databases. By default, no transactions are used for any query and database session. To enable transactions, there are two main methods: sessions and callback.

Composite Primary-Key means, an entity has several primary keys, which are automatically combined to a "composite primary key". This way of modeling the database has advantages and disadvantages. We believe that composite primary keys have huge practical disadvantages that do not justify their advantages, so they should be considered bad practice and therefore avoided. Deepkit ORM does not support composite primary keys. In this chapter we explain why and show (better) alternatives.

In your tsconfig you have to adjust the following settings: jsx and jsxImportSource.

Now you can use TSX directly in your controller.

If you return such a TSX in your route method, the HTTP content type is automatically set to text/html; charset=utf-8.

You can structure your templates the way you are used to in React. Either modularize your layout into multiple function or class components.

The template engine has automatically sanitized all variables used, so you can safely use user input directly in the template. To render dynamic HTML, you can use the html function.

The template engine tries to optimize the generated JSX code so that it is much easier for NodeJS/V8 to generate the HTML string. For this to work correctly, you should move all your components from the main app.tsx file to separate files. A structure might look like this:

Deepkit Framework is based on runtime types in Deepkit Type. Make sure that @deepkit/type is installed correctly. See Runtime Type Installation.

Make sure that all peer dependencies are installed. By default, NPM 7+ installs them automatically.

To compile your application, we need the TypeScript compiler and recommend ts-node to easily run the app.

An alternative to using ts-node is to compile the source code with the TypeScript compiler and execute the JavaScript source code directly. This has the advantage of dramatically increasing execution speed for short commands. However, it also creates additional workflow overhead by either manually running the compiler or setting up a watcher. For this reason, ts-node is used in all examples in this documentation.

Since the Deepkit framework does not use configuration files or a special folder structure, you can structure your project however you want. The only two files you need to get started are the TypeScript app.ts file and the TypeScript configuration tsconfig.json.

Our goal is to have the following files in our project folder:

file: tsconfig.json

File: app.ts

In this code, you can see that we have defined a test command using the TestCommand class and created a new application that we run directly using run(). By running this script, we start the app.

With the shebang in the first line (#!…​) we can make our script executable with the following command.

And then execute:

Now, to execute our test command, we run the following command.

In Deepkit Framework everything is now done via this app.ts. You can rename the file as you like or create more. Custom CLI commands, HTTP/RPC server, migration commands, etc are all started from this entry point.

To start the HTTP/RPC server, do the following:

To serve requests please read chapter HTTP or RPC. In chapter CLI you can learn more about CLI commands.

Via the App object starts like application.

The run() method lists the arguments and executes the corresponding CLI controller. Since FrameworkModule provides its own CLI controllers, which are responsible for starting the HTTP server, for example, these can be called via it.

The App object can also be used to access the Dependency Injection container without running a CLI controller.

Deepkit framework is highly modular and allows you to split your application into several handy modules. Each module has its own dependency injection sub-container, configuration, commands and much more. In the chapter "First application" you have already created one module - the root module. new App takes almost the same arguments as a module, because it creates the root module for you automatically in the background.

You can skip this chapter if you do not plan to split your application into submodules, or if you do not plan to make a module available as a package to others.

A module is a simple class:

It basically has no functionality at this point because its module definition is an empty object and it has no methods, but this demonstrates the relationship between modules and your application (your root module). This MyModule module can then be imported into your application or into other modules.

You can now add features to this module as you would with App. The arguments are the same, except that imports are not available in a module definition. Add HTTP/RPC/CLI controllers, services, a configuration, event listeners, and various module hooks to make modules more dynamic.

In Deepkit framework, modules and your application can have configuration options. For example, a configuration can consist of database URLs, passwords, IPs, and so on. Services, HTTP/RPC/CLI controllers, and template functions can read these configuration options via dependency injection.

A configuration can be defined by defining a class with properties. This is a type-safe way to define a configuration for your entire application, and its values are automatically serialized and validated.