README

Powerful object data storage and querying for collaborative web apps.

Nymph is an ORM with a powerful query language, modern client library, REST and Publish/Subscribe servers, and user/group management.

Deprecation Notice

The PHP implementation of Nymph/Tilmeld has been deprecated. It will no longer have any new features added. Instead, a new version of Nymph running on Node.js, written entirely in TypeScript will replace the PHP implementation. You can find it over at the Nymph.js repo.

Live Demos

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

• Todo (source)
• Sudoku (source)
• Simple Clicker (source)

App Template

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

Nymph Entities

Nymph stores data in objects called Entities. Relationships between entities are done by saving one entity in another one's property.

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

// Creating relationships is also easy.
async function createBlogPostComment(post, body) {
  if (!(post instanceof BlogPost)) {
    throw new Error("post should be a BlogPost object!");
  }

  const comment = new Comment();
  comment.post = post;
  comment.body = body;
  await comment.$save();
  return comment;
}

const post = await createBlogPost(
  "My First Post",
  "This is a great blog post!",
  false
);
await createBlogPostComment(post, "It sure is! Wow!");

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: "&",
      // You can do things like pattern matching.
      like: ["title", "%" + userQuery + "%"],
      // Or strict comparison, etc.
      strict: ["archived", false],
    }
  );
}

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

// 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 on any...
      type: "|",
      // ...of the given posts.
      ref: posts.map((post) => ["post", post]),
    }
  );
}

Nymph PubSub

Making collaborative apps 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 });
  });

  component.onDestroy(() => {
    subscription.unsubscribe();
  });
}

User/Group Management

Tilmeld is a user management system for Nymph. Check it out at tilmeld.org.

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.

Dev Environment Installation

If you are interested in working on Nymph itself:

1. Get Docker
   • You can run the Docker install script on Linux with:

     curl -fsSL https://get.docker.com -o get-docker.sh
     sh get-docker.sh

   • Or, from the repos on Ubuntu:

     sudo apt-get install docker.io
     sudo usermod -a -G docker $USER

     Then log out and log back in.
2. Get Docker Compose
   • From the repos on Ubuntu:

     sudo apt-get install docker-compose

3. Clone the repo:

   git clone --recursive https://github.com/sciactive/nymph.git
   cd nymph

4. Make sure the submodules are on master:

   git submodule foreach git checkout master

5. Run the app:

   ./run.sh

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

• Todo App with Svelte
  • http://localhost:8080/examples/examples/todo/svelte/
• Todo App with React
  • http://localhost:8080/examples/examples/todo/react/
• Sudoku App
  • http://localhost:8080/examples/examples/sudoku/
• Simple Clicker App
  • http://localhost:8080/examples/examples/clicker/

API Docs

Check out the API Docs in the wiki.