search

Kinto / kinto.js

An Offline-First JavaScript Client for Kinto.
http://kintojs.readthedocs.io/
Other
318 stars 72 forks source link

Naming of «raw» methods #474

Closed leplatrem closed 8 years ago

leplatrem commented 8 years ago

getRaw(), put() and deleteAny() were introduced. I don't find the naming very affordant.

What do you think if we rename them to rawGet(), rawUpdate(), rawDelete() instead? I believe it would be easier to grasp that they are raw alternatives to the common get, update and delete methods, and could be documented in a single doc section.

n1k0 commented 8 years ago

Oh that'd be nicer indeed, so +1

Edit: maybe overkill but that could also be raw.get, raw.put and raw.delete.

glasserc commented 8 years ago

I don't think the put operation is the same as a "raw update" operation. To me an update is like a patch -- the things you provide are added to what was there before. By contrast, a put operation is like a set -- the things you provide replace what was there before. I'd be somewhat OK with calling the put operation rawSet or something like that, but I don't think it would be any more ergonomic. How about save (as in Mongo) or upsert?

I'm also hesitant to say that deleteAny is a "raw" version of delete. In particular, delete supports "virtual" vs. "factual" deletion, which deleteAny doesn't. (But maybe we should pull "factual" deletion into a new method.)

If we were going to describe the two categories of methods, I think I would say get, create, update, and delete are "object database" sorts of functions, and getRaw, deleteAny, and put are "key-value" sorts of functions. But I don't know how to turn these ideas into names.

I'm happy to bikeshed names with you but I don't really want to spend too long focusing on it, so I'm -0 on this particular suggestion.

leplatrem commented 8 years ago

Edit: maybe overkill but that could also be raw.get, raw.put and raw.delete.

hum, in that case, we could use the collection.db attribute and raw calls to the adapter :)

I don't think the put operation is the same as a "raw update" operation.

Maybe, I see your point. But I imagine someone new having to pick one of the numerous methods. Using raw prefix everywhere has an advantage: it could be summarized in one section with something such as same as get, update or delete, except that it won't fail if the targeted record does not exist.

How about upsert?

Yes, why not, especially because that's how it's documented.

Instead of getRaw, why not getAny() for some consistency at least ?

I'm personnally in favor of the raw prefix in order to reduce the overhead of docs.

I'm ok to wait and gather feedback...

glasserc commented 8 years ago

OK, just spoke about this with @leplatrem . We're going to rename put to upsert and getRaw to getAny.