React Agent Server

React Agent is a JavaScript library for your client store, server querying, and database management. It can be included in any React project without conflict with other state management tools or REST APIs.

React Agent is easy to learn.

Here's the basic idea: the client runs 'actions' that are defined on the server-side.

// client.js
run(‘setMessage’, { message: ‘Hello World’ })
 
// server.js
setMessage: {
    action: ‘INSERT INTO messages(text) VALUES(:message)’
}

These actions can be as powerful as you want -- i.e. CRUD operations, API calls, and authentication. Moreover, clients can subscribe to server-side actions so that they receive live updates.

React Agent includes offline-support to render optimistic updates and then synchronization on reestablished network connection. It also features time travel debugging.

Why use React Agent?

The popular conceptualization of state management stores state in two places: data on the client-side and data on the server-side.

To connect these, front-end and back-end developers usually write a lot of code such as HTTP requests, controllers, and routes. It can get complicated.

In contrast, React Agent serves as a communication channel between the client and the server. It abstracts state transfer to make it super easy to interact between the client and server.

Below is a server-side guide. Here's our full documentation.

Getting Started

This guide is focused on server-side usage of React Agent, although it includes necessary details to know about client-side usage. See React Agent for more information about client-side set-up.

Installing

Install the package:

npm install react-agent-server --save

How to use

First, require React Agent Server into your server-side script.

const agent = require('react-agent-server')

The agent method is called with a server, actions and database object.

const server = http.createServer(fn).listen(3000)
 
const actions = {
  getMessages: {
    action: 'SELECT * FROM posts'
  }
}
 
const database = {
  name: 'billy',
  user: 'billy-user',
  password: 'billy-pw',
  dialect: 'postgres',
  host: 'rabbit.db.elephantsql.com',
  port: 3421
}
 
agent(server, actions, database)

With this setup, whenever run('getMessages') is called from the client-side (via React Agent), the corresponding SQL query ("SELECT * FROM posts") under the action property for getMessages will be ran. The results of this SQL query will be returned to the client.

It is possible to log what React Agent is doing by passing true as the fourth argument for agent. This feature can be helpful for debugging.

As a best practice, a callback can also be added to inspect and modify the direct response from the SQL database. Whatever is returned from this callback is what gets sent back to the client. Call console.log on the response to see the SQL results.

const actions = {
  getMessages: {
    action: 'SELECT * FROM posts',
    callback: response => {
      console.log(response)
      return { messages: response[0] }
    }
  }
}

In the event of a database error, a custom error message can be sent back to the client. This error message is passed into the client promise rejection so it will appear in a catch block. If an error message is not included, React Agent uses its default error messages.

const actions = {
  getMessages: {
    action: 'SELECT * FROM posts',
    callback: response => ({ messages: response[0] }),
    errorMessage: 'Problem retrieving messages.'
  }
}

A pre property can be used to run any number of functions before the action is ran. This is an easy way to provide validation functions or modify the request object sent from the client in any way before it's passed to the action. Just return the request object and it will get passed into the next function. If any of these functions return false, the promise that the client-side run method returns will be rejected and the action will not run.

login: {
    pre: [
      request => {
        if (request.cookie1 === '123') return request
        else return false
      },
      request => {
        if (request.cookie2 === '456') return request
        else return false
      }
    ],
    action: 'SELECT username, _id FROM users WHERE username = :user AND password = :password',
    callback: response => ({ username: response[0][0].username, id: response[0][0]._id })
  }

In the action property above, two properties from our request object from the client will be injected into the SQL string. This is done by using : followed by the request object property name. For example, if the client-side run call looked like this:

run('login', { user: 'Bob', password: 'superstrongpassword' })

Then the appropriate values with those property names will be injected into the SQL string. React Agent uses Sequelize under the hood, which handles input sanitization protecting against many different types of SQL injection attacks.

Arbitrary functions can also be ran instead of using a SQL query string. The function will be passed both a resolve and reject argument (from a new Promise within the library), along with the request object passed in from the client-side run call. The use of a promise makes dealing with asynchronous code in the action easy. (If a function is ran, the action does not take a callback.)

const actions = {
  getPlanet: {
    action: (resolve, reject, request) => {
      const url = request.url
      fetch(url, (error, response, body) => {
        if (error) reject(error)
        else resolve(body)
      })
    }
  }
}

Similar to the functionality of PostMan, it is also possible to run actions defined on the server-side without setting up the client-side. We find this feature very useful since it makes it possible to set up the backend independently of the frontend

Create an object where 1) each attribute is the name of the action that is being tested, and 2) each respective value is the value being passed to the action from the client, if applicable. If a value is not being passed from the client, the value should be null.

Then, include this object as the fifth argument of the agent method. As a reminder, the fourth argument of the agent method can be set to true or false, indicating whether React Agent will log in the console what it is doing. After restarting the server, what is usually sent back to the client will instead be logged in the console. To log out other information such as the direct response from a SQL query, it is possible to include console logs in the actions.

const runs = {
  register: { username: 'Billy', password: 'hardPassword' },
  postMessage: { message: 'hello world' },
  getMessages: null,
};
 
// add `runs` as fifth parameter to use Postman-style testing for server-side
agent(server, actions, database, false, runs);

.

Contributors

Authors

• Tom Rosenblatt - https://github.com/tskittles

• Eric Choi - https://github.com/eric2turbo

• Henry Au - https://github.com/hhau01

• Andrew Harris - https://github.com/didrio

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.