Object model surface area and nomenclature changes (v2) about azure-cosmos-js HOT 16 CLOSED

Assuming that there is not another contending name, I prefer "collection" over "container". Container I have mostly seen in a GUI context. It does feel awkward.

from azure-cosmos-js.

Suggested change:

I think it makes sense to allow objects to be able to modify themselves and to create objects that can be self-referencing.

The objects would still be stateless (save for the coordinates from the factory i.e. ids and partition keys)

Examples:

Container

#.database(): Database // point to parent database
#.read(options?: RequestOptions) => Promise<Response<ContainerDefinition>>
#.replace(body: T, options?: RequestOptions) => Promise<Response<ContainerDefinition>>
#.delete(options?: RequestOptions) => Promise<Response<ContainerDefinition>>

Example:

// check if this container has a sibling(s) with a suffix
async function findSiblings(c: Container): Container[] {
    const {result: siblings} = await c.database.query(`SELECT * FROM d WHERE STARTSWITH(${c.id})-`).toArray();
    return siblings;
}

Item

#.container(): Container  // points to parent container
#.read<T>(options?: RequestOptions) => Promise<Response<T>>
#.replace<T>(body: T, options?: RequestOptions) => Promise<Response<T>>
#.delete<T>(options?: RequestOptions) => Promise<Response<T>>

somewhat contrived example:

function getTodoForFutureUpdates(c: Container, todoId: string, userId: string): Item {
    return c.getItem(userId, todoId);
}

Stored Procedure

#.container(): Container  // points to parent container
#.execute<T>(params: any[], options?: RequestOptions) => Promise<Response<T>>
#.read<T>(options?: RequestOptions) => Promise<Response<T>>
#.replace<T>(body: T, options?: RequestOptions) => Promise<Response<T>>
#.delete<T>(options?: RequestOptions) => Promise<Response<T>>

Current:

c.executeStoredProcedure("fizzbuzz");
c.executeStoredProcedure("fizzbuzz");

Suggested:

(Current continues to work)

const sp = c.getStoredProcedure("fizzbuzz");
sp.execute();
sp.execute();
sp.execute();

from azure-cosmos-js.

Container vs Collection

As a developer, "container" feels awkward to me. I don't know if that's because I'm used to seeing "collection", but I am wracking my brain and I cannot think of any other instances where I have used "container" in a NoSQL context.

from azure-cosmos-js.

re: Container vs Collection - @kirankumarkolli & @kirillg, could you comment?

from azure-cosmos-js.

@burkeholland RE: Container vs Collection

Because we're multi-model, we're starting to rename the base concepts to more generic names, so we're not overloading traditional NoSQL names (Collection/Document/etc.) when we're doing Graph and Cassandra operations on the same data set, in the future.

We could, however, offer a shim or typedef for Collection & Document for folks looking for traditional NoSQL APIs, that are just direct representations of our Container/Item concepts. Do you think that might address your concern?

from azure-cosmos-js.

from azure-cosmos-js.

It's a good question. We'd have to document them both, is my assumption. Same doc or different doc. I'm not sure how/when we're changing our top level messaging/portal UI/etc.

If it's an interesting idea to you, I can work it out with @kirillg in more detail.

from azure-cosmos-js.

from azure-cosmos-js.

It's fair feedback on the naming, though. We've had a few folks mention it. We have good reasons to change the name for other consumers (like Mongo/Gremlin/etc.) to avoid overloading the Document NoSQL stuff for each of them, but that plan does mean impacting the folks using Cosmos for the Document style interaction. I definitely want to see what can be done to prevent this causing confusion.

We're doing user testing with the new names & API style. That will hopefully give us some more feedback in a controlled setting.

from azure-cosmos-js.

Suggestion:

All the .get*(id) calls should just be called .get(id), though they will all defer in which types they return, still.

I think it's self explanatory that databases.get("foo") will return a database, and it saves on line length/etc.

from azure-cosmos-js.

Suggestion: (Needs more investigation)

Could support a Proxy on the plural objects that have .get calls that will proxy calls to non-reserved indexes to .get.

So you can do:
client.databases["foo"].read()

instead of

client.databases.get("foo").read();

It really pays off once you add two layers:

client.databases.foo.containers.bar.items.get("baz","qux")
vs
client.databases.get("foo").containers.get("bar").items.get("baz", "qux")

.get would still work because Proxy would just proxy to it

Strawman implementation:

type ProxiedDatabases = Databases | [database: string]: Database;

const databases = new Databases(this);
this.databases = new Proxy(databases, {
    get: (obj, prop) => obj.get(prop);

Pros:

• Faster to access things
• Avoids overhead of ".get" call
• Matches C# API

Cons:

• Will add overhead to every single call since it has to go through the proxy.
• It's not a well known pattern in JavaScript (Proxy is very new). It might lead to weird things that are hard to explain.

from azure-cosmos-js.

Suggestion:

.get accepts an id, but it should also be able to accept an object that has an id property on it

from azure-cosmos-js.

Suggestion:

Things like permissions require a link to a resource. It takes a resource url string, but it should also be able to take an object that has a url property on it.

from azure-cosmos-js.

👍 to both of @christopheranderson suggestion. I particularly found that overloading .get would have helped when refactoring the tests.

from azure-cosmos-js.

This was mostly done in #26. Some minor tweaks happened in response to feedback covered in #39.

from azure-cosmos-js.

This feedback has been addressed or moved to independent issues, so I'm closing.

from azure-cosmos-js.