JSDoc: Class: CuriousQuery

new CuriousQuery(initialTermStringopt, initialRelationshipopt, initialObjectClassopt) → {CuriousQuery}

Make a Curious query from constituent parts, using a chain of method calls to a single object.

CuriousQuery objects are an object-based representation of a Curious query string to make passing around parts of a query and assembling queries easier.

The result of curious queries will be an object containing arrays of objects, as specified in the Curious query. This would be analogous to what a Django QuerySet might look like on the back end.

If there is more than one kind of object returned by the query and the query specifies some kind of relationship between the data in the objects (for example, Reactions that have Datasets), the returned objects will have attributes that point to their related objects. The names of these relationships are provided as a user-specified parameter.

You construct CuriousQuery objects with a repeated chain of function calls on a core object, CuriousQuery object, much like in jQuery, or _.chain(). Every stage of the chain specifies a new term in the query, and a relationship name as a string. The stages can also take an optional third parameter that will specify the class of the constructed objects (insead of just CuriousObject).

The initial Curious term happens either by passing parameters directly to the construtor, or by calling .start().

Parameters:

Name	Type	Attributes	Description
`initialTermString`	string	<optional>	The string for the starting term
`initialRelationship`	string	<optional>	The starting term's relationship
`initialObjectClass`	function	<optional>	A custom object class constructor for the starting term

Source:

curious.js, line 222

Returns:

The newly constructed object

Type: CuriousQuery

Examples

// Explicitly set start, wrapWith classes
var q = (new curious.CuriousQuery())
  .start('Experiment(id=302)', 'experiment')
  .follow('Experiment.reaction_set', 'reactions')
  .follow('Reaction.dataset_set', 'dataset').wrapWith(Dataset)
  .follow('Dataset.attachment_set');

q.query() ==
  'Experiment(id=302), Experiment.reaction_set, '
  + 'Reaction.dataset_set, Dataset.attachment_set'

// Terser version of the same query above
var q = new curious.CuriousQuery('Experiment(id=302)', 'experiment')
  .follow('Experiment.reaction_set', 'reactions')
  .follow('Reaction.dataset_set', 'dataset', Dataset)
  .follow('Dataset.attachment_set');

Methods

catch(rejected) → {CuriousQuery}

Add a callback to be called if the promise to perform the query is rejected. This can be useful for constructing a query object with known error-handling before actually executing it.

Parameters:

Name	Type	Description
`rejected`	function	A function to call when the promise is rejected (just like you would pass to Promise.prototype.catch)

Source:

curious.js, line 684

Returns:

The query itself, to allow chaining thens catches, or any other methods

Type: CuriousQuery

clone() → {CuriousQuery}

Return a deep copy of the current query object.

Source:

curious.js, line 353

Returns:

A new CuriousQuery object constaining the same terms, relationships, constructors

Type: CuriousQuery

extend(extensionQueryObject) → {CuriousQuery}

Extend this query object with another query object: return a new query chain with the current query chain's terms followed by the other query chain's terms.

Parameters:

Name	Type	Description
`extensionQueryObject`	CuriousQuery	The query object being added

Source:

curious.js, line 332

Returns:

The combined query

Type: CuriousQuery

follow(termStringnon-null, relationshipnon-null, customConstructoropt, nullable) → {CuriousQuery}

Add an inner-join term to this query.

Parameters:

Name	Type	Attributes	Description
`termString`	string		The contents of the starting term
`relationship`	string		The name of this term in inter-term relationships
`customConstructor`	function	<optional> <nullable>	A custom constructor function for the resulting objects

Source:

curious.js, line 481

Returns:

The query object, with the term appended

Type: CuriousQuery

having(termStringnon-null) → {CuriousQuery}

Add a filter term to this query.

Parameters:

Name	Type	Description
`termString`	string	The subquery to filter by

Source:

curious.js, line 493

Returns:

The query object, with the term appended

Type: CuriousQuery

notHaving(termStringnon-null) → {CuriousQuery}

Add an exclude filter term to this query.

Parameters:

Name	Type	Description
`termString`	string	The subquery to filter by

Source:

curious.js, line 505

Returns:

The query object, with the term appended

Type: CuriousQuery

perform(curiousClientnon-null) → {Promise}

Perform the query using a passed-in CuriousClient object.

Parameters:

Name	Type	Description
`curiousClient`	CuriousClient	A CuriousClient object that will handle performing the actual query

Source:

curious.js, line 622

Returns:

A promise, as returned by module:curious.CuriousClient#performQuery

Type: Promise

query() → {string}

Generate the constructed query string represented by this object.

Source:

curious.js, line 246

Returns:

The fully constructed query

Type: string

setExistingObjects(objsnon-null) → {CuriousQuery}

Set the existing objects that this query will use to link the returned objects into.

Parameters:

Name	Type	Description
`objs`	Array.<!Object>	The existing objects to set

Source:

curious.js, line 598

Returns:

The query object with its existing object set updated

Type: CuriousQuery

setParams(paramsnon-null) → {CuriousQuery}

Set the parameters that this query will pass to its curious client when perform is called.

Parameters:

Name	Type	Description
`params`	Object	An object of parameters to set--see module:curious.CuriousClient#performQuery for a full description of the parameters.

Source:

curious.js, line 574

Returns:

The query object with its curious client parameters updated

Type: CuriousQuery

start(termStringnon-null, relationshipnon-null, customConstructoropt, nullable) → {CuriousQuery}

Add a starting term to this query. Equivalent to passing parameters directly to the constructor.

Parameters:

Name	Type	Attributes	Description
`termString`	string		The contents of the starting term
`relationship`	string		The name of this term in inter-term relationships
`customConstructor`	function	<optional> <nullable>	A custom constructor for the resulting objects, if this part of the query returns new objects

Source:

curious.js, line 465

Returns:

The query object, with the term appended

Type: CuriousQuery

then(fulfilled, rejectedopt) → {CuriousQuery}

Add a (pair of) callback(s) to be called when the promise to perform the query resolves. This can be useful for constructing a query object with known post-processing before actually executing it.

Parameters:

Name	Type	Attributes	Description
`fulfilled`	function		A function to call when the promise is fulfilled (just like you would pass to Promise.prototype.then)
`rejected`	function	<optional>	A function to call when the promise is rejected (just like you would pass as the second argument to Promise.prototype.then)

Source:

curious.js, line 665

Returns:

The query itself, to allow chaining thens, or any other methods

Type: CuriousQuery

toJSON() → {string}

Convert this probject to a plain JavaScript object to allow it to be serialized.

Source:

curious.js, line 300

Returns:

The fully constructed query

Type: string

toString() → {string}

Convert this object to a string, returning the complete query string

Source:

curious.js, line 286

Returns:

The fully constructed query

Type: string

valueOf() → {string}

Convert this probject to its native value equivalent, returning the complete query string

Source:

curious.js, line 293

Returns:

The fully constructed query

Type: string

with(termStringnon-null, relationshipnon-null, customConstructoropt, nullable) → {CuriousQuery}

Add an outer-join term to this query.

Parameters:

Name	Type	Attributes	Description
`termString`	string		The contents of the starting term
`relationship`	string		The name of this term in inter-term relationships
`customConstructor`	function	<optional> <nullable>	A custom constructor for the resulting objects, if this part of the query returns new objects

Source:

curious.js, line 522

Returns:

The query object, with the term appended

Type: CuriousQuery

wrapDynamically(factoryFunction) → {CuriousQuery}

Specify the object factory function to use for the preceding term in the query. Unlike wrapDynamically, which can work with traditional constructors that do not return a value by default, this will only work with factory functions that explicitly return an object.

Parameters:

Name	Type	Description
`factoryFunction`	function	A factory function that returns an object of the desired wrapping class

Source:

curious.js, line 552

Returns:

The query object, with the new constructor data stored internally

Type: CuriousQuery

wrapWith(customConstructoropt, nullable) → {CuriousQuery}

Specify the object constructor to use for the preceding term in the query.

Parameters:

Name	Type	Attributes	Description
`customConstructor`	function	<optional> <nullable>	A constructor to use when instantiating objects from the previous part of the query

Source:

curious.js, line 536

Returns:

The query object, with the new constructor data stored internally

Type: CuriousQuery