v13.0.0 Prerelease (9)

Breaking changes from v12.x.x (Updated)

1. The schema for validation errors is changing

When argmts passed in to a machine fail runtime validation, the Error instance that is passed through the error exit has a different format. Instead of the machine ID (which may or may not have always existed), it provides a reference to the machine instance. This allows other toolchain modules like machine-as-action and machine-as-script to identify which machine caused a validation error. (Previously, it was impossible to tell whether a validation error came from the top-level machine being run, or from any deeply nested machine that happened to be called within its implementation)

2. Unrecognized callbacks are no longer allowed

Unrecognized (aka "bonus") callbacks passed in to .exec() at runtime are no longer passed through to the machine's fn in the exits argument. This was never documented behavior, and it never should have worked this way, but just in case your app or machines were relying on it, we're including it in this major version instead of releasing it in a patch.

3. "Unsafe mode" (unsafe()) is deprecated.

While some aspects of "unsafe" mode may continue to work, it is no longer supported and will be completely removed in upcoming patch releases. The same features will likely return in a future version of the machine runner, and in the mean time, expect to see a few different experimental features which accomplish the same thing but with more fine-grained control.

4. Improvements & breaking changes to built-in caching support.

If you are using .cache(), there are a few things to watch out for in this release:

• The cache model you provide in .cache() is now completely machine agnostic. It now generate its hashes using only argins (it no longer uses the machine's identity in the hash). This means you'll want to use separate Cache models for each type of machine whose results you're caching. (Technically you don't have to do this, but it's our recommended approach.)
• As far as the cache is concerned, key order in dictionaries does not matter. (This was true before as well, but it was never documented.)
• The provided Cache model will now build an md5 hash using vanilla crypto (rather than object-hash). Note that, if you are using a durable cache database, after upgrading machine, all of your existing Cache records will be considered expired!
• Only JSON-serializable arguments can be safely cached. To guarantee that, when the machine runner calculates the argins hash, it now excludes argins provided for inputs with === or -> in their examples (top-level OR nested).

5. .exec()-ing a machine without configuring any kind of error handling\

If a machine is executed with .exec() without providing the mandatory minimum error handling, it now refuses to run, instead synchronously throwing an Error with code === 'E_NO_ERROR_CALLBACK_CONFIGURED'.

Calls to .execSync() are unaffected, since try/catch-ing is left completely up to userland code.

6. The E_TIMEOUT error code is now E_MACHINE_TIMEOUT

Timeout errors now have code === 'E_MACHINE_TIMEOUT'. This is partially for consistency with the updated error code for argin validation errors, but also to improve the encapsulation of errors. The priority is errors which are sometimes useful in userland, but realistically this should be considered any time we set a code. Expect to see more arcane, undocumented errors get namespaced error codes in future patch releases.