Jsoncan
- An agile json based database.
- load seamlessly with zero config.
- if you are developing a project like static site, personal blog or business website, jsoncan will be quite useful.
- all the data is saved in json files, it's like a cache system, and it works the way.
- using in the right place, it will be convenient, fast and effective.
Install
npm install jsoncan
Version
1.1.1
Usage
create and connection
var Jsoncan = ; // db root, the json files will save here, make sure the path does exist. if not, jsoncan will try to create it. var PATH = path; // define tables schemas var tables = people: id: text: 'user id' type: 'autoIncrement' name: text: 'your name' type: 'string' max: 30 min: 2 required: true ; // create a new db, if exists, connect it. var can = PATH tables; // create or open a table. var People = can; // can.table('people') do the same thing. // create table with schemas. var Doctor = can;
primary key
- All the tables will be automatically added an "_id" field as the only primary key.
- You need not to define _id field in table schemas.
- You can add multiply unique keys, which are similar to primary key.
insert
when a record inserted, a new "_id" value will be assigned to it.
var Tom; People; // insert multiply records at one time. People;
finder
- using finder to retrieve one record, when no data found, they will return null value.
- finder(_id) find by primary key.
- finder(uniqueName, value) find by unique key.
- find(_id) and findBy(uniqueName, value) are aliases.
// find by primary id People; // or People; // sync way var man = People; // find by unique id, only used for the uniqued fields. People; // or People; // sync way var otherMan = People;
query or findAll
using query() to retrieve multiply records. findAll() is alias.
// query(filters).exec(callback); Product; // or Product; // using where() Product ; // sync way var men = People; // chain skip, limit and select People; // where // support operators: =, >, <=, <>, !=, in, not in, between, like, pattern. var query = People; query; query; query; query; query; // you can chain them. query; // or use a hash query; // select ways query // select all query; query; query; // order ways // default is ascend query; // in descend query; // skip and limit query; // exec query; // exec in sync var records = query; // count query; // count in sync var count = query;
update
// update by primary field Product; // update by unique field User; // update all User; // sync way Product; User; User;
remove
// delete one record User; User; // delete mutilple records User; // sync way User; User; User;
the model way
There are three ways to create a model object:
- var model = Table.create({/data/});
- var model = Table.load(_id);
- var model = Table.loadBy(uniqueName, value);
var Product = can; // create a new one var productA = Product; // or Product.model({...}); productA; product; // load exist record from db // load by primary id var productB = Product; // load by unique field var productC = product; // use chain productA; // remove productA; // sync way productA; productA; productA;
validate
For data safe, jsoncan will always validate the data automatically before save the data into the json file. all the validate rules are defined in field schemas object. the validate part is based on validator.js
so far, you can add these rules.
- isUnique
- isNull
- isRequired
- required // alias isRequired
- shouldAfter [date string]
- shouldBefore [date string]
- length
- size // alias length
- max // max size
- min // min size
- maxValue
- minValue
- pattern [regex object]
in insert or update process, if validate failed, it will throw an error.
// suppose name is an unique field in product var productA = Product; productA;
you can also validate data in model way
var productA = Product; productA; // return boolean productisValid // after validate, isValid will be set true or false // if failed, messages will be set as a hash object. validateMessages = productAmessages;
schemas
the table schemas defined in a normal hash object. except the above validate rule keys, a schema also support these keys:
- text
- type
- default
- format // define a function which format a value for presentation.
- logic // define a function to create a runtime value by other fields value.
- decimals // used for float type.
- values // used for enum or map fields.
- suffix // used for presentation
- prefix // used for presentation
- validate // a custom validate function, when failed return message or return null.
- isFake // for field like 'passwordConfirm', it 's basically same as normal field, except it will never be saved!
- autoIncrement // the first number for autoIncrement field, default is 1
- step // for autoIncrement, default is 1
- isIndex // index field
field types including:
- 'string'
- 'int'
- 'float'
- 'boolean'
- 'map'
- 'hash' // map alias
- 'ref' // new added, reference field
- 'enum'
- 'date'
- 'datetime'
- 'timestamp'
- 'autoIncrement'
- 'password' // will hash password automatically, and you can use Table.isValidPassword(inputedPassword) to check. see safepass.
- 'created' // will set a current timestamp value when record created.
- 'modified' // will be always updated to current timestamp when record saved.
- 'text',
- 'primary' // only for _id field
- 'random' // alpha number random, default length 8
- 'alias' // a logic field, used with "logic" key.
- 'email'
- 'password'
- 'url'
- 'uuid'
- 'alpha'
- 'numeric'
- 'alphanumeric'
- 'ip' // same as ip4
- 'ip4'
- 'ip6'
- 'creditCard'
- 'credit card' // same as creditCard
- 'object' // array, hash, function, up to you
examples:
var schemas = id: text: 'user id' type: 'random' isUnique: true size: 10 firstName: text: 'first name' type: 'string' max: 50 min: 2 required: true lastName: type: 'alias' { return datafirstName datalastName; } password: type: 'password' size: 30 required: true passwordConfirm: type: 'string' size: 30 isFake: true { if value == undefined || value == '' || value == null return 'please input password confirmation'; else if value != datapassword return 'twice inputed passwords are not same!'; } country: text: 'country' type: 'map' requred: true values: 'cn': 'China' 'uk': 'England' 'jp': 'Japan' 'us': 'USA' age: text: 'age' type: 'int' default: 10 sex: text: 'status' type: 'enum' values: 'female' 'male' balance: text: 'cash balance' type: 'float' default: 000 prefix: '$' created: type: 'created' { var d = t; return d d + 1 d + ' ' + d d d; } modified: type: 'modified' ; // then use to create Table. var People = can;
indexes
please see the test file.
references
please see the test file.
// find one with references Blog; // find all with references Product;
more detail
Please see the test part.
performance test
Please see the performance part.