Upgrading to 0.2

Atscript 0.2.0 changes the generated runtime code and tightens a few compile rules. Most projects only need step 1. Each item links to the page that documents the current behaviour.

1. Regenerate every generated module

Modules generated by atscript 0.1.110 or earlier do not load on the 0.2 runtime: they call builder methods it no longer has (refTo, cloneRefProp). Rebuild your own .as output and every package you depend on that ships generated .as code. There is no compatibility mode. See Packages Built with an Earlier Version.

Code that builds types by hand uses defineAnnotatedType().ref(Target) (or .ref(Target, ['field']) for a field) instead of refTo.

2. Fix the new compile errors

0.1.x still generated JavaScript for a file that had error diagnostics. 0.2 refuses: any error in a file, including a plugin annotation error such as an argument outside its allowed values, fails code generation for that file. Fix every error your editor or build reports.

Schemas that compiled on 0.1.x can fail on 0.2 in these cases:

Error	What to do
Unknown member "…" on a type path through a union	A typo that 0.1.x accepted silently (M.work.hh with type M = Job | null). Fix the path. See Type Paths
"…" names phantom and non-phantom fields through a union	A type path reaches a phantom field on one branch and a data field on another. Make the branches agree, or point at one branch
An interface can't extend a union; use a merge	Write type Post = Content & { … } instead of interface Post extends Content. See Interface Extends
Circular chain reference "…": it resolves to itself	A merged or inherited field typed by a path back to itself; 0.1.x overflowed the stack. Give the field its real type
A block's path can't cross the type path it splits.	Put the annotate block on the union instead of one branch. See Type Paths

A production build now also loads every generated module once and fails when one throws. That failure is a code generation bug to report, not a schema error. See Import cycles need native ES modules for where the check runs and the loadCheck option.

3. Check behaviour changes

• unknownProps: 'strip' deletes keys only when validation passes. A failed validation, a rejected union branch, or a plugin's ctx.validateAnnotatedType(...) call that returns false strips nothing. See unknownProps.
• Raw writes to a type tree need invalidateCompiledValidators() for the interpreted validator and every metadata reader too, not only compiled checks: swapping a node's map (node.metadata = X) or editing a stored value in place. Writes through set / delete / annotate() are tracked as before. See Runtime Metadata.
• .d.ts type paths are written as TAtscriptField<T, "k"> steps (a type-only export of @atscript/typescript/utils) instead of T["k"], so a path through a union or an optional property type-checks. See Type paths.
• A bare alias is the same object at runtime. export type X = Y is Y itself; an alias with annotations of its own, or an annotate Y as X copy, is a separate node that reads through Y. See The Annotated Type.
• An intersection of object types is one object type at runtime (the compiler writes the merge). See How a merge is built.

4. Plugin authors

• doc.unwindType() / doc.unwindRef() on a type path through a union return the field, or fields when the path names several. See doc.unwindType.
• resolveFieldRefAt() and resolveQueryFieldRef() return undefined when a path names several fields; resolveFieldRefsAt() returns all of them.
• render(doc, format, options) receives the render options; a plugin wrapping another plugin's render must pass them on. See render().

Upgrading from an older 0.1.x release as well? The validation tightenings of 0.1.100–0.1.104 (non-finite numbers, zero bounds, nullable constraints, string.required) are listed with upgrade notes in the Validation Reference.