Forem: venture

Edge, an OpenSource NextJS application with dynamic API for makers and developers.

venture — Sun, 31 May 2020 08:08:04 +0000

During the last months, we have been working on an OpenSource tool called Edge.

Edge offers a full-fledged Nextjs server capable of being deployed in minutes, adapting to your needs, only by changing some configuration options. It offers Dynamic API, dynamic dashboard, basic authentication, and authorization based in Roles, file upload, emails, and much more, all implemented.

Edge can be the foundation for your next MVP or web prototype.

Why Edge?

Edge serves the purpose of being able to prototype a new idea easily.

Some examples:

You need to launch a platform for a client with a small budget. And several "boring" things like user authentication, basic API endpoints, static pages, could be resolved for you. Later you can extend edge to adjust to your needs or use it as a stand-alone API.
You want to launch a social platform where users can post content: Recipes, Advertisements, Book Reviews, you name it. It is easy with Edge, for your first version. Later on, you maybe need some custom development to adapt it to your needs.
You want to launch your own blog, but you don't want to deploy another instance for your CMS. You have a built in dashboard in Edge.
You need an content type based API and a landing page for your product in a quick time

What are the features of Edge?

Content

Dynamic forms based on content-type definitions. Allowing users to create any kind of content. Just define them on a config file
Dynamic API with roles, based on content-type definitions. Easily configure your API to support all the content types your project needs.
Dynamic content-views to list all the content and be SEO friendly (with the content slug for the URL, and server-side rendering)
Content can be categorized by tags.
Web monetization built in for content

Users

Possibility to define new user roles or use the standard (ADMIN, USER, PUBLIC).
Administration dashboard to block or unblock users.
Login and register with social providers. Edge offers integration with Github, Google, and Facebook. It uses passport so it is easy to add many more.
Cool user profiles

Files

Content can contain files. Edge has integrated code to work with Google Cloud Platform but is easily extendable to different storage providers

Comments

Content can have comments. Comments are role-based and can create a conversation between users.

Administration

The administration role can access to some dashboards to control content and users.

Themes

Built-in CSS themes Light, Dark, Robot, Edge, Kawaii. Allowing users to change their theme preference.

React Components

We coded many components that you can find here: https://edge-next.now.sh/components.

Why we didn't use MaterialUI or another component library? We want full control of our developments. We want something we can touch, delete, break, adapt.

Other Features

PWA provided by next-pwa
Markdown static page rendering. Static content generation with markdown support
Markdown dynamic content. Support for markdown in content-types

How do I use Edge, now?

It is really easy, just clone our repository and follow the setup instructions.

Setup instructions:

run yarn
run yarn dev to start working

You will need to configure the different environment variables (take a look at the documentation ) for configuring all the features (Mongo, storage, social login, etc). But once you create all the keys you need, you will have your site up and running. That's how we deployed Edgechain just in a couple of hours of work!

Some Documentation

Creating new content types

To create a new content type you will need to edit the edge.config.js file and add as many content type definitions as you want.

const contentType = {
  // The name for this content type
  title: 'Blog Posts',

  // The URL for the API and client routes
  slug: 'blog-posts',

  // How slugs are going to be generated for new content. 
  // For example "a-new-blog-post-123132132"
  slugGeneration: ['title', 'createdAt'],

  // Sets of permissions for the API and client sides
  permissions: {
    // Who can read the content
    read: ['PUBLIC'],

    // Who can create content
    create: ['ADMIN', 'USER'],

    // Who can edit ANY content
    update: ['ADMIN'],

    // Who can delete ANY content
    delete: ['ADMIN'],

    // Who can perform all of the above
    admin: ['ADMIN']
  },

  // Publishing and SEO settings
  publishing: {

    // Allow content owners to mark the content as draft and avoid visibility
    draftMode: true,

    // Which field will be used for SEO and linking
    title: 'title'
  },

  monetization: {
    web: true // Enable web monetization for a content type
  },


  // A list of fields, see Edge next documentation for more information
  fields: [{
    // Required values
    name: 'title',
    type: 'text',
    label: 'Post title',

    // Optional values
    placeholder: 'Type your title',
    minlength: 10,
    maxlength: 200,
    required: true,
  }]
}
```

`

### Enabling or disabling comments on content types

Comments are disabled by default. If you want to enable them on a content type just add 
`

```javascript
const postContentType = {
  /* ... previous configuration ... */
  comments: {
    enabled: true
  }
}
```



Then you can fine-tune the permissions:


````javascript
const postContentType = {
  /* ... previous configuration ... */
  comments: {
    enabled: true,
    permissions: {
      read: ['PUBLIC'],
      create: ['ADMIN', 'USER'],
      update: ['ADMIN'],
      delete: ['ADMIN'],
      admin: ['ADMIN'],
    },
  }
}
```
{% endraw %}

Permissions like {% raw %}`update`{% endraw %} and {% raw %}`delete`{% endraw %} imply that the user will be able to edit ANY or delete ANY comment. Any logged user is able to edit or delete it's own comments or comment.

----

## Configuring environment variables


For that, create a file called {% raw %}`.env.local` and add the following code:



```
BASE_URL=http://localhost:3000
MONGODB_URI=MONGODB_URI=mongodb+srv://<username>:<password>@<url>
MONGODB_DATABASE=<database>
SENDGRID_KEY=XXX
FACEBOOK_ID=XX
FACEBOOK_SECRET=XX
GOOGLE_CLIENT_EMAIL=XX
GOOGLE_PRIVATE_KEY=XX
GOOGLE_PROJECTID=XX
GOOGLE_BUCKET_NAME=edge-next
GITHUB_ID=XX
GITHUB_SECRET=XX
GOOGLE_ID=XX
GOOGLE_SECRET
NEXT_PUBLIC_GA_TRACKING_ID=xx
```

`

As you can see here there are many third-party tools and services that are needed to run a full-fledged service. But do not worry, setting up these accounts is something easy and here there are some tips:

- [Register your Github application](https://developer.github.com/v3/guides/basics-of-authentication/)
- [Register your Google application](https://developers.google.com/identity/sign-in/web/sign-in)
- [Register your Facebook application](https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow/)
- [Get a sendgrid API key](https://www.youtube.com/watch?v=ShOQxpX7Dcw)
- [Create a Mongo Atlas account](https://docs.mongodb.com/guides/cloud/connectionstring/)
- [Create a Google cloud bucket](https://cloud.google.com/storage/docs/creating-buckets) & [Making files public in google bucket](https://cloud.google.com/storage/docs/access-control/making-data-public)
- [Get a Google Maps API key](https://developers.google.com/maps/documentation/javascript/get-api-key?hl=es-419)

-----

## How can I hack Edge?

Anyway...! You don't need to use all the services listed there. You can just use some of the features Edge offers. Think of Edge (at the moment) like Hackathon Starter on steroids. You can delete or adapt any of it's logic.

## Feedback and contributions

We are looking for people who can share HONEST feedback with us, makes us grow and give value back to the community. 


## API 

This is the API that Edge exposes as of version 1.0

### Auth
- `POST /api/auth/login`
  - `{ email: xxx@xxx.com, password: password}`
  - Logs in a user
- `GET /api/auth/logout`
  - Logout a user
- `GET /api/auth/reset-password?email=xxx@xxx.com`
  - Marks the user for reset password, sends an email with a token
- `POST /api/auth/reset-password`
  - `{email: xxx@xxx.com, password: NewPassword, token: token }`
  - Enables de new password for a user
- `GET /api/auth/verify?email=xxx@xxx.com&token=TOKEN`
  - Verifies a user email

### Users
- `GET /api/users`
  - Access limited to users with permission `user.list` or `user.admin`
- `GET /api/users/ID` | `GET /api/users/me` | `GET /api/users/@username`
  - Access limited to own user or users with permission `user.read` or `user.admin` (or own user)
- `POST /api/users`
  - Access limited to users with permission `user.create`. Default is public, to allow users to register.
- `PUT /api/users/ID`
  - Access limited to own user or users with permission `user.admin` and `user.update`
  - To update a user the different endpoint sufixes have to be added
  - `PUT /api/users/ID/profile`

  - `PUT /api/users/ID/email`

  - `PUT /api/users/ID/username`

  - `PUT /api/users/ID/picture`

  - `PUT /api/users/ID/password`

  - `PUT /api/users/ID/block`

- `DELETE /api/users/ID`
  - Access limited to own user or users with permission `user.admin` and `user.delete`. For the current user is also required to send a `password` query parameter.

### Content
- `GET /api/content/[TYPE]`
  - Access limited to users with permission `content.TYPE.read` or `content.TYPE.admin`
- `GET /api/content/[TYPE]/[CONTENT_SLUG]` | `GET /api/content/[TYPE]/[CONTENT_ID]?field=id`
  - Access limited to own user or users with permission `content.TYPE.read` or `content.TYPE.admin`
- `POST /api/content/[TYPE]`
  - Access limited to `content.TYPE.admin`, or `content.TYPE.create`
- `PUT /api/content/[TYPE]/[CONTENT_SLUG]` | `POST /api/content/[TYPE]/[CONTENT_SLUG]` |  `PUT /api/content/[TYPE]/[CONTENT_ID]?field=id` |  `POST /api/content/[TYPE]/[CONTENT_ID]?field=id`
  - Access limited to own user or users with permission `content.TYPE.admin` or `content.TYPE.update`
- `DELETE /api/content/[TYPE]/[CONTENT_SLUG]` | `GET /api/content/[TYPE]/[CONTENT_ID]?field=id`
  - Access limited to own user or users with permission `content.TYPE.admin` or `content.TYPE.delete`

### Comments

- `GET /api/comments?contentType=CONTENT_TYPE`
  - Access limited to users with permission `content.TYPE.comments.read` or `content.TYPE.comments.admin`. If no CONTENT_TYPE is specified, it will list all the comments that the current user has access to.
  - Other filters available are `contentId`, `author` (user id), `conversationId` (can be set to the string `'false'` to ellicit empty conversationIds)

- `POST /api/comments?contentId=CONTENT_ID&contentType=CONTENT_TYPE`
  - Access limited to `content.TYPE.comments.admin`, or `content.TYPE.comments.create`

- `GET /api/comments/[COMMENT_SLUG]` or `GET /api/comments/[COMMENT_ID]?field=id` 
  - Access limited to own user or users with permission `content.TYPE.comments.read` or `content.TYPE.comments.admin`
- `DELETE /api/comments/[COMMENT_SLUG]` or `DELETE /api/comments/[COMMENT_ID]?field=id` 
  - Access limited to own user or users with permission `content.TYPE.comments.admin` or `content.TYPE.comments.delete`

### Activity

- `GET /api/activity/[USER_ID]`
  - Returns a list of activity for the user, access limited to own user or users with permission `activity.read` or `activity.admin`





I hope some of you get to use Edge and can give us some feedback or collaborate on the open source initiative.

Thanks !

Creating a canvas animation, understanding the basics of animation.

venture — Fri, 22 May 2020 15:22:05 +0000

For this example i am going to use the platform glitch.com. It is a free online code editor and hosting platform, which will allow me to show you a full working example that you can edit:

Everything starts with a blank canvas:

<canvas id="canvas"></canvas>

Note: During this tutorial, I don’t want to dive into all the explanations on how canvas work, if you want to understand canvas more in-depth you should follow my leanpub page: https://leanpub.com/deceroacanvas

For now let’s just explain a basic concept about rendering.
To paint things into a canvas we need to use it’s JavaScript API. For that will get the context and interact with it:

const canvas = document.getElementById('canvas');
const context = canvas.getContext('2d');

Imagine we want to pain this rotated square:

For doing that we need to:

Translate the origin of coordinates of the context with context.translate(x, y) followed by a context.rotate(radians)
Draw a square with context.rect(x, y, width, height)
Fill the square with color with context.fillStyle = 'green' and context.fill()
Stroke the square with context.stroke()
Paint the text indicating the angle of rotation with context.text(TEXT, x,y)

const canvas = document.getElementById('canvas');
const context = canvas.getContext('2d');

function drawSquare(x, y, size, angleOfRotation) {
  // Translate in the context the origin of coordinates
  context.translate(x, y);

  // Rotate the context 
  const radians = Utils.degreeToRadian(angleOfRotation)
  context.rotate(radians);

  // Draw a square
  context.beginPath();
  context.rect(-Math.round(size/2), -Math.round(size/2), size, size);
  context.stroke();
  context.fillStyle = 'green';
  context.fill();

  // Paint a text indicating the degree of rotation 
  // (at 0, 0 because we have translate the coordinates origin)
  context.fillStyle = 'black';
  context.fillText(angleOfRotation, 0 , 0 );
}

function maximizeCanvas() {
  canvas.width = window.innerWidth
  canvas.height = window.innerHeight
}


function render() {
  maximizeCanvas()
  drawSquare(100, 100, 100 ,10)
}

render();

You can edit this code on glitch https://glitch.com/~etereo-canvas-animation-0

We have used a function to translate degrees to radians:

Utils.degreeToRadian = function(degree) {
  return degree / (180 / Math.PI);
}

If we want to have many random figures we could expand our previous example with the next code:

const canvas = document.getElementById('canvas');
const context = canvas.getContext('2d');

const totalFigures = 50

const figures = []

function drawSquare(x, y, size, angleOfRotation) {
  // Store the painting state in a stack
  context.save()

  // We get the radians from a degree
  const radians = Utils.degreeToRadian(angleOfRotation);

  // Translate in the context the origin of coordinates
  context.translate(x, y);

  // Rotate the context 
  context.rotate(radians);

  // Draw a square
  context.beginPath();
  context.rect(-Math.round(size/2), -Math.round(size/2), size, size);
  context.stroke();
  context.fillStyle = Utils.randomColor();
  context.fill();

  // Paint a text indicating the degree of rotation (at 0, 0 because we have translate the coordinates origin)
  context.fillStyle = 'black';
  context.fillText(angleOfRotation, 0 , 0 );

  // Restore the state of the context from the stack
  context.restore()
}

function createFigures() {
  for(var i = 0; i<totalFigures; i++) {
    figures.push({
      x: Utils.randomInteger(0, 560),
      y: Utils.randomInteger(0, 560),
      size: Utils.randomInteger(20, 100),
      angle: Utils.randomInteger(0, 360)
    })
  }
}

function maximizeCanvas() {
  canvas.width = window.innerWidth
  canvas.height = window.innerHeight
}


function render() {
  maximizeCanvas()
  createFigures()

  figures.map(square => {
    drawSquare(square.x, square.y, square.size, square.angle)
  })
}

render();

In this case we introduced 2 new concepts.

context.save() allows to preserve the state of the context before the translation and the rotation. If we don’t use context.save any consecutive rotations and translations will apply over the previous ones, producing an undesired behavior (or not, depending on the case you are trying to reproduce).
context.restore() restores the canvas to the previous state on the drawing stack.

This is what we have now:

This is kind of cool but we are not animating anything, this is just a render.

If we want to create the movement we need to change the positions or angle of rotation the figures have. We also need to invoke the render method many times.

Just like in an old movie, animation still happens because frames change over time:

To do so we need different elements:

A loop that will be executed at least 30 times per second ( frames per second), ideally at 60fps.
We will nead to “clear” or delete the previous canvas before we paint the new state.
The figures will need to update their positions based on how much time has passed since the last frame. We call this difference of time since last frame dt

These 3 elements form the basics of animation or any animation engine.

Game engines have much more utilities but they should have this kind of concept embedded somewhere.

Let’s code!

The loop:

For the loop we are going to use requestAnimationFrame . This method will give us a callback that will be executed after the browser finished rendering all the things.
Every time we call the loop we are going to calculate the difference of time dt since the last execution, and we will use this time variable to calculate how much the figures should move

function loop() {
  const now = Date.now()
  dt = (now - before) / 1000

  // update(dt)
  render()

  before = now

  window.requestAnimationFrame(loop)
}

loop()

If we add this code we will have something like this:

The stacking of figures happens because we are not cleaning the canvas between renderings. And also we are not updating our figure positions yet.

Clearing the canvas

To clear the canvas between iterations we can use the next method:

function clear() {
  context.clearRect(0, 0, canvas.width, canvas.height)
}

This will clean everything in that rectangle and we will be able to draw again:

Updating the elements

Instead of rendering new elements each time, we want to keep the same figures we initialized with createFigures but now we are going to update their X position through time. For that we will use dt .

In this example we are going to update the horizontal position, to know more about how to update speeds, acceleration, use vectors of movement, or things like that I suggest you take a look to the book The Nature of Code or wait for my canvas book to be complete.

function update(dt) {
  const speed = 100 // We can have a different speed per square if we want

  figures.forEach(figure => {
    figure.x = figure.x + (dt * speed ) > canvas.width ? 0 : figure.x + (dt * speed)
  })
}
```



![](https://miro.medium.com/max/1200/0*vYCdtjAK-Rzrk1Bg.gif)

Let’s take a look into the full example code.

If you want to edit it or see it working go to : https://glitch.com/~etereo-animation-canvasfinal



```javascript
const canvas = document.getElementById('canvas');
const context = canvas.getContext('2d');

let before = Date.now()
let dt = 0

const totalFigures = 50

const figures = []

function drawSquare(square) {
  // Store the painting state in a stack
  context.save()

  // We get the radians from a degree
  const radians = Utils.degreeToRadian(square.angle);

  // Translate in the context the origin of coordinates
  context.translate(square.x, square.y);

  // Rotate the context 
  context.rotate(radians);

  // Draw a square
  context.beginPath();
  context.rect(-Math.round(square.size/2), -Math.round(square.size/2), square.size, square.size);
  context.stroke();
  context.fillStyle = square.color;
  context.fill();

  // Paint a text indicating the degree of rotation (at 0, 0 because we have translate the coordinates origin)
  context.fillStyle = 'black';
  context.fillText(square.angle, 0 , 0 );

  // Restore the state of the context from the stack
  context.restore()
}

function createFigures() {
  for(var i = 0; i<totalFigures; i++) {
    figures.push({
      x: Utils.randomInteger(0, 560),
      y: Utils.randomInteger(0, 560),
      color: Utils.randomColor(),
      size: Utils.randomInteger(20, 100),
      angle: Utils.randomInteger(0, 360)
    })
  }
}

function maximizeCanvas() {
  canvas.width = window.innerWidth
  canvas.height = window.innerHeight
}


function update(dt) {
  const speed = 100 // We can have a different speed per square if we want

  // We are updating only the X position
  figures.forEach(figure => {
    figure.x = figure.x + (dt * speed ) > canvas.width ? 0 : figure.x + (dt * speed)
  })
}


function render() {
  figures.map(square => {
    drawSquare(square)
  })
}

function clear() {
  context.clearRect(0, 0, canvas.width, canvas.height)
}

function loop() {
  const now = Date.now()
  dt = (now - before) / 1000

  clear()

  update(dt)
  render()

  before = now

  window.requestAnimationFrame(loop)
}

// Initialize everything
createFigures()
maximizeCanvas()
loop()

```



This is all for now! You did understand how to create animations in a canvas, the rest from here is upon your imagination.

A beginners guide to TDD, JavaScript

venture — Mon, 18 May 2020 08:03:06 +0000

Disclaimer: This is a tutorial and an introduction to TDD, not an in-depth and dogmatic approach to real-life projects. We suggest that you practice this skill before deciding to change the way you code.

What is TDD? In brief: TDD stands for Test-Driven Development. This means that you will develop your code by creating tests first. Those tests will tell you what your code should do. First you will write a test — it will fail because your code can not do what the test demands — and after that you will write the code to make it pass. The repetition of “test” to “code” is a cycle. These cycles repeat over and over until your application is complete. After each one of the cycles we will do a refactor to improve the code quality and reorder things a little. Refactoring is a common practice that every experienced software developer should master.

“Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure.” — Martin Fowler

The cycle, test fail, test pass, refactor

The tests that we will write for TDD are unit tests.

UNIT TESTING is a level of software testing where individual units/ components of a software are tested. The purpose is to validate that each unit of the software performs as designed. A unit is the smallest testable part of any software. It usually has one or a few inputs and usually a single output. In procedural programming, a unit may be an individual program, function, procedure, etc. In object-oriented programming, the smallest unit is a method, which may belong to a base/ super class, abstract class or derived/ child class. See More about unit testing here

Let's learn by practice with an example. Imagine you want to build a calculator with a set of methods: add, subtract, multiply and you want to do it with TDD.

First we will need our Calculator class (if you decide to program using classes, if you are using JavaScript you could use modules or any other kind of abstraction).

class Calculator {
  // This is an empty class
}

For this class we will create our first test:

describe("Calculator", function() {
  var calculator;
  beforeEach(function() {
    calculator = new Calculator();
  });
  it("should have an add method", function() {
    expect(calculator.add).toBeDefined()
  });
});

This code we just saw is a Test. This test is saying that the calculator should have an add method. If we run this test, it will fail, showing something like this:

If we want to do TDD the next step would be to make the test go green. We will do so by implementing the add method

class Calculator {
  add = () => {
    // Empty method
  }
}

After we created the method we can see this test run green:

This is an example of a cycle of testing and implementation. Ideally we should not test that a method exists, we should test what a method does.

So… now that we understand how the cycles work, let’s go a bit further on the implementation:

Test the add method

describe('add method', () => {
  it('should return 4 when receiving 2 and 2', () => {
    expect(calculator.add(2, 2)).toEqual(4)
  })
})

After we execute the test we see this screen:

Then let’s implement the add method.

class Calculator {
  add = () => {
    return 4
  }
}

After implementing it we launch our tests again and… green!

Wait. What?

Yeah. We passed the test. But the logic of our code… is just wrong! A calculator should not work like that.

If we focus only on passing our tests we can create undesired behaviors. This calculator we coded is passing all of our unit tests but it does not work as a real calculator.

As a software developer you should always try to understand the real needs your software is going to accomplish. Just trying to do what you are told is never the way to become a real professional.

Understanding problems in-depth and giving the correct solution, trying to be pragmatic, and avoiding dogmatism are ways to be a better software professional.

Some developers say that TDD should only focus on solving what the test says. And if the software does not accomplish the real goals is because the test is not enough. I disagree. I say we should understand the real problem. People who write tests (usually developers) tend to forget about some edge cases to test or even miss some required functionalities that were poorly communicated. If we focus only on solving what the test demands we will lack in quality.

I am not talking about programming in a defensive way, trying to solve all the possible ideas we have in our mind, but to deliver the right value to our clients. To understand.

Now, moving back to our test, let's see an example of a more complete test scenario:

describe('add method', () => {
  it('should return a SUM when receiving two different numbers', () => {
    for (var i = 0; i < 100; i++) {
      const valueA = Math.round(Math.random() * 100)
      const valueB = Math.round(Math.random() * 100)
      const sum = valueA + valueB
      expect(calculator.add(valueA, valueB)).toEqual(sum)
    }
  })
})

What we are doing is generating 100 random value pairs and seeing if the calculator can give the expected result. We could also work with a defined preset of values that we want to test. There are different things we could test: negative numbers -1, decimal numbers 0.4, really big numbers 10000000000000000000...00 or even unexpected values like strings, arrays, undefined

In this case we will continue by not trying to be smarter than we need. We will implement our add method and move on.

class Calculator {
  add = (a, b) => {
    return a + b
  }
}

We could do the same with the different methods for our calculator. First we implement the test and later on we implement the functionality. Just remember not to be too clever and also not too simple. Just doing what the test demands could be enough in some cases, in others may be nothing of value at all.

In our projects we try to do TDD when working on new components, API methods, or isolated pieces of code that can be unit tested.

We don’t use TDD as a way to deliver all of our software, — sometimes other tools and techniques come more in hand for other scenarios — but we like to practice with it to become better software professionals.

If you are learning your way to the mastery you can try other XP practices:

Continuous Integration and deployment
Pair programing
Small feedback loops

Want to read more about TDD?

Writing a neural network in JavaScript (2020) - Intro to neural networks

venture — Sun, 17 May 2020 13:39:09 +0000

What is a neuron and a neural network?

In biology a neuron is a cell that communicates with other cells via specialized connections called synapses.

As we can see in the following picture, a neuron has a set of connections with different sizes and shapes.

In software, a neuron (artificial neuron) is a mathematical function conceived as a model of the biological neurons.
Artificial neurons have a set of connections (x1, x2, x3) with a different set of weights (w1, w2, w3).

The neuron itself generates an output (y) when it performs a function (o) with the values from the input connections (x1,x2,x3 … w1,w2,w3).
Basically: a neuron is a function that gives a value depending on some input values.

A software artificial neural network is a collection of neurons connected to each other that represent a mathematical function that models something we want to accomplish.

Real-life can be decomposed into math. Imagine you want to write code to identify cats in pictures. This would require you a lot of time and complicated maths. Imagine: decomposing the images in groups of pixels, guessing which characteristics represent a cat, and analyzing if each set of pixels maps one of these characteristics. Sounds complicated.
Here is where neural networks come in hand. Neural networks can be trained to learn how to solve a specific problem.

At the beginning neural networks are a little "random". They are generated with random values and trained against a set of data (dataset). They adjust themselves over and over and learn how to give the expected results. Once a network has been trained to do something it will be able to give predictions with new data that it has never seen before.

So, if you train a network with thousands of cat images it will be able to tell you when you are showing it a cat. But it will not be able to tell you when you are showing it a house. You have trained the network and now the network contains the function (or the code) that model cat characteristics, but nothing else.
One of the best resources for learning about neural networks is the next video by 3blue1Brown

https://www.youtube.com/watch?v=aircAruvnKk

Writing our first neural network

What we are going to model is this:

We want to create the following entities:

Neuron: has input connection, output connections and a bias
Connection: Has a "origin" neuron a "destination" neuron, and a weight.
Layer: has neurons and an activation function
Network: has layers

With this simple neural network in JavaScript we will be able to magically auto-program simple logic gates (AND, OR, XOR, etc). This logic gates could be easily programmed with a normal function but we are going to show how a neural network can solve this problems automatically.
With this knowledge you will be able to understand the basics of machine learning and escalate it to other needs.
For more professional needs we advise you to use some solid frameworks like TensorFlow or Pytorch.
Let's go to code our first neural network in JavaScript from the ground.
In this example we will use object oriented programming with ES6 classes and unit tests.
You can find all the code for this tutorial in the following repo: https://github.com/rafinskipg/neural-network-js

Neuron.js

As you can see, most of the code of the neuron is Boilerplate that you can omit (setters, print functions, etc), the only important things are:

bias
delta
output
error
connections

import uid from './uid'
class Neuron {
  constructor() {
    this.inputConnections = []
    this.outputConnections = []
    this.bias = 0
    // delta is used to store a percentage of change in the weight
    this.delta = 0
    this.output = 0
    this.error = 0
    this.id = uid()
  }

  toJSON() {
    return {
      id: this.id,
      delta: this.delta,
      output: this.output,
      error: this.error,
      bias: this.bias,
      inputConnections: this.inputConnections.map(i => i.toJSON()),
      outputConnections: this.outputConnections.map(i => i.toJSON())
    }
  }

  getRandomBias() {
    const min = -3;
    const max = 3
    return Math.floor(Math.random() * (+max - +min)) +min; 
  }

  addInputConnection(connection) {
    this.inputConnections.push(connection)
  }

  addOutputConnection(connection) {
    this.outputConnections.push(connection)
  }

  setBias(val) {
    this.bias = val
  }

  setOutput(val) {
    this.output = val
  }

  setDelta(val) {
    this.delta = val
  }

  setError(val) {
    this.error = val
  }
}

export default Neuron

Connection

Connections link from one neuron to another neuron. And have a weight.
We will store also the change property to know how much the weight should change between iterations, in the backpropagation phase.

class Connection {
  constructor(from, to) {
    this.from = from
    this.to = to
    this.weight = Math.random()
    this.change = 0
  }

  toJSON() {
    return {
      change: this.change,
      weight: this.weight,
      from: this.from.id,
      to: this.to.id
    }
  }

  setWeight(w) {
    this.weight = w
  }

  setChange(val) {
    this.change = val
  }
}

export default Connection

Layer

A layer is just a collection of neurons.
When we do new Layer(5); we are creating a layer with a group of 5 neurons.


import Neuron from './neuron'

class Layer {
  constructor(numberOfNeurons) {
    const neurons = []
    for (var j = 0; j < numberOfNeurons; j++) {
      const neuron = new Neuron()
      neurons.push(neuron)
    }

    this.neurons = neurons
  }

  toJSON() {
    return this.neurons.map(n => {
      return n.toJSON()
    })
  }
}

export default Layer

Simple for now. Right?

Let's do a quick recap: we just have 3 different concepts or classes for now, that we can use in a simple way like this:

var myLayer = new Layer(5); // create a layer of 5 neurons
// Create a connection
var connection = new Connection(myLayer.neurons[0], myLayer.neurons[1])
// Store references to the connection in the neurons
myLayer.neurons[0].addOutputConnection(connection)
myLayer.neurons[1].addInputConnection(connection)

Basically, to create a network, we just need different layers, with different neurons each, and different connections with weights.

To model this you can use another abstraction, you don't have to follow the one I did. For example, you could make just a matrix of objects and store all the data without using classes. I used OOP because it's easier for me to learn new concepts that I can model easily.

The network

There are some things we should understand before we create our network (group of layers).
1 - We need to create various layers

2 - The input layer neurons have no input connections, only output

3 - The output layer neurons have no output connections, only input

4 - All neurons are created with a random Bias value. Except the ones in the input layer which will have the Input values. Input values are the data we are going to use to give a prediction or a result. For example, in an image of 28x28 it would be 784 pixels of data. In a logic gate it will be 2 values (0 or 1).
5 - In each training step we will provide some values to the Input layer (the training data), then calculate the output and apply Backpropagation to recalculate the weights of the connections.
6 - Backpropagation is a way of adapting the weights of the connections based on the error difference of the desired output versus the real output. After executing it many times the network gives something more close to the expected result. This is training the network.
Before we see all the network code we need to understand how a neuron calculates it's own value in each iteration.

const bias = this.layers[layer].neurons[neuron].bias
// For each neuron in this layer we compute its output value, 
// the output value is obtained from all the connections comming to this neuron
const connectionsValue = this.layers[layer].neurons[neuron].inputConnections.reduce((prev, conn)  => {
  const val = conn.weight * conn.from.output
  return prev + val
}, 0)
this.layers[layer].neurons[neuron].setOutput(sigmoid(bias + connectionsValue))

We calculate the output of a neuron by adding all the products of weight and output from previous connections. It means, getting all the connections that come to this neuron, for each connection we will multiply the weight and output and add it to the total. Once we have the SUM of all products we will apply a Sigmoid function to normalize the output.

What is a sigmoid function?

A sigmoid function is a mathematical function having a characteristic "S"-shaped curve or sigmoid curve.
In neural networks sigmoid function is used to normalize the values of a neuron between 0 and 1.
There are different kinds of functions neural networks use, these functions are called activation functions. Some of the most popular activation functions are Sigmoid, Tanh or ReLU.

You can read a more in-depth explanation of activation functions here.

For now we will just use sigmoid function written in JavaScript:

function sigmoid(z) {  
  return 1 / (1 + Math.exp(-z));
} 

export default sigmoid

Let's take a look now at the full network code.

There are many things going on in the network:

The network connects all neurons from one layer to the next one
When the network is training it runs the runInputSigmoid method, which uses the sigmoid function as an activation function.
Backpropagation is done by calculating the change needed in the weights (delta) and then applying it. The code for calculating weights and deltas is complex.
The run method just calls runInputSigmoid to give the results

import sigmoid from './sigmoid'
import Connection from './connection'
import Layer from './layer'

class Network {
  constructor(numberOfLayers) {
    // Create a network with a number of layers. For layers different than the input layer we add a random Bias to each neuron
    this.layers = numberOfLayers.map((length, index) => {
      const layer = new Layer(length) 
      if (index !== 0 ) {
        layer.neurons.forEach(neuron => {
          neuron.setBias(neuron.getRandomBias())
        })
      }
      return layer
    })

    this.learningRate = 0.3  // multiply's against the input and the delta then adds to momentum
    this.momentum =  0.1  // multiply's against the specified "change" then adds to learning rate for change

    this.iterations = 0 // number of iterations in the training process
    this.connectLayers()
  }

  toJSON() {
    return {
      learningRate: this.learningRate,
      iterations: this.iterations,
      layers: this.layers.map(l => l.toJSON())
    }
  }

  setLearningRate(value) {
    this.learningRate = value
  }

  setIterations(val) {
    this.iterations = val
  }

  connectLayers() {
    // Connects current layer with the previous one. This is for a fully connected network
    // (each neuron connects with all the neurons from the previous layer)
    for (var layer = 1; layer < this.layers.length; layer++) {
      const thisLayer = this.layers[layer]
      const prevLayer = this.layers[layer - 1]
      for (var neuron = 0; neuron < prevLayer.neurons.length; neuron++) {
        for(var neuronInThisLayer = 0; neuronInThisLayer < thisLayer.neurons.length; neuronInThisLayer++) {
          const connection = new Connection(prevLayer.neurons[neuron], thisLayer.neurons[neuronInThisLayer])
          prevLayer.neurons[neuron].addOutputConnection(connection)
          thisLayer.neurons[neuronInThisLayer].addInputConnection(connection)
        }
      }
    }
  }

  // When training we will run this set of functions each time
  train(input, output) {
    // Set the input data on the first layer
    this.activate(input)

    // Forward propagate
    this.runInputSigmoid()

    // backpropagate
    this.calculateDeltasSigmoid(output)
    this.adjustWeights()

    // You can use as a debugger
    // console.log(this.layers.map(l => l.toJSON()))

    this.setIterations(this.iterations + 1)
  }

  activate(values) {
    this.layers[0].neurons.forEach((n, i) => {
      n.setOutput(values[i])
    })
  }

  run() {
    // For now we only use sigmoid function
    return this.runInputSigmoid()
  }

  runInputSigmoid() {
    for (var layer = 1; layer < this.layers.length; layer++) {
      for (var neuron = 0; neuron < this.layers[layer].neurons.length; neuron++) {
        const bias = this.layers[layer].neurons[neuron].bias
        // For each neuron in this layer we compute its output value, 
        // the output value is obtained from all the connections comming to this neuron

        const connectionsValue = this.layers[layer].neurons[neuron].inputConnections.reduce((prev, conn)  => {
          const val = conn.weight * conn.from.output
          return prev + val
        }, 0) 

        this.layers[layer].neurons[neuron].setOutput(sigmoid(bias + connectionsValue))
      }
    }

    return this.layers[this.layers.length - 1].neurons.map(n => n.output)
  }

  calculateDeltasSigmoid(target) {
    // calculates the needed change of weights for backpropagation, based on the error rate
    // It starts in the output layer and goes back to the first layer
    for (let layer = this.layers.length - 1; layer >= 0; layer--) {
      const currentLayer = this.layers[layer]

      for (let neuron = 0; neuron < currentLayer.neurons.length; neuron++) {
        const currentNeuron = currentLayer.neurons[neuron]
        let output = currentNeuron.output;

        let error = 0;
        if (layer === this.layers.length -1 ) {
          // Is output layer, 
          // the error is the difference between the expected result and the current output of this neuron
          error = target[neuron] - output;
          // console.log('calculate delta, error, last layer', error)
        }
        else {
          // Other than output layer
          // the error is the sum of all the products of the output connection neurons * the connections weight
          for (let k = 0; k < currentNeuron.outputConnections.length; k++) {
            const currentConnection = currentNeuron.outputConnections[k]
            error += currentConnection.to.delta * currentConnection.weight
            // console.log('calculate delta, error, inner layer', error)
          }

        }
        currentNeuron.setError(error)
        currentNeuron.setDelta(error * output * (1 - output))
      }
    }
  }

  adjustWeights() {
    // we start adjusting weights from the output layer back to the input layer
    for (let layer = 1; layer <= this.layers.length -1; layer++) {
      const prevLayer = this.layers[layer - 1]
      const currentLayer = this.layers[layer]

      for (let neuron = 0; neuron < currentLayer.neurons.length; neuron++) {
         const currentNeuron = currentLayer.neurons[neuron]
         let delta = currentNeuron.delta

        for (let i = 0; i < currentNeuron.inputConnections.length; i++) {
          const currentConnection = currentNeuron.inputConnections[i]
          let change = currentConnection.change

          // The change on the weight of this connection is:
          // the learningRate * the delta of the neuron * the output of the input neuron + (the connection change * momentum)
          change = (this.learningRate * delta * currentConnection.from.output)
              + (this.momentum * change);

          currentConnection.setChange(change)
          currentConnection.setWeight(currentConnection.weight + change)
        }

        currentNeuron.setBias(currentNeuron.bias + (this.learningRate * delta))

      }
    }
  }

}

export default Network

I am not going to explain why the deltas and weights are calculated with that formula. Backpropagation is a complex topic that requires investigation from your side. Let me give you some resources for your investigation:

Backpropagation: https://en.wikipedia.org/wiki/Backpropagation
What is backpropagation really doing?
Multi-Layer Neural Networks with Sigmoid Function- Deep Learning for Rookies
Backpropagation is really simple who made it complicated?

With the code for the network you will be able to run backpropagation to train it. But it is important you take your time to elaborate on your thoughts on it.

Writing tests to train our network:

In the example repository you will find different tests that allow to train the network in different ways:

Here is our test for a XOR gate and it will serve as a full example on how to use this network for different purposes.
You can try to train the network for different things and see what happens.

import Network from '../network'

// Training data for a xor gate
const trainingData = [{
  input : [0,0],
  output: [0]
}, {
  input : [0,1],
  output: [1]
}, {
  input : [1,0],
  output: [1]
}, {
  input : [1,1],
  output: [0]
}]


describe('XOR Gate', () => {
  let network

  beforeAll(done => {
    // Create the network
    network = new Network([2, 10, 10, 1])

    // Set a learning rate
    const learningRate = 0.3
    network.setLearningRate(learningRate)

    // Train the network
    for(var i = 0; i < 20000  ; i ++) {
      const trainingItem = trainingData[Math.floor((Math.random()*trainingData.length))]
      // Randomly train
      network.train(trainingItem.input, trainingItem.output);
    }

    done()

  })

  it('should return 0 for a [0,0] input', () => {
    network.activate([0, 0])
    const result = network.runInputSigmoid()
    expect(Math.round(result[0])).toEqual(0)
  })

  it('should return 1 for a [0,1] input', () => {
    network.activate([0, 1])
    const result = network.runInputSigmoid()
    expect(Math.round(result[0])).toEqual(1)
  })

  it('should return 1 for a [1,0] input', () => {
    network.activate([1, 0])
    const result = network.runInputSigmoid()
    expect(Math.round(result[0])).toEqual(1)
  })

  it('should return 0 for a [1,1] input', () => {
    network.activate([1, 1])
    const result = network.runInputSigmoid()
    expect(Math.round(result[0])).toEqual(0)
  })
})

If you want to do things that require GPU usage for training (more computational strength) or more complex layers you might need to use a more advanced library like:

But remember, you just coded a neural network, now you know how to dive into them!