Introduction

Nymph is an application data framework for Node.js and the browser, written in TypeScript. Nymph data objects, called entities, are accessed just like plain objects. Nymph includes a REST server, a Publish/Subscribe server, and a user/group manager with authentication.

Data in Nymph is stored and manipulated in objects called entities. Entities can hold most types of data available in JavaScript, including other entities. Entities are not strictly structured, so data of any type can be added and saved just by assigning it to a property on the entity and calling $save. This makes data manipulation and rapid prototyping in Nymph very easy. Then when you're ready to launch to production, you would use a validation library to enforce a schema for your entities. Joi is a good one. You can do this in the $save method on your entities before calling return await super.$save();. This means that during development, you don't need to worry about managing schemas at all, but you still get the benefit of strict checks in production.

All entities are given a globally unique identifier (GUID), which is a random, cryptographically secure, 12 byte integer, encoded in a 24 character, lowercase HEX string. Since these are random and quite large, there should never be any two entities in any Nymph installation with the same GUIDs (unless that's done on purpose). Nymph also provides UIDs, which are sequential and can be used to number entities (or anything else).

Using Nymph, nearly all of an app's business logic can be written on either the client side or the server side, since you interact with data the same way in each. Anything that relies on access control can be handled on the server side where Tilmeld, Nymph's optional user/group manager, provides access control.

When you save an entity in another entity's properties, that relationship is saved in the database, and you can query for those kinds of relationships. When you pull out the parent entity from the database, the child entity is in a reference state called a "sleeping entity". When an entity is asleep, only its GUID is known. You can "awaken" the entity, which pulls all of its data from the database/server. Referenced entities' class names are saved along with their GUIDs. When this entity is isntantiated, Nymph will retrieve it using the saved class, so it will have the correct class even when it's asleep. You can awaken a sleeping entity by using the $wake method on it. You can also use the $wakeAll method on an entity to awaken all of the sleeping entities in its data.

When querying entities with Nymph, the ETYPE constant on the class determines which database table(s) Nymph will look in. Usually, one etype will map to exactly one class, but that's not a requirement.

You now know the basics of how data is managed in a Nymph application. When you're ready to start getting into the details, move to the next section.

Caution: When changing an entity's class name, any entities referencing it must be resaved after setting the reference again using the new class name.

If you want to really dive deep into Nymph, you can also browse the API docs, which covers every part of Nymph's API.