clay

clay.js

version 1.0.0

What

Clay is a lightweight active record for Node.js applications. It leverages the effort of declaring models and its relationships, and store them in any backend.

Clay comes with builtin support for Redis but has a very simple interface with storage mechanisms, so that you can write your own backend.

Hands On !

installation

npm install clay

declaration

the example below was extracted from emerald's codebase

var redis = require('redis').createConnection();
var models = require('clay');

var User = models.declare("User", function(it, kind){
    it.has.field("name", kind.string);
    it.has.field("email", kind.email);
    it.has.field("password", kind.hashOf(["name", "email"]));
    it.has.method('greet', function() {
        return [
            "Hello, my name is ", this.name, ", it's nice to meet you"
        ].join('');
    });
});

var Build = models.declare("Build", function(it, kind){
    it.has.field("status", kind.numeric);
    it.has.field("error", kind.string);
    it.has.field("output", kind.string);
});
var BuildInstruction = models.declare("BuildInstruction", function(it, kind){
    it.has.field("name", kind.string);
    it.has.field("repository_address", kind.string);
    it.has.field("build_command", kind.string);
    it.validates.uniquenessOf("name");
    it.has.index("repository_address");
    it.has.many("builds", Build, "instruction");
    it.has.one("owner", User, "created_instructions");
});

anatomy

Clay provides syntactic sugar function calls that will help you declare models in a very classy, fashion and expressive way.

It is possible through the callback passed to the models.declare call, and it has the arguments it and kind. These two will help you out to declare your model.

field types

Clay's field kinds are no more than just functions responsible to transform and validate data.

You can implement your own field kind, or use the builtin kinds. They come with valitation out of the box:

alphanumeric

shorthand for the regexp /^[a-zA-z-0-9]+$/

USAGE:

var Foo = models.declare('Foo', function(it, kind){
    it.has.field('example', kind.alphanumeric);
});

numeric

shorthand for the regexp /^[0-9]+$/ also returns an integer through parseInt

USAGE:

var Foo = models.declare('Foo', function(it, kind){
    it.has.field('example', kind.numeric);
});

email

shorthand for the regexp /^\w+[@]\w+[.]\w{2,}$/

USAGE:

var Foo = models.declare('Foo', function(it, kind){
    it.has.field('example', kind.email);
});

string

any string of any size, although it's trimmed

USAGE:

var Foo = models.declare('Foo', function(it, kind){
    it.has.field('example', kind.string);
});

slug

any string of any size, will me returned as a slug, for example the input Hello World turns into hello-world

USAGE:

var Foo = models.declare('Foo', function(it, kind){
    it.has.field('example', kind.slug);
});

hashOf

Now this is cool :)

Let's say you want to have a password kind of field.

One of the ways to implement such thing is by concatenating with other field value(s) and then hashed with md5 or sha1, right?

That is what the field kind hashOf does for you. Just declare on it which fields must be ued in the concatenation, that will be done automatically for you.

You can take a look on its unit tests to see how it works precisely, but here is an example:

var u1 = new User({
    name: "John Doe",
    email: "[e-mail]",
    password: '123'
});

assert.equal(u1.password, "f8543ecd4084527d7bc443f272a38c6390bbb7d6")

the password was already converted from 123 to f8543ecd4084527d7bc443f272a38c6390bbb7d6, which is the sha1 sum of the string:

John Doe|sha1-emerald|[e-mail]|sha1-emerald|123

saving instances

var assert = require('assert');

var lettuce_instructions = new BuildInstruction({
    name: 'Lettuce Unit Tests',
    repository_address: 'git://github.com/gabrielfalcao/lettuce.git',
    build_command: 'make unit'
});

lettuce_instructions.save(function(err, pk, model_instance, storage, redis_connection){
    assert.equal(pk, 'clay:BuildInstruction:id:1');
});

finding by id

BuildInstruction.find_by_id(1, function(e, found){
    assert.equal(found.name, 'Lettuce Unit Tests');
    assert.equal(found.repository_address, 'git://github.com/gabrielfalcao/lettuce.git');

    assert.equal(
       "Will now build: {name}".render(found),
       "Will now build: Lettuce Unit Tests"
    );
});

finding by any field

Clay attempts to be really simple to use, and for the sake of this fact there is a lot of magic here.

When you declare any model with Clay, you have special class-methods available right away.

In order to search by any declared field, all you need to do is call YourModel.find_by_fieldname, where YourModel is the return of models.declare() and fieldname is the name of any fields you have declared. All of them will be available.

It takes just 2 parameters: the RegExp that will be used to match against values and a callback.

The callback, takes 2 parameters: an error and an array with instances of models.

example

var adam = new User({
    name: "Adam Nelson",
    email: "[e-mail]",
    password: '123'
});
adam.save(function(e, pk, instance){
    User.find_by_email(/yipit.com$/, function(e, found){
        assert.equal(found.length, 1);

        assert.equal(found.first.name, 'Adam Nelson');
        assert.equal(found.first.email, '[e-mail]');
    });

License

<clay - active record for node.js with redis backend>
Copyright (C) <2011>  Gabriel Falcão <[e-mail]>

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.