3.0.0

[jiripudil]

Naja 3.0 is an evolutionary release and should not come with any breaking changes for the majority of users. The breaking changes are mostly expected to affect advanced users, and developers who build custom extensions on top of Naja.

That said, there have been some changes in the inner workings of the snippet cache that may alter the behaviour, so it is strongly recommended that you properly test your application against the 3.x release.

New features

• ✨ SnippetHandler supports asynchronous snippet update operations, such as using View Transitions API. (Snippet update operation with ViewTransition API #383) You can now wrap snippet updates in transitions, and rely on Naja dispatching the afterUpdate event only after the update has been completed.

  • SnippetHandler dispatches a new pendingUpdate event. The event is dispatched right before the now asynchronous update is invoked, and only if the update has not been prevented in the beforeUpdate event.

  • ⚠️ BREAKING CHANGE: if you are using SnippetHandler.updateSnippet() or SnippetHandler.updateSnippets() method directly, please note that the method is now asynchronous and the DOM is guaranteed to be updated only after its returned promise resolves.

  • ⚠️ BREAKING CHANGE: due to the asynchronicity, it is no longer guaranteed that all snippets have been updated by the time success and complete events are dispatched.

• ✨ SnippetCache stores raw snippet content. (Snippet caching problem when afterUpdate modifies snippet DOM #368) This makes snippet restoration more deterministic for snippet update event listeners.

  The afterUpdate event is the preferred way to e.g. initialize third-party scripts and widgets. Previously, snippet cache wasn't populated until after updating the snippets, and thus snippets stored in the cache might already have contained these DOM modifications; as a result, the same afterUpdate listener would receive different inputs in different scenarios: one pristine when updating from the server, and one already modified when restoring the snippet from cache during history navigation.

  In Naja 3.0, snippets are cached in the original form whenever possible, so that afterUpdate event listeners receive the same, unaltered input, regardless of where it comes from.

  • ⚠️ BREAKING CHANGE: if you are implementing your own snippet update operation, it is now expected to be an object implementing a pair of methods:

    • updateElement(snippet: Element, content: string): void | Promise<void>

      This method should just wrap the original, pre-3.0 snippet update operation: it updates the snippet element with the content received from the server. As per the previous section, the update can now be asynchronous.

    • updateIndex(currentContent: string, newContent: string): string

      This method has been added to integrate with the enhanced snippet cache capabilities. It applies the newContent received from the server onto the snippet's cached currentContent, and returns the result. This method works entirely with the raw snippet contents, no DOM involved.

      For example, the built-in replace operation implements this method so that it returns newContent, whereas the append operation does return a concatenation of currentContent + newContent.

    Current snippet update operation implementations are backward-compatible, with updateIndex() falling back to simply returning newContent received from the server. It is recommended that you update your implementation to include the newly added method, so that you have full control over the implementation and its behaviour.

---

This discussion was created from the release 3.0.0.

[jiripudil]

My talk from posobota where I'm introducing the changes and BC breaks in Naja 3.0 is live (in Czech 🇨🇿)