DEV Community: Meeshkan

Reviving the Dhall API discussion

Mike Solomon — Sun, 06 Sep 2020 16:29:28 +0000

I've worked a lot with REST and GraphQL over the past year, and there some issues that crop up in both ways of building an API.

Dense specs: OpenAPI and GraphQL are fairly complex, and they both require a subtle understanding of how input arguments to an API effect the output. For example, to filter an 8base query, you have to understand how a quadruply-nested input argument will effect a specific subfield. Yikes!
Producer-first: OpenAPI and GraphQL put control in the hands of API producers, which means that consumers are constrained in the way data can be viewed and aggregated by the JSON return type (OpenAPI) and structure of the type system (GraphQL).
Clunky auth: Authorization feels like a bolt-on in both OpenAPI and GraphQL. OpenAPI is a bit better in that different tokens can be used for different endpoints, but they both require ad hoc fine-grained authorization solutions.
Custom DSL: Types from OpenAPI (ie the return type of a GET request) and GraphQL (ie an object type) cannot be used in another context without a lot of parsing and converting. Compare this to isomorphic TypeScript, where types can be standardized across entire projects through the use of libraries.

These problems are not because OpenAPI or GraphQL are bad. It's just that modern software has complexities that neither spec was designed to handle.

Tinkering with Dhall this weekend, I had the thought "What if Dhall could be the basis of a query language à la REST or GraphQL? Would this help solve some of the issues above?"

Github did not disappoint - someone was already thiking of this a couple years ago and wrote an initial design document. My spin on it is different, but the basic idea of using Dhall as a stand-in for GraphQL is the same. I'm curious to hear what people think!

What's Dhall

Dhall is a configuration language. It's basically JSON, but with variables, types, functions and the ability to include other files. It also has some built-in functions for basic tasks like folding lists.

This is some dhall:

{ name = "Mike", country = "Finland"}

This is some slightly more complicated Dhall.

let license = "Apache-2.0" in
{ name = "Mike", country = "Finland", license = license }

Once variables are substituted and functions are evaluated, Dhall is output as plain old JSON or YAML.

Dhall for Web APIs

The next sections of this article outline the basics of a Dhall-based API exchange using a pet store example. I'll then address how it solves the four problems I've identified above.

Service discovery

The first step is to send a JWT (ie from Auth0) to a service discovery endpoint which returns a JSON object with two keys:

schema, which shows the JSON schema that an API consumer can consume with the given token; and
nonce, which must be sent along with the token to verify that the correct version of the schema is being served.

In our example, the return value will look something like this:

{
  "nonce": "wjsmcpmpiyvpwqba",
  "schema": {
    "$ref": "#/definitions/user",
    "definitions": {
      "user": {
        "id": { "type": "integer" },
        "name": { "type": "string" },
        "pets": {
          "type": "array",
          "items": { "$ref": "#/definitions/pet" }
        }
      },
      "pet": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "owner": {
            "$ref": "#/definitions/user",
            "items": { "type": "object" }
          }
        }
      }
    }
  }
}

Dhall from the producer

Now that the API consumer knows what information she or he can access with a given token, the server needs to be able to process requests for that information. This is where the Dhall comes in. The example presented below can be seen in its entirety on this gist.

First, let's import some functions we'll need a bit later on:

let fold = https://prelude.dhall-lang.org/List/fold
let filter = https://prelude.dhall-lang.org/List/filter
let equal = https://prelude.dhall-lang.org/Natural/equal

Data, as represented by an API producer, should be flat. A single table with three columns will suffice:

Pointer: A pointer to an underlying object.
Key: A key on the object.
Value: The value of the key.

Below is my data model. It's a simple pet-store API, so there are three types of objects: User, Pet and List. The keys of an object can be Id (ie 42), Type (ie Pet), Name (ie "Fluffy") etc. Head and Tail are a way to represent linked lists.

Entries are integers, booleans, doubles, text, pointers to other objects called Id_, a given Type, and Nil to signal an array terminates.

Lastly, our Db is a list of Row objects that combine a pointer to an Id, a key and a value.

let Obj = <User | Pet | List>
let Key = <Id | Type | Name | Pets | Head | Tail>
let Entry = <Int_: Integer | Bool_: Bool | Double_: Double | Text_: Text | Id_: Natural | Type_: Obj | Nil>
let Row = { ptr: Natural, key: Key, val: Entry }
let Db = List Row

If Haskell and MongoDB had a baby, this'd be it. There is a notion of using a union - Obj - to represent typed objects. At the same time, the way these things are mixed and matched is flexible.

The last thing we do as an API producer is define how to pass this information to consumers. The signature of Reader says "for whatever projection the consumer wants, if they provide a function from the db to the projection, I will provide that projection." We then feed the data to ReaderImpl.

Note that, in a live example, a Dhall-language binding in a given language (ie JavaScript, Python) would be used, and the data would be injected via that binding rather than hardcoding it in Dhall files.

let Reader: Type = forall (Projection: Type)
  -> forall (ProjectionF: Db -> Projection)
  -> Projection

let ReaderImpl: Reader = \(Projection: Type)
  -> \(ProjectionF: Db -> Projection)
  -> ProjectionF [
    {ptr=0, key=Key.Id, val=Entry.Id_ 0},
    {ptr=0, key=Key.Type, val=Entry.Type_ Obj.User},
    {ptr=0, key=Key.Name, val=Entry.Text_ "Mike"},
    {ptr=0, key=Key.Pets, val=Entry.Id_ 1},
    {ptr=1, key=Key.Type, val=Entry.Type_ Obj.List},
    {ptr=1, key=Key.Head, val=Entry.Id_ 10},
    {ptr=1, key=Key.Tail, val=Entry.Nil},
    {ptr=10, key=Key.Id, val=Entry.Id_ 10},
    {ptr=10, key=Key.Type, val=Entry.Type_ Obj.Pet},
    {ptr=10, key=Key.Name, val=Entry.Text_ "Fluffy"}
  ]

One important convention to note in this setup is that the top-level object of the JSON schema is always represented by the pointer 0.

Lastly, this code works for queries but not mutations. For mutations, you'd need a Writer type with the following signature:

let Writer: Type = forall (Projection: Type)
  -> forall (TransformF: Db -> Db)
  -> forall (ProjectionF: Db -> Projection)
  -> Projection

The transform function takes the Db and produces an altered version with whatever writes/deletes/updates one wants to do, and the projection function is the same as above.

Dhall from the consumer

The consumer then fulfills her or his part of the contract by providing the projection function.

let getName: (Db -> Natural -> Text) = \(db: Db)
  -> \(ptr: Natural)
  -> fold
     Row
     (filter
       Row
       (\(a: Row) -> equal a.ptr ptr)
       db)
      Text
      (\(a: Row) -> \(t: Text) ->
        merge {
          Id=t,
          Type=t,
          Name=merge {
            Int_=\(v: Integer) -> t,
            Bool_=\(v: Bool) -> t,
            Double_=\(v: Double) -> t,
            Text_=\(v: Text) -> v,
            Id_=\(v: Natural) -> t,
            Type_=\(v: Obj) -> t,
            Nil=t
          } a.val,
          Pets=t,
          Head=t,
          Tail=t
      } a.key) ""

let View = { name: Text }
in ReaderImpl
   View
   (\(db: Db) -> {
     name = getName db 0
   })

If you copy-and-paste the code in the gist and run it in the on-line dhall interpreter, you'll get {"name":"Mike"} as the output JSON.

NB that the getName monstrosity above is in the grey-zone between producer and consumer. It is consumer side, but is boiler-plate-y enough to warrant a standardized implementation for all consumers. The great thing about Dhall is that these sort of functions can be factored into their own files.

How this fixes the problems defined above

Let's revisit the problems above one by one and see how this solution fixes them.

Spec

The spec is JSON schema, pure and simple. It is more concise than OpenAPI, and it lacks having to deal with input parameters like GraphQL.

It is up to the producer to ensure that the flat data structure fed to the projection function follows the JSON schema. Combing over it is then automatable with functions like getName.

Power to the consumers

The return type from the spec is completely determined by the consumer. That's the line let View = { name: Text } above. The JSON schema represents how the data is provided on the producer side, but it is entirely up to the consumer how they choose to aggregate it. In this case, I opted to leave off pets, going only for {"name":"Mike"}. I didn't need to call the field "name", nor did I need to return "Mike" unaltered. As consumers of the data, we aggregate it as we see fit.

At the same time, the data can be infinitely deep, as we saw with the pets-to-owners recursive relationship in the JSON schema. This is why the types cannot be represented in anything other than a flat structure.

The idea of consumers sending code to a server to execute and turn into a result may seem far-fetched, but Dhall is the perfect language for this because it is ultra-secure (no IO possible) and has no recursion, so no infinite loops.

Authorization

In my opinon, the most important aspect of this design is that it gets authorization right. When the first handshake happens and the consumer receives a JSON schema based on their token, they know what they will be allowed to see. They don't know anything about what anyone else can see or an underlying schema. The JSON encodes the entirety of their authorization permissions.

It could be, for example, that a resource is both viewable (ie someone's name on a list of friends) and not viewable (ie the fact that that person is dating your ex) depending on where it shows up in the JSON schema. In this way, the same resource can have multiple different pointers, and similarly, the same pointer can be referenced recursively (pets-to-owners above), allowing for queries as deeply nested as the consumer wants. What stops a recursive loop is the fact that the consumer's query is not infinitely long, but we do not limit how deep they can nest their data.

Custom DSL

With Dhall, there's no custom DSL like GraphQL. There's just Dhall, and Dhall types can live across projects. Dhall was born for the internet, so including a type is as easy as pointing to its URL (as we saw with the imports of fold, filter and equal above).

Conlcusion

In this article, I presented four ways that I think modern API building suffers:

The specs are too dense.
The way data is queried and mutated is dictated by API producers.
Authorization is broken.
Custom DSLs require needless specialization.

I then presented a brief sketch for a Dhall-based web API that, in my opinion, solves these problems. I encourage you to paste the GitHub gist in the Dhall on-line evaluator to see how the whole thing ties together. Please let me know what you think!

Four reasons that PureScript is your best choice to build a server in 2020

Mike Solomon — Fri, 04 Sep 2020 12:49:46 +0000

Today, on the #purescript channel of the functional programming Slack, I wrote "I think PureScript is the best choice for anyone building a server in 2020." To that, Peter Andersen asked:

Wow! What are the key things in your eyes that make it the best?

Now if that's not an invitation to blog, I don't know what is!

So, here are four reasons that PureScript is the best way to build a server in 2020. I'll tl;dr them here, but you should stick around for the bonus reason at the end as well!

Hello world
Portability
Language
Community

Hello world

The time it takes to get a server up and running in PureScript is as fast as a hello-world server in JavaScript and Python. At Meeshkan, we regularly have to push out a server for some random part of the stack, and my fingers can get in the PureScript+Payload groove as fast as Node+Express or Python+Flask.

npm init -y
npm install purescript spago xhr2
init
spago install payload
spago build

Then mosy on over to src/Main.purs and paste:

module Main where

import Prelude
import Effect (Effect)
import Effect.Aff (Aff)
import Payload.Server as Payload
import Payload.Spec (Spec(Spec), GET)

type Message
  = { text :: String }

spec ::
  Spec
    { hello ::
        GET "/hello"
          { response :: Message
          }
    }
spec = Spec

hello :: {} -> Aff Message
hello _ = pure { text: "world" }

main :: Effect Unit
main = Payload.launch spec { hello }

Then, in bash:

spago run

Try curl http://localhost:3000/hello, get back {"text": "world"}.

The package Payload is one of several ways to build a server in Purescript - there's also Hyper. And there are libraries to work with GraphQL and OpenAPI as well.

In the "just get stuff done" department, PureScript rivals languages like JavaScript, Python and Go. The next time you need to crank out a server, remember that PureScript is imminently crankable!

Portability

PureScript is a front-end for multiple languages. It compiles to JavaScript, Go, Python, Erlang, Haskell, and C++, just to name a few. So the "write once, use everywhere" philosophy that made isomorphic Node+Browser development so popular is even more powerful in PureScript. Furthermore, because PureScript is just transpiling, it can be deployed to environments like Heroku, Vercel or GCP by putting spago run in your package.json for the run command.

If your server needs to access custom language features, like a ML model in Python or a killer library you can't live without in JavaScript, PureScript's foreign function interface allows for seamless interaction between PureScript and the target language. For example, if in PureScript we have:

-- Main.purs
module Main where

foreign import hello :: Int -> Effect String

Then you just need a Main.js in the same folder:

// Main.js
exports.hello = (i) => () => `${i}`

And PureScript automatically links them up.

The day you need to migrate your server from language X to language Y, you'll be glad you wrote most of it in PureScript. I recently had this experience with WebAudio - I wrote a proof of concept in PS->JavaScript and did PS->Wasm once I was ready to make it more performant at the expense of debugability.

Language

PureScript is in the same category of languages as Haskell, Idris, Agda and Coq. Because these languages lend themselves well to proving things, really smart people tend to flock to them, which means the discussion is usually pretty heady and newbs can get easily lost.

However, this discussion masks the reality that functional languages are no more difficult to get started in than other ones. Imagine that you need to write a function that increments positive integers and returns some nullish value for anything less than 0. Compare an implementation in Python to the same in PureScript.

def posinc(i):
  return None if i <= 0 else i + 1

posinc i = if i <= 0 then Just i else Nothing

I've shown these "Rosetta stone" examples before many-a-coder and have yet to find someone that feels one is inherently more difficult than the other.

If I were a betting person, I'd bet that the type safety and clean, readable code that come with the Haskell family of languages will save you many-a-bug in production and cause you to never work with anything else. But alas, I don't bet. The only point I'll make here is that you don't need to have ten years of software development under your belt to grok PureScript. Getting up and running is no different than learning Python.

...a quick aside to those of you who are into FP and swear up and down by it. PureScript is not as full featured as Haskell, and doesn't have out-of-the-box dependent types like Idris/Agda, but it has a minimalistic feature set that allows you to do most of the stuff you'd actually want to do in a real-world app. Plus, it is really easy to deploy on Heroku, Vercel or AWS Lambda.

Community

The PureScript community has an active, non-toxic Discourse and Slack populated by helpful people that answer each others' questions and share resources. Additionally, most libraries you'd ever need for a basic server have already been written with ample documentation on Pursuit, and novel ideas are being explored all the time.

A lot of PureScript coders also use dhall as an alternative to JSON for configuration. If you use spago as I did above, you're using dhall and you'll see dhall files in your directory. For anyone that has ever been hit by a configuration bug, you know the importance of getting config right early on in a project. PureScript+Dhall is an unbeatable combo in this regard.

Bonus

I promised you a bonus, and here it is. While Meeshkan is an equal-opportunity tester, we have additional bells and whistles in our service that we use if you provide us with certain assets like an OpenAPI spec or GraphQL schema. We also have tools that use the types of certain languages to create even more powerful tests, and PureScript is on the list. So by going with PureScript, your service will be more testable by Meeshkan. As our stack becomes more mature, we regularly open-source PureScript libraries to help folks build better servers and write more powerful tests.

Conclusion

PureScript is still in early-adopter mode, and the community is tiny. I personally was reluctant to try it out at first because I didn't see the point over using Haskell. However, the velocity of development/deployment, the limited feature set one can wrap one's head around, and the portability won me over. The next time you're building a server, or even in your current server if it is in a language to which PureScript compiles, give PureScript a shot!

Functional GraphQL 1 - Specs and typelevel parsing

Mike Solomon — Fri, 04 Sep 2020 07:06:24 +0000

One of the common points of friction in GraphQL-land is making sure resolvers are conformant to specs. There are three main strategies I've seen to do this:

Runtime validation of IO like in Apollo and Absinthe.
Code generation, like Prisma and GraphQL code generator.
Deriving the schema from the resolvers or db, which is available in purescript-graphql and underpins services like 8base.

They all have their disadvantages:

Runtime validation requires lots of testing and manual upkeep.
Code generation requires constantly merging generated code and dealing with stubbed methods.
Deriving the schema from the resolvers is my favorite so far, but IMO it puts the control in the wrong direction. A schema should be influenced equally by consumers, and putting too much control in the hands of producers makes development less fluid.

I'd like to talk about a different strategy: generation of resolver types.

The basic idea is that you have a schema, and the compiler uses the schema to generate the type of your resolver. That way, when the schema updates, the code no longer compiles, and getting the code to compile makes it schema-conformant.

This strategy is possible in any strongly-typed language. For example, in TypeScript, GraphQL code generator will generate a resolver type that looks like this:

schema {
  query: Query
}

type Query {
  me: String!
}

export type QueryResolvers<
  ContextType = any,
  ParentType extends ResolversParentTypes["Query"] = ResolversParentTypes["Query"]
> = {
  me?: Resolver<ResolversTypes["String"], ParentType, ContextType>
}

export type Resolvers<ContextType = any> = {
  Query?: QueryResolvers<ContextType>
}

This is already a vast improvement, but it still has a few issues:

Important parts of business logic cannot be known by a type generator. For example, if you want custom directives to influence authentication or need a more nuanced context, a type generator becomes clunky.
You need an extra layer of translation from input types to application-level types. For example, the String me above may need to be a full-fledged User object in the application.
You lose the benefits of code generation in places where application logic is boring and repeatable.

So, while the generation of resolver types is helpful, we can do better. For the rest of this article, I'd like to talk about compile-time generation of resolver types.

What is compile-time generation of types?

Compile-time generation of types means using the compiler to generate one type from another type. While that many sound a bit strange, there's nothing about it that's conceptually different than generating one value from another value. In programming, for example, we can do:

const toString = (i: any): string => `${i}`

At the type-level (switching to PureScript) this becomes:

class ToString a b | a -> b where
  toString :: a -> b

instance ts :: Show a => ToString a String where
  toString = show

In the first example, we're guaranteed that any value that goes into toString will come out as a string on the other end. In the second example, we're guaranteed that any type that goes into ToString will come out as String on the other end.

const a = toString(1) // "1"

forceString :: forall b. ToString Int b => b -> b
forceString = identity

a = forceString "5"

b = toString 5

Here, we've the same toString function in JavaScript for free, and in addition, we've gotten a compile-time validator forceString. To see why, let's look at what happens when you use forceString with anything other than a string.

If we hover over it, you'll see that the compiler has "solved" what forceString must take.

Using ToString, we've pulled a type out of thin air. If you look at forceString, nowhere in the definition does it say b must be a String. The compiler figures it out from the implementation of ToString.

In the same way, the compiler will figure out what type our GraphQL resolver needs to be from our GraphQL spec.

A slightly-more realistic example

In the following example, we'll use purescript-typelevel-parser to turn symbols into types. In PureScript, Symbol is a kind. A kind is just a family of types. The types that inhabit kind Symbol are every unicode string. Thankfully, the binary of the PureScript compiler doesn't contain every unicode string (that'd be a pretty big compiler!). The compiler creates a type for each unicode String on-the-fly. So the type "a" is of kind Symbol just like the value "a" is of type String.

Instead of GraphQL, in this example, we'll use a spec called TypeQL. This (fabricated) spec is a series of lowercase strings separated by &. The general idea is that it defines keys that point to a type. Keys of what? Who knows! Perhaps a dictionary, perhaps a database - that's for us to decide when we implement the spec. What type do the keys point to? Who knows! Perhaps Int, perhaps String.

One example would be gold&silver&bronze pointing to Int, another would be earth&wind&fire pointing to Boolean. Like a GraphQL spec, our TypeQL spec doesn't mean anything. It is just a container of information. Our program will give it meaning, just like a GraphQL resolver gives a spec meaning.

An engineer has been tasked with taking a TypeQL spec and creating a PureScript implementation that can work for any type. So, for example, if we get a spec earth&wind&fire, then we want to be able to automatically generate a type { earth :: a, wind :: a, fire :: a }, where a can be any type (Int, String, etc).

Let's start with some imports.

module Test.TypeQL where

import Prelude
import Prim.Row (class Cons)
import Type.Data.Row (RProxy(..))
import Type.Parser (class Parse,
  type (!:!), ConsPositiveParserResult, ListParser, ListParserResult,
  Lowercase, NilPositiveParserResult, SingletonMatcher', SingletonParserResult,
  SomeMatcher, Success, kind ParserResult)

Now, we define our spec. In this case, it will be python&java&javascript. In the next article, this'll be a full blown GraphQL spec. Notice how "python&java&javascript" is a Symbol, not a String, because of the identifier type.

-- our spec
type OurSpec
  = "python&java&javascript"

The next step is defining a parser. In most cases, you never have to actually write a parser as it is done for you (ie Apollo parses GraphQL). The same will be true of our GraphQL parser in the next article, but I want to show you how it's done so that you can follow a full example

data Key

data Keys

-- here's our parser
type KeyList
  = ListParser ((SomeMatcher Lowercase) !:! Key) (SingletonMatcher' "&") Keys

Using the primitives of purescript-typelevel-parser, we define a list of lowercase values separated by the separator & that accurately describes the TypeQL spec.

Once we have a parser result, we need to define how it translates into a type that our application understands (continuing in GraphQL-speak, we need to define the type of our resolver). In this case, we will take the parser result and turn it into a row where every key points to something of type i. For example, foo&bar&baz with type Int will turn into a type { foo :: Int, bar :: Int, baz :: Int }.

class TypeQLToRow (p :: ParserResult) (i :: Type) (t :: # Type) | p i -> t

instance nqlToRowNil ::
  TypeQLToRow
    ( Success
        (ListParserResult NilPositiveParserResult Keys)
    )
    i
    res

instance nqlToRowCons ::
  ( TypeQLToRow (Success (ListParserResult y Keys)) i out
  , Cons key i out res
  ) =>
  TypeQLToRow
    ( Success
        ( ListParserResult
            ( ConsPositiveParserResult
                (SingletonParserResult key Key)
                y
            )
            Keys
        )
    )
    i
    res

class SymbolToRow (s :: Symbol) (i :: Type) (r :: # Type) | s i -> r

instance symbolToTypeQLType ::
  ( Parse KeyList s out
  , TypeQLToRow out i r
  ) =>
  SymbolToRow s i r

Now, we can create our typelevel validator. The validator just passes through an object, but in doing so, validates at compile-time that the object conforms to our spec. For example, { python: 1, javascript: 2, java: 3 } conforms to our spec.

intValidator ::
  forall (c :: # Type).
  SymbolToRow OurSpec Int c =>
  Record c ->
  Record c
intValidator a = a

languages :: { python :: Int, javascript :: Int, java :: Int }
languages =
  intValidator
    { python: 1
    , javascript: 2
    , java: 3
    }

Let's imagine that we now add a language (say purescript). Our spec becomes python&java&javascript&purescript. What happens to languages? Let's see!

type OurSpec
  = "python&java&javascript&purescript"

As we hoped, the compiler gets angry.

But, because it deep down the PureScript compiler is nice, it gives us a helpful error message letting us know what we did wrong.

Now we can fix it!

languages :: { python :: Int, javascript :: Int, java :: Int, purescript :: Int }
languages =
  intValidator
    { python: 1
    , javascript: 2
    , java: 3
    , purescript: 4
    }

Conclusion and next steps

In this article, I've shown how typelevel-programming allows you to take a spec (ie TypeQL) and use it to generate a type. We use the type to create a validator that makes sure our code is always conformant with the spec. It's also allowed us to use custom business-logic (in this case, using Int as the indexed type of our record).

In the next article in this series, which will come out in mid-September 2020, I'll show how this strategy can be used to build type-safe GraphQL resolvers. In the meantime, if you're building a GraphQL API, you should sign up for Meeshkan! We do automated testing of GraphQL APIs. Our novel approach combines functional programming and machine learning to execute thousands of tests against your GraphQL API and find mission-critical bugs and inconsistencies. Regisration is free, and don't hesitate to reach out - we'd love to learn more about what you're building!

When to start thinking about QA

Mike Solomon — Mon, 31 Aug 2020 08:49:55 +0000

At a conference recently, I heard someone ask the question "When's a good time to start thinking about QA?" The question was asked in earnest, but the speaker responded with a quick "Immediately!" and moved onto the next question. While "Immediately!" reflected the speaker's enthusiasm about quality assurance, it left the question-asker down in the dumps.

Knowing when to think about QA is really hard, and there's not that much good advice out there. A lot of blog posts, like the above-mentioned speaker, skirt the issue by saying things like "write more tests" or "use strong typing." Chances are, if you're Googling "When to start thinking about QA", these are not answers to your question. This article is.

A couple definitions

Once, when I was building an Android app, an angry supervisor asked us to "Stop throwing the app over the net to QA." I understood what the person meant, and I've heard this sort of critique a lot. The issue with the critique is that the most important part of the QA process is throwing your app over the net. The reason you throw your app over the net is because, very soon, you will be throwing your app over an even bigger net called production.

I like to use the analogy of the performing arts here: there are lots of rehearsals where you bring in someone from outside to look at your work. The last rehearsal (the dress rehearsal) is almost always this, but there are regular points in the development of a staged production where you'll bring in a trusted expert to give their opinion. You do this because, eventually, there will be hundreds and thousands of people forming their own opinion about your work, and it's important to make sure that your work represents your ideas. When you collaborate with a QA engineer, you're bringing someone in to watch a rehearsal.

A lot of people worry that QA engineers will treat every rehearsal like the dress rehearsal, but this is not true. Great QA engineers know exactly what stage a project or feature is at and will give feedback that will help the project or feature at that stage.

So to sum up, QA is a third-party viewpoint that gives you stage-appropriate technical feedback about your project.

The single most important step

The most important step you can take, starting today, is kicking off a relationship with a QA professional or a company providing QA. This does not require purchasing or using a service - it just means introducing yourself.

Great QA services (and we like to think we're building one!) know how to take it from here. Like a tailor or a doctor, they will start taking measures. By monitoring a codebase, a roadmap, and specs, a QA professional will focus on the following questions:

When are major releases planned?
Are there any indicators that would predict increased development velocity at a given time?
How often are there breaking changes to a service, and what are the precursors to these changes?

These questions are asked in order to plan out when their help can be most impactful and necessary.

At Meeshkan, we ask and answer these questions by testing code bases, creating specs, and building burn charts. The purpose of this is not to provide you with information (you're already overloaded!) but to answer even more important questions:

When will the team likely have time to digest test reports?
Are there enough valuable indicators about quality to share them with the team?
What is a five-alarm fire in the context of the team's business needs?

All of this means that, when you get a ping from us, you can trust us that it is important. Of course, we give you access to the entire trail that leads up to our decisions, and if you really want to, you can read over the tens of thousands of tests we run on your service. But our job is knowing what to present to you, when to present it, and how it should be presented.

So, introduce yourself! It will take a matter of minutes, and you'll be on the path to cultivating a long-term relationship that underpins great QA.

The next step

You've now won half the battle. Developing a relationship with a QA professional will aleviate a lot of stress because your trusted partner knows when to step in and when to get out of the way.

The next step, and the other half of the battle, is what happens at the "rehearsal", to use the analogy from above. What are you hoping to get out of QA that you wouldn't get out of building a spec, writing a few tests, or using a great linter?

QA is all about business outcomes. It puts itself in the place of the user, looks at the current state of the UX, and assesses if the "diff" between the current UX and the desired UX is on track. If a QA engineer crashes your app by pressing a button five times in rapid succession, they won't bring the crash to your attention unless it is linked to an underlying problem that can effect your bottom line.

We see this all the time at Meeshkan. Our algorithms regularly crash servers by using very large numbers, negative pagination and other forms of exotic input. If you hear about this type of behavior from us, it is because we've linked the crashes to some underlying issue that we think is unsustainable. Otherwise, you won't hear from us because it's ok if your app crashes in the wild. Don't let anyone tell you otherwise! What's not OK is for your business to consistently only ever return three out of twenty valid search results to a user. That's not a crash, but if search is a critical feature of your business, then that's a major problem. Great QA brings that to the fore.

The difference between Meeshkan and traditional QA is that we do this automatically. There are several core benefits of automated QA:

It explores a lot of potential outcomes.
It pools data from thousands of tests to recognize patterns and make the best possible predictions.
It moves at the speed of your development by testing every change to source code.
The price point makes it easy for small businesses to get started.

Automated QA is not a replacement for manual QA. Someone will always need to give your app or service a spin in the wild. Sometimes your most enthusiastic users serve this role. But automated QA leads naturally to manual QA in several respects:

It gives a tester a machine-built spec, which can act as a map of the service.
It shows what parts of the app are the most trivial/predictable so that the manual tester can focus on the hard stuff.
Like drivers in a self-driving car, manual testers provide a valuable source of confirmation to machine-built QA algorithms, creating a positive feedback loop.

An example

Your business deploys a new service. Congrats! 🎊 Initially, all of the service's features are in your head, and you're able to do enough testing so that you confidence when you deploy.

Soon, the service grows in complexity. You add authentication, you write to a database, and you start relying on other services. At a certain point, you begin to feel an uneasy feeling when you merge a branch to production. Why do you feel this way? You've tested the service as best you could, all the tests are passing, and still you fret about bad outcomes. It could be a logged out user accessing logged-in resources. It could be JSON parsing failure leading to serving a 404. But there's some form of psychological resistance to merging to production.

The day you feel this is the day to kick off a conversation with a potential QA partner. If we're fortunate enough to earn your business, one of the first things we'll do is identify all of the points in your app that are most likely making you feel this way. For example, if you use some form of message passing like spawn/register in an Erlang cluster or Google PubSub, we have a certain category of automated tests that apply to this type of setup.

These tests don't just bombard the system with garbage input. For example, we will look to see if there are PubSub topics that are written to but never read. We will also try to find common mispellings of PubSub channels and potential deadlocks. You may get a report that says the following:

Channel customerPaid expects input written to channel customerRegistered, but customerRegistered expects input to customerPaid.

We may send you only this in the report even though your app is crashing in other places. This gets back to the main idea from above - our goal is not to taunt you with the 1,000 ways we made your service crash, but to distill our findings into the five things (maximum!) you need to know.

PubSub is one of hundreds of places where automated QA moves the needle. At Meeshkan, we also look at CRUD operations, calls to third-party APIs, naming conventions, and many other indicators of quality that add up to create a rock-solid service.

I've seen a lot of companies resist bringing in a QA professional because they're still experimenting with a novel idea and they're not sure if it's worth testing yet. I regularly hear folks say "Why bother bringing in QA if we may change the whole thing in a month anyway?" My answer is that one month is too long. Agile teams build upon successive hypotheses in a matter of days, and one way to speed up the process is having high-quality code early on. Meeshkan exists to provide value at exactly this stage. From the day you add Postgres or PubSub or OAuth2 to a service, our algorithms are able to discern if the use of a particular technology is idiomatic and viable.

How to get started

While we hope to be your trusted partner in automated QA, we realize that you have a choice in both automated an manual QA options. For manual QA and for writing your own tests in a Selenium-like style, we really like Rainforest QA. For automated QA, and especially if you're just getting started, we recommend creating a free Meeshkan account.

Conclusion

The purpose of this article, and why it is a bit longer than your average missive on the subject, is to avoid a kitch or cop-out answer to "When should I start thinking about QA?" It explores this question head on, addressing the purpose of QA, the benefits you can expect, and how to kick things off.

As businesses increasingly find themselves pivoting to keep up with market tendencies, the major challenge of the next decade will not be making software that's built to last. It will be honing in on market signals faster than competitors. Your software is the best signal detector there is, and modern quality assurance makes sure that what you are building will return as much signal and as little noise as possible. At Meeshkan, we accompany teams that build modern software. So what are you building?

Type-safe rationals in PureScript - why, what, and how

Mike Solomon — Mon, 31 Aug 2020 08:44:35 +0000

In the era of Corona, I've heard some amazing music projects recorded entirely remotely using technologies like virtual desktops and web audio. As a side project, I'm building an open-source web-based digital audio workstation that uses PureScript in the browser as its scripting language. My hope is to facilitate remote audio collaboration and open up new creative possibilites for musicians all over the world.

One of the biggest challenges in audio is parameter validation. There are so many numeric parameters and tracks in a modern audio project that it's really easy to saturate quickly, resulting in soul-crushing compression and limiting. Add more people to the equation, none of whom have the same mix in their head/ears, and it's a recipe for disaster. So one thing I wanted to get right from the outset was a representation of parameters where people could reason about acceptable ranges.

A lot of user-facing parameters in audio are represented as rational numbers, most often between 0 and 1. Bearing this in mind, I set out to build a library that allows programmers to reason about numeric parameters their audio programs (or any programs) right from their IDE.

Enter purescript-typelevel-rationals. They allow you to keep track of flows of rational numbers to know exactly what the possible range of output values will be. I hope that it helps musicians make more subtle mixes. With time, I'll add features like trigonometric functions, natural logarithms, complex numbers, and other things that can be expressed at the type level.

That's all well and good, but what is a rational number expressed as a type? I'm glad you asked!

Type-level programming

Anyone that uses a strongly typed functional language works with the compiler to some extent as they write their code. Fingers tire, the brain starts to shut down, and at a certain point you think "ah, whatever, let the compiler do the hard work" as you press compile. There are IDE extensions for most languages that'll put these warnings in your editor so that you can tidy up right as you code.

Type-level programming, for me, is a way to enhance this experience. It teaches the compiler to catch mistakes based on the types you define. For example, if you find a way to define PositiveFloat, then the compiler can warn you or downright fail the build anytime the value dips into the negatives. For audio applications, this is really important, as a lot of plugins have wanky behavior with negative input.

My PureScript implementation

To start, I define a number not as a value, but as a constrained value. To the right of the colon is a constraint meaning 0 <= n < 1.

type Between0And1 = ConstrainedRatioI ((Nt (Lt Zero)) &&/ (Lt (P1 +/ P1)))
oneHalf = asConstraintedRational 1 2 :: Maybe Between0And1

This will yield a value of 1/2 with the following type:

Just
  ( ConstrainedRatioI
      ( AndConstraint
          ( NotConstraint
              (LessThanConstraint Zero)
          )
          (LessThanConstraint (PRational P1 P1))
      )
  )

Because our constraint is between 0 and 1, the compiler does not know that it is 1/2, but it does know that it is in an initial acceptable range. Had we tried to do the following, we would have gotten Nothing because 3/2 is greater than 1:


oneHalf = asConstraintedRational 3 2 :: Maybe Between0And1 -- Nothing

Traditionally, this type of validation function is implemented so that it yields Maybe Float. While that's all well and good, we lose tons of information by working with a blunt instrument like Float. Our type above may be a bit verbose (we can stash it in a type variable to save room), but it communicates our intention exactly.

Of course, a type with that wide of an ambitus only makes sense when you're not sure what the input will be, ie if you're reading from disk. If you know it's 1/2, just say it!

type ExactlyOneHalf = ConstrainedRatioI (EqConstraint (P1 +/ P2))

oneHalfPrecise = asConstraintedRational 1 2 :: Maybe ExactlyOneHalf

invoke

The next important bit is invoke. It takes a function from a -> c, where a is a constrained rational, and transforms it into a function of type b -> c if b's type is a sub-constraint of a. For example, 0 <= n < 2 is a sub-constraint of -1 <= n < 2 but not -1 <= n < 1. The constraints and subconstraints can get as wild as you'd like, ie (0 <= n < 2 & 4 <= n < -5) || n < -42. purescript-typeleve-rationals figures it out.

To use invoke, let's take the oneHalfPrecise we defined above. Now, let's create a function that accepts any value between 0 & 1 and returns 0.25.

type OneQuarter = ConstrainedRatioI (EqConstraint (P1 +/ P4))

returnAQuarter :: Between0And1 -> OneQuarter
returnAQuarter _ = constConstrained $ resolve (CRProxy :: CRProxy OneQuarter)

Above, resolve resolves a constraint into a rational if it is a single value (ie 1/4) and constConstrained converts it back to a constrained rational. To see how powerful resolve is, try to mess with it. For example, in my IDE, I changed the NotConstraint (LessThanConstraint (PRational P1 P4)) to NotConstraint (LessThanConstraint (PRational P1 P5)). That means that the value is between 1/5 and 1/4, so we can no longer resolve it to a single value. Sure enough, the IDE gets angry at me. Thanks, PureScript compiler!

Now that we have our function, let's invoke it!

myQuarterBack = invoke returnAQuarter <$> oneHalfPrecise

Neato, we get a quarter. But what if we tried to invoke it with something (gasp) outside of its proscribed range of 0 <= n < 1? Let's find out!

Wow, that compiler is livid. As it should be! We've tried to invoke a function with a value (3/2) outside of its domain (1/2). Going back to audio, think of all those ears that will be spared from gratuitous clipping. Unless you're into Merzbow, in which case you can make a constraint that the volume should always be over one.

Adding numbers

Lastly, let's see how invoke allows us to specialize functions, like an adder, for specific input.

First, we'll create an adder for numbers between 0 and 1.

type Gte0lt1 = ((Nt (Lt Zero)) &&/ (Lt (P1 +/ P1)))

type Between0And1 = ConstrainedRatioI Gte0lt1

zeroToOneAdder =
  addConstrainedRationals ::
    forall (a :: ConstrainedRational).
    InvokableRational
      Gte0lt1
      a =>
    Between0And1 ->
    ( forall (b :: ConstrainedRational).
      InvokableRational
        Gte0lt1
        b =>
      Between0And1 ->
      ( forall (c :: ConstrainedRational).
        AddConstraint a b c =>
        ConstrainedRatioI c
      )
    )

Now that that's done, we can create a specialized function called addTwoHalves that only accepts values that are 1/2 and, consequentially, returns 1.


type IsOneHalf = EqConstraint (P1 +/ P2)

type IsOne = EqConstraint (P4 +/ P4)

addTwoHalves ::
  ConstrainedRatioI IsOneHalf ->
  ConstrainedRatioI IsOneHalf ->
  ConstrainedRatioI IsOne
addTwoHalves i0 i1 = finalStep
  where
  curryFirstArg ::
    Between0And1 ->
    ( forall (c :: ConstrainedRational).
      AddConstraint
        IsOneHalf
        IsOneHalf
        c =>
      (ConstrainedRatioI c)
    )
  curryFirstArg = invoke zeroToOneAdder i0

  finalStep ::
    forall (c :: ConstrainedRational).
    AddConstraint
      IsOneHalf
      IsOneHalf
      c =>
    ConstrainedRatioI c
  finalStep = invoke curryFirstArg i1

The amazing thing here is that, when you give the function a signature, the type of the return value has to be ConstrainedRatioI IsOne. Try it out yourself - if you put any other constrained rational as the return value, the program won't compile. That means that, just by solving type constraints supplied by AddConstraint, the PureScript compiler is smart enough to follow two constrained values through the insides of our addition function and know what constrained is supposed to come out the other side.

How?

Type-level programming in PureScript is just straight-up programming, no more, no less. All of the things I'm about to show you (kinds, functional constraints, type classes etc) take a while to fully understand, but for the purpose of this blog, the most important thing to grok are the equivalencies in a hand-wavy way.

In normal-land, this is how you'd define the Peano representation of the integers.

data Peano = Zero | Succ Peano

In type-level programming, you do the same thing using kinds.

foreign import kind Peano
foreign import data Zero :: Peano
foreign import data Succ :: Peano -> Peano

Next, onto functions. To define addition on the Peano integers, you can do (for example):

add :: Peano -> Peano -> Peano
add Zero x = x
add (Succ x) y = (Succ (Add x y))

Same thing in type classes:

class Add (a :: Peano) (b :: Peano) (c :: Peano) | a b -> c
instance addZero :: Add Zero b b
instance addSucc :: Add a b => Add (Succ a) b (Succ c)

Let's see how we'd implement a series of functions

mul :: Peano -> Peano -> Peano
mul Zero x = 0
mul (Succ x) y = Add (Mul x y) y

Same thing in type classes:

class Mul (a :: Peano) (b :: Peano) (c :: Peano) | a b -> c
instance mulZero :: Mul Zero b b
instance mulSuc :: (Mul a b c, Add c b d) => Add (Succ a) b d

For more information on what's going on under the hood, check out this post, which is where I learned to do all this stuff.

So that's it. When doing type-level programming in PureScript, you have access to recursive functions, pattern matching, and data constructors. What more does one need? If it weren't for that pesky varmant I/O, you could write your entire program just using types. But because my audio project will have I/O (ie a microphone and a speaker), you need some form of input validation and coersion to output. As we saw above, that's doable with invoke.

Type-level programming in PureScript is lots of fun, and the community is implementing helpful things to make it easier all the time. After sprucing up this library a bit and adding more numeric features, I hope to get some killer WebAudio-API-music flowing through it!

Profunctors are everywhere!

Mike Solomon — Mon, 31 Aug 2020 08:42:14 +0000

Profunctors are a really useful abstraction. It took me a while to understand what they are, but once I did, I found myself using them in contexts as diverse as digital signal processing, server building and data mining.

In this article, I'd like to share the intuition I've built up about profunctors. The way I learned these things is by studying how profunctors can be used to create optics. By the end of the article, I hope you'll see the value of using profunctors and optics in your day-to-day work!

What's a profunctor?

In short, a profunctor fulfills three criteria:

It has input and output.
You can bolt on something to the "output" end to modify the output.
You can bolt on something to the "input" end to convert input.

If this sounds like a function, it's because functions are profunctors! Let's see how.

A function has input and output. In JavaScript, (a) => a * 3 maps input, like 5, to output, like 15.
We can bolt something to the output. (b) => ((a) => a * 3)(b) - 5 takes our original function and, for the same input 5, now returns 10 instead of 15.
We can convert input. (b) => ((a) => a * 3)(b + 1) takes our original function and, for the same input 5, now returns 18 instead of 15.
(bonus) We can convert input and modify output at the same time. (b) => ((a) => a * 3)(b + 1) - 5

Profunctors are not just functions. Profunctors are a general way to conceive of IO. This is why I find them so useful. As programmers, we deal with IO on a micro-level (ie chaining functions) and a macro-level (ie chaining audio plugins) all the time.

In PureScript, the function that performs the operation above is called dimap and it works like this:

dimap input output profunctor == new_profunctor

The four JS examples above can be written in PureScript as follows:

dimap identity identity ((*) 3)
dimap identity (flip (-) 5) ((*) 3)
dimap ((+) 1) identity ((*) 3)
dimap ((+) 1) (flip (-) 5) ((*) 3)

For the remainder of the article, we'll focus on one profunctor that I'll affectionately call "The Plus One Server". It takes a number and returns the number + 1. In JavaScript, (a) => a + 1. In Python lambda a: a + 1. In Brainfuck >+[-<+>]<. You get the idea.

Let's say that we've written "The Plus One Server" (aka ((+) 1.0)) and we now learn that it needs to accept and return a string. The temptation may be to do something like this:

const original = (a) => a + 1.0
const modified = (a) => `${original(parseFloat(a))}`
modified("3.1416") // "4.1416"

Thinking profunctorially, we can do it like this in PureScript:

original = ((+) 1.0)
modified = dimap readFloat show original
modified "3.1416" -- "4.1416"

readFloat changes a string to a number, show changes a number to a string, and ((+) 1) is my profunctor.

The difference between the JS and PureScript versions is subtle but important. The first sends us on the path to spaghetti code, and the second leads to organizing things in a clean, maintainable way.

To see why, imagine that the boss comes along and she says "Hey, coder person, your plus-one server needs to accept UTF8 byte strings and return byte strings." No prob, profunctors to the rescue!

original = ((+) 1.0)
modified = dimap readFloat show original
bossMadeMe = dimap fromUTF8 toUTF8 modified

In the JS version, we'd have to constantly dip into the internals of the function to make changes, whereas here, we just bolt converters onto both ends and we're done with it.

Let's now imagine that the boss, ever fickle, decides to keep the output format as String. No problem!

original = ((+) 1.0)
modified = dimap readFloat show original
bossMadeMe = dimap fromUTF8 identity modified

So far, I've glossed over the profunctor-ness (profunctor-iality? profunctor-tude?) of ((+) 1.0), but it's time to address that. Let's see how dimap is implemented for functions:

class Profunctor p where
  dimap :: forall s t a b. (s -> a) -> (b -> t) -> p a b -> p s t

instance profunctorFunction :: Profunctor Function where
  dimap input output function = output <<< function <<< input

At Meeshkan, we work a lot with IO (we're in the business of testing servers), so having "the server typeclass" (aka Profunctor) is invaluable as we build up mock servers from primitives.

Our first profunctor optic - Iso

If you look at the signature of dimap, you can read it a few different ways. One way is that it returns a profunctor p s t. But another way, and one that is closer to that of map, is that it returns a function between profunctors p a b -> p s t. When s == t and a == b, another way to look at dimap (s -> a) (a -> s) is that it has the potential to create an isomorphism between s and a, ie converting a map to a list of tuples and back again. In this case, and if there is no funny business (ie deleting entries), the two can be used interchangeably.

In lens-land, dimap is called iso for this reason.

iso :: forall p s t a b. Profunctor p => (s -> a) -> (b -> t) -> p a b -> p s t
iso = dimap

I'll also rebrand the signature p a b -> p s t as an Iso so that it's easier to understand the contract. Meaning that if you give me (s -> a) -> (b -> t), I'll give you back a p a b -> p s t.

type Iso s t a b = forall p. Profunctor p => p a b -> p s t

iso :: forall s t a b. (s -> a) -> (b -> t) -> Iso s t a b
iso = dimap

In general, a profunctor optic is a function with the signature p a b -> p s t.

You may be wondering, "Why are there two names for that thing profunctors do - dimap and iso?" The reason is because the profunctor of implementation of optics came about after optics were invented. The genius of the profunctor implementation is that one of the classic optics - Iso - is the dimap function.

dimap readFloat show ((+) 1.0) "3.1416" -- "4.1416"
iso readFloat show ((+) 1.0) "3.1416" -- "4.1416"

A stronger profunctor

Now, imagine that "The Plus One Server" is getting used more and, as is natural with servers, we want to hook it up to other services. While other "more sophisticated" services have some sort of logging, our mighty ((+) 1.0) lacks logging capabilities. So how can "The Plus One Server" take logs from upstream services and pass them to downstream services?

(dimap
  (\(Tuple s myLog) -> Tuple (readFloat s) myLog)
  ((Tuple b myLog) -> Tuple (show b) myLog)
  ((+) 1.0))
  "3.1416" -- craaasssshhh

Wouldn't it be nice if we could just ignore the log? We'd need to beef up our profunctor with a bit more muscle so it can "carry" the log in addition to the payload. In short, we need to make our server stronger.

class Profunctor p <= Strong p where
  first :: forall a b c. p a b -> p (Tuple a c) (Tuple b c)
  second :: forall a b c. p a b -> p (Tuple c a) (Tuple c b)

And now, let's make The Plus One Server strong.

dimap
  (\(Tuple s myLog) -> Tuple (readFloat s) myLog)
  ((Tuple b myLog) -> Tuple (show b) myLog)
  (first ((+) 1.0))
  (Tuple "3.1416" "someLog") -- Tuple "4.1416" "someLog"

The function first upgrades ((+) 1.0) to carry the log from the input to the output.

So what does this have to do with profunctor optics? What if we want to carry a map back to the incoming object?

mapBackHome :: String -> Tuple Number (Number -> String)
mapBackHome s = Tuple (readFloat s) show

In the example above, show is our "map back" from readFloat. It tells us how to convert the input to the output. We call a function between strong profunctors a Lens when it carries a map back home.

lens :: forall p s t a b. Strong p => (s -> Tuple a (b -> t)) -> p a b -> p s t
lens inputWithMap server =
  dimap
    inputWithMap
    ((Tuple b backHome) -> backHome b)
    (first server)

Here's the type of Lens.

type Lens s t a b = forall p. Strong p => p a b -> p s t

So we could have written the above definition as:

lens :: forall s t a b. Strong p => (s -> Tuple a (b -> t)) -> Lens s t a b
lens inputWithMap server =
  dimap
    inputWithmap
    ((Tuple b backHome) -> backHome b)
    server

Because optics are functions, we can compose them. Let's see how that works with lenses and our server.

mapBackToString :: String -> Tuple Number (Number -> String)
mapBackToString s = Tuple (readFloat s) show

mapBackToUTF8 :: ByteString -> Tuple String (String -> ByteString)
mapBackToUTF8 s = Tuple (fromUTF8 s) toUTF8

(lens mapBackToUTF8 -- lens 1
  <<< lens mapBackToString) -- lens 2
  ((+) 1.0) -- server
  (withOctets pack [0xAB, 0xCD]) -- "4.1416"

Even though lenses allow a different output type, for the purposes of this tutorial, we're using Lens s s a a, which is defined as Lens' in purescript-profunctor-lenses. In general, when you "zoom out" from a lens, you want to get back to where you started, so Lens' is enough for most cases.

Although we're using our hand-rolled lens function above, it is exactly the same one as in purescript-profunctor-lenses with a slightly different name. They call it lens', and they use lens as a helper function to build lens'. Try subbing lens above out for Data.Lens.lens' and see for yourself!

Give us a choice!

So "The Plus One Server" is the talk of the town, and other devs are starting to notice. Some are a little bit angry because they've never asked for a ((+) 1.0) and now it is part of their stack. A colleague approaches us and says:

Congrats on your accomplishment with "The Plus One Server." But now it's everywhere downstream and I don't work with numbers. Can you just ignore my input when you see it?

Aiming to please, we see what we can do!

-- how I'll use The Plus One Server
dimap
  (\s -> Left (readFloat s))
  (either show identity)
  ((+) 1.0)
  "3.1416" -- craaasssshhh
-- how my colleague's data will pass through the server
dimap
  (\s -> Right "Hello")
  (either show identity)
  ((+) 1.0)
  "3.1416" -- craaasssshhh

How do we deal with this? We have a choice between two data types, and our server needs to be a profunctor that can adapt accordingly.

class Profunctor p <= Choice p where
  left :: forall a b c. p a b -> p (Either a c) (Either b c)
  right :: forall a b c. p a b -> p (Either c a) (Either c b)

Armed with Choice, we can build a server that can act on our data and pass through our colleague's data:

-- how i'll use The Plus One Server
(dimap (\s -> Left (readFloat s)) (either show identity) (left ((+) 1.0))) "3.1416" -- == "4.1416"
-- how my colleague will use my server
(dimap (\s -> Right "Hello") (either show identity) (left ((+) 1.0))) "3.1416" -- == "Hello"

Another choice we can make is whether to attempt the computation at all. If our server can process the information, great, and if not, we provide a sensible default.

sensibleDefault :: String -> Either String Number
sensibleDefault s = if isNaN (readFloat s) then Right s else Left (readFloat s)

In lens-land, this is called a Prism.

prism :: forall p s t a b. Choice p => (s -> Either t a) -> (b -> t) -> p a b -> p s t
prism to fro server = dimap to (either identity fro) (right server)

And we can use it for our server like this:

prism sensibleDefault show ((+) 1.0) "3.1416" -- == "4.1416"
prism sensibleDefault show ((+) 1.0) "not a number" -- == "not a number"

So prisms give us a choice thanks to the Choice profunctor

But what about security?

"The Plus One Server" is so hot that hackers have noticed it and are trying to reverse engineer it to understand its inner workings and exploit its vulnerabilities. The boss, dismayed, starts saying stuff like "we need to lock this thing down" and "does anyone here know about end-to-end encryption?"

Your colleagues scramble to implement a crude form of encryption:

dimap
  (\s password -> readFloat s))
  (\locked -> show (locked "passw0rd"))
  ((+) 1.0)
  "3.1416" -- craaasssshhh

So some upstream service "locks" our operation with a password, and they later unlock it with their super-secure password "passw0rd". Of course, we have no clue what to do with a function that takes a password and produces a number. Our humble server can only work with numbers! Unless we are armed with a Closed profunctor.

class Profunctor p <= Closed p where
  lock :: forall a b x. p a b -> p (x -> a) (x -> b)

A way to think about lock is that it delays application of our function until the point when a password is provided. Another way to imagine it is that it sends the function to the end-user and lets them apply it with their password. I would guess that this is the exact algorithm WhatsApp uses for their end-to-end encryption.

Back to "The Plus One Server", it can now handle password-protected data:

(dimap (\s password -> readFloat s)) (\locked -> show (locked "passw0rd")) (lock ((+) 1.0))) "3.1416" -- == "4.1416"

In functional-programming land, passwords can be anything. Strings, ints, aaannnd..... functions! Yes, passwords can be functions - but why would one do this?

A password "unlocks" our lock, so a function unlocking something would mean that it provides information for a computation to continue. For example, think about image processing. We have a killer algorithm to do something like Gaussian blur or masking, but we don't want to know how the user applies it to their picture. Their use of our algorithm is private, and this use is encoded in a function. We'll call this form of password-protection with a function a Grate.

-- Here, (s -> a) will be our "function" password
grate :: (((s -> a) -> b) -> t) -> p a b -> p s t
grate unlock server = dimap (\s f -> f s) unlock (lock server)

The types going to dimap are a bit hard to follow, so let's write dimap just using its types:

dimap
  (s -> (s -> a) -> a) -- input
  (((s -> a) -> b) -> t) -- output
  (p ((s -> a) -> a) ((s -> a) -> b)) -- internal profunctor
  -- yields p s t

We see that, all the way through, (s -> a) is our password for the closed profunctor. Or, subbing (s -> a) into the definition of Closed, we have:

class Profunctor p <= Closed p where
-- remembering that
-- lock :: forall a b x. p a b -> p (x -> a) (x -> b)
-- when using a function (s -> a), polymorphism turns this into
   lock :: p a b -> p ((s -> a) -> a) ((s -> a) -> b)

If your brain is hurting, rest assured that that's as heady as it gets. Now we can actually use our grate to do some password-protected art with the ((+) 1.0) server.

data RGB = RGB Number Number Number

red :: RGB -> Number
red (RGB r g b) = r

green :: RGB -> Number
green (RGB r g b) = g

blue :: RGB -> Number
blue (RGB r g b) = b

myFilter :: ((RGB -> Number) -> Number) -> RGB
myFilter = \f -> RGB (f green) (f blue) (f red)

grate mySecretFilterApplication ((+) 1.0) (RGB 1.0 2.0 3.0) -- == (RGB 4.0 2.0 3.0)

Our ((+) 1.0) server did its magic without ever knowing the inner workings of your algorithm. The "passwords" here were green, blue and red. When mixed with our ((+) 1.0), they produced a new pixel.

In general, when thinking about password protecting something or, more generally, hiding the application of an algorithm like the one above, closed profunctors and grates are your friend!

Make me a Star

We've now deemed "The Plus One Server" to be so useful that we want to use it with exotic optics that we've never even heard of. So far, we have only been dealing with optics that accept one profunctor - the function. But there are lots of nice profunctors, and we'd like to work with them somehow.

One such profunctor is the Kleisli profunctor. It is a profunctor with a side effect mixed in. So if you take the Function profunctor we've seen before a -> b, a Kleisli profunctor is that with a little something extra like write to a log, read from an environment or launch a rocket. The signature for a Kleisli profunctor, also called a Star, is:

newtype Star f a b = Star (a -> f b)

instance functorStar :: Functor f => Functor (Star f a) where
  map f (Star g) = Star (map f <<< g)

instance profunctorStar :: Functor f => Profunctor (Star f) where
  dimap i o (Star ft) = Star (map o <<< ft <<< i)

Here, f represents the side effect and b represents the output value. This could be something like Log Int or Array String or RocketLauncher Number.

I don't know why they call it Star, but it seems like a reasonable choice. I tried singing "Twinkle Twinkle Little Kleisli" to my kid and it didn't really work, so let's stick with Star.

Anyway, the boss wants to use an optic from Kleisli-Land, and we're responsible for getting it to integrate with our system. Our profunctor that makes a foray into Kleisli-land is called Wander.

class Profunctor p <= Wander p where
  wander :: forall s t a b. StarOptic s t a b -> Optic p s t a b

The first argument is an optic of star profunctors. The return value is also an optic, but one that can be used by any profunctor that implements Wander. Under the hood, our profunctor call the Kleisli (Star) optic. That means that it'll have to know how to add and remove a side effect - adding when it enters Kleisli-land and removing when it leaves.

The actual signature for Wander in purescript is a bit different. I'm not sure why they made it this way, but it is isomorphic to the one above and gets the job done:

-- real signature
class Profunctor p <= Wander p where
  wander :: forall s t a b. (forall f. (a -> f b) -> s -> f t) -> p a b -> p s t

To make this more concrete, let's look at the implementation of Wander for the Function profunctor.

instance wanderFunction :: Wander Function where
  wander kleisli ourfunc input = unwrap ((kleisli (Identity <<< ourfunc)) input)
  -- you can also use this, which is more concise
  -- wander t = alaF Identity t

For example, let's imagine that we got a Kleisli function that lifted a side effect from one operation to another. This is common when, for example, an operation fails for a part of a whole and you need to mark the whole as "failed".

type Client = { name :: String, balance :: Number}

actOnBalance :: forall f. Applicative f => (Number -> f Number) -> Person -> f Person
actOnBalance f p = { name: p.name, balance: _ } <$> f p.balance

When we try using with "The Plus One Server", it will predictably crash.

actOnBalance ((+) 1.0) { name: "Mike", balance: 0.0 } -- crasssshhhh

But if we make ((+) 1.0) effectful, it is able to wander into Kleisli-land by using Identity under the hood, as we saw above.

wander actOnBalance ((+) 1.0) { name: "Mike", balance: 0.0 } -- == { name: "Mike", balance: 0.0 }

Luckily, there is a whole category of functions that behave like actOnBalance. They're called traverse, and they work on types that implement the Traversable typeclass.

The basic contract with something implementing Traversable is that, if you have a container of values and you can produce a side effect for each value in the container, then you can accumulate the side effects. For example, if you have a List of Writer Int (meaning integers we're keeping some sort of log about), then we can get a Writer (List Int) by accumulating the logs for each Int.

Let's look at the signature for traverse:

traverse :: forall a b m t. Traversable t => Applicative m => (a -> m b) -> t a -> m (t b)

It is exactly the same as the first argument to wander, with s == t a and t == t b.

This means that we can create a utility for anything implementing Traversable.

traversal = wander traverse

Now, let's use it with our friend ((+) 1.0).

traversal ((+) 1.0) [1.0,2.0,3.0] -- [2.0, 3.0, 4.0]

Remembering that we can compose optics, let's use it with the lens from above:

(traversal
  <<< lens (\s -> Tuple (readFloat s) show))
  ((+) 1.0)
  ["1.0","2.0","3.0"] -- ["2.0", "3.0", "4.0"]

In summary, a profunctor implementing Wander allows us to take a stroll in Kleisli-Land, and it can be used in lots of different contexts. We saw two of them above - actOnBalance and the mega-useful traversal. Wander will be even more useful when we talk about folds.

Folding up values

So far, our workhorse profunctor has been the function, and even when we wandered into Kleisli-land, we did so to import our results back to the world of functions. Remembering that optics are functions between profunctors, when we give a Function to an optic as an argument, we call that a Setter. This is how "The Plus One Server" worked - it is a function (profunctor) that we passed to an optic (function acting on profunctors) and it set something on the inside of a larger structure (ie an array of integers in a traversal or a RGB channel in a grate).

While this metaphor is helpful, it is admittedly like a bad monad tutorial (sorry), in that it specializes the idea of profunctors too narrowly. Profunctors are a generalized way to reason about I/O, and there's more to I/O than just functions.

One thing that comes up a lot with I/O is intentionally suppressing the output. For example, you can ignore the output value and instead return something else. In Purescript, this is called Forget.

newtype Forget r a b = Forget (a -> r)

instance forgetfulProfunctor :: Profunctor (Forget r) where
  dimap f _ (Forget z) = Forget (z <<< f)

instance forgetfulStrong:: Strong (Forget r) where
  first (Forget z) = Forget (z <<< f <<< fst)
  second (Forget z) = Forget (z <<< f <<< snd)


dimap (const true) (const 42) (identity) "3.1416" -- 42
dimap (const true) (const 42) (Forget identity) "3.1416" -- Forget true

We catch the input (true) and forget about the output.

A Fold is a profunctor optic that is evaluated with a Forget profunctor. A Getter is a special fold that uses the identity function as its accumulator. Let's build up view defined in purescript-profunctor-lenses step by step.

lens i = dimap i ((Tuple b f) -> f b) <<< first
lens (\a -> Tuple (readFloat a) show) (Forget identity) "3.1416" -- Forget 3.1416
forgetForget (Forget f) = f
forgetForget $ lens (\a -> Tuple (readFloat a) show) (Forget identity) "3.1416" -- 3.1416
view profunctor = forgetForget (profunctor (Forget identity))
view $ lens (\a -> Tuple (readFloat a) show) (Forget identity) "3.1416" -- 3.1416

Our view function below is isomorphic to the one you'll find in purescript-profunctor-lenses. It's quite concise!

The issue with Forget is that it can't forget something that doesn't exist. For example, let's try to make Forget an instance of Choice.

instance forgetChoice :: Choice (Forget r) where
  left (Forget f) = either (Left <<< f) ??? -- craaashhhh
  right (Forget f) = either ??? (Right <<< f)  -- craaashhhh

The problem is that we can't pass through a b because we're forgetting it - we just have a and r. So how can we get around this? When we don't have an a for (a -> r), we need to be able to pull an r out of thin air. What is the typeclass of things where you can pull one out of thin air? The monoid! The function to do that is mempty

mempty :: String -- == ""
mempty :: List -- Nil
mempty :: Array -- []
mempty :: Maybe Int -- Nothing

So as long as r above is a monoid, we can have our Choice profunctor.

instance forgetChoice :: Monoid r => Choice (Forget r) where
  left (Forget f) = either (Left <<< f) (Right mempty)
  right (Forget f) = either (Right mempty) (Right <<< f)

The same trick works for Wander but on a functor application level. Again, r will be a monoid, and the Const functor will "pull an r out of thin air" if not provided one.

instance wanderForget :: Monoid r => Wander (Forget r) where
  wander f (Forget r) = Forget (alaF Const f r)

instance applicativeConst :: Monoid a => Applicative (Const a) where
  pure _ = Const mempty -- "out of thin air"

So, when you try to preview a value from an empty list using a lens library as we do below, you get Nothing because:

the Wander instance of forget uses the Const profunctor
the Const profunctor, when used in List's implementation of traverse, starts with a pure const (getting an mempty, or a Nothing in this case)
as there is nothing to smoosh, it returns Nothing

preview traversed (Nil :: List Int) -- Nothing

Going back to Kleisli-land, the Const functor is the side effect that allows us to Wander into a Star profunctor (in this case, the function traversal), get its benefits, and bring them back home to our optic.

tl;dr

When building a server (when using a profunctor), here are some cool optics:

An iso is a profunctor whose input and output are isometric to some other value.
A lens is strong 💪 enough to drill down into a value and carry a map so we know how to get back up.
A prism gives us a choice 🤷‍♂️ between a value and a sensible default if we can't process the value.
A traversal allows us to wander 🏃‍♀️ into Kleisli-land and back to do our bidding
A grate allows us to lock 🔒 our optic and unlock it with a key, where the key is a function

And as optics are just functions from profunctor to profunctor, here are two profunctors you can use with optics:

The Function profunctor (a -> b), which is called Setter, and whose magic we've seen in "The Plus One Server."
The Forget profunctor, that accepts a's and "forgets them" in a recepticle called r, ignoring the output b. A forget that maps a to itself is called a Getter, aka Forget identity. The general operation is called a Fold.

Remember, these are just representations of the concept of optics. There are many ways to build up optics, and the profunctor one is one way. It is my favorite way because it gives you an expressive vocabulary to solve problems. At Meeshkan, we use custom optics and profunctors all over the place for different business cases, and the nice thing about the PureScript community is that we can share these solutions and get their feedback.

In this post, I've tried to build up intuition about what profunctors are and show how lenses are derived from them. Usually, when I use a library like purescript-profunctor-lenses, I'm happy just to use the library without understanding what's going on under the hood. However, the concepts used to implement profunctor lenses are so useful/universal that they're worth exploring in their own right. I hope they help you too as you solve new and exciting challenges!

Launching first-class support for automated GraphQL testing

Makenna Smutz — Wed, 26 Aug 2020 13:28:17 +0000

GraphQL is the future of APIs that we at Meeshkan, are investing in. Today we are announcing our full focus on automated testing of GraphQL servers.

If this is your first time hearing about Meeshkan — we're an automated testing service for the backend of your app using NLP and property-based testing. This announcement is us focusing deeper on developing future features unique to GraphQL testing. We wholeheartedly believe in the benefits the technology brings, as well as the need for better testing of GraphQL APIs.

Does this sound interesting to you? -> Create a free Meeshkan account

In this post, we'll walk through what led us to bet our whole company's future on this technology - and how that affects you and your testing workflow!

The evolution of API technology
Why we believe GraphQL will become the standard choice for building new APIs
What does first-class GraphQL server testing look like?
How automated GraphQL tests work on your server
Benefits of using Meeshkan with your GraphQL API vs your REST API
The future of testing GraphQL as Meeshkan sees it

The evolution of API technology

Modern web APIs entered into the development world in 1999 in numerous implementations. One of the first business APIs, Salesforce debuted it's XML is also known as SOAP API in 2000.

RESTful

In the same year, Roy Fielding and a few colleagues created a standard for APIs now regarded as REST. The doctoral dissertation detailing REST's standards was created with the input of the development community. It contained several features that are critical/common practice today, such as:

Using HTTP verbs (GET, PUT, POST, DELETE)
Stateless-ness (not containing context other than the specific request being made)
Cache-ability

The motivation was to give APIs a common set of standards to rally around and improve as a singular community. The vast majority of production APIs today were originally built following the REST specification (and most are still).

There are several challenges that the REST APIs afford. One of those challenges relates to testing — the lack of generated documentation.

Documentation is important for developers (internal or external) using the API. Many teams with REST APIs use OpenAPI or Swagger as a set of rules that describes the format of their REST API. This is great for understanding what the API is capable of without reading the code. It also provides the structure to create mock APIs to test against. OpenAPI specifications have great tooling but are brittle to API changes if manually created — which is common practice.

GraphQL

The initial prototype of GraphQL came to life in 2012 as a side project by a few Facebook developers. These developers were facing challenges with their existing Newsfeed REST API. The static specification draft was released in 2015 and warmly embraced by the development community. The API specification was designed for the developer who'd be using the API at the core focus and dealing with the technology to make it work after.

Following the design, the features that the GraphQL specification landed include:

Hierarchical nesting: Deeply defining the association of the data stored.
Strongly typed: GraphQL types allow the client to predict what the query will return without knowing that much about the server.
Introspection: Access to the entire type system/specification of a schema based on its endpoint.

Remember GraphQL introspection. It will become important when speaking about automated testing of GraphQL APIs.

Introspection | noun | the examination or observation of one's own processes.

Using an introspection query, we can conclude the GraphQL schema contents and types. With this ruleset of how the API should act and some Natural Language Processing magic — we're able to generate meaningful tests.

For some more history of GraphQL, Honeypot.io has created an insightful documentary:

Why we believe GraphQL will become the standard choice for building new APIs

Processes as precedented as creating an API are resistant to change. Thankfully at the core, the two technologies are very similar. Both REST and GraphQL send an HTTP request and receive a response. GraphQL has many elements of the REST standard built into its functionality with upgrades to its developer experience.

As a company that has been focused on testing, mocking, and use of APIs for the past few years, GraphQL has been on our radar for a while. And several of our team members were early adopters of GraphQL.

We as a team are now bought into the GraphQL ecosystem in our own stack using 8base as our database. It's a MySQL database with a GraphQL API and a beautiful UI - but the preconfigured endpoint that we could query against was the decision settler.

Another sign that GraphQL will continue to be in the stack-of-choice is the growing number of software industry leaders making exactly that choice. GitHub, one of the largest and most used developer tools, has a great GraphQL API and built-in documentation.

What does first-class GraphQL server testing look like?

The first thing to clarify is that several parts of a GraphQL API that can be tested. The GraphQL query (including queries, mutations, and subscriptions), the GraphQL resolver, and the GraphQL server.

Depending on how you build your GraphQL schema, there are different parts of testing that could serve your team:

If you use a service such as GraphCMS or 8base - they take care of building and managing the resolvers and server for you. If this is your case, it'd be most helpful to encourage your provider to use Meeshkan as your tests would need to be frontend focused.
If you've built your GraphQL API from scratch using something like Prisma or Apollo, you're in charge of maintaining all three parts of the API. Meeshkan is currently a tool for the resolvers and the server-side of your API. We make sure your auth is impenetrable and there aren't loopholes such as data accepted that will crash the server and more.

At Meeshkan, committing to first-class support means making decisions about data science algorithms, communities to invest in, and testing capabilities — with GraphQL at the focus. Possibly at the detriment to existing REST focused algorithms, other communities that might be interested in using Meeshkan, and the ability to test other API types. Of course, we keep a close eye on the divergence, but rest cough 🤷‍♀️ assured if you're building with a GraphQL API, we're dedicated.

Some things we are exploring on our roadmap

How automated GraphQL tests work on your server

Using your GraphQL endpoint, Meeshkan dynamically generates and executes a series of property-based tests. There are a lot of moving pieces here that I want to break down the mechanics of.

First, when importing a project into Meeshkan, you're asked for either the location of your Open API specification and/or your project's GraphQL endpoint.

If you're in the middle of a migration from REST to GraphQL or need to authenticate in REST but work with GraphQL, we support testing with both APIs in tandem!

The biggest challenges of automated software testing are dynamically generating tests as the code changes and making sure those tests are meaningful and high quality.

Our approach to this challenge is to base off of a concrete set of rules (in this case the GraphQL schema) and build from there. We use Natural Language Processing to generate reasonable inputs for fields with names like email and password. Starting from a certain (yet dynamic) base assures we know the results are actual, production reproducible scenarios.

Benefits of using Meeshkan with your GraphQL API vs your REST API

Alongside the benefits of using a GraphQL API, there are several benefits of the inherent structure and functionality that make it more compatible for testing.

GraphQL APIs are strongly typed. And while we are big fans of strongly typed patterns in programming at Meeshkan, I digress. The native feature of a GraphQL schema, called introspection, allows the entire type structure and relationships to be queried on-demand, and dynamically as the API evolves.

Another feature that provides testing value, is the documentation of relationships. One feature we're passionate about at Meeshkan is stateful testing. We believe that for your tests to be meaningful, they should replicate a user in the wild — also known as your production app.

Most tools that automatically test your app, read the code statically, and make inferences. Meeshkan imitates a user with our integration tests. Stateful tests create users with traceable/reproducible steps that center around logic-heavy functions in your app. Some examples where stateful testing is invaluable include authorization, authentication, and transactions (currency, databases, etc).

GraphQL stores information about how mutations relate to queries. This gives confidence to our stateful testing algorithms.

For example, tests can be traced to createTest and createManyTests. With a REST API, there are common patterns that our NLP algorithms can pick up — but assumptions make for a lot less confident tests. For more complex relationships, we support custom GraphQL directives.

The future of testing GraphQL as Meeshkan sees it

I'm super stoked to finally announce what we've been brewing internally and working with early adopters. We've got a vision that testing should be intertwined into your dynamic coding workflow, rather than a disconnected, skippable step. We're working hard to achieve this - starting in integration testing.

We're energized by the GraphQL community and the future that we can help developers achieve. A future where 'to test or not to test' is no longer a difficult decision.

Next steps

Allowing you to connect your client to test queries, mutations, and subscriptions used in production.
Creating explicit test cases where you define the queries you'd like to run each test
Monitoring auth (authentication and authorization) rules, notifying when a user scope has changed
Is there something that you'd like to see in your testing workflow? We want to hear from you!

Extension types in TypeScript

Mike Solomon — Thu, 06 Aug 2020 16:15:15 +0000

When creating a TypeScript library, you will invariably run into a scenario where someone wants to extend it. In JavaScript land, they can do this with the following hack:

const yourLibrary = require('your-library');
const myExtension = require('./my-extension');
yourLibrary.yourObject.myExtension = myExtension

In TypeScript, this type of thing is generally frowned upon because the type system will not (easily) allow monkey patching. The “classic” workaround is using a cast to the any type, which effectively de-TypeScript-ifies TypeScript.

import { yourObject } from 'your-library';
import myExtension from 'my-extension';
(<any>yourObject).myExtension = myExtension

The other problem with this pattern is that it myExtension is not referenceable on yourObject, which requires a cast on every access as well.

const result = (<any>yourObject).myExtension.myFunction();

At this point, we have lost the type-safety of myExtension. So the TypeScript compiler will no longer check that myFunction actually exists on myExtension, let alone what the result of myFunction() is. Too much of this pattern will render your TypeScript project un-typeable, at which point JavaScript would have been a better option.

What to do?

One solution is just to make a pull request to the original library to have your extension incorporated into its official package. While this may be a good idea in some scenarios, in most cases extensions are too niche, too broken or too big to be merged into a project. On top of that, pull requests often take a long time to go through review and incorporation into a new release.
Another solution, which is what this article advocates, is building libraries with type-safe extensions as first-class citizens. I realize that this won’t solve your problem here-and-now, but if you are a library author, it will give other developers an easy way to extend your work without necessarily touching the core package. If you are a consumer of a library, a pull-request giving it extensional properties is usually a much easier ask than extending the library with your specific feature.

Two types of extensions

The most common types of extensions developers need are intersection extensions and union extensions. Intersection extensions say “Hey, your objects are awesome, but they would be even more awesome if they did thing X.” Union extensions say “Hey, your objects are awesome, but you’re missing a few that I’d need for scenario Y.” Intersections and unions are part of TypeScript’s core language — the intersection & and union | operator are a basic way to build composite types. What I’m advocating is leveraging these operators to supercharge your libraries with extensionality.

Intersection extensions

Intersection extensions can be achieved with a generic type (let’s call it U) that is passed down through your objects and intersected with primitive objects via the & operator.

Let’s imagine that your library contains the following two types.

type Person = {
  name: string;
  address?: Address;
  friends?: Person[];
}
type Address = {
  city: string;
  country: string;
}

Intersection extensions add an intersection to all relevant types.

type Person<U> = {
  name: string;
  address?: Address<U>;
  friends?: Person<U>[];
} & U;
type Address<U> = {
  city: string;
  country: string;
} & U;

For example, if we want to add an optional id to all types, it becomes a simple operation.

const me: Person<{id?: number}> = {
  name: 'Mike',
  address: {
    id: 5,
    city: 'Helsinki',
    country: 'Finland'
  },
  friends: [{ name: 'Marie', id: 101 }]
}

Even better, we now have a type-safe accessor for id, so the following function will pass the TypeScript compiler

const hasId = (p: Person<{id?: number}>) => typeof p.id === 'number';

Union extensions

Let’s imagine a different scenario — we are creating types for JSON objects.

type JSONPrimitive = number | boolean | string | null;
type JSONValue = JSONPrimitive | JSONArray | JSONObject;
type JSONObject = { [k: string]: JSONValue; };
interface JSONArray extends Array<JSONValue> {}

Let’s say that we would like JavaScript Date objects to also be admitted as JSON. Union extensions, which I’ll represent with the letter T, give us a clean way to do this.

type JSONPrimitive<T> = number | boolean | string | null | T;
type JSONValue<T> = JSONPrimitive<T> | JSONArray<T> | JSONObject<T>;
type JSONObject<T> = { [k: string]: JSONValue<T>; };
interface JSONArray<T> extends Array<JSONValue<T>> {}

Now, we can put Date objects all over our JSON and the TypeScript compiler will not complain.

const jsonWithDates: JSONValue<Date> = {
  foo: 1,
  bar: new Date(),
  baz: [true, 'hello', 42, new Date()]
}

Runtime validation

If you are using a runtime type validator like io-ts, the patterns are quite similar. For intersections, we can use the intersection function from io-ts.

import * as t from 'io-ts';
const PersonValidator = <U>(u: t.TypeOf<U, U>) = t.recursion(
  'Person',
  t.intersection([
    t.type({name: t.string}),
    t.partial({
      address: AddressValidator(u),
      friends: t.array(PersonValidator(u))
    }),
    u
]));
const AddressValidator = <U>(u: t.TypeOf<U, U>) = 
  t.intersection([
    t.type({city: t.string, country: t.string}),
    u    
  ]);

The same type of pattern can be used for union types — just pass the a validator to t.union instead of t.intersection where needed.

Show me the code!

This is the strategy I used to build json-schema-strictly-typed, which creates a typed version of JSON Schema that is extensible with both intersection and union extensions. This way, people can add arbitrary extensions to objects in the Schema (intersection) and arbitrary new Schema primitives (union).

From this level of generic-ness (genericity?, generickitude?), it is easy to export helper objects for “base” cases. The base case of an intersection extension is simply a type from which all your objects already extend. In the example above, Person<{}> and Address<{}> would be this, as intersecting with {} is a no-op. For union types, a default extension could be extending the library with a type that already exists in the union. So, for example, JSONSchemaValue<string> is a no-op.

I’m looking forward to seeing if this pattern catches on and if the community can come up with tools that help maintain and author TypeScript libraries with extensibility in mind!

Kotlin tests and user stories

Mike Solomon — Thu, 06 Aug 2020 16:12:22 +0000

I love stories. I love tests. And I really love tests that read like stories.

My journey into the poetic world of writing tests like stories starts with a talk by Jake Wharton about robot testing. Wharton argues that tests should read like instructions to a robot on how to use your app. The benefits of his approach go beyond the human-readability of a testing spec. Writing hybrid story/tests enforces a form of rigor that forces one to take a step back and think about how one truly wants users to interact with an app. This invariably leads to a cleaner design and less cruft.

This way of authoring tests has recently become a bit of an obsession. So much so that I have dispensed with functional syntax and begun writing my tests using prose. Think OuLiPo plus Larry Wall.

“How does the whole thing work?” you may ask. Imagine we were writing a payment app. The code below would constitute a syntactically-valid Kotlin test.

First sign into your console.
 Then check your point balance. There should be fifteen points.
 Then use all of your points to buy a ticket to Guam that costs exactly the number of points you have.
 Then check your point balance. It should now be zero.

Kotlin makes the example above possible thanks to the infix keyword. I have provided below the same example with all of the infix functions needed to create syntactically correct Kotlin.

You see that some functions above contain placeholder comments to verify the various bits of business logic that we are testing. This allows us to decouple the actual functions we are testing from their semantic meaning. It also reduces the ambiguity of intent even though it requires a fair amount of boilerplate. Even the boilerplate can be mitigated to a certain extent by scripts that transform prose into code.

Robot tests are not the only situations where Kotlin-interpretable prose can prove useful. Devto articles work as well.

Create a mock server for any REST API

Carolyn Stransky — Thu, 06 Aug 2020 15:38:41 +0000

If you make a REST API call from your codebase then there's a good chance that, at some point, you'll want to write a test for that integration. Instead of calling the real API, it might make sense to use a mock. But manually stubbing data can be time-consuming and doesn't lead to a high level of confidence.

That's where this tutorial comes in.

In this tutorial, you'll learn how to create a mock server for any REST API. This mock server will generate dynamic, type-based response data that you can use in your tests. You'll do this using the HTTP Mocking Toolkit (HMT), a tool that mocks HTTP APIs for use in automated and exploratory testing.

As an example, this tutorial uses the Studio Ghibli API, which catalogs the worlds created by Japanese anime studio Studio Ghibli. Why Studio Ghibli? Because they RULE!

✅ Steps:

Collect recordings of your API's traffic
Build an OpenAPI specification from your recordings
Mock server traffic using your specification

⚠️ Prerequisites:

Python 3.6+ installed (no previous Python knowledge is necessary, it's only for installing HMT)
Familiarity with REST APIs and how they work
Comfort using the command-line

💻 References:

There's a GitHub repository that contains a completed Studio Ghibli mock server. You can use it as a reference for this tutorial.

Initial setup

Before building the mock server, you first need to create a project directory. This will house your recordings and specifications (explained later in this tutorial).

Let's do this in the terminal and name it studio-ghibli-mock-server:

mkdir studio-ghibli-mock-server
cd studio-ghibli-mock-server

(Optional) Create a virtual environment

Using a virtual environment can help keep your packages organized and ensure that you have the correct Python version. For this example, you'll name yours .aichienv based on the location of the new Studio Ghibli theme park.

First, run the following script to set up a venv directory:

python3 -m venv .aichienv

Then, launch your virtual environment:

source .aichienv/bin/activate

Finally, check your Python version with python --version. It should be version 3.6 or higher.

Whenever you're done, you can terminate the virtual environment by running: deactivate

Install HMT

You can install HMT on the command line using pip, a package installer for Python:

pip install hmt

For HMT to install and run properly, it requires Python version 3.6+

Check your HMT version with hmt --version to make sure the command-line interface (CLI) is installed.

1. Collect recordings of your API's traffic

The first step towards creating a mock server is to collect recordings of your API's traffic. That way, our future mock server will know what types of data to mimic.

Using the record mode, the HMT CLI can be used to record HTTP API traffic in a format that you can later build into a specification.

Start HMT

To start an HMT server that will record your API traffic, use the hmt record command:

hmt record

This starts HMT as a reverse proxy on the default port of 8000.

To stop HMT without losing any of your data, type Ctrl + C or another kill command.

Keep this running. Then, in another terminal window, you can use HMT as a proxy with curl.

By default, HMT uses path routing to intercept HTTP API calls. Path routing appends the URL you wish to call (https://ghibliapi.herokuapp.com/) to the end of the URL of the recording server (http://localhost:8000/):

curl http://localhost:8000/https://ghibliapi.herokuapp.com/

HMT will automatically make an API call using the URL in the path - in this case, https://ghibliapi.herokuapp.com/ - and return the response from the called API.

Run API-specific curl commands

In order for HMT to later mock your API, it needs to understand what kinds of endpoints exist and the associated responses to expect. One way to feed it that information is by using curl.

There's no minimum or maximum number of calls you should make in order for HMT to accurately record your API traffic. You have to feel it out. A general rule is that you want to record every critical endpoint at least once.

With the Studio Ghibli API, there's five main endpoints: Films, People, Locations, Species, and Vehicles. You'll want to make sure to call each of those.

The example in the reference repository alternates between calling the root endpoint and calling a specific field within that endpoint. For thoroughness, here's exactly what was tested:

# Films
curl http://localhost:8000/https://ghibliapi.herokuapp.com/films

# Film - Castle in the Sky
curl http://localhost:8000/https://ghibliapi.herokuapp.com/films/2baf70d1-42bb-4437-b551-e5fed5a87abe

# People
curl http://localhost:8000/https://ghibliapi.herokuapp.com/people

# Person - Granny (My Neighbor Totoro)
curl http://localhost:8000/https://ghibliapi.herokuapp.com/people/08ffbce4-7f94-476a-95bc-76d3c3969c19

# Locations
curl http://localhost:8000/https://ghibliapi.herokuapp.com/locations

# Location - Irontown (Princess Mononoke)
curl http://localhost:8000/https://ghibliapi.herokuapp.com/locations/11014596-71b0-4b3e-b8c0-1c4b15f28b9a

# Species
curl http://localhost:8000/https://ghibliapi.herokuapp.com/species

# Species - Cats
curl http://localhost:8000/https://ghibliapi.herokuapp.com/species/603428ba-8a86-4b0b-a9f1-65df6abef3d3

# Vehicles
curl http://localhost:8000/https://ghibliapi.herokuapp.com/vehicles

# Vehicle - Sōsuke's Boat (Ponyo on the Cliff by the Sea)
curl http://localhost:8000/https://ghibliapi.herokuapp.com/vehicles/923d70c9-8f15-4972-ad53-0128b261d628

Check the recordings file

Running hmt record will automatically generate two directories: logs and specs.

By default, HMT records all traffic to the logs directory in a file called {hostname}-recordings.jsonl. {hostname} refers to your API's host URL and in this case, that's ghibliapi.herokuapp.com.

How it works is that HMT takes the recorded server traffic and serializes them as JSON objects in the http-types format. Then, this is written to a JSON Lines file.

This specific formatting and file type is required for HMT to be able to build an OpenAPI specification in the next step.

2. Build an OpenAPI specification from your recordings

Using the HMT CLI, you can build an OpenAPI specification that describes how your API works. This is built from that .jsonl file generated by the record command.

On the command-line, you'll run hmt build with the --input-file flag followed by the path to your recordings file:

hmt build --input-file logs/ghibliapi.herokuapp.com-recordings.jsonl

This uses the default build command. To see the other options, run hmt build --help or check out the HMT build documentation.

By default, HMT builds a new OpenAPI specification (called openapi.json) in the specs directory from earlier. Once you've generated the specification, you can use that to create a mock server.

3. Mock server traffic using your specification

Now you can use your openapi.json and a different HMT command to create a mock server.

All it takes is hmt mock followed by the path to the directory or file where your OpenAPI specification is (for this example, that's specs/):

hmt mock specs/

Keep this running. Then, in another terminal window, make another curl request:

curl http://localhost:8000/https://ghibliapi.herokuapp.com/people/08ffbce4-7f94-476a-95bc-76d3c3969c19

Yes, you read that right - it's almost identical to the command that you ran earlier after launching hmt record.

This is the same command we ran in the second step for Granny from My Neighbor Totoro. But our server won't return Granny's exact data. Instead, it'll return the same character response fields from the Studio Ghibli API with mock data for the values based on their types.

Here's an example of what this response could look like:

{
  "id": "Bradley Joseph",
  "name": "Jeremy Vasquez", 
  "gender": "Jodi Francis", 
  "age": "Karen Booth", 
  "eye_color": "Andre Mcclure", 
  "hair_color": "Brandon Freeman", 
  "films": [
    "Stephanie Campbell", 
    "Paul Young", 
    "Catherine Gonzalez DDS", 
    "Charles Dean", 
    "Jackson Smith", 
    "Alexander Manning", 
    "Anthony Reed"
  ], 
  "species": "Jasmine Davis",
  "url": "David Olson"
  }

Because this data is generated, there's a good chance that yours will be different if you're following along. Although the strings almost always seem to be random names 😅

There you have it, your very own mock server 🎉

Conclusion

This tutorial ran through the entire HMT flow: Collect, build, and mock. First, you collected data by recording server traffic from the Studio Ghibli API. Then, you built an OpenAPI specification based on that data. Finally, you used that specification to spin up a Studio Ghibli mock server.

If you want to see the code for the final mock server, check out the example repository on GitHub.

There are many customization options for your mock server - such as custom callback scripts, format options, and response types. You can find out more in the HMT documentation.

HMT is actively maintained by our team at Meeshkan. It's also open-source 🎉 If you run into any problems with the product or have questions, please open an issue on GitHub.

Finding and fixing bugs in your tests with fast-check

Carolyn Stransky — Mon, 27 Jul 2020 13:59:20 +0000

This post assumes that you have a solid understanding of JavaScript. You should also know the basics of property-based testing and the fast-check framework.

Recently, we published Property-based testing for JavaScript developers. In it, we introduced an issue to show the limitations of example-based testing. Throughout the rest of the guide, we provided examples of how to use fast-check and other property-based testing principles.

But we didn't offer a fix to that initial testing bug.

We've been told that this is unsatisfying, so consider this post our redemption.

💻 The tests featured in this post are available in the corresponding GitHub repository.

Summary of the bug in our test

If you're already familiar with the referenced issue, skip to the solution.

Imagine you have an input where users write in a price - but this input is type="text" rather than type="number". So you need to create a function (getNumber) that converts the input string into a number and an accompanying test:

const getNumber = inputString => {
  const numberFromInputString = Number(inputString)
  return numberFromInputString
}

test("turns input string into a number", () => {
  expect(getNumber("59.99")).toBe(59.99)
})

This passes 🎉

Now imagine your website also operates in Germany where the meaning of commas and decimals in numbers are switched (i.e. $1,200.99 in English would be $1.200,99 in German).

So you add another test case to address this:

test("turns input string into a number", () => {
  // English test case
  expect(getNumber("59.99")).toBe(59.99)
  // German test case
  expect(getNumber("19,95")).toBe(19.95)
})

But when you run the test, you hit an error:

expect(received).toBe(expected) // Object.is equality

Expected: 19.95
Received: NaN

Assuming that your website and input are equipped to handle various locales and localized strings, this would be a limitation of your tests - not a bug in your app.

There's something that can help though: Property-based testing.

Fixing this bug with fast-check

To solve this problem, let's use fast-check, a JavaScript framework for generative test cases. Our goal is to test that our function turns any valid input string into a number, regardless of locale.

First, we need to pick the property (or properties) to test for in this situation. There a couple of options:

It works with strings that aren't formatted.
It works with strings that are formatted using one of the accepted locales (in this case, that would be German).
A combination of the two.

We'll tackle the latter: A combination of formatted and non-formatted strings.

Spoiler alert: Final solution

Here's a peek at what our test will look like by the end of this post:

test("turns any valid input string into a number, regardless of locale", () => {
  fc.assert(
    fc.property(
      fc.float(),
      fc.option(fc.constantFrom("de-DE", "fr-FR")),
      (testFloat, locale) => {
        const fixedFloat = parseFloat(testFloat.toFixed(2))

        const floatString = locale
          ? new Intl.NumberFormat(locale).format(fixedFloat)
          : fixedFloat.toString()

        expect(getNumber(floatString)).toBe(fixedFloat)
      }
    )
  )
})

This is a lot all at once. So let's go through it step-by-step.

Setting up our test

To begin, we need to set up our test:

test("turns any valid input string into a number, regardless of locale", () => {
  fc.assert(
    fc.property(
      // Everything else will go here!
  )
})

Note: This test uses the assert and property fast-check functions. If you need a refresher, these are both covered in our JavaScript property-based testing guide.

Applying our properties

To test a combination of formatted and non-formatted strings, we need to pass two different arbitraries to property.

The first will be float to generate the floating-point numbers:

fc.float()

The second is also a combination of sorts. To start, we need to write a constantFrom function that takes in multiple, equally probable values. We'll use this for our German locale: de-DE.

fc.constantFrom(
  "de-DE"
  /* This is where you'd pass another locale */
)

Then, we'll wrap constantFrom in the option function. With option, the complete arbitrary will return either null (a stand-in for the English default) or our values from constantFrom.

fc.option(fc.constantFrom("de-DE"))

Prices in these locales only go to the second decimal place and we want to embody this in our test.

To do this, we'll take the testFloat value and use JavaScript's built-in toFixed method on it. The 2 value indicates how many decimal places we want.

This method returns a string, but we need a number for our final assertion. So we'll wrap it in another built-in function, parseFloat, and name this variable fixedFloat.

const fixedFloat = parseFloat(testFloat.toFixed(2))

Finally, we'll pass two arguments to the property callback: testFloat (representing each generated floating-point number) and locale (representing the generated locale from our option and constantFrom combination).

Altogether, our property function will look like this so far:

fc.property(
  fc.float(),
  fc.option(fc.constantFrom("de-DE")),
  (testFloat, locale) => {
    const fixedFloat = parseFloat(testFloat.toFixed(2))
    // More to come!
  }
)

Processing the strings

Because we're testing both formatted and non-formatted strings, we need a way to differentiate these two string types.

We'll create a variable called floatString that checks if there is a locale value.

If locale !== null, then we need to create a localized string based on the generated float.

To do this, we'll use the Intl.NumberFormat constructor and pass in our locale value. On top, we'll chain on the format method with our fixedFloat value from earlier.

new Intl.NumberFormat(locale).format(fixedFloat)

Note: This constructor should mimic existing functionality in your app.

If locale is null, then we'll use the built-in toString method on fixedFloat, which returns it as a string.

fixedFloat.toString()

The resulting floatString variable:

const floatString = locale
  ? new Intl.NumberFormat(locale).format(fixedFloat)
  : fixedFloat.toString()

Adding your assertion

At last, we need the most crucial part of any test: The assertion.

The following expect statement indicates that when you pass the floatString (formatted or not) to the getNumber function, you expect it to equal the fixedFloat number value:

expect(getNumber(floatString)).toBe(fixedFloat)

Putting it all together

After all that, you're back to that final result:

test("turns any valid input string into a number, regardless of locale", () => {
  fc.assert(
    fc.property(
      fc.float(),
      fc.option(fc.constantFrom("de-DE", "fr-FR")),
      (testFloat, locale) => {
        const fixedFloat = parseFloat(testFloat.toFixed(2))

        const floatString = locale
          ? new Intl.NumberFormat(locale).format(fixedFloat)
          : fixedFloat.toString()

        expect(getNumber(floatString)).toBe(fixedFloat)
      }
    )
  )
})

Reminder: You can check out the code in our accompanying GitHub repository.

Now your tests are more thorough and resilient 🎉

Special thanks

Nicolas Dubien, the creator of fast-check, was the first to flag this issue in the original guide. He also helped develop the solution. You're the best, Nicolas!

Have a better solution? Comment below or open a pull request.

Testing apps with third-party integrations

Carolyn Stransky — Fri, 24 Jul 2020 15:31:32 +0000

This post assumes that you're familiar with APIs and have a basic understanding of testing. It's also based on a presentation by Mike Solomon.

Whether you’re working with the latest technologies or fighting against legacy code, you'll likely need to make a call to an API. And even more likely, this will be an API that you don't maintain.

Reliance on external services is becoming more prevalent in our engineering ecosystem. As a result, we need cost-effective, secure, and reliable ways to test how our app interacts with these services.

In this post, we'll examine some strategies and available tools for testing apps that use third-party integrations.

TL;DR: If you don't have time to write tests but want to be sure your apps are covered, use an automated testing tool like Meeshkan.

Why should you test third-party integrations?

The way we build apps has changed a lot in the past two decades. At the beginning of the 2000s, when you ran into a problem or needed a specific service, you had to build it yourself.

Now, there's an API for almost everything. SendGrid for emails, Auth0 for authentication, Stripe for payments, and the list goes on. The Programmable Web API Directory has over 23,000 different APIs available for use. Even MySpace has its own set of realtime REST APIs.

But using a third-party integration that you didn't build and don't maintain is risky.

You need to be sure that the calls you're making to these APIs are reliable and serving the expected data. That's why you should test them.

There are a few different options for how to test these external services. Let’s start with the most common and walk-through some of the issues they can cause.

Three common (but misguided) ways to test APIs

1. Do nothing

Don't write tests - or comment them out when you write them and they don't work.

If this is you, don't be ashamed.

There's an entire economy around helping you solve issues that arise when you don't test your code. There are also products designed to test your apps when you understand the importance but don't want to manually write any (more on that later in this post).

2. Using the real APIs

We have another blog post that highlights the three primary reasons to not use the real APIs in tests. It covers security, integrity, and speed.

But there are also lots of unfortunate scenarios that can happen when you use the real APIs in a CI/CD pipeline.

During the research for his initial talk, Mike Solomon collected horror stories from developers who have used real APIs in their tests. Here are two of those.

“I want you back”
One company accidentally embedded a Twilio API key in their CI environment. This caused some poor person in Kansas to receive dozens of text messages a day saying “I want you back <3”.

OR 1=1
Another testing engineer created a fake username called OR 1=1 (a common SQL injection). This username got sent repeatedly to a production API and the organization was banned from using the service.

3. Reverse engineering the API

This option is the least dangerous, but the most time-consuming.

When you create a reverse-engineered version of the API you're testing, it comes at a cost. For instance, sinking more time into writing a test script than you did the feature you're testing. Or the stubbed API data ends up being longer than the code you're testing. It's also difficult to maintain unless you endlessly monitor the changelog of that external API.

None of these options are great, so let's look at more reliable strategies for testing your third-party integrations.

Better ways to test third-party integrations

It'd be cruel to leave you without a solution, so outlined below are two cost-effective, secure options for your tests.

Write your tests with a mocking library

A mock is a substitute for a service that mimics the original functionality. Or at least the functionality that you're aiming to test.

In this case, the mock acts as a replacement for your third-party integration. That way, you don't need to make a network call from your tests. This helps make your test resilient when the network is down or slow and enables you to specify and test corner cases. Plus mocks are often less complicated to access and maintain.

There are some libraries you can use to write your mocks. We recently published a post comparing two JavaScript mocking libraries - nock and unmock.

We’ve loved and used this approach ourselves (I mean, we built unmock). There are still issues with this approach though. Namely, that you have to manually write all the tests - even if the input values are generated.

This can be tedious and take a lot of time. So that’s where the second option comes in.

Use a service (like Meeshkan) to test your apps

Yes, this is a product plug - but with good reason.

We built Meeshkan for those of you reading this post and wondering who has time to write tests. Our automated testing service executes and reports on a collection of generated tests. These tests are designed to imitate any third-party integrations you're working with using schemas and a bit of NLP.

All you need to do is authorize our GitHub app, choose a repository test, and set up your base configuration.

Sound good? Request beta access today.

DEV Community: Meeshkan

Reviving the Dhall API discussion

What's Dhall

Dhall for Web APIs

Service discovery

Dhall from the producer

Dhall from the consumer

How this fixes the problems defined above

Spec

Power to the consumers

Authorization

Custom DSL

Conlcusion

Four reasons that PureScript is your best choice to build a server in 2020

Hello world

Portability

Language

Community

Bonus

Conclusion

Functional GraphQL 1 - Specs and typelevel parsing

What is compile-time generation of types?

A slightly-more realistic example

Conclusion and next steps

When to start thinking about QA

A couple definitions

The single most important step

The next step

An example

How to get started

Conclusion

Type-safe rationals in PureScript - why, what, and how

Type-level programming

My PureScript implementation

invoke

Adding numbers

How?

Profunctors are everywhere!

What's a profunctor?

Our first profunctor optic - Iso

A stronger profunctor

Give us a choice!

But what about security?

Make me a Star

Folding up values

tl;dr

Launching first-class support for automated GraphQL testing

Table of Contents

The evolution of API technology

RESTful

GraphQL

Why we believe GraphQL will become the standard choice for building new APIs

What does first-class GraphQL server testing look like?

How automated GraphQL tests work on your server

Benefits of using Meeshkan with your GraphQL API vs your REST API

The future of testing GraphQL as Meeshkan sees it

Next steps

Extension types in TypeScript

What to do?

Two types of extensions

Intersection extensions

Union extensions

Runtime validation

Show me the code!

Kotlin tests and user stories

Create a mock server for any REST API

Initial setup

(Optional) Create a virtual environment

Install HMT

1. Collect recordings of your API's traffic

Start HMT

Run API-specific curl commands

Check the recordings file

2. Build an OpenAPI specification from your recordings

3. Mock server traffic using your specification

Conclusion

Finding and fixing bugs in your tests with fast-check

Summary of the bug in our test

Fixing this bug with fast-check

Spoiler alert: Final solution