deprecate result.then in favour of result.try

3 files changed, 31 insertions, 10 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d9e4421..d8b5056 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 - The `iterator` module gains the `each` function.
 - Fixed a bug in maps when running on JavaScript where value membership could be
   incorrectly stated in some cases.
+- Deprecated `result.then`.
 
 ## v0.28.0 - 2023-03-26
 
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index e64e96a..35c2d00 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -137,26 +137,36 @@ pub fn flatten(result: Result(Result(a, e), e)) -> Result(a, e) {
 /// ## Examples
 ///
 /// ```gleam
-/// > then(Ok(1), fn(x) { Ok(x + 1) })
+/// > try(Ok(1), fn(x) { Ok(x + 1) })
 /// Ok(2)
 /// ```
 ///
 /// ```gleam
-/// > then(Ok(1), fn(x) { Ok(#("a", x)) })
+/// > try(Ok(1), fn(x) { Ok(#("a", x)) })
 /// Ok(#("a", 1))
 /// ```
 ///
 /// ```gleam
-/// > then(Ok(1), fn(_) { Error("Oh no") })
+/// > try(Ok(1), fn(_) { Error("Oh no") })
 /// Error("Oh no")
 /// ```
 ///
 /// ```gleam
-/// > then(Error(Nil), fn(x) { Ok(x + 1) })
+/// > try(Error(Nil), fn(x) { Ok(x + 1) })
 /// Error(Nil)
 /// ```
 ///
-pub fn then(
+/// `result.try` can be utilized the way
+/// ancient Gleam's `try` used to work:
+///
+/// ```text
+/// // Ancient try
+/// try file = open_file()
+/// // ... can be mimicked like so:
+/// use file <- try(open_file())
+/// ```
+///
+pub fn try(
   result: Result(a, e),
   apply fun: fn(a) -> Result(b, e),
 ) -> Result(b, e) {
@@ -166,6 +176,16 @@ pub fn then(
   }
 }
 
+/// DEPRECATED: Use `result.try` instead,
+/// which has the same signature and does the same thing.
+///
+pub fn then(
+  result: Result(a, e),
+  apply fun: fn(a) -> Result(b, e),
+) -> Result(b, e) {
+  try(result, fun)
+}
+
 /// Extracts the `Ok` value from a result, returning a default value if the result
 /// is an `Error`.
 ///
diff --git a/test/gleam/result_test.gleam b/test/gleam/result_test.gleam
index 9075977..df07a4b 100644
--- a/test/gleam/result_test.gleam
+++ b/test/gleam/result_test.gleam
@@ -59,21 +59,21 @@ pub fn flatten_test() {
   |> should.equal(Error(Error(1)))
 }
 
-pub fn then_test() {
+pub fn try_test() {
   Error(1)
-  |> result.then(fn(x) { Ok(x + 1) })
+  |> result.try(fn(x) { Ok(x + 1) })
   |> should.equal(Error(1))
 
   Ok(1)
-  |> result.then(fn(x) { Ok(x + 1) })
+  |> result.try(fn(x) { Ok(x + 1) })
   |> should.equal(Ok(2))
 
   Ok(1)
-  |> result.then(fn(_) { Ok("type change") })
+  |> result.try(fn(_) { Ok("type change") })
   |> should.equal(Ok("type change"))
 
   Ok(1)
-  |> result.then(fn(_) { Error(1) })
+  |> result.try(fn(_) { Error(1) })
   |> should.equal(Error(1))
 }