From 35e2b90ba65176ae2fce6c109c28ab5bbe7e1fe9 Mon Sep 17 00:00:00 2001 From: Hayleigh Thompson Date: Sun, 31 Mar 2024 16:11:31 +0100 Subject: =?UTF-8?q?=F0=9F=94=80=20Create=20a=20guide=20on=20using=20and=20?= =?UTF-8?q?creating=20side=20effects.=20(#93)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * :memo: Explain why managed effects are useful. * :memo: Write a short explainer on pure functions. * :memo: Finish side effects guide. * :wrench: Add side effects guide to generated pages. --- examples/05-http-requests/README.md | 4 ++-- examples/06-custom-effects/README.md | 23 ++++++++++++++--------- 2 files changed, 16 insertions(+), 11 deletions(-) (limited to 'examples') diff --git a/examples/05-http-requests/README.md b/examples/05-http-requests/README.md index 4a118e4..c5fe073 100644 --- a/examples/05-http-requests/README.md +++ b/examples/05-http-requests/README.md @@ -51,8 +51,8 @@ want the Lustre runtime to execute before the next invocation of the `view` function. > **Note**: notice how the type of `view` remains the same. In Lustre, your `view` -> is always a [_pure function_](https://en.wikipedia.org/wiki/Pure_function) that -> takes a model and returns the UI to be rendered: we never perform side effects +> is always a [_pure function_](https://github.com/lustre-labs/lustre/blob/main/pages/hints/pure-functions.md) +> that takes a model and returns the UI to be rendered: we never perform side effects > in the `view` function itself. ## HTTP requests as side effects diff --git a/examples/06-custom-effects/README.md b/examples/06-custom-effects/README.md index 99b90c5..0af61bd 100644 --- a/examples/06-custom-effects/README.md +++ b/examples/06-custom-effects/README.md @@ -7,11 +7,10 @@ this example we'll see how to create effects of our own using Lustre's [`effect.from`](https://hexdocs.pm/lustre/lustre/effect.html#from) function. -Since we use effects to communicate with _external_ systems (like the -browser or the Erlang VM) you'll find creating custom effects usually involves -Gleam's [external -functions](https://tour.gleam.run/everything/#advanced-features-externals). So -be sure to read up on that! +Since we use effects to communicate with _external_ systems (like the browser or +the Erlang VM) you'll find creating custom effects usually involves Gleam's +[external functions](https://tour.gleam.run/everything/#advanced-features-externals). +So be sure to read up on that! > Gleam externals are part of its "foreign function interface", which is why > you'll typically see files with `ffi` in the name - like @@ -20,8 +19,9 @@ be sure to read up on that! ## Accessing Browser Storage In this example, the external system we want to interact with is the browser's -[local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). This way, we can write a message into the text input and it will -still be there when we refresh the page. Handy! +[local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). +This way, we can write a message into the text input and it will still be there +when we refresh the page. Handy! The `view`, `update` and `init` functions should look pretty familiar by now, so let's focus on the functions that generate our custom effects. @@ -58,9 +58,14 @@ Here, our effect is simpler. We tell the gleam compiler we don't need to use the pattern](https://tour.gleam.run/everything/#basics-discard-patterns). Then we write to local storage, and no more work needs to be done. -You may be wondering, why bother using an effect if we aren't also going to update our program with the result? Why not just fire off `do_write_localstorage` directly from the `update` function or a custom event handler? +You may be wondering, why bother using an effect if we aren't also going to update +our program with the result? Why not just fire off `do_write_localstorage` directly +from the `update` function or a custom event handler? -Using effects has many benefits! It lets us implement our `update` and `view` functions as [pure functions](https://en.wikipedia.org/wiki/Pure_function). This makes them easier to test, allows for time-travel debugging, and even opens the door to easily porting them to [server components](https://hexdocs.pm/lustre/lustre/server_component.html). +Using effects has many benefits! It lets us implement our `update` and `view` +functions as [pure functions](https://github.com/lustre-labs/lustre/blob/main/pages/hints/pure-functions.md). +This makes them easier to test, allows for time-travel debugging, and even opens +the door to easily porting them to [server components](https://hexdocs.pm/lustre/lustre/server_component.html). ## Another note on message naming -- cgit v1.2.3