Overview
Beef-Flux is a Flux framework with Typescript Support, and can also be used standalone without Typescript.
It contains a URL Router, Data Store, Action Class, and an API Wrapper around reqwest to simplify and standardize API calls.
Usage
yarn add beef-flux
Routing
Routing can be used as both client-side routing as well as server-side routing. It supports passing in url parameters, sanitizing params, and support for HTTP method matching
Client routes
Router.routesnew RouteDefinitions
Beef allows you to define how your routes are handled. They can be handled via full url resolution, hash resolution, etc
//listen on hash changeswindow.addEventListener'hashchange', //listen to html5 state changewindow.addEventListener'onpopstate',
Beef's route decorators allow you to sanitize URL parameters
Router.routesnew RouteDefinitions
Server routes
Similar to client routes, server routes are setup in classes much the same, and are matched in a similar way, with the exception that they contain HTTP methods during the match as well.
Router.routesnew ApiRouteDefinitions server.use http.createServerserver.listen3000
Routing Inside a React App
The RoutingService will return the value of the matched route function, which allows you to use it easily within a react app, and have the different matched routes, return different React Components.
Router.routesnew RouteDefinitions ReactDOM.renderAppContainer /, document.body
Api Calls
Beef API Service provides a common wrapper around reqwest, making it so that every call is standard, and supports parameter replacement in the URL
; Api.geturl, data.thensuccess, error // url = /api/v1/users/1?foo=barApi.posturl, data.thensuccess, error // url = /api/v1/users/1, data = JSON.stringify({foo: 'bar'})Api.puturl, data.thensuccess, error // url = /api/v1/users/1, data = JSON.stringify({foo: 'bar'})Api.deleteurl, data.thensuccess, error // url = /api/v1/users/1?foo=bar
It will automatically replace variables in the URL that are surrounded by curly braces.
For verbs that support a request body, the data that doesn't match a url token, will be sent in the body as a JSON encoded string. For all other verbs, it will be added to the query string.
Store
Beef's Stores hold all the data in your application. A store can hold different types of data, or a single type, depending on how you want to modularize, and break up your app.
Stores also subscribe to dispatched messages from Actions.
Stores contain state that is returned to registered listeners whenever that state changes
/** * Stores hold the data for our application, sanitize it, and listen for * actions to happen. */);
Store Items
Items in a store can be anything, in the example above we are using a strict typed object with a specific schema.
The decorator will automatically populate the schema object, and when passed through the store's sanitize function, will make sure all fields are setup properly
Supported types:
bool
Will sanitize a given value into a boolean, casting "true" = true, "false" = false, 0 = false, 1 = true
int
Will sanitize the value to a whole number
float
Will sanitize the value to a float
double
Will sanitize the value into a double
string
Will sanitize the value to a string
array
If given a "schema" callback, will sanitize all members of the array to the given schema, otherwise no sanitization is performed on the members
object
Requires a schema: () => {} callback, if it returns null, no schema sanitization is performed, otherwise the object is sanitized agaisnt the given schema. Optionally can provide a "constructor" which refers to a class
datetime
Requires MomentJS to be available in the global scope, and will sanitize the value into a moment.Moment object
callback
Allows you to optionally add a function to a schema object
customType
Allows you to provide a custom sanitization callback (such as sanitizing for email, phone number, or other complex types)
Items
upsertItem allows you to update a row if it exists already, or insert a new one.
You give it an array, a primary key value, and then the object you want to insert, or update.
Updates are by default, merge, and not replace. A good optimization if you are always receiving the full object, is to pass true as the 4th argument to overwrite the row.
import TodoStore from "./todo-store"
let todos = []
let todo = {
id: 1,
title: 'My Title'
}
TodoStore.upsertItem(todos, todo.id, todo)
TodoStore.upsertItem(todos, todo.id, todo, true) //overwrite
let byTitle = todos.sort(TodoStore.sortBy('name', 'ASC'))
Schema - no decorator
Beef Stores support creating a schema to sanitize and/or validate a javascript object against.
Each Schema is a javascript object, where the keys are the keys in the object, and the values are a configuration object explaining how that key should be validated, or sanitized.
Beef ships with decorators to aid in the creation of schemas
Creating a Schema without decorators is just as easy as defining a simple JS Object
Todo: id: type: 'int' name: type: 'string' { return '' } completed: type: 'boolean' { return false }
If no initial value callback is provided, and the value doesn't exist in the object you are sanitizing, it will default to null.
Validation
You an also add validation to the schema, which when passed through the validator will return the object, or an array of errors if it isn't valid.
Built in validators include:
required the value cannot be undefined, null, or an empty string
minLength the string value length must be greater than this
maxLength the string value length must be less than this
You can do custom validators, by doing a callback function that will receive the value of that field, and return true or false.
Store Listeners
You can register a listener into a store, that will be called whenever the store's state changes, and receive the new state from the store.
TodoStore.listenOnTodoStoreUpdateTodoStore.ignoreOnTodoStoreUpdate //no longer listen for changes
Actions
Beef contains action classes, which help to simply the flux dispatcher pattern. A common trend is to have your store register with the Dispatcher, and then a switch statement for the message type, which then calls a function.
This can lead to messy situations, where developers begin to add logic within the switch statement, and adds a lot of boilerplate code that is unnecessary.
In Beef, you define and export action callbacks, and register them into the store
When the store listens on the action, the store callback will receive the results of the action. For the most part, most actions will just return an object with the data they received.
On the store side, you can then register a callback for that specific action.