Proposal: introduce models to help maintain objects and interact with SAFE

[eblanshey]

Introduction

Allow devs to define all of the application's entities and collections using models. The following functionality should be provided by the models:

• Easy network GETS, PUTS, and DELETES: Provide get(), put(), and delete() methods on the models. Only PUT if data has changed, and DELETE if data exists.
• Custom Helper Methods: allow setting user-defined methods on the model that act as helpers. As a basic example, a fullName() helper method could concatenate an object's first_name and last_name fields and then return the result.
• Data validation: every app has set rules on what its data should look like. If an object contains a name field, for example, it expects it to be a string of a certain length, and NOT an integer or array. In SAFE, anybody can upload any data they want, so client-side data validation must be included in the app to prevent breakage. Task: create an easy way for the dev to set rules for their data. If rules are not met, then either use some defaults, or remove the object entirely. The dev will have a guarantee that the object returned from the API will follow the application's rules, even if a nefarious user tries to cause trouble. Allow devs to attach error messages for each validation rule so they could be used to quickly validate forms, too. See proposal here.
• Data versioning: Object schemas change over time: a string field may eventually become an array field to allow multiple options. The developer cannot go and change all existing data to reflect this change, so his app needs to be smart and maintain backwards compatibility for every single object schema change. Over time, this can lead to massive headaches and spaghetti code in order to make sure old data is supported. Task: introduce versioning for models. Every object PUT to the network should have an integer version number. Upon fetching it, if the model detects that the version number is not the latest one, it incrementally modifies its data using the model's set rules until it matches the rules of the latest version. This should make app development much easier knowing that even old data on the network will be returned using the latest schemas. This allows newer code to read older data, but not vice versa. Bonus: if the requester of the data is also the data owner, automatically UPDATE the object on the network (if possible) so that the same version processing won't be required in the future for all requests. With Structured Data this will be free. See proposal here.

Proposed Basic Functionality

The following illustrates the proposed functionality, not including validation and versioning

// Define a new model (using ES2015 syntax, submit issue if you want ES5)
class Post extends Model {
    // Define a helper getter method (optional)
    titleUpper() {
        return this.data('title').toUpperCase();
    }
}
Post.name = 'Post';

// Let's create a new model
var data = {
    title: "My New Post",
    description: "This is my post description"
};

// Use constructor to fill model
var post = new Post(data);

// Read and set data from the model.
// For consistency, all top-level data must be objects.
post.raw(); // returns the data as is
post.data('title'); // "My New Post"
post.set('description', 'This is a new description'); // returns true
post.data('description'); // 'This is a new description'
post.set('myArray', ['a', 'b']); // true
post.get('myArray.0'); // 'a'

// Use our custom method
post.titleUpper(); // "MY NEW POST"

// Set multiple fields at once
post.fill({title: 'New Title', description: 'A better description'}); // true

// Does the data exist on the network?
post.exists; // bool

// Model name -- could be used as part of the tag_type in Structured Data (SD)
post.name; // 'Post'

// Save the data to the network. Throw error if not authenticated,
// or object does not belong to authenticated user.
post.put()
    .then(() => console.log('The model has been saved.'))
    .catch((error) => console.log(error));

// Userid of the owner. `put()` sets the owner to our userid, of course.
post.owner; // 'aUserIdHere', or null if not exists yet

// ID of this model -- could be the `identifier` in SD
post.id; // 'aPostId', or null if not exists yet

// get a model from the network using its userid and id
var post = Post.identify(userid, id);
post.get()
    .then((post) => console.log(post.exists ? 'Found it' : 'Not found'))
    .catch((error) => console.log(error));
post.loading; // bool. is it currently doing a GET, PUT, or DELETE request?
post.networkError; // string if network error encountered.

// Date last retrieved or put to the network
post.timestamp; // Date() instance, or null if not yet fetched/uploaded

// Delete the model. throws error if you're not the owner.
post.delete();
post.exists; // false

Thoughts, suggestions, and questions welcome!