@platforma-sdk/workflow-tengo 4.5.3 → 4.6.1

package/dist/tengo/lib/pt.expression.lib.tengo

@@ -0,0 +1,905 @@
+ll := import("@platforma-sdk/workflow-tengo:ll")
+maps := import("@platforma-sdk/workflow-tengo:maps")
+slices := import("@platforma-sdk/workflow-tengo:slices")
+
+
+
+_newExpression := undefined
+_newWindowExpression := undefined
+col := undefined
+lit := undefined
+allHorizontal := undefined
+anyHorizontal := undefined
+and := undefined
+or := undefined
+when := undefined
+rank := undefined
+
+
+_isExpression := func(item) {
+	return ll.isMap(item) && ll.methodExists(item, "getExpression")
+}
+
+
+_isAggregation := func(item) {
+	return ll.isMap(item) && ll.methodExists(item, "getAggregation")
+}
+
+
+_mapToExpressionStructList := func(itemsList, stringInterpretation) {
+	if !is_array(itemsList) {
+		itemsList = [itemsList] // Allow single item to be passed
+	}
+	if stringInterpretation != "col" && stringInterpretation != "lit" {
+		ll.panic("Invalid stringInterpretation ('%v') for _mapToExpressionStructList. Must be 'col' or 'lit'.", stringInterpretation)
+		return undefined // Unreachable
+	}
+	return slices.map(itemsList, func(item) {
+		if is_string(item) {
+			if stringInterpretation == "col" {
+				return col(item).getExpression()
+			} else { // Must be "lit" due to the check above
+				return lit(item).getExpression()
+			}
+		} else if _isExpression(item) {
+			return item.getExpression()
+		} else {
+			ll.panic("Invalid item type in list: %T. Must be a string (interpreted as '%s') or an expression object.", item, stringInterpretation)
+			return undefined // Unreachable
+		}
+	})
+}
+
+_mapToSingleExpressionStruct := func(item, stringInterpretation) {
+	if _isExpression(item) {
+		return item.getExpression()
+	} else if is_int(item) || is_float(item) || is_bool(item) { // These are always literals
+		return lit(item).getExpression()
+	} else if is_string(item) {
+		if stringInterpretation == "col" {
+			return col(item).getExpression()
+		} else if stringInterpretation == "lit" {
+			return lit(item).getExpression()
+		} else { // stringInterpretation is undefined or an invalid value
+			ll.panic("String item '%v' provided, but its interpretation as 'col' or 'lit' was not specified or is not applicable in this context. (stringInterpretation: '%v')", item, stringInterpretation)
+			return undefined
+		}
+	} else {
+		ll.panic("Invalid item type: %T. Expected an expression, literal (number, bool, null), or string (with 'col'/'lit' interpretation).", item)
+		return undefined
+	}
+}
+
+
+
+
+
+
+
+_newWindowExpression = func(expression, aggregation, currentAlias) {
+	self := undefined
+	self = ll.toStrict({
+		
+		getExpression: func() {
+			if expression == undefined {
+				ll.panic("Using this operation as a window expression is not allowed. Use it as a group by expression instead. %v", aggregation)
+			}
+			return expression
+		},
+		
+		getAggregation: func() {
+			if aggregation == undefined {
+				ll.panic("Using this operation as a group by expression is not allowed, most probably because you applied .over() to it. %v", expression)
+			}
+			return maps.deepMerge(aggregation, {name: self.getAlias()})
+		},
+		
+		getAlias: func() {
+			if currentAlias == undefined {
+				ll.panic("Alias is not defined for this window expression.")
+			}
+			return currentAlias
+		},
+
+
+
+
+
+
+
+		alias: func(newAlias) {
+			return _newWindowExpression(expression, aggregation, newAlias)
+		},
+
+
+
+
+
+
+		over: func(partitionBy) {
+			ll.assert(is_array(partitionBy) || is_string(partitionBy) || _isExpression(partitionBy), "partitionBy must be an array of strings/expressions or a single string/expression")
+
+			if len(expression.partitionBy) > 0 {
+				ll.warn("partitionBy already set on this window expression, overriding.")
+			}
+
+			newExpression := maps.deepMerge(expression, {
+				partitionBy: _mapToExpressionStructList(partitionBy, "col")
+			})
+
+			return _newWindowExpression(newExpression, undefined, currentAlias)
+		}
+	})
+	return self
+}
+
+
+
+
+
+
+_newExpression = func(expression, currentAlias) {
+	self := undefined // forward declaration
+
+
+	binaryOp := func(opType, other) {
+		rhsExprStruct := undefined
+		if _isExpression(other) {
+			rhsExprStruct = other.getExpression()
+		} else if is_int(other) || is_float(other) || is_bool(other) || is_string(other) {
+			rhsExprStruct = lit(other).getExpression()
+		} else {
+			ll.panic(opType + " expects an expression object or a literal (number, boolean, null) as argument. Got type: %T", other)
+		}
+
+		return _newExpression(
+			{type: opType, lhs: expression, rhs: rhsExprStruct},
+			undefined // Result of operation typically doesn't carry forward alias
+		)
+	}
+
+
+	unaryOp := func(opType) {
+		return _newExpression(
+			{type: opType, value: expression},
+			undefined
+		)
+	}
+
+
+	unaryStrOp := func(opType) {
+		return _newExpression(
+			{type: opType, value: expression},
+			undefined
+		)
+	}
+
+
+	aggOp := func(aggType) {
+		return _newWindowExpression(
+			{type: "aggregate", aggregation: aggType, value: expression, partitionBy: []},
+			{aggregation: aggType, expression: expression},
+			undefined // Alias of underlying col, window expression itself is typically aliased later
+		)
+	}
+
+	aggOpBy := func(aggType, by) {
+		return _newWindowExpression(
+			undefined,
+			{aggregation: aggType, expression: expression, by: _mapToExpressionStructList(by, "col")},
+			undefined // Alias of underlying col, window expression itself is typically aliased later
+		)
+	}
+
+	self = ll.toStrict({
+		
+		getExpression: func() { return expression },
+		
+		getAlias: func() {
+			if currentAlias == undefined {
+				ll.panic("Alias is not defined for this expression.")
+			}
+			return currentAlias
+		},
+
+
+
+
+
+
+		alias: func(newAlias) {
+			return _newExpression(expression, newAlias)
+		},
+
+
+		
+		gt: func(other) { return binaryOp("gt", other) },
+		
+		ge: func(other) { return binaryOp("ge", other) },
+		
+		eq: func(other) { return binaryOp("eq", other) },
+		
+		lt: func(other) { return binaryOp("lt", other) },
+		
+		le: func(other) { return binaryOp("le", other) },
+		
+		neq: func(other) { return binaryOp("neq", other) },
+
+
+		
+		plus: func(other) { return binaryOp("plus", other) },
+		
+		minus: func(other) { return binaryOp("minus", other) },
+		
+		multiply: func(other) { return binaryOp("multiply", other) },
+		
+		truediv: func(other) { return binaryOp("truediv", other) },
+		
+		floordiv: func(other) { return binaryOp("floordiv", other) },
+
+		
+		log10: func() { return unaryOp("log10") },
+		
+		log: func() { return unaryOp("log") },
+		
+		log2: func() { return unaryOp("log2") },
+		
+		abs: func() { return unaryOp("abs") },
+		
+		sqrt: func() { return unaryOp("sqrt") },
+		
+		negate: func() { return unaryOp("negate") },
+		
+		floor: func() { return unaryOp("floor") },
+		
+		round: func() { return unaryOp("round") },
+		
+		ceil: func() { return unaryOp("ceil") },
+
+
+
+
+
+
+
+
+
+
+		cast: func(dtype, ...options) {
+			strictVal := false
+			if len(options) > 0 {
+				ll.assert(len(options) == 1, "cast accepts at most one options map argument.")
+				opsMap := options[0]
+				ll.assert(is_map(opsMap), "Second argument to cast(), if provided, must be an options map.")
+				if !is_undefined(opsMap.strict) {
+					ll.assert(is_bool(opsMap.strict), "strict in options map must be a boolean")
+					strictVal = opsMap.strict
+				}
+			}
+			return _newExpression(
+				{type: "cast", value: expression, dtype: dtype, strict: strictVal},
+				undefined
+			)
+		},
+
+
+		
+		and: func(other) {
+			ll.assert(_isExpression(other), "and method expects an expression object as argument")
+			return allHorizontal(self, other) // Refer to top-level function
+		},
+		
+		or: func(other) {
+			ll.assert(_isExpression(other), "or method expects an expression object as argument")
+			return anyHorizontal(self, other) // Refer to top-level function
+		},
+		
+		not: func() {
+			return unaryOp("not")
+		},
+
+
+		
+		isNull: func() { return unaryOp("is_na") }, // Polars: is_null(), TS: is_na
+		
+		isNotNull: func() { return unaryOp("is_not_na") }, // Polars: is_not_null(), TS: is_not_na
+
+
+		
+		strToUpper: func() { return unaryStrOp("to_upper") },
+		
+		strToLower: func() { return unaryStrOp("to_lower") },
+		
+		strLenChars: func() { return unaryStrOp("str_len")},
+
+
+
+
+
+
+
+		strSlice: func(start, ...lengthArgs) { // Primary method with optional length via varargs
+			ll.assert(is_int(start), "start must be an integer")
+			ll.assert(len(lengthArgs) <= 1, "strSlice expects at most one optional length argument.")
+
+			exprDetails := {type: "substring", value: expression, start: start}
+			if len(lengthArgs) == 1 {
+				lengthVal := lengthArgs[0]
+				ll.assert(is_int(lengthVal), "length, if provided, must be an integer")
+				exprDetails.length = lengthVal
+			}
+
+			return _newExpression(exprDetails, undefined)
+		},
+
+
+
+
+
+
+
+		strSliceEnd: func(start, endIdx) { // Method with end index
+			ll.assert(is_int(start), "start must be an integer")
+			ll.assert(is_int(endIdx), "endIdx must be an integer")
+
+			exprDetails := {type: "substring", value: expression, start: start, end: endIdx}
+			return _newExpression(exprDetails, undefined)
+		},
+
+
+
+
+
+
+
+
+
+
+		strReplace: func(pattern, replacement, ...options) {
+			replaceAllVal := false
+			literalVal := false
+
+			if len(options) > 0 {
+				ll.assert(len(options) == 1, "strReplace accepts at most one options map argument.")
+				opsMap := options[0]
+				ll.assert(is_map(opsMap), "Third argument to strReplace(), if provided, must be an options map.")
+				if !is_undefined(opsMap.replaceAll) {
+					ll.assert(is_bool(opsMap.replaceAll), "replaceAll in options map must be a boolean")
+					replaceAllVal = opsMap.replaceAll
+				}
+				if !is_undefined(opsMap.literal) {
+					ll.assert(is_bool(opsMap.literal), "literal in options map must be a boolean")
+					literalVal = opsMap.literal
+				}
+			}
+
+			return _newExpression({
+				type: "str_replace",
+				value: expression,
+				pattern: _mapToSingleExpressionStruct(pattern, "lit"),
+				replacement: _mapToSingleExpressionStruct(replacement, "lit"),
+				replaceAll: replaceAllVal,
+				literal: literalVal
+			}, undefined)
+		},
+
+
+
+
+
+
+
+
+
+		strDistance: func(string2, metric, returnSimilarity) {
+			ll.assert(_isExpression(string2), "string2 must be an expression object")
+			ll.assert(is_string(metric), "metric must be a string")
+
+			returnSimilarityVal := false
+			if returnSimilarity != undefined {
+				ll.assert(is_bool(returnSimilarity), "returnSimilarity must be a boolean")
+				returnSimilarityVal = returnSimilarity
+			}
+
+			return _newExpression({
+				type: "string_distance",
+				string1: expression,
+				string2: string2.getExpression(),
+				metric: metric,
+				returnSimilarity: returnSimilarityVal
+			}, undefined)
+		},
+
+
+
+
+
+
+
+
+
+		fuzzyFilter: func(patternExpr, metric, bound) {
+			ll.assert(_isExpression(patternExpr), "patternExpr must be an expression object")
+			ll.assert(is_string(metric), "metric must be a string")
+			ll.assert(is_int(bound) || is_float(bound), "bound must be a number")
+
+			return _newExpression({
+				type: "fuzzy_string_filter",
+				value: expression,
+				pattern: patternExpr.getExpression(),
+				metric: metric,
+				bound: bound
+			}, undefined)
+		},
+
+
+
+
+
+
+
+
+
+		hash: func(hashType, encoding, bits) {
+			ll.assert(is_string(hashType), "hashType must be a string")
+			ll.assert(is_string(encoding), "encoding must be a string")
+			if bits != undefined {
+				ll.assert(is_int(bits), "bits must be a number")
+			}
+
+			hashExpr := {
+				type: "hash",
+				value: expression,
+				hashType: hashType,
+				encoding: encoding
+			}
+			if bits != undefined {
+				hashExpr.bits = bits
+			}
+			return _newExpression(hashExpr, undefined)
+		},
+
+
+
+
+
+
+
+		fillNull: func(fillValueExpr) {
+			return _newExpression(
+				{type: "fill_na", input: expression, fillValue: _mapToSingleExpressionStruct(fillValueExpr, "lit")},
+				undefined
+			)
+		},
+
+
+		
+		sum: func() { return aggOp("sum") },
+		
+		mean: func() { return aggOp("mean") },
+		
+		median: func() { return aggOp("median") },
+		
+		min: func() { return aggOp("min") },
+		
+		max: func() { return aggOp("max") },
+		
+		std: func() { return aggOp("std") },
+		
+		var: func() { return aggOp("var") },
+		
+		count: func() { return aggOp("count") },
+		
+		first: func() { return aggOp("first") },
+		
+		last: func() { return aggOp("last") },
+		
+		nUnique: func() { return aggOp("n_unique") },
+
+		
+		maxBy: func(...by) { return aggOpBy("max_by", by) },
+		
+		minBy: func(...by) { return aggOpBy("min_by", by) },
+
+
+
+
+
+
+
+		rank: func(...descendingArgs) {
+			ll.assert(len(descendingArgs) <= 1, "rank method expects at most one optional boolean argument for descending.")
+			descendingVal := false
+			if len(descendingArgs) == 1 {
+				ll.assert(is_bool(descendingArgs[0]), "descending argument for rank must be a boolean")
+				descendingVal = descendingArgs[0]
+			}
+			return _newWindowExpression({
+				type: "rank",
+				orderBy: [expression],
+				partitionBy: [], // To be set by .over()
+				descending: descendingVal
+			}, undefined)
+		},
+
+
+
+
+
+
+
+
+
+
+
+
+		cumsum: func(...args) {
+			additionalOrderByVal := []
+			descendingVal := false
+			actualArgs := args
+
+			if len(args) > 0 && is_map(args[len(args)-1]) && !(_isExpression(args[len(args)-1])) {
+				ops := args[len(args)-1]
+				actualArgs = args[0:len(args)-1]
+				if maps.containsKey(ops, "orderBy") {
+					additionalOrderByVal = _mapToExpressionStructList(ops.orderBy, "col")
+				}
+				if maps.containsKey(ops, "descending") {
+					ll.assert(is_bool(ops.descending), "descending in options map must be a boolean")
+					descendingVal = ops.descending
+				}
+			}
+
+
+			if len(additionalOrderByVal) == 0 && len(actualArgs) > 0 {
+				if is_array(actualArgs[0]) || is_string(actualArgs[0]) || _isExpression(actualArgs[0]) {
+					additionalOrderByVal = _mapToExpressionStructList(actualArgs[0], "col")
+					if len(actualArgs) > 1 && is_bool(actualArgs[1]) {
+						descendingVal = actualArgs[1]
+					}
+				} else if is_bool(actualArgs[0]) && len(additionalOrderByVal) == 0 { // only if not set by ops.orderBy
+					descendingVal = actualArgs[0]
+				} else if len(actualArgs) > 0 {
+					ll.panic("Invalid arguments to cumsum. Expected order expressions or options map.")
+				}
+			}
+
+			return _newWindowExpression({
+				type: "cumsum",
+				value: expression,
+				additionalOrderBy: additionalOrderByVal,
+				partitionBy: [],
+				descending: descendingVal
+			}, undefined, undefined)
+		}
+	})
+	return self
+}
+
+
+
+
+
+
+
+
+
+
+col = func(name) {
+	ll.assert(is_string(name), "col name must be a string")
+	return _newExpression({
+		type: "col",
+		name: name
+	}, name)
+}
+
+
+
+
+
+
+lit = func(value) {
+	return _newExpression({
+		type: "const",
+		value: value
+	}, undefined)
+}
+
+
+
+
+
+
+
+
+concatStr := func(expressions, ...options) {
+	ll.assert(is_array(expressions), "First argument to concatStr must be an array of expressions")
+	ll.assert(len(expressions) > 0, "Expression array for concatStr cannot be empty")
+
+	delimiterVal := "" // Default to empty string
+	if len(options) > 0 {
+		ll.assert(len(options) == 1, "concatStr accepts at most one options map argument.")
+		opsMap := options[0]
+		ll.assert(is_map(opsMap), "Second argument to concatStr(), if provided, must be an options map.")
+		if !is_undefined(opsMap.delimiter) {
+			ll.assert(is_string(opsMap.delimiter), "delimiter in options map must be a string")
+			delimiterVal = opsMap.delimiter
+		}
+	}
+
+	return _newExpression({
+		type: "str_join",
+		operands: _mapToExpressionStructList(expressions, "lit"),
+		delimiter: delimiterVal
+	}, undefined)
+}
+
+
+
+
+
+
+minHorizontal := func(expressions) {
+	ll.assert(is_array(expressions), "Argument to minHorizontal must be an array of expressions")
+	ll.assert(len(expressions) > 0, "Expression array for minHorizontal cannot be empty")
+	return _newExpression({
+		type: "min",
+		operands: _mapToExpressionStructList(expressions, "col")
+	}, undefined)
+}
+
+
+
+
+
+
+maxHorizontal := func(expressions) {
+	ll.assert(is_array(expressions), "Argument to maxHorizontal must be an array of expressions")
+	ll.assert(len(expressions) > 0, "Expression array for maxHorizontal cannot be empty")
+	return _newExpression({
+		type: "max",
+		operands: _mapToExpressionStructList(expressions, "col")
+	}, undefined)
+}
+
+
+
+
+
+
+allHorizontal = func(...args){
+    processedOperands := []
+    for arg in args {
+        exprStruct := undefined
+        if _isExpression(arg) {
+            exprStruct = arg.getExpression()
+        } else if is_string(arg) {
+            exprStruct = col(arg).getExpression()
+        } else {
+            ll.panic("Invalid argument type for allHorizontal: %T. Must be an expression object or string.", arg)
+        }
+
+        if exprStruct.type == "and" && is_array(exprStruct.operands) {
+            processedOperands = append(processedOperands, exprStruct.operands...)
+        } else {
+            processedOperands = append(processedOperands, exprStruct)
+        }
+    }
+    if len(processedOperands) == 0 {
+        ll.panic("allHorizontal requires at least one expression.")
+    }
+    return _newExpression({
+        type: "and",
+        operands: processedOperands
+    }, undefined)
+}
+
+
+
+
+
+
+anyHorizontal = func(...args){
+    processedOperands := []
+    for arg in args {
+        exprStruct := undefined
+        if _isExpression(arg) {
+            exprStruct = arg.getExpression()
+        } else if is_string(arg) {
+            exprStruct = col(arg).getExpression()
+        } else {
+            ll.panic("Invalid argument type for anyHorizontal: %T. Must be an expression object or string.", arg)
+        }
+
+        if exprStruct.type == "or" && is_array(exprStruct.operands) {
+            processedOperands = append(processedOperands, exprStruct.operands...)
+        } else {
+            processedOperands = append(processedOperands, exprStruct)
+        }
+    }
+    if len(processedOperands) == 0 {
+        ll.panic("anyHorizontal requires at least one expression.")
+    }
+    return _newExpression({
+        type: "or",
+        operands: processedOperands
+    }, undefined)
+}
+
+
+
+
+
+
+and = func(...args) {
+	return allHorizontal(args...)
+}
+
+
+
+
+
+
+or = func(...args) {
+	return anyHorizontal(args...)
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+rank = func(orderByExpressions, ...options) {
+	orderByVal := []
+	descendingVal := false
+
+	ll.assert(orderByExpressions != undefined, "rank() requires orderByExpressions (single expression/string or array of them).")
+	orderByVal = _mapToExpressionStructList(orderByExpressions, "col")
+	ll.assert(len(orderByVal) > 0, "rank() 'orderBy' list cannot be empty after processing arguments.")
+
+	if len(options) > 0 {
+		ll.assert(len(options) == 1, "rank() accepts at most one options map argument.")
+		opsMap := options[0]
+		ll.assert(is_map(opsMap), "Second argument to rank(), if provided, must be an options map.")
+		if maps.containsKey(opsMap, "descending") {
+			ll.assert(is_bool(opsMap.descending), "descending in options map must be a boolean")
+			descendingVal = opsMap.descending
+		}
+	}
+
+	return _newWindowExpression({
+		type: "rank",
+		orderBy: orderByVal,
+		partitionBy: [],
+		descending: descendingVal
+	}, undefined, undefined)
+}
+
+
+_newWhenThenBuilder := func(currentClauses, currentWhenExprOrUndefined) {
+	builderSelf := undefined
+	builderSelf = ll.toStrict({
+
+
+
+
+
+		then: func(thenExpr) {
+			ll.assert(currentWhenExprOrUndefined != undefined, ".then() must follow a .when() or initial when() call.")
+			ll.assert(_isExpression(thenExpr), ".then() expects an expression object argument.")
+
+
+			newClauses := maps.clone(currentClauses) // Deep copy existing clauses
+			newClauses = append(newClauses, {
+				when: currentWhenExprOrUndefined.getExpression(),
+				then: thenExpr.getExpression()
+			})
+
+
+			return _newWhenThenBuilder(newClauses, undefined)
+		},
+
+
+
+
+
+
+		when: func(conditionExpr) {
+			ll.assert(currentWhenExprOrUndefined == undefined, ".when() must follow a .then() call.")
+			ll.assert(_isExpression(conditionExpr), ".when() expects an expression object argument.")
+
+
+
+			return _newWhenThenBuilder(currentClauses, conditionExpr)
+		},
+
+
+
+
+
+
+		otherwise: func(otherwiseExpr) {
+			ll.assert(currentWhenExprOrUndefined == undefined, ".otherwise() must follow a .then() call.")
+			ll.assert(len(currentClauses) > 0, "At least one .when().then() clause is required before .otherwise().")
+			ll.assert(_isExpression(otherwiseExpr), ".otherwise() expects an expression object argument.")
+
+
+			finalClauses := maps.clone(currentClauses)
+			return _newExpression({
+				type: "when_then_otherwise",
+				conditions: finalClauses,
+				otherwise: otherwiseExpr.getExpression()
+			}, undefined)
+		}
+	})
+	return builderSelf
+}
+
+
+
+
+
+
+
+
+
+
+
+when = func(conditionExpr) {
+	ll.assert(_isExpression(conditionExpr), "Initial when() expects an expression object argument.")
+	return _newWhenThenBuilder([], conditionExpr)
+}
+
+
+
+
+
+
+
+
+
+
+
+
+rawExp := func(expression, ...alias) {
+	ll.assert(len(alias) <= 1, "rawExpression expects at most one alias argument")
+	aliasVal := undefined
+	if len(alias) > 0 {
+		aliasVal = alias[0]
+	}
+	ll.assert(is_map(expression), "rawExpression expects a map as argument")
+	return _newExpression(expression, aliasVal)
+}
+
+export ll.toStrict({
+	col: col,
+	lit: lit,
+	concatStr: concatStr,
+	minHorizontal: minHorizontal,
+	maxHorizontal: maxHorizontal,
+	allHorizontal: allHorizontal,
+	anyHorizontal: anyHorizontal,
+	and: and, // Top-level alias for allHorizontal
+	or: or,   // Top-level alias for anyHorizontal
+	rank: rank,
+	when: when,
+	rawExp: rawExp,
+	_isExpression: _isExpression,
+	_isAggregation: _isAggregation,
+	_mapToExpressionStructList: _mapToExpressionStructList,
+	_mapToSingleExpressionStruct: _mapToSingleExpressionStruct
+})