0.5.5

This is a minor release for Origami language users, but includes breaking changes for JavaScript users directly calling functions in the async-tree library.

The focus of this release in internal refactoring to align the functions in the async-tree library so that they exactly match what's visible to Origami programs as the Tree namespace. Previously, there were two implementations of many operations like Tree.map: a lightweight one in the async-tree library, and a more feature-rich one in the main origami package. This release converges those implementations and moves all tree operations to the async-tree library.

Tree builtins

All builtins should generally work the same as before. Reviewing and updating this code revealed that a number of seldom-used functions may no longer be necessary. These have been deprecated:

• Tree.concat is deprecated. For a while it's been essentially the same as Tree.deepText but due to an oversight was never removed. Use Tree.deepText instead.
• Tree.defineds is deprecated because I'm not aware of a use for it. If you're using it, let me know.
• Tree.fromFn has been generalized and renamed to Tree.withKeys.
• Tree.setDeep has been deprecated because it turns out to have the same behavior as Tree.assign; use that instead.
• Tree.remove has been renamed to Tree.delete for consistency with JavaScript methods like Map.prototype.delete.

async-tree API changes

This release also includes some non-trivial changes to the JavaScript async-tree library, although few people are using that library directly. None of these changes should have visible effects at the Origami language level.

• All tree functions (map, reverse, sort, etc.) are now async.
• The async-tree package now exports all operations as a single Tree. collection, rather than as individually named exports.
• The map operation now calls the key function option with an initial value. The key function's parameters were previously (sourceKey, tree) and are now (sourceValue, sourceKey, tree). The signature now matches what has always been exposed to Origami programs.
• The origami package no longer exports any tree operations; use the async-tree package directly instead.

Experimental Tree.mapExtension method

The ability of Tree.map to map file extensions is extremely useful, but the API design is bad. The extension option conflicts with use of the key or inverseKey options, which are used to provide finer-grained control over key mapping. In fact, under the hood, setting extension actually generates key and inverseKey functions for you.

Whenever a method has multiple parameters that can't work together, that's a signal that the method is trying to do too many things.

The proposed solution to this problem is to separate the extension-mapping behavior into a new builtin, Tree.mapExtension.

// Existing syntax
Tree.map(posts, { extension: ".md→.html", value: page.ori })

// Proposed
Tree.mapExtension(posts, ".md→.html", page.ori) // last param is the value function
Tree.mapExtension(posts, ".md→.html", { deep: true, value: page.ori }) // if you have more options

This new Tree.mapExtension builtin is available in this release, but for the time being is not yet included in the documentation.

Give this a try and share your thoughts in the Origami chat. If this design feels good, this would become the official way of mapping extensions, and the extension option in Tree.map would be retired.

Update to extensions

The changes to async-tree required updating the following Origami extensions:

• esbuild
• json-schema
• handlebars

If you're using those extensions, update your package.json to pick up the latest version.