maizal v0.4.0

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

Examples

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

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

Goals

Examples

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

const goals = {
  height: 200,
};

Actions

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

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

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

Informed

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