DEV Community: Matthew McGarvey

Talk about Crystal & Go Interfaces

Matthew McGarvey — Mon, 15 Dec 2025 22:59:59 +0000

Just a compilation of places where Golang-style interfaces were discussed in the context of Crystal.

https://forum.crystal-lang.org/t/are-inferred-types-frozen-for-crystal-shards-and-the-standard-library/1434

https://forum.crystal-lang.org/t/proposal-interfaces-for-more-generic-code/2103

https://github.com/crystal-lang/crystal/issues/3489

https://forum.crystal-lang.org/t/crystal-has-interfaces-in-java-sense/5105

https://forum.crystal-lang.org/t/rfc-lazy-objects/8460

https://forum.crystal-lang.org/t/structural-typing-vs-interfaces/2086

Converting a nilable generic argument to its non-nil version

Matthew McGarvey — Sat, 07 Jan 2023 18:38:42 +0000

I have struggled a great deal in the past with making generic code that provides functionality to transform a generic argument from a nilable version to a non-nilable version. And I just learned something pretty cool today.

Currently, I am working on a parsing and validation library and want to provide the ability to type-safely move from a nilable string input, to a non-nilable output without directly tying the library to only working with strings are optional inputs.

Here's some simple example code

class Parser(T)
  private getter input : T

  def initialize(@input)
  end

  def not_nil
    if temp = input
      return temp
    else
      raise "input was supposed to be present, but was nil"
    end
  end
end

input = "raw_input".as(String?)
Parser.new(input).not_nil #=> "raw_input" : String

input = nil.as(String?)
Parser.new(input).not_nil #=> runtime exception!

I'm hoping that code example is pretty straightforward. It shows a very basic Parser class that has one method called Parser#not_nil. It returns the non-nilable version of whatever you give it, otherwise it raises an exception if the input actually is nil. In the example, I gave it a nilable string and it returns a non-nilable string. If you are confused as to why I use a temp variable, read more on that here.

One thing to notice about this code example, is that there is no way to express the return type of Parser#not_nil so I am forced to let Crystal infer it. It works as expected but I am not overly fond of leaving off return types. It could easily infer something I didn't expect because there is a bug in the code and it also leaves the documentation lacking.

This code is not very good, though. As I was saying, I'm working on a parsing and validation library so instead of an exception, I'd prefer a way to express this so that it results in a value that I can return to the user.

If your familiar with functional languages (or Rust), I'm talking about implementing a Result type of sorts. A Result type is a data structure that can only be represented as one of two options: an Ok or an Err (or Error to be more explicit). This is implemented generically to where the Result wraps the value contained in either the Ok or Err.
For my purposes, I want the Ok to wrap any value T and the Err to always wrap a String. With Crystal generics you'd write the Result as Result(String, T) where the first item in the parens is the Err type and the second item is the Ok type. To not continue the article with two generics, and because it more closely matches my actual implementation, I will use a Validated(T) type that is essentially equal to a Result(String, T) and has two implementing types of Valid and Invalid.

Here's a real basic implementation of the Validated class.

abstract class Validated(T)
  class Valid(T) < Validated(T)
    getter value : T
    def initialize(@value)
    end
  end

  class Invalid(T) < Validated(T)
    getter value : String
    def initialize(@value)
    end
  end
end

There's very little code here, but it's the basic implementation that matter. I know it looks weird for Validated::Invalid to also have the generic type on it since it only deals with string values (the error messages), but it relates to the code that is missing and it would be more difficult to illustrate what I'm talking about without it. In particular, the code that is missing, involves converting Valid to Invalid and vice-versa. You couldn't do that without keeping up with the valid type on the invalid classes.

FINALLY, let's get to the problem code so that I can show off what I learned today.

class Parser(T)
  private getter input : T

  def initialize(@input)
  end

  def not_nil
    if temp = input
      Validated::Valid.new(temp)
    else
      Validated::Invalid.new("Expected input to be present, but was nil.")
    end
  end
end

input = "raw_input".as(String?)
Parser.new(input).not_nil.value #=> compilation error!

If you actually try to compile this, it fails. It fails because the compiler has no idea what the generic type is supposed to be for the Invalid class. The argument that we pass to create it, is the validation error message after all and we want it to be the not-nil type. We have finally reached the problem that I have run into multiple times and next step has time and again been to open up Discord, go to the Crystal channel, complain, then go do something else while wondering in the back of my mind whether or not I should give up on Crystal and use another language because I figured it was unsolvable. But I decided to do something differently today. I decided to look into where I knew Crystal did something similarly. Specifically, I know that in Crystal you can call [1, 2, nil, 3].compact and get back the array [1, 2, 3] with a type of Array(Int32). The compiler assures that there can't be nil with the type signature. If the core language is able to express a change from T? to T, I should be able to as well. So I opened up the core codebase and found that Array#compact delegates to Enumerable#compact_map. Here's the code for that method

def compact_map(& : T -> _)
  ary = [] of typeof((yield Enumerable.element_type(self)).not_nil!)
  each do |e|
    v = yield e
    unless v.nil?
      ary << v
    end
  end
  ary
end

This took me a while to understand. It's calling this Enumerable.element_type function and yielding with it and I still don't understand that part, but the important piece is that it's calling typeof((...).not_nil!).

🤯🤯🤯🤯

I had no idea that you could call not_nil! inside typeof without raising an error if the thing you are calling it on is actually nil.

x = nil.as(String?)
typeof(x.not_nil!) #=> String : Class

🤯🤯🤯🤯

So Enumerable#compact_map is able to let the compiler infer the return type by creating the return array with the non-nilable type.

Now for the grand reveal of how I was able to use this in my own code.

class Parser(T)
  private getter input : T

  def initialize(@input)
  end

  def not_nil
    if temp = input
      Validated::Valid.new(temp)
    else
      Validated::Invalid(typeof(input.not_nil!)).new("Expected input to be present, but was nil.")
    end
  end
end

input = "raw_input".as(String?)
Parser.new(input).not_nil.value #=> "raw_input" : String

input = nil.as(String?)
Parser.new(input).not_nil.value #=> "Expected input to be present, but was nil." : String

Hey!! Look at that!! It works!!

So while I use the temp to allow the if-block to narrow the type down, I need to avoid doing that with the typeof((...).not_nil!) trick so that it remains the original type. The compiler now understands that, while it doesn't have a reference to the not-nil value, Invalid has the same generic type as Valid.

I love this, and I'm going to run with it in my code that does a whole lot more that's outside the scope of this post but I will hopefully have it ready soon to share. I hope this will be helpful to someone else and that your mind is as blown as mine is.

By the way, I have noticed the core team refers to this hack in generic terms as T -> T! and would love for this to be implemented in Crystal without the hacks.

Crystal View Context

Matthew McGarvey — Fri, 25 Mar 2022 03:27:39 +0000

This article is meant to be more of a public note than anything.

I have found myself wondering why several Ruby gems that allowed you to create HTML in plain ruby still required you to have separate files instead of putting them in plain ol' ruby objects. As I'm working on my Crystal implementation of Roda, it finally occurred to me why. It's to be able to manage scope. All of those languages didn't require calling the methods on anything, the methods were just there. It's because the file is run in the context of a class that provides those messages.

Now why did I put Crystal in the title but only talk about Ruby? Well, we have a context issue in Crystal and we've struggled with it a fair amount. There's ECR which does some fancy macro things but ultimately just copy/pastes the ECR file directly into the place where ECR.render is called. Over in Lucky, though, we make HTML through Crystal code and they are separate objects. One of the pains of that is passing in the HTTP context for things like link helpers and CSRF tokens. Buuuut, if the Crystal code was in a separate, non-Crystal file, we could still have all the functionality of Lucky's html building, but with the context control of ECR.

I am sticking with ECR right now in my library, but I might experiment more in the future. One advantage of this over ECR is that I don't have to do any pre-processing to pull out the fancy tags for embedding crystal into regular HTML.

GitHub Pull Requests with Screenshots Tip

Matthew McGarvey — Tue, 29 Jun 2021 18:51:10 +0000

When you're making a pull request in GitHub and want to include screenshots in the description, you might be tempted to just throw the screenshots in with headings. I urge you, though, not to do that! Those screenshots take up a lot of room and there is a better way!

Dropdowns

Dropdowns are truly the better way to add images to pull requests. By default they can be ignored and can be expanded if you want to look at them.

Here's a picture of a pull request description without using dropdowns. Notice how much room is taken up. I had to zoom out to 60% just to get it all on my screen!

Now here's a picture using dropdowns. It's so much simpler.

Syntax

I used to always google "github markdown dropdown" and used this link.

They are created using markdown like this:

<details>
<summary>How do I dropdown?</summary>
<br>
This is how you dropdown.
</details>

Saved Replies

Just so that you and I don't have to remember this article or that GitHub gist in the future, you can make it easy by creating a saved reply. Those are accessed in the bar above the text area when creating a pull request description.

You can create a new saved reply through that button and make a dropdown saved reply. That's going to save me a bunch of time!

Crystal - Plugin Pattern

Matthew McGarvey — Tue, 12 Jan 2021 05:32:31 +0000

The Inspiration

I recently added Lucky to TechEmpower benchmarks and was looking around for articles/videos about what other frameworks are doing to perform so well. I came across this really good talk by Jeremy Evans called Optimization Techniques Used by the Benchmark Winners. Instead of carrying away a list of changes to make to Lucky, I came away with a fascination for how he designed his framework, Roda. Specifically, I loved the idea of entirely using plugins to extend and add behavior. If you ever get the chance to look at the source code for the framework you'll notice that the classes are almost empty. All the behavior is added in through plugins. I really wanted to see if this was possible in Crystal.

The Challenge

In Roda, when you add a plugin, it includes and extends nested modules.

plugin CustomRender

# becomes...

include(CustomRender::InstanceMethods) if defined?(CustomRender::InstanceMethods)
extend(CustomRender::ClassMethods) if defined?(CustomRender::ClassMethods)
# and more...

It also adds modules to the request and response objects but that is enough code to convey the challenges with converting it to Crystal:

modules can't be included at runtime
there is no defined? method

The Solution

While Crystal can't include modules at runtime, we do have macros that can accomplish much of the same things. The original idea was to just have a macro like:

macro plugin(type)
  include {{ type }}::InstanceMethods
  extend {{ type }}::ClassMethods
end

The only problem with that is the conditional aspect that Roda has. If the plugin doesn't need to add any class methods it shouldn't have to define that module and the framework should be able to handle it. The only solution I've found is to delegate to a second macro.

macro extend_self(instance_methods, class_methods)
  {% if ims = instance_methods.resolve? %}
    include {{ ims }}
  {% end %}
  {% if cms = class_methods.resolve? %}
    extend {{ cms }}
  {% end %}
end

macro plugin(type)
  extend_self({{ "#{type}::InstanceMethods".id }}, {{ "#{type}::ClassMethods".id }})
end

The reason for the second macro is that I need the Path#resolve? method in order to check if the module is defined and this is the only way I know to dynamically create a Path object in a macro. Please let me know if you can think of a better way to do it!

plugin CustomRender

# becomes...

extend_self(CustomerRender::InstanceMethods, CustomRender::ClassMethods)

# becomes...

include CustomerRender::InstanceMethods
extend CustomRender::ClassMethods

I haven't gotten to actually converting Roda over to Crystal yet but I hope to. I also hope to make more posts about it along the way.

Crystal Spec CLI Gotcha (--help)

Matthew McGarvey — Fri, 01 Jan 2021 00:48:57 +0000

When calling crystal spec --help you actually get the spec description but the options list of the crystal CLI instead of the specs.

❯ crystal spec --help
Usage: crystal spec [options] [files]

Options:
    -d, --debug                      Add full symbolic debug info
    --no-debug                       Skip any symbolic debug info
    -D FLAG, --define FLAG           Define a compile-time flag
    --error-trace                    Show full error trace
    --release                        Compile in release mode
    -s, --stats                      Enable statistics output
    -p, --progress                   Enable progress output
    -t, --time                       Enable execution time output
    -h, --help                       Show this message
    --no-color                       Disable colored output
    --warnings all|none              Which warnings detect. (default: all)
    --error-on-warnings              Treat warnings as errors.
    --exclude-warnings <path>        Exclude warnings from path (default: lib)

To get the options list for specs, run crystal spec -- --help.

❯ crystal spec -- --help
crystal spec runner
    -e , --example STRING            run examples whose full nested names include STRING
    -l , --line LINE                 run examples whose line matches LINE
    -p, --profile                    Print the 10 slowest specs
    --fail-fast                      abort the run on first failure
    --location file:line             run example at line 'line' in file 'file', multiple allowed
    --tag TAG                        run examples with the specified TAG, or exclude examples by adding ~ before the TAG.
    --order MODE                     run examples in random order by passing MODE as 'random' or to a specific seed by passing MODE as the seed value
    --junit_output OUTPUT_PATH       generate JUnit XML output within the given OUTPUT_PATH
    -h, --help                       show this help
    -v, --verbose                    verbose output
    --tap                            Generate TAP output (Test Anything Protocol)
    --no-color                       Disable colored output

Maybe this was obvious to everyone but I had no idea until I was told about it.

Custom Spec Expectations

Matthew McGarvey — Wed, 30 Dec 2020 20:24:12 +0000

There are two parts to custom expectations:

The class that performs the expectation logic
The method used in specs that initializes and returns the class

Custom Expectation Class

Methods to implement:

#match - performs the expectation logic
#failure_message - the error message when #match fails and #should was used
#negative_failure_message - the error message when #match fails and #should_not was used

All three of these methods take in one argument, the object that #should or #should_not was called on. So if the expectation was result.should be_nil, those methods would take result as an argument. Here's an example that checks if an HTTP::Request has the expected path:

class HavePathExpectation
  def initialize(@expected_path : String)
  end

  def match(request : HTTP::Request)
    request.path == @expected_path
  end

  def failure_message(request : HTTP::Request)
    <<-MSG
    Expected request to have path: #{@expected_path}
                           actual: #{request.path}
    MSG
  end

  def negative_failure_message(request : HTTP::Request)
    "Expected request to not have path: #{request.path}"
  end
end

Custom Expectation Method

These are global methods and are the expectations that users will call. Libraries should put them in a single module for users to include in their spec_helper.cr. To use the class from above:

module MyLibrary::Expectations
  def have_path(expected_path : String)
    HavePathExpectation.new(expected_path)
  end
end

# in spec_helper.cr
include MyLibrary::Expectations

# in a spec
request.should have_path("/users")

All the method does is take in any arguments if they are necessary and returns the initialized expectation class.

Types are really useful to specify with custom expectations. The types on the class method parameters limits when the expectations can be used. The class above is limited to only when #should is called on an HTTP::Request and the expectation method limits what can be passed in as the expected value.

Fanciness

I haven't had an opportunity to implement it yet, but since #should only expects some object it can call those three methods on, you don't have to stop at just the one expectation method. Using method chaining where the methods always return self at the end, you can make a really pleasant expectation DSL. Imagine, instead of a specific expectation class about the request path, it was a general request validation class that could be updated to check different parts of the request.

class RequestExpectation
  @path : String?
  @request_method : String?
  @errors = [] of String

  def match(request : HTTP::Request)
    if expected_path = @path && request.path != expected_path
      @errors << "Expected path to be #{expected_path} but was #{request.path}"
      return false 
    end

    if expected_method = @request_method && request.method != expected_method
      @errors << "Expected request method to be #{expected_method} but was #{request.method}"
      return false
    end

    true
  end

  def with_path(expected_path : String)
    @path = expected_path
    self
  end

  def with_method(expected_method : String)
    @request_method = expected_method
    self
  end

  def failure_message(request : HTTP::Request)
    # not implemented for brevity
  end

  def negative_failure_message(request : HTTP::Request)
    # not implemented for brevity
  end
end

and then the expectations would need to be updated accordingly

module MyLibrary::Expectations
  def have_path(expected_path : String)
    HavePathExpectation.new.with_path(expected_path)
  end

  def have_method(expected_method : String)
    HavePathExpectation.new.with_method(expected_method)
  end
end

Now you can compose the expectation to validate the pieces you need.

request.should have_method("GET")

request.should have_path("/users/123").with_method("DELETE")

This might not have been the best example because the expectations are very specific but imagine having a broader expectation with helper methods after to provide more specifics.

EmailClient.should have_sent_emails
  .to("foo@example.com")
  .with_subject("Subscription Invoice")
  .with_cc("boss@example.com")
  .with_email_template(SubscriptionInvoice)

It takes a bit of work but I think it's pretty cool!

Macro Tips: Avoid nesting macros if possible

Matthew McGarvey — Wed, 30 Dec 2020 05:46:01 +0000

One issue that has come up recently is that error output for compilations errors only contains the place the error occurred and the place that called the offending code. It might not sound like a problem, but pair that with macros and it will all become clear. It's easiest to show, so here's some code that produces a compilation error:

macro compilation_error(arg)
  1 < {{ arg }}
end

puts compilation_error("asdf")

and the compilation error looks like:

Showing last frame. Use --error-trace for full trace.

There was a problem expanding macro 'compilation_error'

Code in temp.cr:10:6

 10 | puts compilation_error("asdf")
           ^
Called macro defined in temp.cr:2:1

 2 | macro compilation_error(arg)

Which expanded to:

 > 1 | 1 < "asdf"
         ^
Error: no overload matches 'Int32#<' with type String

Overloads are:
 ...cut for brevity

The error output for this compilation error is kind of nice. It states there's an issue and then the very first code reference is to where the macro was called. The next code reference points towards the macro-generated code that caused the error. If the user is not familiar with what code is generated by the macro they are using (and maybe they don't even know it's a macro), the first code reference is often way more helpful than when it dives into the macro code.

Now, let's change how the macro works just a little bit and see what happens to the error output.

macro inner_compilation_error(arg)
  1 < {{ arg }}
end

macro compilation_error(arg)
  inner_compilation_error({{ arg }})
end

puts compilation_error("asdf")

And the new error output

Showing last frame. Use --error-trace for full trace.

There was a problem expanding macro 'inner_compilation_error'

Code in macro 'compilation_error'

 1 | inner_compilation_error("asdf")
     ^
Called macro defined in eval:1:1

Which expanded to:

 > 1 | 1 < "asdf"
         ^
Error: no overload matches 'Int32#<' with type String

Overloads are:
 ...cut for brevity

Can you notice the difference? Where in the error output does it point towards where the macro was called? The answer, it doesn't.

The change to the code was adding another macro method that the original macro method now delegates to. This is very common when making macros since the code generation can become complicated. The downside is that error output only shows the compilation error and the code that called it, and in this case it means that it never makes it out of the macro code. Not so bad when you manage and call the macro, annoying and confusing when you are calling macros provided to you from libraries. At least in this code example you can kind of reference that the error is because you passed in a string, but what if the argument passed into the top-level macro is augmented in some way? What if the string is split into an array? I believe the error output becomes confusing and of little value. (I've written this article without talking about --error-trace because I believe that errors should be helpful without it)

Story from Lucky-land

In Lucky we generate URL helper methods to make it easier to create links in HTML, and we do this using macros called when users set up their actions (what we call controllers in a traditional MVC architecture). A common request for help in our Discord is to help figure out where users went wrong with their action setup. They copy and paste their action code and provide a picture of the stack-trace that looks something like this

You'll notice that the image of the stack-trace looks a little like the second example I laid out above. It talks about an error but the code references it points at are all in macro code. That's why user's end up staring at their action and are forced to ask for help. The awful thing about it is that the error isn't in their action at all. The user spends the most time staring at the action to see the error, but anyone who tries to help also has to spend time carefully reading the code. The annoying thing is that the real problem was with their usage of the generated URL helpers I mentioned, and not with the action implementation at all.

Because I had experienced this issue myself and had helped people out with this often, I really wanted to figure out how to get the usage site (where they originally called into macro code) into the error output. Without going into the code, I looked at the macro and saw something very similar to the code example above where the main macro delegated to another but nowhere else was this second macro called. Moving the second macro code into the first was the solution and now the usage site shows up in the error output!

Here's the pull request that made the change if you want to reference it

Inline render_html_page to change compilation error #1373

matthewmcgarvey posted on Dec 28, 2020

Purpose

No connected issue

Description

Before

After

Notice in the "Before" that the first code reference was a macro and not the usage site that caused the error. By removing the render_html_page we actually see the usage site in the error which will help people track down issues.

That macro was extracted here but you'll notice that this PR achieves the same level of DRY-ness without the separate macro.

Checklist

[ ] - An issue already exists detailing the issue/or feature request that this PR fixes
[x] - All specs are formatted with crystal tool format spec src
[x] - Inline documentation has been added and/or updated
[x] - Lucky builds on docker with ./script/setup
[x] - All builds and specs pass on docker with ./script/test

View on GitHub

LuckyFlow - The Basics

Matthew McGarvey — Mon, 28 Dec 2020 06:02:40 +0000

LuckyFlow is the browser-based testing library for Lucky. It uses headless Chrome to test your web-app as close to actual users would as possible.

Navigation

# go to /users
visit Users::Index

# go to /users/:user_id with user credentials
visit Users::Show.with(current_user.id), as: current_user

Finding Elements on Page

# `el` supports normal CSS selectors
el(".class")
el("#id")

You can also select elements by passing in text. This is helpful when there are multiple elements with the same selector but they are distinguished by their text.

el(".list-item", text: "Item 123")

Keep in mind that el is lazy so an error won't happen if you try to find an element that doesn't exist until you try to use the result.

Note: `flow-id`

Beyond CSS selectors, LuckyFlow and el support a custom attribute called flow-id. This is to allow selecting elements to be more specific and less susceptible to test breakage.

# notice the usage of `@` to reference a `flow-id`
el("@custom-flow-id")

Clicking Links

There are two ways to click an element. You can select it using el or pass a CSS selector directly to click.

el("@my-link").click
click("@my-link")

Filling Out Forms

LuckyFlow provides a nice integration with Avram, Lucky's ORM, to make filling out forms easy.

fill_form CreateUser,
  name: "John Doe",
  email: "john@example.com"

Assertions

# expect the element to be displayed on the page
el("@custom-flow-id).should be_on_page

# expect the current path to match
# self is weird here because I have been showing
# all the code as if it was inside a Flow
# (more about that in a future post)
self.should have_current_path(Users::Index)

el("@custom-flow-id).should have_text("Hello, world!")

In future posts, I want to go more in-depth on LuckyFlow and show how I use it to write clean specs.

Flash Messages with Lucky

Matthew McGarvey — Sat, 26 Dec 2020 05:56:29 +0000

There's often a need to show users some dynamic message based on some process of the app or action on their part. The most common scenario is usually around submitting forms. The user is trying to sign in to the app but use an incorrect password so the app sends them an error flash telling them to please try again. They subsequently sign in successfullyi so the app sends them a happy success flash welcoming them back 🌈🦄. But how might you do this in your Lucky app? Let's check it out.

Adding a flash message

Going back to the form scenario, to add a flash message based on the outcome of a save operation it might look like:

class Users::Create < BrowserAction
  post "/user" do
    SaveUser.create(params) do |op, user|
      if op.saved?
        flash.success = "User created!"
        redirect to: Users::Show.with(user.id)
      else
        flash.failure = "Something went wrong..."
        html Users::NewPage, operation: op
      end
    end
  end
end

This action is to create a new User and renders a success flash message if it worked and a failure message if it failed to create the user. Besides flash.success and flash.failure, there is also flash.info for general information to pass to the user. If you need a custom flash key and message you can call flash.set(:some_key, "some value").

Once a flash is set, it is accessible for the rest of the request or in the next one. The flash will be removed after that. It's so that, as in this example action, flashes can survive redirects. If you need the flash to survive longer than that, I will explain how to do it later in the post.

Accessing flash messages

While flashes are a way to pass information across stateless requests, the most common use for them is for rendering HTML to notify users of events. Here's an example of something you might have in a component or a page to display flash messages if their are any:

flash.each do |type, message|
  div class: "alert alert-#{type}", role: "alert" do
    para message
  end
end

This iterates over every plash and displays the message to the user. When they refresh the page it will be gone. This is a nice and simple way to send the user short-lived informational messages. Much like we set them above, flashes can also be accessed individually. You can call flash.get?(:any_key) to get a message if there is one. There is also helpers for the predefined message types so flash.info? will work as well. This is useful if you display different flash message types in different ways.

Other Usefulness

Persisting flash messages for multiple requests

Flash messages are only kept for the request they were set in and the next one, but sometimes you need to persist them for longer. To do this, you can call flash.keep to persist any flash messages given to the current request onto future ones. The most common use-case for this is when redirecting requests, but Lucky already handles this scenario for you.

It's important to remember to only call flash.keep when you know you need to pass flash messages onto future requests. Calling it outside this scenario can lead to flash messages appearing to the user multiple times.

Clearing flash messages

I think the heading says enough. Just call flash.clear to immediately remove all existing flash messages.

One Warning

It's important to remember that flash messages are accessible in the request they are set in AND the next one. If you render all flash messages in HTML if there are any, setting flash messages on requests that don't redirect can also lead to them appearing to the user multiple times. For example, if you set a flash message on the user's profile page, they will see the flash message and then it will render again if they go to the home page.

Unfortunately, there's not a solution for this problem right now but keep an eye on this issue to know when we have a working solution.

Flash messages are always displayed for 2 requests #1271

odinhb posted on Sep 26, 2020

I'm having trouble with the flash messages.

I'm doing something similar to the generated browser sign_in endpoint:

get "/some_endpoint" do
  flash.info = "here is a message"
  html SomePage
end

It doesn't matter if I use flash.keep or not. The flash message shows up in the response (as it should), but it doesn't go away if I refresh or trigger another request.

I would expect it to disappear in the response to the second request.

Lucky version: 0.24.0

I noticed that in Shared::FlashMessages we loop over flash keys using #each, but in the implementation of Lucky::FlashStore #each is delegated to #all, which means we are looping over both the @next messages and the @now messages.

I also noticed that in Lucky::FlashStore#set we modify @next instead of @now, meaning there is no difference between calling flash.keep or not, as @next gets put in a cookie (i assume thats why #to_json is there), sent back by the client and put back in @now for the next response, essentially always being "kept" and thus being displayed in both responses.

I appended a monkey-patch in src/app.cr which looks like this:

class Lucky::FlashStore
  def set(key : Key, value : String) : String
    @now[key.to_s] = value
  end
end

And it seems to work fine now, but this is not the correct implementation, is it? I'm finding the implications of the implementation a bit hard to hold in my head.

View on GitHub

Macro Tips: Method usage compilation errors

Matthew McGarvey — Sat, 26 Dec 2020 04:22:49 +0000

One cool feature of Crystal macros that I forget about is that they don't always have to be defined in a macro method. Where I've seen this be helpful is when you want to define a compile-time error in a method.

One way to think about it is, say you have a method called destroy and people keep mentioning that they keep forgetting and accidentally trying to call delete. Sometimes Crystal gives you a recommendation of the method it thinks you wanted but that is not always the case. To be helpful to users, you could use macros to provide a better error.

class MyLibrary
  def destroy
    # pure destruction
  end

  def delete
    {% raise "Woops! Did you mean to call destroy instead?" %}
  end
end

my_library = MyLibrary.new
my_library.delete #=> Helpful compilation error!

It's a nice way to provide help to users who make mistakes from time to time. We use this in Lucky's ORM, Avram, to help users avoid making mistakes that would otherwise produce hard to understand compilation errors, or, even worse, runtime errors 🙀. One example is that in Avram::Model you define a "belongs to" association by writing belongs_to user : User but in a migration you can add a column with a foreign key relationship to a different table by writing add_belongs_to user : User. Out of habit, I have accidentally used belongs_to instead of add_belongs_to in a migration and didn't get an understandable error. It took me several minutes to track it down and I felt dumb for making the mistake. Because of that experience, we added a compilation error using macros to catch that and point users towards the solution. Here's the code in Avram that can be found on GitHub here (just a note that this is in a macro def but the same thing can be done in a regular def as well).

macro belongs_to(type_declaration, *args, **named_args)
  {% raise <<-ERROR
    Unexpected call to `belongs_to` in a migration.
    Found in #{type_declaration.filename.id}:#{type_declaration.line_number}:#{type_declaration.column_number}.
    Did you mean to use 'add_belongs_to'?
    'add_belongs_to #{type_declaration}, ...'
    ERROR
  %}
end

Caveat

One problem we've had with this recently, though, is that we implemented this in the base method of a class that would be inherited and a module dynamically overrides it to provide the expected functionality. Because we were replacing existing code, some users were calling super in their method expecting to get the base functionality and were instead getting a compilation error. This is not a knock of the macro usage, just a note that it isn't always the perfect choice.

Macro Tips: TypeDeclaration

Matthew McGarvey — Tue, 08 Dec 2020 01:18:28 +0000

When working with macros, you might have one that allows specifying a name, type, and an optional default value.

It might look something like this

param query : String = "default query"

The code for the macro will take in one parameter and that parameter will be a TypeDeclaration.

macro param(type_decl)
  # ...
end

If you imagine that this param macro is for a web framework and used to define the query params for an endpoint, it makes sense that it would raise an error if the query is not nilable and no default value is given in the method that it defines.

The code for that could be (forgive me for this mess)

macro param(type_decl)
  def {{ type_decl.var }} : {{ type_decl.type }}
    {% is_nilable_type = type_decl.type.is_a?(Union) %}

    val = params.get?(:{{ type_declaration.var.id }})

    return val unless val.nil?

    {% if is_nilable_type %}
      {{ type_declaration.value || nil }}
    {% else %}
      default_or_nil = {{ type_declaration.value || nil }}
      if default_or_nil.nil?
        raise MissingParamError.new("{{ type_declaration.var.id }}")
      else
        default_or_nil
      end
    {% end %}
    end
  end
end

Can you see the problem with this?

What if a param was this instead param show_deleted : Bool = false?

The problem is the line default_or_nil = {{ type_declaration.value || nil }}. It means that any time the value is not provided, it uses the default which is false and is obviously falsey which means that default_or_nil evaluates to nil and ends up raising the error.

The solution is to check if the value is a Nop instead of checking the truthiness of the default value since value is a Nop when it isn't defined.

Instead of

default_or_nil = {{ type_declaration.value || nil }}

it should be

default_or_nil = {{ type_declaration.value.is_a?(Nop) ? nil : type_declaration.value }}

Here's the relevant PR for the fix made in Lucky.