Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/brisa-build/diff-dom-streaming

HTML Streaming Over the Wire! 🥳 Diff DOM algorithm with streaming to make only the necessary modifications, insertions and deletions between a DOM node and an HTML stream reader.
https://github.com/brisa-build/diff-dom-streaming

diff dom dom-manipulation html-streaming javascript typescript virtual-dom

Last synced: 22 days ago
JSON representation

HTML Streaming Over the Wire! 🥳 Diff DOM algorithm with streaming to make only the necessary modifications, insertions and deletions between a DOM node and an HTML stream reader.

Host: GitHub
URL: https://github.com/brisa-build/diff-dom-streaming
Owner: brisa-build
License: mit
Created: 2024-04-02T16:14:35.000Z (9 months ago)
Default Branch: main
Last Pushed: 2024-11-09T19:25:39.000Z (about 1 month ago)
Last Synced: 2024-11-19T04:21:06.199Z (25 days ago)
Topics: diff, dom, dom-manipulation, html-streaming, javascript, typescript, virtual-dom
Language: TypeScript
Homepage: https://stackblitz.com/edit/diff-dom-streaming?file=index.js
Size: 85.9 KB
Stars: 120
Watchers: 6
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-brisa - Diffing DOM Streaming
awesome-brisa - Diffing DOM Streaming

README

        


    

      

      

    

        
Diff DOM Streaming


[![npm version](https://badge.fury.io/js/diff-dom-streaming.svg)](https://badge.fury.io/js/diff-dom-streaming)

![npm](https://img.shields.io/npm/dw/diff-dom-streaming)

![size](https://img.shields.io/bundlephobia/minzip/diff-dom-streaming)

[![PRs Welcome][badge-prwelcome]][prwelcome]









[badge-prwelcome]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square

[prwelcome]: http://makeapullrequest.com

The Diff DOM (Document Object Model) algorithm is used to compare two versions of the DOM, such as before and after an update on a web page. It aims to efficiently identify the changes between both DOMs, minimizing the number of manipulations required to update the user interface.

The Diff DOM Streaming library extends the traditional Diff DOM algorithm by introducing support for comparing a DOM node with a stream. This enables the library to process the changes incrementally as they occur during the diff process.

For more info, read this:

- [HTML Streaming Over the Wire | A Deep Dive](https://dev.to/aralroca/html-streaming-over-the-wire-a-deep-dive-2n20).

- [SPA-like Navigation Preserving Web Component State](https://dev.to/aralroca/spa-like-navigation-preserving-web-component-state-lh3)

## Getting started

### NPM

Install:

```sh

bun install diff-dom-streaming

```

Then import it:

```ts

import diff from "diff-dom-streaming";

```

### JSR

Install:

```sh

bunx jsr add @aralroca/diff-dom-streaming

```

Then import it:

```ts

import diff from "@aralroca/diff-dom-streaming";

```

### UNPKG

Just import it:

```tsx

import diff from "https://unpkg.com/diff-dom-streaming@latest";

```

## Using it

```ts

const res = await fetch(/* some url */);

// Diff between the current document and the stream:

await diff(document, res.body);

```

## API

`diff(oldNode: Node, stream: ReadableStream, options?: Options): Promise`

This function performs a diffing operation between the `oldNode` and the DOM tree from a stream. It applies the necessary changes to update the `oldNode` accordingly. An optional `options` that include:

```ts

type Options = {

  // calback to handle each new docoument node during the streaming

  // (default: undefined)

  onNextNode?: NextNodeCallback;

  // update the DOM using document.startViewTransition (default: false)

  transition?: boolean;

  // callback to ignore nodes (default: undefined)

  shouldIgnoreNode?: (node: Node | null) => boolean;

};

```

## Lists and `key` attribute

Keys help to identify which items have changed, are added, or are removed. Keys should be given to the elements inside the array to give the elements a stable identity:

```jsx 3

const numbers = [1, 2, 3, 4, 5];

const listItems = numbers.map((number) => (

  
{number}

));

```

_(Example with JSX)_

The `diff-dom-streaming` library takes into account the `key` attribute for these cases, if it does not exist, then see if they have `id`.

## Transitions between pages (View Transition API)

You can activate the View Transition API updating the DOM with this property:

```diff

await diff(document, res.body, {

+ transition: true

})

```

> [!TIP]

>

> To access the transition with JavaScript/TypeScript you can access the global property `window.lastDiffTransition`

### Incremental vs full transition

Many times it will make more sense to use a complete transition instead of incremental, especially if we do not use suspense and we want a single transition at once instead of several, in this case, instead of using the configuration, we can use the View Transition API directly:

```diff

+ document.startViewTransition(async () => {

await diff(document, res.body, {

-  transition: true,

});

+});

```

## Strong Opinion on BODY Tag Attributes during Diffing

Our library has a strong opinion regarding the handling of the BODY tag attributes during the HTML diffing process. This approach is designed to provide greater flexibility and control over runtime modifications, such as themes, fonts, and other display properties that are managed through BODY tag attributes.

During the diffing process, all content within the HTML is typically updated to reflect the latest changes. However, we recognize that certain attributes of the BODY tag, like `class` and custom `data-attributes`, are often modified at runtime to control the presentation of the content. To avoid overwriting these runtime changes, our library's diffing algorithm specifically excludes these attributes from being updated.

### Key Points

- **Preservation of Attributes**: Attributes of the BODY tag (e.g., `class`, `data-attributes`) are preserved and not overwritten during the diffing process.

- **Consistent Display**: This ensures that runtime modifications, such as theme changes or other display-related adjustments, remain intact across navigations and updates.

- **Enhanced Customization**: Users can rely on the BODY tag attributes to manage display properties without concern for them being reset during content updates.

### Example

Consider the following scenario where the initial HTML and updated HTML are as follows:

#### Initial HTML

```html

  
Content A


```

#### Updated HTML

After a navigation or content update, the new HTML may look like this:

```html

  
Content B


```

### Result After Diffing

After the diffing process, the resulting HTML will be as follows:

```html

  
Content B


```

## Examples

In the repo we have examples for you to try.

### Locally

There are some examples:

- Run `bun run example:boxes`

- Run `bun run examples:spa-like`

### Stackblitz

You can run the boxes demo with Vanillajs [here](https://stackblitz.com/edit/diff-dom-streaming?file=index.js).

![ezgif-4-1ff18912f4](https://github.com/aralroca/diff-dom-streaming/assets/13313058/f18c01c0-4dfe-473f-8817-fb905adc20c1)

## Acknowledgments

The Diff DOM Algorithm with HTML Streaming is inspired by the [set-dom](https://github.com/DylanPiercey/set-dom) library by [@dylan_piercey](https://twitter.com/dylan_piercey) and a technique for parsing streams pioneered by [@jaffathecake](https://twitter.com/jaffathecake).

## Contributing

See [Contributing Guide](CONTRIBUTING.md) and please follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## License

[MIT](LICENSE)