DEV Community: Konstantin

Persistent routes

Konstantin — Tue, 28 Sep 2021 12:56:16 +0000

Hi, everyone. I'm sure you know, route management in an enterprise project is a tricky task. Enum (typescript data structure) is often used to keep them persistent. But enum itself doesn't solve all problems while we handle the route concatenation. Let's take a look at an example.

Suppose we have three levels of nesting routes:

enum ROOT_ROUTES {
  CATALOG = 'catalog',
  ABOUT = 'about',
  SUPPORT = 'support',
}

enum CATALOG_ROUTES {
  CATEGORY = 'category',
  ITEM = 'item',
  CART = 'cart'
}

enum CATEGORY_ROUTES {
  TOP = 'top',
  SALES = 'sales',
  ALL = 'all'
}

Then, in order to assemble the full route, we have to correctly concatenate all the intermediate values:

const topCategoryRoute = `/${ROOT_ROUTES.CATALOG}/${CATALOG_ROUTES.CATEGORY}/${CATEGORY_ROUTES.TOP}`;

It's a very bad idea to keep it just as it is. I'm sure you don't do that. It's easy to overlook any nesting level. And if similar code starts to appear in several places of project, we violate the DRY principle. It will also lead to problems in the future when we want to change the navigation.

The situation looks better when we add global constants with the routes already concatenated:

const rootRoutes: { [key in keyof typeof ROOT_ROUTES]: string } = {
  CATALOG: `/${ROOT_ROUTES.CATALOG}`,
  ABOUT: `/${ROOT_ROUTES.ABOUT}`,
  SUPPORT: `/${ROOT_ROUTES.SUPPORT}`
}

const catalogRoutes: { [key in keyof typeof CATALOG_ROUTES]: string } = {
  CATEGORY: `${rootRoutes.CATALOG}/${CATALOG_ROUTES.CATEGORY}`,
  ITEM: `${rootRoutes.CATALOG}/${CATALOG_ROUTES.ITEM}`,
  CART: `${rootRoutes.CATALOG}/${CATALOG_ROUTES.CART}`
}

// It's terribly tedious even just to write this example.
// Let's move on to the final part.

And even so, we are not immune to mistakes.

Let's try to automate the process to get rid of the routine and reduce the human factor. I started to think not from what I can do, but from what I want to get.

Suppose we already have rootRoutes with a signature corresponding to ROOT_ROUTES. I would like the rootRoutes properties to behave like primitive values in operations, but at the same time have a method for the subsequent concatenation of routes. Something like that (TDD in action):

// https://nodejs.org/api/assert.html#assert_assert_strictequal_actual_expected_message
assert.strictEqual(`${rootRoutes.CATALOG}`, '/catalog')
const catalogRoutes = rootRoutes.CATALOG.concatRoutes(CATALOG_ROUTES);
assert.strictEqual(`${catalogRoutes.CATEGORY}`, '/catalog/category');

The implementation of the [Symbol.toPrimitive] method in the class will help us achieve this.

Final result:

class Route {
  constructor(private _value: string) {}

  [Symbol.toPrimitive]() {
    return this._value;
  }

  concatRoutes<R extends Record<string, string>, K extends keyof R>(routes: R) {
    return Object.fromEntries(
      Object.entries(routes).map(([key, value]) => [key, new Route(`${this._value}/${value}`)])
    ) as { [key in K]: Route };
  }
}

const rootRoutes = new Route('').concatRoutes(ROOT_ROUTES);

Thank you for reading. Please share, how do you manage routes in your project?

Design predictable GraphQL API

Konstantin — Sun, 15 Aug 2021 13:54:58 +0000

Today I am going to tell you how we design our GraphQL API and how we make it predictable.

Unfortunately, knowledge of GraphQL doesn’t answer the question how to design API. And I would be happy to find such an article when we started. Every time we faced problems, we had to make decisions on the go. Some of them took root, while others were altered as a result of retrospective. Finally, we made a number of strict rules that have been helping us structure our API without freedom of interpretation for a long time. I have no illusion that these rules will work for every project. But I'm sure they can help many of us find answers when we need them.

Queries

Let's take a look at the book accounting service API for a some Library as an example. We will operate with such entities as author, book, collection and user.

Rule #1: provide a resolver to get entity data named according to entity name

In our example, we will declare 4 resolvers to get the data of the corresponding entities

type Query {
  author(id: ID!): Author 
  book(id: ID!): Book
  collection(id: ID!): Collection
  user(id: ID!): User
}

In relationships between entities, this rule also works

type Book {
  id: ID!
  title: String!
  author: Author!
}

Rule #2: provide a resolver to get a list of entity data named according to the entity's plural name*

There are several nuances here. Data lists can be either limited or not. For small limited lists, you can simply return an array of items

type Collection {
  id: ID!
  title: String!
  books: [Book!]!
}

But of course, we cannot do this with either authors, books, or users, because these lists have no limits.

Rule #3: unlimited lists must be paginated

There are two common types of pagination: offset-based and cursor-based. The truth is, you will most likely want to use both for different tasks. So, for the offset-based paginated list we leave the entity name in the plural and for cursor-based paginated list we add the Connection suffix (*).

type Query {
  authors(offset: Int, limit: Int): Authors
  books(offset: Int, limit: Int): Books
  booksConnection(
    before: String
    after: String
    first: Int
    last: Int
  ): BooksConnection
  collectionsConnection(
    before: String
    after: String
    first: Int
    last: Int
  ): CollectionsConnection
  users(offset: Int, limit: Int): Users
}

As you can see, the object types for paginated lists are named according to the resolvers.

Rule #4: resolvers must be universal regardless of the client's access level

You should not create different resolvers to receive data from the same entity, depending on the access level. There are other ways to differentiate access to fields such as schema directives.

# 😡 Bad way
type Query {
  user(id: ID!): User
  userByAdmin(id: ID!): UserByAdmin
}

type User {
  id: ID!
  login: String!
}

type UserByAdmin {
  id: ID!
  login: String!
  email: String!
}

# 😊 Good way
directive @auth(requires: Role = ADMIN) on OBJECT | FIELD_DEFINITION

enum Role {
  ADMIN
  GUEST
}

type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  login: String!
  email: String! @auth(requires: ADMIN)
}

Rule #5: add resolvers as fields to entity types to calculate their characteristics instead of separate resolvers

In GraphQL, any field of an object type can return not just the data stored in it, but be processed by a separate resolver. Due to this, the entity dataset can be enriched with additional, calculated parameters.

# 😡 Bad way
type Query {
  book(id: ID!): Book
  isBookBorrowed(id: ID!): Boolean
}

# 😊 Good way
type Query {
  book(id: ID!): Book
}

type Book {
  id: ID!
  title: String!
  author: Author!

  isBorrowed: Boolean!
}

Rule #6: if requested data doesn't exist, you must return `null` or empty list `[]` instead of an exception

The main point of this rule: you should not throw an exception in query resolvers. Lack of data is not a error.

You may have noticed in the query resolvers examples above, there is no Non-Null modifier (!) for the return data type. It means that these resolvers can return null instead of object types.

In cases where a list is supposed, you must return an empty array []. You should always use the Non-Null modifier in conjunction with the list modifier [Entity!]!. You don't need other combinations [Entity], [Entity!] or [Entity]! which will allow you to pass null instead of a list or as an item.

type Query {
  collection(id: ID!): Collection
}

type Collection {
  id: ID!
  title: String!
  books: [Book!]!
}

Mutations

Rule #7: CRUD mutations of an entity must be named according to the pattern `${operation}${Entity}`

type Mutation {
  createUser(userData: CreateUserInput!): User!
  updateUser(userData: UpdateUserInput!): User!
  deleteUser(id: ID!): User!
}

Rule #8: CRUD mutations of an entity must return entity data

As in the example above, even a delete mutation returns deleted entity data.

Rule #9: it is necessary to distinguish between arguments that are heterogeneous data and the input data of an entity

Parameters of single entity must be combined into input object type and passed in one argument.

type Mutation {
  createUser(userData: CreateUserInput!): User!
}

input CreateUserInput {
  login: String!
  email: String!
}

Dissimilar arguments must be passed separately.

type Mutation {
  borrowBook(userId: ID!, bookId: ID!): Borrowing!
}

Rule #10: the name of the input type must match the pattern `${Mutation}Input`

type Mutation {
  createUser(userData: CreateUserInput!): User!
  updateUser(userData: UpdateUserInput!): User!
}

Rule #11: the name of the argument corresponding to the entity's input type must match the pattern `${entity}Data`.

type Mutation {
  createUser(userData: CreateUserInput!): User!
  updateUser(userData: UpdateUserInput!): User!
}

Rule 12: all fields of the input type of the update mutation except the identifying ones must be optional

type Mutation {
  updateUser(userData: UpdateUserInput!): User!
}

input UpdateUserInput {
  id: ID!
  login: String
  email: String
}

This rule allows you to use a single mutation to update different parts of the entity separately.

mutation UpdateUserEmail {
  updateUser(
    userData: {
      id: "User ID"
      email: "New e-mail"
    }
  ) {
    id
    email
  }
}

Rule 13: if for some reason the operation cannot be performed, an exception must be thrown

In this regard, mutations are different from queries.

Conclusion

The subscriptions are remaining overboard for now. We continue to gain experience with them and maybe later I will share the results with you.

I would love to discuss these 13 rules with you (don't let the number scare you). Please share your experience on how you approach API design in your projects. Tell me in what cases these rules will not work and how you get out of the situation.

Thank you for your attention!

WSL is still not ready for development

Konstantin — Fri, 09 Aug 2019 12:52:17 +0000

Hello, I'm a front-end developer, and today I want to tell you about my experience with WSL.

As developers, we choose UNIX-systems because of the easiest way to set up the needed environment. That's why the first thing you do when you buy a windows laptop is installing Linux.

But since Microsoft introduced WSL, there are a lot of articles on the internet about how to set up a convenient working environment using this technology. The advantage of this approach is that you do not lose the windows environment. Sometimes this can be important for your hardware, for your user experience, or if you still want to use any Windows applications. And I honestly tried to do it for about a year. During this time I was lucky to participate in several projects. However, in almost all of them, I came across various kinds of problems.

Tools

Firstly, I was slightly annoyed by the fact that in addition to installing git in WSL, I had to install git on Windows to activate VSCode functions. And these were two different versions of git, which did not lead to any negative consequences, but the fact itself was alarming. I also tried this solution https://github.com/andy-5/wslgit, but the GitLens extension doesn’t work with it.

The second unpleasant thing was the Windows console. We must pay tribute, Microsoft has greatly improved it in the latest editions. However, this is still not comparable to the solutions that are for Linux. I know there are projects like Hyper and Terminus. But they are slower, than default CMD. Maybe this is because they are based on Electron, I'm not sure. That's why I'm used CMD. And I also used improved window layouts in Windows 10 to display up to 4 console windows on one desktop. For working with windows and desktops in Windows 10, I can only praise Microsoft. It's done cool. But you are not here to listen to laudatory comments about Windows and Microsoft, you want to know what can upset you.

Colors ... colors in CMD ~~sucks~~ is not good. And I hate the configuration of it. There are great turnkey solutions that change the CMD color scheme through the Windows registry, and I also created my color scheme (attention, at times the combination of text color and selection is unreadable). But be very careful, because if you try to change the color scheme in the CMD properties settings, it will be saved in the shortcut data and the settings from the registry will not be applied... 😫 You can read more about this here.

Below I will talk about what problems with WSL I had directly in work.

Development

If you are a front-end developer and begin your journey in the development of mobile applications, perhaps you will choose to React Native as it is pretty close to what you already know. And in this case, Expo will be a good choice as a toolkit, because it is very convenient and easy to start. I did just that and... ran into the rather strange problem, described in this issue https://github.com/expo/expo-cli/issues/99.

After several minutes of Expo's work, all network requests fail. Only restarting WSL helped. It was very difficult to work in this mode. Having found this issue, I found a comment by Alexander Martin: "Can confirm that Windows Insider Build 18890 fixes this issue". Since it was very important for me to establish a workflow, I had to switch to Insider Preview mode. And yes, after that, Expo worked fine, and as a bonus, I got a broken hibernation mode, problems with getting out of sleep, and small problems with sound on my laptop.

The next time I needed to install MongoDB locally, however, as stated on the official website: "MongoDB does not support WSL". I have no solution in this regard because in the end a remote connection was used.

The last factor that convinced me to return to Linux was the need to develop an application on Electron. Since WSL does not support window mode, this is not possible.

Besides, there were other cases when something did not compile or did not work as expected, but I can't recall the details.

You may notice that these cases are not directly related to front-end development, but I did not set myself such a goal. I just want to warn you that whatever you do, the WSL may fail you, and sometimes it can be critical.

Conclusion

We prefer Linux to Windows because it simplifies the search for tools, the setup of the working environment and allows us to focus on solving problems. However, WSL is currently even worse than pure Windows, because it looks like the perfect solution and breaks at the most unexpected moment. At the same time, WSL problems are worse to solve, because for the community it is still a dark horse.

Now I am returning to Linux, I hope you take into account my experience and avoid my mistakes. However, if you still decide to try WSL yourself, I think this will be useful to you. Thanks for attention and please comment about your cases.

DEV Community: Konstantin

Persistent routes

Design predictable GraphQL API

Queries

Rule #1: provide a resolver to get entity data named according to entity name

Rule #2: provide a resolver to get a list of entity data named according to the entity's plural name*

Rule #3: unlimited lists must be paginated

Rule #4: resolvers must be universal regardless of the client's access level

Rule #5: add resolvers as fields to entity types to calculate their characteristics instead of separate resolvers

Rule #6: if requested data doesn't exist, you must return null or empty list [] instead of an exception

Mutations

Rule #7: CRUD mutations of an entity must be named according to the pattern ${operation}${Entity}

Rule #8: CRUD mutations of an entity must return entity data

Rule #9: it is necessary to distinguish between arguments that are heterogeneous data and the input data of an entity

Rule #10: the name of the input type must match the pattern ${Mutation}Input

Rule #11: the name of the argument corresponding to the entity's input type must match the pattern ${entity}Data.

Rule 12: all fields of the input type of the update mutation except the identifying ones must be optional

Rule 13: if for some reason the operation cannot be performed, an exception must be thrown

Conclusion

WSL is still not ready for development

Tools

Development

Conclusion

Rule #6: if requested data doesn't exist, you must return `null` or empty list `[]` instead of an exception

Rule #7: CRUD mutations of an entity must be named according to the pattern `${operation}${Entity}`

Rule #10: the name of the input type must match the pattern `${Mutation}Input`

Rule #11: the name of the argument corresponding to the entity's input type must match the pattern `${entity}Data`.