Forem: andreespirela

How Mandarine Framework could surpass NestJS

andreespirela — Wed, 28 Oct 2020 20:49:36 +0000

Introduction

Mandarine is a relatively new typescript framework that runs on Deno. Its objective is very simple: to provide as many built-in functionalities as possible for application development.

Mandarine is a ready-for-production framework & one of the few packages that are production-ready, and by far, the best server-side framework in Deno

Mandarine was mainly inspired by Spring Boot & owns a big set of built-in tools for development such as Dependency Injection, Built-in authentication system, MQL (Mandarine Query Language), ORM (with MQL), Built-in session middleware, CORS middleware, and much more.

For more information about what Mandarine has and why is perhaps the best server-side framework in Deno, click here.

Mandarine & NestJS

Mandarine & NestJS are perhaps brothers from different mothers, they are really similar in terms of syntax & features, some would definitely argue Mandarine has a much better & simpler syntax than NestJS, this is because NestJS tends to adopt the Angular pattern of modules while Mandarine only cares about declarations: there's no such thing as a "module" in Mandarine.

Mandarine does not have the concept of "modules" or "providers", everything is plain declaration of ES6 classes & decorators and it's ready to be used. NestJS on the other hand, abstracts this a little bit more.

Finally, friendly reminder that Mandarine & NestJS run on different runtimes: Mandarine is for Deno while NestJS for NodeJS.

Mandarine: Richer In Functionalities

Mandarine is perhaps richer in functionalities. This does not mean that Mandarine has all the features NestJS has, not at all. This means, Mandarine has many others (and more) built-in tools that make development easier and reduce the boilerplate of many packages with only one goal: Every major functionality you would write in Mandarine should be a Mandarine-powered feature.

To explain this a little better, let's look at some of the features Mandarine has:

Built-in Authentication (No need to write the logic behind securing endpoints, or authorizing users as it is already provided)
Built-in Repositories (No need to code the logic behind database queries as Mandarine's ORM is fully powered by MQL)
MQL (Mandarine Query Language)
Session Middleware (No need to use external packages to manage sessions, as it is already built-in in Mandarine with the option to create your own session container)
CORS Middleware
Serving Static Content
X-Response-Time Header Middleware
Resource Handlers (Interceptors for different kind of static content)
Pipes
Custom Decorators

And of course, there are a few more features that are important but that is not the purpose of this post.

For more information about Mandarine's feature, visit its official documentation

Mandarine surpassing NestJS, Really?

Extraordinary claims require extraordinary evidence

Many of you may be thinking, how come a Deno framework could possibly better or more stable than a NodeJS one?
Let's start with some facts:

Deno is at version 1.5.0, and it's production ready, this has been stated even by Ryan Dahl (Creator of NodeJS & Deno)
Deno is richer in functionalities.
There is already room to argue NodeJS and Deno are both good enough for production environments, some would argue Deno is even better since it provides a set of built-in dev tools (like bundling, linting...) & typescript support as first language.

With that said, we can put Mandarine & NestJS at the same level of the discussion in terms of real-world stability.

Mandarine's Plan To Be Better... Much Better

Deno has an excellent relation with Rust, in fact, you can connect Rust-written libraries to Deno & call the methods inside those libraries through JS. When you think about it, the limit is the sky. We are talking about direct connection of a very powerful language like Rust (which some argue it's much better and simpler than C++) being called/used from a very popular language like JS. This is a key for Mandarine's plan of success.

As stated in this blog:

If Deno is not capable of providing a required feature for stability, we would use Rust again to cover these needs.

That means, Mandarine is not only a Typescript framework but will also be powered by Rust.

Why does this matter ?

Rust is a very popular language (most loved language for 4 years in a row according to Stackoverflow), it has been out there for 10 years, and we can all agree it is very very stable. As a matter of fact, Google is considering integrating it in its V8 engine (Click here for more)

Now with Deno, Rust & Mandarine, Mandarine would connect every requested feature that Deno cannot provide to its Rust core which means, Rust would provide functionalities to Mandarine thus bringing Rust's stability & Rust limitless internal processes to Mandarine (The JS/TS world).

Quick example of what this means: You want to use Mandarine to modify images, but there are no packages in Deno to do such things (nor Deno provides such functionality). It doesn't matter, Mandarine will provide you a rust application to modify images that you can call from your JS/TS application.
Of course, this is a very vague example, Mandarine's rust core is meant to go along with Mandarine's goals. But I mention this example for a better perspective on what this means.

What does this have to do with NestJS & Mandarine?

With the support of Rust, Mandarine can provide functionalities that are yet to exist in Deno & NodeJS, this will give Mandarine advantage in both runtimes.

One of the main features of NestJS (which Mandarine is missing) are microservices. Microservices in NestJS are entirely coded in Typescript (JS). On the other side, Mandarine could provide a communication-interface for microservices written in Rust but used in the JS side, thus providing performance and more stability in terms of maintenance.

Is It Happening Already?

One of the goals Mandarine has had for quiet a long time is to provide a very stable, multi-threaded, database driver not only for Deno but for its internal usage.

This week, Mandarine came out with Mandarine Postgres, a PostgreSQL rust driver that you can use from Deno which officially made Mandarine a framework with mixed codebases.

This driver makes use of tokio-postgres under the hood, a widely-used Rust driver for postgres which has been out there for more than 4 years.

This, again, is one of the examples of "What Deno can't provide, Rust can".

The End

This post is not meant to dismiss NestJS awesome work and features rather than presenting both facts & views to how Mandarine could in the future surpass NestJS in terms of functionality and perhaps stability with the Deno core.

This post is also meant to show how Deno can get to be more stable than NodeJS in some scenarios, or how packages in Deno can take advantage of Rust for the better.

The different opinions towards NestJS are just that, opinions. It is up to the reader to interpret this post. While it is true that Mandarine may be at the same level of NestJS, it is also true NestJS has been out there for much more time and it is widely used globally because of the excellent work they have done & provided to different companies around the globe.

Simple Usage

Click here to see a quick example on how to get started with Mandarine

Mandarine on social media

Reactive programming in backend

andreespirela — Wed, 07 Oct 2020 18:01:14 +0000

What are some of the use cases you would have for reactive programming in back-end. For front-end, it makes a lot of sense. I just can't see enough examples of how reactive programming is also good for back-end?

Anything you can think of?

The wait is over, Mandarine 2.0.0 is here.

andreespirela — Mon, 31 Aug 2020 13:05:09 +0000

Mandarine is an open-source typescript framework that runs on Deno. Mandarine is used to develop any type of server-side application (Mostly MVC) with the use of strong design patterns such as Dependency Injection, or the SOLID principles.

From Mandarine's website:

A minimalist, decorator-driven, MVC framework for Deno.

Mandarine is by far the best server-side framework in Deno

If you have not read this article, I highly recommend you reading it in order to have a better ground on the things that will be discussed on this version 2.0.0 presentation post & the reason why's Mandarine is perhaps the most stable framework in Deno.
Click here for the article

Rich in features

Mandarine 2.0.0 comes with a ton of built-in features that will make you life easier when it comes to back-end development. Not only these features were created to solve enterprise-level problems but also issues for small-level projects.
2.0.0 gives Mandarine a better position in front of other great frameworks such as NestJS and makes it clear there is no doubt that Mandarine is production-ready.

Without further ado, let's get to it:

Built-in Authentication System
- Mandarine provides a built-in authentication system. With this system you no more have to worry about creating endpoints such as login & logout. Or, creating the logic necessary to protect different endpoints in your application. Following Mandarine's built-in authentication guide will make your application more secure and it will all be handled by the framework, saving you not only time, but security concerns and lines of code. There is a complete guide on Mandarine's documentation page under "Mandarine Security" you will find the documentation of "Authentication". Click here to see a full example
- This system was mainly inspired by the great work of Spring Boot Framework in Java.
- This feature puts Mandarine ahead of many other typescript/javascript frameworks out there.
Pipes
- Mandarine now provides the concept of Pipes for HTTP Parameter Decorators. Pipes can process and return a new/processed value before it gets to the HTTP Handler, cleaning your data during request time without any boilerplate. Read more about Pipes here
Custom Decorators
- Mandarine now provides a decorator factory which lets you create your own HTTP Parameter Decorators. This is useful when wanting to avoid boilerplate of utility classes or helpers. The use cases of this are many, hopefully you will find one!. Read more about Custom Decorators here

Those are the main 3 features Mandarine provides in its 2.0.0 version. Although, many were included in this release such as:

Middleware targeting specific controllers or HTTP Handlers. See here
Non-component middleware. See here
Exception filters. See here
Security Expressions. See here

And many more. If you are interested in finding out a complete overview on what is new in Mandarine 2.0.0, Click here on the official release page and take a look.

Simple Usage

Click here to see a quick example on how to get started with Mandarine

Mandarine on social media

Release Page Here

Comments, question? Below.

Why Mandarine is by far the best server-side framework in Deno

andreespirela — Sat, 15 Aug 2020 13:47:09 +0000

A minimalist, decorator-driven, MVC framework for Deno.

On this post, we will cover why Mandarine is perhaps, the best server-side framework in the Deno community. I admit, it's a hot take to describe Mandarine as such, but I will defend these points throughout the post.

Deno, not NodeJS.

We have to start from this point. NodeJS as you may already know is meant to work with Javascript and yes, you can make it compatible with Typescript as well, but NodeJS itself was not created under a Typescript paradigm. Unlike Deno, Deno was fully created to support typescript out of the box, most Deno applications are written in Typescript and this will continue to be this way. As Ryan Dahl (Creator of both NodeJS & Deno) stated:

The reason I address this is because I keep seeing packages in Deno that are written in Typescript but they have the same kind of code a Javascript code could have & this is really an issue because people are just trying to think in a "Javascript way" inside a Typescript environment which definitely stops the development of more powerful features & stops the limits of our imagination in a Typescript environment. I keep seeing people coding the "equivalent" of a NodeJS package in Deno and while this may be good at some extend, I can't stand the fact that the "Javascript way" is being kept in many Deno packages.

Mandarine changes this. Mandarine takes advantage of every single feature Typescript has to offer, from generic classes inside Mandarine's core, to the use of Decorators & Metadata reflection for the creation of Mandarine-powered applications.
Mandarine tries to get as far away as possible from a Javascript thinking in a Typescript runtime. Typescript really are not just Types, Typescript has an extensive core of solutions for design-patterns and functionalities that many developers are not taking advantage of which is something Mandarine is looking forward to changing.

(A simple quickstart in Mandarine)

Strong Design Patterns

Mandarine believes in the strong use of Design Patterns as well as the benefits of Object-Oriented programming. Mandarine makes use of two important design patterns: Dependency Injection & MVC in order to provide the most SOLID development.

Mandarine is well-known because of its dependency injection system. Among only 3 frameworks that support Dependency Injection in Deno, Mandarine has perhaps the most stable approach. It allows dependency injection by both construction-based & property-based with the benefit of property-based injection not having to specify what type we are trying to inject like in Angular or NestJS where property injection needs to receive a token (type). Also, another +1 for Mandarine's dependency injection system is the fact there is no such thing as a "Module": If you come from Angular or NestJS for back-end, you will know dependencies usually go under the concept of "Module" and through Modules is the way your application communicates with other components. In Mandarine such concept does not exist since everything in Mandarine is either a Mandarine-powered component or not and so by the time you use the dependency declarator-decorators such as @Controller, @Service, @Component, @Configuration or others that component is immediately available for injection at other Mandarine-powered components. If you come from a Java environment, you probably know about Spring Boot, most likely, you have used. Mandarine uses the same concept of dependency injection that Spring Boot has.

Built-in Tools

Mandarine has a set of built-in tools that allow back-end development to be easier, not only in terms of design patterns as we mentioned before, but in terms of common features that are highly used.

Template Engine: Mandarine supports EJS & Handlebars out of the box. More about Mandarine's template engine here
Session Middleware: Mandarine has full support for session middleware (including a default in-memory implementation & the possibility to re-write this implementation). See more here
CORS Middleware: Mandarine has a CORS middleware out of the box that is not only available for endpoints but also for resources. See more here
Static Content: Mandarine has full support for static-content serving, fully customizable. See more here
Resource Handlers: Mandarine has full support for adding, overriding and creating Resource Handlers. Resource Handlers are the logic behind serving static content. The possibility to customize the behavior of this allow different interpretation and outcomes for different types of URL, for exmaple, with Resource Handlers you could add a logic to process all the .xml files and convert them to .json by the time of the request. See more here
ORM: Mandarine has a built-in ORM which takes away the complexity of writing SQL queries or the complexity of having chain-like ORM's. Mandarine brings the concept of MQL (Mandarine Query Language) to write complex queries.

Built-in ORM

Mandarine's built-in ORM is perhaps my favorite feature. It allows you to write SQL queries in the same way you would in frameworks like Spring Boot. With the concept of MQL, much of the functional (or SQL) boilerplate code is taken away.

Where

findByAirlineAndPassengerName(airline: string, passengerName: string)

is transformed into

SELECT .... WHERE airline = $1 AND passengerName = $2

# $1 = airline parameter
# $2 = passengerName parameter

Here is a clear implementation of how this works:

For more information about Mandarine's built-in ORM Click here
For more information about Mandarine's MQL Click here

Native Components

Mandarine brings the concept of Native Components to Typescript. Native components are classes that Mandarine uses as default to boost the framework. These classes usually have some sort of information related to the different behaviors of the framework. For example, in Mandarine, there is the native component WebMvcConfigurer which has the behavior of how the session container (for the session middleware) will behave, it also has information about the default resource handlers (used for serving static content). With the concept of Native Components, Mandarine allows the developer to override (through @Override) and establish custom behaviors in a OOP way, making it not only straightforward but readable in terms of lines of code to execute such thing.

See more about native components here

Decorator-driven

Many of you may know the express syntax, which is something like

new Router().get('/route', (context) => {});

This syntax is widely used in the NodeJS community as well as the Deno community. In Deno, we have several frameworks that take use this approach such as Oak or Pogo. While this approach may be found straightforward, it really sticks to the way we write javascript & as I mentioned before, I believe a Typescript ecosystem should make use of all its Typescript features, otherwise, what's the point behind using typescript really?. Mandarine takes a different view and creates your routes through the use of decorators such as @GET, @POST and so on, similar to NestJS or Spring Boot.

2.0.0

Just to make the last remark about why Mandarine is perhaps the best server-side framework by far in Deno, Mandarine has announced the list of features that will be available in version 2.0.0 (expected to land during last week of August 2020, or first two weeks of September 2020). These features include:

Native support for built-in authentication & user handling.
Custom Decorators
Exception Filters
Pipes
Guards
CRON Jobs

You can read more about these features and what they mean in this blog

Conclusion

We have deeply analyzed some of the most important features that divide Mandarine from the rest of server-side frameworks in Deno. The opinions behind whether Mandarine is really the best server-side framework in Deno will be different for every person, although we can state the fact that Mandarine accomplishes a better interaction between a modular application through enforcing principles such as SOLID or MVC. On the other hand, a opinion-driven thought is whether enforcing OOP programming and making use of all typescript features is really a good thing. Some would argue that Javascript is the way it is and it should be written that way, my take really goes to: If Javascript is what it is, why did we even invent Typescript?, and what I'm saying with this is that in a Typescript environment, you should think in a Typescript way: interpreting Typescript as only types is fundamentally wrong.

This post is not meant to cause any controversy on the different contributions people have made to Deno rather than presenting both facts & views to how Mandarine can get to solve different issues in a enterprise-like way, not only technically speaking but also theoretically speaking.

The different comparisons made to different frameworks such as Angular, NestJS, Pogo or Oak do not refer to facts rather than opinions on what a better approach looks like. While it is true that these frameworks do things the way they do it for a specific reason which has been thought by knowledgeable developers, it is also true that every approach can have a better approach which is exactly what I am dressing in the different comparisons and their final objective.

It is clear that every developer has a preference towards a coding style, some will prefer decorators, others would prefer functional-like declaration. Every opinion on the matter is of course appreciated by this post.

Want to know more about Mandarine?: Try Mandarine's quickstart example.

Thoughts? I'd like to know them, comment below.
Questions? I'd like to answer them, ask below in the comments section.

Writing a framework. PT I

andreespirela — Tue, 07 Jul 2020 16:53:31 +0000

Over the last few months of 2020, I have dedicated myself to writing MandarineTS Framework. It has been an amazing journey where I have met really knowledgeable people & have participated in the Deno community more actively.
I never thought I would be participating in such a large open source community but more than participating, I never thought I was going to collaborate in some sort of way.

Participating in Open-Source projects have been one of the most honorable experiences I have had: I have interacted with really important people in the computer science world (theoretically speaking), and this gives you not only a new way to look at your code & your reasons to code but it also opens your mind to where you want to go & offers you a better sense of how important your work can get to be.

On this post, I will be discussing the details of creating a framework: The concept & the reason, the basis of it, the core, what I have learned, what I regret, and how to maintain it.

This first part will only be about main concepts we need to know in order to create a framework. I will be posting a second and probably a third part where we will creating our own dependency injection framework.

Without further ado, let's get to it.

The Concept & The Reason

Most of the things you think you can create are already created. Under that scenario, you have to think what is your added value, for example: You may pretty well offer the same things with better performance & syntax, or you may pretty well offer new things with the same performance & same syntax. In most cases, this is not worth it. The amount of time it requires and the very little usability you may get will not make it worth it.

But let's say you have either decided to continue no matter whether it's already created, or you have an awesome idea. The first thing you need to consider and have a pretty clear perspective about is an answer for the following question: What problem are you trying to solve?. Such question will be the one to lead you to structure your framework. You need to have a pretty solid idea of what your code will be solving because before starting to code, you already need to know how your framework will be distributed, you need to consider the performance aspects, whether you will use third party libraries, the problems of your current runtime, the limitations of the language you will use, and more fundamental questions we will be reviewing.

I created Mandarine because there was nothing alike in Deno. In the case of NodeJS, Mandarine is pretty similar to NestJS, but in Deno, this was an unique opportunity to bring the MVC pattern & a decorator-driven development style as the Deno community is growing.

Basis of Creating a Framework

Now, let's get to the technical side.

When creating a framework, you need to have a deep understanding of both coding skills and fundamental skills (knowing how to code, why to code it, and the impact it has on the computer your code is running). You also need to have a deep understanding of the different environments that we have in software such as Develop environment & Production environment, this is because, if you are creating a framework, its objective will be to be used in a production environment where multiple instances (servers) and concurrent requests are constantly ongoing, this is something you need to consider how to handle when writing the first part of your code. If you leave these details out, you will regret.

Architecture

Building a framework requires an architecture, this means, you will need to think what design patterns you will use, you will need to come up with your own standards in order to have the same kind of code when collaborators join, or even for yourself. You need to establish a line between the language you are using, the runtime and your framework. You will not use all the features of the language and/or runtime you are using, and this is important because you should not use all the features, you should only use what you will be needing. Do not get fancy or hacky to do things, that really does not make your code better.

Naming conventions

You should maintain the same naming conventions across the framework. I personally like camel case, but this depends on the developer. Make sure you follow this, it will help when your code grows.

For example, Mandarine does not use a deps.ts file where all the exports of the different dependencies are located for the modules. I did it this way because every file should import the dependencies it will use, it should not use a "index" file for dependencies. if an "index" file for dependencies such as deps.ts is used, the risk of a code breaking all your modules grow. Instead, when importing manually the dependencies your file will use, you gain more control over that, and if a module breaks your application, it is easier to find the root of the cause.

The core

Every framework has a core, needs a core. Your framework will need a core too. The core is just that, a core. It will connect the basis of your framework to all the different modules, it will be responsible for loading & initializing the different components that are needed for it to work out. For example, if you are writing a dependency injection framework (DI), then your core will be responsible for creating & injecting all the instances.
The core should stick to core functionalities, for example: If your framework is to create an HTTP Server, the HTTP Dispatcher (Creation of routes, initialization of the HTTP Server, etc) should not go inside the core, instead, your framework would need a module called "http-dispatcher" that will handle this kind of things & the core will provide it with the necessary functionalities as the core will work as a bridge for your framework.

The core is the most important part of a framework as it handles everything that is needed. It will be possible the module that has more lines of code (LOC). In Mandarine, the core contains the decorators that the developer will be likely to use, the interfaces, the DI factory and the DI container, it also contains all the exceptions that are originally thrown from Mandarine & utility classes that are used across the other modules.

The Other Modules

Your framework will probably have more modules than just the core, this is where things will start getting messier. The more modules you have the more code you have, this affects performance at both compile (more time to compile your code) & runtime (it can take many resources if your code is not well-written, along with other aspects).
With that said, when having other modules than just the core, you always need to think how to make everything re-usable across your framework: You need to make everything you can a utility method or class, do not over code, do not repeat code. Try to centralize things such as Similar interfaces or similar classes, make use of generics, make use of class-extension. The cleaner your code is, the easier it will be to maintain and the better it will be for performance.

Do not framework your framework

This is something you must be really careful of. Do not use your framework's functionalities inside the core or modules of your framework. Your framework must only provide functionality to the developer who is using it, but it should not provide functionality to itself. Your framework should be written as natively as possible, meaning, as self-dependent as possible. This practice of a self-dependent framework increases testability, readability, and decrease the boilerplate and risk of breaking.

For example, Mandarine has a DI Framework, although, Mandarine does not use its DI framework inside the core, everything in Mandarine is Javascript/Typescript native.

Think globally, not for yourself.

When creating a framework, after you release the first version, you have to start thinking & assuming many people are using your framework by now. It's important to have this kind of thinking because it will make you carefully consider every single change: You do not want your framework to break other's people applications.
Avoid breaking changes as much as you can. Breaking changes can have a huge impact on other people's code. The new features you add & the bugs you fix should not alter the behavior of what is out there that people are using.
Yes, you can have breaking changes. Any project has breaking changes, in fact, breaking changes are something really common during the early versions of any program, but... avoid them.
Always your framework is being used in production, thus, you need to be thoughtful when it comes to changing the structure of something, the syntax of something, when removing a method from the code, etc.

What I have learned

Creating Mandarine has given me a lot of stories to tell, a lot of experience to be shared. One of the main things I have struggled while creating Mandarine is being consistent with design patterns & self-dependency for modules. Mandarine lacked design patterns during its first days, after several versions being released, this has improved. Mandarine's code is more consistent & has more design patterns, yet, it's still a process where I find myself always refactoring and thinking carefully what is the best approach to add a feature or solve a bug, since every single line of code can affect the consistency of the design patterns mandarine makes use of.
Another thing I would say I have learned is the importance of self-dependency modules. During the very very very early versions of Mandarine, Mandarine was hard to unit-test because all the modules had some sort of relation with the other modules, but as of right now, things have gotten easier as Mandarine is now using the proxy design pattern which wraps all core methods and functionalities in classes called Proxy, so the calls to a method are always made to the proxy and the proxy validates and then calls the requested method. This has made not only performance get better, but it has also made the code more readable and testable.

What I regret

This is an interesting questions because I don't really have regrets that can be used as a useful experience when writing a framework. But I do have to say, not everything has been pretty with Mandarine. If I could go back to when I started writing it, I would tell myself to establish design patterns because the amount of code refactoring that is coming on my way is incredible (I have refactored the whole core of Mandarine 4 times, only because I didn't consider design patterns in the beginning).
I do think I could have made a better job writing unit tests, at the very beginning I didn't write unit tests for Mandarine. It is now that Mandarine is starting to have unit tests for every of its modules, it's been a long process writing these unit tests as Mandarine has grown significantly.

How To Maintain a Open-Source Framework

When I started with Mandarine, I felt really uncertain about how to maintain an open-source framework, and sometimes I still do because there's a lot to learn everyday for everyone, for me too, the community is always evolving & you need to adapt faster every time.

Develop branch & Master Branch

Your Master branch is the branch you have to protect the most. The master branch must always, always be stable. For this, I always recommend the following:
Create two branches: Master & Develop. Your main code/last release code will be always located under Master. The code for feature releases (features, bug fixes, etc) will be always be worked on Develop. When the release is ready and develop is stable, you merge Develop into master and then you create the release from master. From there, you continue to work on develop for anything that you want following the same process. Develop can get to be unstable, master must never be unstable.

Versioning

Your versioning needs to be meaningful (MAJOR.MINOR.PATCH). You can't just release whatever number looks good, it is important to keep consistency & meaning of your versions. If something is a patch then it should affect the patch numbering, if an update includes many patches and features that affect many modules then it can be considered a minor, if there is a list of features & fixes that have been constantly released, and there is a big change that affect your framework at all levels then it can be considered a major update.
You also need to have a release plan, although this is a complex subject, the basic of it is, you need to know what each version will have, you can't just add anything to any version. You need to plan releases ahead, this way you can know what you have to code per release, you organize your framework more, it's less time consuming than just coding and releasing.

Issues

You should open issues to any feature/bug fix/other you are going to work on. This is because, the more documented a framework is, the better. Issues represent documentation to a specific problem at a specific period of time. These issues should have a context of why it is being done, and if it is a bug, these issues should have information about that bug. Don't code without an issue, open an issue if necessary.

Docs

Your framework should be extremely documented as mentioned before, don't expect people to know how to use it, be as explicit as you can, and document every single feature your framework has and how to use it in different scenarios. Also, don't only document code, document concepts. The concept of why something is made that way, why something exists inside your framework, what it does, when it can fail, everything about it is as important as the code. You don't really do anything with just documenting the code.

Guidelines

Your framework should have guidelines (Check the contributing guidelines of Mandarine here & Style guide here)

Bug reporting

When you want to report a bug to yourself, or someone is reporting a bug, you must always have the basic information of that bug:
Operative System, version of the runtime, version of your framework, etc. This will help you find the cause quicker.

The end

This is the end of "Writing a framework" part number 1. As I mentioned before, I will be creating a second and probably third part to use the concepts we went over this post programmatically. We will be creating our own DI Framework (a simple one) but that will give you a better understanding of what a core is, etc.

Question/Feedback? Please comment below :)

What has made me more efficient

andreespirela — Fri, 26 Jun 2020 23:31:39 +0000

Throughout my years of programming, I have gone through different phases, phases that have shaped me as a developer and the personal side of being a developer. At first, being efficient was a challenge: When you are just getting into programming you want to do everything at the same time, and your thoughts are just like constant explosions in your brain.

What I am going to share today is not scientifically proved nor a fact, it is an opinion & perspective on how things have turned out for me.

When I started programming, I used to ask myself a lot of things, "How does that website work?", "How can I make a login page?", "How is a programming language created?". There were just so many questions that my brain didn't get enough rest. At night while laying on my bed, these questions used to come up and bother me thus making me sleepless. Learning how to control this kind of behaviors was a difficult task but not impossible, and at the end, it was necessary to control this because my life-balance was out of balance.

When programming started to be clear, fluent & more natural in my mind, then the issue was not only about the questions but now there was a new issue: I wanted to be always coding, at first, I thought that was a good idea, like "Yes, I'll stop coding at 5am, to then wake up at 10am and keep coding" and for a while it gave some results, but I knew there has to be something wrong, If programming was so tiring in the same way I was exercising it, then nobody would be a programmer.

What I have learned

Routine is your best friend:

I discovered that my efficiency improved in impressing ways when I started getting a routine, not a routine in programming but a routine in general. I started waking up at the same time everyday and I started falling asleep at the same time everyday. If I forced myself to have period of times where I could code and period of times where I had to stop coding.
For example: I would allow myself to code anytime from 9am to 8pm but after 8pm I would have to get a distraction of some sort.

Issues can wait

Many times we run into issues and we feel like we have to solve them right away, and trust me, I know the feeling of self-satisfaction when we solve an important issue or when we solve something we didn't understand why it was happening in the first place. Sometimes this behavior of wanting to code code and code leads to "solving, solving and solving". But really, issues can wait. In the same way you should have a routine, you should be powerful enough to tell yourself "I am going to fix this tomorrow" or "I am going to fix this over the weekend". This will provide you with life-balance and code-balance.

Read, don't code.

Many times, when I am going through my period where I don't allow myself to code (ex, after 8pm or before 9am) but I want to code, and I want it so badly, I just start reading articles about coding, things such as best practices, new trends, discussions, and more. Reading about coding while not coding is actually really good, it makes your brain have a better flows of ideas & solutions to possible issues you have, and since your brain is not working so hard as it is when coding, you can perceive and understand the readings better.

Get an uncomfortable habit

This is a weird one but perhaps the second most important one for me. When I am coding, I always have a bottle of water that I throw from hand to hand, kind of passing a ball from one hand to the other. I do this with a bottle of water, with my wallet, with anything that has a curve pretty much. This is because when I am coding & thinking I feel anxious and I feel the need to get that anxiety out of me. At first, it seemed like I was crazy just throwing things from one hand to the other, after a while, it became a way to have my mind thinking and my body doing something without having to walk or do something even more distracting.

Finally & the most important for me

Get away from electronic devices

It's hard to get away from body electronic devices (like your phone or your laptop/PC) these days, we are always on social media and when we are programmers, we feel the need to be on our computers even to just read the email or to have it turned on. Being a programmer and having a lot of interaction with electronic devices is bad. Your job, coding, already requires you to be in front of your laptop, that energy is transmitted to your body and mind, it overcharges you (If you don't believe me, keep yourself coding one day until 12am and then try to sleep).
In the same way you should have a routine, you should have a schedule for your electronic devices, for example: I don't use my phone while coding, or no that much,

I only use it after coding.
I only use my laptop during weekdays, I don't code or try to not code or have some interaction of some sort with computers during the weekend. Try to get an schedule or some sort of established-interaction time with your electronic devices, it will help you keep your life outside out of the technology world.

The end

These are some tips that I'm glad to share since they have helped me and they have shaped me into a better programmer, many programmers that are just getting started with programming feel like they have tons of energy, and they want to code and code and code, and this is not wrong, but it's not efficient in the long game. As I initially said, my advises are not scientifically proved so feel free to ignore them, but I highly suggest you to check them out and perhaps try them.

I think everything is based on how you manage your time which is something I recall multiple times in this post.

How do you feel about it? Do you have any tips? Comment below.

What Mandarine Framework needs to be production ready

andreespirela — Wed, 24 Jun 2020 17:22:29 +0000

During the last few days, as the creator of Mandarine Framework, I have not been able to stop wondering whether Mandarine is ready for production environments, that does not mean whether Mandarine has everything but whether Mandarine is reliable enough.

Mandarine has grown over the past months in functionalities and stability, although the community is still fairly small, in fact, I am the only collaborator.

Mandarine has an extensive built-in tools that allow you to develop complex applications (front-end & back-end) with important Design Patterns such as SOLID & Dependency Injection. Everything in Mandarine is based on the MVC pattern, SOLID, and the use of Components (Your application should be modular in order to be well-distributed). Click here to see some of the features

With that said, I have to say: I do not feel comfortable with the idea of using Mandarine in production environments with a lot of traffic/usage.

The Deno Problem

Deno is fairly new, it is still in its early versions (1.1.1) and it is yet to be widely used.
Among other things, Deno has a lot of questions to be addressed like the multiple modules issue: What if a module goes down, what if the module of a module of a module goes down. Since Deno does not have a package manager like NPM and imports are cached but they are not directly related to our application, it is hard to define or track when a module breaks another module and ends up breaking your application too as well as many other issues you can think of related to this concept.
The fact that Deno is very new and its in early versions gives Mandarine a lot of impediments such as working with reliable Database modules, only if the Deno community grows to enterprise levels then Mandarine will be able to support multiple database systems.
With Deno being in its early versions as well as Mandarine, it is almost impossible to determine what impact Mandarine can have on a large production environment.

Why It is not production ready

It needs a testing framework not only to test the core behavior but also for users to be able to test their Mandarine-powered application
- As of right now, Mandarine does not have unit tests. Every module must have unit tests.
Mandarine must have continuous integration with Github workflow.
Code needs to be refactor since there are part of the code that are not located in the right places.
- Part of the code needs to be cleaned.
- Everything in Mandarine should be a proxy or a factory in order to make testability easier.
Benchmarks must be created and added to the documentation in order to be able to measure how much changes are affecting.
Mandarine needs collaborators in order for it to grow and get impulse in both communities Javascript & Typescript.
Evaluate how things evolve with Deno.
Document the life cycles of Mandarine framework engine, and perhaps make the starter implementable so the developer can override behaviors.
Mandarine needs a website with the documentation and everything related to Mandarine. As of right now, Gitbook is being used but it turns out to not be enough.
Standards need to be implemented not only for the collaborators but for everyone who uses Mandarine.

Looking for collaborators

Mandarine is currently looking for Collaborators to help start addressing new features, fixes, but overall, the steps for Mandarine to be production ready (See issue here)

Disclaimer

I am the creator of Mandarine Framework

End

Do you have any thought? Please, I would love to know it even if I do not like it. Comment it below.

Why I created Mandarine.ts Framework... and Deno.

andreespirela — Thu, 18 Jun 2020 00:58:16 +0000

Let's talk Deno

A few months back, I started getting involved with Deno, the new runtime for Typescript & Javascript created by Ryan Dahl (The creator of NodeJs). When I started trying Deno, I saw the potential it has for the whole industry, with new things coming along such as Web Assembly and faster and improved versions of V8, but most important, the use & popularity Typescript is receiving due to its fantastic features & use cases, I could see how Deno may disrupt the javascript & typescript industry, maybe not now, but pretty sure in the future.

Deno gave me a unique experience & feeling that as a programmer, I didn't have with Node. The fact is, Deno solves all anti-design patterns Node has as of today since it is written in Typescript, it makes your code not only flexible but also readable & extensible with the use of Generic classes, Decorators, Extensions, Interface & Implementations, and more.
Deno also supports top-level await which is kind of a game changer since it the necessity of a callback hell.

Node.js always gave me a bit of discomfort when working with it: its package manager always stressed me out & the fact that I always had to "trust" the third-party libraries because Node.js is not secure by default, this means, any library can gain access to your system without so much of trouble.
Deno, on the other side, is secure by default, you need to pass flags to allow Deno to behave. You would --allow-net to allow access to everything related to your network like socket connection for an HTTP dispatcher, or you would use --allow-read to give Deno permissions to read from your file system.

The reasons I mentioned & more made me decide that I should use Deno to build Mandarine.TS Framework

Mandarine.TS Framework

When I saw the potential of Deno and the fact that it is still in its early days, which means, it has a growing community without too much of mass adoption, I saw a big opportunity to collaborate to the open source community & make a enterprise framework that as the community grows, it would grow along, and possibly become the next NestJS. For that reason, I created Mandarine.TS framework.

Mandarine.TS is a framework to build enterprise applications on Deno. These applications are often referred as Mandarine-powered applications.
Think of Mandarine.TS as a all-in-one solution for your business application: Mandarine.TS is divided in 4 modules: Data, Security, Core & MVC which provides different built-in functionalities and sub frameworks to meet your development standards and design patterns.

Features

Mandarine.TS gives you the possibility to work with:

Dependency Injection
Components
ORM (CRUD style)
Mandarine Query Language (MQL), a way to write SQL syntax without having any real SQL.
- findByEmailAndPassword(); = SELECT * FROM ... WHERE email = $1 and password = $2
Template Engine
Sessions
CORS
Static content
Resource handlers

Mandarine & Javascript native code.

Mandarine gives you the flexibility to use its technology in native javascript, for example: If you want to access a mandarine-powered component (Injectable dependency) from a javascript native class without using any special code or decorator, you may do so. Click here to see an example.

Inspiration

Mandarine.TS was inspired in Spring Boot

Goal

The main goal of Mandarine.TS is to solve the different enterprise problems related to their coding style & best practices by using the less configuration & more automatization as possible.

Future

I visualize Mandarine.TS becoming the main MVC framework in the Deno community.
I can't deny, it's still during its early days & it requires a lot of new features and use cases in order to get widely used and become the main MVC framework, but the progress done as of Deno v1.1.0 has been incredible & it will continue improving.
Many of the features NestJS currently offers are yet to come along with unique features in Mandarine, but as everything in development, it requires time & users using it.

Should I use Deno?

This is one questions that can be found as controversial. Many people are already on what I would call "The Deno hype" while others are skeptical. I'm personally in the middle of both sides. If you are building an enterprise application that will be used by thousands of people, I would highly recommend you to go with Node.js as it has more support than Deno and more modules that will save you time, code and worries. However, if you are building an enterprise application that will be used only by the people that work there, or a general application that is not expected to grow so quickly, then Deno is your way to go and catch-up with the newest technologies in the market.

As mentioned before, Deno is still in its early days. You can already build complex applications that can even be used in Production, but for more stability, we will have to wait two important things from the Deno community

A typescript compiler fully written in Rust
A HTTP module fully written in Rust.

Should I use Mandarine.TS Framework?

As well as Deno, Mandarine.TS framework is still in its early days, it has a lot to offer but it also has a lot of features missing. If you are working on creating an application for a start-up, Mandarine.TS is the way to go. However, if your application is more enterprise-like or enterprise-used, then there are a couple things to consider:

It is missing features
Expect breaking changes as early versions roll out.

Mandarine.TS can already cover a lot of requirements for any type of application, but it needs work & it needs to be improved to reach its goal: A all-in-one solution for enterprises which makes me recommend Mandarine for small applications or in-house applications in your company.

Thoughts

1) I personally don't think Deno will replace NodeJS, mainly because NodeJS is used across millions of companies which affect billion of people. I do think Deno will get widely used in the next 4-5 years for the new start-ups and projects that existing companies will have since it solves many of the uncomfortable things of Node. In a nutshell, I see Deno being used for new projects & new requirements rather than an option to migrate a NodeJs project.

2) The future of Mandarine.TS is very very interesting, the amount of features & achievements in a so short period of time makes Mandarine.TS framework something to look at, it still needs a community, more collaborators & enterprise usage. As of right now, Mandarine.TS is a solution for small projects or big projects used by a small amount of people, however, it is expected to have major changes this year 2020 that would change the concept of Mandarine.TS and would make it a enterprise-level solution.

The end

We have analyzed what Deno is & what Mandarine.Ts framework is, we have seen the possible futures of both & the options we have.

Do you have any thought? I would love to hear it, even if I don't like it or agree. Leave a comment below!.

Deno API + Postgres: without SQL

andreespirela — Tue, 09 Jun 2020 22:49:13 +0000

Introduction

Throughout my years of programming, I have seen many applications that combine the database layer with the business logic of the app. In one way or the other, some ORM's fail to disperse the concepts of application layers & make your app not singly-responsible. When I was first getting into programming, I did this too but after learning & learning, it started seeming like an odd thing to do.
In this article, we will be exploring how to create a simple API that will run on Deno and will use Postgres as its database, but the interesting thing is that we will not use SQL whatsoever, thus, we won't mix the business logic of our application with the database layer.

What is Deno?

According to the Deno website

Deno is a simple, modern and secure runtime for JavaScript and TypeScript that uses V8 and is built in Rust.
It was first created by Ryan Dahl, the same creator of Node.JS.

What we'll need

We will be exploring the following

Deno
Mandarine.TS framework (A framework to build applications, specially web apps)
Mandarine.TS ORM
PostgreSQL

Goals

Create a simple API that uses Postgres without writing SQL on our application.

Getting Started

Step 1: tsconfig.json

Mandarine requires us to use a tsconfig.json in order for the typescript compiler to work properly.

tsconfig.json

{
    "compilerOptions": {
        "strict": false,
        "noImplicitAny": false,
        "noImplicitThis": false,
        "alwaysStrict": false,
        "strictNullChecks": false,
        "strictFunctionTypes": true,
        "strictPropertyInitialization": false,
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,
        "allowUmdGlobalAccess": false,
    }
}

Step 2: Database configuration

In order for Mandarine's internal ORM to work, we will need to establish our connection configuration inside Mandarine's property file.
For this, we will create a file called properties.json under /src/main/resources (your-project/src/main/resources/properties.json)

properties.json

{
    "mandarine": {
        "dataSource": {
            "dialect": "postgresql",
            "data": {
                "host": "localhost",
                "port": 5432,
                "username": "postgres",
                "password": "",
                "database": ""
            }
        }
    }
}

Now you just have to put the your connection information.

Step 3: Creating our Model.

A model is an object that represents an entity (table) in our database. The properties are used to represent columns.
To create our model, we will create a folder called "database" (which we will divide into two folders: models and repositories). Inside the models folder, we will locate our model called: booksModel.ts

booksModel.ts

import { Table } from "https://deno.land/x/mandarinets/mod.ts";

export interface IBook {
    id: number;
    name: string;
    author: string;
}

@Table({ schema: "public", name: "books"})
export class BooksModel implements IBook {

}

In the above example, we are importing the decorator Table from Mandarine.TS framework repository & we are decorating our class BooksModel with it, basically telling Mandarine that this class is an entity. Note that if you do not specify the property name in the decorator then Mandarine will take the name of the class as it.

Step 4: Adding columns to our Model.

Now that we have created our model, it's time to add some columns.

Our class BooksModel (booksModel.ts) will look like this.

import { Table, Id, GeneratedValue, Column } from "https://deno.land/x/mandarinets/mod.ts";

export interface IBook {
    id: number;
    name: string;
    author: string;
}

@Table({ schema: "public", name: "books"})
export class BooksModel implements IBook {

    @Column()
    @Id()
    @GeneratedValue({ strategy: "SEQUENCE" })
    public id: number;

    @Column()
    public name: string;

    @Column()
    public author: string;
}

In the code above, we are indicating that we will have 3 columns: id, name, and author (We are decorating them with @Column), but we are also indicating that the column id will be a primary key since we are decorating it with @Id & we are also indicating that it will be auto-increment (@GeneratedValue). Note that GeneratedValue must always be used if we want to insert data directly from Mandarine's ORM.
There is a lot of documentation on how to use those three decorators. Click here to see the official documentation.

Note that you do not have to create the table manually. Instead, Mandarine will create this table (if it doesn't exist) called books at mandarine compile time so you do not have to worry about handling database operations at all.

Step 5: Creating our SQL-free Repository

A repository is a class that handles your database queries. Unlike many ORM providers, Mandarine.TS framework gives us one of its most amazing features: MQL (Mandarine Query Language), which is the equivalent to the CRUD interface in Java for example. Mandarine-powered repositories are extremely easy to use and practical as they save us a lot of time and code.
We will create our repository under the folder database/repositories that we created during Step 3.

booksRepository.ts

import { Repository, MandarineRepository } from "https://deno.land/x/mandarinets/mod.ts";
import { BooksModel } from "../models/booksModel.ts";

@Repository()
export abstract class BooksRepository extends MandarineRepository<BooksModel> {

    constructor() {
        super(BooksModel);
    }

}

In the code above, we have created the an abstract class BooksRepository and we have decorated it with @Repository, this way, we will let Mandarine know that this class should be considered a Mandarine-powered repository. Note that for a class to be a Mandarine-powered repository, we must extend it to MandarineRepository which is a generic class that will take our model. After extending it, we need to call super from our repository's constructor. super will take one argument which is the class representation of our model (without being initialized, just the class)

Step 6: Adding methods to our repository

Now that we have created our repository, we will be adding methods that we will use later to request our database. This is where the fun begins because these methods we will write will be empty methods, without anything inside but they will actually bring or send information to our database. Let's see..

@Repository()
export abstract class BooksRepository extends MandarineRepository<BooksModel> {

    constructor() {
        super(BooksModel);
    }

    public findById(id: number) {}
    public findByAuthor(author: string) {}
    public findByName(name: string) {}
    public findByIdAndName(id: number, name: string) {}
}

In the example above, we have added 4 new methods to our repository: findById, findByAuthor, findByName, findByIdAndName.
Note our columns in the model have to match the name in the name of our methods, we can't just write whatever (This should be self-explanatory but I don't mind taking the time to remind about it).
These methods will then be processed by MQL.

Step 7: Creating our Controller

In this step, we will be creating our API controller which we will request to interact with our database. We will be injecting our repository in this controller but note, for production environments, I would highly recommend to have a service where your repository will be injected, and the service class will be the one to interact with your controller, although, since this is a tutorial, I will not get into that to not make it harder.

We will create a folder in the root of our project called "controllers" and in that folder we will create the following file

booksController.ts

import { Controller } from "https://deno.land/x/mandarinets/mod.ts";

@Controller('/api')
export class BooksController {

}

In the above example, we have created our controller which will have a base route which is /api, this means, all the endpoints that belong to this controller will be part of the URL /api.

Step 8: Injecting our repository in our controller

Now that we have created our controller, it's time to inject our repository by using Mandarine's Dependency Injection.

import { Controller } from "https://deno.land/x/mandarinets/mod.ts";
import { BooksRepository } from "../database/repositories/booksRepository.ts";

@Controller('/api')
export class BooksController {

    constructor(private readonly booksRepository: BooksRepository){}

}

While it is true that we could use the @Inject decorator, the best practice is to do injections in the constructor of our component.

Step 9: Creating endpoints

In this step, we will be adding the endpoints we will request to interact with our database.

Our booksController.ts will look like this:

import { Controller, POST, RequestBody, GET, RouteParam, QueryParam } from "https://deno.land/x/mandarinets/mod.ts";
import { BooksRepository } from "../database/repositories/booksRepository.ts";
import { IBook, BooksModel } from "../database/models/booksModel.ts";

@Controller('/api')
export class BooksController {

    constructor(private readonly booksRepository: BooksRepository){}

    @POST('/add-book')
    public async addBook(@RequestBody() bookToAdd: IBook) {

        let newBook: BooksModel = new BooksModel();
        newBook.author = bookToAdd.author;
        newBook.name = bookToAdd.name;
        await this.booksRepository.save(newBook);

        return { msg: "New book have been added" };
    }

    @GET('/get-book/:id')
    public async getBookById(@RouteParam() id: number) {
        return await this.booksRepository.findById(id);
    }

    @GET('/:author/books')
    public async getBooksByAuthor(@RouteParam() author: string) {
        return await this.booksRepository.findByAuthor(author);
    }

    @GET('/search')
    public async getBooksByIdAndName(@QueryParam() id: number, @QueryParam() name: string) {
        return await this.booksRepository.findByIdAndName(id, name);
    }

    @GET('/all-books')
    public async getAllBooks() {
        return await this.booksRepository.findAll();
    }

}

I know, it can seem like a lot of code so let me explain some of it.

addBook: Add a book to our database using repository.save, the method save in our repository is a mandarine reserved keyword for repositories, and it will resolve the insertion of a new row.
getAllBooks: List all the books that we have in our database by using repository.findAll. findAll is another Mandarine reserved keyword for repositories, it is responsible for bringing all the rows of that specific table.

Step 10: Creating our single-entry point file.

The single entry-point file is a file where we will import all our components in order for Mandarine & Deno to compile them properly. You can read more about this in Mandarine's official Documentation (Click here)

We will create this file in the root of our project and we'll call it entry-point.ts

app.ts

import { BooksController } from "./controllers/booksController.ts";
import { BooksRepository } from "./database/repositories/booksRepository.ts";
import { MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

const controllers = [BooksController];
const repositories = [BooksRepository];

new MandarineCore().MVC().run();

Step 10: Running our app.

Now to run our app, we will run the following command:

deno run --config tsconfig.json --allow-net --allow-read entry-point.ts

Step 11: Interacting.

As we coded before, we have an endpoint for adding books which is a POST-type endpoint. Now we will send some JSON data to it.
I personally use postman, but you can use any REST client you'd like.

POST /api/add-book HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
    "name": "The Diary Of a Young Girl",
    "author": "Anne Frank"
}

And let's add one more book

POST /api/add-book HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
    "name": "Sapiens: A Brief History of Humankind",
    "author": "Yuval Noah Harari"
}

Getting a book by its ID

`/get-book/:id`

Now, let's try our endpoint /get-book/:id.

GET /api/get-book/1 HTTP/1.1
Host: localhost:8080

and to that request, we are getting:

[
    {
        "id": 1,
        "name": "The Diary Of a Young Girl",
        "author": "Anne Frank"
    }
]

Getting books by its author

`/:author/books`

Now, let's try our endpoint /:author/books.

GET /api/Yuval Noah Harari/books HTTP/1.1
Host: localhost:8080

which will make us get

[
    {
        "id": 2,
        "name": "Sapiens: A Brief History of Humankind",
        "author": "Yuval Noah Harari"
    }
]

Searching a book by name & id

`/search`

Our first book (1) is The Diary Of a Young Girl
Now let's try to find it by using this endpoint

GET /api/search?id=1&name=The Diary Of a Young Girl HTTP/1.1
Host: localhost:8080

which will return

[
    {
        "id": 1,
        "name": "The Diary Of a Young Girl",
        "author": "Anne Frank"
    }
]

Getting all books in our table.

`/all-books`

Finally, let's test our endpoint which is responsible for returning all the books we have added.

GET /api/all-books HTTP/1.1
Host: localhost:8080

which will return the following array

[
    {
        "id": 1,
        "name": "The Diary Of a Young Girl",
        "author": "Anne Frank"
    },
    {
        "id": 2,
        "name": "Sapiens: A Brief History of Humankind",
        "author": "Yuval Noah Harari"
    }
]

There is more

Mandarine's ORM has reserved methods such as findAll or save that will save you a lot of code already. But there is more to it. Mandarine has countAll (returns the amount of rows in the table), deleteAll (deletes all rows) and the possibility to write existsBy... which would return a boolean value after evaluating if a row exists => existsById would be a good example of this.
If you would like to learn more about Mandarine.TS framework & specially Mandarine.TS ORM, don't hesitate to visit its official documentation and follow me.

Summary

What we did:

We created an API with Deno, Mandarine & Postgres
We used Mandarine.TS framework ORM
We added & requested data from our database without having to write any SQL whatsoever.
We created models, repositories & controllers ## Why Mandarine.TS?
As we saw in this article and past articles I have written, Mandarine.TS offers a lot of built-in solutions that will save us a lot of code and will allow us to work in a more enterprise way as well as making our code simple & readable.
Mandarine.TS is decorator driven which gives us a lot of flexibility on how to write our code.

Note

The intention of this article is to show how to build an API with Deno. The examples shown are simple examples that are not meant to be used in production environments.

Disclaimer

I am the creator of Mandarine.TS Framework.

The end

Get the full source code here

Do you have any question or something to say? If so, please leave a comment. If you like this article, please tweet it!

Writing an API with Deno

andreespirela — Mon, 08 Jun 2020 03:21:59 +0000

In this post, we will be developing a small API system using Deno (A runtime for Javascript & Typescript developed by Ryan Dahl, Node.JS creator).

For our API system we will be using Mandarine.TS framework. This framework will help us code & save a lot of time in our design as it has built-in solutions such as Dependency Injection, HTTP Handlers & Routes, and more.

Goals

Create an API which manages books.
Provide GET & POST Routes
Use Mandarine.TS to get you involved with this framework and why it can be important when using Deno for web applications.

Let's get started.

Concepts

Services: Classes Where our business logic is.
Controllers: Classes responsible for handling HTTP requests as well as creating the routes for it.
Mandarine.ts/Mandarine: A Typescript decorator-driven web framework for Deno.

Now, coding.

Step 1

We will be creating a tsconfig.json file in the root of our project. Mandarine.TS framework requires a tsconfig.json in order to work properly.

tsconfig.json

{
    "compilerOptions": {
        "strict": false,
        "noImplicitAny": false,
        "noImplicitThis": false,
        "alwaysStrict": false,
        "strictNullChecks": false,
        "strictFunctionTypes": true,
        "strictPropertyInitialization": false,
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,
        "allowUmdGlobalAccess": false,
    }
}

Step 2

We will be creating a typescript file and we will call it books-service.ts. This file will contain the functioning of our API that we will later be using in our Controller. We will locate this file inside a folder called services

books-service.ts

import { Service } from "https://deno.land/x/mandarinets/mod.ts";

let books: Array<IBook> = new Array<IBook>();

interface IBook {
    id: number;
    name: string;
    author: string;
}

@Service()
export class BooksService {

}

In code above, we are importing from the repository of Mandarine.TS framework the decorator @Service() which will decorate our class BooksService, this way, Mandarine can interpret this as a Mandarine-powered component. We have also declared a variable called books which we will be using to add & get books from, and we have created an interface IBook, which is simply the structure of the book item.

Step 3

Now that we have our service class decorated with @Service(), we will be adding some logic to it, we will create 4 methods: addBook, getBookById, getBookByName, getAllBooks

@Service()
export class BooksService {

    public addBook(id: number, name: string, author: string) {
        if(!books.some(book => book.name == name || book.id == id)) {
            books.push({
                id: id,
                name: name,
                author: author
            });
        }
    }

    public getBookById(id: number): IBook {
        return books.find(book => book.id = id);
    }

    public getBookByName(name: string): IBook {
        return books.find(book => book.name = name);
    }

    public getAllBooks(): Array<IBook> {
        return books;
    }
}

addBook: Adds a book only when the id or the name are available.
getBookById: Look up a book in the array that matches with our provided id.
getBookByName: Look up a book in the array that matches with our provided book name.
getAllBooks: Returns all the books that have been added.

Step 4

In this step, we will be creating our controller. For this, we will create a new folder in the root of our project called controllers, and in this folder, we will locate our books-controller.ts which will contain our controller class.

books-controller.ts

import { Controller } from "https://deno.land/x/mandarinets/mod.ts";

@Controller('/api')
export class BooksController {
}

In the code above, we have declared our controller by using the decorator @Controller which will inform Mandarine that this is a class that must be considered a controller (See official documentation here). As you can see, we are passing a parameter to our decorator with the value /api, this means, all the routes inside our controller will have to start with /api when requesting them.

Step 5

Now that we have declared our controller, we will inject our Service. This is done by importing our Service & putting it in the constructor of our controller.

Our code will look like this:

import { Controller } from "https://deno.land/x/mandarinets/mod.ts";
import { BooksService } from "../services/books-service.ts";

@Controller('/api')
export class BooksController {
    constructor(private readonly booksService: BooksService){}
}

By injecting our service, Mandarine will resolve all its dependencies (if it has) and will make it available for us to use in our controller component without needing to manually initialize it. (See more documentation about this here)

Step 6

Now that we have our controller & we have also injected our book service (BooksService), we will proceed to create 3 endpoints:

/api/books/add-sample: It will add default books to our books array when requesting it.
/api/books/getAll: It will return all the books that have been added.
/api/books/get: It will get a book from the array by filtering by ID or book name.

Our controller will look like this

import { Controller, GET, POST, QueryParam } from "https://deno.land/x/mandarinets/mod.ts";
import { BooksService } from "../services/books-service.ts";

@Controller('/api')
export class BooksController {

    constructor(private readonly booksService: BooksService){}

    @POST('/books/add-sample')
    public addSampleBooksHandler() {
        this.booksService.addBook(1, "The Diary Of a Young Girl", "Anne Frank");
        this.booksService.addBook(2, "Sapiens: A Brief History of Humankind", "Yuval Noah Harari");
        return "Success";
    }

    @GET('/books/getAll')
    public getAllBooks() {
        return this.booksService.getAllBooks();
    }

    @GET('/books/get')
    public getBook(@QueryParam('search') typeOfSearch: string, @QueryParam() data: string) {
        if(typeOfSearch === 'id') {
            // We use <any> so the compiler doesn't complain about using a possible string for a number parameter in getBookById
            return this.booksService.getBookById(<any> data);
        } else {
            return this.booksService.getBookByName(data);
        }
    }

}

Note that we are importing 3 new items: GET, POST, and QueryParam.

GET: Will create a GET route. It takes one parameter which is the route to create.
POST: Will create a GET route. It takes one parameter which is the route to create.
QueryParam: It is a HTTP Parameter Decorator which will be responsible for injecting the values from the query parameters of the request into our HTTP handler. Refer to the link for a deeper explanation.

Step 7

Now that we have our service & controller for our books, we will proceed to create the entry point file. If you have got to this step, congratulations, this step is extremely easy & straight forward as we are just importing our classes to a common place.
This entry point file we will create is the file we will run with Deno

We will locate this file in the root of our project and we will call it entry-point.ts.

entry-point.ts

import { MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";
import { BooksService } from "./services/books-service.ts";
import { BooksController } from "./controllers/books-controller.ts";

const services = [BooksService];
const controllers = [BooksController];

new MandarineCore().MVC().run();

In the code above, we are basically locating our components in just one place.
MandarineCore is possibly the most important part for your code as it handles the engine of Mandarine Framework. This engine will resolve our dependencies & run our website. (See more here).

Step 8: Running our Mandarine-powered API.

To run our web application, we will run the following command in the root of our project.

deno run --config tsconfig.json --allow-read --allow-net entry-point.ts

After running that, we should be seeing our engine started which would mean we are ready to request our API.

Step 9: Requesting our API

/api/books/add-sample:

POST /api/books/add-sample HTTP/1.1
Host: localhost:8080

which will return Success.

/api/books/getAll

GET /api/books/getAll HTTP/1.1
Host: localhost:8080

which will return

[
    {
        "id": 1,
        "name": "The Diary Of a Young Girl",
        "author": "Anne Frank"
    },
    {
        "id": 2,
        "name": "Sapiens: A Brief History of Humankind",
        "author": "Yuval Noah Harari"
    }
]

/api/books/get?search=id&data=2

GET /api/books/get?search=id&data=2 HTTP/1.1
Host: localhost:8080

which will return

{
    "id": "2",
    "name": "The Diary Of a Young Girl",
    "author": "Anne Frank"
}

Summary

What we did

We created an API using Deno.
We created an API using Mandarine.TS as our framework.
We interacted with Dependency Injection
We worked with nested routes (Base route in controller to its children)
We tested our endpoints.

Why Mandarine.ts was used as the web framework

Mandarine saves us a lot of code & functionalities to build any type of web application. This time we used it for an API and in a few lines of code we did a lot with it (Services, Controllers, Handlers, Dependency Injection).
Mandarine is decorator-driven, which means, it uses a lot of decorators to interpret functionalities which makes our code more readable and shorter.

Note

The intention of this article is to show how to build an API with Deno. The examples shown are simple examples that are not meant to be used in production environments.

Disclaimer

I am the creator of Mandarine.TS Framework.

The end

Get the full source code by clicking here.

Do you have any question or something to say? If so, please leave a comment. If you like this article, please tweet it!

Mandarine.TS, the next ExpressJS?

andreespirela — Fri, 05 Jun 2020 15:21:33 +0000

What is Mandarine.TS?

Mandarine.TS is a framework that allows you to develop applications, mainly web-applications. It is written in Typescript and runs on Deno (A Javascript & Typescript runtime created by Ryan Dahl, inventor of Node.JS) and it recently released its version 1.0.0.

Mandarine is divided into 4 modules: Core, Data, Security & MVC which essentially give you tools to create Mandarine-powered applications.

From the official documentation:

Under its umbrella, Mandarine.TS has 4 modules: Core, Data, Security and MVC, these modules will offer you the requirements to build a Mandarine-powered application. However, the most common module is Mandarine MVC, since it combines all the concepts from its different cores into one, in order to make the creation of complex web-applications (front-end & back-end) easy, reliable, and following design patterns & principles such as SOLID, making your application sustainable & readable across developers.

Mandarine offers you in its 4 different modules the use of: Dependency Injection, Components, Routes, HTTP Handlers, Session middleware, built-in ORM, Template Engine, and more.

The real question. Is Mandarine the next ExpressJS?

Mandarine can be considered fundamentally different when it comes to comparing it to ExpressJS. They can perform the same tasks but they are not the same when it comes to using it and writing it.

Differences:

Mandarine.TS is known for being decorator-driven
Mandarine.TS is not only for web applications but for any kind of typescript application that runs on Deno.

Decorator-driven

Example I

Almost everything in Mandarine needs a decorator, this will make your code readable and easy to write.

import { Controller, GET, MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

@Controller('/api')
export class Boo {

    @GET('/hello-world')
    public helloWorld(): string {
        return "Hello World";
    }

}

new MandarineCore.MVC().run();

# request => http://localhost:4444/api/hello-world => Hello World

Example II

import { Controller, GET, RouteParam, QueryParam, MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

@Controller()
class TestController {

    @GET('/say-hi/:name')
    public helloWorld(@RouteParam('name') personsName: string, @QueryParam() lastname: string): string {
        return `Hello ${personsName} ${lastname}, welcome.`;
    }
}
new MandarineCore.MVC().run();

# request => http://localhost:4444/say-hi/Bill?lastname=Gates => Hello Bill Gates, welcome.

Not only for web-apps.

Although the concept of "Mandarine Native" is really in its early days as Mandarine.TS 1.0.0 was only released yesterday, The objective of Mandarine is to create Mandarine-powered applications that let a development environment use built-in solutions such as DI & Components without having to compile it into a web app. Some of this concept is already possible, for example, you can use Mandarine's DI framework in a javascript/typescript native class (See example here) but this concept is still being developed.

Mandarine.TS vs ExpressJS

ExpressJS has been out there for a decade now, this makes it more reliable in terms of community size & it runs on Node, a runtime that has been out there for a decade and a year now. This may make ExpressJS seem more reliable because it possibly is in certain areas.

Mandarine.TS has only been out there for a few months, and its community is still growing. Although, the fact that Mandarine is written in Typescript & runs on Deno offers a now modern solution for future web-applications or applications in general with modern technologies. One of the most interesting things of Mandarine, is MQL (Mandarine Query Language) (See here), which is some sort of version of CRUD repositories but implemented in Typescript.

Another +1 for mandarine is the fact that it supports Dependency Injection out of the box with its built-in DI framework (See documentation here). This makes your application not only more easy to test, but it also makes it more readable & practice as it gets larger.

Thoughts

It is definitely interesting where Mandarine.TS is going, while it may seem that it cannot fight against ExpressJS, some of its features and the possibly growing community will make its future something to be curious about.
You can see Mandarine's documentation here and you can access its Github repository here

Disclaimer

I am the creator of Mandarine.TS