From f72d186df717286a84d6f4ba5273a7375069d67b Mon Sep 17 00:00:00 2001 From: Bushuo Date: Sat, 21 Feb 2026 18:04:57 +0100 Subject: [PATCH] docs: for @notUndefined decorator and its usage --- markdown-pages/docs/manual/module.mdx | 6 ++++ .../syntax-lookup/decorator_non_undefined.mdx | 35 +++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 markdown-pages/syntax-lookup/decorator_non_undefined.mdx diff --git a/markdown-pages/docs/manual/module.mdx b/markdown-pages/docs/manual/module.mdx index 266c46575..b1f0ed208 100644 --- a/markdown-pages/docs/manual/module.mdx +++ b/markdown-pages/docs/manual/module.mdx @@ -350,6 +350,12 @@ It's also useful to hide the underlying type as an implementation detail others can't rely on. If you ask what the type of `Company.profession` is, instead of exposing the variant, it'll only tell you "it's `Company.profession`". +This also means that the compiler can't make assumptions about the type. +In certain cases, when working with abstract types and `option` for example, the compiler doesn't know whether +the abstract type can be the JavaScript value `undefined` or not. This can lead to less optimal code being generated. +For this reason, you can use the `@notUndefined` decorator to tell the compiler that the abstract type can never be `undefined` +(use with caution and see the `@notUndefined` decorator documentation for more details and caveats). + ### Extending module signatures Like modules themselves, module signatures can also be extended by other module signatures using `include`. Again, **heavily discouraged**: diff --git a/markdown-pages/syntax-lookup/decorator_non_undefined.mdx b/markdown-pages/syntax-lookup/decorator_non_undefined.mdx new file mode 100644 index 000000000..d9fff2822 --- /dev/null +++ b/markdown-pages/syntax-lookup/decorator_non_undefined.mdx @@ -0,0 +1,35 @@ +--- +id: "not-undefined-decorator" +keywords: ["not", "undefined", "decorator"] +name: "@notUndefined" +summary: "This is the `@notUndefined` decorator." +category: "decorators" +--- + +**Since 12.0** + +Use `@notUndefined` on an abstract type to tell the compiler that +values of that type can never be JavaScript `undefined`. + +With `@notUndefined`, the compiler can treat the abstract type as never-undefined for optimization purposes (notably option representation and code generation decisions). + +> **Note:** This attribute is a compiler contract. If `undefined` can flow into that type through unsafe interop or casts, generated code assumptions can be broken. Use it only when this guarantee is actually true. + +### Example + + + +```res +@notUndefined +type t +``` + +```js +// Empty output +``` + + + +### References + +- [Signatures](../docs/manual/module.mdx#signatures)