local_orm

A simple ORM-like wrapper around localStorage with functional interface, types and validations.

Installation

npm install local_orm --save

Usage

Define a schema (yes, we call it a schema):

const { define: define, types: t, validations: v } = require("local_orm");

const Store = define({
  name: "books_schema",
  schema: {
    books: {
      title: {
        type: t.string,
        validations: [v.present, v.maxLength(32)]
      },
      year: {
        type: t.integer,
        validations: [v.min(1900), v.max(2999)]
      },
      genre: {
        type: t.string,
        validations: [v.present, v.oneOf('fiction', 'non-fiction')],
        defaultVal: 'fiction'
      }
    }
  }
});

Let's save some books.

// Create a book
let [err, book] = Store.books.save({ title: "War And Peace" });
console.log(book);
// => { id: "0326d5ce-d3db-4bf7-853f-37d4d5adf6a8", title: "War And Peace", genre: 'fiction' }
// ( Note that we have an id now, and that genre was populated with a default value )

// Let's try another one
let [err, book] = Store.books.save({ year: "1984" });
console.log(book); // => null

// Was there some errors?
console.log(err); // => { 'year': ['should be an integer'], 'title': ['should be present'] }

// Oh, I see now...
let [err, book] = Store.books.save({ title: "So Long, and Thanks for all the Fish", year: 1984 });

We can load books from localStorage now.

// Find a book by id
let book = Store.books.find(id);

// Load all books
let books = Store.books.all();

// Filter by title
let books = Store.books.where({title: 'War And Peace'});

// Any function is also accepted
let books = Store.books.where((b) => b.year > 1980);

Store API

• build builds a new entity with set default values. Returns a new entity

• validate validates an entity. Returns an array [errors, isValid], where errors is an object like this one:

{
  "title": [ "should be present", "should have more than 5 characters" ],
  "year": [ "should be less of equal to 2999" ]
}

• save creates a new entity or updates the existing one (if it has an id). Returns an array [errors, entity]

• find finds an entity by id. Throws an error if it does not exist. Returns an entity

• destroy destroys an entity by id. Throws an error if it does not exist. Returns true

• all loads all entities. Returns an array of entities

• where filters out entities. Accepts object or function. Returns an array of entities

Validations

Validation is a simple plain JavaScript function that takes a value and returns an array like this one [error, valid]. Local_orm comes with several predefined validations.

• present requires a value to be present (not undefined and not null)

validations: [v.present]

• min, max define a range for integer types (inclusive)

validations: [v.min(0), v.max(127)]

• minLength, maxLength define a length range for strings or arrays (really, anything that has length)

validations: [v.maxLength(32)]

• oneOf require a value to be in a particular set of values (like enum)

validations: [v.oneOf("sun", "moon")]

Also, note that when you define a type, under the curtains the corresponding validation is added to the list.

As noted earlier, validations are just functions, so it is easy to define your own:

const positive = (val) => {
  if (val > 0) {
    return [null, true];
  } else {
    return ["should be positive", false];
  }
};

validations: [ positive ]

Contributing

Feel free to fork, add features and send pull requests. Please make sure to add corresponding tests.