DEV Community: Daniel Little

Don't Ignore Your Functions

Daniel Little — Mon, 05 Oct 2020 10:31:00 +0000

Ignoring return values can often be dangerous in subtle ways but you may be so used to doing it that you don't even notice anymore. It's likely that at some point you have run into an issue caused by forgetting to use the return value of a function. It's even more likely you throw away the return values of functions without thinking too much about it. Most of the time there's no real impact of doing so, and if there is it's certainly not immediate. But if you find yourself doing this often it is important to ask why. Presumably, the function is returning this value for a reason? Is there something wrong with the design of the API, or are you missing something important?

Adding to a date doesn't change it

Have you ever seen code like this?

var date = new DateTime(2000, 01, 01);

date.AddYears(1);
Console.WriteLine($"{date.ToShortDateString()}");

It looks pretty straightforward, but there's a bug in this code. If you're familiar with the dotnet DateTime API it might be an obvious one but it can be subtle and confusing if you've never used it before.

The issue is that when you call AddYears it doesn't modify the date, instead it returns a brand new date. Therefore when WriteLine is called the value will still say 2000/01/01 instead of 2001/01/01 like you may have expected.

To get this to work correctly you'd have to capture the new date by assigning the new value to the date variable, like so.

var date = new DateTime(2000, 01, 01);

date = date.AddYears(1);
Console.WriteLine($"{date.ToShortDateString()}");

So why does AddYears return a new date object instead of adding a year to the existing date? It does this because date is an immutable type. This means that once you create a date you can never modify or change it, in any way. If you need a different date you'll always need to create a new one.

Immutability itself is a very useful technique because it can help manage complexity due to limiting the possibilities you have to consider; there is only one way to change the date, replace it. However, issues like the example above can be hard to find if you're not looking for them. Wouldn't it be great if the C# compiler could detect issues like this and prevent you from making the mistake in the first place!

Async and you forgot to await

Let's look at a different problem for a moment. Say you had an async function which calls out to two async functions but you forget to await one of them.

async Task<ActionResult<Resource>> GetResource(string id) {

    AuditRequestAsync(id); // Forgot to await this, oops

    return await LoadResourceAsync(id);
}

In this case, you'll get a warning from the C# compiler telling you that there might be a missing await. This is fantastic because the majority of the time this is almost certainly a bug. However, depending on how closely you monitor your warning, it's still possible to compile the app with the default compiler options. But what happens if we have the same function but without the async keyword, like so.

Task<ActionResult<Resource>> GetResource(string id) {

    AuditRequestAsync(id);

    return LoadResourceAsync(id);
}

Semantically this function is exactly the same, it also suffers from the same bug but this time there's not even a warning. I've found this kind of issue to more common than it appears because a function can start off by only returning a task without needing the async keyword. In the example above if the AuditRequestAsync function was added later on, or by a different author, they could forget to add the async keyword and the program will still happily compile.

To make matters worst, the function might work in some cases, but fail in others. The AuditRequestAsync function will still run, but without await there is no guarantee the caller will still be around when it finishes. In some cases you might get an error regarding multiple active result sets if they both make database calls. In others, you might not notice anything is wrong at all. Issues like these can often lie dormant until other changes trigger them, or result in indeterministic (or at the very least non obvious) behaviour making them extremely hard to track down and fix.

Implicitly ignoring functions is dangerous

What these examples have in common is that the value returned by a function (AddYears and AuditResourceRequestAsync) was implicitly ignored, resulting in a bug. If the compiler had issued a warning or an error indicating that the value was unused or implicitly ignored these issues could have been caught earlier or prevented entirely.

There are also many more scenarios that suffer from this problem. For example using APIs like LINQ, Reactive Extensions, using Structs, and all immutable types, are cases where forgetting to use the value is almost certainly a bug. Even regular functions, particularly those that return values without side effects would benefit from making it obvious that a return value was ignored or forgotten.

Explicitly ignoring functions is safer

Instead of implicitly throwing away unused values, if we don't want to use a value we should explicitly discard it.

To help catch unused values you could use a custom analyzer to create a warning for all unused values, not just a missing await inside an async function. There are no analyzers that do this yet, however, there are a few similar existing analyzers for some of these cases, such as async await.

Once there are warnings for unused return values it becomes clearer that an unused value is either a bug or something that can be explicitly discarded.

A task, for example, would result in a warning about a possible missing await. If you do want to ignore the task then you can use a standalone discard to let others know you don't care about it.

_ = Task.Run(() => { ... }) // Explicitly discard the result

This makes it clear that you made a conscious decision not to use the value. It shows other developers that a decision was made not to use the value as opposed to forgetting to use it.

When someone else reads that code it is the difference between:

Did they forget to use the return value? I'll need to investigate, versus...
They've chosen to ignore the return value. I can move on.

Making things more explicit will prevent bugs and save you and others a lot of time.

Would this really work

There's a lot of code out there today which was written without explicit discards in mind. And I don't expect the world of C# to change drastically overnight. Nevertheless, the aim of this article is to get more you interested in an analyzer that warns developers about unused return values in the same way your editor warns you about an unused variable today.

You may still be wondering if so much C# code was written without explicit ignores in mind, would this be even practical to do in C#? Recently I've been doing a lot of dotnet development using F# which does emit compiler warning if a function return value is not used. So I can say that even with the dotnet as it exists today, I have been pleasantly surprised. I didn't need to discard half as many values as I thought I would.

The large majority of code didn't need a single discard. There were only a few cases where I needed to use a discard, for example discarding the value at the end of a mutable fluent API.

In that case, I would use an extension method to explicitly "cap off" the expression.

builder
    .RegisterType<HttpClient>().AsSelf()
    .InstancePerLifetimeScope()
    .Ignore() // <- Takes a type <T> and returns a void

I did however still run into at least one bug where I explicitly discarded a value that I shouldn't have. In the end, I found that even explicitly discarding values was something that should be done sparingly. Whenever I discarded a return value I found myself rethinking the code instead.

I was more likely to use or log a status code or return code.

var response = await httpClient.PostAsync(url, null);
log.Information("Responded with {StatusCode}", response.StatusCode);

If I wanted to run a task in the background I kept the task in a Task service and it simplified error handling for all background tasks.

BackgroundService.Register(async () => {...})

// Instead of

_ = Task.Run(async () => {...}) // Hope you handled the exceptions in here

If I used the builder pattern or a fluent API I considered using an immutable API and returning the value instead of a using a mutable one. For example using LINQ vs using the List API.

public IEnumerable<Out> GetResults(IEnumerable<In> items) => items
    .Where(x => ...)
    **.Select(x => ...)
    .OrderBy(x => ...)

I'm also cautious of functions that don't return values but that's another story.

I'm interested but maybe not convinced

Whenever I first stumble across a new concept or technique I find that I need to play with it for a while to start to get a good feel for how it works. Have a go at building an analyzer and see where the warnings are. Try writing a program from scratch with the warnings on. Turn on warnings as errors so you aren't tempted to take shortcuts and follow where the analyzer takes you.

But most importantly, if you find yourself discarding values without using them, ask yourself why.

Type-Safe Hypermedia Controls

Daniel Little — Sun, 12 Jul 2020 08:00:00 +0000

Hypermedia Controls in REST provide links and actions with each response pointing to related resources. This concept is a powerful tool that enables the server to remain in control of links and access. If you're not sure what I mean by this, take a moment to read my previous article on my approach regarding Practical Hypermedia Controls.

Enter Typescript. Adding types to JavaScript allows us to write safer code, so naturally I wanted to figure out how to make a Hypermedia Controls type-safe. Typically when writing a type-safe API you might start out with something like this.

const api = (fetch: Fetch) => ({
  getAccount: async (id: string) : AccountResource => {
    const response = await fetch(`/account/${id}`, jsonGetOptions);
    return response.json() as AccountResource;
  }
  updateAccount: async (account: AccountResource) : AccountResource => {
    const response = await fetch(`/account/${account.id}`, jsonPutOptionsWith(account));
    return response.json() as AccountResource;
  }
})

In this example, the Request and Response types are strongly typed but the URL is hardcoded and you can't tell when you'd have access or who has access to this endpoint. Using Hypermedia Controls can provide that missing context. Links and actions are related to a resource, and the server can dictate if or when the various links and actions are available.

In order to see how to combine these two concepts, let's look at what the usage of type-safe Hypermedia controls would look like.

// Fetch a root resource
const account = await fetchAccount(url)
const accountHypermedia = accountHypermedia(account)

const accountUpdate = { ...account, email: "daniellittle@elsewhere" }

// Invoke the Update action
const updatedAccount = await accountHypermedia.actions.update.call(updatedAccount) // <- Typechecked!

In this example the account email address is being updated and then the Hypermedia Controls are used to update the resource. Fetching the account resource contains the raw Hypermedia Controls but passing the resource into the accountHypermedia function transforms the hypermedia into a type safe API style object. There are a few interesting things happening here, so let's peel back the covers.

Types for Links and Actions

First, Let's take a look at what the AccountResource type looks like.

export type AccountResource = {
  id: Identifier
  username: string
  name: string
  email: string

  _links: {
    self: Relationship
  }
  _actions: {
    activate?: Relationship
    deactivate?: Relationship
    update: Relationship
  }
}

The Hypermedia Controls are statically defined inside of the _links and _actions properties which contain all the well known relationships. Looking at these relationships we can see the resource always contains a self link and an update action but optionally contains activate and deactivate. It's important to note that the types are only coupled to the names of the relationships (rels) and their optionality. The server still controls the URLs and the presence of optional relationships.

Be cautious of making the types for the Hypermedia Controls too dynamic. On my first attempt at adding types for hypermedia, I used a more general dictionary type for links and actions. My thinking was that this would more accurately model the changing and dynamic hypermedia relationships a resource would have.

type Relationships = { [rel: string]: Relationship | unknown }

This assumption quickly turned out to be false and worked against the goal and benefits of strong typing. The relationships were not as dynamic as I had originally assumed. Links and actions don't change frequently, so you can safely define them as part of the type. Another downside was that you can't easily see what relationships are contextual and which ones are always present.

Hypermedia is often taken a bit too far and is often associated with machine-readable metadata or form builders. My advice here is to avoid designing your types for general hypermedia clients. Instead, think of these types as representing a well defined and static contract between the client and the server.

All links and actions use the Relationship type which represents the relationship and its location. A relationship can be either a simple URL or a contain extra info such as the Method or Title.

export type Href = string
export type DetailedRelationship = {
  href: Href
  method?: Method
  title?: string
}
export type Relationship =
  | Href
  | DetailedRelationship

I usually use the DetailedRelationship type but sometimes it's conventient to only provide the URL for links, which typically use the GET verb.

Contextual Relationships

In the AccountResource above you can see there are three potential actions. The update action is always available but activate and deactivate are optional so the client only has to check for the presence of the optional relationships. The server can then decide when these optional actions are available, enabling the actions for the client based on the state of the resource.

const account = fetchAccount(url)
const accountHypermedia = accountHypermedia(account)

if (accountHypermedia.deactivate) {
  // The account can be deactivated!

  await accountHypermedia.deactivate.call() // <- Also Typechecked, no request payload is needed!
}

In this sample, deactivate has to be null checked before it can be used. The call function also knows that deactivate takes no payload and what the return type is.

Creating a Hypermedia Model

Next, let's look into the accountHypermedia function, which does the heavy lifting of transforming the resource with hypermedia into a typed hypermedia model containing all the links and actions. To make the conversion easier I've also written a function createHypermediaModel which helps to create the API for a resource.

type none = void // Used when a Request requires no payload (function <T>(arg: T) would need no arguments)

const accountHypermedia = createHypermediaModel((resource: AccountResource, resolve) => ({
  links: {
    self: resolve<none, AccountResource>(resource._links.self)
  },
  actions: {
    deactivate: resolve<none, AccountResource>(resource._actions.deactivate),
    update: resolve<none, AccountResource>(resource._actions.update)
  }
}))

You can view this code as a mapping from the resource to a set of, ready to use, functions. The resolve function takes the relationship and returns an object containing a strongly typed call function as well as the href and title if one was provided.

resolve<none, AccountResource>(resource._links.self)

Note: In Typescript, you are able to pass through a generic function as a parameter. The resolve parameter makes use of this to compose (an instance of) fetch and the request/response types.

The ResolvedRelationship makes it convenient to access the href and other metadata if you only have access to the hypermedia model.

export type ResolvedRelationship<Request, Response> = {
  call: (request: Request) => Promise<Response>
  href: string
  title: string | undefined
}

I use href from the ResolvedRelationship to follow links to different pages by changing the URL. This means exposing the Method isn't nessesary as they are always GET requests.

Multiple Resources

The createHypermediaModel function focuses on creating a hypermedia model for a single resource. In order to create a model for an entire API you can use a createApi function to create a single object composing the sub-APIs for each individual resource.

export function createApi(fetch: Fetch) {
  const resolve = createResolver(fetch)

  return {
    getAccount: (url: string) => resolve<none, AccountResource>(url).call(),
    accounts: accountHypermedia(resolve),

    // More models go here!
  }
}

That covers all the main pieces of using createHypermediaModel to build a type-safe hypermedia API. Please let me know if you liked this approach as I'm considering wrapping this up into an npm package. However, I've glossed over the detail of how createHypermediaModel works. It's mostly the glue and pluming but there are a few interesting parts. Feel free to read the apendix below if you'd like to dig deeper under the covers.

That's all I have for now and as always thanks for reading!

Apendix: Deeper into the Code

Here is the bulk of the code, feel free to skim over it and jump to the alaysis at the bottom.

export type JsonFetch = <Request, Response>(method: Method, url: string, data?: Request) => Promise<Response>
export type Resolver = <Request, Response>(relationship: Relationship) => ResolvedRelationship<Request, Response>

export const getHref = (rel: Relationship) => (typeof rel === "string" ? rel : rel.href)
export const getTitle = (rel: Relationship) => (typeof rel === "string" ? undefined : rel.title)

export const createResolver = (fetch: JsonFetch) => <Request, Response>(
  relationship: Relationship
): ResolvedRelationship<Request, Response> => {

  const apiCall = async (request: Request) => {
    const rel: { href: Href; method: Method; name?: string } =
      typeof relationship === "string"
        ? {
            href: relationship,
            method: "get"
          }
        : {
            ...relationship,
            method: relationship.method || "get"
          }
    const response = await fetch<Request, Response>(rel.method, rel.href, request)
    return response as Response
  }

  return {
    call: apiCall,
    href: getHref(relationship),
    title: getTitle(relationship)
  }
}

export const createHypermediaModel = <Resource, T>(
  builder: (resource: Resource, resolver: Resolver) => T
) => (resolver: Resolver) => (resource: Resource) => builder(resource, resolver)

The code is written in a functional programming style and functions declared before they are used. Therefore it is usually easier to look at functions starting from the bottom and going up.

The first function is, therefore, ceateHypermediaModel, which uses a bit of currying so the resolver and resource can be provided at different times. Dependencies such as Fetch and the Resolver are threaded through the call stack so no global references are needed.

The other main function is createResolver which constructs the ResolvedRelationship. Its main job is to wrap up the call to fetch using the given relationship and the request/response types.

Practical Hypermedia Controls

Daniel Little — Wed, 08 Jul 2020 00:38:25 +0000

A lot has been written about REST but less so when it comes to Hypermedia Controls. I haven't seen too many Hypermedia based APIs out in the wild. I theorize that there are two main reasons for this. First, it is something many people haven't been exposed to, and second, it requires a little more up-front effort in order to get the ball rolling. However, I believe it's an incredibly useful pattern and it's easier to get started than you might think. This post aims to help out with that first problem, exposure. We'll take a look at what Hypermedia Controls are and why they're useful.

Whatever the reason for the rarity of Hypermedia Controls, what you might commonly see in a REST API instead, is something like this.

{
  "id": "0001"
  "username": "daniellittledev"
  "name": "Daniel Little"
  "email": "daniellittle@somewhere"
  "canUpdate": true
  "canDeactivate": false
}

This JSON object represents a user account. In this system, there are a few simple rules. Only the owner of the resource can update it and only admins can deactivate or activate accounts. This resource uses boolean flags to inform the client what state the object is in and what actions it can perform.

However, there are some problems with this model.

We can't tell if the current user should be able to activate or deactivate the account.
We can't tell if the account can be activated, we have to assume it can be because we can't deactivate it.
We don't know how to update or deactivate an account, we'd need more external information like the URL.

Wouldn't it be nice if all these things were a bit easier to figure out? I think so too!

Enter Hypermedia Controls

Hypermedia Controls in REST APIs are all about adding links and actions to a resource instead of needing to interoperate what links and actions are available based on state. Examples of state are boolean flags like above or a status value like ready or pending. Here's what the same resource would look like if we added Hypermedia Controls instead.

{
  "id": "0001",
  "username": "daniellittledev",
  "name": "Daniel Little",
  "email": "daniellittle@somewhere",

  "links": { ... }
  "actions": {
    "update": { "href": "/account/0001", "method": "put"}
    "activate": { "href": "/account/0001/activate", "method": "post" }
  }
}

Now we can clearly see which actions are available. There are two available actions, update and activate, along with the URL and verb needed to make the calls. Instead of the client needing to infer this from the data, the server directly dictates what actions are available. We don't need to assume the client can activate the account if canDeactivate is false. There's also no danger of adding conflicting flags. The client can directly show or enable buttons or links directly based on what Hypermedia Controls are present.

Let's look at our previous problems again, now that we're using Hypermedia.

There is no action for deactivating the account; so the user can't see or perform that action.
There is an action to activate the account; so the user should see and perform that action.
We know the URL and method, so the client doesn't need hardcode or build-up any URLs.

Much better! This also helps out immensely when debugging or looking at the REST API directly. There's no need for all that extra context to be extracted from the client because it's all there in the resource.

Also, note that to perform an update you would simply modify the resource as desired and send it right back. You can optionally remove the links and actions, but otherwise, they're typically ignored.

All this makes the API much easier to reason about and use. But the key benefit is the client no longer needs to interpret any state to figure out what is going on. We're able to keep the knowledge, of who can do what and when, on the server without having to duplicate any logic into the client. And while this example is a fairly trivial one, a few more flags like the ones above or worse, enum states where the client has to decide what buttons are available based on states like Pending, InProgress or Completed, can easily increase complexity and the burden of keeping everything in sync.

More Control

We can also do more than just make links and actions available or unavailable. We could also show that an action exists but isn't available. On the UI this could manifest as a visible but disabled button.

"actions": {
  "update": null // or { disabled: true }
}

If you'd like things to be a bit more dynamic or server controlled you can also include a title for an action which could be used as the label for a link or button.

"actions": {
  "update": { "href": "/account/0001", "method": "put", "title": "Update Account" }
}

It's really up to you to choose how much information is provided to the client. However, I'd be cautious of adding too much. You might be tempted to include other metadata like field types or validation rules. But the main goal here is to keep duplicate logic out of the client and keep the server in control of application state. Decoupling too much tends to lead to the Inner Platform Effect.

Client-Side Routing

There's one unexpected question I came across while implementing a Hypermedia based API. Which is how they affect client-side routing. I've found keeping API URLs in sync with the browser URLs to be a good approach. Or to be more accurate, I believe they should be the same URL. If you're coming from a non-hypermedia based API your URLs will most likely have diverged so I'll demonstrate what this looks like in practice.

The root hypermedia resource is the starting point for the API, it provides all the top level links you'd need to get started.

// Request:
GET "/"

// Response:
{
  "links": {
    "my-account": "/account/0001",
    "accounts": "/account"
  }
}

Following a link such as my-account (which the client knows by name) would update the browsers route to match, eg. /account/0001. The client-side routing rules mirror the server-side rules to render the relevant components but simply forward the URL directly to the API to fetch a resource. Note that the value here is that the client doesn't have to hardcode, reconstruct or build any URLs.

// Request:
GET "/account/0001"

// Response:
{
  "links": {
    "self": "/account/0001",
    "home": "/"
  }
}

Actions are a little different and don't usually represent a route change. I recommend using a get-post-redirect style pattern so that a link (self) or a redirect is used to determine the next URL for the client.

Try it out

Next time you're building a form with a few actions especially if those actions change under different conditions or states consider using Hypermedia Controls. I hope you enjoyed this article, and if so make sure to keep an eye out for my next post on Type Safe Hypermedia with Typescript.