flatiron/resourceful — Issue #22: Documentation on engine interfaces?
Author: pdaoust
Created: 2011-11-25 00:24:00+00:00
State: open

Hi there. I'm just starting to write a MongoDB engine (don't worry; I'll issue a pull request), and I have some questions...

Have you folks started writing documentation on the interfaces that an engine is supposed to expose? The CouchDB and Memory engines are somewhat self-documenting, but I have questions about the nuances of `put()`, `save()`, and `update()` -- coming from a MongoDB point-of-view, some of these seem redundant, and I'm wondering if one can be a direct reference to another, or if there are enough subtle differences that they should be implemented differently? (E.g., what should happen when `update()` tries to update a record that isn't there; should it fail, or should it `upsert`?)

There doesn't seem to be a `post()` interface defined in either of the reference engines; for now, it seems like you have to go `Resource.create()` and allow it to create and assign a unique ID for you. This means that the example code (the one where you create a wolf and feed it a squirrel) using the `new` keyword and saving later won't work... would it be sensible to implement a `post()` interface which does not require an ID but assigns the ID to the object later? If so, I think the callback in `Resource.prototype.save()` should also check to see if a new ID has been returned and assign it to `_id`, just as with `Resource.create()`. (Note: I'm not sure how new records are saved to the database without IDs, because none of the engine's interface permit a null or undefined ID.)

In what situations is `update()` actually used; can it be used to send just a few key/value pairs to the engine and have it update just those values on the object with the given ID?

mmmmmmmmm... I think those are all my questions for now. Thanks for an awesome library; looking forward to using it!