framewrk

Framework a.k.a Framewrk

Motivation

This is a client side framework that I decided to write as a learning exercise. I've taken some ideas used in Redex and applied them to the framework i've written. Along with this i've also decided to limit the view layer to React only due to it's performance.

Libraries used

Core

• React
• Router.js

Build

• Babel
• Webpack

Quick Start

import React from 'react';
import framework from '../src';

const AppView = (props) => {
  return (<h1>Hello, {props.name}!</h1>);
}

framework.setup({
  defaultRoute: '/:name'
});

const container = document.createElement('div');
document.body.appendChild(container);

framework.route({
  path: '/:name',
  view: {
    component: AppView,
    props: (req) => {
      return {
        name: req.params.name
      };
    },
    container: container
  }
});

framework.start();

Installation

npm install framewrk --save

Example

The obligatory todomvc example.

Documentation

Framework

• setup
• start

Routes

• route
• Route Configuration
• View Object
• Request Object

Stores

• store

Store Instance

• get
• actions
• processor
• publish
• subscribe

Persistence Interface

• get
• set

Framework

setup(options)

Provides you with an opportunity to set a default route and persistence the framework should use. You must call this before start(), if you provide a Persistence class then you must call this before you setup a store with the framework.

Arguments

• options

• defaultRoute - The first route the framework should trigger, defaults to /.
• Persistence - A class that implements the persistence interface.

Example

const options = {
  defaultRoute: '/',
  Persistence: PersistenceClass
};
framework.setup(options);

---

start()

Triggers the defaultRoute provided during the setup call.

Example

framework.start();

Routes

route(routeConfiguration)

Provide the framework with a configuration for a route.

Arguments

• options - A route configuration object.

Examples

const AppComponent = React.createClass({
  render() {
    return (<h1>Hello, {this.props.name}</h1>);
  }
});

const options = {
  path: '/:name',
  view: {
    container: document.getElementById('#my-app-container'),
    props(req) {
      return {
        name: req.params.name
      };
    },
    component: AppComponent
  }
};

framework.route(options);

---

Route Configuration

A route configuration object supports the following properties:

• path - (required) The absolute path (must begin with /) used to trigger the given route, the path can accept parameters (e.g. /welcome/:name) and wildcards (e.g. /:name/*(*)).
• handler - A function that is called with the current routes request object.
• view - A view object.
• views - An array of view objects.

Example

{
  path: '/:name',
  handler(req) {
    req.admin = true;
  },
  view: {
    container: document.getElementById('#my-app-container'),
    props(req) {
      return {
        name: req.params.name,
        admin: req.admin
      };
    },
    component: AppComponent
  }
}

---

View Object

A view object supports the following properties:

• container - A javascript element for where the given react component should be mounted.
• props - A function that is called with the current routes request object, it should return an object of props to pass to the react component.
• component - A react component.

Example

{
  container: document.getElementById('#my-app-container'),
  props(req) {
    return {
      name: req.params.name
    };
  },
  component: AppComponent
}

---

Request Object

A request object provides the following properties:

• href - The current path including the #
• params - An object containing any path parameters.
• query - An object of the current query string, values are not casted.
• splats - An array containing one element which will be the matched wildcard from the path, however this property is only available if the current path contains a wildcard.

Example

For a path of /:name:

{
  href: '#/rahul?new=true',
  params: {
    name: 'rahul'
  },
  query: {
    new: 'true'
  }
}

For a path of /:name/**:

{
  href: '#/rahul/welcome/admin',
  params: {
    name: 'rahul'
  },
  query: { },
  splats: [
    'welcome/admin'
  ]
}

Stores

store(name, initialState)

Create or retrieve a store instance. Not providing an initialState will cause the initialState to be set to an empty object, but if a persistence class is provided, the framework will set the initialState to the result of persistence.get().

Arguments

• name - (required) The identifier for the store.
• initialState - The initial state of the store, defaults to { } or persistence.get() if persistence is provided.

Example

const store = framework.store('todos', [ ]);

const todosStore = framework.store('todos');

// store === todosStore

Store Instance

get()

Get the current state of the store.

Example

const initialState = [
  {
    id: 0,
    title: 'My first todo',
    completed: false
  }
];
const store = framework.store('todos', initialState);

const state = store.get();

// state === initialState

---

actions()

Returns an object of all actions currently supported by the store.

Example

const store = framework.store('todos', [ ]);
store.processor('ADD_TODO', (currentState, actionData) => [...state]);

const actions = store.actions();

// actions === {
//   ADD_TODO: 'ADD_TODO'
// }

---

processor(action, processor)

Give the store a processor (equivalent to a reducer in redux) for the given action.]

Arguments

• action - The name of the action this processor should be run for.
• processor(currentState, actionData) - A function that will receive the current state of the store along with the current action data. The processor must return a new copy of the state.

Example

const store = framework.store('todos', [ ]);
store.processor('ADD_TODO', (currentState, actionData) => [...currentState]);

---

publish(action, data)

Publish an action to the store. The store will run the necessary processor (if one has been provided) and call all subscribers with the new state and action. You may call publish without any arguments, which will cause the view(s) to re-render and the persistence to be updated once again with the same state. The framework will automatically re-render to the current routes view(s) as well as persist the state if persistence has been provided.

Arguments

• action - The name of the action.
• data - Any context you'd like to provide for the action, it'll be passed to the corresponding processor.

Example

const store = framework.store('todos', []);
store.processor('ADD_TODO', (currentState, actionData) => {
  return [
    actionData,
    ...currentState
  ];
});
store.publish('ADD_TODO', {
  id: 1,
  title: 'My second todo',
  completed: false
});

---

subscribe(callback)

Be notified of any updates to the store.

Arguments

• callback(state, action) - The function to call when anything is published to the store.

Example

const store = framework.store('todos', [ ]);

store.subscribe((state, action) => {
  console.log(state);
  console.log(action);
});

store.processor('ADD_TODO', (currentState, actionData) => {
  return [
    actionData,
    ...currentState
  ];
});
store.publish('ADD_TODO', {
  id: 1,
  title: 'My second todo',
  completed: false
});

// Console output:
// [
//   {
//     id: 1,
//     title: 'My second todo',
//     completed: false
//   }
// ]
// 'ADD_TODO'

Persistence Interface

Persistence is used internally by the framework to persist the state of stores to where ever you may require. It's simple interface means it's perfect for key value data stores, though it's extendable enough to be able to use just about any store you'd like. Checkout the Persistence Class in the example to see how to set it up to persist to state local storage.

get(storeName)

Get the state for the given store from the persistence.

Arguments

• storeName - The name of the store.

---

set(storeName, state)

Persist the state for the given store name.

Arguments

• storeName - The name of the store.
• state - The current state from the store.

Changelog

<1.0.2> <16/14/2016>

• Add npm preversion script