# jsdom-extras

Convenience utilities for working with **JSDOM / JSaddle** from Haskell. This package wraps a few common patterns you’ll reach for in browser-ish code: console logging, JSON ↔︎ JSVal conversion, small object helpers, and a tiny utility to wait for globals to appear.

> **Motivation**
> If you’re doing Reflex-DOM or JSaddle work, you often need to bridge `aeson` values, poke at JS objects, or
> ensure a script on the page has loaded before using it. `jsdom-extras` provides a small, typed toolkit for that.

---

## Features

* **Console logging** via `console.log` without requiring `Show` or manual conversions.
* **JSON helpers:** `Value ↔︎ JSVal` that work on both GHCJS and JSaddle-native backends.
* **Object helpers:** Build, decompose, and query JavaScript `Object`s in a few lines.
* **Wait for globals:** Poll for a `window` global and run code once it’s available.

---

## Quick start

Below are small, self‑contained snippets. All examples assume:

```haskell
{-# LANGUAGE OverloadedStrings #-}
import Language.Javascript.JSaddle (JSM, JSVal, MonadJSM)
import qualified JSDOM.Extras.ConsoleLog as C
import qualified JSDOM.Extras.JSON       as J
import qualified JSDOM.Extras.Object     as O
import qualified JSDOM.Extras.WaitForJS  as W
```

### 1) Console logging

```haskell
hello :: MonadJSM m => m ()
hello = C.consoleLog ("Hello from Haskell!" :: JSM.String)
```

No `Show` burden: anything with `ToJSVal` is fair game.

### 2) JSON ↔︎ JSVal

```haskell
import Data.Aeson (Value(..), object, (.=))

mkUser :: JSM JSVal
mkUser = J.jsValFromJSON (object ["name" .= ("Ada" :: String), "id" .= (1 :: Int)])

roundTrip :: JSVal -> JSM (Maybe Value)
roundTrip v = J.jsValToJSON v

stringified :: JSVal -> JSM JSM.String
stringified v = J.stringify v

parsed :: JSM JSVal
parsed = J.parse =<< J.toJSVal ("{\"ok\":true}" :: JSM.String)
```

These functions are **platform‑independent**:

* On **GHCJS**, conversions use `toJSVal`/`fromJSVal`.
* On **JSaddle native**, we reuse JSaddle’s internal JSON bridges.

### 3) Object helpers

```haskell
mkObj :: MonadJSM m => m O.Object
mkObj = O.toObject [("answer", 42 :: Int), ("name", "Ada" :: JSM.String)]

readObj :: MonadJSM m => O.Object -> m [(JSM.String, JSVal)]
readObj = O.fromObject

findKey :: MonadJSM m => O.Object -> m (Maybe JSVal)
findKey o = O.lookup "answer" o

noop :: O.JSCallAsFunction
noop = O.doNothing
```

`lookup` gracefully treats `null` and `undefined` as `Nothing`, and `toMaybe` is exposed if you need it directly.

### 4) Wait for a global and use it

Useful when a script tag populates `window.SomeLib` asynchronously.

```haskell
useWhenReady :: MonadJSM m => m ()
useWhenReady = W.withGlobalJS "SomeLib" $ \lib -> do
  -- do something with `lib :: JSVal`
  C.consoleLog ("SomeLib is ready" :: JSM.String)
```

`waitForGlobalJS` polls at ~250ms intervals until the value is present (neither `null` nor `undefined`). If you want a non‑blocking probe, use `getGlobalJS` which returns `Maybe JSVal`.

---

## API reference

The library exposes four modules:

* `JSDOM.Extras.ConsoleLog`

  * `consoleLog :: (MonadJSM m, ToJSVal a) => a -> m ()`

* `JSDOM.Extras.JSON`

  * `jsValFromJSON :: Value -> JSM JSVal`
  * `jsValToJSON   :: JSVal -> JSM (Maybe Value)`
  * `stringify     :: MonadJSM m => JSVal -> m JSM.String`
  * `parse         :: MonadJSM m => JSVal -> m JSVal`

* `JSDOM.Extras.Object`

  * `type ToJSObject k v = (ToJSString k, ToJSVal v)`
  * `singleton   :: (ToJSObject a b, MonadJSM m) => a -> b -> m Object`
  * `toObject    :: (MonadJSM m, ToJSObject a b) => [(a, b)] -> m Object`
  * `fromObject  :: MonadJSM m => Object -> m [(JSM.String, JSVal)]`
  * `lookup      :: MonadJSM m => JSM.String -> Object -> m (Maybe JSVal)`
  * `toMaybe     :: MonadJSM m => JSVal -> m (Maybe JSVal)`
  * `doNothing   :: JSCallAsFunction`

* `JSDOM.Extras.WaitForJS`

  * `getGlobalJS   :: MonadJSM m => Text -> m (Maybe JSVal)`
  * `waitForGlobalJS :: MonadJSM m => Text -> m JSVal`
  * `withGlobalJS  :: MonadJSM m => Text -> (JSVal -> m a) -> m a`