datastore: scope Key creation to include NS. fixes #116.

[stephenplusplus]

RE: #116

I actually have 2 different implementations for this, but this was the one I thought was the most logical.

When a user creates a dataset, they can provide a namespace. Then, anytime they need a key, instead of datastore.key(), they call datasetInstance.key() - the key will be created with the namespace already bound to the Key.

The other implementation removed any association of a namespace from a Key object, which felt wrong.

PTAL & LMKWYT.

[rakyll]

This sounds better. There are some cases datastore.key() would be useful to have such as migrating data from one namespace to the other. I think we may need to support namespaces for createQuery optionally too.

[stephenplusplus]

Sounds reasonable, I'll add that in. I also think I may have missed some
doc updates, not sure. Will send through another commit soon.

On Thursday, August 21, 2014, Burcu Dogan notifications@github.com wrote:

This sounds better. There are some cases datastore.key() would be useful
to have such as migrating data from one namespace to the other. I think we
may need to support namespaces for createQuery optionally too.

—
Reply to this email directly or view it on GitHub
#124 (comment)
.

[stephenplusplus]

Made the updates. I didn't add Datastore.key back in, instead allowing for control from the dataset instance level. I think having two places to create one is more confusing than having two ways to configure one. I'll just paste in the documentation to show the changes :)

/**
 * Helper to create a Key object, scoped to the dataset's namespace by default.
 *
 * You may also specify a configuration object to define a namespace and path.
 *
 * @example
 * ```js
 * var key;
 *
 * // Create a key from the dataset's namespace.
 * key = dataset.key('Company', 123);
 *
 * // Create a key from a provided namespace and path.
 * key = dataset.key({
 *   namespace: 'My-NS',
 *   path: ['Company', 123]
 * });
 * ```
 */
Dataset.prototype.key = function(keyConfig) {
  // ...

And I took a similar approach with createQuery:

/**
 * Create a query from the current dataset to query the specified kinds, scoped
 * to the namespace provided at the initialization of the dataset.
 *
 * @borrows {module:datastore/query} as createQuery
 *
 * @param {string=} ns - Optional namespace.
 * @param {string|array} kinds - Kinds to query.
 *
 * @example
 * ```js
 * var query;
 *
 * // If your dataset was scoped to a namespace at initialization, your query
 * // will likewise be scoped to that namespace.
 * query = dataset.createQuery(['Lion', 'Chimp']);
 *
 * // However, you may override the namespace per query.
 * query = dataset.createQuery('AnimalNamespace', ['Lion', 'Chimp']);
 *
 * // You may also remove the namespace altogether.
 * query = dataset.createQuery(null, ['Lion', 'Chimp']);
 * ```
 * @return {module:datastore/query}
 */
Dataset.prototype.createQuery = function(ns, kinds) {
  // ...

[rakyll]

Added some comments, otherwise LGTM.

[stephenplusplus]

undefined -> null 🍻

[silvolu]

I see all of @rakyll's comments resolved, merging.