Home

Awesome

live_json

GitHub Hex.pm WIP

LiveJSON is an Elixir/Phoenix library which provides LiveView-like updating for JSON objects rather than DOM elements. It works within your existing LiveViews - just use push_patch as you would assign or push_event. Only the changes to the data are sent over the wire, not the whole object every time, so it can end up being quite fast indeed.

This may be useful for front-end frameworks, data visualization, games and anything else where you need dynamically updated data that lives outside of the DOM, like mobile apps.

Fundamentally, LiveJSON is an easy way interact with client's JavaScript context from LiveView.

Example

def handle_info({:new_data_to_visualize, new_data} = _event, socket) do
  {:noreply, 
    socket
    |> push_patch("viz_data", new_data)
  }
end

Now, check your JS console:

window.viz_data
// {1: ["a"], 2: ["b"] ... 99999: ["zzzzz"]}

The data is automatically updated, but if you check the WebSocket, you'll see that only the data that changed has been sent.

Problem / Solution

Phoenix LiveView is awesome for automatically updating your webpage's DOM. However, it doesn't work as well for data objects, since it only works at the DOM level out of the box, meaning any complex data objects need to be entirely re-sent every time. So, if you load your JS app's data via a templated script tag, LiveView will rewrite the whole tag, not just the elements that changed, which means sending a lot of data over the wire and other headaches on the client-side.

LiveJSON is a simple alternative - it uses Jsondiff/JSON-Patch (RFC 6902) to only send the delta of the data, which is then patched client side, similar to how morphdom works on the DOM.

Installation

First, the usual:

def deps do
  [
    {:live_json, "~> 0.4.3"}
  ]
end

Next, you'll need to set up the hooks in your app.js:

// Import the JS..
import { createLiveJsonHooks } from 'live_json';
const liveJsonHooks = createLiveJsonHooks();

// ..then define all your hooks..
const Hooks = {
  // your other hooks
  // ...
  ...liveJsonHooks,
};

// ..and use them!
let csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content")
let liveSocket = new LiveSocket("/live", Socket, {
  hooks: Hooks,
  params: {_csrf_token: csrfToken},
});

If your app uses an assets/package.json, you'll also need to add:

{
  "dependencies": {
    "live_json": "file:../deps/live_json"
  }
}

and then npm install.

Finally, you'll need to put a tag for the hook somewhere on the related Heex:

<div id="lj" phx-hook="LiveJSON"></div>

Usage

Normal usage requires two commands: initialize and push_patch.

On your mount, initialize the state:

def mount(_params, _, socket) do
  data = get_your_data()

  {:ok,
    socket
    |> LiveJson.initialize("dataviz", data)
  }
end

Then, to send updated data:

def handle_info({:new_data_to_visualize, new_data} = _event, socket) do
  {:noreply, 
    socket
    |> LiveJson.push_patch("dataviz", new_data)
  }
end

Or, in RFC 6902 mode:

def handle_info({:new_data_to_visualize, new_data} = _event, socket) do
  {:noreply, 
    socket
    |> LiveJson.push_patch("dataviz", new_data, :rfc)
  }
end

In your JS console window.dataviz will now hold the updated data for this example. Also note that dataviz is just an example - you can call it whatever you want the object to be called, and you can have multiple objects on the same page.

Each init/patch also emits a global event, which you can listen to with:

window.addEventListener('dataviz_initialized', event => doSomethingOnInit(), false)
window.addEventListener('dataviz_patched', event => doSomethingOnPatch(), false)

Utility Functions

LiveJSON also includes some utility functions that you might want if you're working with Phoenix and JavaScript at the same time.

Assign

Assign a value in the JS context without tracking.

{:noreply, 
  socket
  |> LiveJson.assign("foo", "bar")
}

window.foo
// "bar"

Also dispatches a doc_name + "_assigned" event.

Append

Append data to a list in the JS context without tracking. Will create the list if it doesn't global exist.

{:noreply, 
  socket
  |> LiveJson.append("foo", "bar")
  |> LiveJson.append("foo", "baz")
}

window.foo
// ["bar", "baz"]

Also dispatches a doc_name + "_appended" global event.

Put

Put data in a map in the JS context without tracking. Will create the dictionary if it doesn't exist.

{:noreply, 
  socket
  |> LiveJson.put("foo", "bar", "baz")
}

window.foo
// {"bar": "baz"}

Also dispatches a doc_name + "_put" global event.

Sending Data to Your Application

LiveJSON also provides a convenient way to send data from a JavaScript context back to your Phoenix LiveView without user interaction.

import { sendData } from 'live_json';
sendData('your_handler', your_data); 
// or sendData('your_handler', your_data, 'your_hook_id_if_it_isnt_lj')

or:

const ljEvent = new CustomEvent('send_data', {
  bubbles: true,
  detail: { 
    name: 'your_handler',
    data: your_data,
  }
});
document.getElementById("lj").dispatchEvent(ljEvent);

def handle_event("your_handler", data, socket) do
  IO.inspect("Got data!")
  {:noreply, socket}
end

Also dispatches data_sent and your_handler + "_sent" global events.

Capabilities and Limitations

Fast and Non-Standard

By default, LiveJSON uses jsondiff for diffing/patching data. This is fast, but isn't defined by an RFC and subject to change, and may not have a client available on all plaforms. This is the best solution if you just want performance on a page you control.

Slower and Standardized

Alternately, you can use :rfc mode to use JSON-Patch (RFC 6902) style patching. This is (currently) slower, but will mean that your data can be used by a larger number of consumers, such as a mobile applications.

As of 0.2.1, this is much faster!

TODO

Standing on the Shoulders of Giants

There actually isn't very much code in this repo, just a convenient interface and application of work done by other people:

Other people have tried to solve this problem in other ways, but this was the solution that I wanted for my application. If you'd like to explore alternate approaches see:

The project structure for building and packaging hooks comes from:

License

2022, Rich Jones, MIT License

Note

This project lives at github.com/Miserlou/live_json. If you're seeing it on another website that isn't GitHub or Hex, it has been scraped by some SEO scammer. Please check out the real homepage instead.