
# Gradient Avatars

Do you ever need a placeholder profile image for someone? Perhaps for new users who haven't uploaded an image yet.

Well, I often do. Which is why I've built [Gradient Avatars](https://avatars.jakerunzer.com), a tool that will give you a deterministic circular SVG image with a gradient based on some text.

For example, the text "hello" outputs:

![Gradient Avatar With Text Hello](https://avatars.jakerunzer.com/hello)

"world" creates the image:

![Gradient Avatar With Text Hello](https://avatars.jakerunzer.com/world)

The source url for these images is `avatars.jakerunzer.com/{text}`, where text is something unique.

Check it out yourself at 👉 [avatars.jakerunzer.com](https://avatars.jakerunzer.com) 👈

Gradient Avatars

gradient avatars


# Cursors

I often forget all the options for cursors in [[CSS]] and testing each one in Chrome is tedious and time consuming. That is why I made Cursors. Available at [cursors.jakerunzer.com](https://cursors.jakerunzer.com). A small [[web|website]] that shows you all examples of CSS cursors and allows you to copy them to clipboard.

![Screenshot of Cursors](https://user-images.githubusercontent.com/3044853/115191624-8a453380-a09e-11eb-82da-bd7534f59197.png)

Source is [available on GitHub](https://github.com/coffee-cup/cursors).

This also the first thing I've built using [SvelteKit](https://kit.svelte.dev/). It has been a great experience so far and I expect I will use [[Svelte]] a lot more in the future for tiny sites like this.





Cursors

cursors


# useFavicon

Change your favicon when [[React]] components are mounted. 

You can generate favicons from images with [[favocon]].

## Implementation

```ts
import { useEffect } from "react";

export const favicons = {
  sparkles: "/favicon.ico",
  garden: "/seedling.ico",
  bookmark: "/bookmark.ico",
  rocket: "/rocket.ico",
};

export const useFavicon = (name: keyof typeof favicons) => {
  useEffect(() => {
    const href = favicons[name];

    const link: HTMLLinkElement =
      document.querySelector("link[rel*='icon']") ||
      document.createElement("link");

    link.type = "image/x-icon";
    link.rel = "shortcut icon";
    link.href = href;

    document.getElementsByTagName("head")[0].appendChild(link);
  }, [name]);
};
```

## Usage

```ts
const MyComponent = () => {
  useFavicon("sparkles");
  return ( /* ... */ );
}
```


useFavicon

usefavicon


# Stack Components using Twin.macro

I like to use [[tailwind-react-composition|Tailwind via twin.macro]] for styling. These are a `VStack` and `HStack` components that can be used to layout UI in [[React]].

```ts
<HStack space={4}>
  <div tw="bg-blue-500 w-20 h-20" />
  <div tw="bg-blue-500 w-20 h-20" />
  <div tw="bg-blue-500 w-20 h-20" />
</HStack>
```

## Implementation

twin.macro runs at build time so we need to define all possible styles upfront. This gives us ability to space between 0 and 16 in horizontal and vertical directions.

```ts
import tw, { TwStyle } from "twin.macro";

export interface StackProps {
  justify?: JustifyValues;
  align?: AlignValues;
  space?: StackSpace;
  className?: string;
}

type JustifyValues = "center" | "between" | "start" | "end";
type AlignValues = "center" | "start" | "end" | "baseline";

const justifyValues: Record<JustifyValues, TwStyle> = {
  center: tw`justify-center`,
  between: tw`justify-between`,
  start: tw`justify-start`,
  end: tw`justify-end`,
};

const alignValues: Record<AlignValues, TwStyle> = {
  center: tw`items-center`,
  baseline: tw`items-baseline`,
  start: tw`items-start`,
  end: tw`items-end`,
};

type StackSpace = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 12 | 14 | 16;

const vSpaces: Record<StackSpace, TwStyle> = {
  0: tw`space-y-0`,
  1: tw`space-y-1`,
  2: tw`space-y-2`,
  3: tw`space-y-3`,
  4: tw`space-y-4`,
  5: tw`space-y-5`,
  6: tw`space-y-6`,
  7: tw`space-y-7`,
  8: tw`space-y-8`,
  9: tw`space-y-8`,
  10: tw`space-y-8`,
  12: tw`space-y-12`,
  14: tw`space-y-14`,
  16: tw`space-y-16`,
};

const hSpaces: Record<StackSpace, TwStyle> = {
  0: tw`space-x-0`,
  1: tw`space-x-1`,
  2: tw`space-x-2`,
  3: tw`space-x-3`,
  4: tw`space-x-4`,
  5: tw`space-x-5`,
  6: tw`space-x-6`,
  7: tw`space-x-7`,
  8: tw`space-x-8`,
  9: tw`space-x-8`,
  10: tw`space-x-8`,
  12: tw`space-x-12`,
  14: tw`space-x-14`,
  16: tw`space-x-16`,
};

const BaseStack: React.FC<StackProps & { dir: "vertical" | "horizontal" }> = ({
  dir,
  justify,
  align,
  space,
  ...props
}) => (
  <div
    {...props}
    css={[
      dir === "vertical" ? tw`flex flex-col` : tw`flex`,
      dir === "vertical" ? vSpaces[space ?? 0] : hSpaces[space ?? 0],
      justify != null && justifyValues[justify],
      align != null && alignValues[align],
    ]}
  />
);

export const HStack: React.FC<StackProps> = props => (
  <BaseStack {...props} dir="horizontal" />
);

export const VStack: React.FC<StackProps> = props => (
  <BaseStack {...props} dir="vertical" />
);

```

tags: [[web]]

Stack Components using Twin.macro

twin-stacks


# Shader Hash Functions

Hash functions from [David Hoskins](https://www.shadertoy.com/view/4djSRW). These are straight copied. I only have them here so I don't lose them.

```glsl
//  1 out, 1 in...
float hash11(float p)
{
    p = fract(p * .1031);
    p *= p + 33.33;
    p *= p + p;
    return fract(p);
}

//  1 out, 2 in...
float hash12(vec2 p)
{
	vec3 p3  = fract(vec3(p.xyx) * .1031);
    p3 += dot(p3, p3.yzx + 33.33);
    return fract((p3.x + p3.y) * p3.z);
}

//  1 out, 3 in...
float hash13(vec3 p3)
{
	p3  = fract(p3 * .1031);
    p3 += dot(p3, p3.zyx + 31.32);
    return fract((p3.x + p3.y) * p3.z);
}

//  2 out, 1 in...
vec2 hash21(float p)
{
	vec3 p3 = fract(vec3(p) * vec3(.1031, .1030, .0973));
	p3 += dot(p3, p3.yzx + 33.33);
    return fract((p3.xx+p3.yz)*p3.zy);

}

///  2 out, 2 in...
vec2 hash22(vec2 p)
{
	vec3 p3 = fract(vec3(p.xyx) * vec3(.1031, .1030, .0973));
    p3 += dot(p3, p3.yzx+33.33);
    return fract((p3.xx+p3.yz)*p3.zy);

}

///  2 out, 3 in...
vec2 hash23(vec3 p3)
{
	p3 = fract(p3 * vec3(.1031, .1030, .0973));
    p3 += dot(p3, p3.yzx+33.33);
    return fract((p3.xx+p3.yz)*p3.zy);
}

//  3 out, 1 in...
vec3 hash31(float p)
{
   vec3 p3 = fract(vec3(p) * vec3(.1031, .1030, .0973));
   p3 += dot(p3, p3.yzx+33.33);
   return fract((p3.xxy+p3.yzz)*p3.zyx); 
}


///  3 out, 2 in...
vec3 hash32(vec2 p)
{
	vec3 p3 = fract(vec3(p.xyx) * vec3(.1031, .1030, .0973));
    p3 += dot(p3, p3.yxz+33.33);
    return fract((p3.xxy+p3.yzz)*p3.zyx);
}

///  3 out, 3 in...
vec3 hash33(vec3 p3)
{
	p3 = fract(p3 * vec3(.1031, .1030, .0973));
    p3 += dot(p3, p3.yxz+33.33);
    return fract((p3.xxy + p3.yxx)*p3.zyx);

}

// 4 out, 1 in...
vec4 hash41(float p)
{
	vec4 p4 = fract(vec4(p) * vec4(.1031, .1030, .0973, .1099));
    p4 += dot(p4, p4.wzxy+33.33);
    return fract((p4.xxyz+p4.yzzw)*p4.zywx);
    
}

// 4 out, 2 in...
vec4 hash42(vec2 p)
{
	vec4 p4 = fract(vec4(p.xyxy) * vec4(.1031, .1030, .0973, .1099));
    p4 += dot(p4, p4.wzxy+33.33);
    return fract((p4.xxyz+p4.yzzw)*p4.zywx);

}

// 4 out, 3 in...
vec4 hash43(vec3 p)
{
	vec4 p4 = fract(vec4(p.xyzx)  * vec4(.1031, .1030, .0973, .1099));
    p4 += dot(p4, p4.wzxy+33.33);
    return fract((p4.xxyz+p4.yzzw)*p4.zywx);
}

// 4 out, 4 in...
vec4 hash44(vec4 p4)
{
	p4 = fract(p4  * vec4(.1031, .1030, .0973, .1099));
    p4 += dot(p4, p4.wzxy+33.33);
    return fract((p4.xxyz+p4.yzzw)*p4.zywx);
}
```



Shader Hash Functions

shader hash functions


# TypeScript in the Browser

![Stock image of a laptop and code](https://images.unsplash.com/photo-1545670723-196ed0954986?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1952&q=80)

I recently had to get [[Typescript]] running in
the browser an online code editor that
gives you live feedback on your code. We had previously only showed parse and
runtime errors, but we wanted to show more advanced type errors that are only
detectable with static analysis (e.g. TypeScript).

TypeScript can easily be used programmatically for files on the file system.
With a little configuration it can even be run on code that only exists in
memory. However, running TypeScript in the browser with no access to the file
system turned out to be a bit more challenging than I thought. In this post I
will go over setting up a TypeScript language service that you can use to get
type errors, quick info, documentation, etc, of code in the browser.

All code in this post can be found in [this
CodeSandbox](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il).

Credit where credit is due: [Andrew's](https://twitter.com/atcb) blog post,
[_Overengineering a blog_](https://blog.andrewbran.ch/overengineering-a-blog/),
and [associated source](https://github.com/andrewbranch/blog) were an invaluable
resource. Thanks Andrew!

---

The main functionality I wanted was to query the compiler for type errors.

```ts
function typecheck(code: string): TypeError[] {
  /* ... */
}
```

For this I reached for the TypeScript language service, which is a layer on top
of the core compiler and provides common editor like operations.

![TypeScript language service](https://raw.githubusercontent.com/wiki/Microsoft/TypeScript/images/architecture.png)

To typecheck code in the browser we need the following:

- Virtual system
- Compiler host
- Language service host
- Language service
- Type files for any language features we want to use

## System

A `ts.System` contains methods for reading files, writing files, checking if a
file exists, etc. If you run TypeScript in Node, then the system is a wrapper
around `fs`. The filesystem does not exist in the browser, so we have to create
our own _virtual_ system. The full file is [here](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il?file=/src/system.ts).

```ts
// system.ts
import * as ts from "typescript";

export function createSystem(files: { [name: string]: string }): ts.System {
  files = { ...files };
  return {
    // ...
    directoryExists: directory =>
      Object.keys(files).some(path => path.startsWith(directory)),
    fileExists: fileName => files[fileName] != null,
    getCurrentDirectory: () => "/",
    readFile: fileName => files[fileName],
  };
}
```

We pass in an object from filename → file contents that contains all of our
files on our virtual filesystem.

## Library Types

TypeScript knows the types of variables and functions through the use of
declaration files (`.d.ts` extension). These are what you download when you
install a package from DefinitelyTyped (`@types/package`).

Since there are many different versions of TypeScript/JavaScript, the types of
core language features are not baked into the compiler. Declaration files for
the languages features you want to use must be included in the virtual file
system. This is what the `lib` field in your `tsconfig.json` file configures.

In this demo we will use es2015 and dom features, equivalent to

```json
// tsconfig.json
{
  // ...
  "lib": ["es2015", "dom"]
}
```

The decalaration files are in `node_modules` and can be loaded at build time using the Webpack `raw-loader`.

```ts
// tsLib.ts
export const libs = {
  "/dom.d.ts": require("!raw-loader!typescript/lib/lib.dom.d.ts"),
  "/es2015.d.ts": require("!raw-loader!typescript/lib/lib.es2015.d.ts"),
  "/lib.es5.d.ts": require("!raw-loader!typescript/lib/lib.es5.d.ts"),
  "/lib.es2015.d.ts": require("!raw-loader!typescript/lib/lib.es2015.d.ts"),
  "/lib.es2015.core.d.ts": require("!raw-loader!typescript/lib/lib.es2015.core.d.ts"),
  "/lib.es2015.collection.d.ts": require("!raw-loader!typescript/lib/lib.es2015.collection.d.ts"),
  "/lib.es2015.generator.d.ts": require("!raw-loader!typescript/lib/lib.es2015.generator.d.ts"),
  "/lib.es2015.promise.d.ts": require("!raw-loader!typescript/lib/lib.es2015.promise.d.ts"),
  "/lib.es2015.iterable.d.ts": require("!raw-loader!typescript/lib/lib.es2015.iterable.d.ts"),
  "/lib.es2015.proxy.d.ts": require("!raw-loader!typescript/lib/lib.es2015.proxy.d.ts"),
  "/lib.es2015.reflect.d.ts": require("!raw-loader!typescript/lib/lib.es2015.reflect.d.ts"),
  "/lib.es2015.symbol.d.ts": require("!raw-loader!typescript/lib/lib.es2015.symbol.d.ts"),
  "/lib.es2015.symbol.wellknown.d.ts": require("!raw-loader!typescript/lib/lib.es2015.symbol.wellknown.d.ts"),
};
```

If we wanted to use a third party library, we could include the type file here.

## Compiler Host

The TypeScript compiler interacts with the host environment via a compiler host.

```ts
const compilerHost: ts.CompilerHost = {
  // ...
  getCanonicalFileName: fileName => fileName,
  getDefaultLibFileName: () => "/lib.es2015.d.ts",
  getDirectories: () => [],
  getNewLine: () => sys.newLine,
  getSourceFile: filename => sourceFiles[filename],
  useCaseSensitiveFileNames: () => sys.useCaseSensitiveFileNames,
};
```

The compiler host uses `ts.SourceFile`s for representing files on the
filesystem. These include the content of the file as well as additional
metadata, such as the language version. We can easily create source files from
an object from filename -> contents.

```ts
const sourceFiles: { [name: string]: ts.SourceFile } = {};
for (const name of Object.keys(files)) {
  sourceFiles[name] = ts.createSourceFile(
    name,
    files[name],
    compilerOptions.target || ts.ScriptTarget.Latest,
  );
}
```

## Language Service Host

The language service host "abstracts all interactions between the language service and the external world. The language service host defers managing, monitoring, and maintaining input files to the host" ([source](https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API#language-service-host)).

This means that the only way the compiler can access the outside world is through the language service host.

```ts
const languageServiceHost: ts.LanguageServiceHost = {
  // ...
  getCompilationSettings: () => compilerOptions,
  getScriptFileNames: () => Object.keys(files),
  getScriptSnapshot: filename => {
    const contents = sys.readFile(filename);
    if (contents) {
      return ts.ScriptSnapshot.fromString(contents);
    }

    return undefined;
  },
};
```

In the above code we create a `ScriptSnapshot` instead of returning the contents of the file as a string because they allow efficient incremental parsing. The snapshot contains information about the entire contents of the file, as well as changes made from a previous snapshot. Since we are not worrying about incremental parsing in this demo, a new snapshot is created every time.

## Language Service

The final thing we need is a `ts.LanguageService`. This will be our main
interface into the compiler. In a proper application you would create the
language service once and update the (virtual) file contents as you need. This
would allow the compiler to perform various optimizations such as only
parsing and typechecking code that has changed. However, in our demo we will
create a new language service every time we want to typecheck some code.

```ts
const languageService = ts.createLanguageService(languageServiceHost);
```

## Getting Diagnostics

The language service contains a bunch of useful functions for querying the compiler.

![language service available functions](./language-service.png)

The one we are most interested in is `getSemanticDiagnostics`, which will return an array of `ts.Diagnostic`s that look like,

```ts
{
  file: SourceFileObject;
  start: number;
  length: number;
  code: number;
  messageText: string;
}
```

The field `messageText` is a human readable description of the problem found.

## Implementation

Using the information above, lets implement a function for typechecking some input code.

First, we need to specify some compiler options. This object looks nearly
identical to what you find in `tsconfig.json`.

```ts
const compilerOptions: ts.CompilerOptions = {
  ...ts.getDefaultCompilerOptions(),
  jsx: ts.JsxEmit.React,
  strict: false,
  target: ts.ScriptTarget.Latest,
  esModuleInterop: true,
  module: ts.ModuleKind.None,
  suppressOutputPathCheck: true,
  skipLibCheck: true,
  skipDefaultLibCheck: true,
  moduleResolution: ts.ModuleResolutionKind.NodeJs,
};
```

And now onto our typechecking function. Some code is commented out for
concisness as it is shown in more detail above. The full typechecking code can
be found
[here](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il?file=/src/typecheck.ts).

```ts
const typecheck = (code: string): ts.Diagnostic[] => {
  // Create our virtual file system
  const dummyFilename = "file.ts";
  const files: { [name: string]: string } = {
    [dummyFilename]: code,
  };
  const sys = createSystem({ ...libs, ...files });

  // create source files from the `files` object
  const sourceFiles: { [name: string]: ts.SourceFile } = {};
  for (const name of Object.keys(files)) {
    /* ... */
  }

  // create the compiler host, an abstraction for the language service
  // to interact with the host environment
  const compilerHost: ts.CompilerHost = {
    /* ... */
  };

  // create the language service host, an absctraction of all interactions
  // between the language service and the external world
  const languageServiceHost: ts.LanguageServiceHost = {
    /* ... */
  };

  // create an instance of the TypeScript language service
  const languageService = ts.createLanguageService(languageServiceHost);

  // get all semantic diagnostics for the code we passed into this function
  const diagnostics = languageService.getSemanticDiagnostics(dummyFilename);
  return diagnostics;
};
```

And there you have it! A simple function for typechecking code in the browser with TypeScript.

## Usage

Using the above `typecheck` function on the code

```ts
const x: string = 100;
```

we get

```ts
[{
  file: SourceFileObject
  start: 6
  length: 1
  code: 2322
  category: 1
  messageText: "Type '100' is not assignable to type 'string'."
}]
```

## Improvements

Our current implementation has the overhead of re-creating the language service
everytime we call `typecheck`. An improvment we could make is to only create a
single instance of the language service and just update the contents of the
virtual file when something changes. If we can track which parts of the file
have updated, we can pass that information to the compiler via a
`ScriptSnapshot` to enable incremental parsing.

We could also use the language service to offer IDE like features in the browser with things like quick info, function documentation, JSX closing tag hints, and much more.

## Conclusion

Although getting TypeScript running in the browser is not as simple as
installing a package from NPM, with a little understaning of how the language
service works, we can get the full power of TypeScript in the browser fairly
quickly. With that we can query the compiler for type errors and access many more IDE
like features.

## Resources

- [Companion CodeSandbox](https://codesandbox.io/s/ts-typechecking-in-the-browser-gg9il?file=/src/typecheck.ts)
- [Andrew's Overengineering a Blog post](https://blog.andrewbran.ch/overengineering-a-blog/#the-language-service)
- [Using the Compiler
  API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#a-minimal-compiler)
- [TypeScript Architectural Overview](https://github.com/microsoft/TypeScript/wiki/Architectural-Overview)
- [Langauge Service API](https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API)
- [Alfie](https://alfie.prodo.ai)


tags: [[web]] [[typescript]]

TypeScript in the Browser

running-ts-in-browser


# The Krill Language

Krill is a small programming language with a very minimal syntax. You can find
it at [krill.jakerunzer.com](https://krill.jakerunzer.com).

It looks like this.

```python
even = x -> x % 2 == 0
square = x -> x * x
sumOddSquares = sum . filter (not . even) . map square
sumOddSquares [1..100]
# => 166650
```

At a high level Krill is

- dynamic
- interpreted
- eager
- curried
- immutable

In this article I will go over some interesting aspects of the language and
briefly explain how it is implemented.

## Concepts

When designing Krill, I wanted to ensure that the language was

- immutable
- clean and friendly to use
- allow a functional coding style

Lets dig into these

### Immutable

Variables in Krill are immutable per scope.

```python
x = 1
x = 2 # Error!
```

However, you can shadow variables in an inner scope.

```python
x = 0

foo = _ -> {
  x = 1
  print ("inner " ++ x)
}

foo ()
print ("outer " ++ x)

# inner 1
# outer 0
```

### Clean and friendly

This aspect of any language is mostly down to personal preference, but I think
most of us can agree that large amounts of punctuation and complicated symbols
can make code harder to look at. Ruby is easier to read than C++.

In Krill I tried to keep the use of punctuation to a minimum. There are no semi
colons at the end of the line, no commas between function parameters, and no
parens surrounding function arguments. There is even an operator (stolen from
Haskell) dedicated to avoiding parens. It works by evaluating the entire right
side of the operator before the left. With it, you can change this

```python
print (foo (bar x))
```

to this

```python
print $ foo $ bar x
```

### Allow a functional style

Krill is not a purely function language like Haskell. However, the following
features allow you to write programs in a functional way.

- Dedicated operator for function composition.
- Functions are treated as first class variables.
- All functions are curried.

When using functional languages like Haskell, one of my favourite aspects is how
function composition is actively encouraged and supported by the syntax. In
Krill I wanted to replicated this, so I added the function composition operator `.`.

The function composition operator takes two functions and returns a new function
where the result of the first one is used as the input to the second.

```python
(f . g) x == f (g x)
```

With this you can create complicated functions by composing together simple
ones.

```python
even = x -> x % 2 == 0
square = x -> x * x
sumOddSquares = sum . filter (not . even) . map square
```

An important feature of functional languages is the fact that functions are
treated as first class variables. This is also the case in Krill. In fact, there
are no "functions", only lambdas. You can simulate creating a
function by assigning a lambda to a variable.

```python
add = a b -> a + b
```

Lambdas are closures since they _capture_ variables in scope.

```python
foo = _ -> {
  x = "hello"
  name -> x ++ " " ++ name
}

print $ foo () $ "jake"
# => "hello jake"
```

Another functional feature of Krill is automatic function currying. This means
that if you don't provide all arguments, a new function is returned that accepts
all remaining arguments.

```python
add10 = add 10
print $ add10 1
# => 11
```

## Implementation

Krill was implemented in Haskell and the source code is [available on
Github](https://github.com/coffee-cup/krill/). There are three main components of
the compiler: the parser, the interpreter, and the repl.

The
[parser](https://github.com/coffee-cup/krill/blob/master/src/Parser/Parser.hs)
uses the [megaparsec](https://hackage.haskell.org/package/megaparsec) parser
combinator library. My experience with the library (and parser combinators in
general) is mostly positive. My main grievances I encountered are mostly around
error reporting, but this seems to be a commonly known issue with these types of
parsers. The AST for the language has the following type.

```hs
data Expr
 = EApp Loc Expr Expr        -- a b
 | EBinOp Loc Name Expr Expr -- a + b
 | EUnOp Loc Name Expr       -- !a
 | EVar Loc Name             -- a
 | ELam Loc [Name] Block     -- x -> x + 1
 | ELit Loc Literal          -- 3
 | EIf Loc Expr Block Block  -- if cond then block else block
 | EFor Loc Name Expr Block  -- for i in [1,2,3] block
 | EAss Loc Name Expr        -- a = b
 | EList Loc [Expr]          -- [1, x, "hello"]
 | EListAcc Loc Name Expr    -- list[x]
 | ERange Loc Expr Expr Expr -- [1,2..10] or [1..10]
 | EParens Loc Expr          -- (a)
 deriving (Ord, Show)
```

The
[interpreter](https://github.com/coffee-cup/krill/blob/master/src/Eval/Eval.hs)
is built using a monad transformer stack.

```hs
type EvalMonad =
  ExceptT EvalError (StateT EvalState IO)

newtype Eval a = Eval { unEval :: EvalMonad a }
  deriving
    ( Functor
    , Applicative
    , Monad
    , MonadFix
    , MonadIO
    , MonadFail
    , MonadState EvalState
    , MonadError EvalError
    )
```

When building this part of the compiler I really learned to appreciate the value
of monad transformers and the abstraction they bring. One thing that took me a
while to figure out was how to properly report errors during evaluation.

The [repl](https://github.com/coffee-cup/krill/blob/master/src/Repl.hs) uses
[haskeline](https://hackage.haskell.org/package/haskeline) which provides a
fairly nice interface for tab completing common things such as filenames and
variable names. The repl execution loop is
fairly simple. It just runs the compiler and updates the compiler state.

```hs
exec :: CompilerM () -> Repl ()
exec compM = do
  cs <- gets _compilerState
  (cm , cs') <- liftIO $ runCompilerM compM cs
  hoistErr cm
  updateCompilerState cs'
  return ()
```

The overall compiler is also built using a monad transform stack.

```hs
type CompilerMonad =
  ExceptT CompilerError (StateT CompilerState IO)

newtype CompilerM a = Compiler { runCompiler :: CompilerMonad a }
  deriving
    ( Functor
    , Applicative
    , Monad
    , MonadFix
    , MonadIO
    , MonadFail
    , MonadState CompilerState
    , MonadError CompilerError
    )

data CompilerState = CompilerState
  { _fname :: Maybe FilePath
  , _src   :: Maybe L.Text
  , _ast   :: Maybe Module
  , _flags :: Flags.Flags
  , _evalS :: EvalState
  } deriving (Eq)
```

# Conclusions

I've really enjoyed working on Krill and have learned a lot about building
compilers. Haskell is indeed a great language for compilers. Features such as
pattern matching, monads, and abstract data types are amazing. Some aspects of
the Haskell toolchain did frustrate me. Using and version third party libraries
with Stack can be confusing. I still often get confused of the difference
between stack.yaml, package.yaml, and cabal files. I guess these frustrations
help me realise how important a programming languages supporting tools are and
is something I will keep in mind when designing new languages. An intuitive
package manager, compiler, and test runner have a huge effect on developer
experience. Something I think Rust is doing really well at.


Dynamic, curried, and minimal programming language.

The Krill Language

krill


# Introducing Stck

Stck is a [stack based](https://esolangs.org/wiki/Category:Stack-based)
[esoteric programming
language](https://esolangs.org/wiki/Esoteric_programming_language). You can
check out and use stck at [stck.jakerunzer.com](https://stck.jakerunzer.com), or
find the source on [Github](https://github.com/coffee-cup/stck).

In Stck, the only data structures are global stacks. Stacks are identified
using a sequence of alpha characters.

```
# this is a comment!

1>a # push 1 onto stack a
a>  # pop from a
a>b # pop from a and push to b
```

The stacks `o` and `i` are used to output to standard out and take input from
standard in, respectively.

There are two types of primitives in Stck: strings and numbers.

```
"hello">a
1>b
```

In addition to pushing and popping, you can also manipulate the stacks with
operators. Currently, there are four mathematical operators: `+, -, *, /`. The syntax is

`stack+operand` or `stack+stack` or `stack+`

For example,

- `a+b`: Pop from a and b, perform addition, push the result to a.
- `a+`: Pop two values from a, perform addition, push the result to a.
- `a+4`: Pop from a, perform addition with the literal 4, push the result to a.

There is also the clear operator, `?`. `a?` will clear the stack if the topmost
value is 0.

Additionally, there are loops and functions.

```
# create function
{:foo
  # function body
}

:foo # call function foo
```

```
(n
  # loop until stack n is empty
)
```

## Motivation

Stck was created because there was a period of time where I was really into
esolangs and wanted to contribute to that world. Exploring programming language
concepts and design is super interesting. I had never used or created a stack
based language, so I thought that was a good place to start. I will definitely
be creating another esolang in the future, although probably not a stack based
one.

tags: [[languages]]

Introducing Stck

stck


# Babel Macros

[Babel](https://babeljs.io/) macros are a way to apply code transformations
without having to install a new plugin for each transformation. They are
implemented in a clever way and can be very useful. And best of all, they work
out of the box with Create React App, GatsbyJS, and NextJS. This post will dive
into what they are, how to use them, and how to make them using TypeScript.

## Why?

Regular Babel plugins are great, but come with a few downsides.

- They can be difficult for users to setup and configure, especially when using
tools like [CRA](https://create-react-app.dev/) and
[Gatsby](https://www.gatsbyjs.org/). CRA [straight up prevents you](https://github.com/facebook/create-react-app/issues/167) from
editing the config.
- Plugins can lead to confusion as it can be unclear what in the code is being
transpiled and what isn't.
- They can conflict in non-intuitive ways. The ordering you define the plugins
  in is important and when the ordering causes a bug, it can be impossible to
  debug.
  
Babel macros to the rescue!

## What?

Babel macros are possible because of the
[babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) library
(which is itself a Babel plugin).

This library enables other libraries to create macros by

1. treating all imports that end in `.macro` or `/macro` as a macro.
2. providing a `createMacro` function that gives access to Babel.

## But TypeScript?

If you use TypeScript you can still benefit from the power of macros. Instead of
using the TypeScript compiler (tsc) to compile your code, you can use Babel
with the [TypeScript preset](https://babeljs.io/docs/en/babel-preset-typescript)
instead. This is what CRA, Gatsby, and Next are already configured to do.

## Usage

If you are not using CRA, Gatsby, or Next and have full control over the Babel
pipeline, you can enable using Babel macros in your project by adding the
dependency (if you are using these tools, then you don't have to install or
configure anything).

```shell
npm i --save-dev babel-plugin-macros
```

and adding it to your Babel config

```json
// .babelrc
{
  "plugins": ["macros"]
}
```

Use a macro just by importing it like any other JavaScript dependency. For
example, the [count.macro](https://github.com/coffee-cup/count.macro).

```javascript
import { lines } from "count.macro";

console.log(`This file has ${lines} lines`);
```

## Development

Let's make a macro! The macro will place the contents of a file into a variable
at compile time. A user will be able to use it like this:

```ts
import file from "my.macro";

const contents = file("my-file.txt");
```

This section assumes you have some knowledge of
[ASTs](https://en.wikipedia.org/wiki/Abstract_syntax_tree) and how to manipulate
them with Babel. The [plugin
handbook](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md)
and [AST explorer](https://astexplorer.net/) are great resources for learning or
familiarising yourself with these concepts.

### Caveats

There are a few caveats you have to keep in mind when developing a macro.

- Macros are evaluated at compile time. This means that the code you write must
  be able to run in Node on whatever machine is using the macro. This means no
`import/export` syntax... unless you compile your macro before using it
(_meta_). In this example we will use TypeScript and compile with `tsc`, but you
can just as easily write your macro in ES6 and compile it with Babel. Just
remember, after updating your macro, **remember to recompile**.
- They must be synchronous. If you do in file IO, make sure to use the sync version.
- To enable type checking when the macro is used in TypeScript, you must lie
  about the type.

### TypeScript

We are going to develop it in TypeScript. If you are not using TypeScript you
can still follow along, just remove the type definitions.

### Setup

First we need to install our dependencies. We will use `yarn` for this.

```shell
yarn add babel-plugin-macros
yarn add --dev typescript jest ts-jest @types/babel__core @types/node @babel/cli @babel/preset-typescript
```

If using TypeScript, create a tsconfig file. [Something like
this](https://github.com/coffee-cup/count.macro/blob/master/tsconfig.json).
Also, if you are using TypeScript you will want to add some definitions for
`babel-plugin-macros` (the ones on
[DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) are a bit
outdated at the time of writing this. There is a PR open to update them). You
can [grab the updated ones from here](https://github.com/coffee-cup/count.macro/blob/master/typings/babel-plugin-macros.d.ts).


Next we can add some npm/yarn scripts.

```json
"scripts": {
  "build": "tsc -p .",
  "test": "jest",
  "compile": "yarn run build && babel --plugins=babel-plugin-macros --presets=@babel/preset-typescript"
}
```

The `compile` script will first compile our macro, then compile an example file
with Babel. This is really helpful when testing and developing.

Finally, we can create our macro and an example to test with.

```ts
// src/index.macro.ts

// TODO
```

```ts
// examples/test.ts
const x = 1;
```

Run our example with

```shell
yarn compile examples/test.ts
```

You should see the contents of the file output to the console. Awesome! We are
now setup.

### Macro Definition

A macro is created by calling the `createMacro` function from
`babel-plugin-macros`. The macro must be the default export.

```ts
import { createMacro } from "babel-plugin-macros";

const myMacro = createMacro(/* ... */);
export default myMacro;
```

The first argument to `createMacro` is a function that takes an single
parameter: an object with a references, state, and Babel field. This is the type
definition:

```ts
export type References = {
  [key: string]: Babel.NodePath[];
};

export interface MacroParams {
  references: { default: References } & References;
  state: any;
  babel: typeof Babel;
}

export type MacroHandler = (params: MacroParams) => void;

export function createMacro(handler: MacroHandler, options?: Options);
```

#### references

This is the main thing our macro will use to manipulate the AST. References is
an object that contains Babel `NodePaths` all the places your macro was
imported. For example, if I have the following source.

```ts
import foo, { bar } from "my.macro";

foo(); // line 3
foo(); // line 4

const x = bar + 1; // line 6
```

References will be:

```ts
{
  default: [/* NodePath line 3 */, /* NodePath line 4 */],
  bar: [/* NodePath line 6 */]
}
```

This is important to note and tripped me up when I was first learning about
macros. 

> The default export of your macro file is always called with references
to all places it was imported and used. Even if the user imports a named
export from your macro, the default export will still be called.

Since references contain Babel `NodePaths`, they allow use to manipulate the
ASTs. This is what we will use below.

#### state

The state of the file being traverse. This is the second argument received in a
visitor function of a normal Babel plugin. It will look something like:

```json
{
  "file": {
    "declarations": {},
    "path": NodePath,
    "ast": Node,
    "code": string,
    "opts": {
      /* ... */
    },
    "scope": Scope
    // ...
  },
  "filename": string
  // ...
}
```

#### babel

Same as `require("babel-core")`. We can use it to get [Babel
types](https://babeljs.io/docs/en/babel-types).

```ts

const myMacro = ({ references, state, babel }) => {
  const t = babel.types;
};
```

## Our Macro 

With the above knowledge, here is our macro.

```ts
import { createMacro, MacroHandler } from "babel-plugin-macros";
import * as fs from "fs";
import * as path from "path";

const myMacro: MacroHandler = ({ references, state, babel }) => {
  const t = babel.types;
  const currentFilename = state.file.opts.filename;

  references.default.map(({ parentPath }) => {
    if (
      t.isCallExpression(parentPath.node) &&
      t.isStringLiteral(parentPath.node.arguments[0])
    ) {
      const filename = path.resolve(
        path.dirname(currentFilename),
        parentPath.node.arguments[0].value
      );
      const contents = fs.readFileSync(filename, "utf8");
      parentPath.replaceWith(t.stringLiteral(contents));
    }
  });
};

export default createMacro(myMacro) as (filename: string) => string;
```

You can see I had to manually case the type to `(filename: string) => string`.
This way TypeScript users will get type checking and autocomplete when using
this macro. If my macro was a named export instead, I could type with:

```ts
export const file = null as (filename: string) => string;
```

Finally, we can change the example to:

```ts
// examples/test.ts
import file from "../lib/index.macro";

const contents = file("test.ts");
```

The tranpsiled code will be,

```ts
const contents = "import file from \"../lib/index.macro\";\n\nconst contents = file(\"test.ts\");\n";
```

## Conclusion

Babel macros are a great way to add compile time transformations to your
project. They are low effort to setup and already work if you are using CRA,
Gatsby, or Next. There are already a lot of macros available (check out
[awesome-babel-macros](https://github.com/jgierer12/awesome-babel-macros)), but
I believe there is still a lot of untapped potential. They are also fairly easy to
create, especially if you already have some experience writing Babel plugins.


tags: [[web]]

Babel Macros

babel-macros


# Introducing Favocon

Favocon is a small command line utility I made for generating favicons from
images. It is available on [cargo](https://crates.io/crates/favocon), the
[[Rust]] package registry.

![favocon usage gif](https://user-images.githubusercontent.com/3044853/57985881-5dc5ae80-7a66-11e9-8a8a-fff327b83e73.gif)

[Favicons](https://en.wikipedia.org/wiki/Favicon) are the little icon you see on
the tab for a website.

Favicon files (`.ico` extension) contain one or more small icons inside of them.
When they were invented they were useful because the same file could be used for
a websites icon in the browser and a websites icon when saved to the desktop
(something a lot more popular in 1999). Browsers today look for `<link
rel="icon" href="...">` tags in the HTML and support multiple file formats and
sizes. However, they still fallback to a `favicon.ico` placed at the root of the
website.

Generating these files can be a pain. I would normally have a single high
quality icon I want to use, and somehow need to generate PNGs at multiple
resolutions, an ICO file, and a [site manifest
file](https://developers.google.com/web/fundamentals/web-app-manifest). I would
often just Google "favicon generator" and use one of the top results, which
don't get me wrong, work really well. But I wanted something with less friction.

Favocon does just that. In its simplest usage just call `favocon` with a path to
an image file. All the files you need will be saved to `favocon/` and The HTML you
should place in the head of your `index.html` file are output to the console.

The tool is [free to use](https://crates.io/crates/favocon) and [open source on
Github](https://github.com/coffee-cup/favocon). Please feel free to contribute
or create an issue if you think of any improvements.

tags: [[web]]

Intorducing Favocon

favocon


# Static Sites

I first started web development in 2013 by learning HTML and CSS. I created
simple photography and portfolio sites with unnecessarily complicated nested
DIVs and terribly written CSS. I remember wondering why DOM elements could have
classes because I just put IDs on everything and styled them directly. Like most
[[web]] developers, my journey lead me to learn JavaScript. First JQuery, followed
by frameworks such as Angular 1, EmberJS, React, and Elm.

After learning these frameworks I was convinced that the future of the web was
single page apps. Myself, and many other developers create SPAs for the simplest
sites. I believe this trend of using the latest and greatest framework for
everything has made some of us forget just how useful dead simple static
websites can be.

## Benefits of Static Sites

- Works on all web browsers
- Small file sizes (fast)
- Works for noScript users
- Content is more cache friendly

## Benefits of JavaScript Frameworks

- Good for content that is constantly changing
- Load content without refreshing the page
- Best for web apps

## Closing Thoughts

I wrote this post so that I (and hopefully others) remember that the web was
literally created to serve static content. Only in the last 10 years have we
_hacked_ it to make it work with dynamic content.
Before immediately reaching for the newest JavaScript (or Elm) framework, take a
step back, consider all the options, and choose the best tool for the job.

tag: [[web]]

Static Sites

static-sites


# Applicatives

Applicative [[functors]] are more powerful than Functors but not as powerful as
monads. They provide a way to partially apply a function inside an Applicative
context to parameters also inside the same context.

Confused? Well hopefully after this article you won't be.

As we saw [[functors|earlier]], a Functor is just a [[haskell]] typeclass with the
single required `fmap` function.

```haskell
class Functor f where
  fmap :: (a -> b) -> f a -> f b
```

We can apply a function from `a -> b` to a value wrapped inside of a functor
context.

Now what if we want to apply a function to multiple arguments that are all
wrapped inside of a context? Such as summing two numbers wrapped in a `Maybe`.

```haskell
(Just 1) + (Just 2) -- ?
```

If we apply `fmap` to `Just 1` with the `(+)` function we get back another
function wrapped in the `Maybe` context.

```haskell
ghci> :t (+) <$> Just 1
(+) <$> Just 1 :: Num a => Maybe (a -> a)
```

But now we are stuck. We need to apply a function inside of the Maybe context to
a number inside the Maybe context.

This is where Applicatives come in!

They allow us to take a function which operates on <span
class="underline">normal</span> unwrapped values, and apply it to parameters
which are all wrapped in a context.

The typeclass definition requires all Applicatives to be Functors (meaning they
all implement the `fmap` function).

```haskell
class (Functor f) => Applicative f where
  pure  :: a -> f a
  (<*>) :: f (a -> b) -> f a -> f b
```

Additionally, an Applicative must implement the `pure` and `(<*>)` functions.

`pure` just takes a normal unwrapped value and wraps it into an Applicative
context.

`(<*>)` takes a function wrapped in an Applicative context and a parameter also
wrapped. It then unwraps both, applies `a` to the function, and wraps the result
back up.

Lets see how it is implemented for the `Maybe` type.

```haskell
instance Applicative Maybe where
  pure x = Just x
  (Just f) <*> (Just x) = Just (f x)
  _ <*> _ = Nothing
```

If either Maybe types are `Nothing` then `Nothing` is returned. Otherwise, each
value is unwrapped (via pattern matching), the function is applied to the
contents of second Maybe, and the result is wrapped back up as a Maybe.

Since all functions in Haskell are curried, we can partially apply a function of
`n` arguments to `n` parameters wrapped in the Applicative context.

Using our above example, summing two numbers wrapped in a Maybe would look like
this

```haskell
ghci> (+) <$> Just 1 <*> Just 2
Just 3
```

We first use `<$>` to partially apply `+` to `Just 1`. Functor stuff. But then
we use `<*>` to take the wrapped function and apply it to the wrapped parameter.

Alternatively we can use the `pure` function to wrap `(+)` inside of an
Applicative.

```haskell
ghci> pure (+) <*> Just 1 <*> Just 2
Just 3
```

What happens if one of the parameters is `Nothing`?

```haskell
ghci> (+) <$> Just 1 <*> Nothing
Nothing
```

This is awesome! We don't have to worry about checking whether or not our
parameters are valid. The `(<*>)` function does that for us under the hood.


Applicatives

applicatives


# Functors

In mathematics, Functors are a mapping between categories. They define a way to
convert an object in one category to an object in another.

In programming, they are basically the same thing.

> A Functor is a data structure that can be mapped over.

The term Functor is most commonly used in Haskell, but nothing about them are
specific to [[Haskell]].

The Haskell Functor type class is defined as

```haskell
class Functor f where
  fmap :: (a -> b) -> f a -> f b
```

This means that all data structures that are Functors must implement the `fmap`
function. `fmap` take two parameters. `(a -> b)` is a function which takes a
single parameter of type `a` and returns an item of type `b`. The second
parameter to `fmap` is a Functor of type `a`. A Functor of type `b` is returned.

## Lists

Lets look at an example: The list data structure.

Lists are homogeneous containers which hold 0 or more items. How can we
implement a `fmap` function that allows us to map over every item in the list?
In other words, we need to apply a function to every element in the list and
create a new list with the result of each function application.

```haskell
instance Functor [] where
  fmap _ [] = []
  fmap f (x:xs) = f x : fmap f xs
```

Awesome! A short recursive function which applies `f` to `x`, and appends the
result to `fmap` applied to the tail (rest) of the list. Our base case is when
we get an empty list.

We can now map over any list like so

```haskell
ghci> fmap (^2) [1,2,3]
[1,4,9]

ghci> fmap show [4,5,6]
["4","5","6"]
```

Lists are the most intuitive example for functors, but any data structure can
become one.

## Binary Trees

Let's look at binary trees.

A binary tree can be either empty or of some value with subtrees on the left and
right. In Haskell we would represent that as

```haskell
data Tree a
  = Nil
  | Node a (Tree a) (Tree a)
  deriving (Show)
```

We can make `Tree` a Functor by making it an instance of the typeclass

```haskell
instance Functor Tree where
 fmap _ Nil = Nil
 fmap f (Node x left right) =
   Node (f x) (fmap f left) (fmap f right)
```

All this does it apply the function `f` to every node of the tree. Now we can do
things like this

```haskell
ghci> let t = Node 2 (Node 1 Nil Nil) (Node 6 Nil Nil)

ghci> :t t
t :: Num a => Tree a

ghci> fmap (*10) t
Node 20 (Node 10 Nil Nil) (Node 60 Nil Nil)

ghci> fmap show t
Node "2" (Node "1" Nil Nil) (Node "6" Nil Nil)
```

## Maybes

Another less intuitive instance of the Functor typeclass is the `Maybe` type.

A `Maybe` can be `Nothing` or `Just` a value.

When you map over a Maybe with the function `f`, it will apply `f` to the
contents of the Maybe if it is `Just` a value, otherwise it just returns
`Nothing`.

```haskell
instance Functor Maybe where
  fmap _ Nothing = Nothing
  fmap f (Just x) = Just (f x)
```

As an example, lets say we want to get the head of a list but not crash our
program if the list is empty.

```haskell
safeHead :: [a] -> Maybe a
safeHead [] = Nothing
safeHead (x:xs) = Just x
```

If the list is empty we return `Nothing`, otherwise we return `Just x`.

```haskell
ghci> safeHead [1,2,3]
Just 1

ghci> safeHead []
Nothing
```

Now if, for whatever reason, we want to square the head of the list, we could
pattern match on the `Maybe` type to extract the wrapped value and apply the
function.

```haskell
doubleHead :: [Int] -> Maybe Int
doubleHead l =
  case safeHead l of
    Nothing -> Nothing
    Just x -> Just (x^2)
```

But since `Maybe` is an instance of the Functor typeclass we can instead use
`fmap`.

```haskell
ghci> fmap (^2) $ safeHead [2,3,4]
Just 4

ghci> fmap (^2) $ safeHead []
Nothing
```

Much nicer!

## Sugar

Haskell provides a nice infix operator for Functors. This is the `(<$>)`
function, synonymous to `fmap`.

```haskell
ghci> :t (<$>)
(<$>) :: Functor f => (a -> b) -> f a -> f b
```

Our previous examples could have been written like

```haskell
ghci> (^2) <$> [1,2,3]
[1,4,9]

ghci> (*10) <$> Node 2 (Node 1 Nil Nil) (Node 6 Nil Nil)
Node 20 (Node 10 Nil Nil) (Node 60 Nil Nil)

ghci> (^2) <$> safeHead [2,3,4]
Just 4
```


My Garden

Seeds to Start From 🌱

Latest