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.
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!'.
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 synchronously. You can
call $clearCache
in Node.js or $refresh
in the client
to turn all the entities back into sleeping references.
Keep in mind that because Nymph is making a synchronous database call when you access a referenced entity's data, you may get thrown errors. You should surround access to data like this in a try/catch block.
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.