UIDs

UIDs, or unique IDs, provide an easier way for users to identify entities. UIDs are just sequential numbers and can be used for anything you like, not just entities. As opposed to a GUID, which is a unique ID for all entities, a UID is only unique for its own sequence. Therefore, they are more visually appealing to be used as an ID. (Think Sale #615 vs Sale #790219d8fb67a1357707b71d.)

Nymph has the following methods for handling UIDs:

  • deleteUID - Delete a unique ID from the system.
  • getUID - Get the current value of a unique ID.
  • newUID - Increment or create a unique ID and return the new value.
  • renameUID - Rename a unique ID.
  • setUID - Set the value of a unique ID.
let entity = await Post.factory();

entity.id = await nymph.newUID('Blog/Post');
await entity.$save();

You probably don't want to allow any UIDs from the client. Then a malicious user can mess with the UID. Instead, from the server side, you can create a UID when the entity is saved. You can also gate UIDs using abilities like "uid/get/nameofuid", "uid/new/nameofuid", and "uid/set/nameofuid". These abilities are only checked for client queries. If you're using UIDs from Node.js and want to gate them, use the checkClientUIDPermissions method on Tilmeld.

Caution: If a UID is incremented, and the entity you're using it on can't be saved, there is no safe way to decrement the UID back to its previous value. Therefore, you're advised to not use UIDs within transactions. (You can use your top-level instance of Nymph to make a query outside of your transaction.)