# Mongo pipeline group stage
#
# https://docs.mongodb.com/manual/reference/operator/aggregation/group/#pipe._S_group
#
# Groups documents by some specified expression and outputs to the next stage a
# document for each distinct grouping.
#
# ~~~
# var group = (new MongoGroup("$game._id")).sum("nitcoins", "$game.nitcoins")
#
# var pipeline = (new MongoPipeline).group(group)
# ~~~
#
# 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.
#
# The `$group` stage has the following prototype form:
#
# ~~~json
# { $group: { _id: <expression>, <field1>: { <accumulator1> : <expression1> }, ... } }
# ~~~
#
# The `_id` field is mandatory; however, you can specify an `_id` value of null
# to calculate accumulated values for all the input documents as a whole.
#
# The remaining computed fields are optional and computed using the `<accumulator>`
# operators.
class MongoGroup
	super JsonObject

	# Group `_id`
	#
	# See `MongoGroup::group`.
	var id: String

	init do self["_id"] = id

	# Add an accumulator
	#
	# Each accumulator is registered as:
	# ~~~json
	# <field>: { <accumulator> : <expression> }
	# ~~~
	private fun acc(name: String, field: String, expression: nullable Serializable): MongoGroup do
		var q = new JsonObject
		q["${name}"] = expression
		self[field] = q
		return self
	end

	# Calculates and returns the sum of numeric values
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/sum/#grp._S_sum
	#
	# ~~~json
	# { $sum: <expression> }
	# ~~~
	#
	# `$sum` ignores non-numeric values.
	fun sum(field: String, expression: Serializable): MongoGroup do
		return acc("sum", field, expression)
	end

	# Returns the average value of the numeric values
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/avg/
	#
	# ~~~json
	# { $avg: <expression> }
	# ~~~
	#
	# `$avg` ignores non-numeric values.
	fun avg(field: String, expression: Serializable): MongoGroup do
		return acc("avg", field, expression)
	end

	# Returns the maximum value
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/max/
	#
	# ~~~json
	# { $max: <expression> }
	# ~~~
	#
	# `$max` compares both value and type, using the specified BSON comparison
	# order for values of different types.
	fun max(field: String, expression: Serializable): MongoGroup do
		return acc("max", field, expression)
	end

	# Returns the minimum value
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/min/
	#
	# ~~~json
	# { $min: <expression> }
	# ~~~
	#
	# `$min` compares both value and type, using the specified BSON comparison
	# order for values of different types.
	fun min(field: String, expression: Serializable): MongoGroup do
		return acc("min", field, expression)
	end

	# Return the first value
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/first/
	#
	# ~~~json
	# { $first: <expression> }
	# ~~~
	#
	# Returns the value that results from applying an expression to the first
	# document in a group of documents that share the same group by key.
	#
	# Only meaningful when documents are in a defined order.
	fun first(field: String, expression: Serializable): MongoGroup do
		return acc("first", field, expression)
	end

	# Return the last value
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/last/
	#
	# ~~~json
	# { $last: <expression> }
	# ~~~
	#
	# Returns the value that results from applying an expression to the last
	# document in a group of documents that share the same group by key.
	#
	# Only meaningful when documents are in a defined order.
	fun last(field: String, expression: Serializable): MongoGroup do
		return acc("last", field, expression)
	end

	# Push to an array
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/push/
	#
	# ~~~json
	# { $push: <expression> }
	# ~~~
	#
	# Returns an array of all values that result from applying an expression to
	# each document in a group of documents that share the same group by key.
	fun push(field: String, expr: Serializable): MongoGroup do
		return acc("push", field, expr)
	end

	# Push to a unique array
	#
	# https://docs.mongodb.com/manual/reference/operator/aggregation/addToSet/
	#
	# ~~~json
	# { $addToSet: <expression> }
	# ~~~
	#
	# Returns an array of all unique values that results from applying an
	# expression to each document in a group of documents that share the same
	# group by key.
	#
	# Order of the elements in the output array is unspecified.
	fun addToSet(field: String, expr: Serializable): MongoGroup do
		return acc("addToSet", field, expr)
	end
end