DEV Community: Quod AI

5 Best Dev Tools for Code Search

Quod AI — Fri, 02 Jul 2021 03:53:02 +0000

Today’s article is slightly different from our usual ones. If you’re a developer there is no doubt that you might've gone through the process of searching for code. It can be through the code repository of your organization and you’re trying to implement something new, or it might just be another hobby project and you’re clearing your doubts from StackOverflow. Today, we will take a look at the 5 best dev tools for code search.

This article was originally posted at: https://www.quod.ai/post/5-best-dev-tools-for-code-search

Developers and code search

Increasing code base sizes and sophisticated logic are prompting developers to search through code more often. According to a study, it is found that developers search through code at least 5 sessions a day. Most of the searches are surrounding the use of particular APIs, where a particular code is located, how a piece of code is failing, or what a piece of code does. Code search is becoming a crucial part of software development and developers must be equipped with the right tools.

According to the results of the study, we will narrow down our comparison to certain aspects of the tools. Here are two tables to ease the process of understanding what the criteria will be.

With these statistics in mind, we will lay down the basic criteria that we will use to compare the tools. We will assess the tools based on their ability to do the following:

Get code examples
Advanced search options
Code impact analysis

GitHub

Ideal for: public code examples
Pros: easy to use
Cons: hard to find exact code and to filter to what you want

GitHub has over 190 million repositories and is the largest host of source code in the world. GitHub has tons of features for searching through code and the code review is extremely useful. The default code search in GitHub is not very powerful and the options are very limited. But with the advanced search, you can fine-tune your search by specifying the repository owners, the number of stars that it has, the size of the file, the extension, the number of issues on it, and more.

GitHub is the place you want to be if you want to get code examples. Due to the enormous amount of code hosted on it, there is always something or the other that fits your criteria when looking for examples.

In terms of searching, there are a lot of advanced options available, but to make the most of it, you will need to know what exactly you’re searching for. GitHub doesn’t let you search for exact pieces of code but rather only by project and file names. Searching for example repositories is pretty straightforward, and you can use the search bar to search for it from your current repository, your current organization or from all of GitHub.

The advanced options might not ring any bells if you haven’t seen them before. Since GitHub also powers the Git version control system, it can be used to review pull requests, view the impact of merges if there are any conflicts, and take necessary corrective action.

Quod AI

Ideal for: in-depth code search, impact analysis
Pros: easy to use interface, integrates with Git/Github, JIRA, versatile code search
Cons: programming languages is limited to Javascript, Typescript, Java, Python and Ruby

Quod AI is an AI-powered tool that does a lot of the work for you. It allows you to search for code, find experts and impacts from GitHub repositories as well as from Jira issues. QuodAI can be a great tool if used in addition to GitHub because both of them complement each other very well. If you have found a particular code example that you’re looking for on GitHub, you can connect the repository to Quod AI.

Once the connection is made, Quod AI uses artificial intelligence to scan through the entire repository and generate questions and tags. These questions redirect you to code snippets where the particular operation is performed and the tags will redirect you to all the snippets where that tag might be relevant. For example, if there is a tag called API, it will take you to all the controllers in your source code where an API may be implemented. The advanced search allows you to filter down to technical tags, business tags, the path (right down to a specific file), modified date, and file extensions. The UI is very simple to get accustomed to and there is also a quick demo to walk you through everything when you first start.

VSCode

Ideal for: searching local code
Pros: de-facto text editor for software development, plethora of extensions available
Cons: code search is not very feature-rich

VSCode is Microsoft’s very own code editor that has become the de-facto standard in the industry. It is being used by a huge majority of developers thanks to the rich ecosystem of extensions that it supports. Once you have a working repository on your machine, you can open it in VSCode to search through it. Searching is not very feature-rich but is pretty good for a code editor. VSCode has extensions with Git that can show a preliminary impact analysis but again, this is restricted, considering it is a code editor.

SourceGraph

Ideal for: searching through large codebases
Pros: supports multiple repository types, code search is fast
Cons: complex-UI, need to understand querying

SourceGraph is a web-based code search and navigation engine. In our opinion, it has a complex UI and will need some getting used to. You can link your GitHub or GitLab accounts and select the repositories you want to search for or you can add public repositories as well. Their searching is fast and there are quite a few advanced search options that you can try. The searches are made through certain queries which you can find here, so it is a little difficult for someone trying it for the first time to try and understand these. It doesn’t have any functionality to view the impacts as well.

‍

Opengrok

Ideal for: searching through code quickly, better suited to more advanced users
Pros: supports multiple version control systems, fast code search
Cons: difficult to set up, initial configuration is a little difficult

Opengrok is a source code browser and code navigation tool. It is extremely fast to search for code and can make complex search queries but the initial configuration required is a little difficult for the faint-hearted. But they do have a Docker image which simplifies the process. Opengrok is an extremely feature-rich code browser and it supports full-text search, definition and identifier search, path and history search, API searches, using logical operators to chain queries, etc. It supports a lot of version control systems like Git, RCS, CVS, Monotone, and more. Opengrok too doesn’t support any kind of impact analysis.

Conclusion

That’s it for our 5 best dev tools for code search. In our opinion, the tool that you use depends a lot on what you’re trying to achieve. We think that to get the best results, you shouldn’t stick to one tool, but use them in conjunction to maximize efficiency.

How to structure your Java apps using JHipster

Quod AI — Fri, 14 May 2021 02:06:52 +0000

7 years ago, JHipster had its initial release. It allowed developers to generate code for modern web applications that utilize the microservice architecture. Today, it has grown so much with its main focus being developer productivity.

This article was originally posted at: https://www.quod.ai/post/how-to-structure-your-java-apps-using-jhipster

Introduction to JHipster

JHipster, in simple terms, is a code generator that can get you up and started with building applications very quickly. But the simplicity of JHipster ends with that sentence there. It can be used for building the most modern applications following cutting-edge patterns and technologies. The fact that they make it so easy to get started is their ultimate selling point. The best part is that it is all open source. The ‘J’ in JHipster stands for Java and it is directed at Java applications. Today we will take a look at some of the core components of a Java Spring Boot application that is generated by JHipster for you.

RESTful APIs using Spring Web

Spring Boot makes it very straightforward to implement complex concepts through the use of annotations. That is one of the biggest advantages of Spring Boot, that a lot of the configuration is hidden from the user and it takes an opinionated approach on what is the minimum that needs to be there for the application to run. Below is an example of a GET request to activate a particular user from the JHipster repository.

@GetMapping("/activate")
public void activateAccount(@RequestParam(value = "key") String key) {
    Optional user = userService.activateRegistration(key);
    if (!user.isPresent()) {
        throw new AccountResourceException("No user was found for this activation key");
    }
}

View UserController.java in context at Quod AI

Line 1: The @GetMapping annotation marks the method to be executed when the exact URL path is hit from the browser or some tool like Postman. It tells that it is a GET request and the path is “/activate”. Assume you run the application on your localhost on port 8080, the URL would be localhost:8080/activate.

Line 2: This line shows the method name and the arguments that it accepts. We have another annotation here called @RequestParam, with the value as ‘key’. This tells that the request will have a parameter in the URL called key, with its associated value. The URL would look like this: localhost:8080/activate?key=_some_value_.

Line 3-5: The next three lines implement the logic for activating a user. We call the activate method on the userService, passing in the key that we got as a request parameter. It returns an Optional value of User and this is checked to determine whether the user is activated or not.

Database entities and executing queries

Repositories are used to query the database and, in this example, we will take a look at the UserRepository and a few methods associated with it. But before that, we need to understand what the User entity consists of.

@Entity
@Table(name = "jhi_user")
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public class User extends AbstractAuditingEntity implements Serializable {


    private static final long serialVersionUID = 1L;


    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "sequenceGenerator")
    @SequenceGenerator(name = "sequenceGenerator")
    private Long id;


    @NotNull
    @Pattern(regexp = Constants.LOGIN_REGEX)
    @Size(min = 1, max = 50)
    @Column(length = 50, unique = true, nullable = false)
    private String login;


    @JsonIgnore
    @NotNull
    @Size(min = 60, max = 60)
    @Column(name = "password_hash", length = 60, nullable = false)
    private String password;

View User.java in context at Quod AI

Line 1-3: The @Entity annotation marks this class as a database entity and the @Table annotation denotes that it represents a table with the name ‘jhi_user’. The @Cache annotation is used to denote that this entity will be part of the cache and the strategy used for caching is NONSTRICT_READ_WRITE. This is used for entities that are updated less frequently and also where two transactions would try to update the same item.

Line 5-53: These are the different fields present inside the user table. There are quite a few annotations to understand here. The @id annotation tells us that this is the primary key of the table. It has a generated value, meaning we don’t have to explicitly set it, which is done through a sequence generator. The @Column annotation depicts different columns of the table. @Size specifies the max size whereas @notnull denotes that it cannot be null.

Next, we will execute a database query using Spring Data JPA. Spring uses the @Repository annotation to abstract out a lot of the boilerplate code that was earlier required to make database queries. The below example is to execute a query to return a single user with a particular activation key. Remember the REST API we looked at before that checked whether a user is activated or not? This query is executed as a part of that operation.

@Repository
public interface UserRepository extends JpaRepository {
    Optional findOneByActivationKey(String activationKey);  
 }

View UserRepository.java in context at Quod AI

Line 1-2: The first line denotes that the following interface is a repository. We extend the JpaRepository with the entity class name and the type of its primary key, which is Long. This gives us access to a lot of predefined methods that perform queries behind the scenes.

Line 3: The query that we want to execute here is to find one user from that table with a specific activation key. In traditional SQL, it would be SELECT * FROM USER WHERE ACTIVATION_KEY = “key_value”. But with Spring Data JPA, we can write it as findOneByActivationKey(String activationKey). How does this work? Remember when we defined the columns, we specified the activation key as String. This allows Spring Data JPA to enable this method for us. One calling this method with a key as an argument, it will return a User entity if they exist otherwise null.

Testing using jUnit5

If you’re a Java developer, you must be familiar with jUnit testing. With jUnit 5, they’ve brought about some good additions to make it easier for testing your code. A new addition is the @BeforeEach annotation which you can see in action below.

@BeforeEach
public void initTest() {
    user = initTestUser(userRepository, em);
}

View UserTest.java in context at Quod AI

Line 1-3: The first line marks the following method to be done before each test case. The initTest() method calls another method initTestUser() in the test file passing in the repository object and the entity manager object. This is then used to create a mock object for the user for all the test cases.

Another great new addition is that of lambda functions within test cases. Below is an example of using lambda functions in our test cases. Don’t worry about the logic present here. It simply gets the size of the database before the user is deleted, performs the deletion operation, and checks whether the size has decreased by 1.

@Test
@Transactional
void deleteUser() throws Exception {
    // Initialize the database
    userRepository.saveAndFlush(user);
    int databaseSizeBeforeDelete = userRepository.findAll().size();


    // Delete the user
    restUserMockMvc
        .perform(delete("/api/admin/users/{login}", user.getLogin()).accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isNoContent());


    assertThat(cacheManager.getCache(UserRepository.USERS_BY_LOGIN_CACHE).get(user.getLogin())).isNull();


    // Validate the database is empty
    assertPersistedUsers(users -> assertThat(users).hasSize(databaseSizeBeforeDelete - 1));
}

View DeleteUserTest.java in context at Quod AI

Line 1-2: Denotes that this is a test case. @Transactional specifies that the following method will perform a database transaction and it will need to satisfy certain rules like not allowing updates if it gets cancelled in between, and ensuring that the database state is stable before and after the operation.

Line 5-6: We initialize the database here and then get the number of users present in the database. This is stored in the variable databaseSizeBeforeDelete.

Line 9-12: We then perform the delete operation on the user which accepts JSON input and the expected status is that of no content.

Line 13-16: Here we check two things. One is that we assert that the user is not present in the cache. Second, we assert that the database size has decreased by 1. If you see Line 16, you can also see the use of a lambda function to do the same, which was previously not possible with jUnit.

Conclusion

We hope that this post gave you an insight into JHipster and some of the concepts behind building a Spring Boot application. Don’t stop here, the repository contains a lot more than you can explore and use to evolve your application.

Quod AI is code search and navigation on steroids. We turn git repositories into documentation that developers actually use. Do follow us on Twitter @quod_ai for updates on our product and DEVs community content. Check our app at: beta.quod.ai.

How to structure your Flask apps using cookiecutter

Quod AI — Wed, 21 Apr 2021 01:18:20 +0000

Today’s article is all about cookiecutter. If you are a Python fanatic, you might’ve already heard of cookiecutter and possibly even have used it. It is a command-line tool that allows you to create boilerplate application code with a few simple steps.

This article was originally posted at: https://www.quod.ai/post/how-to-structure-your-flask-apps-using-cookiecutter

We will see how we can use cookiecutter to create a demo flask project and go through some of the important concepts present in the cookiecutter flask project. The topics we will cover today are listed below.

● Installing cookiecutter and setting up the project

● Flask-SQLAlchemy with a basic User model

● Easy database migrations with Flask-Migrate

● pytest and Factory-Boy for testing

● Configuration using environment variables

Installing cookiecutter and setting up the project

Installing cookiecutter is the easiest thing that you can do. Just run over to your command line and use the following command.

pip install cookiecutter

This will install cookiecutter in your system. Today, we are going to take a look at a sample flask-restful project. For importing this to your system, you can use the following command from the command line:

cookiecutter https://github.com/QuodAI/tutorial-cookiecutter-flask-restful.git

This will set up the basic project in your system. The folder will be stored under the path:

/users/your_user/.cookiecutters

Now, run the following command to install all the required dependencies.

pip install -r requirements.txt

There you have it, your basic flask-restful project is set up and ready to be used. Now, we will go through some of the important concepts that are detailed within that project. Below we have the file structure of the cookiecutter project. The ones that have been highlighted are the main directories that we will be looking at, but some of the others would also be linked internally.

Flask-SQLAlchemy with a basic User model

The flask-sqlalchemy library adds sqlalchemy support for your flask application. SQLAlchemy is a very popular ORM (Object Relational Mapper) that allows you to integrate the SQL capabilities into your application.

Below, we have a very simple User model that is created using Flask-SQLAlchemy.

from sqlalchemy.ext.hybrid import hybrid_property
from tutorial-cookiecutter-restful.extensions import db, pwd_context
class User(db.Model):
    """Basic user model"""
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(80), unique=True, nullable=False)
    _password = db.Column("password", db.String(255), nullable=False)
    active = db.Column(db.Boolean, default=True)
    @hybrid_property
    def password(self):
        return self._password
    @password.setter
    def password(self, value):
        self._password = pwd_context.hash(value)
    def __repr__(self):
        return "" % self.username

View user.py in context at Quod AI

Line 1-2: We import the hybrid-property from SQLAlchemy and the db and pwd_context from our extensions. The hybrid property depicts that a particular value would have different behaviors based on the context.

Line 3: This is a class we are going to create and we pass the db.Model base class to it. This base class instance is created when we initialize SQLAlchemy.

Line 5-9: These lines are used to declare the columns and their properties. We have 5 columns in the table, namely id, username, email, password, and active. The db.Column class is used to denote a column and the other classes denote datatypes. The unique property denotes that it will be a unique value and the nullable property denotes that it cannot be set to null or not depending on the boolean.

Line 10-17: We have a getter for the password that returns the password and we also have a setter that takes in the value and generates a hashed version of it using pwd_context import from extensions. This uses an SHA-256 to generate a hashed value. The last method is a general method that is used to represent the value of the particular type, in our case a user, with a simple string.

Easy database migrations with Flask-Migrate

Flask-Migrate is a flask extension that allows for easy db migrations through SQLAlchemy. To set up Flask-Migrate and start using it, we can follow the below code snippet.

def configure_extensions(app):
    """configure flask extensions"""
    db.init_app(app)
    jwt.init_app(app)
    migrate.init_app(app, db)

View migrate_config.py in context with Quod AI

Line 1-5: The above code snippet shows how we can configure db migrations with Flask-Migrate. We are assuming that the app is already created in this case and passed as an argument to this function. It will initialize an SQLAlchemy instance passing the app as an argument. This db instance will be used for the migrations by calling the init_app function present inside Flask-Migrate passing in the app instance and the db instance we created earlier.

PyTest and Factory-Boy for Testing

Factory-Boy and PyTest are used in conjunction for testing. Factory-Boy is basically a library that allows you to get an instance of a particular class. It contains a model attribute under a Meta class that describes for which class the factory is being created. Below is the creation of a factory for the User class.

import factory
from tutorial-cookiecutter-restful.models import User
class UserFactory(factory.Factory):
    username = factory.Sequence(lambda n: "user%d" % n)
    email = factory.Sequence(lambda n: "user%d@mail.com" % n)
    password = "mypwd"
    class Meta:
        model = User

View factories.py in context at Quod AI

Line 1-2: We import the factory library and the User model for which we are creating a factory.

Line 3-6: We create a class called UserFactory and pass in the factory.Factory subclass. Note that the username and email fields have the Sequence class from factory invoked. This is to create unique instances each time with different values of username and email. The password is set to ‘mypwd’.

Line 7-8: We then have a Meta class with the model attribute set to User which finalizes the creation of the UserFactory. This can now be used to get instances of User for testing.

Below, we have the test case for getting all users. To test a test case in Python, we can use the pytest library and use the pytest command from the command line.

def test_get_all_user(client, db, user_factory, admin_headers):
    users_url = url_for('api.users')
    users = user_factory.create_batch(30)
    db.session.add_all(users)
    db.session.commit()
    rep = client.get(users_url, headers=admin_headers)
    assert rep.status_code == 200
    results = rep.get_json()
    for user in users:
        assert any(u["id"] == user.id for u in results["results"])

View test_user.py in context with Quod AI

Line 1: This line declares the function with all the required arguments. Note that we are passing in the user_factory we created earlier.

Line 2-3: We then set the URL to get all the users. Then create a batch of 30 users using Factory-Boy.

Line 4-5: Next step is to all the users to the db session and commits all of the users that we created.

Line 6-10: We then call the get method on the URL created before passing in the admin headers to get a response. If it is 200, the test proceeds further. Next step, we loop through the response and match the user ids with the user ids present inside the users variable we created.

Configuration using environment variables

The project houses a file called .flaskenv that stores all the configuration information needed through environment variables that are accessed within the program.

var server = require("net").createServer();
var io = require("socket.io")(server);


var handleClient = function (socket) {
    socket.emit("message", {msg: "Hello World"});
};


io.on("connection", handleClient);


server.listen(4000);

Line 1: This sets up the environment for the flask app.

Line 2: This tells Flask how to load the application. The create_app factory is called that is present within the folder tutorial-cookiecutter-restful.app

Line 3: The SECRET_KEY variable is used to generate the JWT tokens

Line 4: The database URI for the SQLite in-memory database is present here.

Conclusion

That’s it for this one. We have gone through some of the concepts surrounding cookiecutter and how you can structure your next flask-restful app. Happy Coding!

How GraphQL works in the real world, a deep dive into Spectrum chat

Quod AI — Fri, 09 Apr 2021 08:40:53 +0000

If you're a web developer, there’s a high chance that you’ve already heard of GraphQL. It completely changed the landscape of how APIs are queried and is growing at a tremendous pace with wider adoption from the developer community.

This article was originally posted at https://www.quod.ai/post/how-graphql-works-in-the-real-world-a-deep-dive-into-spectrum-chat

The specification for GraphQL was written by the folks over at Facebook and they implemented a JavaScript version of it, but now we have several implementations in several different languages. It is a query language (similar to SQL) that gives clients the power to request exactly what they want from an API and GraphQL does the magic for you. You might be wondering what the magic is. Today, we will be looking at just that.

Objectives

In this post, we will get into all the basic concepts behind GraphQL and what makes it a great solution for better web applications.

1. Intro to GraphQL

2. GraphQL Concepts

a. Schema

b. Type

c. Queries, Resolvers, Mutations

3. GraphQL using Spectrum

a. Spectrum Introduction

b. Queries in Action

Intro to GraphQL

As we wrote in the introduction, GraphQL was developed at Facebook. The specification was initially used in house, but they open sourced it. Now, there are several implementations of the specification in various different languages. GraphQL is a query language that sits in front of your API and integrates well with almost anything that you have. It is strongly typed, and expects you to know exactly what you want and it will give back clean, and concise results. Unlike REST APIs, GraphQL only has one single endpoint that does all the work. For instance, if you wanted to delete a product in your application, a REST endpoint would look something like this: /api/product/{id} and the type of request would be DELETE. If you had to buy a new product, there would be another endpoint like /api/product/buy and the type of request would be POST.

In GraphQL, we have a single endpoint and almost always, it is a POST request, that contains exactly what is to be sent back from the server. The request body determines what the server will send back, unlike in REST, where the server decides what to send. Before we use some of the terms in GraphQL, let’s take a look at high level concepts in more detail.

GraphQL concepts

If you ever have to have a discussion over GraphQL, these 5 terms would be of utmost importance. The beautiful thing about GraphQL is that it is very simple to get started with, but is so complex that you can never stop learning it.

Schema

A GraphQL schema dictates how the resources will be structured and organized and how the client can query them. You can think of a GraphQL schema as a DB schema, but for APIs. These schemas let you know what resources are available for querying and the way you need to query them.

Type

We have two kinds of types in GraphQL. They are scalar types and object types. Scalar types are similar to primitive data types and every field in a type should eventually run down to this. For instance, there can be an Object type called User with a field that references another Object type called Student, and so on. But the field that is referenced last will and should have scalar types. The scalar types available in GraphQL are: String, Int, Float, Boolean, ID (which is another String, but ensures uniqueness). Let’s look at a few sample types in GraphQL.

  type Message @cacheControl(maxAge: 600) {
    id: ID!
    timestamp: Date!
    thread: Thread
    content: MessageContent!
    author: ThreadParticipant! @cost(complexity: 2)
    reactions: ReactionData @cost(complexity: 1)
    messageType: MessageTypes!
    parent: Message
    modifiedAt: Date
    bot: Boolean
    sender: User! @deprecated(reason: "Use Message.author field instead")

Line 1: This line has the keyword type to denote that it is a type followed by the name of the type, which is Message.

Line 2-12: These lines contain fields present inside the message type. You can see that we have a combination of scalar as well as Object types within the Message type. The fields id and bot are scalars. The rest of the fields are Object types. The ‘!’ mark next to the type tells that it is a non-nullable field.

Queries, mutations and resolvers

Queries - Queries in GraphQL determine what the client can access. In other words, it defines what your API can return.

Mutations - Mutations are queries that perform some changes to the data itself, therefore the name mutation.

Resolvers - In a traditional web application, we have controllers that route the request from the frontend to the server endpoint. Resolvers are basically like your controllers in a REST API. They are functions that return values for the different fields that are present in your type.

In just a bit, we will be looking at code that will showcase all these concepts in action.

GraphQL using Spectrum

Spectrum Introduction

To look at some GraphQL code, we will explore Spectrum chat. Spectrum is a community-based chat platform that gives additional functionalities like direct messaging, group messaging, ability to subscribe/unsubscribe to/from topics and specific chats. Spectrum is, however, moving over to GitHub Discussions and they don’t allow the creation of new communities anymore. By August 10, 2021, Spectrum will be completely archived and made read-only. This doesn’t stop us from going over some open-sourced code, does it?

Queries in Action

Now, let’s look at some of the queries in action which will incorporate most of the concepts that we covered before.

getMessageById - Query

export const getMessageByIdQuery = gql`
  query getMessageById($id: ID!) {
    message(id: $id) {
      ...messageInfo
    }
  }
  ${messageInfoFragment}

View getMessageByIdQuery.js in context at Quod AI

Line 1-2: The first two lines denote exporting a constant named getMessageByIdQuery and we assign it a GraphQL query that is preceded by the ‘query’ keyword. You can see that the gql template literal tag is used to write the GraphQL query. This is imported from the graphql-tag library. If you notice, we have an argument id of type ID that is passed in as input to the query.

Line 3-7: Inside the query, we have the messageInfo which is preceded by three dots (this is not the spread/rest operator of JS). These are used to refer fragments within the code. You might be wondering, what are fragments? It is basically a piece of code that can be shared between multiple queries/mutations. In this query, we return a message, when an id is passed as in input. The MessageInfo fragment contains all the other fields that are needed to be returned by the message which includes an id, timestamp, messageType, content and more.

banUserMutation – Mutation

type BanUserInput = {
  userId: string,
  reason: string,
};


export const banUserMutation = gql`
  mutation banUser($input: BanUserInput!) {
    banUser(input: $input)
  }
`;

View banUserMutation.js in context at Quod AI

Line 1-4: Mutations are also queries, but instead of just reading data, it updates data. This particular mutation is for banning a user. The first four lines denote the input type that is required to be given as input to the mutation. It has two fields, one is the userId and the next is the reason for banning the user.

Line 6-10: This shows the definition of the mutation itself, wherein we have the banUser mutation as the name which is preceded by the keyword ‘mutation’. It has a banUser field which takes in an input of the BanUserInput type we created above.

getCommunityById – Query

export const getMessageByIdQuery = gql`
  query getMessageById($id: ID!) {
    message(id: $id) {
      ...messageInfo
    }
  }
  ${messageInfoFragment}
`;

View getCommunityByIdQuery.js in context at Quod AI

Line 1-9: Spectrum is all about communities and this particular query is used to retrieve a community by its id. Upon receiving an input id, this query returns two fragments, which are the communityInfo fragment and the communityMetaData fragment. You can check these two files under the following directory (spectrum/ shared/ graphql/ fragments/ community/ communityMetaData.js) and see the contents that are being returned by these two fragments.

Conclusion

With that, we have covered some ground in GraphQL and also seen some concepts in action using Spectrum. You can check out the code in the GitHub repo here and see the app in action over here. Quod AI is the smartest way to search and navigate. We turn git repositories into documentation that developers actually use. Do follow us on twitter @quod_ai for updates on our product and DEVs community content. Check our app at: beta.quod.ai.

Quod AI #2: Automatically discover code impact + easy tutorials

Hervé Vũ Roussel — Wed, 07 Apr 2021 08:56:24 +0000

Automatically discover the impact of code

3 years ago, I hired a new backend developer. He was bright and eager. I felt validated when he pushed his first ticket to production on his 2nd day... which crashed our platform for 3.5 hours when it was released. He had forgotten to update one of the property keys in a related file.

Our newest feature Code browser would saved my team from unhappy customer emails and disappointed looks from the sales team. Code browser features code in full context with file tree, impactful commits and code owner automatically. But our fan favorite feature is the ability to show related code in one click.

Try code browser

An easier way to share code tutorials, guidelines, and more!

Stripe's API documentation is the best in the world. We took inspiration from it to build our new UX for collections. Share your code tutorials, guidelines, and more with your team. They'll enjoy our shiny new table of content.

PS: I built this collection ☝ in 5 minutes!

Try collections

Blog

We've been busy writing articles for the productive and smart engineer.

Check out our latest blog posts:

Our reading list

Four Ways of Writing Thoughtful Code to Think Less

How NodeBB uses Socket.IO to write a real-time message board

Quod AI — Mon, 05 Apr 2021 06:14:36 +0000

NodeBB is one amazing off-the-shelve community platform for your onboarding requirements. Be it a brand community or a board for flawless product support to your customers – this solution is built perfectly for everything you need for forum management.

such as:

Real-time interactions through private chats and message rooms;
Topics and replies for information-broadcasting;
Instant notifications to keep users engaged.

This article was originally posted at: https://www.quod.ai/post/how-nodebb-uses-socket-io-to-write-a-real-time-message-board

This GDPR-compliant next-gen community platform utilizes web sockets to enable interactive communication. As NodeBB has Node.js in its core, Socket.IO is a suitable pick for it. This library enables bi-directional communication in real-time and lets the browser & server communicate on the basis of events.

In this article, we will explain how NodeBB uses Socket.IO for its feature-rich real-time message board module in the community platform solution.

How NodeBB uses Socket.IO to write message boards?

Loading the real-time message board

SocketModules.chats.loadRoom = async function (socket, data) {
    if (!data || !data.roomId) {
        throw new Error('[[error:invalid-data]]');
    }


    return await Messaging.loadRoom(socket.uid, data);
};

View Modules.js in context at Quod AI

Line 1: The first step to using a message-board is, loading the chat rooms and rendering the list of previous chats. After initiation through Line 1, Socket.IO checks all the existing chats and the restrictions added for them. As per that, it loads the list of chats in the real-time message board. If there is no data or invalid data ID, an error message will be returned. Users will be able to click on each of the chats and open the chat window in NodeBB due to this.

Initiating a New Private Chat

SocketModules.chats.hasPrivateChat = async function (socket, uid) {
    if (socket.uid <= 0 || uid <= 0) {
        throw new Error('[[error:invalid-data]]');
    }
    return await Messaging.hasPrivateChat(socket.uid, uid);
};

View Modules.js in context at Quod AI

Line 1: When someone chooses a user to start a chat, NodeBB uses Socket.IO to check if the user already has a private chat for the current request. On clicking a link that could trigger a private chat, Socket.IO fetches and returns messaging data, e.g., the chat room icon/user display picture, old messages, user names (for chat rooms) with their names as disabled or enabled, option to send messages (or disabled chat), etc. If there exist previous messages, it loads the existing messages in the chat box. At this stage, the message board also accesses the restrictions and opens/disables the private chat option for the selected user, or the chat room of users.‍

‍

Chat room creation (New) and management

SocketModules.chats.newRoom = async function (socket, data) {
    if (!data) {
        throw new Error('[[error:invalid-data]]');
    }


    if (rateLimitExceeded(socket)) {
        throw new Error('[[error:too-many-messages]]');
    }


    const canChat = await privileges.global.can('chat', socket.uid);
    if (!canChat) {
        throw new Error('[[error:no-privileges]]');
    }
    await Messaging.canMessageUser(socket.uid, data.touid);
    return await Messaging.newRoom(socket.uid, [data.touid]);
};

View Modules.js in context at Quod AI

Line 1: The function in line 1 is responsible for the new chat room’s creation. When a new chat room is created, the admin must add a few details such as chat room name, chat room icon, and member list. If the admin has not added any member during the room creation or added itself only, it will see an error message and the chat room will not be created. Regarding the users with restrictions related to chat room/admin, there will be error messages, telling the reason why the selected user(s) is not added to the chat room.‍

Line 10: All the users will be assigned access rights and privileges, as set by the chat room admin. The same are being validated at line 10. Allowed users will be able to send messages in the room and perform operations as per their user role in the chat room. For example, administrators will be able to add/remove users from the chat room.

This all is taken care of by Socket.IO in NodeBB.

‍

SocketModules.chats.leave = async function (socket, roomid) {
    if (!socket.uid || !roomid) {
        throw new Error('[[error:invalid-data]]');
    }


    await Messaging.leaveRoom([socket.uid], roomid);
};

View Modules.js in context at Quod AI

Line 2: Hare, it is checked if the ‘leave chat room’ request is legit or not. At this point, the following aspects are validated through Socket.IO:

If the user has already left the chat room or if the user is not a part of the chat room;
If the user is the only administrator of the chat room;
If the invalid input is given to leave the chat room;

In these cases, the user will receive an error message and won’t be able to leave the chat room.

Deleting Messages

it('should error out if a message is deleted again', (done) => {
            socketModules.chats.delete({ uid: fooUid }, { messageId: mid, roomId: roomId }, (err) => {
                assert.strictEqual('[[error:chat-deleted-already]]', err.message);
                done();
            });
        });

View Messaging.js in context at Quod AI

Line 1: From this line, the code for message deletion starts in the messaging.js file. During message deletion for all, Socket.IO checks if the user is trying to delete the already deleted messages.

If so, an error message will be displayed.
If not, the visibility for selected messages, messages, or the whole chat will be checked. The Socket.IO module will make the messages hidden for everyone. So, no one will be able to view the messages.

While deleting the message(s) for self, the above will happen for the user making this request. In the NodeBB community, users and admins can restore the messages too.

*Blocking a User/Leaving a chat room

*

When a user blocks another person or leaves a chat room, the chat window in the real-time message board will be disabled from sending/receiving messages through Socket.IO in the NodeBB community. Line 732-762 has the code for this in the test/messaging.js file.

Socket Event Listeners

messages.addSocketListeners = function () {
        socket.removeListener('event:chats.edit', onChatMessageEdited);
        socket.on('event:chats.edit', onChatMessageEdited);


        socket.removeListener('event:chats.delete', onChatMessageDeleted);
        socket.on('event:chats.delete', onChatMessageDeleted);


        socket.removeListener('event:chats.restore', onChatMessageRestored);
        socket.on('event:chats.restore', onChatMessageRestored);
    };

View Messaging.js in context at Quod AI

Line 1: From this line, starts the function that updates the deletion, restoration and editing of messages in the real-time. Socket event listeners are used for this purpose.

Receiving Messages and Read/Unread Message Marker and Counter

socket.onAny((event, ...args) => {
        const payload = { data: [event].concat(args) };
        onMessage(socket, payload);
    });

View Index.js in context at Quod AI

Line 3: When the message arrives, it triggers the onMessage event in the real-time. With this the new message is added for the recipient to read and counters/message-status-markers are updated. Socket.IO uses a way to distinguish read and unread messages. When a message is read by recipient(s) on the message board, it is marked ‘read’. For unread messages, the unread-message counter is shown for each chat.‍

‍

Handling Restrictions and Invalid Inputs‍

For each user, there is a list of restrictions they have added. This may include the blocked users and parameters in settings.

When someone tries to initiate an action related to real-time messaging through NodeBB, Socket.IO is used for validating the inputs and confirming that there is no conflict in proceeding with the instruction.

For example: If a user is creating a Chat room and is trying to add someone who has blocked that user, there will be an error message. The selected person won’t be added to the chat room in this case.

Also, if a user is trying to add himself or herself to the chat room, the Socket.IO module returns an error.

Initiating or taking forward a private chat also requires that:

Both the users in conversation haven’t blocked each other;
Both users have active accounts with no messaging-related restrictions;

When do you need the Build-in Real-time Chat Functionality for your Community?

NodeBB message boards can be utilized for:

Discussions among teams regarding different projects;
To accept and address customers’ queries;
To let the community member discuss open-source projects;
To enable a seamless communication mode for the whole organization.

Is Socket.IO capable enough for your real-time message board?

Yes, Socket.IO is a reliable and secure choice for speedy communication. So, it is generally the best pick for real-time messaging and notifications. It works for all standard browsers, devices, and platforms. Overall, Socket.IO makes the best choice for the real-time message board in your NodeBB community.

The Final Words

NodeBB uses Socket.IO for event-based communications in the community. Be it notifications or message boards, the platform utilizes this technology to ensure instant and reliable communication. If you are thinking of using a ready-made message board with multiple other capabilities for your community, NodeBB can be considered. Check out source code on Quod AI repository: https://beta.quod.ai/github/NodeBB/NodeBB

‍

Quod AI is code search and navigation on steroids. We turn code into documentation that developers actually use. Do follow us on twitter @quod_ai for updates on our product and DEVs community content. Check our app at: beta.quod.ai‍

How to integrate Facebook Login API into your React app

Quod AI — Mon, 29 Mar 2021 03:52:44 +0000

Today, we're going to learn how to integrate Facebook login API into your React app. Why do we need that? According to data from oberlo, Facebook is one of the social media which has more than 2.8 billion active users every day. Where this number is spread across Facebook's main business, namely Facebook, WhatsApp, Instagram, and Messenger.

One of the ways to attract new users to register is that users can easily register. By utilizing a large number of active users on Facebook and integrating Facebook login API into our website, it will increase the probability of increasing users on our website by simply doing one tap on sign up that are already integrated with existing accounts on Facebook.

This article was originally posted at: https://www.quod.ai/post/how-to-integrate-facebook-login-api-into-your-react-app

Objectives

In this tutorial, we will show you how to:

Set up a Facebook App
Create React.js App
Install Package "react-facebook-login"
Adding Facebook login to our React app
Run React App to Facebook Login
Run our React App to login with Facebook

1. Set up a Facebook App

In this tutorial, we will use several frameworks, tools and modules as below.

Node.js. In this tutorial, we are using version 14.15.5. If you have not installed, you can download it from https://nodejs.org/en/download/‍
react-facebook-login package from npm (node package manager)
React.js. We use version 17.0.1. Before create React App you must install “npx“ package. If you have not installed, you can following this website https://www.npmjs.com/package/npx‍
Text Editor or IDE (We recommend using Visual Studio Code)
Terminal

After all the requirement are available, we need to register as a Facebook Developer Apps. To register, we need to log in using your existing Facebook account at https://developers.facebook.com/apps/ . If you haven't logged in to Facebook, you will be asked to enter your email or mobile number and password.

After that, you will redirect to https://developers.facebook.com and click “Get Started” if the first you register at Facebook Developer Apps.

You will be taken to the registration dashboard , and click “Continue”

Fill container of Primary Email with your email other than the Facebook account email that has been registered

You will get an email code from Facebook. Fill that container with the code you got earlier.

Choose as “Developer” and the press button “Complete and Registration”

We will be redirected to Facebook for the Developer dashboard

Press button “Create App” for create app in Facebook Developer.

Choose “Build Connected Experiences” and the press button “Continue”

Fill the App Display Name with what you want to name this app and your email that was previously registered. In this tutorial we use the name “React_Login”. After that, press the button “Create App”.

After checking the captcha dialog and click submit button, we will be redirected to the Facebook Application Dashboard.

2. Create React.js App

To create a React project we use the command line or CLI. Referring to the https://reactjs.org/docs/create-a-new-react-app.html#gatsby-focus-wrapper, we can create a React project with the command

npx create-react-app react-fb_login

This command works by downloading the latest React Js template from the repository. Or we can also download the React Js template and place it globally on our computer, so that every time we create a new React project we don't need to download it from the repository. The command line is as follows.

npm install -g create-react-app

create-react-app react-fb_login

Next, go to “ react-fb_login ” folder and open the project in your IDE or Text Editor. Below is the template structure for our React application

You can also see "package.json" in our React project folder to see what packages are installed by default and the versions of the packages.

{
  "name": "default_react",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.11.9",
    "@testing-library/react": "^11.2.5",
    "@testing-library/user-event": "^12.8.0",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "react-scripts": "4.0.3",
    "web-vitals": "^1.1.0"
  },

We can run our React project which is the default design template for create-react-app. To run, we only need to call this command in the terminal, where previously we have directed our terminal into our React project folder (react_fb_login).

npm start

By default the React app runs on localhost with port 3000.

3. Install the “ react-facebook-login ” library

In this tutorial we will be using the "react-facebook-login" package / modules / library which we will be installed in our React application project. To install this library we just need to use the command below in the terminal from our project directory.

npm install react-facebook-login

After the install is complete, we will see the “ react-facebook-login ” package has been added to the package.json file.

{
  "name": "default_react",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.11.9",
    "@testing-library/react": "^11.2.5",
    "@testing-library/user-event": "^12.8.0",
    "react": "^17.0.1",
    "react-bootstrap": "^1.5.1",
    "react-dom": "^17.0.1",
    "react-facebook-login": "^4.1.1",
    "react-scripts": "4.0.3",
    "web-vitals": "^1.1.0"
  },

We need to set up our React app project to running with HTTPS. This is because currently Facebook Login need to use HTTPS. To set this up, we need to replace the script of "start" in our packagae.json file with the start script below. The packagae.json file is in the directory "react-fb_login/package.json "

"start": "HTTPS=true react-scripts start",

  "scripts": {
    "start": "HTTPS=true react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

‍

4. Adding Facebook login to our React app

import React, { useState } from 'react';
import FacebookLogin from 'react-facebook-login';
import { Card, Image } from 'react-bootstrap';
import './App.css';


function App() {


  const [login, setLogin] = useState(false);
  const [data, setData] = useState({});
  const [picture, setPicture] = useState('');


  const responseFacebook = (response) => {
    console.log(response);
    setData(response);
    setPicture(response.picture.data.url);
    if (response.accessToken) {
      setLogin(true);
    } else {
      setLogin(false);
    }
  }


  return (



          {!login &&

          }
          {login &&

          }

        {login &&

            {data.name}

              {data.email}


        }


  );
}


export default App;

View App.js in context at Quod AI

Line 1-4: We are calling all the libraries needed to build our React app project, including calling the react-facebook-login, react-bootstrap and react libraries.

Line 26-39: We use the FacebookLogin component from the react-facebook-login library to login to Facebook. This library makes it easy for us to configure our React app to log into Facebook. In this component we need to add the appId (appId="") that we got from the dashboard at Facebook Developer.

Line 36-38: The FacebookLogin component is a button-like component. The FacebookLogin button will turn into an image component when we have successfully logged in.

Line 41-47: Our Facebook profile information will appear in the form of name and email if we have successfully logged in.

Line 12-21: This is an arrow function used to capture the response from the FacebookLogin component. In this response we will get an access token and also some profile data from our Facebook.

‍

5. How the FacebookLogin library works

To understand how the FacebookLogin library works, we need to take a look at the code we have installed in our project. Open the react-facebook-login folder in the directory "/ node_modules / react-facebook-login /". Then open the facebook.js file in the directory "/node_modules/react-facebook-login/dist/facebook.js". Before the FacebookLogin component is rendered, the attributes given to this component will be fetched and processed by FB SDK, especially in the appId we prepared earlier.

window.FB.init({
  version: 'v' + version,
  appId: appId,
  xfbml: xfbml,
  cookie: cookie
});

View facebook.js in context at Quod AI

      if (_this.props.isMobile && !disableMobileRedirect) {
        window.location.href = '//www.facebook.com/dialog/oauth?' + (0, _objectToParams2.default)(params);
      } else {
        window.FB.login(_this.checkLoginState, { scope: scope, auth_type: params.auth_type });
      }

View App.js in context at Quod AI

Line 126: The login function is executed when we click the login button. Then the response will be caught by the checkLoginState function.

‍

    }, _this.responseApi = function (authResponse) {
      window.FB.api('/me', { locale: _this.props.language, fields: _this.props.fields }, function (me) {
        _extends(me, authResponse);
        _this.props.callback(me);
      });
    }, _this.checkLoginState = function (response) {
      _this.setStateIfMounted({ isProcessing: false });
      if (response.authResponse) {
        _this.responseApi(response.authResponse);
      } else {
        if (_this.props.callback) {
          _this.props.callback({ status: response.status });
        }
      }

View App.js in context at Quod AI

Line 74: The authResponse we get will then be processed by the responseApi function.

Line 69-73 the responseApi data will be returned to the callback function which in our code was previously used to get the profile data response from our Facebook account.

‍

Next step, Open our Facebook Developer dashboard, click on "Settings" in the left navigation, then select "Basic". Continue scrolling down until you find the "+ Add Platform" button.

Then will be pop up select platform menu. Choose “Website”

fill in the " Site URL " container with " http://127.0.0.1:3000/auth/facebook/callback " and then press the "Save Changes" button.

6. Run our React App to login with Facebook

To run this react app, we use command line like below.

npm start

Go to https://localhost:3000 and you can see the browser displays a button to Login With Facebook as below.

‍

Click the Login with Facebook\ button then it will be a Facebook login dialog pop up.

Enter your email address or phone number and password. Then press button “Log in”. It will be a Facebook login dialog pop up again. Press button “Continue as "your_name"” and it will be back to the previous page with this data.

Congratulations, you have successfully integrated reactions with Facebook using the Facebook Login API. In our browser, it displays the profile picture and name of our Facebook account.

‍

You can see the full code on our GitHub repository: https://github.com/QuodAI/tutorial-react-facebook-api-login

Quod AI is code search and navigation on steroids. We turn code into documentation that developers actually use. Do follow us on Twitter @quod_ai for updates on our product and DEVs community content.

Check our app at: beta.quod.ai

How to write a chat app using Socket.io: A deep dive into Lounge Chat

Quod AI — Sun, 21 Mar 2021 13:37:11 +0000

Have you heard of IRCs before? IRC stands for Internet Relay Chat and is a protocol that allows users to install a client application on their systems or on the web browser and chat to other clients through a central server. Most IRC clients are used for communication on forums, but they facilitate one-to-one communication as well. Today, we will look at one of the most popular IRC clients, The Lounge Chat, which makes use of Socket.IO to handle bi-directional communication. Without further ado, let’s get going!

This article was originally posted at: https://quod.ai/post/how-to-write-a-chat-app-using-socket-io-a-deep-dive-into-lounge-chat

Objectives

In this deep-dive, we will mainly be looking at Socket.IO and how it enables bi-directional real-time communication in The Lounge Chat through its event mechanism. The article will be structure in the following way:

1. Socket.IO and Lounge Chat
a. Socket.IO - How does it work?
b. Connection between users

2. Socket.IO Events
a. Auth Event
b. Join Event
c. Mentions Event

Socket.IO and Lounge Chat

Socket.IO is a JavaScript library that enables applications to use WebSockets to provide real-time, low-latency, bi-directional communication. It is a very lightweight wrapper over the original WebSocket API, therefore, it allows you to stray away from conventional WebSocket code, and use a streamlined API. Socket.IO works through events that are emitted between the client and server. Both the client and server can emit events as well as listen to them and use a plethora of data structures as well as any number of arguments. We will look at the syntax in detail in the events section.

Lounge Chat is an entirely free and open-source chat application that uses the IRC protocol. The application uses Vue.js as the frontend library and has Socket.IO for all the communication between client and server. You can set the application using this guide, which is pretty comprehensive. Since this is not a complete guide on how to build it from scratch, we assume some proficiency of using these libraries.

Socket.IO - How does it work?

Like we said earlier, Socket.IO is a lightweight wrapper over the original WebSocket API. Websocket connections take place when the client sends a connection request to the server using an HTTP request. The server responds with a 101 code establishing a full duplex connection. When the client disconnects, the communication link is dropped. Websockets can be thought of as a very low level implementation of how you can establish two-way communication. But with Socket.IO, we have a library that has a lot of additional functionalities and an easy to use API to do this. Below is a small intro on how Socket.IO works. We have the server code first, followed by the client code.

var server = require("net").createServer();
var io = require("socket.io")(server);


var handleClient = function (socket) {
    socket.emit("message", {msg: "Hello World"});
};


io.on("connection", handleClient);


server.listen(4000);

We are going to start from the lines below and then explain the function.

Line 7: We are starting the server on port number 4000.

Line 5: We are creating a Socket.IO server instance which has been attached to the server during the imports itself. We are listening for the “connection” event, which is fired when the client visits the server page at port 4000. Once the connection is established we invoke the handleClient() method. This is used to fire a message using the socket.emit() method. Here, the event name is “message” and we pass a simple JSON with the message “Hello World”.

socket.on("message", function(sample) {
    console.log("Message:", sample.msg);
});

Line 1-3: This bit of code can be added to any of your client applications. We are listening for the event “message” from anyone who is connected through Socket.IO. Once you visit the server running on port 4000, the connection event will be invoked. This will fire the “message” event from the server sending the message to the client and since the client is listening in for the “message” event, it will log it to the console.

Socket.IO works entirely based on this logic, where there is a connection establishment at the onset and event based triggering of listeners and methods. The best part is that both parties can send and receive these.

Sending and receiving messages

The Lounge Chat has a public mode as well as a private mode. The public mode allows anyone to join a public chat room. The default connection details are all pre-populated, so you can get started right away. It runs on localhost:9000 when you first install it. At a very high level, this is how the chats between the clients and servers work in The Lounge Chat.

socket.emit("input", {target, text});

Line 1: This line of code emits the text entered by the user in the chat box and it has the event name as “input”. The value of the field target is the channel Id and the text field is the actual contents of what the user typed in. Channel is nothing but the name entered into the “Channels” field while connecting to The Lounge Chat. In public mode, the default channel is “#thelounge”.

‍

    socket.on("input", (data) => {
        if (_.isPlainObject(data)) {
            client.input(data);

Inside the src/server.js file, we have the listener for incoming messages from the client. This is shown in the gist above.

Line 1-3: The first line creates a Socket.IO listener for the “input” event and has a callback function with an argument “data”. This is then checked using the lodash function isPlainObject and this is set as the input data for the client.

Socket.IO Events

Below, we have some of the chat related events that are used between the client and the server in The Lounge Chat. There’s the “auth” event which is used for authentication, the “join” event for when the user wants to join particular channels and the “mentions” event, wherein the user mentions other users’ names in chat.

Auth Event

"use strict";
import socket from "../socket";
import storage from "../localStorage";
import {router, navigate} from "../router";
import store from "../store";
import location from "../location";
let lastServerHash = null;


socket.on("auth:success", function () {
    store.commit("currentUserVisibleError", "Loading messages…");
    updateLoadingMessage();
});


socket.on("auth:failed", function () {
    storage.remove("token");
    if (store.state.appLoaded) {
        return reloadPage("Authentication failed, reloading…");
    }
    showSignIn();
});


socket.on("auth:start", function (serverHash) {
    // If we reconnected and serverHash differs, that means the server restarted
    // And we will reload the page to grab the latest version
    if (lastServerHash && serverHash !== lastServerHash) {
        return reloadPage("Server restarted, reloading…");
    }
    lastServerHash = serverHash;
    const user = storage.get("user");
    const token = storage.get("token");
    const doFastAuth = user && token;


    // If we reconnect and no longer have a stored token, reload the page
    if (store.state.appLoaded && !doFastAuth) {
        return reloadPage("Authentication failed, reloading…");
    }
    // If we have user and token stored, perform auth without showing sign-in first
    if (doFastAuth) {
        store.commit("currentUserVisibleError", "Authorizing…");
        updateLoadingMessage();
        let lastMessage = -1;
        for (const network of store.state.networks) {
            for (const chan of network.channels) {
                if (chan.messages.length > 0) {
                    const id = chan.messages[chan.messages.length - 1].id;
                    if (lastMessage < id) {
                        lastMessage = id;
                    }
                }
            }
        }
        const openChannel =
            (store.state.activeChannel && store.state.activeChannel.channel.id) || null;
        socket.emit("auth:perform", {
            user,
            token,
            lastMessage,
            openChannel,
            hasConfig: store.state.serverConfiguration !== null,
        });
    } else {
        showSignIn();
    }
});

View auth.js in context at Quod AI

Line 1-7: These lines contain all the imports needed within the event. On the last line we have a variable called lastServerHash which we will be using further down.Line 9-12: This sets a socket event listener for the auth:success event which shows the message “Loading messages” followed by the invocation of the updateLoadingMessages() method.Line 14-20: These lines set a socket event listener for the auth:failure event. Firstly, it removes the token field from the local storage. This will unauthorize any existing users. If the app’s state is currently loaded, then we will reload the page stating that authentication has failed. Otherwise, we proceed to showing the sign in page for the user to login again.

Line 22-64: This chunk of code contains the main logic for authentication. It sets up a socket event listener for the auth:start event with a callback function. When the serverHash is received from the server upon starting this event, it is checked with the currently available server hash. If they are not equal, we need to reload the page to get the latest server hash.

If it is the first time being executed, the server hash is stored in the lastServerHash variable. Then, we get the user and token fields from the local storage. If both of them do not exist, we directly go for the sign in page that is shown from lines 61-63. Otherwise, we set a flag known as doFastAuth to true.

If this flag is true, it means that the local storage has a user’s information already and we can log them in directly. We then set the currentUserVisibleError field in the state to “Authorizing” and invoke the updateLoadingMessage() method. This message simply displays the message that is present in the currentUserVisibleError field in the state.

The next few lines are used to check for the existing networks in the store and then pick out the channel id and the last message from the particular channel. We then create a constant openChannel to store the channel using the existing channel id. Lastly, we emit an event auth:perform passing in the user, token, last message, the open channel and whether the state has config information or not.

Join Event

"use strict";
import socket from "../socket";
import store from "../store";
import {switchToChannel} from "../router";


socket.on("join", function (data) {
    store.getters.initChannel(data.chan);
    const network = store.getters.findNetwork(data.network);
    if (!network) {
        return;
    }
    network.channels.splice(data.index || -1, 0, data.chan);
    // Queries do not automatically focus, unless the user did a whois
    if (data.chan.type === "query" && !data.shouldOpen) {
        return;
    }
    switchToChannel(store.getters.findChannel(data.chan.id).channel);
});

View join.js in context at Quod AI

Line 1-4: We import the Vuex store that holds the entire application state. On the fourth line, we import the switchToChannel(channel) function from the router.js file.

Line 6-12: We use the socket.on() method to listen for join events and execute the callback that follows. We initialize a channel on the Vuex store using the data that is received. We then check for existing networks on the store using the data.network field to see if they match. If not, we return. Otherwise, we pick out the first network element in the array using the splice function.

Line 14-18: We then check if the channel is of type query and if the data should be opened. If not, then again, we return. Otherwise, we proceed to switch to that channel using the switchToChannel function that we imported from the router. This will load the RoutedChat Vue component.

Mentions Event

This is the event that is used when a client mentions other usernames on his chat. This event also a client side event that listens for events from the server as well as a server side event that sends events. The mentions are stored into the Vuex store in an array called “mentions”.

‍‍

socket.on("mentions:list", function (data) {
    store.commit("mentions", data);

Line 1-2: On the client side we create a socket event listener for any events that come with the name “mentions”. It has a callback function that gets executed which stores the list of mentions in the Vuex store. Like with any store, any change in the data, will lead to updation of all the components that use that data.

‍

    socket.on("mentions:get", () => {
        socket.emit("mentions:list", client.mentions);

Line 1-2: The server side has a socket event listener for “mentions:get” event which is emitted from the Vue component. This event listener has a callback that triggers the “mentions:list” event on the client updating the store of the client with the list of mentions.

Want to learn and contribute to Lounge Chat? Check out Quod AI’s real time documentation, powered by AI at https://beta.quod.ai/github/thelounge/thelounge.

Quod AI #1: Tackle remote onboarding + Ruby support 💎

Hervé Vũ Roussel — Fri, 19 Mar 2021 12:05:31 +0000

This is a newsletter round-up for Quod AI, the smartest way to search & navigate code. Quod AI turn git repositories into real-time documentation using AI.

Tackle remote onboarding with related search

In our latest blog post The ultimate README for remote onboarding, we argue that one of the goal of a README is to resurface the known unknowns (what a new developer knows he doesn't know).

Our latest feature Did you mean? will save developers from Slack interruptions and long Zoom calls! Did you mean? search suggestions takes the guess work out of code search ... it resurfaces the know unknowns automatically for new developers. With Quod AI, it doesn't matter if you called your function resetPassword, recoverPassword or lostPassword. Quod AI will find it.

Did you mean also works with :

Typos like pazzword
Semantic suggestions (example: encryption → password)

Try related search

Ruby support

We've released beta support for Ruby. So if want to easily find rails migration files, controllers and more.

Check out a sample Ruby repo

Blog

We've been busy writing away helpful engineering articles for big developers teams moving fast.

Check out our latest blog posts:

The ultimate README for remote onboarding
Firebase, Twitter login API and Google login API on our blog.

Our reading list

How to keep developer documentation up to date in a CI/CD world

Quod AI — Wed, 17 Mar 2021 07:29:06 +0000

75.4% of new software developers say that bad documentation is their #1 blocker at work. During the pandemic and remote work, software developer teams have reported 3x slowdown in collaboration due to lack of documentation and challenges in collaboration. So what’s going on? Is it so hard to write good and reliable documentation? Well, yes it is.

And there are 2 main reasons to that:

Writing for other developers is hard.
Updating documentation when code changes daily is a lot of work.

This article was originally posted at: https://quod.ai/post/how-to-keep-developer-documentation-up-to-date-in-a-ci-cd-world

What’s good documentation anyway?

To understand what makes documentation good, we must first talk about the goal of documentation. Why do we need documentation in the first place?

Good documentation answers questions from other developers

In order to evolve an existing codebase, a developer should understand the existing code. As developers, we’re constantly asking questions about our codebase to better understand and evolve it.

In a research case study, Google collected questions that their own software engineers asked when coding. They categorized all of those questions into 5 categories:

How (example code): How do I use X API? How do I implement feature Y?
What (reading specific code): What does this script do? What’s the name of the enumeration?
Where (code localization): Where is the code to do X? Where do we configure environment variables for Y?
Why (determine impact): Why did my change not work?
Who and when (metadata): Who edited this code and when? Who can help review this code?

In normal times, working at the office, you could just tap on your co-workers shoulders to get your answer (even though he may not like being interrupted). Now, with Slack ping pongs and Zoom overload, getting answers is a lot more work.

Obviously, it’s not easy to communicate online. But for developers, discussions require a lot of technical context and complex technical situations. IRL whiteboards are super helpful… However, digital whiteboards… not so much.

So how can we collaborate productively on code without face to face or whiteboards?

The attributes of good documentation

In the context of information systems, documentation is organized information. And when it comes to information, there are 11 criterias that define how good it is. We’re going to go through all those criterias but essentially, documentation should:

Be easy to find.
Be easy to read/write and update.
Be up to date and simple.
Offer the whole context.

Usability

The criterias for usability of documentation relate to how easy it is to read and write (and update) documentation.

Relevant: documentation should show what’s important to its reader. For devs, documentation should help make technical decisions.
Simple: documentation should be easy to read and not go into details that are not needed.
Economical: documentation should be easy to write and update.
Flexible: documentation should be consumable by different people in your team with different goals. For example a QA could look up the password reset feature from a BDD perspective, while Frontend and Backend can look up its implementation.

Delivery

The criterias for delivery have to do with the how and when. How the documentation is read and found.

Accessible: documentation should be available when you need it, in the format you need it. For example: in the IDE as I call a function; in Github when I search for code; or in Slack when I ask a question to my team.
Timely: documentation should show up when we need it. Not a week later when the PR is ready to be reviewed.

Quality

Quality of documentation reflects how good the decisions are, after documentation is read. A developer could make bad decisions if the documentation is out of date, incorrect or lacks important context (and he is unaware of those issues).

Accurate: documentation shouldn’t have any errors. Duh. But easier said than done.
Complete: documentation should explain code impact and full context. For example, imagine microservice A saves users in the users table and microservice B also writes to the same users table. If the documentation for A fails to mention B, then it wouldn’t be complete.
Reliable: documentation should rely on data and facts rather than opinions or mis-collected data.

Practical tips to keep documentation up to date in a CI/CD world

I once heard an enterprise software architect say at a public talk “Don’t bother updating documentation. By the time you’re done the code will have changed.”

Today, we are expected to release faster than ever: weekly, daily … and sometimes even hourly. Documentation is hard to maintain. However, we can make our job easier by following the principles of good documentation:

Be easy to find.
Be easy to read/write and update.
Be up to date and simple.
Offer the whole context.

Avoid writing code comments

A few years ago, my CEO asked me if our departing software engineer had documented his code with comments. I answered: “I hope not”. He laughed… but he didn’t realize I wasn’t joking.

A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.

- Uncle Bob

We sometimes tend to write comments to explain the behavior in our code instead of writing good code. We expect code comments to explain the expected behavior of the app. For example, a developer on your team may ask: “When does the user have access to premium features?”

Bad:

// Checks whether the user has access to premium features  
if (user.subscriptionPlan == 'premium'
   && user.billing.lastPaid 30 
   || user.daysLeftInTrial < 30)

Instead try:

if (user.hasPremiumFeatures()) {

Write code that’s self documenting. Robert C. Martin (aka Uncle Bob) has dedicated a whole chapter about comments in his book Clean Code. Check out Chapter 4. He has fantastic examples of good and bad comments.

Essentially, there are 3 types of code comments:

Redundant/noisy: just remove it.
Explanatory/summary: refactor the code.
Useful: explains the why - keep it.

Keep your documentation light… or just delete it

Have you ever read documentation that you knew was out of date? But you knew some parts were correct? Stale documentation can be as useless as no documentation because you don’t know which parts you can rely on. Or worse, you could rely on it thinking it’s up to date when it isn’t.

So before you start writing documentation, ask yourself:

Who’s going to read it? What questions will they be asking?
How often will I need to update it?

Make documentation easy to find

One of the reasons documentation gets stale is because it doesn’t get used often. It doesn’t get used, because it’s hard to search (*cough cough* Confluence).

Organize information so that it’s easy to find when others need it. Here are some practical tips:

Add README.md in sub folders of your repos to explain specific modules or concepts.
Link your tickets/issues in your documentation. Use hashtags and keywords to make it easy to search.
Move important information from your Slack to your README.
Organize your documentation into folders that are consistent and logical:
- For a standard README table of content, we recommend our ultimate README as a way to organize your processes.
- Use a nomenclature that’s easy to follow and think about. For example: README, LICENSE, etc.
- Organize your Confluence documentation into folders that reflect your features (example: user, billing, authentication, etc.). Use the same folder hierarchy consistent with how your code is organized.

Keep documentation close to code

One of the biggest reasons for obsolete documentation is that it’s far from source code. As discussed above, documentation should be easy to write and update.

Real code examples

The most searched documentation at Google is real code examples. For example: How do I use the billing API? Is there example code that does this?

You could write a paragraph about the endpoint URL and each of its parameters, the HTTP verbs, expected parameters… Or, you could just write an example usage of your API as part of a demo. Or better yet...

Write tests

Tests are a great way to document the expectation of your users. For example: “When does a user get locked out of his account?”

describe("User login", function() {  
  it("should lock out", function() {  
    login(“jdoe", "wrongpassword");  
    login(“jdoe", "wrongpassword");  
    login(“jdoe", "wrongpassword");  
    expect(statusMessage).toBe("You’ve been locked out of your account");  
  });  
});

Running your tests frequently (or using CI/CD) will force you to update your tests as documentation when the behavior of the app changes.

Code tutorials with git message and merge commits

Another way to document is to link your git messages, with your issue tracker and pull requests.

This can help answer questions like: How do I add a new database entity into our app? How should I name the API routes? Which files do I need to edit?

Source: add Note API

If someone has implemented a similar feature before, one great starting point is to get inspired from that commit. It’s an example implementation to build on.

Automate with tools and scripts

Turn documentation (processes, rules) into apps and scripts. Automation removes ambiguity and sets up (very) clear step by step instructions.

For example, instead of writing in prose “how to export users from the database in CSV” or “how to build and deploy the app”, why not write a script or a program to do it? Very much like testing, automation (if used frequently) forces you to update your scripts when behavior of the app or process changes.

Writing documentation can be a great way to support developers on your team. However, documentation is a time investment by the entire team. Your team needs to write, update and organize your documentation so that every developer on the team can benefit for effective and productive collaboration.

But ... What if you could spend less time documenting and organizing? Yet, still be able to answer questions from your fellow developers?

Use AI for easy and simple documentation

At Quod AI, our goal is to help developers find answers in the smartest way. Our platform turns source code repositories into documentation using Deep Learning and NLP.

There is only one step to get your documentation: submit your Git repo URL. That’s it. Our AI models take care of the rest.

We’ve submitted Winds, a gorgeous open source podcast and RSS feed app. Using Quod AI as auto generated documentation, we’re going to answer questions based on Google’s case study.

Example code of how use the articles API

How do I retrieve an article using the API? To answer this, let's search: retrieve article api test.

The first result is a test that shows a test to retrieve an article from the articles API.

Exploring and reading how articles work

What is an article? What can a user do with an article? To answer this, let’s search: article.

Not only did I learn about that an article can be pinned, I also learned from the suggested search that parsing article was an important feature of article

Sharing authentication code

How do you prevent unauthorized access? How do you reset a user password? How do we prevent unauthorized access?

In most applications, authentication is spread out around in many files due to its complexity. The Winds app is no different.

Sharing one snippet of code is not enough. That’s why Quod AI supports the concepts of collections. Collections are like a YouTube playlist of code snippets (without the music and copyright infringement).

I created the authentication collection in 5 minute. All I had to do was to find and collect snippets. Yet my documentation for authentication is fairly comprehensive because the code is automatically augmented with questions and tags.

Sometimes, code is not enough and you need to contextualize the code. In that situation, you can simply comment on the code. When sharing a collection, your team can read the code with the added context of your comment.

Sharing environment configuration

How do I configure the database for Winds? Which port is Redis using?

Winds has most of its environment configuration centralized into one file. But for ease of readability, I created a collection to show the dev, test and production configurations. Check out how to configure Winds’ external dependencies.

Trace code history for Podcast schema

“Podcast” is one of the most important concepts of Winds. Naturally, it’s one of the most viewed code files. Who’s the best person to review this code? Who can help me understand this code?

To answer this, we can go directly to models/podcast.js in Quod AI’s smart Code Browser. The automatic context tab gives us information about who are the key contributors to a specific snippet.

What were the last changes and which ones were impactful? Quod AI can answer this automatically as it resurfaces the latest commits with an impact score. A low impact commit is a commit that reformats the code and doesn’t change the behavior of the code for example.

That’s it! Documentation was and still is an essential part of software development. It’s just changing.

How to use Firestore: A deep dive into Todoist clone

Quod AI — Fri, 05 Mar 2021 09:02:21 +0000

This article was originally posted at: https://quod.ai/post/how-to-use-firestore-a-deep-dive-into-todoist-clone

Todoist is one of the most popular to-do-list applications in the market today. It came out way back in 2007 and currently has over 25 million users worldwide. Today, we will take a deep dive into Firebase Collections and will use the Todoist Clone repository as a reference point. Do note that this is not going to focus on the React side of things, and assumes you have a basic understanding of custom hooks, state management, etc. Here’s a brief of what we’re going to cover today.

Set up the Todoist clone in your system
Integrate Firebase with the application
Firestore Basics - Queries, documents, and collections
Why Firestore?

We’re not going to bore you further with our introduction. Let’s dive straight in.

Set up the Todoist clone in your system

Building a clone of an app such as Todoist from scratch would mean long hours of setup. We want to help you get the right stuff, the best possible way and for that, we already have a GitHub repository with the code required. You can download the source code from here:

https://github.com/karlhadwen/todoist

Clone this code to your system using HTTPS or SSH:

https://github.com/karlhadwen/todoist.git

git@github.com:karlhadwen/todoist.git

Once you clone the code, fire up your favorite code editor, ours is Visual Studio Code. Run the following command to download all the dependencies mentioned in the package.json file. You can use either yarn or npm to do this. Since we have npm that comes along with the node executable, we will be using that. After executing the command, you should see something similar to this.

To run a React application using npm, we can use the npm start command and the application will be set up at localhost:3000. You can also use the yarn start command to do the exact same thing. If you run the application right now, you will be greeted with an error message saying that ‘firebase’ is missing. To rectify this, we need to integrate Firebase with our application. But before we do that, let’s just take a look at the folder structure to understand what we’re dealing with.

├── __tests__ - Contains the test files

├── components - Houses all the components present within the application

├── constants - Constants, store some of the constants that we need within the application

├── context - Context is used to store the programming context

├── helpers - Helpers contain all of the helper functions that we will commonly use

├── hooks - This folder contains the custom React Hooks

├── App.js

├── App.scss

├── index.js

We have replaced App.css with App.scss. Do note that several files that come up when we create a basic React app have been removed. This includes App.test.js, index.css, serviceWorker.js, logo.svg, App.css, logo192.png, logo512.png, favicon.ico, manifest.json, and robots.txt. We will be focusing on the Firebase elements in this application, so let’s get started.

Integrate Firebase with the application

Integrating Firebase with our web application is extremely simple and straightforward. You can use your Google account to log in to Firebase. Then, head over to the Firebase Console and create a new project.

‍

This will open up a project creation wizard that has just two easy steps. The first step is to enter a project name.

‍

Once you enter the name and hit enter, you will be asked whether you want to use Google Analytics for your project. We can disable this for now.

‍

If you disable Google Analytics, you can directly create the project after step 2. Otherwise, you will have one more step to go through. Hit the ‘Create Project’ button now and you’re all set to go.

You will be greeted with this page that says the project has been successfully created. Once you hit Continue, you will be at the project dashboard. The next step is to add Firebase to your project.

‍

Click on the ‘</>’ button that indicates a web application. The following screen will give you all the configuration information that is required. For us, we just need to copy the 6 lines of code marked below.

‍

To integrate Firebase into our Todoist application, we will need to create a file named firebase.js inside the src folder. This config file is then imported into all the other components as and when Firebase is required in the application.

‍

import firebase from 'firebase/app';
import 'firebase/firestore';


const firebaseConfig = firebase.initializeApp({
    apiKey: "$YOUR_API_KEY_HERE",
    authDomain: "$YOUR_AUTH_DOMAIN",
    projectId: "$YOUR_PROJECT_ID",
    storageBucket: "$YOUR_STORAGE_BUCKET",
    messagingSenderId: "$YOUR_MESSAGE_SENDER_ID",
    appId: "$YOUR_APP_ID"
});


export { firebaseConfig as firebase };

Line 1-2: These are the two imports that we need. One is for Firebase and the next is for Firestore.

Line 4: We create a constant named firebaseConfig. Here we call the initialize app function on the firebase object that we imported earlier and pass in the configuration information.

Line 5-10: This is where you paste the 6 lines that we copied from the Firebase Console.

Line 13: We then import the firebaseConfig constant as firebase, so that we can use it everywhere in the project.

With that, we have successfully integrated Firebase within our application. To use Firestore in our application, we simply import this file and call the firestore() method. This will initialize an instance of Firestore with the configuration information that we provided. This instance will be used to query the db, retrieve data and make updates. We will look deeper into this aspect of Firestore in the next section and go through queries, documents, and collections.

Firestore Basics: Queries, documents, and collections

The great thing about the Todoist clone project is that even though it is feature-rich and looks complex, the underlying functionality can be easily implemented. Firestore is Firebase's NoSQL database that allows us to store information from our application like users, tasks, projects, etc. Other NoSQL databases in the market include MongoDB, CouchDB, Cassandra, Amazon DynamoDB and HBase.

Todoist Clone: Database Model

Here is a snapshot from the Firebase Console. For the todoist clone, we just have two entities in the database, projects and tasks. Tasks contain five fields: archived, data, projectId, task and userId. The archived field is used to denote whether a task has been completed or not. The data field is used to set the task date. The projectId is used to link the task to a project (it can be empty also, if there’s no project associated with the task). The task field, denotes the name of the task and the userId, denotes the user who created the task.

Projects contain three fields: name, projectId and userId. The name denotes the project name, projectId is the unique identifier that we generate using a helper function and the userId denotes the user who created the task.

Firestore simplifies a lot of the operations that are usually cumbersome with traditional databases. It allows the frontend client app to make calls directly to the DB (no backend servers needed) and that is what we’re going to capitalize on. Most traditional database clients require a middleware to process the calls from the frontend. Firestore/FBRD allows you to directly query the database from the frontend app without having to have a Node/Express, Spring, Flask backend. Since it is a NoSQL database, meaning there is no rigid structure. It stores data in the form of JSON. Simple data is stored as documents and a series of related documents are stored as collections. Collections will have multiple documents present within them, with some kind of unique id linking each document to a collection. In the screenshot above, we can see that we have two collections: projects and tasks. Each of them have multiple documents present inside them referencing the collection using an id field. Instead of having multilevel JSONs to represent complex relationships, Firestore represents them as single-level JSONs with a unique ID linking them to other documents.

Firestore is also highly optimized to have a lot of small documents in it and it allows us to listen to changes. This means that any change in the database is immediately reflected back to all the listeners. This makes it a perfect solution for a lot of real-time applications like reservation systems, online ticket booking, etc (where the chances of double booking are high). Imagine a scenario, where you’re trying to book a particular seat to a cinema on an online booking platform, and see that the seat turns gray because someone else books it right before you do. Firebase Realtime Database is another alternative that Firebase provides. But it is slightly more difficult to use and has less functionality when there is large amount of data to handle.Firebase Realtime Database (FBRD) stores data as a single large JSON file while Firestore provides better structure with bifurcation into documents and collections. Due to the indexing present in Firestore, querying will always be fast. This is because it depends only on the query result and not on the size of the dataset. Firestore also has a better billing method because it bills you based on the number of operations and not on the network bandwidth and storage.

Cloud Firestore - Basic Querying

Queries are used in Firestore to access the data and for all the create/read/update/delete operations. It is important to know how these are constructed to get a better understanding of how data comes in and goes out of the application.‍

import firebase from 'firebase/app';
firebase.firestore()
firebase.firestore().collection(‘subjects’)
firebase.firestore().collection(‘subjects’).doc('123')
firebase.firestore().collection(‘subjects’).where(‘subjectName’, '==', ‘Mathematics’)

Line 1: This is the import statement that is needed to use firebase within our app.

Line 2: This creates a Firestore instance with the config information that we have provided.

Line 3: This is how we reference a collection.

Line 4: This is how we reference a particular document in the collection.

Line 5: Last line shows how we can query a document that satisfies a particular condition.

The last line has three parts. ‘subjectName’, '==', ‘Mathematics’. This is how every query is constructed. It has the field which we are referring to, the relational operation (‘<’, ‘<=’, ‘>’, ‘>=’, ‘==’), and lastly the value to compare. We can also chain queries using multiple where() blocks but do note that we are not allowed to use range operators on different fields while chaining. The end product of this line of code is a ref and it doesn't actually execute the queries. Refs are references to documents or collections. They can be DocumentReference or a CollectionReference. To get the contents, we need to call the get() method at the end that returns a promise.

Cloud Firestore - Document/Query Snapshots

const subject = await firebase.firestore().collection(‘subjects’).doc('123').get();

Line 1: This line returns a promise, but we still need to resolve it to get the data. This is known as the DocumentSnapshot (in case of documents) or a CollectionSnapshot (in case of collections).

You might think that the const variable will now store the key-value pairs that are present in a particular document. But it actually returns a DocumentSnapshot. This object stores certain metadata of the document along with the data present itself. So, we need to access this by calling the data() method on the snapshot returned.‍

const snapshot = await firebase.firestore().collection(‘subjects’).doc('123').get();
const data = snapshot.data();

Line 1: We store the return value of the get() method into a constant called snapshot.

Line 2: We use the data() method from the snapshot to get the actual data.

In case we query for something that returns multiple documents, we don't get a DocumentSnapshot, but a QuerySnapshot. We need to access the docs property on the QuerySnapshot to get the array of documents and then use something like an arrow function to map it to a constant, calling the data() method on each document. Snapshots allow us to listen for database changes. For instance, if you see a reservation for a seat in a cinema hall, and if another person books it, you will see it turning to gray in real-time showing that it is unavailable.

Another advantage with Firestore is that documents are automatically indexed. This means that even if there’s an increase in the size of documents to be fetched the time taken to retrieve them doesn’t linearly increase.

Let’s take a look at another code snippet from the Todoist clone that explains how we can retrieve the tasks from the to-do list.

export const useProjects = () => {
  const [projects, setProjects] = useState([]);


  useEffect(() => {
    firebase
      .firestore()
      .collection('projects')
      .where('userId', '==', 'jlIFXIwyAL3tzHMtzRbw')
      .orderBy('projectId')
      .get()
      .then(snapshot => {
        const allProjects = snapshot.docs.map(project => ({
          ...project.data(),
          docId: project.id,
        }));


        if (JSON.stringify(allProjects) !== JSON.stringify(projects)) {
          setProjects(allProjects);
        }
      });
  }, [projects]);


  return { projects, setProjects };

View index.js in context at Quod AI

Line 1: This is a custom React Hook that we are using to get the list of the projects.

Line 2: This contains the project's state as well as the setProjects used to update the state if there’s a change. We use the useState() hook to make it a stateful component.

Line 4-10: This is where the actual magic happens. We use the useEffect() hook to allow our component to use lifecycle hooks in React, which was earlier only possible for class components. We then use a query to retrieve all the projects for the specific userId and order them by their project ids.

Line 11-23: As we said earlier, when we use the get() method, we get a QuerySnapshot, and we iterate through all of them using an arrow operator and store the data into the constant allProjects. It is interesting to note that we compare it with the existing list of projects and change state only if there’s any difference between the two. Finally, we return the array of projects and the setProjects method.

Cloud Firestore - Create/Update/Delete Operations

Similar to the query we saw in the example above, we can also create, update or delete in the exact same way. All of these return promises, and we can use async/await along with these. We will look at code snippets where we can create a new project, delete a project as well as update a task.

  const addProject = () =>
    projectName &&
    firebase
      .firestore()
      .collection('projects')
      .add({
        projectId,
        name: projectName,
        userId: 'jlIFXIwyAL3tzHMtzRbw',
      })
      .then(() => {
        setProjects([...projects]);
        setProjectName('');
        setShow(false);
      });

View AddProject.js in context at Quod AI

Line 1-15: This is the snippet used to add a new project. We reference the collection using, firebase().firestore().collection(‘projects’) and then call the add() method to add a project to the collection. The projectId is generated using a function and is a random set of characters and numbers. You can take a look at src/helpers/index.js for the function (generatePushId). The project name is what we type into the text box and the userId is a predefined string to identify the user. You can use any predefined string here, but make sure to use the same string throughout.‍

const archiveTask = () => {
    firebase.firestore().collection('tasks').doc(id).update({
      archived: true,
    });
  };

View Checkbox.js in context at Quod AI

Line 1-5: This is a very short snippet to showcase the update functionality of Firestore. Similar to the create operation, we reference the collection using firebase().firestore().collection(), passing in the collection name. But since we need to update a specific document, we need to pass the document id, which is passed as an argument to the doc() method. To update, we simply call the update() method on this document, and set the property that we want to the new value. In this case, the archived field is set to true. On setting archived to true, the item on the todo list is removed indicating that it has been already completed.

  const deleteProject = (docId) => {
    firebase
      .firestore()
      .collection('projects')
      .doc(docId)
      .delete()
      .then(() => {
        setProjects([...projects]);
        setSelectedProject('INBOX');
      });
  };

View IndividualProject.js in context at Quod AI

Line 1-5: We delete a project by passing in the document ID associated with the project, each time we click on the delete button. This is then used along with the query to select the particular document to delete. Similar to the retrieval, we call the firebase object’s firestore() method, reference the collection, projects, then pass in the document ID to the doc() method.

Line 6-11: Then we call the delete() method which returns a promise and we resolve it by setting the projects array with the new one and set the selected project as ‘INBOX’, which will show the Inbox view to the user.

Checkout all the firebase functions in context in Quod AI’s firebase collection for todoist.

Why Firestore?

The main reason to use Firestore is the fact that anyone without previous experience with Firebase can get up and running in no time. The fact that we were able to integrate Firebase into our web application, hook up the database and start querying it in very little time is a testament to how easy it is to use. Also, Firebase has come a long way since its inception and is perfect for hobby projects as well as commercial applications. Their billing is very flexible and is a great entry point for your next big application.

Phew! That was a long one. But we really hope that you now have a better understanding of Firestore and how you can integrate it with your web application. We saw how easy it is to use Firestore to store, retrieve and perform operations on our application data. The fact that everything happens in real-time makes it all the more exciting!

Checkout todoist source code: https://github.com/karlhadwen/todoist

Want to easily and quickly onboard and contribute to todoist? Checkout todoist on Quod AI.

Quod AI is code search and navigation on steroids. We turn code into documentation that developers actually use. Check our app free at: beta.quod.ai

The ultimate README for effective remote onboarding

Quod AI — Fri, 26 Feb 2021 09:07:43 +0000

Getting someone new on a team is always exciting. Developer teams have shifted to Slack and Zoom and it has been quite challenging. We’ve seen collaboration slow down 3x during WFH. Yet, a solid README could increase developer's productivity by 1.7x. This could lead to informed questions by new teammates on Slack and Zoom and better pull requests.

This article was originally posted at: https://quod.ai/post/the-ultimate-readme-for-remote-onboarding

What’s onboarding? It’s the ultimate knowledge transfer. getting someone new from knowing nothing to pushing code in production.

The goal of this post is to establish a template for the ultimate README.

Sections of the README should be easy and helpful for both readers (new developers) and writers (more experienced developers):

Easy to write & update
A powerful orientation guide for new developers

How to onboard onto complex code

Onboarding onto large code is not about understanding a lot of code. It’s about understanding the structure, concepts and abstractions of the system.

There are basically 2 approaches to onboarding:

Top down: from a high level system down to specific code.
Bottom up: from specific code up to the layers of the system. We navigate from code to layers of abstractions.

Onboarding is about mapping what your new developer doesn't know (unknown unknowns).

When onboarding, you need both.

The top down approach is more about the big picture. This is helpful to avoid pitfalls and side effects of the system (what you don’t know you don’t know - unknowns unknowns). It won't help close tickets but is tedious to self teach.
The bottom up approach is more pragmatic. Give someone a ticket and starting point in the code and let your new developer navigate to the answer. The risk is that your new developer may not be aware of unknown unknowns… his code could have unintended consequences (like side effects).

A good README is about giving a top down approach and pointing your new developers to the starting point of the bottom up approach (specific code locations).

Your new developer is successful when he pushes his first code to production. The goal of a good onboarding guide is to help him to be effective in that process.

So how do we pave the path for your new developer's success?

What makes a good README?

So how do we set up your new developer for success?

A good README explains what’s already in place: the existing code, the processes and the team with the goal that your new developer can evolve it. Here are some of the high characteristics of a good README:

What should a README answer?

The ultimate README template

So here goes the template. It should be quick to write from scratch if you know your repo.

‍

The ultimate README for nodetube

One of the problems with nodetube’s README is that it is aimed towards users and not contributors.

Known unknowns about nodetube:

It’s a web app but I don’t know how the front end, API, DB architecture are organized
It can host videos but I don’t know how the hosting is managed

Unknowns unknowns: we hope to clarify by applying our README template

‍