Creating Entities

To create or retrieve an entity, you can call the factory static method of an entity's class and pass in an optional GUID. You can also use the factorySync method if you need to create a new entity synchronously. The benefit of using the factory method is that it can return the correct type in TypeScript. To check that an entity hasn't been saved yet, check that the GUID is null (entity.guid == null).

// BlogPost extends the Entity class.
let blogPost = await BlogPost.factory();

// Check that the entity is new.
if (someBlogPost.guid == null) {
  alert("This blog post hasn't been saved yet!");
}

Much like entries in many blogging systems, entities can be organized using tags. The tags provide a fast way to query entities.

blogPost.$addTag('super-post');
await blogPost.$save();

let superPosts = await nymph.getEntities(
  { class: BlogPost.class },
  { type: '&', tag: 'super-post' }
);

blogPost.$inArray(superPosts); // true

Be cautious when saving an entity in another entity's property. If the referenced entity is newly created and does not have a GUID, Nymph will not be able to retrieve it later. Always save the referenced entity first.

Saving a Referenced Entity the Right Way

let entity = await Entity.factory();
entity.foo = await Entity.factory();

entity.foo.bar = 'It works!';
await entity.foo.$save(); // Saving the referenced entity first! :)
await entity.$save(); // now foo has been saved.

const guid = entity.guid;
entity = await Entity.factory(guid);

entity.foo.guid == null; // False
console.log(entity.foo.bar); // Outputs 'It works!'.

Saving a Referenced Entity the Wrong Way

let entity = await Entity.factory();
entity.foo = await Entity.factory();

await entity.$save(); // foo hasn't been saved yet!

entity.foo.bar = 'It works!';
await entity.foo.$save();

const guid = entity.guid;
entity = await Entity.factory(guid);

entity.foo.guid == null; // True
console.log(entity.foo.bar); // Outputs undefined.

Caution: Since the referenced entity's class name is stored in the reference on the parent entity, if you change the class name in an update, you need to reassign all referenced entities of that class and resave.

When an entity is loaded, it does not request its referenced entities from Nymph. Instead, it creates instances without data called "sleeping references". When you first access an entity's data (in Node.js), if it is a sleeping reference, it will fill its data from the DB. You can call $clearCache in Node.js or $refresh in the client to turn all the entities back into sleeping references.

In the client, the $readyAll method can be used to awaken all sleeping references in the entity's data. This is the most convenient way to do this, since, unlike in Node.js, the sleeping reference can't just be loaded when it is first accessed.

Previous: Introduction

Next: Entity Querying