```yaml
---
slug: mocking-aws-with-msw
published: 2024-03-06T18:49:00-08:00
description: A Better Way to Mock AWS
changelog: ~
---
```

We use AWS pretty heavily at Taskless, with their compute-on-demand making it easy for us to scale our bi-directional API Gateway from zero to thousands of concurrent requests with no additional effort. It's truly wonderful; that is, until it's time to write tests.

The path most developers go is to grab the [aws-sdk-client-mock](https://github.com/m-radzikowski/aws-sdk-client-mock) library, which works really well assuming you don't have presigning, are using AWS Timestream, and can keep all your AWS libraries on the exact same version to avoid type conflicts.

I'm also assuming you're here because you either need pre-signing, are using AWS Timestream, think force-upgrading all AWS client libraries for a single fix is a difficult pill to swallow, or are otherwise jammed on a traditional mocking approach. The good news is, there **is** another way. We just have to move from the node / module layer down to the network layer.

## What Are You Testing, Really?

First, the realization. We don't actually care what the `@aws-sdk/*` libraries do.

There's a lot of internals in the AWS client libraries (middleware, smithy, signing, etc). Every one of them has their own abstractions, inputs, outputs, and naming conventions. Some concepts, like middleware, are impossible to mock. None of that matters though. What we **do** care about is how our app reacts to network conditions, including those made by the SDK libraries.

And **that** we can test.

* We can introduce network delays and ensure the libraries we depend on handle these events well
* We can simulate a service being down
* We use APIs instead of SDKs, which are less volatile
* We gain a better understanding about how AWS makes its network requests
* We catch if a dependency suddenly starts phoning home

So how do you go about mocking the network? There's [nock](https://www.npmjs.com/package/nock) and Mock Service Worker / [MSW](https://www.npmjs.com/package/msw). Both are excellent libraries; I just prefer MSW so I can use the same testing patterns on the node.js and browser. While these next sections are written for MSW, they can be easily applied to a nock-based setup.

## Preparing for Network Mocks

Setting up for network based mocking requires a little bit of pre-work. Specifically, we want to knock out all our AWS environment variables with dummy values; this ensures if a request ever does fall through to the network layer, it cannot trigger a billable event. When launching any node.js app, including tests, you can include a `NODE_OPTIONS` environment variable which passes additional options through to the node process. In the case of a multi-process tester like [AVA](https://github.com/avajs/ava), this ensures the options are carried to each worker. For a single-process worker like [Jest](https://jestjs.io/), any node options are passed through as if they were directly on the command line.

```json
{
    // ...
    "scripts": {
        "test": "NODE_OPTIONS='-r ./test.setup.js' ava"
    }
}
```

The above snippet adjusts our test command to include additional node options. `-r <file>` tells node.js to include a file _first_ before running any other code. In this case, we want to load a bootstrap file. Our bootstrap will take care of removing all AWS environment variables for us, first by explicitly deleting all `aws_` prefixed values, then setting suitable test values for access, secrets, and tokens. I'm using [dotenv](https://www.npmjs.com/package/dotenv) for readability, but you can also explicitly set `process.env` if you prefer.

```js
const dotenv = require("dotenv");
const util = require("node:util");

util.inspect.defaultOptions.depth = 10;

for (const key of Object.keys(process.env)) {
  if (key.toLowerCase().startsWith("aws_")) {
    delete process.env[key];
  }
}

dotenv.populate(
  process.env,
  {
    AWS_ACCESS_KEY_ID: "testing",
    AWS_SECRET_ACCESS_KEY: "testing",
    AWS_SECURITY_TOKEN: "testing",
    AWS_SESSION_TOKEN: "testing",
    AWS_DEFAULT_REGION: "us-east-1",
    AWS_REGION: "us-east-1",
    // DEBUG: "*",
  },
  { override: true }
);

```

One important reason we remove all `aws_` items is because the `AWS_PROFILE` environment variable messes with pre-signing. If the variable is set, smithy middleware will attempt to authenticate and load the profile in question. So, don't be clever; take a scorched earth approach to the `aws_*` environment variables and ensure they're all replaced.

With confidence our AWS account won't get any surprise billing, we can [follow MSW's Getting Started Guide](https://mswjs.io/docs/integrations/node) for node.js and create our handlers. We can verify MSW is working because running our tests will tell us about unhandled requests, and our first call to AWS should automatically fail.

To make it easier to mock our network requests, we'll want to create a default handler.

## The Default Handler at `*`

Unhandled requests from MSW are fine, but I find that it's not always helpful telling you where / why something fell through to the unhandled request. I recommend adding these two handlers at the end of your chain, ensuring you get actionable errors when tests try and call out to AWS.

```ts
const handlers: RequestHandler[] = [
  // force inercept of any attempts to call the local AWS Credential Provider
  http.all("http://169.254.169.254/*", () => {
    throw new Error("Attempted to call local AWS Credential Provider");
  }),

  // Provide additional info beyond MSW's default unhandled request error
  http.all("*", async (info) => {
    const request = info.request.clone();

    const debug = {
      url: request.url,
      method: request.method,
      headers: Object.fromEntries(request.headers.entries()),
      body: await request.text(),
    };

    console.error("Unhandled Request");
    console.error(JSON.stringify(debug, null, 2));
  }),
];
```

Our first handler (the `169.254...`) takes care of the AWS Credential Provider. In some scenarios, like when `AWS_PROFILE` is set to a dummy value, the credential provider is automatically called by AWS. Adding a catch-all for the credential provider will tell us immediately if AWS is attempting to verify our test credentials.

The second handler is a better debugger. Instead of a thrown error that tells you the network request came from within AWS, you can unpack the URL, method, headers, and body. Usually this additional data makes it much easier to see what request isn't being mocked. As a bonus, this gives you all the information you need to write a matching handler of your own.

## Make a Lot of Mocks

There's no limit to the number of mocks you can have. Don't be afraid to have a dozen handlers for `https://dynamodb.*.amazonaws.com`, and return `undefined` if you don't want to handle the request. A return value of `undefined` from a handler tells MSW to try the next one in-sequence. For example, I check DynamoDB handlers for a specific table using the following TypeScript:

```ts
export const isGetForTable = async (original: Request, table?: string) => {
  const request = original.clone();
  const body = (await request.json()) as GetItemInput;
  if (table) {
    return body.TableName === table;
  }

  return true;
};
```

DynamoDB operates off of JSON, making it trivial to check the `TableName` for a match. When adding these checks, don't forget to `clone()` the request object! Because MSW uses the built-in `Request` object, you can only read from the request body once, just like when you're using `fetch()`.

Most of your helpers will focus on "is this a `<blank>` command" and "is this a `<blank>` command for resource `<blank>`". You only have to write these once, and then you can reuse them anywhere.

## A Little JSON, A Little XML, A Few Surprises

As you mock, you're going to discover some clients operate on XML while others work with JSON, even though all v3 endpoints support JSON now. Just [roll with it](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-xml-api-responses.html) and follow the AWS API doc's XML responses when required. You'll know when this happens because despite returning JSON, the AWS client will complain about a missing `<` or unhandled `{` in the response.

Some services, like AWS Timestream, make multiple requests. The first request (the one you'd normally associate with an endpoint) just retrieves the *real* endpoint, and the second request goes to this discovered endpoint. When you find these discovery-based services, take advantage of wildcard routes to simplify the network mocks.

Finally, while all this may seem more difficult than the usual mocking pattern, keep with it. The AWS API itself is absurdly stable. Seriously. The SQS API version is tagged November 5, 2012. So once you get these mocks working to your liking, they'll continue to work for the foreseeable future. And if AWS changes something that causes your network requests to change, you'll find out about it immediately.

## Supplement: Known Weird AWS Replies

Because not everything mocked in AWS is obvious, I'll add specific notes about libraries and mocks as I uncover them.

### SQS Uses XML

It's used in almost all infrastructure, but SQS responses are XML. Even worse, you have to include an MD5 digest that is checked by a smithy middleware. The following snippet can create XML success and error responses for the AWS XML API.

```ts
export const sendMessageXMLError = (
  code = "TestingError",
  message = "This is a custom error"
) => /* XML */ `
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>${code}</Code>
  <Message>${message}</Message>
  <RequestId>7fe4446e-b452-53f7-8f85-181e06f2dd99</RequestId>
</Error>
`;

export const sendMessageXMLResponse = (messageBody: string) => /* XML */ `
<?xml version="1.0" encoding="UTF-8"?>
<SendMessageResponse xmlns="http://queue.amazonaws.com/doc/2012-11-05/">
    <SendMessageResult>
        <MessageId>374cec7b-d0c8-4a2e-ad0b-67be763cf97e</MessageId>
        <MD5OfMessageBody>${createHash("md5")
          .update(messageBody)
          .digest("hex")}</MD5OfMessageBody>
    </SendMessageResult>
    <ResponseMetadata>
        <RequestId>7fe4446e-b452-53f7-8f85-181e06f2dd99</RequestId>
    </ResponseMetadata>
</SendMessageResponse>
`;

export const createMockSendMessageRespone = (messageBody: string): Response =>
  HttpResponse.xml(sendMessageXMLResponse(messageBody), {
    status: 200,
  });
```

### S3 PutObjectCommand Requires an Empty Body

When putting an object into s3 via `PutObjectCommand`, smithy (the engine underneath the AWS client libraries) expects an HTTP body. A test response needs to include both an empty body and a `Content-Length` header of `0`. This helper makes it easier to create responses for the command.

```ts
type MockResponseBodyOptions = {
  time?: Date;
  etag?: string;
  requestId?: string;
};

export const createMockPutResponse = (
  options?: MockResponseBodyOptions
): Response =>
  HttpResponse.arrayBuffer(new TextEncoder().encode(), {
    status: 200,
    // https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html#API_PutObject_ResponseSyntax
    headers: {
      Etag: options?.etag ?? "1b2cf535f27731c974343645a3985328",
      "Last-Modified": options?.time
        ? options.time.toISOString()
        : new Date().toISOString(),
      "x-amz-request-id":
        options?.requestId ?? "7fe4446e-b452-53f7-8f85-181e06f2dd99",
      "content-length": "0",
    },
  });
```

Link

strong

code

{
    // ...
    "scripts": {
        "test": "NODE_OPTIONS='-r ./test.setup.js' ava"
    }
}


Fence

const handlers: RequestHandler[] = [
  // force inercept of any attempts to call the local AWS Credential Provider
  http.all("http://169.254.169.254/*", () => {
    throw new Error("Attempted to call local AWS Credential Provider");
  }),

  // Provide additional info beyond MSW's default unhandled request error
  http.all("*", async (info) => {
    const request = info.request.clone();

    const debug = {
      url: request.url,
      method: request.method,
      headers: Object.fromEntries(request.headers.entries()),
      body: await request.text(),
    };

    console.error("Unhandled Request");
    console.error(JSON.stringify(debug, null, 2));
  }),
];


export const isGetForTable = async (original: Request, table?: string) => {
  const request = original.clone();
  const body = (await request.json()) as GetItemInput;
  if (table) {
    return body.TableName === table;
  }

  return true;
};


export const sendMessageXMLError = (
  code = "TestingError",
  message = "This is a custom error"
) => /* XML */ `
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>${code}</Code>
  <Message>${message}</Message>
  <RequestId>7fe4446e-b452-53f7-8f85-181e06f2dd99</RequestId>
</Error>
`;

export const sendMessageXMLResponse = (messageBody: string) => /* XML */ `
<?xml version="1.0" encoding="UTF-8"?>
<SendMessageResponse xmlns="http://queue.amazonaws.com/doc/2012-11-05/">
    <SendMessageResult>
        <MessageId>374cec7b-d0c8-4a2e-ad0b-67be763cf97e</MessageId>
        <MD5OfMessageBody>${createHash("md5")
          .update(messageBody)
          .digest("hex")}</MD5OfMessageBody>
    </SendMessageResult>
    <ResponseMetadata>
        <RequestId>7fe4446e-b452-53f7-8f85-181e06f2dd99</RequestId>
    </ResponseMetadata>
</SendMessageResponse>
`;

export const createMockSendMessageRespone = (messageBody: string): Response =>
  HttpResponse.xml(sendMessageXMLResponse(messageBody), {
    status: 200,
  });


type MockResponseBodyOptions = {
  time?: Date;
  etag?: string;
  requestId?: string;
};

export const createMockPutResponse = (
  options?: MockResponseBodyOptions
): Response =>
  HttpResponse.arrayBuffer(new TextEncoder().encode(), {
    status: 200,
    // https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html#API_PutObject_ResponseSyntax
    headers: {
      Etag: options?.etag ?? "1b2cf535f27731c974343645a3985328",
      "Last-Modified": options?.time
        ? options.time.toISOString()
        : new Date().toISOString(),
      "x-amz-request-id":
        options?.requestId ?? "7fe4446e-b452-53f7-8f85-181e06f2dd99",
      "content-length": "0",
    },
  });


Document

Mocking AWS at the Network Level

```yaml
---
slug: tailwind-css-for-email
published: 2022-10-11T15:00:00-07:00
description: While this won't remove your dependency on table tags, at least you can reuse your Tailwind colors and spacing rules in email templates
changelog: ~
---
```

I can no longer count the hours [Tailwind](https://tailwindcss.com) saves me. I don't really _hate_ the state of CSS-in-JS. I just find it gets in the way of quickly saying "make this blue, put it in a flex box oriented by row, with the items centered." It's a preference thing, and my preference is towards utility class names at this point, letting React components do any reusable composition for me. It's been great, save for one quibble; email is awful. It's not really tailwind's fault, but emails are still table-based, inline styles, and generally everything awful we definitely thought we got rid of in 2002.

What follows isn't complex enough to justify an NPM module, but it is a pattern generally usable for getting Tailwind into your HTML emails. The short version is:

1. A very minimal `tailwind.email.css` is generated using the tailwind CLI. It contains `@tailwind utilities;` and any resets I'd like to do. Be sure you add your email templates to tailwind's config file, otherwise your styles won't be included.
2. We put the generated `tailwind.email.css` through a conversion of `rem` to `px` because it's 2022 and [outlook still does not support the `rem` unit](https://www.caniemail.com/features/css-unit-rem/)
3. [juice](https://github.com/Automattic/juice) inlines the tailwind styles for us where possible, keeping the media queries in the head for email clients that support it
4. A [rehype](https://github.com/rehypejs/rehype) pipeline replaces Tailwind `--tw-` variables with their resolved values

## On Generating the HTML
For what I'm currently doing, emails are built using everyday React and a renderer that calls `ReactDOMServer.renderToStaticMarkup(element)`. The complexities of `tr` and `td` nesting is easily hidden behind some common components, which I chose to name `Row` and `Column` respectively. They're nothing fancy and based on the reality we'll probably never get flexbox in HTML emails in my lifetime.

```tsx
const tableAttributes = {
  role: "presentation",
  cellPadding: 0,
  cellSpacing: 0,
};

interface EmailComponentProps {
  className?: string;
}

export const Row: React.FC<PropsWithChildren<EmailComponentProps>> = ({
  children,
  className,
}) => {
  return (
    <table
      {...tableAttributes}
      {...({ border: "0" } as Record<string, string>)}
      className={cx(className, "w-full")}
    >
      <tr>{children}</tr>
    </table>
  );
};

export const Column: React.FC<PropsWithChildren<EmailComponentProps>> = ({
  children,
  className,
}) => {
  return <td className={className}>{children}</td>;
};
```

Ultimately though, how you generate the HTML is up to you, as long as you have it as a string.

## Tailwind Configuration
To make Tailwind email friendly, we need to disable a bunch of core plugins that don't work well across email clients. A huge shoutout goes to [Can I Email](https://www.caniemail.com). Disabling these plugins is straightforward: add them to your theme's definition, and Tailwind will make sure not to generate CSS for them. Trying to use these CSS classes will just result in useless CSS classes with no style information & can be stripped later.

```js
module.exports = {
  content: [
    // put your email paths here
  ],
  theme: {
    corePlugins: {
      preflight: false,
      backgroundOpacity: false,
      borderOpacity: false,
      boxShadow: false,
      divideOpacity: false,
      placeholderOpacity: false,
      textOpacity: false,
    },
  },
  plugins: [],
};

```

## Converting `rem` to `px`

I wasn't keen on building a completely custom `tailwind.config.js` file, and the `rem` unit is easy enough to convert from as long as you specify a base value in pixels. Tailwind [uses a default base](https://tailwindcss.com/docs/customizing-spacing#default-spacing-scale) of `16px`, so we can convert all of our units via a regular expression.

```ts
const css = originalCSS.replace(
  /([\d.-]+rem)/gi,
  (_, value) => `${parseFloat(value.replace(/rem$/, "")) * 16}px`
);
```

## Applying juice

Our stylesheet is now email friendly, and it's time for [juice](https://github.com/Automattic/juice).

> Given HTML, juice will inline your CSS properties into the style attribute.

Cool. That sounds exactly what we're looking to do. We'll take our HTML plus our px-friendly CSS and ask juice to merge the two together into a final output.

```ts
const juiced = juice(html, { extraCss: css });
```

That's mostly it. Juice takes care of the inline style tags for us where it can, defaulting to a `<style>` tag in the head where it can't (ie media queries), and just generally does the right thing all the time. About the only thing it can't do is fix custom CSS variables, but [there's an issue for CSS variable support](https://github.com/Automattic/juice/issues/312) with a workaround. We'll use code similar to the workaround, but with a tool that's a bit faster than cheerio.

## Resolving CSS Variables

Resolving our CSS variables requires us to make a few assumptions about how email clients behave. First, if a client supports advanced CSS such as `@media` queries, they also support CSS variables. That means the only CSS variables we'll need to care about are those located inline and in the body. Second, we can assume that Tailwind isn't going to generate any weird syntax. CSS variables will be in the form of `--declaration: value`, and usage will be in the form of `var(--declaration)` with an optional fallback.

Replacing the variables will require two passes. On the first pass, we'll capture all our CSS variables assigned to the inline style, and on the second, we'll replace our `var()` statements with the resolved values. Using [`rehype`](https://github.com/rehypejs/rehype) and [`rehype-rewrite`](https://github.com/jaywcjlove/rehype-rewrite) makes this a straightforward task.

```ts
const variableDefRegex = /(--[a-zA-Z0-9-_]+)\s*:\s(.+?);/g;
const variableUsageRegex = /var$(\s*--[a-zA-Z0-9-_]+\s*)(?:$|,\s*(.*)\))/;
const hyped = rehype()
  .use(rehypeRewrite, {
    rewrite: (node) => {
      if (node.type !== "element") {
        return node;
      }
      const resolveVariables = (s: string): string => {

        // pass 1: pull definitions
        const defs = new Map<string, string>();
        let withoutDefs = s.replace(
          variableDefRegex,
          (_, def: string, value: string) => {
            defs.set(def.trim(), value.trim());
            return "";
          }
        );

        // pass 2: replace variables (maxCycles prevents Terrible Things from happening)
        let maxCycles = 1000;
        while (withoutDefs.match(variableUsageRegex)) {
          maxCycles--;
          if (maxCycles <= 0) {
            throw new Error("Max Cycles for replacement exceeded");
          }
          withoutDefs = withoutDefs.replace(
            variableUsageRegex,
            (_, def: string, fallback: string) => {
              const d = def.trim();
              if (defs.has(d)) {
                return defs.get(d) ?? "";
              }
              return (fallback ?? "").trim();
            }
          );
        }

        // return clean result
        return withoutDefs;
      };
      node.properties = {
        ...node.properties,
        style: resolveVariables(`${node.properties?.style ?? ""}`),
      };
    },
  })
  .use(stringify)
  .processSync(juiced)
  .toString();
```

## Wrapping Up

At this point, I'm pretty happy with where the code is. The generated tailwind output from the email.css is easy to understand and manage since it's just vanilla tailwind. Juice is doing what it does best, and the only manual adjustments in the code are converting the `rem` to `px` and fixing of inline CSS variables. That's a really small amount of maintained code relative to an email specific library and build system in exchange for the full power of Tailwind. Emails still suck, but hopefully they'll suck a little less. With the Libraries in place, we put together the Taskless Usage in about 20 minutes.

![image](https://user-images.githubusercontent.com/1795/193527500-a0ada56c-272b-4809-b886-8f112312ef5e.png)

And the associated code:

```ts
/* mailwindCss.ts */
import { readFile } from "node:fs/promises";
import juice from "juice";
import { rehype } from "rehype";
import rehypeRewrite from "rehype-rewrite";
import stringify from "rehype-stringify";

/** Cache of compiled tailwind files */
const twcCache = new Map<string, Promise<string>>();

/**
 * Originally based on The MailChimp Reset from Fabio Carneiro, MailChimp User Experience Design
 * More info and templates on Github: https://github.com/mailchimp/Email-Blueprints
 * http://www.mailchimp.com &amp; http://www.fabio-carneiro.com
 * These styles are non-inline; they impact UI added by email clients
 * By line:
 * (1) Force Outlook to provide a "view in browser" message
 * (2) Force Hotmail to display emails at full width
 * (3) Force Hotmail to display normal line spacing
 * (4) Prevent WebKit and Windows mobile changing default text sizes
 * (5) Remove spacing between tables in Outlook 2007 and up
 * (6) Remove table borders on MSO 07+ http://www.campaignmonitor.com/blog/post/3392/1px-borders-padding-on-table-cells-in-outlook-07/
 * (7) Specify bicubic resampling for MSO on img objects
 * (8) Media Query block - Pretty phone numbers in email: http://www.campaignmonitor.com/blog/post/3571/using-phone-numbers-in-html-email
 * (9) Media Query block - same as above, but for tablet sized devices
 */
const universalStyles = /*css*/ `
  #outlook a{ padding:0; }
  .ReadMsgBody{ width:100%; } .ExternalClass{ width:100%; }
  .ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div { line-height: 100%; }
  body, table, td, p, a, li, blockquote{ -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
  table, td{ mso-table-lspace:0pt; mso-table-rspace:0pt; }
  table td {border-collapse: collapse;}
  img{-ms-interpolation-mode: bicubic;}
  @media only screen and (max-device-width: 480px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
  @media only screen and (min-device-width: 768px) and (max-device-width: 1024px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
`;

/**
 * Inline reset styles
 * These set common defaults for a consistent UI. Their comments will be automatically stripped by juice
 */
const resetStyles = /*css*/ `
  /* default margin/padding, box sizing*/
  * { margin: 0; padding: 0; box-sizing: border-box; }
  /* height 100% all the way down */
  table, tr, td {height: 100%;}
  /* img behavior - bicubic ms resizing, no border, fix space gap on gmail/hotmail */
  img { outline: none; text-decoration: none; -ms-interpolation-mode: bicubic; display: block; }
  a img { border: none; }
  /* mso 07, 10 table spacing fix http://www.campaignmonitor.com/blog/post/3694/removing-spacing-from-around-tables-in-outlook-2007-and-2010 */
  table { border-collapse: collapse; mso-table-lspace: 0pt; mso-table-rspace: 0pt;}
  /* tel/sms links are unstyled by default */
  a[href^="tel"], a[href^="sms"] { text-decoration: none; pointer-events: none; cursor: default; }
`;

const variableDefRegex = /(--[a-zA-Z0-9-_]+)\s*:\s(.+?);/g;
const variableUsageRegex = /var$(\s*--[a-zA-Z0-9-_]+\s*)(?:$|,\s*(.*)\))/;

/** Juices the styles, and then resolves CSS variables and additional HTML adjustements via rehype */
const inlineStyles = (html: string, css?: string) => {
  const juiced = juice(html, { extraCss: css });
  const hyped = rehype()
    .use(rehypeRewrite, {
      rewrite: (node) => {
        if (node.type !== "element") {
          return node;
        }

        // inline styles into the <head>
        if (node.tagName === "head") {
          node.children = [
            ...node.children,
            {
              type: "element",
              tagName: "style",
              children: [{ type: "text", value: universalStyles }],
            },
          ];
        }

        const resolveVariables = (s: string): string => {
          // pass 1: pull definitions
          const defs = new Map<string, string>();
          let withoutDefs = s.replace(
            variableDefRegex,
            (_, def: string, value: string) => {
              defs.set(def.trim(), value.trim());
              return "";
            }
          );

          // pass 2: replace variables
          let maxCycles = 1000;
          while (withoutDefs.match(variableUsageRegex)) {
            maxCycles--;
            if (maxCycles <= 0) {
              throw new Error("Max Cycles for replacement exceeded");
            }
            withoutDefs = withoutDefs.replace(
              variableUsageRegex,
              (_, def: string, fallback: string) => {
                const d = def.trim();
                if (defs.has(d)) {
                  return defs.get(d) ?? "";
                }
                return (fallback ?? "").trim();
              }
            );
          }

          // return clean result
          return withoutDefs;
        };
        node.properties = {
          ...node.properties,
          style: resolveVariables(`${node.properties?.style ?? ""}`),
        };
      },
    })
    .use(stringify)
    .processSync(juiced)
    .toString();
  return hyped;
};

interface MailwindOptions {
  /** A path to your tailwind.css file, optimized for email */
  tailwindCss: string;
  /** The base px value for 1rem, defaults to 16px */
  basePx?: number;
  /** Set to `false` to disable extended resets */
  reset?: boolean;
}

const mailwindCss = async (email: string, options: MailwindOptions) => {
  const basePx = options?.basePx ?? 16;

  // cache promise for performance in serverless environments
  if (
    !twcCache.has(options.tailwindCss) ||
    process.env.NODE_ENV === "development"
  ) {
    // console.log("loading styles");
    const p = new Promise<string>((resolve, reject) => {
      readFile(options.tailwindCss)
        .then((buf) => {
          const s = buf.toString();
          // rem to px
          const pxed = s.replace(
            /([\d.-]+rem)/gi,
            (_, value) => `${parseFloat(value.replace(/rem$/, "")) * basePx}px`
          );
          resolve(pxed);
        })
        .catch((reason) => reject(reason));
    });
    twcCache.set(options.tailwindCss, p);
  }

  const s = await twcCache.get(options.tailwindCss);
  if (typeof s === "undefined") {
    throw new Error(`Could not load tailwind css from ${options.tailwindCss}`);
  }

  return inlineStyles(
    email,
    options.reset === false ? s : [resetStyles, s].join("\n")
  );
};

export default mailwindCss;
```


While this won't remove your dependency on table tags, at least you can reuse your Tailwind colors and spacing rules in email templates

module.exports = {
  content: [
    // put your email paths here
  ],
  theme: {
    corePlugins: {
      preflight: false,
      backgroundOpacity: false,
      borderOpacity: false,
      boxShadow: false,
      divideOpacity: false,
      placeholderOpacity: false,
      textOpacity: false,
    },
  },
  plugins: [],
};



const css = originalCSS.replace(
  /([\d.-]+rem)/gi,
  (_, value) => `${parseFloat(value.replace(/rem$/, "")) * 16}px`
);


blockquote

const juiced = juice(html, { extraCss: css });


/* mailwindCss.ts */
import { readFile } from "node:fs/promises";
import juice from "juice";
import { rehype } from "rehype";
import rehypeRewrite from "rehype-rewrite";
import stringify from "rehype-stringify";

/** Cache of compiled tailwind files */
const twcCache = new Map<string, Promise<string>>();

/**
 * Originally based on The MailChimp Reset from Fabio Carneiro, MailChimp User Experience Design
 * More info and templates on Github: https://github.com/mailchimp/Email-Blueprints
 * http://www.mailchimp.com &amp; http://www.fabio-carneiro.com
 * These styles are non-inline; they impact UI added by email clients
 * By line:
 * (1) Force Outlook to provide a "view in browser" message
 * (2) Force Hotmail to display emails at full width
 * (3) Force Hotmail to display normal line spacing
 * (4) Prevent WebKit and Windows mobile changing default text sizes
 * (5) Remove spacing between tables in Outlook 2007 and up
 * (6) Remove table borders on MSO 07+ http://www.campaignmonitor.com/blog/post/3392/1px-borders-padding-on-table-cells-in-outlook-07/
 * (7) Specify bicubic resampling for MSO on img objects
 * (8) Media Query block - Pretty phone numbers in email: http://www.campaignmonitor.com/blog/post/3571/using-phone-numbers-in-html-email
 * (9) Media Query block - same as above, but for tablet sized devices
 */
const universalStyles = /*css*/ `
  #outlook a{ padding:0; }
  .ReadMsgBody{ width:100%; } .ExternalClass{ width:100%; }
  .ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div { line-height: 100%; }
  body, table, td, p, a, li, blockquote{ -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
  table, td{ mso-table-lspace:0pt; mso-table-rspace:0pt; }
  table td {border-collapse: collapse;}
  img{-ms-interpolation-mode: bicubic;}
  @media only screen and (max-device-width: 480px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
  @media only screen and (min-device-width: 768px) and (max-device-width: 1024px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
`;

/**
 * Inline reset styles
 * These set common defaults for a consistent UI. Their comments will be automatically stripped by juice
 */
const resetStyles = /*css*/ `
  /* default margin/padding, box sizing*/
  * { margin: 0; padding: 0; box-sizing: border-box; }
  /* height 100% all the way down */
  table, tr, td {height: 100%;}
  /* img behavior - bicubic ms resizing, no border, fix space gap on gmail/hotmail */
  img { outline: none; text-decoration: none; -ms-interpolation-mode: bicubic; display: block; }
  a img { border: none; }
  /* mso 07, 10 table spacing fix http://www.campaignmonitor.com/blog/post/3694/removing-spacing-from-around-tables-in-outlook-2007-and-2010 */
  table { border-collapse: collapse; mso-table-lspace: 0pt; mso-table-rspace: 0pt;}
  /* tel/sms links are unstyled by default */
  a[href^="tel"], a[href^="sms"] { text-decoration: none; pointer-events: none; cursor: default; }
`;

const variableDefRegex = /(--[a-zA-Z0-9-_]+)\s*:\s(.+?);/g;
const variableUsageRegex = /var$(\s*--[a-zA-Z0-9-_]+\s*)(?:$|,\s*(.*)\))/;

/** Juices the styles, and then resolves CSS variables and additional HTML adjustements via rehype */
const inlineStyles = (html: string, css?: string) => {
  const juiced = juice(html, { extraCss: css });
  const hyped = rehype()
    .use(rehypeRewrite, {
      rewrite: (node) => {
        if (node.type !== "element") {
          return node;
        }

        // inline styles into the <head>
        if (node.tagName === "head") {
          node.children = [
            ...node.children,
            {
              type: "element",
              tagName: "style",
              children: [{ type: "text", value: universalStyles }],
            },
          ];
        }

        const resolveVariables = (s: string): string => {
          // pass 1: pull definitions
          const defs = new Map<string, string>();
          let withoutDefs = s.replace(
            variableDefRegex,
            (_, def: string, value: string) => {
              defs.set(def.trim(), value.trim());
              return "";
            }
          );

          // pass 2: replace variables
          let maxCycles = 1000;
          while (withoutDefs.match(variableUsageRegex)) {
            maxCycles--;
            if (maxCycles <= 0) {
              throw new Error("Max Cycles for replacement exceeded");
            }
            withoutDefs = withoutDefs.replace(
              variableUsageRegex,
              (_, def: string, fallback: string) => {
                const d = def.trim();
                if (defs.has(d)) {
                  return defs.get(d) ?? "";
                }
                return (fallback ?? "").trim();
              }
            );
          }

          // return clean result
          return withoutDefs;
        };
        node.properties = {
          ...node.properties,
          style: resolveVariables(`${node.properties?.style ?? ""}`),
        };
      },
    })
    .use(stringify)
    .processSync(juiced)
    .toString();
  return hyped;
};

interface MailwindOptions {
  /** A path to your tailwind.css file, optimized for email */
  tailwindCss: string;
  /** The base px value for 1rem, defaults to 16px */
  basePx?: number;
  /** Set to `false` to disable extended resets */
  reset?: boolean;
}

const mailwindCss = async (email: string, options: MailwindOptions) => {
  const basePx = options?.basePx ?? 16;

  // cache promise for performance in serverless environments
  if (
    !twcCache.has(options.tailwindCss) ||
    process.env.NODE_ENV === "development"
  ) {
    // console.log("loading styles");
    const p = new Promise<string>((resolve, reject) => {
      readFile(options.tailwindCss)
        .then((buf) => {
          const s = buf.toString();
          // rem to px
          const pxed = s.replace(
            /([\d.-]+rem)/gi,
            (_, value) => `${parseFloat(value.replace(/rem$/, "")) * basePx}px`
          );
          resolve(pxed);
        })
        .catch((reason) => reject(reason));
    });
    twcCache.set(options.tailwindCss, p);
  }

  const s = await twcCache.get(options.tailwindCss);
  if (typeof s === "undefined") {
    throw new Error(`Could not load tailwind css from ${options.tailwindCss}`);
  }

  return inlineStyles(
    email,
    options.reset === false ? s : [resetStyles, s].join("\n")
  );
};

export default mailwindCss;


Tailwind CSS for Email

```yaml
---
slug: javascript-threading
published: 2007-11-08T00:00:00-08:00
description: Not Everything Adheres to JavaScript's Semi-Single-Threaded Model
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
  - on: 2020-02-24
    note: While I couldn't find the test page, I'm happy to report that this bug no longer exists in Firefox and IE on the Mac is also no longer a concern for JS engineers.
---
```

There's a lot of digging required to figure out if JavaScript is single or multi-threaded. Thanks to the work Dan Simard in June, [a final answer on JavaScript threads was reached](https://web.archive.org/web/20071118102059/http://www.javascriptkata.com/2007/06/12/ajax-javascript-and-threads-the-final-truth/). The only major problem in this was that the comments by a user to Simard's post indicated that `alert()` caused Firefox's execution chain to change. The result was while the prompt was on screen, `setTimeout()` and other assorted callback functions were free to resolve.

The problem is made worse with several `setTimeout()` calls. As a single thread, JavaScript maintains some sort of event stack, where all of the callbacks and timeouts pile up, waiting for their turn. Once the event stack is out of events, the timers start again to count down to execution. If you fire one call with a `setTimeout()` and a timeout value of 2 seconds, and one more second of code execution follows, there will still be 2 seconds on the timer since it has not had a chance to run.

```js
var foo_count = 0;
var bar_count = 0;
var foo = function () {
  ++foo_count;
  window.setTimeout(bar, 5);
};
var bar = function () {
  ++bar_count;
  alert("foo=" + foo_count + ", bar=" + bar_count);
};

// triggers
window.setTimeout(foo, 10);
window.setTimeout(bar, 20);
// end triggers
```

In a perfectly timed environment (running just this code), `foo` will execute, followed by `bar`, followed by `foo`'s call to `bar`. In reality, the millisecond calibration for this is iffy. The output comes out as `foo=1`, `bar=2` then `foo=1`, `bar=1`. However, simply looking at the timing values, our alert calls should be reversed. We've entered the world of volatile variables and shared space without even knowing (and probably not even wanting). Under the hood, it appears that making a call to `alert()`, `prompt()`, `confirm()`, or any other window level call pauses the current thread's execution, letting any pending `setTimeout()` calls resolve. When the execution returns from the window event, variables that were scoped one block higher could have changed without the knowledge of the current execution block.

A more practical example of this can be found on the thread safe ~~JS Example Page~~. As of this writing, IE and Opera execute things properly in order, waiting for the prompt() to finish before continuing the current code block, and after completion, letting the pending `setTimeout()` event fire. In Firefox and Safari, during the `prompt()` call, the `setTimeout()` executes, overwriting the value of bar. [Ed-- unfortunately, the test page is currently MIA. If you find it, I'd love to relink it!]

## Protecting a Volatile Bar
As mentioned before, when the browser's JS Interpreter hands off to the `alert()`, it begins resolving any waiting `setTimeout()` calls that in in the event queue. In our example, another call to `bar()` is waiting which also increments `bar_count`. By the time we alert `bar_count`, something has gone and changed it. This seems to also hold true for `prompt()` and `confirm()` in Firefox and a few other browsers.

Imagine instead of just our primitive `window.setTimeout()` we were using an AJAX callback which waited for a DOM node to be available. The costs of this shared variable space being violated is a bit more costly. In many other languages, there are Mutexes for the synchronized calls, and the volatile declarative to avoid problems. Because the implementation of ECMAScript is unique to each browser, there needs to be a consistent way to secure data from tampering during the application's critical moments.

At our disposal...

- `new Object()` is atomic (can't be interrupted by browser events)
- `return (new Object() === new Object());` is always false as each new object is given a unique ID by the system. We need a way to atomically create an ID for a fake thread, and the Object's deep equality can do just that given it is atomic.
- `Array.push()` is atomic (can't be interrupted by browser events) as long as we are using the native implementation. Even if two objects push onto an array in a race condition, only one will hold the coveted index of `0`.
- `(function() { new Object(); })();` is garbage collected properly
- block scope level variables cannot be changed by outside factors

That doesn't leave us with much. [Ming made a post on JS Mutexes](https://web.archive.org/web/20071118102059/http://my2iu.blogspot.com/2006/10/javascript-mutexes-2.html) though that gave me an idea. The biggest concern from Ming's entries was that in Internet Explorer, events such as onload can interrupt a process, creating multiple events at the same time. To get around this, we would need a method which the browser cannot interrupt. This is where the native `Array.push()` comes in handy. For some reason, IE treats this call as non-interruptible, letting us have a queue process that ensures element `0` is the first lock requester. If we have two atomic commands, one to uniquely identify a lock request and another to enqueue the lock, then we have everything we need for a very basic spinlock implementation. Even if a second event interrupts our two statements, the pushing onto the array guarantees only one of the two requests will be given rights to the lock. We'll know which function got the lock thanks to our deep quality `===` of objects.

Spinlock design implies a "busy wait" cycle for getting the lock, meaning each individual thread usually sits in the equivalent of `while(1) {}`. Because we don't have threads and instead have the event queue, a while loop would seize the system. To get around this, we can use the same `setTimeout()` call that was the source of our problem to "sleep" an event until the lock resource is available. The result is a very lazy locking method that requires the application to care about the lock (but a lock that can be used in many different ways). Our pseudo code looks like:

```
sub process
    lock = get lock
    if not lock owner
        retry sub process in N ms (sleep)
        return

    lock was obtained
    perform critical code
    release lock

    non critical segment here
end process
```

Return to the ~~thread safe test page~~ and try the protected version. Across all browsers, the lock is held until the our asynchronous events properly completed.

## Beyond Locking Down Variables
A locking system like this can be extended to deal with more than just the JavaScript Variables. In the case of lazy loading JavaScript, it is possible to be using the same utility to load several "sets" of JavaScript at the same time. To avoid keeping the `document.head` open (and risking Operation Aborted problems), we use the same locking strategy to keep a DOM node from getting written to until Internet Explorer reports it as closed, such as an `onreadystate` for a script tags.

The locking utility can also be used to create "run once" functions such as an `init()` for a class outside of its constructor. The class can simply request the lock, and on completion, refuse to release it. While this takes up a small bit of memory in the lock utility, it also guarantees only one `init()` reaches the critical section for the life of the page.

## Limitations
Building such a locking system in JavaScript is not without drawbacks. The most notable of these is the lack of support for browsers which do not support `Array.push()` (hello, Internet Explorer on a Mac). If you have this esoteric corner case, I'm stumped; there's not much you can do.

It's also unknown just how atomic the methods are in non-browsers. While brief tests in Rhino imply that `Array.push()` is properly atomic, there's no guarantee that it is in any specification.

While I couldn't find the test page, I'm happy to report that this bug no longer exists in Firefox and IE on the Mac is also no longer a concern for JS engineers.

This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.

Not Everything Adheres to JavaScript's Semi-Single-Threaded Model

var foo_count = 0;
var bar_count = 0;
var foo = function () {
  ++foo_count;
  window.setTimeout(bar, 5);
};
var bar = function () {
  ++bar_count;
  alert("foo=" + foo_count + ", bar=" + bar_count);
};

// triggers
window.setTimeout(foo, 10);
window.setTimeout(bar, 20);
// end triggers


sub process
    lock = get lock
    if not lock owner
        retry sub process in N ms (sleep)
        return

    lock was obtained
    perform critical code
    release lock

    non critical segment here
end process


JavaScript Threading

```yaml
---
slug: just-in-time-javascript
published: 2007-11-27T00:00:00-08:00
description: Chained CSS and JavaScript loading
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

Web apps are heavy, and wait times suck. For every interaction you build, there's that much more code being added to the project. Eventually, it's going to be too much for the user to handle, especially if they are on dialup or slow DSL (though I suppose even an iPhone on EDGE would qualify). For example, the Cash Shop we just launched at Gaia weighed in at over 400k (~100k gzip compressed and minified). While we're a graphic heavy site, waiting for an additional 100k was needlessly painful. To boot, _there was no promise the user was even going to use that feature_, making loading all that JavaScript and CSS a really silly exercise. We needed a way to load the JS and CSS on the fly across all browsers.

Getting the JIT Loader

- [Get the most recent JIT Loader](https://gist.github.com/Jakobo/7a5aec5fcebc8f4886193b114c9ec4f0) (23k)
- [Get the most recent JIT Loader - min + packed](https://gist.github.com/Jakobo/7a5aec5fcebc8f4886193b114c9ec4f0) (5.6k)

The locking utility is also included, but if Lock exists, it won't be used. Enough thanks can't go to Ryan Grove for the [original LazyLoad](https://web.archive.org/web/20071215020306/http://wonko.com/article/527) utility. The JIT loader, like LazyLoad is released under the New BSD License.

## Putting off Loading the CSS and JavaScript
The method of loading we are specifically looking at is known as "event based loading" or "lazy loading". While the [wikipedia article on lazy loading](https://web.archive.org/web/20071215020306/http://en.wikipedia.org/wiki/Lazy_loading) is not very detailed, the summary of the article is that lazy loading allows us to wait on loading stuff until we need it. In computer science, usually the discussion revolves around expensive objects or data calls. In our case, it's all about the browser load time. There's little reason to put JavaScript or CSS into the head of a document unless we know it is 100% needed for the page. We want to put off the expensive http connection and download as long as possible.

A very practical example (and one already out there) is to defer the loading of images until they are within the viewport. Both the [jQuery Lazy Load Plugin](https://web.archive.org/web/20071215020306/http://www.appelsiini.net/projects/lazyload) and the [YUI Image Loader](https://web.archive.org/web/20071215020306/http://developer.yahoo.com/yui/imageloader/) do exactly this, reducing load times on pages by holding out on pulling down images until you need them. For these examples, scrolling the page (and moving a placeholder into the viewport) is an event that triggers the load. If this has proven successful for images and content, there's no reason this can't be applied to scripts and CSS as well.

## Loading JavaScript In Existing Frameworks
To a certain extent, Dojo and YUI have both built in a loading system for including packages before executing script. They are the [`dojo.require()` directive](https://web.archive.org/web/20071215020306/http://dojotoolkit.org/book/dojo-book-0-9/part-3-programmatic-dijit-and-dojo/functions-used-everywhere/dojo-require) and the [YUI Loader Utility](https://web.archive.org/web/20071215020306/http://developer.yahoo.com/yui/yuiloader/) respectively. These two were specifically called out because their methods of including requested files are so different.

In the case of Dojo, an XMLHttpRequest (XHR) is made to load the JavaScript package, and then is ran through `eval()` to convert the request into functional code. This lets Dojo use a package style syntax similar to Java for including libraries to run. Each call to `require()` is synchronous and blocks, meaning you can trust a directive to fully complete before getting into your code. This method is highly effective for lazily loading a package since Dojo is clever enough to not include something twice. The crutch though is the XMLHttpRequest, which is subject to any cross site scripting issues. (Note: AOL has managed to do a custom Dojo build with XHR support across domains and the process is pretty well documented, but it is not the default behavior.)

On the other end of the spectrum, the folks at Yahoo! have taken a different approach, writing to the DOM directly using the `<script>` tag. This eliminates the cross browser issues that Dojo grapples with, but trades it for the limitations of inline script writing exposing the DOM to Internet Explorer in a state when it's not "complete" in IE's mind, resulting in the dreaded Operation Aborted error. In order to use the loader, there's also a lot that needs to be done if custom modules are going to be used. (As of this writing, the YUI Loader constructor does not take the config object, so it's hard to dynamically add to the object without using `YAHOO.lang.augment()`.)

Ryan Grove built a library independent utility for including scripts, similar to YUI, called Lazy Load. It was a good strong start, and needed a steroid boost to provide the CSS support and streamlined DOM writing. Because the API was radically changed, the name was changed as well.

## Just In Time Loader (JIT Loader) Basics
In most situations, the behavior we are looking for is "on event X, load this, then load this, then load this, then execute Function X". To provide access to this streamlined interface, `JIT.startChain()` was created. Calling `startChain()` returns a method-chaining object that you can use to build up a series of JavaScript and CSS includes. The following methods are available on the object returned from the `startChain()` call.

- `addCss(urls, verifier, ie_version)`: adds a CSS File (or array of CSS files) to the execution stack. It will continue when `verifier` returns true. By default, all verifiers simply make sure the nodes have been written to the DOM, not that they have been processed internally. In the case of CSS, you can specify a specific IE version you want to apply this CSS to in order to keep your CSS files clean.
- `load(urls, verifier)`: adds a JavaScript file to the execution stack
- `loadOnce(urls, verifier)`: adds a JavaScript file to the execution stack. When fired, if the URL has already been added by another JIT load or an external source, it won't be loaded again.
- `onComplete(fn, obj, scope)`: Starts the execution chain. When the execution chain has completed, `fn` will be ran. If `obj` is suppled, it will be passed as an argument. If `scope` is `true`, `fn` will instead be directly ran in the context of `obj`.

The most primitive example of chaining would then look something like:

```js
JIT.startChain()
  .loadOnce(jsfile, function () {
    /* verifier */
  })
  .addCSS(cssfile)
  .onComplete(function () {
    // run this when everything is loaded
  });
```

If chaining is not your thing, you can also make direct calls to the JIT object (see examples at the end). After the verifier, each of the above calls takes a callback function, object, and scope; the `onComplete()` doesn't exist in the root JIT object and is used solely for the purposes of chaining. These are left available in case more advanced functionality is required.

## Optimizations
Because JavaScript is (mostly) single threaded, if there are multiple calls to the Lazy Loader, we shouldn't wait on the current code execution block to write to the DOM and clean up when it is finished. The original Lazy Load used a queue system that let multiple calls stack as pending, even if they were for different load requests. The smallest synchronous operation is the DOM write, which can be pushed out to a method and can be locked using a [spinlock](./javascript-threading) to emulate fake threads. Any events that get queued up between DOM writes can be added to the stack, and can then execute while slow scripts take a while. This speedup is surprisingly most noticeable on Internet Explorer, where events are allowed to interrupt the current JavaScript thread, to write more concurrent nodes into the DOM.

## Limitations
The verifier function that is passed in is the linchpin of the event based loading. When the verifier resolves to `true`, the loading process continues with the assigned callback. When working with CSS, this is exceptionally difficult. There are two options when dealing with event loading the CSS files, either find a testable property in the CSS, or pass in `null` for the verifier slot, and load the CSS first. While the first offers more reliability, the second tends to be more practical, since the CSS won't usually apply to anything other than nodes created by the JavaScript. A simple example of a CSS verifier would be (assuming your CSS sets the body's background image to the below mentioned URL:

```js
var verifier = function () {
  return (document &&
  document.body &&
  document.body.backgroundImage = "http://example.com/load_complete.gif")
    ? true
    : false;
};
```

The second major limitation of the system is in `loadOnce()` which requires script nodes to exist in the DOM to test if they have been properly loaded. This testing method makes it incompatible with the `dojo.require()` directive which uses the XHR to perform script includes. In the future, the verifier check might be ran once to preemptively test for component loading, but that will cause issues with testing in the `YAHOO` namespace.

## Enough Already, Examples Please!
You can see JIT in use on the website [Gaia Online for the Cash Shop](https://web.archive.org/web/20071215020306/http://www.gaiaonline.com) (under the market submenu) and eventually the same technique will be in place for the world map and other header-based events.

JIT.startChain()
  .loadOnce(jsfile, function () {
    /* verifier */
  })
  .addCSS(cssfile)
  .onComplete(function () {
    // run this when everything is loaded
  });


var verifier = function () {
  return (document &&
  document.body &&
  document.body.backgroundImage = "http://example.com/load_complete.gif")
    ? true
    : false;
};


Just In Time JavaScript

```yaml
---
slug: stylizing-form-submits
published: 2006-10-28T00:00:00-08:00
description: Camino and Safari & styling type=submit
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

"The buttons aren't styling" I remarked as I stared at the page in Camino and Safari. Testing on the Mac platform has been the absolute bane of my existence as of late, mostly because for some reason, these browsers in particular are very protective of their form widgets. Coming back to [Cameron Adams' Entry on Styling Form Widgets](https://web.archive.org/web/20061218112920/http://themaninblue.com/writing/perspective/2004/04/28/), I found that none of the Macromedia examples were actually working for Camino/Safari, although they looked beautiful in Firefox. The submit button simply would not take the background settings. Interesting enough though, something of `input type="button"` styled perfectly.

However, the value attribute of the button wasn't getting passed in. For the legacy code around Gaia, we have forms with more than one possible "submit" for an action. The most common case of this is preview and submit buttons we traditionally use in the forums. This left us with two scenarios:

```html
<form id="myForm" action="some.php" method="POST">
  <input type="text" name="foo" value="" />
  <input id="submitBar" type="submit" name="action" value="bar" />
  <input id="submitBaz" type="submit" name="action" value="baz" />
</form>
```

or Button tags that wouldn't pass in their value to the PHP script (and shouldn't technically perform a submit either)

```html
<form id="myForm" action="some.php" method="POST">
  <input type="text" name="foo" value="" />
  <input id="submitBar" type="button" name="action" value="bar" />
  <input id="submitBaz" type="button" name="action" value="baz" />
</form>
```

The final solution ended up being something right down the middle and using JavaScript to make up for Safari / Camino's shortcomings. Starting with a default submit button, we can replace it with a input `type="button"` node, and add a bit of JavaScript to the `onClick` to make up for the stylized button's shortcomings. The first block of JavaScript goes into the head, and the second block can either go into an `onLoad` handler or at the end of the form tag, depending on how soon you need the replacement.

```js
////////
// SwapSubmit - A Tool for Stylizing Submit Buttons on All Browsers
// Licensed under CC-GPL-2.0
// http://creativecommons.org/licenses/GPL/2.0/
////////
var RJH_SwapSubmit = {
  replacedEles: new Object(),
  replace: function (formid, eleid) {
    if (typeof eleid == "string") var ele = document.getElementById(eleid);
    else var ele = eleid;

    if (typeof formid == "string") var f = document.getElementById(formid);
    else var f = formid;

    if (ele) {
      var o = this.build(formid, ele);
      var name = ele.getAttribute("name");
      var value = ele.getAttribute("value");

      var pn = ele.parentNode;
      pn.removeChild(ele);
      pn.appendChild(o);

      if (!document.getElementById(name))
        f.appendChild(this.buildInputField(formid, name));

      this.replacedEles[eleid] = new Object();
      this.replacedEles[eleid]["name"] = name;
      this.replacedEles[eleid]["value"] = value;
      this.replacedEles[eleid]["form"] = formid;
    }
  },
  build: function (formid, ele) {
    var o = document.createElement("button");
    var f = document.getElementById(formid);

    var oldOnclick = ele.onclick;
    o.id = ele.id;
    o.className = ele.className;
    o.onclick = function () {
      if (oldOnclick) {
        if (oldOnclick() == false) return false;
      }
      RJH_SwapSubmit.submitForm(this);
    };

    return o;
  },
  buildInputField: function (formid, name) {
    var o = document.createElement("input");

    o.setAttribute("type", "hidden");
    o.id = name;
    o.setAttribute("name", name);

    return o;
  },

  // ORIGIN: onClick of a button
  submitForm: function (ele) {
    var clickId = ele.id;
    var name = RJH_SwapSubmit.replacedEles[clickId]["name"];
    var value = RJH_SwapSubmit.replacedEles[clickId]["value"];
    var formid = RJH_SwapSubmit.replacedEles[clickId]["form"];
    document.getElementById(name).value = value;
    document.getElementById(formid).submit();
  },
};
```

```js
RJH_SwapSubmit.replace("FORMID", "SUBMITBBUTTONID");
```

Replace `FORMID` and `SUBMITBUTTONID` with the relevant values.

## Drawbacks
The largest drawback hands down is the addition of JavaScript. It's not something to depend on, and many steps were taken to ensure that the enhancement is progressive in nature.

Styled images will have to be styled to reflect the change from an input to a button node, and can be referenced via `button#idNameofElement` to apply all the necessary stylization.

////////
// SwapSubmit - A Tool for Stylizing Submit Buttons on All Browsers
// Licensed under CC-GPL-2.0
// http://creativecommons.org/licenses/GPL/2.0/
////////
var RJH_SwapSubmit = {
  replacedEles: new Object(),
  replace: function (formid, eleid) {
    if (typeof eleid == "string") var ele = document.getElementById(eleid);
    else var ele = eleid;

    if (typeof formid == "string") var f = document.getElementById(formid);
    else var f = formid;

    if (ele) {
      var o = this.build(formid, ele);
      var name = ele.getAttribute("name");
      var value = ele.getAttribute("value");

      var pn = ele.parentNode;
      pn.removeChild(ele);
      pn.appendChild(o);

      if (!document.getElementById(name))
        f.appendChild(this.buildInputField(formid, name));

      this.replacedEles[eleid] = new Object();
      this.replacedEles[eleid]["name"] = name;
      this.replacedEles[eleid]["value"] = value;
      this.replacedEles[eleid]["form"] = formid;
    }
  },
  build: function (formid, ele) {
    var o = document.createElement("button");
    var f = document.getElementById(formid);

    var oldOnclick = ele.onclick;
    o.id = ele.id;
    o.className = ele.className;
    o.onclick = function () {
      if (oldOnclick) {
        if (oldOnclick() == false) return false;
      }
      RJH_SwapSubmit.submitForm(this);
    };

    return o;
  },
  buildInputField: function (formid, name) {
    var o = document.createElement("input");

    o.setAttribute("type", "hidden");
    o.id = name;
    o.setAttribute("name", name);

    return o;
  },

  // ORIGIN: onClick of a button
  submitForm: function (ele) {
    var clickId = ele.id;
    var name = RJH_SwapSubmit.replacedEles[clickId]["name"];
    var value = RJH_SwapSubmit.replacedEles[clickId]["value"];
    var formid = RJH_SwapSubmit.replacedEles[clickId]["form"];
    document.getElementById(name).value = value;
    document.getElementById(formid).submit();
  },
};


RJH_SwapSubmit.replace("FORMID", "SUBMITBBUTTONID");


Stylizing Form Submits

```yaml
---
slug: sslac
published: 2011-05-03T00:00:00.000Z
description: A JavaScript class library that lets you runtime patch your methods
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
  - on: 2020-02-24
    note: You have ES6 Classes. You should certainly be using those now! `Sslac` is also long since retired, though it was in use at LinkedIn for several years because of the need to test fixes and patches for CDN-delivered code on third party sites via the browser console. Ultimately, this was a lot safer than giving the framework a "switch" flag that could retrieve runtime JS from an arbitrary URL.
---
```

The world of JavaScript is rich with ways to bring typical OOP constructs to a highly prototyped language. The world probably doesn't need another library either. Further, it probably doesn't need an entire blog post talking about its features and how it can be used. Nevertheless, the hat is being tossed into the ring. Welcome Sslac, a (somewhat) backward approach to class instantiation in JavaScript.

If you're not keen on the intro documentation, you can [download Sslac from github](https://github.com/jakobo/sslac), view the source, etc. The Short List (features)

- Natural chaining syntax to define an object
- Compatible with `instanceof` operators
- Support for superclass methods
- Change definitions of objects after creation
- Support for namespacing and `noConflict`
- Common JS 1.1 Modules compliant
- Multiple class types (static, instance, and functions)

## A Dual Object Structure

The most important thing to remember in Sslac is that when working from the Sslac chain, you're working on what's internally called the "ObjectRef". This reference isn't the object your code will instantiate, but rather a souped up dictionary with some helpful setters and getters. This syntax allows you to get a method that you've already defined somewhere along the extension chain, and then swap it for something new or patch new code over the old. We'll actually get to that in a bit, but first, the class basics.

For people who have worked with JS class libraries, the syntax should feel familiar. With lowercase versions of the words reserved (static and extends come to mind), Uppercase was used instead. An unexpected benefit of this seems to be that code written is a bit easier to read. For those who have played with Prototype or [Resig's Simple JS Inheritance](https://web.archive.org/web/20110507092802/http://ejohn.org/blog/simple-javascript-inheritance/), the syntax shouldn't feel too unwieldy either.

## Runtime Mixins and Monkeypatching

I hear it's also called "duck punching," which sounds way more cool. One thing Sslac really excels at is the ability to alter code at runtime without modifying the original source code. Much like Prototype's addMethod functionality, these runtime methods cascade into inherited objects. Unlike the other frameworks, however, Sslac provides a set of helper methods to get at the original definitions. To change a method's definition at runtime, you can retrieve the original object's definition, and then swap out a method.

    (this code sample went missing in the many migrations)

In the above, we've enabled the Person object to flip out, and enabled the Ninja object to kill people. Thankfully, only Ninjas (which extend Persons) will be able to [flip out and kill people](https://web.archive.org/web/20110507092802/http://www.realultimatepower.net/index4.htm), but that's the purpose of ninjas anyway. Prototype inheritance means that, by adding the `flipOut` method to Person, Ninja will automatically get it. The Person object's probably feeling left out though. And if it's someone else's Person object, you may not want to re-implement their method entirely. This is where that whole "duck punching" concept comes in.

Using `definitionOf` and `getMethod`, we can retrieve the original implemented method and call it using the old school `apply` method, passing the current object along with the arguments array.

## In the Real World

Perhaps the most compelling real-world use case for Sslac comes from development at LinkedIn. With our current framework deployed on high profile sites, we can take a bug we want to fix, write the patch, and then use a tool like Greasemonkey to add our own custom code on top. Bugs can be verified, partner implementations can be tested to ensure there are no regressions, all without either us or the end user developers having to change production code. This provides an invaluable mechanism, allowing code changes to be verified out in the wild, on live sites, without impacting any end user experience. If nothing else, the monkeypatching alone has made the 2k library (minified, pre gzip) well worth its cost.

[Sslac on Github](https://github.com/jakobo/sslac)


You have ES6 Classes. You should certainly be using those now! `Sslac` is also long since retired, though it was in use at LinkedIn for several years because of the need to test fixes and patches for CDN-delivered code on third party sites via the browser console. Ultimately, this was a lot safer than giving the framework a "switch" flag that could retrieve runtime JS from an arbitrary URL.

A JavaScript class library that lets you runtime patch your methods

Sslac: A Runtime Patchable Class Library

```yaml
---
slug: gulp-and-browserify
published: 2014-07-14T00:00:00.000Z
description: How to use Vinyl after gulp-browserify was blacklisted
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

If you've tried [gulp](http://gulpjs.com/), you've probably also tried [browserify](http://browserify.org/). This also means you googled for "gulp browserify" and were led to the `gulp-browserify` plugin on npm. I haven't linked to it because the gulp team has ruled that the `gulp-browserify` plugin is blacklisted due to redundancy. Instead, the current consensus is a [recipe leveraging vinyl](https://github.com/gulpjs/gulp/issues/369), the underlying virtual file system in gulp. While I think that's technically correct, it requires intimate knowledge of browserify, streams, and the vinyl system.

## The Vinyl Code

Let's start with the code and work backwards. First up, the (simplified) recommended solution.

```js
var gulp = require("gulp");
var browserify = require("browserify");
var toVinyl = require("vinyl-source-stream");
gulp.task("js", function () {
  return browserify("file.js")
    .bundle()
    .pipe(toVinyl("bundle.js"))
    .pipe(gulp.dest("output_dir/"));
});
```

This is a very powerful pattern. We're able to leverage the default browserify npm module. [vinyl-source-stream](https://www.npmjs.org/package/vinyl-source-stream) (npm) can take a stream in progress and convert it to a vinyl supported stream, thus giving it a virtual file system and name. By using this, you no longer have to use a special plugin for browserify. However, this solution breaks down if you want to leverage the globbing in gulp.src that makes for powerful pipelines, do additional transformations prior to browserify, or simply work with a npm module that doesn't support streams or buffers. Like all things gulp, there's a plugin for this functionality; it lets us tap into a gulp pipeline, making our own modifications. That plugin is appropriately named [gulp-tap](https://www.npmjs.org/package/gulp-tap). We're going to use `gulp-tap` to get all the globbing power of gulp, but still be able to run browserify on our entries.

## What it Looks Like With gulp-tap

```js
var gulp = require("gulp");
var tap = require("gulp-tap");
var toBuffer = require("gulp-buffer");
var browserify = require("browserify");
gulp.task("js", function () {
  return gulp
    .src("**/*.js")
    .pipe(
      tap(function (file) {
        var bundler = browserify({
          entries: [file.path],
        });
        return bundler.bundle();
      })
    )
    .pipe(toBuffer())
    .pipe("...")
    .pipe(gulp.dest("output_dir/"));
});
```

Okay, we've added a few more lines courtesy of the gulp-tap plugin. However, this is a pattern that goes well beyond browserify. gulp-tap is a swiss army knife in the gulp world. It's purpose is to expose the file in the middle of the pipeline, allowing you to call whatever custom transformations you may need. The signature for the gulp-tap configuration takes two parameters. The first is the `vinyl-fs` file object and contains `file.contents`, `file.path`, etc. The second is an instance of the `through2` module in case you need to use the stream directly.

Return a buffer, return a stream, or modify `file.contents` and you're done. Even operations that don't normally return streams or buffers are automatically moved into a buffer for compatibility with the next step on the gulp pipeline.
As a caveat, it should be noted that since you are leaving the stream/buffer world during your gulp-tap operation, it will be slower than if you had a pure stream based solution. However, the leverage you gain for this strategy is high. Every npm module can be part of your gulp system now.

## gulp-buffer and gulp-stream

Not all gulp plugins are stream or buffer ready. Because of their design, they might be operating on one or the other. This is most common with plugins that are calling out to external commands or require the evaluation of the entire file in order to perform a task. gulp allows these utilities to decline handling streams by throwing an exception. Enter [gulp-buffer](https://www.npmjs.org/package/gulp-buffer) and [gulp-stream](https://www.npmjs.org/package/gulp-stream), taking in either buffers or streams and returning a buffer or stream for the next step of the pipeline.

In our above code, browserify provides a stream, but uglify only operates on a buffer. Piping through gulp-buffer solves this problem.

## Doing it Gulp's Way

The most successful gulp pipelines are those built with small modular components. Per the gulp team's recommendation, plugins shouldn't be created when there is already a npm module that accomplishes your goal. Thanks to utilities like vinyl-source-stream, gulp-tap, gulp-buffer, and gulp-stream, you can make the entire npm ecosystem gulp friendly. You really don't need to write a gulp plugin for most use cases, and that's serious leverage.


How to use Vinyl after gulp-browserify was blacklisted

var gulp = require("gulp");
var browserify = require("browserify");
var toVinyl = require("vinyl-source-stream");
gulp.task("js", function () {
  return browserify("file.js")
    .bundle()
    .pipe(toVinyl("bundle.js"))
    .pipe(gulp.dest("output_dir/"));
});


Gulp and Browserify

```yaml
---
slug: line-numbers-in-eval
published: 2015-03-16T00:00:00.000Z
description: You should never do this. But "never" is a bit too absolute for engineering
changelog:
  - on: 2017-10-01
    note: Better alternatives than `eval` finally exist with `await import()` syntax. You should definitely explore those. Additionally, LinkedIn has sunset [Inject](https://github.com/linkedin/inject) on their production site now that many viable alternatives exist. Hoo-ray modern web development!
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

When it comes to executing code, `eval()` is a [terrible idea](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). However, somewhere in your coding career, you will need to evaluate code.

And unfortunately, if there's an error in the code, any line numbers are going to point to the invocation of `eval()` and not the erroring line within the body itself. Lucky for us, `<script>` tags correctly report erroring lines with line numbers.

Before we go any further, this is an obligatory **don't use eval**. It should be an option of last resort. Your Content Security Policy is hopefully already preventing you from doing this.

## Trying to not Evaluate: `.innerHTML` or `.text`

The first attempt was to set `innerHTML` to your JavaScript, and then place that node onto the page via `appendChild`. If you are only concerned with modern non-Microsoft browsers, you'd be done at this point.

```js
// ⚠️ Obligatory THIS IS EVAL DO NOT DO THIS
function createScriptNode(code) {
  var scr = document.createElement("script");
  scr.type = "text/javascript";
  scr.innerHTML = code;
  return scr;
}
```

Internet Explorer won't execute the JavaScript inside of this script tag, even though the `innerHTML` property is set. However, it uniquely [supports the "text" property](http://msdn.microsoft.com/en-us/library/ie/ms535892(v=vs.85).aspx), which no other browsers seem to support. When set, scripts in IE will execute once appended to the DOM. A few changes to our above script, and we have a "safe" method. Borrowing from the idea of [feature testing for things only IE supports](./enhancing-for-bugs), we'll actually feature test against this text property, falling back to alternate versions as needed.

```js
// ⚠️ Obligatory THIS IS EVAL DO NOT DO THIS
function createScriptNode(code) {
  var scr = document.createElement("script");
  scr.type = "text/javascript";
  try {
    scr.text = code;
  } catch (e) {
    try {
      scr.innerHTML = code;
    } catch (ee) {
      return false;
    }
  }
  return scr;
}

```

## Tying it Together

Further optimizations can be used to pre-select the best insertion method. In [inject](https://github.com/linkedin/inject/blob/68c343180ed3a08dffb0ad445fe45d70908683e1/src/executor.js#L129), we wrap the code we want to execute within a function declaration and assignment. This enables us to store the results of the `eval` so that modules can then be executed on demand. The below example is just a simple JSON evaluator as a proof of concept. Like all things `eval`, you should always be cautious with invoking it on items that are not 100% in your control.

```js
// ⚠️ Obligatory THIS IS EVAL DO NOT DO THIS
var createScriptNode = (function () {
  var testScr = document.createElement("script"),
    property = "innerHTML";
  testScr.type = "text/javascript";
  try {
    testScr.text = ";";
    property = "text";
  } catch (e) {}
  return function (code) {
    var scr = document.createElement("script");
    scr.type = "text/javascript";
    scr[property] = code;
    return scr;
  };
})();

var evalJSON = function (jsonString) {
  var exec = ["window.results =", jsonString],
    node = createScriptNode(exec),
    results;
  document.body.appendChild(node);
  results = window.results;
  delete window["results"];
  return results;
};
```

While this code definitely makes it possible to do more harm than good (we're stepping around JSLint/Hint `eval` checks), the upside is huge when you're evaluating code and need to understand at what line something is failing on. In the case of a module loading system, having both the upsides of a lazy `eval` and the  embedded script tag is a huge win.


Better alternatives than `eval` finally exist with `await import()` syntax. You should definitely explore those. Additionally, LinkedIn has sunset [Inject](https://github.com/linkedin/inject) on their production site now that many viable alternatives exist. Hoo-ray modern web development!

You should never do this. But "never" is a bit too absolute for engineering

// ⚠️ Obligatory THIS IS EVAL DO NOT DO THIS
function createScriptNode(code) {
  var scr = document.createElement("script");
  scr.type = "text/javascript";
  scr.innerHTML = code;
  return scr;
}


// ⚠️ Obligatory THIS IS EVAL DO NOT DO THIS
function createScriptNode(code) {
  var scr = document.createElement("script");
  scr.type = "text/javascript";
  try {
    scr.text = code;
  } catch (e) {
    try {
      scr.innerHTML = code;
    } catch (ee) {
      return false;
    }
  }
  return scr;
}



// ⚠️ Obligatory THIS IS EVAL DO NOT DO THIS
var createScriptNode = (function () {
  var testScr = document.createElement("script"),
    property = "innerHTML";
  testScr.type = "text/javascript";
  try {
    testScr.text = ";";
    property = "text";
  } catch (e) {}
  return function (code) {
    var scr = document.createElement("script");
    scr.type = "text/javascript";
    scr[property] = code;
    return scr;
  };
})();

var evalJSON = function (jsonString) {
  var exec = ["window.results =", jsonString],
    node = createScriptNode(exec),
    results;
  document.body.appendChild(node);
  results = window.results;
  delete window["results"];
  return results;
};


Line Numbers in eval

```yaml
---
slug: ajax-prototype-scope
published: 2006-04-13T08:00:00.000Z
description: Avoiding AJAX Scope Issues in Prototype.js
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

I haven't seen this covered much, but I really felt it was worth a mention. A lot of people have worked with the [prototype library](https://web.archive.org/web/20060426013445/http://prototype.conio.net/), including myself. One of the most challenging things I've had to do was create an object that could make an AJAX request, and then internalize the response. Calling a function out on the global scope is messy and in poor taste if you can avoid it. I thought back to my Java classes, and remember an almost reflexive style of programming. About an hour later (including reading through prototype's source) I had a working model. The major players in this design are the `XMLHttpCatchobject` and the `Ajax.Request` object. Our goal is to call a sending function inside of an instance of `myObj`, and then have the response be ran in the context of `myObj`. By default, you cannot refer to `this` inside of the callback, because of scope issues. The solution is to encapsulate the request, and then have a way for the response to find its way back home. We do this by passing the scope down into the `XMLHttpCatch object`. Hopefully other people will find this useful, as occasionally it is not practical to have globally scoped functions for `onComplete`, and you want access to all the proper `this.methodName()` calls. I thought about moving the catch object into `myObj` as a function definition during initialize, but the current model is a bit more reusable.

```js
Abstract.XMLHttpCatch = Class.create();
Abstract.XMLHttpCatch.prototype = {
  initialize: function (opts) {},
  receive: function (response, scope) {
    scope.receive(response);
  },
};

Abstract.myObj = Class.create();
Abstract.myObj.prototype = {
  initialize: function (opts) {
    for (var prop in opts) {
      this[prop] = opts[prop];
    }
    this.XMLHttpCatch = new Abstract.XMLHttpCatch();
  },

  receive: function (response) {
    this.response = response.responseText;
    alert("Response Text: " + this.response);
  },

  send: function () {
    // get a local name for our catch object
    XMLHttpCatch = this.XMLHttpCatch;

    // get a local name for "this" (what we want to run the response under)
    scope = this;

    // prototype does the rest
    ajax = new Ajax.Request(
      "http://www.myurl.com/path/to/my.php", // URL
      {
        // options
        method: "get",
        onComplete: function (resp) {
          XMLHttpCatch.receive(resp, scope);
        },
      }
    );
  },
};

example = new Abstract.myObj();
example.send();
```

Avoiding AJAX Scope Issues in Prototype.js

Abstract.XMLHttpCatch = Class.create();
Abstract.XMLHttpCatch.prototype = {
  initialize: function (opts) {},
  receive: function (response, scope) {
    scope.receive(response);
  },
};

Abstract.myObj = Class.create();
Abstract.myObj.prototype = {
  initialize: function (opts) {
    for (var prop in opts) {
      this[prop] = opts[prop];
    }
    this.XMLHttpCatch = new Abstract.XMLHttpCatch();
  },

  receive: function (response) {
    this.response = response.responseText;
    alert("Response Text: " + this.response);
  },

  send: function () {
    // get a local name for our catch object
    XMLHttpCatch = this.XMLHttpCatch;

    // get a local name for "this" (what we want to run the response under)
    scope = this;

    // prototype does the rest
    ajax = new Ajax.Request(
      "http://www.myurl.com/path/to/my.php", // URL
      {
        // options
        method: "get",
        onComplete: function (resp) {
          XMLHttpCatch.receive(resp, scope);
        },
      }
    );
  },
};

example = new Abstract.myObj();
example.send();


AJAX Scope in Prototype.JS

```yaml
---
slug: enhancing-for-bugs
published: 2015-03-14T00:00:00.000Z
description: Sometimes, instead of feature detection, you can get away with "bug detection"
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

In the days of Internet Explorer 6, it was common to lament the problems of the browser nobody wanted to support. Some of the bugs that developers have uncovered are well documented, some of them not. This falls more into the later camp. It's fix, while trivial, serves as a great reminder about how to build software that works in every browser.

Let's get the basics out of the way first. In every browser on the planet (except IE6), it is possible to create a checkbox in IE6 that is by default selected using everyday JavaScript.

```js
var cb = document.createElement("input");
cb.type = "checkbox";
cb.checked = true;
```

A simple checkbox
The above code would render the checkbox once you append the checkbox to the DOM, but no matter how one tries, the box won't actually start in the checked state. While it's technically possible to [sniff IE6 using conditional comments](http://dean.edwards.name/weblog/2006/11/sandbox/) and react accordingly, trying to detect a browser based on its signature will always be a poor choice and a last resort.

Internet Explorer's documentation on `document.createElement` shows that before IE9, it was possible to render an element using the angle brackets, `<` and `>` respectively. When rendering out an entire tag with angle brackets, IE6 properly sets the "checked" property. Since standards compliant browsers don't allow angle brackets, we can start with a non-standard solution, falling back to the W3C method on failure.

```js
// IE6 requires a checkbox to be made differently
try {
  var cb = document.createElement('<input type="checkbox" checked>');
} catch (e) {
  var cb = document.createElement("input");
  cb.type = "checkbox";
  cb.checked = true;
}
```

By applying the philosophy of feature detection to something that is (by all accounts) a bug, we can keep true to our development principals in the browser.


Sometimes, instead of feature detection, you can get away with "bug detection"

var cb = document.createElement("input");
cb.type = "checkbox";
cb.checked = true;


// IE6 requires a checkbox to be made differently
try {
  var cb = document.createElement('<input type="checkbox" checked>');
} catch (e) {
  var cb = document.createElement("input");
  cb.type = "checkbox";
  cb.checked = true;
}


Enhancing for Bugs

```yaml
---
slug: fake-germanizer
published: 2008-11-13T00:00:00.000Z
description: Long words can make short work of your design
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

I ran into a problem where I needed to guess how something would look in German, without knowing a single drop of German. So, I pulled up Mozilla's XPath documents and made a small bookmarklet. It's far from perfect, but it definitely has its uses when you're trying to estimate how items will look before they reach a translation team... even if the first use was messing with my Twitter feed.

[Fauxgermanhausen das Pagen! (bookmarklet)](javascript:%28function%28%29%7Bvar%20prefixes%3D%5B%27%27%2C%27glocken%27%2C%27das%27%2C%27borfa%27%2C%27maushe%27%2C%27uber%27%5D%2Csuffixes%3D%5B%27%27%2C%27hausen%27%2C%27%20die%20vander%27%2C%27gleuten%27%2C%27noshan%27%2C%27flagellan%27%2C%27mek%27%2C%27dak%27%2C%27en%20das%27%2C%27ga%27%5D%2CxPathResult%3Ddocument.evaluate%28%27.//text%28%29%5Bnormalize-space%28.%29%21%3D%27%27%5D%27%2Cdocument.body%2Cnull%2CXPathResult.ORDERED_NODE_SNAPSHOT_TYPE%2Cnull%29%2Ci%2CtextNode%2Ccnt%2Cout%2Cj%2Cpfx%2Csfx%3Bfor%28i%3D0%2Cl%3DxPathResult.snapshotLength%3Bi%3Cl%3Bi++%29%7BtextNode%3DxPathResult.snapshotItem%28i%29%3Bif%28textNode.parentNode.nodeName.toLowerCase%28%29%3D%3D%27script%27%7C%7CtextNode.tagName%3D%3D%27style%27%29continue%3Bcnt%3DtextNode.data.split%28/s/g%29%3Bout%3D%5B%5D%3Bfor%28j%3D0%3Bj%3Ccnt.length%3Bj++%29%7Bif%28cnt%5Bj%5D.replace%28/%5Bs%5D/g%2C%27%27%29%3D%3D%27%27%29continue%3Bpfx%3D%28%21Math.floor%28Math.random%28%29*10%29%29%3F%27%27%3Aprefixes%5BMath.floor%28Math.random%28%29*prefixes.length%29%5D%3Bsfx%3D%28%21Math.floor%28Math.random%28%29*10%29%29%3F%27%27%3Asuffixes%5BMath.floor%28Math.random%28%29*suffixes.length%29%5D%3Bout.push%28pfx+cnt%5Bj%5D+sfx%29%3B%7DtextNode.data%3D%27%20%27+out.join%28%27%20%27%29+%27%20%27%3B%7D%7D%29%28%29%3B)

```js
    (function () {
      var prefixes = ["", "glocken", "das", "borfa", "maushe", "uber"],
        suffixes = [
          "",
          "hausen",
          " die vander",
          "gleuten",
          "noshan",
          "flagellan",
          "mek",
          "dak",
          "en das",
          "ga",
        ],
        xPathResult = document.evaluate(
          ".//text()[normalize-space(.)!='']",
          document.body,
          null,
          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
          null
        ),
        i,
        textNode,
        cnt,
        out,
        j,
        pfx,
        sfx;
      for (i = 0, l = xPathResult.snapshotLength; i < l; i++) {
        textNode = xPathResult.snapshotItem(i);
        if (
          textNode.parentNode.nodeName.toLowerCase() == "script" ||
          textNode.tagName == "style"
        )
          continue;
        cnt = textNode.data.split(/\s/g);
        out = [];
        for (j = 0; j < cnt.length; j++) {
          if (cnt[j].replace(/[\s]/g, "") == "") continue;
          pfx = !Math.floor(Math.random() * 10)
            ? ""
            : prefixes[Math.floor(Math.random() * prefixes.length)];
          sfx = !Math.floor(Math.random() * 10)
            ? ""
            : suffixes[Math.floor(Math.random() * suffixes.length)];
          out.push(pfx + cnt[j] + sfx);
        }
        textNode.data = " " + out.join(" ") + " ";
      }
    })();
```

Long words can make short work of your design

Fake Germanizer

```yaml
---
# This frontmatter will be used by CodeDrift
slug: reparenting-iframes
published: 2015-03-17T00:00:00.000Z
description: How to change an iframe parent node without a reload
changelog:
  - on: 2017-10-04
    note: It's been noted in [comments](https://medium.com/@mbogdan/even-in-webkit-support-for-the-so-called-magic-iframe-has-been-removed-882a27d1bf15) and confirmed that the reparenting with `adoptNode()` no longer works and will instead cause the iframe to reload. Based on the [bug report](https://bugs.webkit.org/show_bug.cgi?id=13574), we're also not likely to see this situation change either. So until the situation changes, the answer is "no, you can't call `adoptNode()` without the iframe reloading. You will likely need to get clever with positioning items absolutely.
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

If you're playing around with iframes, there's a nasty bug that occurs when you attempt to move the iframe using methods such as `appendChild` or `insertBefore`. How nasty the bug is depends on how tolerant your code is of reloading behaviors. Any attempts to move the iframe around will cause reloads in older Safari & Firefox versions. The problem lies in how the browsers interpret these events, removing the node and then adding it to its new destination which triggers a reload. If you're trying to move iframes around on the page with something like a drag and drop interface, this rears its ugly head. Strangely enough, IE doesn't exhibit this behavior, which leaves the problem to just Webkit and Firefox.

## Workarounds in CSS

A quick search reveals only one consistent technique for moving iframes about on the page using CSS- positioning absolutely. An absolutely positioned iframe can be readjusted easily, and can track directly on top of a placeholder such as a div. This works pretty fantastically in all but the most complex of layouts where absolute positioning requires a relative parent in just the right place.

```html
<body>
  <div id="#placeholder"></div>
  
  <iframe id="theFrame" src="http://www.example.com" style="left: -12345px; top: 0; position: absolute;"></iframe>
</body>
```

```js
(function () {
  var div = document.getElementById("placeholder");
  var iframe = document.getElementById("theFrame");

  window.setInterval(function putFrameOntoPlaceholder() {
    // 1) measure the size of the iframe, change size of div
    div.width = iframe.offsetWidth + "px";
    div.height = iframe.offsetHeight + "px";

    // 2) get the div's position on the page, position iframe
    iframe.left = div.offsetLeft + "px";
    iframe.top = div.offsetHeight + "px";
  }, 100);
})();
```

In layouts that make heavy use of relative positioning, it's easy to see where this might run into snags. Styles on either the div or iframe could mess up the alignment a bit, and while it's correctable it's not very feasible for a large scale site where there's going to be several developers building code.

## Webkit & Gmail: Adopting Nodes

In July 2010, Google silently released an improvement to Gmail. It was most noticeable when using the gmail chat feature. You could open the chat window, "pop" it out of the main window, and then *close the parent window* and everything continued to work. The most fascinating part about this was the minimal load time in the popup. It was as if the entire Gmail environment were being ported over to the popup as part of the unload events. That's exactly what's happening. **The iframe contained the code both the main page and popup needed.**[The initial webkit bug on reparenting iframes](https://bugs.webkit.org/show_bug.cgi?id=32848) became the ideal fix.

This worked thanks to the [DOM Level 3](http://www.w3.org/TR/DOM-Level-3-Core/core.html) core; a new DOM manipulation method was added called `adoptNode`. Adopting an HTML node would simply move the node and in the case of the iframe, would not trigger a reload of the content. Coming back to Gmail, the JavaScript needed for the popup window is loaded into an iframe. When the parent window is closed, `adoptNode` is called, moving all of the necessary code into the popup window before itself closing.

## And Firefox? Opera? Other Browsers?

Unfortunately, as of this writing, Firefox still has [an open ticket on the [broken adoptNode behavior](https://bugzilla.mozilla.org/show_bug.cgi?id=254144), with no fixes in sight. As a last ditch effort, we can fall back to `importNode`, we will just take the performance hit and trigger an undesirable reload which can possibly erase state within the iframe if there is any.

This stuff hasn't been validated against Opera. Since Opera is based on webkit, it shouldn't be exhibiting this bug.

## Falling Back

Using the below code, it's possible to use `adoptNode` when it's available, and then fall back to the `importNode` as a last resort. Depending on the browser, you may still reload the sub-document. Should the `adoptNode` bug ever get fixed, you'll get a large performance boost in iframes and popups.

```js
try {
  document.adoptNode(window.opener.$("#my-iframe"));
} catch (exc) {
  // performance hit. Either importNode, or load the
  // frame contents with appendChild()
  // remember you'll also need state somewhere
  // in window.opener
  document.importNode(window.opener.$("#my-iframe"));
}
```

It's been noted in [comments](https://medium.com/@mbogdan/even-in-webkit-support-for-the-so-called-magic-iframe-has-been-removed-882a27d1bf15) and confirmed that the reparenting with `adoptNode()` no longer works and will instead cause the iframe to reload. Based on the [bug report](https://bugs.webkit.org/show_bug.cgi?id=13574), we're also not likely to see this situation change either. So until the situation changes, the answer is "no, you can't call `adoptNode()` without the iframe reloading. You will likely need to get clever with positioning items absolutely.

How to change an iframe parent node without a reload

(function () {
  var div = document.getElementById("placeholder");
  var iframe = document.getElementById("theFrame");

  window.setInterval(function putFrameOntoPlaceholder() {
    // 1) measure the size of the iframe, change size of div
    div.width = iframe.offsetWidth + "px";
    div.height = iframe.offsetHeight + "px";

    // 2) get the div's position on the page, position iframe
    iframe.left = div.offsetLeft + "px";
    iframe.top = div.offsetHeight + "px";
  }, 100);
})();


try {
  document.adoptNode(window.opener.$("#my-iframe"));
} catch (exc) {
  // performance hit. Either importNode, or load the
  // frame contents with appendChild()
  // remember you'll also need state somewhere
  // in window.opener
  document.importNode(window.opener.$("#my-iframe"));
}


Reparenting iframes

```yaml
---
slug: window-postmessage-and-ie
published: 2015-03-14T00:00:00.000Z
description: Limitations on a crucial cross-origin API
changelog:
  - on: 2016-01-12
    note: IE 9 Support has **ended**. That means we can finally just use `window.postMessage` the way it was intended. You can safely discard 99% of this now!
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

It started out innocently enough: the LinkedIn Platform needed to run our Professional Plugins on third party sites. To do the basic process of resizing iframes (to fit our plugins), we needed a way to talk across domains. With HTML5, we gained access to `postMessage`, which was a nice standard way of talking between domains. For the browsers such as IE6 and IE7, libraries such as [Apache Shindig](http://shindig.apache.org/) and [easyXDM](http://easyxdm.net/) have found a way to use Visual Basic objects (and later Flash) to coerce older browsers into supporting a compatible interface. Internet Explorer 8 and 9, however, have a set of quirks in its `window.postMessage` which will frustrate users of home-grown solutions and libraries alike. Inevitably, another developer is going to run into these problems.

## Internet Explorer Recasting Things to "Object"

If you're using popup windows alongside a cross domain library, you'll probably be calling methods in `window.opener` to avoid having to create multiple listeners for the postMessage object. While this nuance isn't postMessage specific, if you're using an RPC implementation in a library, you can expect your `success()` and `error()` methods to get mangled.

```js
// child window
function childFunction() {}
window.opener.parentFunction(childFunction);

// parent window
function parentFunction(f) {
  alert(typeof f); // object
}
```

To get around this, you can either serialize the function using or make sure that `parentFunction` doesn't depend on a `typeof` check. Even though in the parent window it looks like an object, it will still begin with "function" when serialized. As an added check, you can verify the existence of `call()` and `apply()` before treating it like a callable object. On some level, what Internet Explorer is doing is correct, as Functions are Objects just like everything else. Since the Parent and Child window both have different window objects, their Function objects would also be different, because reasons.

```js
// Oh IE...
window.opener.Function === Function; // false
```

As of Internet Explorer 9, the typeof operator properly displays the object as Function, implying it's callable. Therefore, the fix can be localized to IE 6/7/8 using a conditional comment in JavaScript.

## No Communication Across Popup Windows

If you're adventurous and forgo a library for cross domain communication, do not expect it to talk to popup windows in Internet Explorer 8. The worst part about this is that it's a [known bug in postMessage](http://blogs.msdn.com/ieinternals/archive/2009/09/16/Bugs-in-IE8-support-for-HTML5-postMessage-sessionStorage-and-localStorage.aspx) for which the current solution is to make an iframe, for which you can then hand off the `window.opener` assignment. There are two problems with this approach. In order to reach our opener, the popup window and iframe will need to be on the same domain or set their `document.domain` property. The second problem is a bit more vexing, as reaching through `window.opener` triggers the first bug mentioned above. The workarounds are still usable, but if you're passing anything more complex than a primitive such as a string between windows, you're sunk.

To be safe, it's worth wrapping the things in postMessage as a string using JSON. If you need to persist objects between windows, giving objects a way to instantiate on the other side is really the only option.

## Origin Mismatching

The rules for postMessage security are pretty straightforward. When calls are made, the origin is derived from the window object used to initiate the postMessage call. The below code highlights the IE8 inconsistency. For whatever reason, reaching through `window.opener` again causes issues, and the domain is changed to the initial script entry point into postMessage versus the page where the code actually resides.

```js
// popup window (popup.example.com)
document.domain = "example.com";
window.opener.postMessageInterface("string");

// window that opened the popup (iframe.example.com)
// just contains normal postMessage()
document.domain = "example.com";
function postMessageInterface(str) {
  window.top.postMessage(str);
}

// On the ultimate listening page, IE8 identifies the origin
// as where the call stack began. Other browsers all identify
// the origin as the domain from which the .postMessage() call
// was made
window.addEventListener(
  "message",
  function receive(evt) {
    // IE 8
    alert(evt.origin); // popup.example.com

    // Every Other Browser
    alert(evt.origin); // iframe.example.com
  },
  false
);
```

The workaround for this is that we can use `setTimeout`. By putting the intent to call postMessage back on the stack, we are able to resolve it with the correct origin.

```js
function postMessageInterface(str) {
  window.setTimeout(function () {
    window.top.postMessage(str);
  }, 0);
}
```

The need to make use of this workaround is even more important if you're using `document.domain` due to a CDN. Even though it's been set in the example, the values are ignored for `postMessage` on IE (even though those exact same rules allowed `window.opener` to be reached in the first place).

## Just Use easyXDM

This is a long post for saying [easyXDM](http://easyxdm.net/) has already solved these problems if you need to support IE 8 and IE 9. We're actively working towards a world where you won't need the library. But if you do, it's there.


IE 9 Support has **ended**. That means we can finally just use `window.postMessage` the way it was intended. You can safely discard 99% of this now!

Limitations on a crucial cross-origin API

// child window
function childFunction() {}
window.opener.parentFunction(childFunction);

// parent window
function parentFunction(f) {
  alert(typeof f); // object
}


// Oh IE...
window.opener.Function === Function; // false


// popup window (popup.example.com)
document.domain = "example.com";
window.opener.postMessageInterface("string");

// window that opened the popup (iframe.example.com)
// just contains normal postMessage()
document.domain = "example.com";
function postMessageInterface(str) {
  window.top.postMessage(str);
}

// On the ultimate listening page, IE8 identifies the origin
// as where the call stack began. Other browsers all identify
// the origin as the domain from which the .postMessage() call
// was made
window.addEventListener(
  "message",
  function receive(evt) {
    // IE 8
    alert(evt.origin); // popup.example.com

    // Every Other Browser
    alert(evt.origin); // iframe.example.com
  },
  false
);


function postMessageInterface(str) {
  window.setTimeout(function () {
    window.top.postMessage(str);
  }, 0);
}


window.postMessage and Internet Explorer

```yaml
---
slug: tailwind-css-in-react-native
published: 2021-05-03T00:00:00.000Z
description: Tailwind's CSS classes in your React Native projects
changelog:
  - on: 2021-12-20
    note: I'm currently using [twrnc](https://www.npmjs.com/package/twrnc) which is an evolution of the tailwind-rn library. A pattern like `gust` is great for custom components, but right now, the React Native ecosystem almost always needs to pass style objects around.
---
```

React Native is very behind the web when it comes to UI libraries. There’s two likely reasons for this: CSS on the web is easy and the object known as `StyleSheet` in React Native is not.

At a fundamental level, the syntax of `StyleSheet` causes a lot of problems. It looks like CSS (the kind you’d use in React’s `style` prop), it acts like CSS (most of the time) just like you’d expect in a browser, but then you encounter one of dozens of scenarios where React Native takes the CSS specification and yeets it out the nearest window.

- Shadows are a custom object syntax instead of a conversion of `box-shadow`
- Random elements such as `ScrollView` introduce custom non-standard props such as `elevation`, but also only for specific platforms
- You get flexbox. Only flexbox. Everything flexes. Everything is boxes. Except for the `flex` property which has decided it is not actually `flex` as you’d expect but just a number that translates to a percentage. But not a useful number-to-percentage like `55` meaning `55%`. Instead, you get an alternate universe number that is expressed as a ratio based on the sum of all flex properties on sibling nodes. It’s a universe where `flex:1` means both `100%` and `50%` based on elements outside of its rendering tree. /rant

Yes, a lot of this will be fixed over time as React Native continues to improve on its style interpreter, but we are still converting from CSS to platform-specific layout calls. I don’t think we’ll ever reach parity, but I’d also like to avoid the programming equivalent of “hammering my thumb” every time I lay things out in a mobile app.

The truth is, what I want is something as easy as [Tailwind CSS](https://tailwindcss.com/) in React Native. If you haven’t tried Tailwind yet, you should. It’s trivial to make something look good, and it’s adaptable enough withstand design changes. In React Native, there's a few really solid options:

* **tailwind-rn**([github](https://github.com/vadimdemedes/tailwind-rn), [npm](https://www.npmjs.com/package/tailwind-rn)) is the OG of Tailwind in your React Native projects. It works by converting the Tailwind styles into JSON, which is memoized in your app on access. Because it tries to be only a translation layer between systems, complex behaviors such as breakpoints and React Native's Appearance are not supported out of the box.
* **tailwind-rn-gust** (_archived_ [github](https://github.com/jakobo/tailwind-rn-gust), [npm](https://www.npmjs.com/package/tailwind-rn-gust)) extends the `tailwind-rn` library by adding utilities for custom component creation. By introducing a React Component generator, it's possible to add additional props to turn "on" flags inside of a call to `tailwind-rn`'s style generator. _However, I wouldn't recommend this, as the components add an additional layer of complexity once you want to use `Animated.View` or other 3rd party components that want to leverage the `style` prop for stylistic behavior.
* **twrnc** ([github](https://github.com/jaredh159/tailwind-react-native-classnames), [npm](https://www.npmjs.com/package/twrnc)) Is what I'm currently using and it leverages [Tailwind's JIT Compiler](https://v2.tailwindcss.com/docs/just-in-time-mode) to remove the built steps inherent in other Tailwind-bridging systems. Out of the box, it uses React Native's hooks for figuring out screen sizes and appearance, making it easier to use normal Tailwind prefixes such as `lg:text-xl`.

Originally, this post focused on `tailwind-rn-gust`, but I think it's becoming more clear that until there's an official Tailwind for React Native, `twrnc` is going to be the truest-to-Tailwind experience you'll find on the platform.

Instead, here's how you'd accomplish something like a rich "press" interaction using `twrnc`. (You can also put both styles into a single `tw.style` call, but I find it easier to read leveraging the array syntax supported for multiple style objects.)

```jsx
<MyComponent style={({pressed}) => [
  tw`bg-red-500`,
  tw.style({
    "bg-blue-500": pressed
  })
]} />
```

The best thing about the `tw` helper is that it's built for generating `style` objects, meaning it'll work with Moti, Reanimated 2, and many other component libraries that focus on the `style` prop.

## Gust Archived
And so, with great alternatives out there, `gust` is archived. The [entire library](https://github.com/Jakobo/tailwind-rn-gust) is only 159 lines and is easy to port into your own existing React Native project if you need the features. However, until we see something like a native `className` in React Native, the `style` tag is going to be the default operating mode for rich styles, animation, and state based effects.


I'm currently using [twrnc](https://www.npmjs.com/package/twrnc) which is an evolution of the tailwind-rn library. A pattern like `gust` is great for custom components, but right now, the React Native ecosystem almost always needs to pass style objects around.

Tailwind's CSS classes in your React Native projects

<MyComponent style={({pressed}) => [
  tw`bg-red-500`,
  tw.style({
    "bg-blue-500": pressed
  })
]} />


A Guide to Tailwind CSS in React Native

```yaml
---
slug: nodejs-memory-leak-heroku
published: 2022-07-19
description: You can connect to your production Heroku instance, debug it live, and even trace down memory leaks.
keywords: heroku, r14, r15, memory leak
changelog: ~
---
```

There's nothing more frustrating that your node.js app leaking memory. If you're coming here because of Heroku R14 / R15 errors, take some deep breaths, it'll be okay. Heroku's smart enough to swap to disk when this happens, and will kill and restart your app if things get absolutely wild.

## Background

![Heroku Dashboard with a lovely orange band of R14 errors](https://user-images.githubusercontent.com/1795/163650457-2371246f-bc80-4482-b42e-8bfdbf664a1a.png)

It started with my email box getting pelted with warnings that the memory quota on a project I advise for was getting hit with R14 errors. Going to the Heroku metrics page confirmed that yes, something was clearly wrong. In the above picture, you can see again and again the memory usage surge and then Heroku responding with an R15 and force rebooting the server. Moments later, the memory usage was growing again.

It's a Memory Leak, Ruin of Productivity and afternoons. 😭 

However, since the last time I dealt with a memory leak (2011) the tools have come a long way. So here's how you triage a production memory issue, run analysis against your currently leaking production boxes, and stamp out the issue.

## Modern Tools

The tools for dealing with a memory leak have gotten much better, especially if you're on Heroku. You only need two:

* A current version of Chrome (which comes with the amazing v8 debugger)
* The Heroku CLI (if on Heroku)

The first does 90% of the heavy lifting, while the second now has all the commands we need to turn on a debugger in production and forward debug data to our local machine. Make sure you've logged in to the Heroku CLI if you're triaging Heroku.

## Opening Chrome's Inspector

The Chrome Developer Tools are always available on `chrome://inspect`, which can be put in your browser's address bar. The DevTools are useful for debugging everything from node.js processes to Service workers. For now, we want to stay on the `Devices` tab, make sure `Discover network targets` is checked, and leave that window open while we set other things up. You may even see a few device targets show up that Chrome's discovered. In my case, apparently my TV can be seen. Odd, but neat.

![The Chrome developer tools](https://user-images.githubusercontent.com/1795/163651415-d75abf95-e781-45fb-ab2c-3e9adcb6ba1d.png)

## Enabling the Debugger With a Signal

The most common way to start debugging node is to add the `--inspect` CLI arg, either directly (via `node --inspect <your file>`), or in the appropriate env values ( `NODE_OPTIONS="--inspect" node <your file>`). In production environments, it may not be desirable to enable the debugger on every start; in the case of Heroku which randomly assigns ports, you can't even guarantee the debug port of `9229` is available. But, you can enable the debugger a different way.

From the [node.js debugging page](https://nodejs.org/en/docs/guides/debugging-getting-started/)

> Node.js will also start listening for debugging messages if it receives a SIGUSR1 signal. (SIGUSR1 is not available on Windows.) In Node.js 7 and earlier, this activates the legacy Debugger API. In Node.js 8 and later, it will activate the Inspector API.

Sending a signal is as easy as using the unix `kill` command, where `<PID>` is your node.js process ID:

```sh
$ kill -usr1 <PID>
```

You can try this locally by running `ps aux | grep node` to find your node.js process, and then using the `PID` for the above `kill` command. Personally, I find that the `usr1` signal is not only more reliable (works everywhere) but also means you don't have to completely restart the server. When you send `usr1`, node just sees the signal and starts up its debugger. It'll pop up moments later in the Chrome DevTools.

![local development showing the inspector starting](https://user-images.githubusercontent.com/1795/163651616-5d423ec2-bdd9-4bcd-828c-29e4bbf5335e.png)

![the development tools showing the new remote target](https://user-images.githubusercontent.com/1795/163651579-b7181e72-86d9-47e9-9d46-eb4c3cf76bc4.png)

Hit the `inspect` link and you'll be taken to a very familiar DevTools interface, but optimized for node.js debugging. In addition to the Console and Sources, you'll also have "Profiler" for CPU profiling, and "Memory" for memory usage profiling,

![connected development tools, ready to go](https://user-images.githubusercontent.com/1795/163651715-22c7a39a-81cb-43da-bc97-4e17523ffb56.png)

## Connecting to Heroku in Production

Once that's all working, it's time to connect to our production instance in Heroku and take some live samples. Close the inspector and local development server if needed, and make sure your `heroku` command works. If you're using a different environment such as Digital Ocean, look up SSH instructions to get to your host. They'll be different on every provider.

For heroku, there's the `ps:exec` command which gives you a shell on your default process for dyno 1. Be sure to specify your `<APP_NAME>` so that you're ssh-ing into the correct box, and if you need to connect to a dyno process that's not `web`, add the `-d <dyno>` flag.

```sh
$ heroku ps:exec -a <APP_NAME>
```

![connecting to a remote box over SSH](https://user-images.githubusercontent.com/1795/163652037-8309d4c9-452a-4bf5-848a-98f466346471.png)

From here, we can search our node process with `ps aux | grep node` and start the debugger with `kill -usr1 <PID>`. Our debugger will start, but obviously we can't see it yet. Heroku (and other providers) don't expose port `9229` to the internet for security reasons. Open another terminal window and use heroku's forwarding command to create a local tunnel for your debugger (and add the optional `-d` flag if needed).

```sh
$ heroku ps:forward -a <APP_NAME>
```

And just like that, your production instance shows up in the Chrome DevTools.

## Sampling

Taking samples is straightforward. Wait for the VM instance size to grow, click the trash can icon (force GC) to ensure it's actually grown by a reasonable amount, and then hit the **Take Snapshot** button to capture a memory heap. Chrome DevTools will be busy for a bit, but it'll create a Heap, which it adds to the left-hand side of the Memory profiler. Every heap is a detailed analysis of what was in JavaScript at that exact moment. Every string, object, key, event, closure, callback; you name it, it's here.

Collect several samples (5-6 is ideal) since you'll be looking for identifiable trends. I also recommend waiting about 2-3 MB between each sample. We want our growth in memory to be noticeable, and whatever's leaking to stick out.

Here, I've got 6 production samples of a leaking app. In the time I sampled, we added about 15MB to the footprint. 😱 

![chrome devtools with several heaps loaded](https://user-images.githubusercontent.com/1795/163652520-5df538be-aa9a-4ae7-bf41-17617abe030f.png)

What matters is we can see the memory growing, we have several samples of the Heaps in question (which contain our growing memory), and those Heaps are readable by the Chrome DevTools. We can save the Heaps, disconnect from our production machine (which also closes the debugger), and get to our analysis.

## Using Heap Compare

Select the newest (largest) Heap, and above the list of objects in the heap, change from `Summary` to `Comparison`. This changes the Heap view from telling you what's in the Heap to what changed **between** Heaps.

![how to change from summary to comparison view](https://user-images.githubusercontent.com/1795/163652680-cd5f2530-6b12-4c00-8014-326df53c8a80.png)

Sort the table by `# Delta`, and the problem suddenly becomes very obvious.

![a sorted by delta comparison](https://user-images.githubusercontent.com/1795/163652782-5832abe0-c4c3-4e79-b804-100f1916fa47.png)

We can compare against a few other Heaps (that's why we captured them) to isolate the source of the memory leak. Here, I'm comparing Heap 5 to Heap 4, where the number of `(concatenated string)` is much smaller and easier to manage. There's a lot of weird date strings like "-137 days, 21" being created and retained. Clicking on one gives us the full Retainer log. It's part of a larger string, that's part of a larger string, that's in `discountTimeLeft` in the update cycle of a React component called `DiscountBanner`, inside of a... `Timeout`.

![The memory leak source](https://user-images.githubusercontent.com/1795/163653410-35a401c4-0b85-4eb6-9c14-4eec51878a0d.png)

Opening up the `DiscountBanner` culprit, there's a `setInterval` in the `constructor`. Fixing this and redeploying closed the memory leak. It turned out that when next.js was running in Heroku, the `setInterval` would just keep on running and building its string about how many days were left on the discount. Since that string was locked in the `setInterval` callback, it could never be garbage collected by v8. Add in a few thousand requests per second, and those discount strings would ultimately take up all of the available memory and cause Heroku to restart the server with an R15 error.

## More than Heaps

I only needed the Heap compare, but the CPU profiler and the Memory timeline (Allocation instrumentation on timeline) can help narrow the issue even further in a larger application. The hardest part is getting a reproducible issue. Looking at production not only makes it easier, but ensures you're solving the right problem. And when you're done, you'll never put a `setInterval` in a React component constructor again. 😆 

You can connect to your production Heroku instance, debug it live, and even trace down memory leaks.

Solving a Node.js Memory Leak on Heroku

```yaml
---
slug: use-github-as-a-cms
published: 2022-01-11T11:40:00-08:00
description: GitHub's rich GraphQL API gives you a built-in headless CMS
changelog: ~
---
```

First thing's first. I really love [Ghost](https://ghost.org/). It's got an excellent content and admin API and I'd honestly consider it better than many other Headless CMS options. Second, this isn't a post about Ghost. There were two major shortcomings in Ghost that ultimately I couldn't find good workarounds for.

1. Custom structured data. As it stands I was jamming everything into `codeinjection_foot` as YAML and hoping I didn't ever need that field. I also needed to comment my code explaining all my additional metadata resided in the field not called `metadata`. Yikes.
2. Something that isn't Mobiledoc. I understand why it's used. I don't like that my parsing process on Codedrift requires that I start from the final HTML and then throw it all in [rehype](https://github.com/jakobo/codedrift/blob/9d0bd286355f5b80d1ba71561d78603a9a388ed0/src/components/markup/rehype.js#L25) to [fix URL links, remove widowed text, and more](https://github.com/jakobo/codedrift/blob/0f5991456f576dd031f2e95888af5878a63f16c3/src/graphql/util.js).

HTML to AST back to HTML is not a good feeling and the pipeline was brittle. When I realized I didn’t want to re-add tags on my posts to Codedrift because of the complexity, I looked for alternatives.

I saw [Casual JavaScript](https://github.com/casualjavascript/blog) which was running the entire site off of [GitHub Issues](https://github.com/casualjavascript/blog/blob/gh-pages/index.html). It wasn't perfect, but GitHub Issues are in Markdown, and Markdown _does_ support frontmatter, and frontmatter _is literally designed for metadata_.

The missing piece was something that wasn't issue based. [Discussions](https://github.blog/changelog/2021-02-23-github-discussions-graphql-api-public-beta/). Sold.

## Core Tools
The original Codedrift had a GraphQL micro server that ran everything. It was overengineered (like all good personal projects should be), but in the rewrite I wanted to remove as much of my code as possible. The entire GraphQL infrastructure became a simple [http proxy](https://github.com/jakobo/codedrift/blob/9d5b0349dc204cd1076b54fd5e475dffe449c84d/src/pages/api/proxy/api.github.com/graphql.ts) using [http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). This way I wouldn't need to expose a personal access token in the browser.

The next step was to use [graphql-code-generator](https://www.graphql-code-generator.com/) for Typescript typed Urql hooks. I'm still a fan of Urql, and their [docs for next.js integration](https://formidable.com/open-source/urql/docs/advanced/server-side-rendering/#nextjs) are easy to follow and set up.

Because scope creep is a thing, the site's now also in Typescript. 🥳 

So now I've got typed GraphQL queries to GitHub's API without exposing the access token. All that's left is to get our Discussions, turn them into blog posts, and solve for weird cases like [tag-based searches](https://github.com/jakobo/codedrift/blob/main/src/pages/thunked/tag/%5Bname%5D.tsx#L19) which need to go through the `search` endpoint instead of the `repository` endpoint. Consistency (and sanity) between queries came from the Post fragment.

## The Post Fragment
Fragments are [better explained by graphql.org](https://graphql.org/learn/queries/#fragments), but in context they are the reusable unit of documents. In this case, a fragment on `Discussions` will let me get the same fields every time for our discussion, regardless if I arrived at the Discussion via the `search` endpoint or a `repository` endpoint. Even though it might overfetch a little for its use case, a fragment pushed through graphql-code-generator will give you a typed object representing the returned data structure.

In other words, having this GraphQL fragment
```gql
fragment PostDetails on Discussion {
  id
  title
  lastEditedAt
  url
  labels(first: 100) {
    nodes {
      id
      name
      description
    }
  }
  author {
    avatarUrl(size: 10)
    ... on User {
      id
      name
    }
  }
  body
}
```

Will give us this type in our generated file:
```ts
export type PostDetailsFragment = {
  __typename?: "Discussion";
  id: string;
  title: string;
  lastEditedAt?: any | null | undefined;
  url: any;
  body: string;
  labels?:
    | {
        __typename?: "LabelConnection";
        nodes?:
          | Array<
              | {
                  __typename?: "Label";
                  id: string;
                  name: string;
                  description?: string | null | undefined;
                }
              | null
              | undefined
            >
          | null
          | undefined;
      }
    | null
    | undefined;
  author?:
    | { __typename?: "Bot"; avatarUrl: any }
    | { __typename?: "EnterpriseUserAccount"; avatarUrl: any }
    | { __typename?: "Mannequin"; avatarUrl: any }
    | { __typename?: "Organization"; avatarUrl: any }
    | {
        __typename?: "User";
        id: string;
        name?: string | null | undefined;
        avatarUrl: any;
      }
    | null
    | undefined;
};
```

Even a `Partial<PostDetailsFragment>` adds excellent safeguards to a function when I expect to receive data shaped like the GraphQL response for a Discussion.

## Slugs and Search
Fetching the most recent posts is [a straightforward process](https://github.com/jakobo/codedrift/blob/cbcc0f4beac26e611c14cb789a7adc5b3ba7c55a/src/graphql/posts.graphql#L27) since the API can go from a repository to its discussions and limit those to a single category. For accessing a single post by anything other than its ID, there's only the `search` endpoint.

A generic search on GitHub takes a search query as a string. It's the same string used in [GitHub's Advanced Search](https://github.com/search/advanced?r=jakobo%2Fcodedrift) which at least means it's easy to test and iterate on, even if there is no official query builder. The result is a very generic GraphQL query for searching, which can be used for both slugs and tags. It could probably also be used for the recently created posts, but I'd prefer less magic strings where possible.

```gql
query SelectPostsWithSearch($search: String!, $first: Int = 1, $after: String) {
  search(first: $first, after: $after, type: DISCUSSION, query: $search) {
    nodes {
      ... on Discussion {
        ...PostDetails
      }
    }
    discussionCount
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}
```

The first of two major downside to this approach is I need to constantly cast the node collection to `Discussion`, but I feel that's more my inexperience with Typescript than the language itself. The other is that because when running a search, there's always a risk of returning two records for a search. I briefly thought about changing the URLs to be `slug/post_id` but that felt like it was binding me too closely to GitHub's ID system.

## The New Post Workflow
Posts on Codedrift start in [my public notes](https://codedrift.com/notes), but eventually they’re well-formed enough to get ideas and opinions. At that point, there’s discussion on the draft, which used to exist exclusively over email and Twitter DMs. These processes also worked, but it always felt like I was missing an opportunity for more open discourse about a topic.

So now, when a post grows out of Codedrift, it’ll become an [issue](https://github.com/jakobo/codedrift/issues?q=is%3Aopen+is%3Aissue+label%3A%22%E2%9C%92+Draft%22), When it’s ready to be published, it can be moved to a Discussion, and GitHub saves all of the relevant comments and edits in the transfer. This has the added benefit of matching my mental model. Unposted content is an issue which certainly needs resolution. Posted content deserves a discussion.

The code for all of this is in the [Codedrift repository](https://github.com/jakobo/codedrift), though now that I'm just calling a GitHub API with no interference, the code feels very vanilla. And that feels pretty good.

GitHub's rich GraphQL API gives you a built-in headless CMS

fragment PostDetails on Discussion {
  id
  title
  lastEditedAt
  url
  labels(first: 100) {
    nodes {
      id
      name
      description
    }
  }
  author {
    avatarUrl(size: 10)
    ... on User {
      id
      name
    }
  }
  body
}


export type PostDetailsFragment = {
  __typename?: "Discussion";
  id: string;
  title: string;
  lastEditedAt?: any | null | undefined;
  url: any;
  body: string;
  labels?:
    | {
        __typename?: "LabelConnection";
        nodes?:
          | Array<
              | {
                  __typename?: "Label";
                  id: string;
                  name: string;
                  description?: string | null | undefined;
                }
              | null
              | undefined
            >
          | null
          | undefined;
      }
    | null
    | undefined;
  author?:
    | { __typename?: "Bot"; avatarUrl: any }
    | { __typename?: "EnterpriseUserAccount"; avatarUrl: any }
    | { __typename?: "Mannequin"; avatarUrl: any }
    | { __typename?: "Organization"; avatarUrl: any }
    | {
        __typename?: "User";
        id: string;
        name?: string | null | undefined;
        avatarUrl: any;
      }
    | null
    | undefined;
};


query SelectPostsWithSearch($search: String!, $first: Int = 1, $after: String) {
  search(first: $first, after: $after, type: DISCUSSION, query: $search) {
    nodes {
      ... on Discussion {
        ...PostDetails
      }
    }
    discussionCount
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}
