README.md

Maizal

Pronounced like /'māisɔːl/

Promise based modern Javascript framework to use your favourite algorithms on the web and node

Installing

Using npm:

$ npm install maizal

In the browser

<script src="https://unpkg.com/maizal/dist/maizal.min.js"></script>

Usage

Perform a Breadth-first search

const maizal = require('maizal');

maizal.bfs({
  initial: {
    position: 1,
  },
  goals: {
    position: 4,
  },
  actions: [
    {
      name: 'right',
      expand: (state) => {
        if (state.position + 1 > 5) return undefined;
        return { position: state.position + 1 };
      },
    },
    {
      name: 'left',
      expand: (state) => {
        if (state.position - 1 < 0) return undefined;
        return { position: state.position - 1 };
      },
    },
  ],
  hash: 'position',
})
.then(results => console.log(results))
.catch(error => console.log(error));

Perform a Dijkstra search

const maizal = require('maizal');

const config = {
  initial: {
    position: 3,
  },
  goals: {
    position: 4,
  },
  actions: [
    {
      name: 'right',
      cost: 50,
      expand: (state) => {
        if (state.position + 1 > 5) return undefined;
        return { position: state.position + 1 };
      },
    },
    {
      name: 'left',
      expand: (state) => {
        if (state.position - 1 < 0) return undefined;
        return { position: state.position - 1 };
      },
    },
  ],
  hash: 'position',
}

async function solveCorridor() {
  try {
    const results = await maizal.dijkstra(config);
    console.log(results);
  } catch (error) {
    console.error(error);
  }
}

NOTE: async/await is part of ECMAScript 2017 and is not supported in Internet Explorer and older browsers, so use with caution.

Documentation

The config object

Initial state

Type	Defaults	Optional	Description
Object		false	Initial state of the search

Examples

const initial = {
  position: [4, 5],
};

const initial = {
  name: 'myFancyName',
};

Goals

Type	Defaults	Optional	Description
Object | Array		false	Set of goals states

Examples

const goals = [
  {
    position: [10, 12],
  },
  {
    position: [4, 2],
  }
];

const goals = {
  height: 200,
};

Actions

Type	Defaults	Optional	Description
Object | Array		false	Set of actions to take for each new state

Key	Type	Defaults	Optional	Description
name	String	'expand'	true	Action name
cost	Int	1	true	Action cost
expand	Function		false	Function that takes a state as argument and returns the data for the following states

Examples

const actions = [
  {
    expand: (state) => {
      return { position: state.position + 1 };
    }
  },
  {
    expand: (state) => {
      return Promise.resolve({ position: state.position - 1});
    }
  },
  {
    name: 'myFancyAction',
    cost: 80,
    expand: (state) => {
      if(state.height > 90) {
        return;
      }
      return { height: state.height + 10 };
    }
  },
];

NOTE: Remember to return undefined or simply return on forbidden actions to avoid generating infinite states

Hash

Used to establish when two newly generated states are essentially the same , for example, in a maze going to the left one cell and the returning to the same represents essentially the same state and we do not want that

Type	Defaults	Optional	Description
String|Function		false	Field or function to determine the equality of two states

Examples

const hash = 'position';

const hash = 'height';

const hash = (state) => `${state.x},${state.y}`;

Heuristics

Used to give a state a 'sense of approaching to the goal'. It is a function that returns decreasing values as the closer we get to the goal. It depends purely on your search state representation and you must ensure to provide logical and decreasing values the closer the solution is

Type	Defaults	Optional	Description
Function		true	Function to determine the 'proximity' to a goal

Examples

const heuristics = ({ x, y }) => {
  // Euclidean distance
  return Math.sqrt(((x - goal.x) ** 2) + ((y - goal.y) ** 2));
};

const heuristics = ({ x, y }) => {
  // Manhattan distance
  return Math.abs((x - goal.x) + (y - goal.y));
};

const heuristics = state => 90 - state.position;

A better documentation its on the way.

Engines

Available engines

Uninformed

Engine	API
Breadth-first	bfs
Dijkstra	dijkstra
Random-search	random
Depth-first	dfs

Informed

Engine	API
Best-first search	bestfs
A*	astar
Weighted-A*	weightedastar

Promises

Maizal depends on a native ES6 Promise implementation to be supported. If your environment doesn't support ES6 Promises, you can polyfill.

Name

Maizal comes from the spanish word 'maizal' which basically means 'cornfield'. Cross thinking in different languages I got the idea of a maze solving library and the popular cornfield mazes and therefore maizal as a similar word as maze in spanish.

License

MIT

Copyright (c) 2018