@grain/stdlib 0.5.12 → 0.6.0

package/option.gr

@@ -1,19 +1,16 @@
 /**
- * @module Option: Utilities for working with the Option data type.
+ * Utilities for working with the Option data type.
  *
  * The Option type is an enum that represents the possibility of something being present (with the `Some` variant), or not (with the `None` variant). There’s no standalone `null` or `nil` type in Grain; use an Option where you would normally reach for `null` or `nil`.
  *
- * @example import Option from "option"
+ * @example from "option" include Option
  *
  * @example let hasValue = Some(1234) // Creates an Option containing 1234
  * @example let noValue = None // Creates an Option containing nothing
  *
  * @since v0.2.0
  */
-
-/**
- * @section Values: Functions for working with the Option data type.
- */
+module Option
 
 /**
  * Checks if the Option is the `Some` variant.
@@ -23,7 +20,7 @@
  *
  * @since v0.2.0
  */
-export let isSome = option => {
+provide let isSome = option => {
   match (option) {
     Some(_) => true,
     None => false,
@@ -38,7 +35,7 @@ export let isSome = option => {
  *
  * @since v0.2.0
  */
-export let isNone = option => {
+provide let isNone = option => {
   match (option) {
     None => true,
     Some(_) => false,
@@ -54,7 +51,7 @@ export let isNone = option => {
  *
  * @since v0.2.0
  */
-export let contains = (value, option) => {
+provide let contains = (value, option) => {
   match (option) {
     Some(x) => x == value,
     None => false,
@@ -73,7 +70,7 @@ export let contains = (value, option) => {
  *
  * @since v0.2.0
  */
-export let expect = (msg, option) => {
+provide let expect = (msg, option) => {
   match (option) {
     Some(x) => x,
     None => fail msg,
@@ -91,7 +88,7 @@ export let expect = (msg, option) => {
  *
  * @since v0.2.0
  */
-export let unwrap = option => {
+provide let unwrap = option => {
   expect("Could not unwrap None value", option)
 }
 
@@ -104,7 +101,7 @@ export let unwrap = option => {
  *
  * @since v0.2.0
  */
-export let unwrapWithDefault = (default, option) => {
+provide let unwrapWithDefault = (default, option) => {
   match (option) {
     Some(x) => x,
     None => default,
@@ -120,7 +117,7 @@ export let unwrapWithDefault = (default, option) => {
  *
  * @since v0.2.0
  */
-export let map = (fn, option) => {
+provide let map = (fn, option) => {
   match (option) {
     Some(x) => Some(fn(x)),
     None => None,
@@ -138,7 +135,7 @@ export let map = (fn, option) => {
  *
  * @since v0.2.0
  */
-export let mapWithDefault = (fn, default, option) => {
+provide let mapWithDefault = (fn, default, option) => {
   match (option) {
     Some(x) => fn(x),
     None => default,
@@ -157,7 +154,7 @@ export let mapWithDefault = (fn, default, option) => {
  *
  * @since v0.2.0
  */
-export let mapWithDefaultFn = (fn, defaultFn, option) => {
+provide let mapWithDefaultFn = (fn, defaultFn, option) => {
   match (option) {
     Some(x) => fn(x),
     None => defaultFn(),
@@ -173,7 +170,7 @@ export let mapWithDefaultFn = (fn, defaultFn, option) => {
  *
  * @since v0.2.0
  */
-export let flatMap = (fn, option) => {
+provide let flatMap = (fn, option) => {
   match (option) {
     Some(x) => fn(x),
     None => None,
@@ -190,14 +187,13 @@ export let flatMap = (fn, option) => {
  *
  * @since v0.2.0
  */
-export let filter = (fn, option) => {
+provide let filter = (fn, option) => {
   match (option) {
-    Some(x) =>
-      if (fn(x)) {
-        Some(x)
-      } else {
-        None
-      },
+    Some(x) => if (fn(x)) {
+      Some(x)
+    } else {
+      None
+    },
     None => None,
   }
 }
@@ -211,7 +207,7 @@ export let filter = (fn, option) => {
  *
  * @since v0.2.0
  */
-export let zip = (optionA, optionB) => {
+provide let zip = (optionA, optionB) => {
   match ((optionA, optionB)) {
     (Some(a), Some(b)) => Some((a, b)),
     _ => None,
@@ -228,7 +224,7 @@ export let zip = (optionA, optionB) => {
  *
  * @since v0.2.0
  */
-export let zipWith = (fn, optionA, optionB) => {
+provide let zipWith = (fn, optionA, optionB) => {
   match ((optionA, optionB)) {
     (Some(a), Some(b)) => Some(fn(a, b)),
     _ => None,
@@ -245,7 +241,7 @@ export let zipWith = (fn, optionA, optionB) => {
  *
  * @since v0.2.0
  */
-export let flatten = option => {
+provide let flatten = option => {
   match (option) {
     Some(Some(x)) => Some(x),
     _ => None,
@@ -260,7 +256,7 @@ export let flatten = option => {
  *
  * @since v0.2.0
  */
-export let toList = option => {
+provide let toList = option => {
   match (option) {
     Some(x) => [x],
     None => [],
@@ -275,7 +271,7 @@ export let toList = option => {
  *
  * @since v0.2.0
  */
-export let toArray = option => {
+provide let toArray = option => {
   match (option) {
     Some(x) => [> x],
     None => [>],
@@ -291,7 +287,7 @@ export let toArray = option => {
  *
  * @since v0.2.0
  */
-export let toResult = (err, option) => {
+provide let toResult = (err, option) => {
   match (option) {
     Some(a) => Ok(a),
     None => Err(err),
@@ -306,7 +302,7 @@ export let toResult = (err, option) => {
  *
  * @since v0.2.0
  */
-export let sideEffect = (fn, option) => {
+provide let sideEffect = (fn, option) => {
   match (option) {
     Some(x) => fn(x),
     None => void,
@@ -323,7 +319,7 @@ export let sideEffect = (fn, option) => {
  *
  * @since v0.2.0
  */
-export let peek = (fn, option) => {
+provide let peek = (fn, option) => {
   sideEffect(fn, option)
   option
 }
@@ -335,9 +331,10 @@ export let peek = (fn, option) => {
  * @param optionB: The second option
  * @returns The first Option if it is the `Some` variant or the second Option otherwise
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `or`
  */
-export let or = (optionA, optionB) => {
+provide let (||) = (optionA, optionB) => {
   match (optionA) {
     Some(x) => optionA,
     None => optionB,
@@ -351,9 +348,10 @@ export let or = (optionA, optionB) => {
  * @param optionB: The second option
  * @returns The second Option if both are the `Some` variant or the first Option otherwise
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `and`
  */
-export let and = (optionA, optionB) => {
+provide let (&&) = (optionA, optionB) => {
   match (optionA) {
     Some(_) => optionB,
     None => optionA,

package/option.md

@@ -12,7 +12,7 @@ No other changes yet.
 </details>
 
 ```grain
-import Option from "option"
+from "option" include Option
 ```
 
 ```grain
@@ -25,7 +25,7 @@ let noValue = None // Creates an Option containing nothing
 
 ## Values
 
-Functions for working with the Option data type.
+Functions and constants included in the Option module.
 
 ### Option.**isSome**
 
@@ -35,7 +35,7 @@ No other changes yet.
 </details>
 
 ```grain
-isSome : Option<a> -> Bool
+isSome : (option: Option<a>) => Bool
 ```
 
 Checks if the Option is the `Some` variant.
@@ -60,7 +60,7 @@ No other changes yet.
 </details>
 
 ```grain
-isNone : Option<a> -> Bool
+isNone : (option: Option<a>) => Bool
 ```
 
 Checks if the Option is the `None` variant.
@@ -85,7 +85,7 @@ No other changes yet.
 </details>
 
 ```grain
-contains : (a, Option<a>) -> Bool
+contains : (value: a, option: Option<a>) => Bool
 ```
 
 Checks if the Option is the `Some` variant and contains the given value. Uses the generic `==` equality operator.
@@ -111,7 +111,7 @@ No other changes yet.
 </details>
 
 ```grain
-expect : (String, Option<a>) -> a
+expect : (msg: String, option: Option<a>) => a
 ```
 
 Extracts the value inside a `Some` option, otherwise throws an
@@ -144,7 +144,7 @@ No other changes yet.
 </details>
 
 ```grain
-unwrap : Option<a> -> a
+unwrap : (option: Option<a>) => a
 ```
 
 Extracts the value inside a `Some` option, otherwise
@@ -176,7 +176,7 @@ No other changes yet.
 </details>
 
 ```grain
-unwrapWithDefault : (a, Option<a>) -> a
+unwrapWithDefault : (default: a, option: Option<a>) => a
 ```
 
 Extracts the value inside a `Some` option or provide the default value if `None`.
@@ -202,7 +202,7 @@ No other changes yet.
 </details>
 
 ```grain
-map : ((a -> b), Option<a>) -> Option<b>
+map : (fn: (a => b), option: Option<a>) => Option<b>
 ```
 
 If the Option is `Some(value)`, applies the given function to the `value` and wraps the new value in a `Some` variant.
@@ -211,7 +211,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of a `Some` variant|
+|`fn`|`a => b`|The function to call on the value of a `Some` variant|
 |`option`|`Option<a>`|The option to map|
 
 Returns:
@@ -228,7 +228,7 @@ No other changes yet.
 </details>
 
 ```grain
-mapWithDefault : ((a -> b), b, Option<a>) -> b
+mapWithDefault : (fn: (a => b), default: b, option: Option<a>) => b
 ```
 
 If the Option is `Some(value)`, applies the given function to the `value` to produce a new value, otherwise uses the default value.
@@ -238,7 +238,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of a `Some` variant|
+|`fn`|`a => b`|The function to call on the value of a `Some` variant|
 |`default`|`b`|A fallback value for a `None` variant|
 |`option`|`Option<a>`|The option to map|
 
@@ -256,7 +256,8 @@ No other changes yet.
 </details>
 
 ```grain
-mapWithDefaultFn : ((a -> b), (() -> b), Option<a>) -> b
+mapWithDefaultFn :
+  (fn: (a => b), defaultFn: (() => b), option: Option<a>) => b
 ```
 
 If the Option is `Some(value)`, applies the `fn` function to the `value` to produce a new value.
@@ -267,8 +268,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of a `Some` variant|
-|`defaultFn`|`() -> b`|The default function|
+|`fn`|`a => b`|The function to call on the value of a `Some` variant|
+|`defaultFn`|`() => b`|The default function|
 |`option`|`Option<a>`|The option to map|
 
 Returns:
@@ -285,7 +286,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatMap : ((a -> Option<b>), Option<a>) -> Option<b>
+flatMap : (fn: (a => Option<b>), option: Option<a>) => Option<b>
 ```
 
 If the Option is `Some(value)`, applies the given function to the `value` to produce a new Option.
@@ -294,7 +295,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Option<b>`|The function to call on the value of a `Some` variant|
+|`fn`|`a => Option<b>`|The function to call on the value of a `Some` variant|
 |`option`|`Option<a>`|The option to map|
 
 Returns:
@@ -311,7 +312,7 @@ No other changes yet.
 </details>
 
 ```grain
-filter : ((a -> Bool), Option<a>) -> Option<a>
+filter : (fn: (a => Bool), option: Option<a>) => Option<a>
 ```
 
 Converts `Some(value)` variants to `None` variants where the predicate function returns `false`.
@@ -321,7 +322,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The predicate function to indicate if the option should remain `Some`|
+|`fn`|`a => Bool`|The predicate function to indicate if the option should remain `Some`|
 |`option`|`Option<a>`|The option to inspect|
 
 Returns:
@@ -338,7 +339,7 @@ No other changes yet.
 </details>
 
 ```grain
-zip : (Option<a>, Option<b>) -> Option<(a, b)>
+zip : (optionA: Option<a>, optionB: Option<b>) => Option<(a, b)>
 ```
 
 Combine two Options into a single Option containing a tuple of their values.
@@ -364,7 +365,8 @@ No other changes yet.
 </details>
 
 ```grain
-zipWith : (((a, b) -> c), Option<a>, Option<b>) -> Option<c>
+zipWith :
+  (fn: ((a, b) => c), optionA: Option<a>, optionB: Option<b>) => Option<c>
 ```
 
 Combine two Options into a single Option. The new value is produced by applying the given function to both values.
@@ -373,7 +375,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, b) -> c`|The function to generate a new value|
+|`fn`|`(a, b) => c`|The function to generate a new value|
 |`optionA`|`Option<a>`|The first option to combine|
 |`optionB`|`Option<b>`|The second option to combine|
 
@@ -391,7 +393,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatten : Option<Option<a>> -> Option<a>
+flatten : (option: Option<Option<a>>) => Option<a>
 ```
 
 Flattens nested Options.
@@ -422,7 +424,7 @@ No other changes yet.
 </details>
 
 ```grain
-toList : Option<a> -> List<a>
+toList : (option: Option<a>) => List<a>
 ```
 
 Converts an Option to a list with either zero or one item.
@@ -447,7 +449,7 @@ No other changes yet.
 </details>
 
 ```grain
-toArray : Option<a> -> Array<a>
+toArray : (option: Option<a>) => Array<a>
 ```
 
 Converts an Option to an array with either zero or one item.
@@ -472,7 +474,7 @@ No other changes yet.
 </details>
 
 ```grain
-toResult : (a, Option<b>) -> Result<b, a>
+toResult : (err: a, option: Option<b>) => Result<b, a>
 ```
 
 Converts the Option to a Result, using the provided error in case of the `None` variant.
@@ -498,7 +500,7 @@ No other changes yet.
 </details>
 
 ```grain
-sideEffect : ((a -> Void), Option<a>) -> Void
+sideEffect : (fn: (a => Void), option: Option<a>) => Void
 ```
 
 If the Option is `Some(value)`, applies the `fn` function to the `value` without producing a new value.
@@ -507,7 +509,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Void`|The function to call on the value of a `Some` variant|
+|`fn`|`a => Void`|The function to call on the value of a `Some` variant|
 |`option`|`Option<a>`|The option to inspect|
 
 ### Option.**peek**
@@ -518,7 +520,7 @@ No other changes yet.
 </details>
 
 ```grain
-peek : ((a -> Void), Option<a>) -> Option<a>
+peek : (fn: (a => Void), option: Option<a>) => Option<a>
 ```
 
 If the Option is `Some(value)`, applies the `fn` function to the `value` without producing a new value.
@@ -528,7 +530,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Void`|The function to call on the value of a `Some` variant|
+|`fn`|`a => Void`|The function to call on the value of a `Some` variant|
 |`option`|`Option<a>`|The option to inspect|
 
 Returns:
@@ -537,15 +539,22 @@ Returns:
 |----|-----------|
 |`Option<a>`|The unmodified option|
 
-### Option.**or**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+### Option.**(||)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `or`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-or : (Option<a>, Option<a>) -> Option<a>
+(||) : (optionA: Option<a>, optionB: Option<a>) => Option<a>
 ```
 
 Behaves like a logical OR (`||`) where the first Option is only returned if it is the `Some` variant and falling back to the second Option in all other cases.
@@ -563,15 +572,22 @@ Returns:
 |----|-----------|
 |`Option<a>`|The first Option if it is the `Some` variant or the second Option otherwise|
 
-### Option.**and**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+### Option.**(&&)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `and`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-and : (Option<a>, Option<a>) -> Option<a>
+(&&) : (optionA: Option<a>, optionB: Option<a>) => Option<a>
 ```
 
 Behaves like a logical AND (`&&`) where the first Option is only returned if it is the `None` variant and falling back to the second Option Result in all other cases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grain/stdlib",
-  "version": "0.5.12",
+  "version": "0.6.0",
   "description": "The standard library for the Grain language.",
   "license": "MIT",
   "homepage": "https://grain-lang.org",
@@ -18,7 +18,7 @@
     "directory": "stdlib"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=18.15"
   },
   "main": "index.js",
   "files": [