Data Objects for JavaScript and PHP
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
assets
client @ f3938bc
client-node @ f7abdce
examples @ 855a2fd
nymph.io @ 77a8b2c
pubsub @ 01b4c56
query-editor @ 2b0e29c
server @ 9414fd7
tilmeld-client @ c645aa1
tilmeld-server @ da658e8
tilmeld.org @ 6b71408
.gitignore
.gitmodules
Dockerfile-mysql
Dockerfile-pubsub
Dockerfile-web
LICENSE
README.md
autoload-dev.php
docker-compose.yml
favicon.ico
run.sh

README.md

Nymph

Build Status Demo App Uptime Last Commit license

Nymph stores data from objects and lets you query it easily.

It's an ORM with a powerful query language, modern client library, REST and Pub/Sub servers, and user/group management.

Live Demos

Try opening the same one in two windows, and see one window update with changes from the other.

App Template

To start building an app with Nymph, you can use the Nymph App Template.

Nymph Entities

Nymph sends data from objects (called entities) to the server and saves to the database.

// Creating entities is super easy.
async function createBlogPost(title, body, archived) {
  // BlogPost extends Entity.
  const post = new BlogPost();
  post.set({title, body, archived});
  if (!await post.save()) {
    return null;
  }
  // The post is now saved in the database.
  return post;
}

// Creating relationships is also easy.
async function createBlogPostComment(post, body) {
  if (!(post instanceof BlogPost)) {
    alert('post should be a BlogPost object!');
    return null;
  }

  const comment = new BlogPostComment();
  comment.set({post, body});
  if (!await comment.save()) {
    return null;
  }
  return comment;
}

Nymph Query Language

Nymph uses an object based query language. It's similar to Polish notation, as 'operator':['operand','operand'].

// Object based queries are easy from the frontend.
async function searchBlogPosts(userQuery, page = 0) {
  // The server will only return entities the user has access to.
  return await Nymph.getEntities({
    'class': BlogPost.class,
    'limit': 10,
    'offset': page * 10
  }, {
    'type': '&',
    'like': ['title', '%' + userQuery + '%'],
    'strict': ['archived', false]
  });
}

// Querying relationships is also easy.
async function getBlogPostComments(post) {
  return await Nymph.getEntities({
    'class': BlogPostComment.class
  }, {
    'type': '&',
    'ref': ['post', post]
  });
}

// Even complicated queries are easy.
async function getMyLatestCommentsForPosts(posts) {
  return await Nymph.getEntities({
    // Get all comments...
    'class': BlogPostComment.class
  }, {
    'type': '&',
    // ...made in the last day...
    'gte': ['cdate', null, '-1 day'],
    // ...where the current user is the author...
    'ref': ['user', await User.current()]
  }, {
    // ...and the comment is for any...
    'type': '|',
    // ...of the given posts.
    'ref': posts.map(post => ['post', post])
  });
}

Nymph PubSub

Live page updating is easy with the PubSub server.

function watchBlogPostComments(post, component) {
  const comments = component.state.comments || [];
  const subscription = Nymph.getEntities({
    'class': BlogPostComment.class
  }, {
    'type': '&',
    'ref': ['post', post]
  }).subscribe(update => {
    // The PubSub server keeps us up to date on this query.
    PubSub.updateArray(comments, update);
    component.setState({comments});
  });

  return {
    destroy() {
      subscription.unsubscribe();
    }
  };
}

Installation

If you want to build an app with Nymph, you can use the app template.

You can also install Nymph in an existing app by following the instructions in the server and client repos, or in the wiki for Nymph and PubSub.

Nymph Server PubSub Server Tilmeld Server Browser Client Node.js Client Tilmeld Client App Examples

Dev Environment Installation

If you are interested in working on Nymph itself:

  1. Get Docker. On Ubuntu: sudo apt-get install docker.io docker-compose.
  • If you're on Ubuntu, you need to also run sudo usermod -a -G docker $USER, then log out and log back in.
  1. Clone the repo: git clone --recursive https://github.com/sciactive/nymph.git && cd nymph
  2. Make sure you're on master: git submodule foreach git checkout master
  3. Run the app: ./run.sh

Now you can see the example apps on your local machine:

API Docs

Check out the API Docs in the wiki.

What's Next

Tilmeld is a user management system for Nymph. Currently in beta, it provides registration and login with Nymph entities. It's available at tilmeld.org.