Forem: Pragmatic Maciej

Helper - the architecture whole

Pragmatic Maciej — Sat, 28 May 2022 12:09:41 +0000

Helper, this word starts my list of the most hated dev words. I am experienced developer who work with many languages, but lately I've sticked longer in Python and particularly in Django. In every project there is the same problem, where to put things and how to name things, helpers are very much about how we can do it wrong.

Very often these reusable things get a name like - utils. I am ok with the name, it means that this are some utilities. Of course like with everything we can do too much and make these utilities a garbage. But this article is not about this problem, but the hated "helper" problem.

So my journey with Django started, and I got this MVC thing which I am familiar with, though in current architecture BE is not responsible for the view part, so Django MVC ends with really MC - we have models and controllers, eventually repositories in the middle - MRC or services MSC. Yes these are just made names, so I have no clue anybody names it like that.

Ok, so going back to helpers. What I was surprise to see was that outside of controllers and models, we have helpers, and developers really put there a lot of staff. This helpers thing is a liquide level of architecture. Everything which doesn't belong to C or M is there. So looks like at least half of the whole codebase lands in helpers 😱. Even more, when developers talk about the code they say - "I will make this and that helper" or "I will use this and that helper". Helpers are everywhere. They are reusable functions, but also classes responsible for specific domain flow. There is nothing consistent in it, or there are no rules where helpers live in the codebase. Helpers can be used by any part of the code, helpers can use third parties, can call database, but can be also reusable pure functions.

What is this helper thing then? Really, after almost 2 years in this environment, I know what is it. It is just everything and nothing, it is just a proof of the whole in the architecture. When some dev tells me - "I will make an helper", I am asking what does it mean? For me saying this is like saying - "I will make a function", or "I will make a class" or just "I will make a thing", it does not say really nothing more.

Of course I forced some improvements, we have introduced the missing part of the architecture so - Service layer which connects our so called Views, but really just end point definitions with models and repositories (QuerySet). This level is now used instead of helpers for all kind of flow managing, actions with side effects, it manages transactions and business procedures. The other things like - reusable functions moved to utils, other things like domain knowledge representations is put now in domain related files. Helpers - I don't write them, and never plan to do it again. If I hear word "helper", my response is WHAAAAT?!.

That article has been written in 20 minutes, sorry for any gramma errors, don't hesitate to point them in comments though.

Return statement is ok

Pragmatic Maciej — Sat, 09 Oct 2021 11:26:48 +0000

Hey, long time no see. I have a new fancy subject, very much related to the code style, so the subject which developers like to argue about. My motivation to write this article is the eslint rule which I've lately found in the codebase, exactly - arrow-body-style. So we will talk about - using or not using "return" statements in expression based arrow functions.

Arguments against explicit return

Few points which will tell us why we have this rant at all.

Explicit return is less readable.

JS has return statement, yes it does, even though features like arrow functions allow for not using it, we cannot magically make JS a language without it. Why? Because we have statements, and when we need to use them, we need to use return statements also.

Consider below two code examples:

let hateReturn = (user) => (
  hasDog(user) ? "Dog lover" : "Cat lover";
)

let returnIsOk = (user) => {
  return hasDog(user) ? "Dog lover" : "Cat lover";
}

Is there any difference between them in terms of readability? I don't think there is any difference. Do you think "return" very much makes this code worse? I don't think so. Do you think the second form should be somehow forbidden? I hope not.

Arrow functions should be consistent and not use return

Yes, great but is it even possible? Let's add another function.

let hateReturn = (user) => (
  hasDog(user) ? "Dog lover" : "Cat lover";
)

let returnOk = (user) => {
  return hasDog(user) ? "Dog lover" : "Cat lover";
}

let anotherReturnOk = (user, max) => {
  const distance = calculateDistance(user);
  if (distance > max) {
    return "Too far";
  } else {
    return "Close enough";
  }
}

How do you see these three functions together? Which ones are consistent in syntax? Looks like last two have the same brackets, the same form of returning, and the hateReturn has no curly brackets but round ones, it has also no return.

There is no chance that all your functions will not have a return statement. And for sure having some of them with curly brackets and returns, and some of them with round ones doesn't make the code consistent.

Note Yes you can ho hardcore and make you own language by creating all statements as expressions, but we don't talk about such ;)

Note Yes we can use standard function declaration and not be bothered by arrow functions. Then there is no choice to make.

With "return" there is more code

Yes it is, so what?

Arrows without return are cool

Yes, they are...

Arguments for explicit return

Now counter attack. Beware.

Flexibility issues with implicit return

What if our function needs to have additional logic included? Ye we can try to keep implicit return by keeping conditional expression:

let hateReturn = (user) => (
  hasDog(user) 
    ? "Dog lover" 
    : hasCat(user) 
      ? "Cat lover"
      : "No animals"
)

Take a look at the formatting which even better allows us to read this. Is it bad? I don't think it is, but what if I would like to make it more explicit with "if" instead of ternary? (Un)fortunately we need to rewrite the function and use explicit return then:

let returnIsOk = (user) => {
  if (hasDog(user)) {
    return "Dog lover"
  } 
  if (hasCat(user) {
    return "Cat lover"
  }
  return "No animals"
}

We used a technique called "early return" here. And again is the second version the worst? I don't think so. And it is not a rant aiming into ternaries, no, it only shows that we are less flexible with implicit returns, and we need to do a lot of gymnastics to keep it.

Additional variables

Assignment is a statement, therefore you cannot use it in arrow function without return. Consider two code examples:

let hateReturn = (user) => (
  user.dogs + user.cats > 5 && user.flat_size < 50 
    ? "Cannot have more animals" 
    : "Can have more animals"
)

let returnIsOk = (user) => {
  const manyAnimals = user.dogs + user.cats > 5;
  const smallFlat = user.flat_size < 50;

  if (manyAnimals && smallFlat) {
    return "Cannot have more animals"
  } else {
    return "Can have more animals"
  }
}

Unfortunately any local variables for better readability cannot happen in the implicit return version.

Note Expression based languages like Elm, Haskell have special expression for having local constants. In that way we can use expression and still make code more readable. Below example from Elm:

-- ELM LANGUAGE --
let
    manyAnimals = 
      user.dogs + user.cats > 5
    smallFlat =
      user.flat_size < 50
in
  if manyAnimals && smallFlat then 
    "Cannot have more animals"
  else
    "Can have more animals"

And it is an expression, there is also the if expression visible above. No statements but code looks almost the same as the one with statements. Also no explicit return, but this is not JS and there is no return keyword.

Do you return or not dilemma

Two functions close to each other

let bomb = (bomb) => {
  api.post.sendBomb(bomb); // doesn't return
}

let secondBomb = (bomb) => (
  api.post.sendBomb(bomb); // does return
)

Looks like no difference, but because of different brackets we have different returns, first function returns void, second returns what sendBomb is returning. Quite an implicit difference don't you think? You need to look at brackets to understand if there is return or not.

Object returning

That is I think a legendary example, my first impression years ago was - what a hack, they introduced new syntax and created such an issue. How do we return objects by implicit return?

let f = (a) => {a} // this has no return
let f2 = (a) => ({a}) // returns object with key 'a'

That always made me sad. Syntax confusion is high, therefore I see no issue in doing:

let f3 = (a) => { 
  return {a}; 
}

Yes the longest of them all, but there is no confusion.

I want to use hooks in React

const Component = ({name}) => (
  <div>
    {name}
  </div>
)

Great, now what if we need to use some hook inside? Yes, unfortunately we need to rewrite the function:

const Component = ({name}) => {
  const [show, setShow] = useState(true);
  return {show && <div>
    <button onClick={() => setShow(true)} >Hide</button>
    {name}
  </div>}
}

There is no way to avoid explicit return. We need to rewrite the component, change brackets, add return. Maybe not much, but for me it is always a burden.

But wait, onClick there is an arrow function, it has no explicit return, there you go, you have used it - looser. Yep I am using implicit returns of arrow functions when I see it as a best fit, for example for function arguments in many cases we already have a closure with all needed data, we don't need any local variables, in most they are simple functions. So yes I see no issue in using implicit return, but the whole rant is not about not using it, but about forbidding using the return for expression based functions. I see no valid reason to forbid it, in the same way I see no reasons to not use standard function syntax.

In summary if you have arrow-body-style rule in your project, turn it off. Don't create not needed code restrictions.

Note that the whole article is about JS only. If language does not have explicit return - good, there is no problem and no decision making.

Follow the type

Pragmatic Maciej — Tue, 22 Jun 2021 07:52:13 +0000

TypeScript has been around for a while, in many new projects it started to be a standard, even old projects slowly migrate into TS. That is really good, good until we use it with common sense. In this article I will show how we can create a problem by doing things in contrast to the type system.

I am not sure if I have you

We have following types in our codebase

type Movie = {
  uuid: string,
  title: string,
  comments: Comment[]
}
type Comment = {
  uuid: string,
  content: string,
}

Now these types are used by some function which is responsible for showing comments. In our example this function will be React component

const Comments = (movie: Movie) => {
  if (movie?.comments?.length > 0) {
    return movie.comments.map(comment =>
      <p>comment?.content</p>)
  } else {
    return "No comments"
  }
}

Yes it works, but... But we have used a lot of optional chaining operator and what was the reason?

My code says A, my type says B

We use TypeScript, so we should seek for the reason in types, and our type definitions say following things:

movie is always there
movie always has comments array
comments array have comment objects inside

And our code says:

movie can be not there
movie can not have comments array
comments array can have elements with null/undefined values

Ok, so why do we need types if we don't believe them. The whole idea of having type annotation is to have live documentation of our assumptions for the code. Now we have different type assumptions and clear indications in the code that we don't believe in them. And such a situation is very risky, if we continue doing that the whole project will start to be unstable, as nobody will believe that type is correct. Such a thing ends very badly, and better would be to not have a type system at all.

Now some points in defence of this approach which I have heard:

But we always can get corrupted data
But BE can send null or undefined

Yes BE can send smth wrong, but it does not mean we on the FE side should "fix" broken data. And to be clear, using such a defensive approach doesn't fix anything, it just hides under the carpet real problems, leaving application still not working properly. Although BE can break our data and contract in so many ways that trying to defend that is more like Sisyphean work and nothing more.

Code always has some data assumptions, even this code without types. If you access an object by property "name" it means your code assumes there is an object with such property. Everything we do has some assumptions over data we transform, types only show these assumptions in an explicit way. Having explicit assumptions different from implicit one (these in code directly) means we have two different data assumptions.

But the problem is real

What if we really see that comments sometimes are not in movie object?

Aha, yes so we should use optional chaining then, but we should firstly change the contract, and contract is our type definition.

type Movie = {
  uuid: string,
  title: string,
  comments?: Comment[] // optional property
}
type Comment = {
  uuid: string,
  content: string,
}

Pay attention that comments is now optional property, and TS will now check if we do the check before we use this property as an array. Now after the type change we can follow the type doing code changes. In that way, types always define the contract and code follows them.

I want full defence though

Ok, I get that. We don't want the code to fail, we want to show some info to the user rather than just having an unexpected crash. That is reasonable, but doing defensive checks everywhere without knowing what to do in the negative path is no solution.

Make the defence, but as close to the data source as possible. In Elm world for example nothing can get to your application code before it will not be validated and parsed to the wanted form by using type constructors. This thing is called decoder. And yes, even in TS we can follow this kind of defence, so not believe third parties, and servers that they send valid data. Just validate that data, and if something is different than assumption, show some user friendly error, as our app doesn't work with this case. For example one of projects which does that is io-ts, or runtimes. Also we can validate types manually by creating our own decoders, but this will be hard as we need to have a way to keep these decoders aligned with types always. But yes, it can be done. And the simplest start of such decoders is having them as function from unknown to our wanted type.

Know how to defend yourself

Doing defensive checks in every place of your codebase, even though types say differently is a special kind of foot gun. Don't do it, believe in your types, make the guard close to the source of the data, do not assume wrong or corrupted data can go through your app, as if so, it cannot be fixed in a meaningful way outside of having a validator/decoder before the data flows through your app.

Know too much

Pragmatic Maciej — Fri, 18 Jun 2021 13:05:27 +0000

Single responsibility principle is stating that given program, procedure or function should be responsible for one thing. Following this rule means also that we should think about how much our part of the program know, and how much is enough to perform given operation.

Optional arguments

Optional arguments are values which can be passed to given function or not, optional argument can also mean the value can be None or null or any other empty value (depends from the language). Let's see first code example, it will by Python with some MyPy type annotations, but don't worry if you don't know Python, examples should be easy for coder of any language as I have tried to keep complexity in very low level.

def buy_product(user: User = None, product: Product = None):
  if user and product:
    user.products.add(product)

Function buy_product has two optional arguments, and it means it can be called without anything, or with None values. Below some examples of such "strange" calling of the function:

buy_product() # yyy, but what product and who buys it?
buy_product(user=None, product=None) # buying None by None :)
buy_product(user=my_user, product=None) # ah yes user buys nothing
buy_product(user=None, product=my_product) # ah yes None buys smth

I hope when you read above code you feel uncomfortable, at least I do. Something is wrong here, how we can buy product without providing who buys it neither what is being bought.

The problem with buy_product is that it has really no answer on situation where one of arguments is not set, this function for None in any of arguments changes in noop (No Operation) function, so does nothing.

The intention of a maker of such function is to call it in any circumstances, and be sure that it will work only for valid data, and be noop in other situations. This also avoids branching logic, we always call it. But do we really avoid anything? And what if we will pass optional value down even more?

def do_payment(user: User = None, product: Product = None):
  if user and product:
    call_some_payment_service(...)

def add_product_db(user: User = None, product: Product = None):
  if user and product:
    append_to_db(...)

def log(user: User = None, product: Product = None):
  if user and product:
    log_service_call(...)

def buy_product(user: User = None, product: Product = None):
  do_payment(user, product)
  add_product_db(user, product)
  log(user, product)

Now our situation changes even more. We still can just call our function buy_product() but it means that it passes None down and all functions deal with it.

The problem with all of this is that all functions can work only with existing values, are not prepared to work with None, like None is not supported value of these functions domains. These functions know too much, they know that argument which is required for them to work can be not set. By doing that we extend all functions responsibilities to handle optionality. We don't want that, believe me.

The solution for this problem is - call these functions only when we have enough data to perform the operation.

# definition without optionality in arguments
def buy_product(user: User, product: Product):
  # below functions also do not consider working with None
  do_payment(user, product)
  add_product_db(user, product)
  log(user, product)


# calling it
if user and product:
  buy_product(user, product)

In result all data passed below buy_product is safe as it is always set. No need to handle optionality anymore.

Send some email

Our codebase has such a function for email sending.

def send_email(user, email_template, data):
  if user.active and user.email_notifications:
    smpt_conf = {# setting some email conf #}
    content = compile_template(email_template, data)
    my_email_service(
      smpt_conf, 
      user.email, 
      content, 
      title = data['title']
    )

Now new requirements comes and we need to send email to not a user, but somebody else. We have email, title, and even content which is compiled html. But... we clearly cannot use our send_email function as it is prepared only for users and only for some specific templates.

And this is because function which should just send email knows about users, knows when user can get email, knows how to generate email template. It knows too much.

def send_email(email, title, content):
  smpt_conf = {# setting some email conf #}
  my_email_service(smpt_conf, email, content, title)

The new version is simplified, has only knowledge about email things. Knows what and to what email should be send. Now it can be used in the new use case:

send_email(my_email, my_title, my_html)

And now using with user

def send_email_to_user(user, email_template, data):
  if user.active and user.email_notifications:
    send_email(
      user.email, 
      data['title'], 
      compile_template(email_template, data)
    )

Done, we have made send_email responsible only for sending emails, and send_email_to_user is domain related function which deals with sending emails to users.

And now small addition, if we take a look at send_email_to_user also is noop when our user is not active or has no email notifications turn on, why then this function needs to know it? Well, in this particular situation it can be fine to have function which is responsible for sending user emails, and sending it only when it is possible, we have this additional safety that email will not be send if should not be. Having function which sometimes does nothing is a tool which we should use but not overuse.

Am I logged in?

log_movement(request)
add_points(request)
send_sms(request)

Definitions of above functions:

def log_movement(request: Request):
  if request.session:
    log("movement", request.session.user.name)
  else:
    log("noop",'Anonymous user')

def add_points(request: Request):
  if request.session:
    db_add_points(request.session.user)

def send_sms(request: Request):
  if request.session and request.session.user.sms_notifications:
    sms_service("movement", request.session.user)

Now, what is wrong? Take a look that all these functions have the same problem and the same condition, they check if user has session and perform operation. Request object contains a lot of other informations, which are really not important for these functions, and if we would like to test them, we would need to mock all these details, mocking not used things is not specially joyful experience . Again, these functions know too much, let's fix it.

# definitions with less knowledge
def log_movement(user_name: string):
  log("movement", user_name)

# below function even not need to exists 
# as it just calls another
def add_points(user: User):
  db_add_points(user)

def send_sms(user: User):
  if user.sms_notifications:
    sms_service("movement", user)

# calling them
if request.session:
  user = request.session.user
  log_movement(user)
  add_points(user)
  send_sms(user)
else:
  log("noop",'Anonymous user')

Instead of moving responsibility to all functions, we just deal with the question once on the top, other functions have only what they wanted, nothing more.

In summary, if we can narrow functions domain and knowledge, we should do it, instead of passing the problem down, deal with it as soon as it can be solved. If function does not work for None do not use it with it, if many functions deal with the same problem, maybe problem can be solved before they are called? Of course it depends, and every choice you make in the code should be carefully considered, as there are no silver bullets.

Hide the constant, abstract the code

Pragmatic Maciej — Sat, 13 Mar 2021 20:19:09 +0000

We like to use constants, put them in some shared files and use them everywhere. Although, it happens that we don't recognise when not only the constant repeats, but also how the constant is used repeats.

Let me tell you about some error message

Somewhere deep in the source code, repeats an import, in this import, on top of many files, there is a "nicely" named constant STANDARD_ERROR_MSG.

Deep in all these files, there is also the use of the constant, the same, exactly the same in all of them:

import {STANDARD_ERROR_MSG} from 'constants';
// usage
<Error message={STANDARD_ERROR_MSG} />

Why my precious constant, why you need to be exposed to all these files, not better to sit in one spot? Some privacy would do, why everybody need to know you, my precious constant.

Precious constant hiding

const Error = ({message = "This is my precious error message"}) => 
  <p>{message}</p>;

// usage in code
<Error />

No constant anymore, but also one import less in every file using <Error />, no more copy/pasted props.

Implicit default value, bleh

Ok, some of you can say, previous was explicit and now we have implicit default value. True, but we can make it explicit and still not use the shared constant.

const Error = ({message}) => 
  <p>{message}</p>;

const StdError = () => <Error message="Std eror" />

We can go forward and make other kinds of errors:

const PermissionError = () => <Error message="No permission" />
const AuthError = () => <Error message="Not authenticated" />

After that we don't import constants, instead we import reusable components.

The story about groups

Developer task requires different logic for different users groups. No problem, said developer, no problem at all. Firstly as every good developer should, he checked how we distinguish users in the code base, and there he found:

import {Group} from 'constants';
// 3 times in the code base
user.groups.includes(Group.Marketing)
// 9 times in the code base
user.groups.includes(Group.IT)
// 22 times in the code base
user.groups.includes(Group.Management)

So let's add another use of these, shall we? No! No! Shouted developer. We copy the same logic, import the same constants, and we use these constants in the same way everywhere. I can do that better, said developer with a big dose of faith.

Let's name this, in other words, let's make abstraction from available use examples. Firstly abstract the calculation/logic:

const isGroupMember = (group) => (user) => user.groups.includes(group);

Ah, developer wants to look smart by this function returning another function. But looks like this has a reason:

// not exposed private enum
enum Group {
  Marketing,
  IT,
  Management
}
const isMarketingMember = isGroupMember(Group.Marketing);
const isITMember = isGroupMember(Group.IT);
const isManagmentMember = isGroupMember(Group.Management);

Wow, this clever developer made isGroupMember in such a way, that it is a factory for functions which address specific group. Clever!

Pay attention that we do apply first argument to isGroupMember and we get out function which takes user as argument and has pre-populated group already. In FP terms we would say isGroupMember is curried function, and we partially apply it.

Now the codebase has:

// 3 times in the code base
isMarketingMember(user)
// 9 times in the code base
isITMember(user)
// 22 times in the code base
isManagmentMember(user)

No constant use, but new primitives in form of functions, no copy/paste of logic. Our developer can play some games in the evening, he has earned that.

Check my status

Paid or not, the question should be ask in the code, so it is:

import {PaymentStatus} from 'constants';
payment.status === PaymentStatus.Completed

And we check like that in ten places maybe, but will be more. All these places need to import the constant, and make the check. Abstraction will save us again:

const isPaymentComplete = (payment) => 
  payment.status === PaymentStatus.Completed

No constant imports, no need to remember which field compare to which status (people using TS can say now - this argument doesn't apply to TS, and I agree), everything nicely abstracted and we have our new primitive.

Domain Specific Language

All these functions isManagementMember, isITMember or isPaymentComplete are our new primitives, and can be used in the codebase. They abstract implementation details, and we can focus on the higher business rules. Using constants without reusing the logic will not level up the abstraction, the detail remains. If we see the same constant used in the same way few times in the codebase, maybe it is a place for our new domain primitive expression?

The lonely constant

Pragmatic Maciej — Thu, 28 Jan 2021 22:05:07 +0000

All software projects have differences, but there are also things which never change, and one of them are utils - where we put all staff we don't know where to put, and constants file where we put all constants which we don't know where to put. There are also many variations of above, but still you will always find such place, or places in every project.

Among these constants we can find so-called "lonely constants".

The lonely message

In some famous constants file there is a lonely constant.

const MESSAGE_TITLE = "Welcome to the 'Some Site'"

After some codebase search looks like constant is used only in one module of the application. Why is it then shared and not inside the module? I assume the author or A) thought somebody will need it, B) author didn't know where to put this constant. No matter what was the reason, constant which belongs to one specific domain of the application, should be kept there and not be exposed. As I am not a fan of telling people about magical programming patterns or principles, you need to forgive me for this one. This situation is exactly violation of "You aren't gonna need it" principle.

The lonely cutter

In some famous constants file there is a lonely constant.

const CUTTER = 'cutter'

After some codebase search looks like constant is used cross the whole app. It is not a local thing, as in our previous example. This is properly made global, but after some while you see that there is something more, another constant used close to this one.

const BATTLESHIP = 'battleship'

Now the code which uses them:

if (ship.kind === BATTLESHIP) {
 ...
} else if (ship.kind === CUTTER) {
 ...
} else {
 ...
}

Now it should be clear. We have two constants, which are tightly connected, and even more, they are one thing - type of vessel.

enum VESSEL_TYPE {
  BATTLESHIP,
  CUTTER,
  OTHER
}

The very dry digit

In some module there is a lonely constant.

const TWO = 2

It is a local constant of the module, so at least it is not exposed. After code investigation, it was clear that the reason why it was a constant, was avoiding repetition. Developer have seen few '2' in the code, and as was taught to do, followed the DRY principle, and instead of repetition of '2', code had repetition of 'TWO' 😅, what a win...

In the code the incredible 'TWO' was used as number of digits after dot. So instead of naming it as just value synonymous, lets use name which defines the purpose.

const DECIMAL_PART = 2

Don't be so lonely my constant

To not make constants lonely, we need to follow common sense in naming, sharing and grouping of constants. If we will not share local things, if we will put proper names and if we will gather constants in domain enums/objects, then no constant will be lonely in our codebase.

The state you've never needed

Pragmatic Maciej — Tue, 12 Jan 2021 13:26:57 +0000

Every application has a state. State represents our application data and changes over time. Wikipedia describes state as:

A computer program stores data in variables, which represent storage locations in the computer's memory. The contents of these memory locations, at any given point in the program's execution, is called the program's state

And the most important part of this quote is "at any given point", what means that state changes over time. And that is the reason why managing state is one of the hardest thing we do. If you don't believe me, then remind yourself how often you needed to restart computer, tv or phone when it hangs or behave in strange way. That exactly, are state issues.

In the article I will show examples from managing state in React, but the advice I want to share is more broad and universal.

Where is the lion

Below code with some state definition by useState hook.

const [animals, setAnimals] = useState([]);
const [lionExists, setLionExists] = useState(false);

// some other part of the code... far far away 🌴
setAnimals(newAnimals);
const lionExists = newAnimals
.some(animal => animal.type === 'lion');
setLionExists(lionExists);

What we can see here is clear relation between animals and lionExists. Even more, the latter is calculated from the former, and in the way that nothing more matters. It really means whenever we change animals, we need to recalculate if lion exists again, and if we will not do that, welcome state issues. And what issues exactly? If we change animals and forget about lionExists then the latter does not represent actual state, if we change lionExists without animals, again we have two sources of truth.

The lion exists in one dimension

My advice for such situation is - if your state can be recalculated from another, you don't need it. Below the code which can fully replace the previous one.

const [animals, setAnimals] = useState([]);
const lionExists = (animals) => {
  return animals.some(animal => animal.type === 'lion');
};

// in a place where we need information about lion
if (lionExists(animals)) {
  // some code
}

We have two benefits here:
✅ We've reduced state
✅ We've delayed computation by introducing function

But if this information is always needed? That is a good question, if so, we don't need to delay the computation, but we just can calculate that right away.

const [animals, setAnimals] = useState([]);
const lionExists = 
  animals.some(animal => animal.type === 'lion');

And now we have it, always, but as calculated value, and not state variable. It is always recalculated when animals change, but it will be also recalculated when any other state in this component change, so we loose second benefit - delayed computation. But as always it depends from the need.

What about issues here, do we have still some issues from first solution? Not at all. Because we have one state, there is one source of truth, second information is always up to date. Believe me, less state, better for us.

Error, success or both? 🤷‍♂️

const [errorMsg, setErrorMsg] = null;
const [hasError, setHasError] = false;
const [isSuccess, setIsSuccess] = false;
// other part of the code
try {
  setSuccess(true);
}
catch (e) {
  setErrorMsg('Something went wrong');
  setHasError(true);
}

This one creates a lot of craziness. First of all, as error and success are separated, we can have error and success in the one time, also we can have success and have errorMsg set. In other words our state model represents states in which our application should never be. Amount of possible states is 2^3, so 8 (if we take into consideration only that errorMsg is set or not). Does our application have eight states? No, our application has three - idle state (normal, start state or whatever we will name it), error and success, so how come we did model our app as state machine with eight states? That is clearly not the application we work on, but something few times more complicated.

The pitfall of bad glue

In order to achieve consistent state we need to make changes together. So when we have error, 3 variables need to change:

  setErrorMsg('Something went wrong');
  setHasError(true);
  setSuccess(false);

and when success also:

  setErrorMsg(null);
  setHasError(false);
  setSuccess(true);

Quite a burden to always drag such baggage with us, and remember how these three state variables relates to each other.

Now let's imagine few issues created by such state model:
⛔ We can show error message when there is success state of the app.
⛔ We can have error, but empty box with error message
⛔ We can have both success and error states visible in UI

One state to rule them all 💍

I said our app has three states. Let's then model it like that.

const [status, setStatus] = useState(['idle']);
// other part of the code
try {
  // some action
  setStatus(['success']);
}
catch (e) {
  setStatus(['error', 'Something went wrong']);
}

Now we can also make functions which will clearly give our status a meaning:

const isError = ([statusCode]) => statusCode === 'error';
const isSuccess = ([statusCode]) => statusCode === 'success';
const errorMsg = (status) => {
  if (!isError(status)) {
    throw new Error('Only error status has error message');
  }
  const [_, msg] = status;
  return msg;
}

What benefit this solution has:
✅ We've reduced state variables
✅ We removed conflicting states
✅ We removed not possible states

Our application uses single state to model application status, so there is no way to have both success and error in one time, or have error message with success 👍. Also thanks to state consolidation, we don't need to remember what to change, and what variable is variable relation. We just change one place.

Few words about implementation. I have used tuple, because tuples are ok, but we could be using key-value map like {statusCode:'error', msg: 'Something went wrong'}, that also would be fine. I also made exception in errorMsg as I believe such wrong usage should fail fast and inform developer right away that only error can have an error message.

Add some explicit types

TypeScript can help with more explicit state modelling. Let's see our last example in types.

type Status = ['idle'] | ['success'] | ['error', string ];
const [status, setStatus] = useState<Status>(['idle']);

Above TS typying will allow for no typos, and always when we would like to get error message, TypeScript will force us to be sure it is error status, as only this one has message.

Summary

What I can say more. Putting attention at state modelling is crucially important. Every additional state variable multiplicates possible states of the app, reducing state reduce the complexity.

If something can be calculated from another it should not be state variable, if things change together, consolidate them. Remember the simplest to manage are things which does not change, so constants, next in the line are calculations, so pure functions which for given argument always produce the same value, and the last is state. State is most complicated because it changes with time.

Advanced TypeScript Exercises - Answer 10

Pragmatic Maciej — Mon, 02 Nov 2020 11:03:34 +0000

I've asked how to make different & operation by custom Merge type level function.

Note - if you don't recall what means - type level function please take a moment for reading - typescript is more than you think.

Solution 1 - Mapped Type

type Merge<A, B> = {
    [K in keyof A | keyof B]: 
        K extends keyof B ? B[K] : 
        K extends keyof A ? A[K] : never
}

What we are doing here is creating function Merge which is a mapped type. Mapped type allows for iteration over one type and mapping it into another type.

[K in keyof A | keyof B] - we iterate over union of keys from both types A and B, union will remove repeating keys in both types, so iteration will not need to go through them twice
K extends keyof B ? B[K] : K extends keyof A ? A[K] : never - we use conditional type in order to check if our current key belongs to key of type B, if no, we check if it belongs to type A, if not belongs to any of these, what is not possible, we fallback to never.

Note pay attention that we check firstly B type, so if the key is in B, we take value from B, it means we will overwrite eventual value from type A. Don't worry though, that was the requirement of the task.

Note I said that there is no possibility that key will not be either in A or B, because we iterate over keyof A | keyof B, so there is no option that key will not belong to any of them.

Solution 2 - Using Omit

type Merge<A, B> = Omit<A, keyof B> & B;

Yes that is the whole solution 😉. TypeScript type level standard library gives us functions like Omit which is really just mapped type as we did in the solution 1. So if there is ready to use function why not to use it?

Omit<A, keyof B> we make type which contains only keys of A which are not in B
Omit<A, keyof B> & B - we merge B type to already created type which has no intersection with B as keys of B where removed from A.

In result we have done the same thing as in previous solution,but with one line of code.

Special thanks for SirMoustache, hnicolas and others for their great answers in comments. You can find both solution in the playground.

This series will continue. If you want to know about new exciting questions from advanced TypeScript please follow me on dev.to and twitter.

Advanced TypeScript Exercises - Question 10

Pragmatic Maciej — Fri, 23 Oct 2020 12:13:18 +0000

Intersection type level operator & has changed in the last versions of TypeScript. The current behavior escalates 'never' type, so if any of fields will produce empty/never type, the whole composite will end as 'never'. Let's see some examples:

type X  = {
    a: 1
    b: number
}
type Y = {
    a: 2
    b: string
    c: boolean
}
// XY is never, as field 'a' evaluates as 1 & 2 which is never
type XY = X & Y

More about this TS behavior you can find here:

Exercise will be about having different intersection behavior. Our task is to write Merge type level function which will merge two product/object types. Our final Merge should be able to create a type from above X and Y in such a way that the latter type will overwrite types of fields of former type.

type XY = Merge<X,Y>
// XY should be {a: 2, b: string, c: boolean}

Link to the playground with the task.

Good luck! If you have a solution then don't hesitate to link it in the comment. Answer will be published soon!

This series will continue. If you want to know about new exciting questions from advanced TypeScript please follow me on dev.to and twitter.

Grow up

Pragmatic Maciej — Sun, 18 Oct 2020 18:15:16 +0000

Strong opinions about not important things, this is what developers community likes. Tabs vs spaces, React vs Angular, JS vs TS, Python vs PHP, OOP vs FP. These are just examples, we like to say our technology stack is better, our solution is a silver bullet, yes... but it's simply not true.

My code is better than yours

My code is better than yours, but what means better code? Isn't it a subjective statement? If you rewrite 'for loop' into 'reduce' only because you feel sick looking on any loop, it only means your goal has nothing to do with your project goal. All these articles which start with - "Never use x" or "Don't use y". What is the point? Point is to show how my opinion is better than somebody else's. Are there any proofs? No, only examples made to show the difference in a specific light, the one which works for the author. There is no reason to point somebody that he has used 'else' instead of 'early return', there is no point in fixing code which has switch instead of fancy using object keys. If you think your code is perfect, you didn't grow up.

Paradigm for every problem

I am an observer of people who try to show the rest of the programming community that FP is a better paradigm than any other, and everything else is just not worth trying. Most programs working in the wild and maintaining our society and industry were written in an imperative style of programming. You say imperative code is wrong, you didn't grow up.

Note. I am not saying FP is wrong, I am saying FP is not ideal, and is not a silver bullet.

OOP sucks

How common is to repeat that OOP is wrong, object orientation failed, you should never do OOP. Very, very popular opinion among so called FP programmers. The problem with this statement is that many people who say that, even don't exactly know how looks OOP and how to write object oriented code. They say classes and inheritance, strange and complicated patterns. And as I agree that you can very easily write wrong OOP by overusing tools, you can also make maintainable and readable code by separating your domain into objects with own responsibilities and state. Yes you can write good soft in object oriented paradigm. It is fully fair to prefer functional programming, but blaming OOP for all programming sins is a proof that you didn't grow up.

Static vs dynamic types

No difference is with static vs dynamic typing. One say - I don't need static types, there are no benefits of having it. Other say - dynamic type systems have one type, and are so error prone that you cannot do anything with them. I personally prefer languages with static type level, but I see the tradeoff, static type languages in order to achieve comparable expressiveness need to create very sophisticated ways of making polymorphism (for example Haskell typeclasses). Example of something which probably cannot be expressed in nowadays static typed languages are - transducers. Also there is quite a visible benefit of dynamic type languages in writing fast, small programs, they allow for rapid development. On the other hand static type languages give tools for code maintenance without a fear. You say - static types are useless - you didn’t grow up. You say there is no place for dynamic languages - you didn’t grow up either.
// Detect dark theme var iframe = document.getElementById('tweet-1317331148360437760-185'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1317331148360437760&theme=dark" }

Everybody needs to play the game by my rules

New project, lets force my rules. Very common is to see senior developers who enter the project and instead of understanding current codebase and current code decisions, like to say - let's rewrite it, or - everything is wrong because you don't use library x. As critical thinking is beneficial, rejection thinking is poisoning. If you want to rewrite somebody else code, only because you don't want to understand it, you didn't grow up.

I write my code in the ideal language

Every technology has flaws, has pros and cons. Some languages, libraries will work better for us in specific circumstances. Very often a better choice will be using libraries, languages which we already know. And it is ok. If your native language is let's say Polish, even though Polish is a very hard language, it is easier for you to describe some things in Polish than in English. But even though you can do that, it doesn't inherently mean Polish is in general better in describing these things, it only means the tradeoff is positive in this situation. If you choose Node.js for your server, only because you have a team of JS developers, it is ok, but don't fool others that you have picked Node.js because it is the best server side technology. If you say that the language you use is ideal - you didn’t grow up.

The real programming language

PHP is not a programming language. Why is PHP not programming when Python is? The difference is really syntax only, the same algorithms can be expressed in both. We can say objectively Python was better designed and has nicer syntax, but it doesn't make PHP not a programming language. If you say PHP is not programming - you didn't grow up.

The real programmer

Frontend is not programming. This is a far less common opinion than it was some time ago. But I remember times, when BE developers were proud to be "real programmers". If you think so, you didn't grow up.

I have opinion on every subject

Not knowing something is fully ok, it is totally fine that you are not expert in everything. It is better to say simply "I don't know" instead of stating some nonsense and pretending you know what you are talking about. Even though you are experienced developer who is considered as senior from seniors, even then, you can say "I don't know". If you try to have opinion on things which you have no idea about, you didn't grow up.

Everything is a tradeoff

Enough examples. Be critical, see pros and cons, understand your tools, don't believe in your tools. Languages differ from each other, but most are capable of doing the same things. Hating or loving is not what we should do, being a fanboy does not make you better in your job. Sitting ten years in one language either. Change languages, change domains, learn from other people, you are senior in JS, great but don't be afraid to work with Java as a junior dev, changes will make you a better programmer in general.

Apply agreed project rules

Code should be consistent, projects should have coding rules, and everybody should obey these rules. If we agree that we use FP concepts like maps and reduce, then let's use them, if we agree on specific code conventions, let's obey it, if we do unit tests, let’s do them, even though you don't feel the benefit. If rules are to be fixed, let's discuss that, let's propose, don’t force. Some of your team members can be not comfortable with things you are comfortable with, you need to help them, take them to your level. But also, maybe it is not the time for that, maybe you need to postpone your ideas.

Have positive impact

Having no strong opinions doesn’t mean you don’t care about code quality or agree on bad solutions. You still see bad, good code, you still refactor bad code, you still try to push better solutions. What is different, is that your decisions are not based on the one framework you know, or what is currently trendy. But your decisions are based on your knowledge, on your experience, are not based on being a fanboy of solution X. You see tradeoffs, not silver bullets. If your decisions are based on experience, you are able to describe and explain them better, you are able to introduce your ideas and concepts without forcing them.

This post is written to myself from the past. Yes, I was a developer with strong opinions. I've needed a very long time to understand that such an attitude makes me weaker. I hope you will understand this faster than me. Also, as a last, take into consideration that some of your programming colleagues will never grow up.

Advanced TypeScript Exercises - Answer 9

Pragmatic Maciej — Mon, 17 Aug 2020 08:53:33 +0000

Hi folks. It was a while, sorry for such a big delay between next challenges. But here we are again 😁. The good news is also that the whole series was checked against newest TS and after few changes every code snippet works! So feel free to start with the whole series if you haven't yet, as its up to date with TS 4.0.

Now to our question - How to make NonEmptyArray type which doesn't include [] value as a member.

Solution 1 - rest parameters in tuple types

type NonEmptyArray<T> = [T, ...T[]]

The solution is very clean and clear. What we do is - we explicitly set first element as T and spread the rest as array of T, in result the type force to have 0 index filled by T. This is possible because of rest parameters in tuple types language feature.

Solution 2 - by intersection

type NonEmptyArray<T> = T[] & { 0: T };

Second solution in my own opinion is also great, we use simple intersection & and create an array type T[] which needs to have 0 index element as T. In result first item of array cannot be empty.

Both code snippets are available in The Playground

This series will continue. If you want to know about new exciting questions from advanced TypeScript please follow me on dev.to and twitter.

Mutation is ok

Pragmatic Maciej — Mon, 06 Jul 2020 11:08:44 +0000

The phrase - "mutation" started to have almost negative connotation in our programming community. It's like something wrong to mutate. As if we mutate we are not writing our beloved functional code anymore. Is mutation so evil? Or maybe some misuses are? Let's dive in.

Statements

Functional programming is commonly about programming with using expressions only, and expression is something which evaluates to a value, therefore it has no side effects. But what if a function locally uses imperative statements, what can go wrong?

// expression based
const userName(u: User)  => u.secured ? "No access" : u.name;

// statement based
function userName(u: User) {
  if (u.secured) {
    return "No access";
  } else {
    return u.name;
  }
}

Ok so probably most of you don't see issues with both options, even though in the second I have used statements. We can then use statements in functional programming. I hope we agree at this point.

Note I am deliberately using arrow function for expression based as arrow function is an expression, where function declaration is a statement.

Local mutation

// declarative / expression based
const removeInactive (users: User[]) => 
  users.filter(user => user.active)

// imperative / statement based
function removeInactive (users: User[]) {
  let newUsers = []
  for (u in users) {
    if (u.active) {
      newUsers.push(u)
    }
  }
  return newUsers;
}

Now the code is more controversial. Declarative code is short, has no variables, it is also more readable for anyone having fp basics. The imperative one is longer, has variables and has local mutation.

For sure I would pick the first option if somebody would ask me - which code is better for you. But, if somebody has written the second, then does it create any problems for our code-base?

Looking from helicopter view on how functions behave, both are

referential transparency (for the same input gives the same output)
have no side effects

Looks like from the interface perspective these functions are equivalent, both functions are pure mathematical functions. If some developer would write imperatively such function, and put it into some library, nobody would notice, and even nobody would care. And that is the thing. What is inside this function is - implementation details.

Note Still if we consider comparison of local complexity there is a clear winner.

Reduce it

Many say that reduce can be overused, and many times when we use reduce code is just over-complicated. In my experience I have never seen reduce as a problem, but if we start to use it as a hammer, it can start to be a problem.

// reduce version - declarative
const intoCSV = (users: User[]) => 
   users.reduce((acc, user) => {
     const prefix = acc.length === 0 ? "" : ",";
     return acc + prefix + user.name;
  }
  , "");

// for..of version - imperative
function intoCSV (users: User[]) {
  let csv = "";
  for (const user of users) {
    const prefix = csv.length === 0 ? "" : ",";
    csv = csv + prefix + user.name; 
  }
  return csv;
}

In terms of input -> output both versions of intoCSV are again the same. These are pure functions even though inside of the second there are statements and variables. But readability argument is not so obvious as in previous examples. The reduce version is not far better. I would say there is no clear winner here.

Copy or not to copy

// reduce version - declarative
const intoUsersById = (users: User[]) => 
   users.reduce((acc, user) => ({...acc, [user.id]: user })
  , {} as { [k: number]: User });

// for..of version - imperative
function intoUsersById (users: User[]) {
  let byId: { [k: number]: User } = {};
  for (const user of users) {
    byId[user.id] = user;
  }
  return byId;
}

Next example shows another issue with the declarative version. This is also common, overusing copying of the structure. In the example we make a shallow copy of our final object during every "iteration". This has a real impact on the performance. Of course not as we should be very afraid, but if our collection is processed by node.js/deno we should worry. Some more thoughts about this aspect you can find in my previous article Data mutation in functional JS.

Still you should not be worried to make a mutation here. Its local not shared variable, nobody can use it until you will be done. Mutation is allowed and preferable in this case.

Note my point is here not against reduce. I like and use reduce, but we need to understand the trade-off. Also we can make mutation and use reduce.

Why are people saying mutation is wrong?

First of all people are saying many things, and not all of them are correct 😉. Second of all, we have currently hype for FP, the hype is so strong that some people just go into dark corners of the paradigm, and claim FP supremacy even in places where there are no arguments to prove it. And I am also fan of FP, but I also follow common sense.

And yes if we work with expression based language like Haskell, Elm, PureScript, then we write only expressions and pure functions, but this is exactly how these languages were designed.

In multi-paradigm languages like TypeScript, JavaScript, Java, C# and so on, we should understand that language is not made for some concepts, and also that there are statements and mutations. If we know when it's safe to use that, everything should be ok.

But when mutation is really wrong?

Everything which does not belong to the function should not be mutated. By "belong" I mean something created inside the body of the function. In other words, we can mutate our local variables, but we should avoid mutation of external state and input arguments. If we follow the rule then mutation should not bite us.

And this concept is commonly known, even Rust language made from this its core concept. Take a look at borrowing.

Summary

Imperative core, functional shell.. wait what? Yes, so common architecture pattern is "Functional core, imperative shell", and it is about putting side effects to the border. I am starting some mini-series about exactly making such imperative shell here. But what we are doing in this article is reverse of that, we use micro-mutations in order to produce some data inside pure functions. And don't be afraid to do so, until outside the function is referential transparent everything is good.

If you like this article and want read more from me, follow me on dev.to and twitter.