0.1.0

This is a big release. Apologies for so many breaking changes; once the namespacing work (below) began, many other changes had to follow.

Version 0.1.0

Since this release has more disruptive changes than usual, we're giving it a minor version number bump instead of just incrementing the patch version. Until Origami is ready for version 1.0, any given release may contain breaking changes. Instead of changing the major version number (as would be typical) to indicate breaking changes, we'll update the minor version number instead.

To the extent that was practical, Origami should throw meaningful errors if your code hits a breaking change. (Exception: see the breaking change below for YAML/JSON files.)

Namespaces

With this release, Origami builtin functions are grouped into namespaces:

• All builtins now belong to a namespace. The Builtins area lists all namespaces and the functions they contain.
• You can always refer to the builtin by a full name that includes the namespace. E.g., the full name for the map builtin is tree:map.
• Some builtins behave like protocols. For example, where you might have written @files/build previously, you would now write files:build. Along the same lines, @js is now js:, and @node is now node:.
• You can also refer to a builtin by a shorthand that omits the namespace: map.
• The @ prefix is now deprecated for all functions. For now you should see a deprecation warning that includes the new full and shorthand name of the function. Eventually the @ forms will be removed.
• The @ is still preserved in the name of the @text in documents. @text isn't a builtin, just a property name that's unlikely to come up in document metadata.
• Some builtins have been renamed for consistency. E.g., the previous @clean command is now clear to match the Tree.clear() method. That method is intended to match standard web APIs like Storage.prototype.clear().

Why namespaces were necessary:

• Manage complexity. Origami already contains roughly 150 builtin functions and will keep growing from here.
• Allow for the eventual possibility of using Origami without the full builtin set. Origami can be used for more than making websites, so at some point we'd like to support the possibility of installing the sets of builtins one actually needs for the task at hand.
• Factor out dev tools. A particular example of the above point: it'd be good if you could exclude the dev tools if one is installing Origami on a production machine (e.g., Netlify).
• Allow for the possibility of having official or unofficial Origami extensions someday define new features under a custom namespace.
• Group builtins for documentation purposes.
• Tighten parsing behavior for builtins (see below).

Recommendations:

1. Before upgrading, you may want to take a snapshot of your current build to establish a baseline before the upgrade. See the changes builtin for details on that strategy.
2. After upgrading to version 0.1.0, run npm run build to see all warnings and errors.
3. Search your .ori files for @.
4. Change @files to files:, @js to js:, @node to node:, and @package to package:.
5. Change @clean to clear.
6. Remove the @ from all other builtins, but leave it in place for @text, package names that begin with a @ organization, TypeScript/jsDoc comments, etc.
7. Search your package.json scripts for @ as well.
8. In package.json, change watch scripts from debug site.ori to debug src/site.ori. See the watch change below.

Help

The CLI help system has been overhauled:

• ori help — display a list of available namespaces
• ori help:<namespace — display short descriptions of the commands in that namespace, including a link to the namespace's online help.
• ori help<command> — display a short description of the command, including a link to the command's online help.

You can lookup the namespace for a command like if with ori help:if. This will show that if is in the calc: namespace, so its full form is calc:if.

CLI suggestions

The CLI tries to help with this transition, and with Origami more generally, by providing suggestions if a command can't be found. This can be useful in identifying typos.

Parsing

The Origami parser now recognizes a name that ends in a colon as a namespace.

Previously the @ prefix was used to identify builtins, because a @ character rarely comes up in filenames or object keys.

However, using a : colon to identify the top-level namespaces in Origami provides a much stricter guarantee. It's physically impossible to create a Windows file name that includes a colon, and even on macOS it's difficult to accidentally include a colon in a name. It's also cumbersome (but not impossible) to include a colon in a JavaScript object key or a YAML key. This means that using a colon to identify a namespace is much, much less likely to result in accidental name collisions than using @.

Update VS Code extension

The Origami VS Code extension now recognizes namespaces like tree: as well as builtin shorthand functions like map().

Breaking changes to new:

The syntax of the new: protocol has changed.

// Old
new:@js/Date("2025-07-04")

// Updated to use js: namespace
new:(js:Date)("2025-07-04")

// Or use the shorthand
new:Date("2025-07-04")

Breaking change in trees from YAML/JSON files

The data object parsed from a YAML or JSON file is now a deep object tree. This means that keys for subobjects will now end in trailing slashes.

There's no way for Origami to know whether this will be a breaking change for your project, so it can't throw an error if it thinks your code needs to be updated. You should review all cases where, for example, you are mapping over YAML/JSON data with expressions like map(data.yaml, (value, key) => ...) as the key may now end in a trailing slash.

Breaking change mapping extensions

The extension option of the map builtin (previously @map) used to allow extensions without a dot prefix: "md->html". A dot is now required: ".md->.html".

If you are mapping keys that end in trailing slashes, you can now use a slash as if it were an extension. For example, "/→.json" would map a folder key like “data/” to “data.json”.

Breaking change in watch behavior

The @watch builtin previously ran its watch expression inside the tree being watched. A common invocation in package.json was:

    "start": "ori @serve @watch src, =@debug site.ori"

This would run site.ori, which would generally be found inside the src folder.

As part of a general simplification, Origami now evaluates all expressions in the context where they were defined. In the case of an npm run command, the script will be run in the project's root folder, so a script like start here will evaluate all expressions in the context of the root folder.

This means that, along with updating @ builtins, you must update such package.json entries to:

    "start": "ori serve watch src, =debug src/site.ori"

This will allow the watch builtin to find the src/site.ori file.

Deprecations of Fn functions

Previous releases offered functional forms of builtins with names ending in Fn, like @mapFn. Given that Origami offers a shorthand lambda form, these functional forms didn't save very much typing: you can get @mapFn(…) with =@map(_, …). Having to maintain functional forms incurred some conceptual and maintenance overhead, and in the long run didn't seem worthwhile. During the namespace reorg (above), the Fn variations were deprecated.