enhancement(remap): Add push and append functions

docs/reference/remap.cue

@@ -49,7 +49,7 @@ remap: {
 
 			arguments: [...#Argument] // Allow for empty list
 			return: [#RemapReturnTypes, ...#RemapReturnTypes]
-			category:    "Check" | "Coerce" | "Encode" | "Enumerate" | "Event" | "Hash" | "IP" | "Map" | "Number" | "Parse" | "Random" | "String" | "Test" | "Timestamp"
+			category:    "Array" | "Check" | "Coerce" | "Encode" | "Enumerate" | "Event" | "Hash" | "IP" | "Map" | "Number" | "Parse" | "Random" | "String" | "Test" | "Timestamp"
 			description: string
 			examples?: [#RemapExample, ...#RemapExample]
 			name: Name

docs/reference/remap/append.cue

@@ -0,0 +1,40 @@
+package metadata
+
+remap: functions: append: {
+	arguments: [
+		{
+			name:        "value"
+			description: "The array"
+			required:    true
+			type: ["array"]
+		},
+		{
+			name:        "items"
+			description: "The items to append"
+			required:    true
+			type: ["array"]
+		},
+	]
+	return: ["array"]
+	category: "Array"
+	description: """
+		Adds each item from an array to the end of another array. The expression
+		`append([1, 2, 3], [4, 5, 6])`, for example, would produce the array `[1, 2, 3, 4, 5, 6]`.
+		The items in both arrays can be of any VRL type.
+		"""
+	examples: [
+		{
+			title: "Mixed array"
+			input: {
+				kitchen_sink: [72.5, false, [1, 2, 3]]
+				items: ["booper", "bopper"]
+			}
+			source: """
+				.kitchen_sink = append(.kitchen_sink, .items)
+				"""
+			output: {
+				kitchen_sink: [72.5, false, [1, 2, 3], "booper", "bopper"]
+			}
+		},
+	]
+}

docs/reference/remap/push.cue

@@ -0,0 +1,58 @@
+package metadata
+
+remap: functions: push: {
+	arguments: [
+		{
+			name:        "value"
+			description: "The array"
+			required:    true
+			type: ["array"]
+		},
+		{
+			name:        "item"
+			description: "The item to push"
+			required:    true
+			type: ["any"]
+		},
+	]
+	return: ["array"]
+	category: "Array"
+	description: """
+		Adds the specified item to the end of an array and returns the resulting array. The item
+		can be of any VRL type and is added even if an item with the same value is already present
+		in the array.
+
+		The `push` function does *not* change the array in place. In this example, the `push`
+		function would return an array with `apple`, `orange`, and `banana`, but the value of
+		`fruits` would be unchanged:
+
+		```js
+		.fruits = ["apple", "orange"]
+		push(.fruits, "banana")
+		.fruits
+		["apple", "orange"]
+		```
+
+		In order to change the value of `fruits`, you would need to store the resulting array in
+		the field:
+
+		```js
+		.fruits = push(.fruits, "banana")
+		```
+		"""
+	examples: [
+		{
+			title: "Mixed array"
+			input: {
+				kitchen_sink: [72.5, false, [1, 2, 3]]
+				item: "booper"
+			}
+			source: """
+				.kitchen_sink = push(.kitchen_sink, .item)
+				"""
+			output: {
+				kitchen_sink: [72.5, false, [1, 2, 3], "booper"]
+			}
+		},
+	]
+}

lib/remap-functions/Cargo.toml

@@ -35,6 +35,7 @@ anyhow = "1"
 [features]
 
 default = [
+    "append",
     "assert",
     "ceil",
     "compact",
@@ -73,6 +74,7 @@ default = [
     "parse_regex_all",
     "parse_timestamp",
     "parse_url",
+    "push",
     "redact",
     "replace",
     "round",
@@ -97,6 +99,7 @@ default = [
     "uuid_v4",
 ]
 
+append = []
 assert = []
 ceil = []
 compact = []
@@ -135,6 +138,7 @@ parse_key_value = ["nom"]
 parse_syslog = ["syslog_loose"]
 parse_timestamp = ["shared/conversion"]
 parse_url = ["url"]
+push = []
 redact = []
 replace = []
 round = []

lib/remap-functions/src/append.rs

@@ -0,0 +1,143 @@
+use remap::prelude::*;
+
+#[derive(Clone, Copy, Debug)]
+pub struct Append;
+
+impl Function for Append {
+    fn identifier(&self) -> &'static str {
+        "append"
+    }
+
+    fn parameters(&self) -> &'static [Parameter] {
+        &[
+            Parameter {
+                keyword: "value",
+                accepts: |v| matches!(v, Value::Array(_)),
+                required: true,
+            },
+            Parameter {
+                keyword: "items",
+                accepts: |v| matches!(v, Value::Array(_)),
+                required: true,
+            },
+        ]
+    }
+
+    fn compile(&self, mut arguments: ArgumentList) -> Result<Box<dyn Expression>> {
+        let value = arguments.required("value")?.boxed();
+        let items = arguments.required("items")?.boxed();
+
+        Ok(Box::new(AppendFn { value, items }))
+    }
+}
+
+#[derive(Debug, Clone)]
+struct AppendFn {
+    value: Box<dyn Expression>,
+    items: Box<dyn Expression>,
+}
+
+impl Expression for AppendFn {
+    fn execute(&self, state: &mut state::Program, object: &mut dyn Object) -> Result<Value> {
+        let mut value = self.value.execute(state, object)?.try_array()?;
+        let mut items = self.items.execute(state, object)?.try_array()?;
+
+        value.append(&mut items);
+
+        Ok(value.into())
+    }
+
+    fn type_def(&self, state: &state::Compiler) -> TypeDef {
+        use value::Kind;
+
+        let items_type = self
+            .items
+            .type_def(state)
+            .fallible_unless(Kind::Array)
+            .with_inner_type(self.items.type_def(state).inner_type_def);
+
+        self.value
+            .type_def(state)
+            .fallible_unless(Kind::Array)
+            .merge(items_type)
+            .with_constraint(Kind::Array)
+            .with_inner_type(
+                self.items
+                    .type_def(state)
+                    .merge(self.value.type_def(state))
+                    .inner_type_def,
+            )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use value::Kind;
+
+    test_type_def![
+        value_array_items_array_infallible {
+            expr: |_| AppendFn {
+                value: array!["foo", "bar", 142].boxed(),
+                items: array!["baq", "baz", true].boxed(),
+            },
+            def: TypeDef {
+                fallible: false,
+                kind: Kind::Array,
+                inner_type_def: Some(TypeDef {
+                    kind: Kind::Boolean | Kind::Bytes | Kind::Integer,
+                    ..Default::default()
+                }.boxed())
+            },
+        }
+
+        value_non_array_fallible {
+            expr: |_| AppendFn {
+                value: lit!(27).boxed(),
+                items: array![1, 2, 3].boxed(),
+            },
+            def: TypeDef {
+                fallible: true,
+                kind: Kind::Array,
+                inner_type_def: Some(TypeDef {
+                    kind: Kind::Integer,
+                    ..Default::default()
+                }.boxed())
+            },
+        }
+
+        items_non_array_fallible {
+            expr: |_| AppendFn {
+                value: array![1, 2, 3].boxed(),
+                items: lit!(27).boxed(),
+            },
+            def: TypeDef {
+                fallible: true,
+                kind: Kind::Array,
+                inner_type_def: Some(TypeDef {
+                    kind: Kind::Integer,
+                    ..Default::default()
+                }.boxed())
+            },
+        }
+    ];
+
+    test_function![
+        append => Append;
+
+        both_arrays_empty {
+            args: func_args![value: array![], items: array![]],
+            want: Ok(value!([])),
+        }
+
+        one_array_empty {
+            args: func_args![value: array![], items: array![1, 2, 3]],
+            want: Ok(value!([1, 2, 3])),
+        }
+
+        neither_array_empty {
+            args: func_args![value: array![1, 2, 3], items: array![4, 5, 6]],
+            want: Ok(value!([1, 2, 3, 4, 5, 6])),
+        }
+    ];
+}

lib/remap-functions/src/lib.rs

@@ -1,5 +1,7 @@
 mod util;
 
+#[cfg(feature = "append")]
+mod append;
 #[cfg(feature = "assert")]
 mod assert;
 #[cfg(feature = "ceil")]
@@ -76,6 +78,8 @@ mod parse_syslog;
 mod parse_timestamp;
 #[cfg(feature = "parse_url")]
 mod parse_url;
+#[cfg(feature = "push")]
+mod push;
 #[cfg(feature = "redact")]
 mod redact;
 #[cfg(feature = "replace")]
@@ -127,6 +131,8 @@ mod uuid_v4;
 pub use crate::md5::Md5;
 #[cfg(feature = "sha1")]
 pub use crate::sha1::Sha1;
+#[cfg(feature = "append")]
+pub use append::Append;
 #[cfg(feature = "assert")]
 pub use assert::Assert;
 #[cfg(feature = "ceil")]
@@ -199,6 +205,8 @@ pub use parse_syslog::ParseSyslog;
 pub use parse_timestamp::ParseTimestamp;
 #[cfg(feature = "parse_url")]
 pub use parse_url::ParseUrl;
+#[cfg(feature = "push")]
+pub use push::Push;
 #[cfg(feature = "match")]
 pub use r#match::Match;
 #[cfg(feature = "redact")]
@@ -246,10 +254,8 @@ pub use uuid_v4::UuidV4;
 
 pub fn all() -> Vec<Box<dyn remap::Function>> {
     vec![
-        #[cfg(feature = "md5")]
-        Box::new(Md5),
-        #[cfg(feature = "sha1")]
-        Box::new(Sha1),
+        #[cfg(feature = "append")]
+        Box::new(Append),
         #[cfg(feature = "assert")]
         Box::new(Assert),
         #[cfg(feature = "ceil")]
@@ -294,6 +300,8 @@ pub fn all() -> Vec<Box<dyn remap::Function>> {
         Box::new(IsNullish),
         #[cfg(feature = "log")]
         Box::new(Log),
+        #[cfg(feature = "md5")]
+        Box::new(Md5),
         #[cfg(feature = "merge")]
         Box::new(Merge),
         #[cfg(feature = "now")]
@@ -322,6 +330,8 @@ pub fn all() -> Vec<Box<dyn remap::Function>> {
         Box::new(ParseTimestamp),
         #[cfg(feature = "parse_url")]
         Box::new(ParseUrl),
+        #[cfg(feature = "push")]
+        Box::new(Push),
         #[cfg(feature = "match")]
         Box::new(Match),
         #[cfg(feature = "redact")]
@@ -330,6 +340,8 @@ pub fn all() -> Vec<Box<dyn remap::Function>> {
         Box::new(Replace),
         #[cfg(feature = "round")]
         Box::new(Round),
+        #[cfg(feature = "sha1")]
+        Box::new(Sha1),
         #[cfg(feature = "sha2")]
         Box::new(Sha2),
         #[cfg(feature = "sha3")]