# Mongo pipelines are arrays of aggregation stages
#
# With the `MongoCollection::aggregate` method, pipeline stages appear in a array.
# Documents pass through the stages in sequence.
#
# ~~~json
# db.collection.aggregate( [ { <stage> }, ... ] )
# ~~~
#
# The MongoPipeline fluent interface can be used to bluid a pipeline:
# ~~~
# var pipeline = (new MongoPipeline).
#	match((new MongoMatch).eq("game", "nit")).
#	group((new MongoGroup("$game._id")).sum("nitcoins", "$game.nitcoins")).
#	sort((new MongoMatch).eq("nitcoins", -1)).
#	limit(10)
# ~~~
#
# The pipeline can then be used in an aggregation query:
# ~~~nitish
# collection.aggregate(pipeline)
# ~~~
#
# For more information read about MongoDB pipeline operators from the MongoDB
# official documentation: https://docs.mongodb.com/manual/reference/operator/aggregation/
class MongoPipeline
	super JsonArray

	# Add a stage to the pipeline
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/#stage-operators
	#
	# Each stage is registered as:
	# ~~~json
	# { $<stage>: <json> }
	# ~~~
	fun add_stage(stage: String, json: Serializable): MongoPipeline do
		var obj = new JsonObject
		obj["${stage}"] = json
		add obj
		return self
	end

	# Apply projection
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/project/#pipe._S_project
	#
	# Passes along the documents with only the specified fields to the next stage
	# in the pipeline.
	#
	# ~~~json
	# { $project: { <specifications> } }
	# ~~~
	#
	# The specified fields can be existing fields from the input documents or
	# newly computed fields.
	fun project(projection: JsonObject): MongoPipeline do return add_stage("project", projection)

	# Apply match
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/match/
	#
	# Filters the documents to pass only the documents that match the specified
	# condition(s) to the next pipeline stage.
	#
	# ~~~json
	# { $match: { <query> } }
	# ~~~
	fun match(query: MongoMatch): MongoPipeline do return add_stage("match", query)

	# Apply sort
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/sort/
	#
	# Sorts all input documents and returns them to the pipeline in sorted order.
	#
	# ~~~json
	# { $sort: { <projection> } }
	# ~~~
	fun sort(projection: JsonObject): MongoPipeline do return add_stage("sort", projection)

	# Apply skip
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/skip/
	#
	# Skips over the specified number of documents that pass into the stage and
	# passes the remaining documents to the next stage in the pipeline.
	#
	# ~~~json
	# { $skip: { <number> } }
	# ~~~
	#
	# If `number == null` then no skip stage is generated
	fun skip(number: nullable Int): MongoPipeline do
		if number == null then return self
		return add_stage("skip", number)
	end

	# Apply limit
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/limit/
	#
	# Limits the number of documents passed to the next stage in the pipeline.
	#
	# ~~~json
	# { $limit: { <number> } }
	# ~~~
	#
	# If `number == null` then no limit stage is generated
	fun limit(number: nullable Int): MongoPipeline do
		if number == null then return self
		return add_stage("limit", number)
	end

	# Apply group
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/group/
	#
	# Groups documents by some specified expression and outputs to the next stage
	# a document for each distinct grouping.
	#
	# The output documents contain an `_id` field which contains the distinct
	# group by key.
	#
	# The output documents can also contain computed fields that hold the values
	# of some accumulator expression grouped by the `$group`'s `_id` field.
	# `$group` does not order its output documents.
	#
	# ~~~json
	# { $group: { <group> } }
	# ~~~
	fun group(group: MongoGroup): MongoPipeline do return add_stage("group", group)

	# Apply unwind
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/
	#
	# Deconstructs an array field from the input documents to output a document
	# for each element.
	# Each output document is the input document with the value of the array
	# field replaced by the element.
	#
	# ~~~json
	# { $unwind: <field path> }
	# ~~~
	fun unwind(path: String): MongoPipeline do return add_stage("unwind", path)
end