Effect Website 2.0 (Release)

Maxwell Brown — Tue, 29 Oct 2024 00:00:00 +0000

We are very excited to unveil the newly rebuilt Effect website - a major step forward in both functionality and performance! This update represents an exciting milestone as we transition to using Astro, a change that will allow us to deliver a better experience to our growing community of developers.

Why the Switch to Astro?

Over the past year, the Effect website has grown significantly, becoming the go-to source for everything Effect — from in-depth documentation to key announcements and beyond. This growth has been invaluable to the community, providing a wealth of resources on Effect. However, as the site expanded, maintaining and updating the site’s content has become one of our biggest challenges.

Our previous content management solution relied on a patchwork mixture of disparate tooling, resulting in progressively slower build times as our content grew. The inability of our system to scale with our content became especially problematic as we began to consider adding more use-case driven examples and interactive tutorials to the site.

Switching to Astro has provided us with a unified, streamlined set of tools that has dramatically improved our workflow. Astro’s optimized approach to content management allows us to iterate, build, and deploy faster, supporting our commitment to creating an accessible, responsive, and continually evolving hub for Effect’s developer community.

What’s New

The newly rebuilt Effect website comes with several enhancements to improve the developer experience:

Better Support for Shiki Twoslash in Code Snippets
Improved Site-Wide Search
RSS Support for the Blog
Faster Load Time for the Effect Playground

…and many improvements that we don’t have room to list here!

What’s Next?

This release is just the beginning. The Effect team is actively working on new, use-case-driven documentation as well as hands-on tutorials to accelerate your onboarding experience.

Our goal is to make the Effect ecosystem as approachable as possible, empowering developers at all levels to quickly gain proficiency and confidence.

We hope you enjoy the new Effect website! Dive in, explore the features, and let us know what you think. Your feedback is invaluable in helping us shape the future of Effect.

The Effect Team

graphics-ts: Functional Bindings for the HTML 5 Canvas API

Maxwell Brown — Fri, 05 Jun 2020 19:24:05 +0000

In this post, I will describe the functional design of graphics-ts, a part of the fp-ts ecosystem that provides functional bindings for the HTML 5 Canvas API.

For those unfamiliar with fp-ts, I encourage you to read @gcanti's excellent series on Getting starting with fp-ts.

Getting started with fp-ts: Eq

Giulio Canti ・ Mar 11 '19

#functional #typescript

The HTML 5 Canvas API

As described by the Mozilla Developer Network Web Docs:

The Canvas API provides a means for drawing graphics via JavaScript and the HTML <canvas> element. Among other things, it can be used for animation, game graphics, data visualization, photo manipulation, and real-time video processing.

Here is a basic example of using the Canvas API to draw a house:

Html

<canvas id="my-house" width="300" height="300"></canvas>

JavaScript

const draw = () => {
  const canvas = document.getElementById('my-house')

  if (canvas) {
    const context = canvas.getContext('2d')
    // Set line width
    context.lineWidth = 10;
    // Wall
    context.strokeRect(75, 140, 150, 110);
    // Door
    context.fillRect(130, 190, 40, 60);
    // Roof
    context.beginPath();
    context.moveTo(50, 140);
    context.lineTo(150, 60);
    context.lineTo(250, 140);
    context.closePath();
    context.stroke();
  }
}

Output

As you can see, rendering to a <canvas> element is imperative by nature and involves repeated mutation of the canvas context.

Functional Programming and the Canvas API

The Canvas Module

In graphics-ts, operations made against the canvas are modeled by the IO type class.

From Getting started with fp-ts:

In fp-ts a synchronous effectful computation is represented by the IO type, which is basically a thunk, i.e. a function with the following signature: () => A.

By representing canvas operations as instances of IO, we are pushing evaluation of the canvas to the boundary of our program's execution. This is because an IO is just a value which represents an effectful computation, so in order to execute any side effect you must execute the IO action.

Getting Access to the Canvas

Before we can start drawing to a <canvas> element, we need to get a reference to it, as well as to its context.

export const unsafeGetCanvasElementById: (id: string) => HTMLCanvasElement = (id) =>
  document.getElementById(id) as HTMLCanvasElement

export const unsafeGetContext2D: (canvas: HTMLCanvasElement) => CanvasRenderingContext2D = (c) =>
  c.getContext('2d') as CanvasRenderingContext2D

But there is a problem here - these operations are not running in the IO context. To solve this, we can lift these functions into the IO context.

import * as IO from 'fp-ts/lib/IO'

export const getCanvasElementById: (id: string) => IO.IO<O.Option<HTMLCanvasElement>> = (id) => () => {
  const canvas = unsafeGetCanvasElementById(id)
  return canvas instanceof HTMLCanvasElement ? O.some(canvas) : O.none
}

export const getContext2D: (canvas: HTMLCanvasElement) => IO.IO<CanvasRenderingContext2D> = (c) =>
  IO.of(unsafeGetContext2D(c))

Abstracting Canvas Operations

Now we can start working on implementing the rest of our API.

Example (canvas dimensions)

import * as IO from 'fp-ts/lib/IO'

export const getWidth: (canvas: HTMLCanvasElement) => IO.IO<number> = (c) => () => c.width

export const setWidth: (width: number) => (canvas: HTMLCanvasElement) => IO.IO<void> = (w) => (c) => () => {
  c.width = w
}

export const getHeight: (canvas: HTMLCanvasElement) => IO.IO<number> = (c) => () => c.height

export const setHeight: (height: number) => (canvas: HTMLCanvasElement) => IO.IO<void> = (h) => (c) => {
c.height = h


export interface CanvasDimensions {
  readonly width: number
  readonly height: number
}

export const getDimensions: (canvas: HTMLCanvasElement) => IO.IO<CanvasDimensions> = (c) =>
  sequenceS(IO.io)({ height: getHeight(c), width: getWidth(c) })

export const setDimensions: (dimensions: CanvasDimensions) => (canvas: HTMLCanvasElement) => IO.IO<void> = (d) => (c) =>
  pipe(
    c,
    setWidth(d.width),
    IO.chain(() => pipe(c, setHeight(d.height)))
  )

Example (stroke a path)

export const strokePath: <A>(
  f: (ctx: CanvasRenderingContext2D) => IO.IO<A>
) => (ctx: CanvasRenderingContext2D) => IO.IO<A> = (f) => (ctx) =>
  pipe(
    ctx,
    beginPath,
    IO.chain(() => f(ctx)),
    IO.chain((a) =>
      pipe(
        ctx,
        stroke(),
        IO.map(() => a)
      )
    )
  )

Refactoring our Domain Model

If we examine our API as we continue, we will notice that almost all functions have the following signatures:

HTMLCanvasElement

(canvas: HTMLCanvasElement) => IO.IO<A>

CanvasRenderingContext2D

(ctx: CanvasRenderingContext2D) => IO.IO<CanvasRenderingContext2D>

Essentially, we are reading from an HTMLCanvasElement or CanvasRenderingContext2D and returning a type A wrapped in an IO.

So we could say that when managing HTMLCanvasElement we are yielding an Html effect, when managing CanvasRenderingContext2D we are yielding a Render effect, and when managing CanvasGradient we are yielding a Gradient effect.

We can model these effects using the Reader module from fp-ts.

import * as R from 'fp-ts/lib/Reader'

export interface Html<A> extends R.Reader<HTMLCanvasElement, IO.IO<A>> {}

export interface Render<A> extends R.Reader<CanvasRenderingContext2D, IO.IO<A>> {}

export interface Gradient<A> extends R.Reader<CanvasGradient, IO.IO<A>> {}

So our examples from above become the following:

Example (canvas dimensions)

export const getWidth: Html<number> = (c) => () => c.width

export const setWidth: (width: number) => Html<HTMLCanvasElement> = (w) => (c) => () => {
  c.width = w
  return c
}

export const getHeight: Html<number> = (c) => () => c.height

export const setHeight: (height: number) => Html<HTMLCanvasElement> = (h) => (c) => () => {
  c.height = h
  return c
}

export const getDimensions: Html<CanvasDimensions> = (c) =>
  sequenceS(IO.io)({ height: getHeight(c), width: getWidth(c) })

export const setDimensions: (dimensions: CanvasDimensions) => Html<HTMLCanvasElement> = (d) => (ctx) =>
  pipe(ctx, setWidth(d.width), IO.chain(setHeight(d.height)))

However, if we continue to examine our code we will see that in many instances we are manually threading the ctx through our API.

Example (stroke a path)

export const strokePath: <A>(f: Render<A>) => Render<A> = (f) => (ctx) =>
  pipe(
    ctx,
    beginPath,
    IO.chain(() => f(ctx)),
    IO.chainFirst(() => pipe(ctx, stroke()))
  )

Example (preserve the canvas context):

export const withContext: <A>(f: Render<A>) => Render<A> = (f) => (ctx) =>
  pipe(
    save(ctx),
    IO.chain(() => f(ctx)),
    IO.chainFirst(() => restore(ctx))
  )

From Getting started with fp-ts:

The purpose of the Reader monad is to avoid threading arguments through multiple functions in order to only get them where they are needed.

What if we could simply chain Render effects? We would need a Monad instance of Render. We know that Render admits a Monad instance because theory tells us that

Reader<R, M<A>>

admits a Monad instance for any effect M as long as M admits a Monad instance. In our case we have

Reader<R, IO<A>>

and, since IO admits a Monad instance, we know that

Render<A> = Reader<CanvasRenderingContext2D, IO<A>>

admits a Monad instance too.

To create our Monad instance of Render, we can utilize the ReaderIO module from fp-ts-contrib.

ReaderIO<R, A> = Reader<R, IO<A>>

So our effect models now become the following

import * as R from 'fp-ts-contrib/lib/ReaderIO'

export interface Gradient<A> extends R.ReaderIO<CanvasGradient, A> {}

export interface Html<A> extends R.ReaderIO<HTMLCanvasElement, A> {}

export interface Render<A> extends R.ReaderIO<CanvasRenderingContext2D, A> {}

and we can refactor strokePath and withContext from above to

export const strokePath: <A>(f: Render<A>) => Render<A> = (f) =>
  pipe(
    beginPath,
    R.chain(() => f),
    R.chainFirst(() => stroke())
  )

export const withContext: <A>(f: Render<A>) => Render<A> = (f) =>
  pipe(
    save,
    R.chain(() => f),
    R.chainFirst(() => restore)
  )

Putting it all Together

Using the Canvas module from graphics-ts, we can rewrite our example of rendering a house from above as

import { error } from 'fp-ts/lib/Console'
import * as R from 'fp-ts-contrib/lib/ReaderIO'
import * as C from 'graphics-ts/lib/Canvas'
import * as S from 'graphics-ts/lib/Shape'
import { pipe } from 'fp-ts/lib/pipeable'

const canvasId = 'my-house'

const wall = C.strokeRect(S.rect(75, 140, 150, 110))

const door = C.fillRect(S.rect(130, 190, 40, 60))

const roof = C.strokePath(
  pipe(
    C.moveTo(S.point(50, 140)),
    R.chain(() => C.lineTo(S.point(150, 60))),
    R.chain(() => C.lineTo(S.point(250, 140)))
  )
)

C.renderTo(canvasId, () => error(`[ERROR]: Unable to find canvas with id ${canvasId}`))(
  pipe(
    // Set line width
    C.setLineWidth(10),
    R.chain(() => wall),
    R.chain(() => door),
    R.chain(() => roof)
  )
)

The Drawing Module

graphics-ts also provides another layer of abstraction on top of the HTML 5 Canvas API through the Drawing module.

The Drawing module abstracts away the repetitive calls to the HTML Canvas API that are required when using the Canvas module directly and allows for composition of different shapes, styles, and drawings.

If we refactor the example of rendering a house from above one last time using the Drawing module, we get the following

import { error } from 'fp-ts/lib/Console'
import * as M from 'fp-ts/lib/Monoid'
import * as RA from 'fp-ts/lib/ReadonlyArray'
import * as R from 'fp-ts-contrib/lib/ReaderIO'
import * as C from 'graphics-ts/lib/Canvas'
import * as Color from 'graphics-ts/lib/Color'
import * as D from 'graphics-ts/lib/Drawing'
import * as S from 'graphics-ts/lib/Shape'
import { pipe } from 'fp-ts/lib/pipeable'

const canvasId = 'my-house'

const wall = D.outline(
  S.rect(75, 140, 150, 110),
  M.fold(D.monoidOutlineStyle)([D.lineWidth(10), D.outlineColor(Color.black)])
)

const door = D.fill(S.rect(130, 190, 40, 60), D.fillStyle(Color.black))

const roof = D.outline(
  S.path(RA.readonlyArray)([S.point(50, 140), S.point(150, 60), S.point(250, 40)]),
  D.outlineColor(Color.black)
)

C.renderTo(canvasId, () => error(`[ERROR]: Unable to find canvas with id ${canvasId}`))(
  D.render(D.many([wall, door, roof]))
)

Repository

I encourage anyone who is interested in experimenting with the HTML 5 Canvas API to give the library a try!

gcanti / graphics-ts

A porting of purescript-{canvas, drawing} featuring fp-ts

Acknowledgements

I would like to thank @gcanti for giving me the opportunity to work on this rewrite as well as for providing teaching and guidance on use of functional programming theory and the fp-ts ecosystem.

DEV Community: Maxwell Brown