diff --git a/404.html b/404.html new file mode 100644 index 000000000..99ced6733 --- /dev/null +++ b/404.html @@ -0,0 +1,30 @@ + + + + + + The AssemblyScript Book + + + + + + + + + + + + + + + + + + +

404

That's a Four-Oh-Four.
+ Take me home. +
+ + + diff --git a/CNAME b/CNAME new file mode 100644 index 000000000..c4945bd0f --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +www.assemblyscript.org diff --git a/assets/css/0.styles.6b61c7e6.css b/assets/css/0.styles.6b61c7e6.css new file mode 100644 index 000000000..de728ca3e --- /dev/null +++ b/assets/css/0.styles.6b61c7e6.css @@ -0,0 +1 @@ +code[class*=language-],pre[class*=language-]{color:#ccc;background:none;font-family:Consolas,Monaco,Andale Mono,Ubuntu Mono,monospace;font-size:1em;word-wrap:normal;line-height:1.5}:not(pre)>code[class*=language-],pre[class*=language-]{background:#2d2d2d}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal}.token.block-comment,.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#999}.token.punctuation{color:#ccc}.token.attr-name,.token.deleted,.token.namespace,.token.tag{color:#e2777a}.token.function-name{color:#6196cc}.token.boolean,.token.function,.token.number{color:#f08d49}.token.class-name,.token.constant,.token.property,.token.symbol{color:#f8c555}.token.atrule,.token.builtin,.token.important,.token.keyword,.token.selector{color:#cc99cd}.token.attr-value,.token.char,.token.regex,.token.string,.token.variable{color:#7ec699}.token.entity,.token.operator,.token.url{color:#67cdcc}.token.entity{cursor:help}.token.inserted{color:green}code[class*=language-],pre[class*=language-]{color:#393a34;font-family:Consolas,Bitstream Vera Sans Mono,Courier New,Courier,monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;font-size:.9em;line-height:1.2em;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-ms-hyphens:none;hyphens:none}pre>code[class*=language-]{font-size:1em}code[class*=language-]::-moz-selection,code[class*=language-] ::-moz-selection,pre[class*=language-]::-moz-selection,pre[class*=language-] ::-moz-selection{background:#c1def1}code[class*=language-]::selection,code[class*=language-] ::selection,pre[class*=language-]::selection,pre[class*=language-] ::selection{background:#c1def1}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto;border:1px solid #ddd;background-color:#fff}:not(pre)>code[class*=language-]{padding:1px .2em;background:#f8f8f8;border:1px solid #ddd}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:green;font-style:italic}.token.namespace{opacity:.7}.token.string{color:#a31515}.token.operator,.token.punctuation{color:#393a34}.token.boolean,.token.constant,.token.inserted,.token.number,.token.symbol,.token.url,.token.variable{color:#36acaa}.language-autohotkey .token.selector,.language-json .token.boolean,.language-json .token.number,.token.atrule,.token.attr-value,.token.keyword,code[class*=language-css]{color:#00f}.token.function{color:#393a34}.language-autohotkey .token.tag,.token.deleted{color:#9a050f}.language-autohotkey .token.keyword,.token.selector{color:#00009f}.token.important{color:#e90}.token.bold,.token.important{font-weight:700}.token.italic{font-style:italic}.language-json .token.property,.token.class-name{color:#2b91af}.token.selector,.token.tag{color:maroon}.token.attr-name,.token.entity,.token.property,.token.regex{color:red}.token.directive.tag .tag{background:#ff0;color:#393a34}.line-numbers.line-numbers .line-numbers-rows{border-right-color:#a5a5a5}.line-numbers .line-numbers-rows>span:before{color:#2b91af}.line-highlight.line-highlight{background:rgba(193,222,241,.2);background:linear-gradient(90deg,rgba(193,222,241,.2) 70%,rgba(221,222,241,0))}.theme-default-content code{color:#476582;padding:.25rem .5rem;margin:0;font-size:.85em;background-color:rgba(27,31,35,.05);border-radius:3px}.theme-default-content code .token.deleted{color:#ec5975}.theme-default-content code .token.inserted{color:#007acc}.theme-default-content pre,.theme-default-content pre[class*=language-]{line-height:1.4;padding:1.25rem 1.5rem;margin:.85rem 0;background-color:#fff;border-radius:6px;overflow:auto}.theme-default-content pre[class*=language-] code,.theme-default-content pre code{color:#fff;padding:0;background-color:transparent;border-radius:0}div[class*=language-]{position:relative;background-color:#fff;border-radius:6px}div[class*=language-] .highlight-lines{-webkit-user-select:none;user-select:none;padding-top:1.3rem;position:absolute;top:0;left:0;width:100%;line-height:1.4}div[class*=language-] .highlight-lines .highlighted{background-color:rgba(0,0,0,.66)}div[class*=language-] pre,div[class*=language-] pre[class*=language-]{background:transparent;position:relative;z-index:1}div[class*=language-]:before{position:absolute;z-index:3;top:.8em;right:1em;font-size:.75rem;color:hsla(0,0%,100%,.4)}div[class*=language-]:not(.line-numbers-mode) .line-numbers-wrapper{display:none}div[class*=language-].line-numbers-mode .highlight-lines .highlighted{position:relative}div[class*=language-].line-numbers-mode .highlight-lines .highlighted:before{content:" ";position:absolute;z-index:3;left:0;top:0;display:block;width:3.5rem;height:100%;background-color:rgba(0,0,0,.66)}div[class*=language-].line-numbers-mode pre{padding-left:4.5rem;vertical-align:middle}div[class*=language-].line-numbers-mode .line-numbers-wrapper{position:absolute;top:0;width:3.5rem;text-align:center;color:hsla(0,0%,100%,.3);padding:1.25rem 0;line-height:1.4}div[class*=language-].line-numbers-mode .line-numbers-wrapper br{-webkit-user-select:none;user-select:none}div[class*=language-].line-numbers-mode .line-numbers-wrapper .line-number{position:relative;z-index:4;-webkit-user-select:none;user-select:none;font-size:.85em}div[class*=language-].line-numbers-mode:after{content:"";position:absolute;z-index:2;top:0;left:0;width:3.5rem;height:100%;border-radius:6px 0 0 6px;border-right:1px solid rgba(0,0,0,.66);background-color:#fff}div[class~=language-js]:before{content:"js"}div[class~=language-ts]:before{content:"ts"}div[class~=language-html]:before{content:"html"}div[class~=language-md]:before{content:"md"}div[class~=language-vue]:before{content:"vue"}div[class~=language-css]:before{content:"css"}div[class~=language-sass]:before{content:"sass"}div[class~=language-scss]:before{content:"scss"}div[class~=language-less]:before{content:"less"}div[class~=language-stylus]:before{content:"stylus"}div[class~=language-go]:before{content:"go"}div[class~=language-java]:before{content:"java"}div[class~=language-c]:before{content:"c"}div[class~=language-sh]:before{content:"sh"}div[class~=language-yaml]:before{content:"yaml"}div[class~=language-py]:before{content:"py"}div[class~=language-docker]:before{content:"docker"}div[class~=language-dockerfile]:before{content:"dockerfile"}div[class~=language-makefile]:before{content:"makefile"}div[class~=language-javascript]:before{content:"js"}div[class~=language-typescript]:before{content:"ts"}div[class~=language-markup]:before{content:"html"}div[class~=language-markdown]:before{content:"md"}div[class~=language-json]:before{content:"json"}div[class~=language-ruby]:before{content:"rb"}div[class~=language-python]:before{content:"py"}div[class~=language-bash]:before{content:"sh"}div[class~=language-php]:before{content:"php"}.custom-block .custom-block-title{font-weight:600;margin-bottom:-.4rem}.custom-block.danger,.custom-block.tip,.custom-block.warning{padding:.1rem 1.5rem;border-left-width:.5rem;border-left-style:solid;margin:1rem 0}.custom-block.tip{background-color:#f3f5f7;border-color:#42b983}.custom-block.warning{background-color:rgba(255,229,100,.3);border-color:#e7c000;color:#6b5900}.custom-block.warning .custom-block-title{color:#b29400}.custom-block.warning a{color:#2c3e50}.custom-block.danger{background-color:#ffe6e6;border-color:#c00;color:#4d0000}.custom-block.danger .custom-block-title{color:#900}.custom-block.danger a{color:#2c3e50}.custom-block.details{display:block;position:relative;border-radius:2px;margin:1.6em 0;padding:1.6em;background-color:#eee}.custom-block.details h4{margin-top:0}.custom-block.details figure:last-child,.custom-block.details p:last-child{margin-bottom:0;padding-bottom:0}.custom-block.details summary{outline:none;cursor:pointer}.arrow{display:inline-block;width:0;height:0}.arrow.up{border-bottom:6px solid #ccc}.arrow.down,.arrow.up{border-left:4px solid transparent;border-right:4px solid transparent}.arrow.down{border-top:6px solid #ccc}.arrow.right{border-left:6px solid #ccc}.arrow.left,.arrow.right{border-top:4px solid transparent;border-bottom:4px solid transparent}.arrow.left{border-right:6px solid #ccc}.theme-default-content:not(.custom){max-width:960px;margin:0 auto;padding:2rem 2.5rem}@media (max-width:959px){.theme-default-content:not(.custom){padding:2rem}}@media (max-width:419px){.theme-default-content:not(.custom){padding:1.5rem}}.table-of-contents .badge{vertical-align:middle}body,html{padding:0;margin:0;background-color:#fff}body{font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-size:16px;color:#2c3e50}.page{padding-left:20rem}.navbar{z-index:20;right:0;height:4.6rem;background-color:#fff;box-sizing:border-box;border-bottom:1px solid #eaecef}.navbar,.sidebar-mask{position:fixed;top:0;left:0}.sidebar-mask{z-index:9;width:100vw;height:100vh;display:none}.sidebar{font-size:16px;background-color:#fff;width:20rem;position:fixed;z-index:10;margin:0;top:4.6rem;left:0;bottom:0;box-sizing:border-box;border-right:1px solid #eaecef;overflow-y:auto}.theme-default-content:not(.custom)>:first-child{margin-top:4.6rem}.theme-default-content:not(.custom) a:hover{text-decoration:underline}.theme-default-content:not(.custom) p.demo{padding:1rem 1.5rem;border:1px solid #ddd;border-radius:4px}.theme-default-content:not(.custom) img{max-width:100%}.theme-default-content.custom{padding:0;margin:0}.theme-default-content.custom img{max-width:100%}a{font-weight:500;text-decoration:none}a,p a code{color:#007acc}p a code{font-weight:400}kbd{background:#eee;border:.15rem solid #ddd;border-bottom:.25rem solid #ddd;border-radius:.15rem;padding:0 .15em}blockquote{font-size:1rem;color:#999;border-left:.2rem solid #dfe2e5;margin:1rem 0;padding:.25rem 0 .25rem 1rem}blockquote>p{margin:0}ol,ul{padding-left:1.2em}strong{font-weight:600}h1,h2,h3,h4,h5,h6{font-weight:600;line-height:1.25}.theme-default-content:not(.custom)>h1,.theme-default-content:not(.custom)>h2,.theme-default-content:not(.custom)>h3,.theme-default-content:not(.custom)>h4,.theme-default-content:not(.custom)>h5,.theme-default-content:not(.custom)>h6{margin-top:-4.1rem;padding-top:5.6rem;margin-bottom:0}.theme-default-content:not(.custom)>h1:first-child,.theme-default-content:not(.custom)>h2:first-child,.theme-default-content:not(.custom)>h3:first-child,.theme-default-content:not(.custom)>h4:first-child,.theme-default-content:not(.custom)>h5:first-child,.theme-default-content:not(.custom)>h6:first-child{margin-top:-1.5rem;margin-bottom:1rem}.theme-default-content:not(.custom)>h1:first-child+.custom-block,.theme-default-content:not(.custom)>h1:first-child+p,.theme-default-content:not(.custom)>h1:first-child+pre,.theme-default-content:not(.custom)>h2:first-child+.custom-block,.theme-default-content:not(.custom)>h2:first-child+p,.theme-default-content:not(.custom)>h2:first-child+pre,.theme-default-content:not(.custom)>h3:first-child+.custom-block,.theme-default-content:not(.custom)>h3:first-child+p,.theme-default-content:not(.custom)>h3:first-child+pre,.theme-default-content:not(.custom)>h4:first-child+.custom-block,.theme-default-content:not(.custom)>h4:first-child+p,.theme-default-content:not(.custom)>h4:first-child+pre,.theme-default-content:not(.custom)>h5:first-child+.custom-block,.theme-default-content:not(.custom)>h5:first-child+p,.theme-default-content:not(.custom)>h5:first-child+pre,.theme-default-content:not(.custom)>h6:first-child+.custom-block,.theme-default-content:not(.custom)>h6:first-child+p,.theme-default-content:not(.custom)>h6:first-child+pre{margin-top:2rem}h1:focus .header-anchor,h1:hover .header-anchor,h2:focus .header-anchor,h2:hover .header-anchor,h3:focus .header-anchor,h3:hover .header-anchor,h4:focus .header-anchor,h4:hover .header-anchor,h5:focus .header-anchor,h5:hover .header-anchor,h6:focus .header-anchor,h6:hover .header-anchor{opacity:1}h1{font-size:2.2rem}h2{font-size:1.65rem;padding-bottom:.3rem;border-bottom:1px solid #eaecef}h3{font-size:1.35rem}a.header-anchor{font-size:.85em;float:left;margin-left:-.87em;padding-right:.23em;margin-top:.125em;opacity:0}a.header-anchor:focus,a.header-anchor:hover{text-decoration:none}.line-number,code,kbd{font-family:source-code-pro,Menlo,Monaco,Consolas,Courier New,monospace}ol,p,ul{line-height:1.7}hr{border:0;border-top:1px solid #eaecef}table{border-collapse:collapse;margin:1rem 0;display:block;overflow-x:auto}tr{border-top:1px solid #dfe2e5}tr:nth-child(2n){background-color:#f6f8fa}td,th{border:1px solid #dfe2e5;padding:.6em 1em}.theme-container.sidebar-open .sidebar-mask{display:block}.theme-container.no-navbar .theme-default-content:not(.custom)>h1,.theme-container.no-navbar h2,.theme-container.no-navbar h3,.theme-container.no-navbar h4,.theme-container.no-navbar h5,.theme-container.no-navbar h6{margin-top:1.5rem;padding-top:0}.theme-container.no-navbar .sidebar{top:0}@media (min-width:720px){.theme-container.no-sidebar .sidebar{display:none}.theme-container.no-sidebar .page{padding-left:0}}@media (max-width:959px){.sidebar{font-size:15px;width:16.4rem}.page{padding-left:16.4rem}}@media (max-width:719px){.sidebar{top:0;padding-top:4.6rem;transform:translateX(-100%);transition:transform .2s ease}.page{padding-left:0}.theme-container.sidebar-open .sidebar{transform:translateX(0)}.theme-container.no-navbar .sidebar{padding-top:0}}@media (max-width:419px){h1{font-size:1.9rem}.theme-default-content div[class*=language-]{margin:.85rem -1.5rem;border-radius:0}}.sidebar::-webkit-scrollbar{width:.3em}.sidebar::-webkit-scrollbar-track{background-color:#eaecef}.sidebar::-webkit-scrollbar-thumb{background-color:#007acc}.sidebar-group:is(.collapsable) .sidebar-heading{opacity:1!important;cursor:pointer!important}.nav-dropdown .dropdown-item h4{margin:.45rem 0 .2rem!important}.token.builtin{color:#36acaa}.token.comment{font-style:normal}.theme-default-content a code{color:#007acc}.theme-default-content pre[class*=language-] code,.theme-default-content pre code{color:#222;color:#476582;font-size:1em}div[class*=language-]:before{color:#fff;background:#bbb;padding:1px 4px 3px 5px}div[class~=language-ts]:before,div[class~=language-typescript]:before{color:#fff;background:#007acc}div[class~=language-javascript]:before,div[class~=language-js]:before{color:#323330;background:#f0db4f}div[class~=language-bash]:before,div[class~=language-sh]:before{color:#fff;background:#000}div[class~=language-wat]:before,div[class~=language-webassembly]:before{color:#fff;background:#654ff0}div[class~=language-html]:before{color:#fff;background:#e44d26}div[class~=language-c]:before{color:#fff;background:#3949ab;padding-right:6px;padding-left:7px}.theme-default-content li div[class*=language-]:first-child pre[class*=language-]{background:#fff;border:0;padding:0;font-size:1.1em}.theme-default-content li div[class*=language-]:first-child:before{display:none}img.engine{position:relative;top:3px}details summary{cursor:pointer}details summary::marker{color:#ccc}details summary:hover{color:#007acc}details table td{font-family:source-code-pro,Menlo,Monaco,Consolas,Courier New,monospace}#nprogress{pointer-events:none}#nprogress .bar{background:#007acc;position:fixed;z-index:1031;top:0;left:0;width:100%;height:2px}#nprogress .peg{display:block;position:absolute;right:0;width:100px;height:100%;box-shadow:0 0 10px #007acc,0 0 5px #007acc;opacity:1;transform:rotate(3deg) translateY(-4px)}#nprogress .spinner{display:block;position:fixed;z-index:1031;top:15px;right:15px}#nprogress .spinner-icon{width:18px;height:18px;box-sizing:border-box;border-color:#007acc transparent transparent #007acc;border-style:solid;border-width:2px;border-radius:50%;-webkit-animation:nprogress-spinner .4s linear infinite;animation:nprogress-spinner .4s linear infinite}.nprogress-custom-parent{overflow:hidden;position:relative}.nprogress-custom-parent #nprogress .bar,.nprogress-custom-parent #nprogress .spinner{position:absolute}@-webkit-keyframes nprogress-spinner{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}@keyframes nprogress-spinner{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}.icon.outbound{color:#aaa;display:inline-block;vertical-align:middle;position:relative;top:-1px}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border-width:0}.home{padding:4.6rem 2rem 0;max-width:960px;margin:0 auto;display:block}.home .hero{text-align:center}.home .hero img{max-width:100%;max-height:280px;display:block;margin:3rem auto 1.5rem}.home .hero h1{font-size:3rem}.home .hero .action,.home .hero .description,.home .hero h1{margin:1.8rem auto}.home .hero .description{max-width:35rem;font-size:1.6rem;line-height:1.3;color:#6a8bad}.home .hero .action-button{display:inline-block;font-size:1.2rem;color:#fff;background-color:#007acc;padding:.8rem 1.6rem;border-radius:4px;transition:background-color .1s ease;box-sizing:border-box;border-bottom:1px solid #006eb8}.home .hero .action-button:hover{background-color:#008ceb}.home .features{border-top:1px solid #eaecef;padding:1.2rem 0;margin-top:2.5rem;display:flex;flex-wrap:wrap;align-items:flex-start;align-content:stretch;justify-content:space-between}.home .feature{flex-grow:1;flex-basis:30%;max-width:30%}.home .feature h2{font-size:1.4rem;font-weight:500;border-bottom:none;padding-bottom:0;color:#3a5169}.home .feature p{color:#4e6e8e}.home .footer{padding:2.5rem;border-top:1px solid #eaecef;text-align:center;color:#4e6e8e}@media (max-width:719px){.home .features{flex-direction:column}.home .feature{max-width:100%;padding:0 2.5rem}}@media (max-width:419px){.home{padding-left:1.5rem;padding-right:1.5rem}.home .hero img{max-height:210px;margin:2rem auto 1.2rem}.home .hero h1{font-size:2rem}.home .hero .action,.home .hero .description,.home .hero h1{margin:1.2rem auto}.home .hero .description{font-size:1.2rem}.home .hero .action-button{font-size:1rem;padding:.6rem 1.2rem}.home .feature h2{font-size:1.25rem}}.algolia-search-wrapper>span{vertical-align:middle}.algolia-search-wrapper .algolia-autocomplete{line-height:normal}.algolia-search-wrapper .algolia-autocomplete .ds-dropdown-menu{background-color:#fff;border:1px solid #999;border-radius:4px;font-size:16px;margin:6px 0 0;padding:4px;text-align:left}.algolia-search-wrapper .algolia-autocomplete .ds-dropdown-menu:before{border-color:#999}.algolia-search-wrapper .algolia-autocomplete .ds-dropdown-menu [class*=ds-dataset-]{border:none;padding:0}.algolia-search-wrapper .algolia-autocomplete .ds-dropdown-menu .ds-suggestions{margin-top:0}.algolia-search-wrapper .algolia-autocomplete .ds-dropdown-menu .ds-suggestion{border-bottom:1px solid #eaecef}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion--highlight{color:#2c815b}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion{border-color:#eaecef;padding:0}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--category-header{padding:5px 10px;margin-top:0;background:#007acc;color:#fff;font-weight:600}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--category-header .algolia-docsearch-suggestion--highlight{background:hsla(0,0%,100%,.6)}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--wrapper{padding:0}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--title{font-weight:600;margin-bottom:0;color:#2c3e50}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column{vertical-align:top;padding:5px 7px 5px 5px;border-color:#eaecef;background:#f1f3f5}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column:after{display:none}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column-text{color:#555}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-footer{border-color:#eaecef}.algolia-search-wrapper .algolia-autocomplete .ds-cursor .algolia-docsearch-suggestion--content{background-color:#e7edf3!important;color:#2c3e50}@media (min-width:719px){.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column{float:none;width:150px;min-width:150px;display:table-cell}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--content{float:none;display:table-cell;width:100%;vertical-align:top}.algolia-search-wrapper .algolia-autocomplete .algolia-docsearch-suggestion .ds-dropdown-menu{min-width:515px!important}}@media (max-width:719px){.algolia-search-wrapper .ds-dropdown-menu{min-width:calc(100vw - 4rem)!important;max-width:calc(100vw - 4rem)!important}.algolia-search-wrapper .algolia-docsearch-suggestion--wrapper{padding:5px 7px 5px 5px!important}.algolia-search-wrapper .algolia-docsearch-suggestion--subcategory-column{padding:0!important;background:#fff!important}.algolia-search-wrapper .algolia-docsearch-suggestion--subcategory-column-text:after{content:" > ";font-size:10px;line-height:14.4px;display:inline-block;width:5px;margin:-3px 3px 0;vertical-align:middle}}.search-box{display:inline-block;position:relative;margin-right:1rem}.search-box input{cursor:text;width:10rem;height:2rem;color:#4e6e8e;display:inline-block;border:1px solid #cfd4db;border-radius:2rem;font-size:.9rem;line-height:2rem;padding:0 .5rem 0 2rem;outline:none;transition:all .2s ease;background:#fff url(/assets/img/search.83621669.svg) .6rem .5rem no-repeat;background-size:1rem}.search-box input:focus{cursor:auto;border-color:#007acc}.search-box .suggestions{background:#fff;width:20rem;position:absolute;top:2rem;border:1px solid #cfd4db;border-radius:6px;padding:.4rem;list-style-type:none}.search-box .suggestions.align-right{right:0}.search-box .suggestion{line-height:1.4;padding:.4rem .6rem;border-radius:4px;cursor:pointer}.search-box .suggestion a{white-space:normal;color:#5d82a6}.search-box .suggestion a .page-title{font-weight:600}.search-box .suggestion a .header{font-size:.9em;margin-left:.25em}.search-box .suggestion.focused{background-color:#f3f4f5}.search-box .suggestion.focused a{color:#007acc}@media (max-width:959px){.search-box input{cursor:pointer;width:0;border-color:transparent;position:relative}.search-box input:focus{cursor:text;left:0;width:10rem}}@media (-ms-high-contrast:none){.search-box input{height:2rem}}@media (max-width:959px) and (min-width:719px){.search-box .suggestions{left:0}}@media (max-width:719px){.search-box{margin-right:0}.search-box input{left:1rem}.search-box .suggestions{right:0}}@media (max-width:419px){.search-box .suggestions{width:calc(100vw - 4rem)}.search-box input:focus{width:8rem}}.sidebar-button{cursor:pointer;display:none;width:1.25rem;height:1.25rem;position:absolute;padding:.6rem;top:.6rem;left:1rem}.sidebar-button .icon{display:block;width:1.25rem;height:1.25rem}@media (max-width:719px){.sidebar-button{display:block}}.dropdown-enter,.dropdown-leave-to{height:0!important}.dropdown-wrapper{cursor:pointer}.dropdown-wrapper .dropdown-title,.dropdown-wrapper .mobile-dropdown-title{display:block;font-size:.9rem;font-family:inherit;cursor:inherit;padding:inherit;line-height:1.4rem;background:transparent;border:none;font-weight:500;color:#2c3e50}.dropdown-wrapper .dropdown-title:hover,.dropdown-wrapper .mobile-dropdown-title:hover{border-color:transparent}.dropdown-wrapper .dropdown-title .arrow,.dropdown-wrapper .mobile-dropdown-title .arrow{vertical-align:middle;margin-top:-1px;margin-left:.4rem}.dropdown-wrapper .mobile-dropdown-title{display:none;font-weight:600}.dropdown-wrapper .mobile-dropdown-title font-size inherit:hover{color:#007acc}.dropdown-wrapper .nav-dropdown .dropdown-item{color:inherit;line-height:1.7rem}.dropdown-wrapper .nav-dropdown .dropdown-item h4{margin:.45rem 0 0;border-top:1px solid #eee;padding:1rem 1.5rem .45rem 1.25rem}.dropdown-wrapper .nav-dropdown .dropdown-item .dropdown-subitem-wrapper{padding:0;list-style:none}.dropdown-wrapper .nav-dropdown .dropdown-item .dropdown-subitem-wrapper .dropdown-subitem{font-size:.9em}.dropdown-wrapper .nav-dropdown .dropdown-item a{display:block;line-height:1.7rem;position:relative;border-bottom:none;font-weight:400;margin-bottom:0;padding:0 1.5rem 0 1.25rem}.dropdown-wrapper .nav-dropdown .dropdown-item a.router-link-active,.dropdown-wrapper .nav-dropdown .dropdown-item a:hover{color:#007acc}.dropdown-wrapper .nav-dropdown .dropdown-item a.router-link-active:after{content:"";width:0;height:0;border-left:5px solid #007acc;border-top:3px solid transparent;border-bottom:3px solid transparent;position:absolute;top:calc(50% - 2px);left:9px}.dropdown-wrapper .nav-dropdown .dropdown-item:first-child h4{margin-top:0;padding-top:0;border-top:0}@media (max-width:719px){.dropdown-wrapper.open .dropdown-title{margin-bottom:.5rem}.dropdown-wrapper .dropdown-title{display:none}.dropdown-wrapper .mobile-dropdown-title{display:block}.dropdown-wrapper .nav-dropdown{transition:height .1s ease-out;overflow:hidden}.dropdown-wrapper .nav-dropdown .dropdown-item h4{border-top:0;margin-top:0;padding-top:0}.dropdown-wrapper .nav-dropdown .dropdown-item>a,.dropdown-wrapper .nav-dropdown .dropdown-item h4{font-size:15px;line-height:2rem}.dropdown-wrapper .nav-dropdown .dropdown-item .dropdown-subitem{font-size:14px;padding-left:1rem}}@media (min-width:719px){.dropdown-wrapper{height:1.8rem}.dropdown-wrapper.open .nav-dropdown,.dropdown-wrapper:hover .nav-dropdown{display:block!important}.dropdown-wrapper.open:blur{display:none}.dropdown-wrapper .nav-dropdown{display:none;height:auto!important;box-sizing:border-box;max-height:calc(100vh - 2.7rem);overflow-y:auto;position:absolute;top:100%;right:0;background-color:#fff;padding:.6rem 0;border:1px solid;border-color:#ddd #ddd #ccc;text-align:left;border-radius:.25rem;white-space:nowrap;margin:0}}.nav-links{display:inline-block}.nav-links a{line-height:1.4rem;color:inherit}.nav-links a.router-link-active,.nav-links a:hover{color:#007acc}.nav-links .nav-item{position:relative;display:inline-block;margin-left:1.5rem;line-height:2rem}.nav-links .nav-item:first-child{margin-left:0}.nav-links .repo-link{margin-left:1.5rem}@media (max-width:719px){.nav-links .nav-item,.nav-links .repo-link{margin-left:0}}@media (min-width:719px){.nav-links a.router-link-active,.nav-links a:hover{color:#2c3e50}.nav-item>a:not(.external).router-link-active,.nav-item>a:not(.external):hover{margin-bottom:-2px;border-bottom:2px solid #0089e4}}.navbar{padding:.7rem 1.5rem;line-height:3.2rem}.navbar a,.navbar img,.navbar span{display:inline-block}.navbar .logo{height:3.2rem;min-width:3.2rem;margin-right:.8rem;vertical-align:top}.navbar .site-name{font-size:1.3rem;font-weight:600;color:#2c3e50;position:relative}.navbar .links{padding-left:1.5rem;box-sizing:border-box;background-color:#fff;white-space:nowrap;font-size:.9rem;position:absolute;right:1.5rem;top:.7rem;display:flex}.navbar .links .search-box{flex:0 0 auto;vertical-align:top}@media (max-width:719px){.navbar{padding-left:4rem}.navbar .can-hide{display:none}.navbar .links{padding-left:1.5rem}.navbar .site-name{width:calc(100vw - 9.4rem);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}}.page-edit{max-width:960px;margin:0 auto;padding:2rem 2.5rem}@media (max-width:959px){.page-edit{padding:2rem}}@media (max-width:419px){.page-edit{padding:1.5rem}}.page-edit{padding-top:1rem;padding-bottom:1rem;overflow:auto}.page-edit .edit-link{display:inline-block}.page-edit .edit-link a{color:#4e6e8e;margin-right:.25rem}.page-edit .last-updated{float:right;font-size:.9em}.page-edit .last-updated .prefix{font-weight:500;color:#4e6e8e}.page-edit .last-updated .time{font-weight:400;color:#767676}@media (max-width:719px){.page-edit .edit-link{margin-bottom:.5rem}.page-edit .last-updated{font-size:.8em;float:none;text-align:left}}.page-nav{max-width:960px;margin:0 auto;padding:2rem 2.5rem}@media (max-width:959px){.page-nav{padding:2rem}}@media (max-width:419px){.page-nav{padding:1.5rem}}.page-nav{padding-top:1rem;padding-bottom:0}.page-nav .inner{min-height:2rem;margin-top:0;border-top:1px solid #eaecef;padding-top:1rem;overflow:auto}.page-nav .next{float:right}.page{padding-bottom:2rem;display:block}.page[data-v-bb3fd134]{padding-bottom:0}.editor-wrap{position:relative;-webkit-margin-before:1em;margin-block-start:1em;-webkit-margin-after:1em;margin-block-end:1em}.editor-wrap a.maximize{position:absolute;top:8px;right:12px;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;color:#c7c4c7;cursor:pointer;font-size:1.2rem;z-index:1000}.editor-wrap a.maximize:hover{color:#fff;text-decoration:none}.editor-wrap iframe{background:#1e1e1e;width:100%;height:540px;min-height:540px;border:0;resize:vertical}.editor-wrap.maximized{position:fixed;-webkit-margin-before:auto;margin-block-start:auto;-webkit-margin-after:auto;margin-block-end:auto;z-index:9000;margin:0;top:0;left:0;height:100%;width:100%}.editor-wrap.maximized iframe{height:100%!important;resize:none}.sidebar-group .sidebar-group{padding-left:.5em}.sidebar-group:not(.collapsable) .sidebar-heading:not(.clickable){cursor:auto;color:inherit}.sidebar-group.is-sub-group{padding-left:0}.sidebar-group.is-sub-group>.sidebar-heading{font-size:.95em;line-height:1.4;font-weight:400;padding-left:2rem}.sidebar-group.is-sub-group>.sidebar-heading:not(.clickable){opacity:.5}.sidebar-group.is-sub-group>.sidebar-group-items{padding-left:1rem}.sidebar-group.is-sub-group>.sidebar-group-items>li>.sidebar-link{font-size:.95em;border-left:none}.sidebar-group.depth-2>.sidebar-heading{border-left:none}.sidebar-heading{color:#2c3e50;transition:color .15s ease;cursor:pointer;font-size:1.1em;font-weight:700;padding:.35rem 1.5rem .35rem 1.25rem;width:100%;box-sizing:border-box;margin:0;border-left:.25rem solid transparent}.sidebar-heading.open,.sidebar-heading:hover{color:inherit}.sidebar-heading .arrow{position:relative;top:-.12em;left:.5em}.sidebar-heading.clickable.active{font-weight:600;color:#007acc;border-left-color:#007acc}.sidebar-heading.clickable:hover{color:#007acc}.sidebar-group-items{transition:height .1s ease-out;font-size:.95em;overflow:hidden}.sidebar .sidebar-sub-headers{padding-left:1rem;font-size:.95em}a.sidebar-link{font-size:1em;font-weight:400;display:inline-block;color:#2c3e50;border-left:.25rem solid transparent;padding:.35rem 1rem .35rem 1.25rem;line-height:1.4;width:100%;box-sizing:border-box}a.sidebar-link:hover{color:#007acc}a.sidebar-link.active{font-weight:600;color:#007acc;border-left-color:#007acc}.sidebar-group a.sidebar-link{padding-left:2rem}.sidebar-sub-headers a.sidebar-link{padding-top:.25rem;padding-bottom:.25rem;border-left:none}.sidebar-sub-headers a.sidebar-link.active{font-weight:500}.sidebar ul{padding:0;margin:0;list-style-type:none}.sidebar a{display:inline-block}.sidebar .nav-links{display:none;border-bottom:1px solid #eaecef;padding:.5rem 0 .75rem}.sidebar .nav-links a{font-weight:600}.sidebar .nav-links .nav-item,.sidebar .nav-links .repo-link{display:block;line-height:1.25rem;font-size:1.1em;padding:.5rem 0 .5rem 1.5rem}.sidebar>.sidebar-links{padding:1.5rem 0}.sidebar>.sidebar-links>li>a.sidebar-link{font-size:1.1em;line-height:1.7;font-weight:700}.sidebar>.sidebar-links>li:not(:first-child){margin-top:.75rem}@media (max-width:719px){.sidebar .nav-links{display:block}.sidebar .nav-links .dropdown-wrapper .nav-dropdown .dropdown-item a.router-link-active:after{top:calc(1rem - 2px)}.sidebar>.sidebar-links{padding:1rem 0}}.footer[data-v-7c0e63ba]{text-align:center;color:#4e6e8e;padding:0 2rem}.footer .item[data-v-7c0e63ba]{white-space:nowrap}#hero[data-v-0f93345e]{margin-top:2rem;text-align:center;height:400px;background:#007acc}#hero[data-v-0f93345e]:before{content:"";position:absolute;z-index:0;top:0;left:0;width:100%;height:520px;background:#007acc url(/images/header.svg) bottom no-repeat;background-size:1440px}#hero>[data-v-0f93345e]{position:relative}#hero h1[data-v-0f93345e]{color:#fff;margin:1.3rem auto 1.8rem;font-size:2rem;font-weight:200}#logo[data-v-0f93345e]{display:inline-block;width:640px}#logo svg[data-v-0f93345e]{width:100%;height:100%;max-height:240px;fill:#fff}@media only screen and (max-width:740px){#logo[data-v-0f93345e]{width:100%}#logo svg[data-v-0f93345e]{max-height:213px}}#features[data-v-0f93345e]{padding:1.2rem 0 0;margin-top:2.5rem;display:flex;flex-wrap:wrap;align-items:flex-start;align-content:stretch;justify-content:space-between}#features .feature[data-v-0f93345e]{flex-grow:1;flex-basis:30%;max-width:30%}#features h2[data-v-0f93345e]{font-size:1.4rem;border-bottom:none;padding-bottom:0;color:#3a5169}.action[data-v-0f93345e]{text-align:center;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.action a[data-v-0f93345e]{display:inline-block;font-size:1.2rem;color:#fff;background-color:#007acc;padding:.8rem 1.6rem;border-radius:4px;transition:background-color .1s ease;box-sizing:border-box;border-bottom:1px solid #006eb8;text-decoration:none!important;margin:.1rem 0}.action a[data-v-0f93345e]:hover{background-color:#1a8ae7}.action a svg[data-v-0f93345e]{width:2em;position:relative;left:-10px;float:left;height:32px}.action a.docs[data-v-0f93345e]{color:#111;background:#fff;border-bottom-color:#aaa}.action a.docs[data-v-0f93345e]:hover{background:#eee}.action a.github[data-v-0f93345e]{color:#fff;background:#24292e;border-bottom-color:#101214}.action a.github[data-v-0f93345e]:hover{background:#3e464f}.action a.npm[data-v-0f93345e]{color:#fff;background:#cb3837;border-bottom-color:#ba3232}.action a.npm[data-v-0f93345e]:hover{background:#eb3f3f}@media only screen and (max-width:720px){.action a.github svg[data-v-0f93345e]{float:none;left:0;margin-bottom:-.5rem}.action a.github .title[data-v-0f93345e],.action a.npm[data-v-0f93345e]{display:none}#features .feature[data-v-0f93345e]{flex-basis:100%;max-width:100%}}@media only screen and (max-width:640px){#try[data-v-0f93345e]{display:none}}#sponsors[data-v-0f93345e]{margin-bottom:2rem}#community h2 svg[data-v-0f93345e]{display:inline-block;height:25px;position:relative;top:3px}.frontpage .page-edit{display:none}.community .list[data-v-181c7660]{text-align:center}.community .list a[data-v-181c7660]{display:inline-block;box-sizing:border-box;position:relative;top:0;transition:top .1s}.community .list a[data-v-181c7660]:hover{top:-4px}.community .list a[data-v-181c7660]:before{content:"";position:absolute;border-radius:50%;background:#999;bottom:2px;right:2px;width:10px;height:10px;border:2px solid #fff}.community .list a.online[data-v-181c7660]:before{background:#49b684}.community .list a.idle[data-v-181c7660]:before{background:#fff url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMCAxMCI+PHBhdGggZD0iTTUgMGE1IDUgMCAwMC0xLjA1OS4xMkEzLjA5IDMuMDkgMCAwMTYuMTggMy4wODdhMy4wOSAzLjA5IDAgMDEtMy4wOSAzLjA5QTMuMDkgMy4wOSAwIDAxLjEyIDMuOTMgNSA1IDAgMDAwIDVhNSA1IDAgMDA1IDUgNSA1IDAgMDA1LTUgNSA1IDAgMDAtNS01eiIgZmlsbD0iI2Y4YTczNSIvPjwvc3ZnPg==");background-size:10px 10px}.community .list a.dnd[data-v-181c7660]:before{background:#fff url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMCAxMCI+PHBhdGggZD0iTTUgMGE1IDUgMCAwMC01IDUgNSA1IDAgMDA1IDUgNSA1IDAgMDA1LTUgNSA1IDAgMDAtNS01ek0yIDRoNnYySDJWNHoiIGZpbGw9IiNlZDQ3NGEiLz48L3N2Zz4=");background-size:10px 10px}.community .list img[data-v-181c7660]{width:32px;height:32px;overflow:hidden;border-radius:50%;border:1px solid #fff;box-shadow:0 0 0 1px #007acc}.community .list a[data-v-181c7660]{padding:.15rem}.contributors h3[data-v-31cd9d1c]{text-align:center;border:0}.contributors .list[data-v-31cd9d1c]{text-align:center}.contributors .list a[data-v-31cd9d1c]{display:inline-block;box-sizing:border-box;position:relative;top:0;transition:top .1s}.contributors .list a[data-v-31cd9d1c]:hover{top:-4px}.contributors .list img[data-v-31cd9d1c]{width:32px;height:32px;overflow:hidden;border-radius:50%;border:1px solid #fff;box-shadow:0 0 0 1px #007acc}.contributors .list a[data-v-31cd9d1c]{padding:.15rem}.sponsors[data-v-7f9b29e8]{border:1px solid #eaecef;background:#fff;padding:0 .5rem 1.5rem}.sponsors h3[data-v-7f9b29e8]{text-align:center;border:0}.sponsors .list[data-v-7f9b29e8]{text-align:center}.sponsors .list a[data-v-7f9b29e8]{display:inline-block;box-sizing:border-box;position:relative;top:0;transition:top .1s}.sponsors .list img[data-v-7f9b29e8]{overflow:hidden}.sponsors .list a[data-v-7f9b29e8]:hover{top:-4px}.sponsors .platinum .list img[data-v-7f9b29e8]{height:80px}.sponsors .platinum .list a[data-v-7f9b29e8]{padding:.5rem}.sponsors .gold .list img[data-v-7f9b29e8]{height:64px}.sponsors .gold .list a[data-v-7f9b29e8]{padding:.5rem}.sponsors .silver .list img[data-v-7f9b29e8]{height:48px}.sponsors .silver .list a[data-v-7f9b29e8]{padding:.4rem}.sponsors .bronze .list img[data-v-7f9b29e8]{height:36px}.sponsors .bronze .list a[data-v-7f9b29e8]{padding:.3rem}.sponsors .backer .list img[data-v-7f9b29e8]{width:32px;height:32px;border-radius:50%;border:1px solid #fff;box-shadow:0 0 0 1px #007acc}.sponsors .backer .list a[data-v-7f9b29e8]{padding:.15rem}.testimonials[data-v-aebe12ce]{padding-bottom:1rem}.testimonials h3[data-v-aebe12ce]{text-align:center;border:0}.testimonial[data-v-aebe12ce]{display:flex;flex-direction:row;align-items:center;padding:1.5rem 0;margin:0 0 0 30px}.testimonial .logo[data-v-aebe12ce]{border-radius:50%;width:76px;height:76px;border:1px solid #fff;box-shadow:0 0 0 1px #007acc}.testimonial p[data-v-aebe12ce]{margin:0 30px;text-align:justify}@media only screen and (max-width:720px){.testimonial[data-v-aebe12ce]{flex-direction:column;margin:0}.testimonial .logo[data-v-aebe12ce]{width:90px;height:90px}.testimonial p[data-v-aebe12ce]{margin:20px 0 10px}}.badge[data-v-15b7b770]{display:inline-block;font-size:14px;height:18px;line-height:18px;border-radius:3px;padding:0 6px;color:#fff}.badge.green[data-v-15b7b770],.badge.tip[data-v-15b7b770],.badge[data-v-15b7b770]{background-color:#42b983}.badge.error[data-v-15b7b770]{background-color:#da5961}.badge.warn[data-v-15b7b770],.badge.warning[data-v-15b7b770],.badge.yellow[data-v-15b7b770]{background-color:#e7c000}.badge+.badge[data-v-15b7b770]{margin-left:5px}.theme-code-block[data-v-759a7d02]{display:none}.theme-code-block__active[data-v-759a7d02]{display:block}.theme-code-block>pre[data-v-759a7d02]{background-color:orange}.theme-code-group__nav[data-v-deefee04]{margin-bottom:-35px;background-color:#fff;padding-bottom:22px;border-top-left-radius:6px;border-top-right-radius:6px;padding-left:10px;padding-top:10px}.theme-code-group__ul[data-v-deefee04]{margin:auto 0;padding-left:0;display:inline-flex;list-style:none}.theme-code-group__nav-tab[data-v-deefee04]{border:0;padding:5px;cursor:pointer;background-color:transparent;font-size:.85em;line-height:1.4;color:hsla(0,0%,100%,.9);font-weight:600}.theme-code-group__nav-tab-active[data-v-deefee04]{border-bottom:1px solid #42b983}.pre-blank[data-v-deefee04]{color:#42b983}.searchbox{display:inline-block;position:relative;width:200px;height:32px!important;white-space:nowrap;box-sizing:border-box;visibility:visible!important}.searchbox .algolia-autocomplete{display:block;width:100%;height:100%}.searchbox__wrapper{width:100%;height:100%;z-index:999;position:relative}.searchbox__input{display:inline-block;box-sizing:border-box;transition:box-shadow .4s ease,background .4s ease;border:0;border-radius:16px;box-shadow:inset 0 0 0 1px #ccc;background:#fff!important;padding:0 26px 0 32px;width:100%;height:100%;vertical-align:middle;white-space:normal;font-size:12px;-webkit-appearance:none;-moz-appearance:none;appearance:none}.searchbox__input::-webkit-search-cancel-button,.searchbox__input::-webkit-search-decoration,.searchbox__input::-webkit-search-results-button,.searchbox__input::-webkit-search-results-decoration{display:none}.searchbox__input:hover{box-shadow:inset 0 0 0 1px #b3b3b3}.searchbox__input:active,.searchbox__input:focus{outline:0;box-shadow:inset 0 0 0 1px #aaa;background:#fff}.searchbox__input:-ms-input-placeholder{color:#aaa}.searchbox__input::-moz-placeholder{color:#aaa}.searchbox__input::placeholder{color:#aaa}.searchbox__submit{position:absolute;top:0;margin:0;border:0;border-radius:16px 0 0 16px;background-color:rgba(69,142,225,0);padding:0;width:32px;height:100%;vertical-align:middle;text-align:center;font-size:inherit;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;right:inherit;left:0}.searchbox__submit:before{display:inline-block;margin-right:-4px;height:100%;vertical-align:middle;content:""}.searchbox__submit:active,.searchbox__submit:hover{cursor:pointer}.searchbox__submit:focus{outline:0}.searchbox__submit svg{width:14px;height:14px;vertical-align:middle;fill:#6d7e96}.searchbox__reset{display:block;position:absolute;top:8px;right:8px;margin:0;border:0;background:none;cursor:pointer;padding:0;font-size:inherit;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;fill:rgba(0,0,0,.5)}.searchbox__reset.hide{display:none}.searchbox__reset:focus{outline:0}.searchbox__reset svg{display:block;margin:4px;width:8px;height:8px}.searchbox__input:valid~.searchbox__reset{display:block;-webkit-animation-name:sbx-reset-in;animation-name:sbx-reset-in;-webkit-animation-duration:.15s;animation-duration:.15s}@-webkit-keyframes sbx-reset-in{0%{transform:translate3d(-20%,0,0);opacity:0}to{transform:none;opacity:1}}@keyframes sbx-reset-in{0%{transform:translate3d(-20%,0,0);opacity:0}to{transform:none;opacity:1}}.algolia-autocomplete.algolia-autocomplete-right .ds-dropdown-menu{right:0!important;left:inherit!important}.algolia-autocomplete.algolia-autocomplete-right .ds-dropdown-menu:before{right:48px}.algolia-autocomplete.algolia-autocomplete-left .ds-dropdown-menu{left:0!important;right:inherit!important}.algolia-autocomplete.algolia-autocomplete-left .ds-dropdown-menu:before{left:48px}.algolia-autocomplete .ds-dropdown-menu{top:-6px;border-radius:4px;margin:6px 0 0;padding:0;text-align:left;height:auto;position:relative;background:transparent;border:none;z-index:999;max-width:600px;min-width:500px;box-shadow:0 1px 0 0 rgba(0,0,0,.2),0 2px 3px 0 rgba(0,0,0,.1)}.algolia-autocomplete .ds-dropdown-menu:before{display:block;position:absolute;content:"";width:14px;height:14px;background:#fff;z-index:1000;top:-7px;border-top:1px solid #d9d9d9;border-right:1px solid #d9d9d9;transform:rotate(-45deg);border-radius:2px}.algolia-autocomplete .ds-dropdown-menu .ds-suggestions{position:relative;z-index:1000;margin-top:8px}.algolia-autocomplete .ds-dropdown-menu .ds-suggestions a:hover{text-decoration:none}.algolia-autocomplete .ds-dropdown-menu .ds-suggestion{cursor:pointer}.algolia-autocomplete .ds-dropdown-menu .ds-suggestion.ds-cursor .algolia-docsearch-suggestion.suggestion-layout-simple,.algolia-autocomplete .ds-dropdown-menu .ds-suggestion.ds-cursor .algolia-docsearch-suggestion:not(.suggestion-layout-simple) .algolia-docsearch-suggestion--content{background-color:rgba(69,142,225,.05)}.algolia-autocomplete .ds-dropdown-menu [class^=ds-dataset-]{position:relative;border:1px solid #d9d9d9;background:#fff;border-radius:4px;overflow:auto;padding:0 8px 8px}.algolia-autocomplete .ds-dropdown-menu *{box-sizing:border-box}.algolia-autocomplete .algolia-docsearch-suggestion{display:block;position:relative;padding:0 8px;background:#fff;color:#02060c;overflow:hidden}.algolia-autocomplete .algolia-docsearch-suggestion--highlight{color:#174d8c;background:rgba(143,187,237,.1);padding:.1em .05em}.algolia-autocomplete .algolia-docsearch-suggestion--category-header .algolia-docsearch-suggestion--category-header-lvl0 .algolia-docsearch-suggestion--highlight,.algolia-autocomplete .algolia-docsearch-suggestion--category-header .algolia-docsearch-suggestion--category-header-lvl1 .algolia-docsearch-suggestion--highlight,.algolia-autocomplete .algolia-docsearch-suggestion--text .algolia-docsearch-suggestion--highlight{padding:0 0 1px;background:inherit;box-shadow:inset 0 -2px 0 0 rgba(69,142,225,.8);color:inherit}.algolia-autocomplete .algolia-docsearch-suggestion--content{display:block;float:right;width:70%;position:relative;padding:5.33333px 0 5.33333px 10.66667px;cursor:pointer}.algolia-autocomplete .algolia-docsearch-suggestion--content:before{content:"";position:absolute;display:block;top:0;height:100%;width:1px;background:#ddd;left:-1px}.algolia-autocomplete .algolia-docsearch-suggestion--category-header{position:relative;border-bottom:1px solid #ddd;display:none;margin-top:8px;padding:4px 0;font-size:1em;color:#33363d}.algolia-autocomplete .algolia-docsearch-suggestion--wrapper{width:100%;float:left;padding:8px 0 0}.algolia-autocomplete .algolia-docsearch-suggestion--subcategory-column{float:left;width:30%;text-align:right;position:relative;padding:5.33333px 10.66667px;color:#a4a7ae;font-size:.9em;word-wrap:break-word}.algolia-autocomplete .algolia-docsearch-suggestion--subcategory-column:before{content:"";position:absolute;display:block;top:0;height:100%;width:1px;background:#ddd;right:0}.algolia-autocomplete .algolia-docsearch-suggestion--subcategory-inline{display:none}.algolia-autocomplete .algolia-docsearch-suggestion--title{margin-bottom:4px;color:#02060c;font-size:.9em;font-weight:700}.algolia-autocomplete .algolia-docsearch-suggestion--text{display:block;line-height:1.2em;font-size:.85em;color:#63676d}.algolia-autocomplete .algolia-docsearch-suggestion--no-results{width:100%;padding:8px 0;text-align:center;font-size:1.2em}.algolia-autocomplete .algolia-docsearch-suggestion--no-results:before{display:none}.algolia-autocomplete .algolia-docsearch-suggestion code{padding:1px 5px;font-size:90%;border:none;color:#222;background-color:#ebebeb;border-radius:3px;font-family:Menlo,Monaco,Consolas,Courier New,monospace}.algolia-autocomplete .algolia-docsearch-suggestion code .algolia-docsearch-suggestion--highlight{background:none}.algolia-autocomplete .algolia-docsearch-suggestion.algolia-docsearch-suggestion__main .algolia-docsearch-suggestion--category-header,.algolia-autocomplete .algolia-docsearch-suggestion.algolia-docsearch-suggestion__secondary{display:block}@media (min-width:768px){.algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column{display:block}}@media (max-width:768px){.algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column{display:inline-block;width:auto;float:left;padding:0;color:#02060c;font-size:.9em;font-weight:700;text-align:left;opacity:.5}.algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column:before{display:none}.algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--subcategory-column:after{content:"|"}.algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--content{display:inline-block;width:auto;text-align:left;float:left;padding:0}.algolia-autocomplete .algolia-docsearch-suggestion .algolia-docsearch-suggestion--content:before{display:none}}.algolia-autocomplete .suggestion-layout-simple.algolia-docsearch-suggestion{border-bottom:1px solid #eee;padding:8px;margin:0}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--content{width:100%;padding:0}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--content:before{display:none}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--category-header{margin:0;padding:0;display:block;width:100%;border:none}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--category-header-lvl0,.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--category-header-lvl1{opacity:.6;font-size:.85em}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--category-header-lvl1:before{background-image:url('data:image/svg+xml;utf8,');content:"";width:10px;height:10px;display:inline-block}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--wrapper{width:100%;float:left;margin:0;padding:0}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--duplicate-content,.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--subcategory-inline{display:none!important}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--title{margin:0;color:#458ee1;font-size:.9em;font-weight:400}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--title:before{content:"#";font-weight:700;color:#458ee1;display:inline-block}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--text{margin:4px 0 0;display:block;line-height:1.4em;padding:5.33333px 8px;background:#f8f8f8;font-size:.85em;opacity:.8}.algolia-autocomplete .suggestion-layout-simple .algolia-docsearch-suggestion--text .algolia-docsearch-suggestion--highlight{color:#3f4145;font-weight:700;box-shadow:none}.algolia-autocomplete .algolia-docsearch-footer{width:134px;height:20px;z-index:2000;margin-top:10.66667px;float:right;font-size:0;line-height:0}.algolia-autocomplete .algolia-docsearch-footer--logo{background-image:url("data:image/svg+xml;charset=utf-8,%3Csvg width='168' height='24' xmlns='http://www.w3.org/2000/svg'%3E%3Cg fill='none' fill-rule='evenodd'%3E%3Cpath d='M78.988.938h16.594a2.968 2.968 0 012.966 2.966V20.5a2.967 2.967 0 01-2.966 2.964H78.988a2.967 2.967 0 01-2.966-2.964V3.897A2.961 2.961 0 0178.988.938zm41.937 17.866c-4.386.02-4.386-3.54-4.386-4.106l-.007-13.336 2.675-.424v13.254c0 .322 0 2.358 1.718 2.364v2.248zm-10.846-2.18c.821 0 1.43-.047 1.855-.129v-2.719a6.334 6.334 0 00-1.574-.199 5.7 5.7 0 00-.897.069 2.699 2.699 0 00-.814.24c-.24.116-.439.28-.582.491-.15.212-.219.335-.219.656 0 .628.219.991.616 1.23s.938.362 1.615.362zm-.233-9.7c.883 0 1.629.109 2.231.328.602.218 1.088.525 1.444.915.363.396.609.922.76 1.483.157.56.232 1.175.232 1.85v6.874a32.5 32.5 0 01-1.868.314c-.834.123-1.772.185-2.813.185-.69 0-1.327-.069-1.895-.198a4.001 4.001 0 01-1.471-.636 3.085 3.085 0 01-.951-1.134c-.226-.465-.343-1.12-.343-1.803 0-.656.13-1.073.384-1.525a3.24 3.24 0 011.047-1.106c.445-.287.95-.492 1.532-.615a8.8 8.8 0 011.82-.185 8.404 8.404 0 011.972.24v-.438c0-.307-.035-.6-.11-.874a1.88 1.88 0 00-.384-.73 1.784 1.784 0 00-.724-.493 3.164 3.164 0 00-1.143-.205c-.616 0-1.177.075-1.69.164a7.735 7.735 0 00-1.26.307l-.321-2.192c.335-.117.834-.233 1.478-.349a10.98 10.98 0 012.073-.178zm52.842 9.626c.822 0 1.43-.048 1.854-.13V13.7a6.347 6.347 0 00-1.574-.199c-.294 0-.595.021-.896.069a2.7 2.7 0 00-.814.24 1.46 1.46 0 00-.582.491c-.15.212-.218.335-.218.656 0 .628.218.991.615 1.23.404.245.938.362 1.615.362zm-.226-9.694c.883 0 1.629.108 2.231.327.602.219 1.088.526 1.444.915.355.39.609.923.759 1.483a6.8 6.8 0 01.233 1.852v6.873c-.41.088-1.034.19-1.868.314-.834.123-1.772.184-2.813.184-.69 0-1.327-.068-1.895-.198a4.001 4.001 0 01-1.471-.635 3.085 3.085 0 01-.951-1.134c-.226-.465-.343-1.12-.343-1.804 0-.656.13-1.073.384-1.524.26-.45.608-.82 1.047-1.107.445-.286.95-.491 1.532-.614a8.803 8.803 0 012.751-.13c.329.034.671.096 1.04.185v-.437a3.3 3.3 0 00-.109-.875 1.873 1.873 0 00-.384-.731 1.784 1.784 0 00-.724-.492 3.165 3.165 0 00-1.143-.205c-.616 0-1.177.075-1.69.164a7.75 7.75 0 00-1.26.307l-.321-2.193c.335-.116.834-.232 1.478-.348a11.633 11.633 0 012.073-.177zm-8.034-1.271a1.626 1.626 0 01-1.628-1.62c0-.895.725-1.62 1.628-1.62.904 0 1.63.725 1.63 1.62 0 .895-.733 1.62-1.63 1.62zm1.348 13.22h-2.689V7.27l2.69-.423v11.956zm-4.714 0c-4.386.02-4.386-3.54-4.386-4.107l-.008-13.336 2.676-.424v13.254c0 .322 0 2.358 1.718 2.364v2.248zm-8.698-5.903c0-1.156-.253-2.119-.746-2.788-.493-.677-1.183-1.01-2.067-1.01-.882 0-1.574.333-2.065 1.01-.493.676-.733 1.632-.733 2.788 0 1.168.246 1.953.74 2.63.492.683 1.183 1.018 2.066 1.018.882 0 1.574-.342 2.067-1.019.492-.683.738-1.46.738-2.63zm2.737-.007c0 .902-.13 1.584-.397 2.33a5.52 5.52 0 01-1.128 1.906 4.986 4.986 0 01-1.752 1.223c-.685.286-1.739.45-2.265.45-.528-.006-1.574-.157-2.252-.45a5.096 5.096 0 01-1.744-1.223c-.487-.527-.863-1.162-1.137-1.906a6.345 6.345 0 01-.41-2.33c0-.902.123-1.77.397-2.508a5.554 5.554 0 011.15-1.892 5.133 5.133 0 011.75-1.216c.679-.287 1.425-.423 2.232-.423.808 0 1.553.142 2.237.423a4.88 4.88 0 011.753 1.216 5.644 5.644 0 011.135 1.892c.287.738.431 1.606.431 2.508zm-20.138 0c0 1.12.246 2.363.738 2.882.493.52 1.13.78 1.91.78.424 0 .828-.062 1.204-.178.377-.116.677-.253.917-.417V9.33a10.476 10.476 0 00-1.766-.226c-.971-.028-1.71.37-2.23 1.004-.513.636-.773 1.75-.773 2.788zm7.438 5.274c0 1.824-.466 3.156-1.404 4.004-.936.846-2.367 1.27-4.296 1.27-.705 0-2.17-.137-3.34-.396l.431-2.118c.98.205 2.272.26 2.95.26 1.074 0 1.84-.219 2.299-.656.459-.437.684-1.086.684-1.948v-.437a8.07 8.07 0 01-1.047.397c-.43.13-.93.198-1.492.198-.739 0-1.41-.116-2.018-.349a4.206 4.206 0 01-1.567-1.025c-.431-.45-.774-1.017-1.013-1.694-.24-.677-.363-1.885-.363-2.773 0-.834.13-1.88.384-2.577.26-.696.629-1.298 1.129-1.796.493-.498 1.095-.881 1.8-1.162a6.605 6.605 0 012.428-.457c.87 0 1.67.109 2.45.24.78.129 1.444.265 1.985.415V18.17z' fill='%235468FF'/%3E%3Cpath d='M6.972 6.677v1.627c-.712-.446-1.52-.67-2.425-.67-.585 0-1.045.13-1.38.391a1.24 1.24 0 00-.502 1.03c0 .425.164.765.494 1.02.33.256.835.532 1.516.83.447.192.795.356 1.045.495.25.138.537.332.862.582.324.25.563.548.718.894.154.345.23.741.23 1.188 0 .947-.334 1.691-1.004 2.234-.67.542-1.537.814-2.601.814-1.18 0-2.16-.229-2.936-.686v-1.708c.84.628 1.814.942 2.92.942.585 0 1.048-.136 1.388-.407.34-.271.51-.646.51-1.125 0-.287-.1-.55-.302-.79-.203-.24-.42-.42-.655-.542-.234-.123-.585-.29-1.053-.503a61.27 61.27 0 01-.582-.271 13.67 13.67 0 01-.55-.287 4.275 4.275 0 01-.567-.351 6.92 6.92 0 01-.455-.4c-.18-.17-.31-.34-.39-.51-.08-.17-.155-.37-.224-.598a2.553 2.553 0 01-.104-.742c0-.915.333-1.638.998-2.17.664-.532 1.523-.798 2.576-.798.968 0 1.793.17 2.473.51zm7.468 5.696v-.287c-.022-.607-.187-1.088-.495-1.444-.309-.357-.75-.535-1.324-.535-.532 0-.99.194-1.373.583-.382.388-.622.949-.717 1.683h3.909zm1.005 2.792v1.404c-.596.34-1.383.51-2.362.51-1.255 0-2.255-.377-3-1.132-.744-.755-1.116-1.744-1.116-2.968 0-1.297.34-2.316 1.021-3.055.68-.74 1.548-1.11 2.6-1.11 1.033 0 1.852.323 2.458.966.606.644.91 1.572.91 2.784 0 .33-.033.676-.096 1.038h-5.314c.107.702.405 1.239.894 1.611.49.372 1.106.558 1.85.558.862 0 1.58-.202 2.155-.606zm6.605-1.77h-1.212c-.596 0-1.045.116-1.349.35-.303.234-.454.532-.454.894 0 .372.117.664.35.877.235.213.575.32 1.022.32.51 0 .912-.142 1.204-.424.293-.281.44-.651.44-1.108v-.91zm-4.068-2.554V9.325c.627-.361 1.457-.542 2.489-.542 2.116 0 3.175 1.026 3.175 3.08V17h-1.548v-.957c-.415.68-1.143 1.02-2.186 1.02-.766 0-1.38-.22-1.843-.661-.462-.442-.694-1.003-.694-1.684 0-.776.293-1.38.878-1.81.585-.431 1.404-.647 2.457-.647h1.34V11.8c0-.554-.133-.971-.399-1.253-.266-.282-.707-.423-1.324-.423a4.07 4.07 0 00-2.345.718zm9.333-1.93v1.42c.394-1 1.101-1.5 2.123-1.5.148 0 .313.016.494.048v1.531a1.885 1.885 0 00-.75-.143c-.542 0-.989.24-1.34.718-.351.479-.527 1.048-.527 1.707V17h-1.563V8.91h1.563zm5.01 4.084c.022.82.272 1.492.75 2.019.479.526 1.15.79 2.01.79.639 0 1.235-.176 1.788-.527v1.404c-.521.319-1.186.479-1.995.479-1.265 0-2.276-.4-3.031-1.197-.755-.798-1.133-1.792-1.133-2.984 0-1.16.38-2.151 1.14-2.975.761-.825 1.79-1.237 3.088-1.237.702 0 1.346.149 1.93.447v1.436a3.242 3.242 0 00-1.77-.495c-.84 0-1.513.266-2.019.798-.505.532-.758 1.213-.758 2.042zM40.24 5.72v4.579c.458-1 1.293-1.5 2.505-1.5.787 0 1.42.245 1.899.734.479.49.718 1.17.718 2.042V17h-1.564v-5.106c0-.553-.14-.98-.422-1.284-.282-.303-.652-.455-1.11-.455-.531 0-1.002.202-1.411.606-.41.405-.615 1.022-.615 1.851V17h-1.563V5.72h1.563zm14.966 10.02c.596 0 1.096-.253 1.5-.758.404-.506.606-1.157.606-1.955 0-.915-.202-1.62-.606-2.114-.404-.495-.92-.742-1.548-.742-.553 0-1.05.224-1.491.67-.442.447-.662 1.133-.662 2.058 0 .958.212 1.67.638 2.138.425.469.946.703 1.563.703zM53.004 5.72v4.42c.574-.894 1.388-1.341 2.44-1.341 1.022 0 1.857.383 2.506 1.149.649.766.973 1.781.973 3.047 0 1.138-.309 2.109-.925 2.912-.617.803-1.463 1.205-2.537 1.205-1.075 0-1.894-.447-2.457-1.34V17h-1.58V5.72h1.58zm9.908 11.104l-3.223-7.913h1.739l1.005 2.632 1.26 3.415c.096-.32.48-1.458 1.15-3.415l.909-2.632h1.66l-2.92 7.866c-.777 2.074-1.963 3.11-3.559 3.11a2.92 2.92 0 01-.734-.079v-1.34c.17.042.351.064.543.064 1.032 0 1.755-.57 2.17-1.708z' fill='%235D6494'/%3E%3Cpath d='M89.632 5.967v-.772a.978.978 0 00-.978-.977h-2.28a.978.978 0 00-.978.977v.793c0 .088.082.15.171.13a7.127 7.127 0 011.984-.28c.65 0 1.295.088 1.917.259.082.02.164-.04.164-.13m-6.248 1.01l-.39-.389a.977.977 0 00-1.382 0l-.465.465a.973.973 0 000 1.38l.383.383c.062.061.15.047.205-.014.226-.307.472-.601.746-.874.281-.28.568-.526.883-.751.068-.042.075-.137.02-.2m4.16 2.453v3.341c0 .096.104.165.192.117l2.97-1.537c.068-.034.089-.117.055-.184a3.695 3.695 0 00-3.08-1.866c-.068 0-.136.054-.136.13m0 8.048a4.489 4.489 0 01-4.49-4.482 4.488 4.488 0 014.49-4.482 4.488 4.488 0 014.489 4.482 4.484 4.484 0 01-4.49 4.482m0-10.85a6.363 6.363 0 100 12.729 6.37 6.37 0 006.372-6.368 6.358 6.358 0 00-6.371-6.36' fill='%23FFF'/%3E%3C/g%3E%3C/svg%3E");background-repeat:no-repeat;background-position:50%;background-size:100%;overflow:hidden;text-indent:-9000px;padding:0!important;width:100%;height:100%;display:block} \ No newline at end of file diff --git a/assets/img/search.83621669.svg b/assets/img/search.83621669.svg new file mode 100644 index 000000000..03d83913e --- /dev/null +++ b/assets/img/search.83621669.svg @@ -0,0 +1 @@ + diff --git a/assets/js/10.b593aa85.js b/assets/js/10.b593aa85.js new file mode 100644 index 000000000..ac9fd116a --- /dev/null +++ b/assets/js/10.b593aa85.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[10],{175:function(t,e,a){},208:function(t,e,a){"use strict";a(175)},221:function(t,e,a){"use strict";a.r(e);var s={name:"CodeBlock",props:{title:{type:String,required:!0},active:{type:Boolean,default:!1}},mounted(){this.$parent&&this.$parent.loadTabs&&this.$parent.loadTabs()}},i=(a(208),a(6)),n=Object(i.a)(s,(function(){var t=this.$createElement;return(this._self._c||t)("div",{staticClass:"theme-code-block",class:{"theme-code-block__active":this.active}},[this._t("default")],2)}),[],!1,null,"759a7d02",null);e.default=n.exports}}]); \ No newline at end of file diff --git a/assets/js/11.e70694b8.js b/assets/js/11.e70694b8.js new file mode 100644 index 000000000..035a34309 --- /dev/null +++ b/assets/js/11.e70694b8.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[11],{176:function(e,t,a){},209:function(e,t,a){"use strict";a(176)},222:function(e,t,a){"use strict";a.r(t);var o={name:"CodeGroup",data:()=>({codeTabs:[],activeCodeTabIndex:-1}),watch:{activeCodeTabIndex(e){this.activateCodeTab(e)}},mounted(){this.loadTabs()},methods:{changeCodeTab(e){this.activeCodeTabIndex=e},loadTabs(){this.codeTabs=(this.$slots.default||[]).filter(e=>Boolean(e.componentOptions)).map((e,t)=>(""===e.componentOptions.propsData.active&&(this.activeCodeTabIndex=t),{title:e.componentOptions.propsData.title,elm:e.elm})),-1===this.activeCodeTabIndex&&this.codeTabs.length>0&&(this.activeCodeTabIndex=0),this.activateCodeTab(0)},activateCodeTab(e){this.codeTabs.forEach(e=>{e.elm&&e.elm.classList.remove("theme-code-block__active")}),this.codeTabs[e].elm&&this.codeTabs[e].elm.classList.add("theme-code-block__active")}}},s=(a(209),a(6)),c=Object(s.a)(o,(function(){var e=this,t=e.$createElement,a=e._self._c||t;return a("ClientOnly",[a("div",{staticClass:"theme-code-group"},[a("div",{staticClass:"theme-code-group__nav"},[a("ul",{staticClass:"theme-code-group__ul"},e._l(e.codeTabs,(function(t,o){return a("li",{key:t.title,staticClass:"theme-code-group__li"},[a("button",{staticClass:"theme-code-group__nav-tab",class:{"theme-code-group__nav-tab-active":o===e.activeCodeTabIndex},on:{click:function(t){return e.changeCodeTab(o)}}},[e._v("\n "+e._s(t.title)+"\n ")])])})),0)]),e._v(" "),e._t("default"),e._v(" "),e.codeTabs.length<1?a("pre",{staticClass:"pre-blank"},[e._v("// Make sure to add code blocks to your code group")]):e._e()],2)])}),[],!1,null,"deefee04",null);t.default=c.exports}}]); \ No newline at end of file diff --git a/assets/js/12.eac7b90f.js b/assets/js/12.eac7b90f.js new file mode 100644 index 000000000..69922ea8c --- /dev/null +++ b/assets/js/12.eac7b90f.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[12],{170:function(t,e,s){},199:function(t,e,s){"use strict";s(170)},217:function(t,e,s){"use strict";s.r(e);var n={name:"Community",data(){return{members:this.members||[]}},mounted(){fetch("https://green-sun-f03e.encors.workers.dev/?url="+encodeURIComponent("https://discordapp.com/api/guilds/721472913886281818/widget.json"),{mode:"cors",credentials:"omit"}).then(t=>t.json()).then(({members:t})=>{this.members=t.filter(t=>"string"==typeof t.username&&"string"==typeof t.avatar_url&&t.avatar_url.startsWith("https://cdn.discordapp.com/")&&["online","idle","dnd"].includes(t.status))}).catch(t=>{})}},r=(s(199),s(6)),a=Object(r.a)(n,(function(){var t=this.$createElement,e=this._self._c||t;return this.members.length>0?e("div",{staticClass:"community"},[e("div",{staticClass:"list"},this._l(this.members,(function(t){return e("a",{class:t.status,attrs:{href:"https://discord.gg/assemblyscript",title:t.username,target:"_blank",rel:"noopener"}},[e("img",{attrs:{src:t.avatar_url+"?size=64",alt:t.username,loading:"lazy"}})])})),0)]):this._e()}),[],!1,null,"181c7660",null);e.default=a.exports}}]); \ No newline at end of file diff --git a/assets/js/13.a23bc4f4.js b/assets/js/13.a23bc4f4.js new file mode 100644 index 000000000..8aaf08eac --- /dev/null +++ b/assets/js/13.a23bc4f4.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[13],{215:function(t,e,s){"use strict";s.r(e);const o=["There's nothing here.","How did we get here?","That's a Four-Oh-Four.","Looks like we've got some broken links."];var n={methods:{getMsg:()=>o[Math.floor(Math.random()*o.length)]}},h=s(6),i=Object(h.a)(n,(function(){var t=this.$createElement,e=this._self._c||t;return e("div",{staticClass:"theme-container"},[e("div",{staticClass:"theme-default-content"},[e("h1",[this._v("404")]),this._v(" "),e("blockquote",[this._v(this._s(this.getMsg()))]),this._v(" "),e("RouterLink",{attrs:{to:"/"}},[this._v("\n Take me home.\n ")])],1)])}),[],!1,null,null,null);e.default=i.exports}}]); \ No newline at end of file diff --git a/assets/js/14.38407d5c.js b/assets/js/14.38407d5c.js new file mode 100644 index 000000000..5a0526468 --- /dev/null +++ b/assets/js/14.38407d5c.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[14],{259:function(t,e,s){"use strict";s.r(e);var n=s(6),i=Object(n.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("img",{staticClass:"engine",attrs:{src:"/images/chrome.svg",width:"18",height:"18",title:"Chrome"}})}),[],!1,null,null,null);e.default=i.exports}}]); \ No newline at end of file diff --git a/assets/js/15.ccfb67c4.js b/assets/js/15.ccfb67c4.js new file mode 100644 index 000000000..1d437a08c --- /dev/null +++ b/assets/js/15.ccfb67c4.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[15],{261:function(t,e,i){"use strict";i.r(e);var s=i(6),n=Object(s.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("img",{staticClass:"engine",attrs:{src:"/images/firefox.svg",width:"18",height:"18",title:"Firefox"}})}),[],!1,null,null,null);e.default=n.exports}}]); \ No newline at end of file diff --git a/assets/js/16.9e12fbb3.js b/assets/js/16.9e12fbb3.js new file mode 100644 index 000000000..a6830bc33 --- /dev/null +++ b/assets/js/16.9e12fbb3.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[16],{260:function(t,e,s){"use strict";s.r(e);var n=s(6),i=Object(n.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("img",{staticClass:"engine",attrs:{src:"/images/nodejs.svg",width:"18",height:"18",title:"Node.js"}})}),[],!1,null,null,null);e.default=i.exports}}]); \ No newline at end of file diff --git a/assets/js/17.ebe32f37.js b/assets/js/17.ebe32f37.js new file mode 100644 index 000000000..5758879f9 --- /dev/null +++ b/assets/js/17.ebe32f37.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[17],{262:function(t,e,s){"use strict";s.r(e);var i=s(6),a=Object(i.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("img",{staticClass:"engine",attrs:{src:"/images/safari.svg",width:"18",height:"18",title:"Safari"}})}),[],!1,null,null,null);e.default=a.exports}}]); \ No newline at end of file diff --git a/assets/js/18.e8b2f77f.js b/assets/js/18.e8b2f77f.js new file mode 100644 index 000000000..91ac35eaa --- /dev/null +++ b/assets/js/18.e8b2f77f.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[18],{263:function(t,e,s){"use strict";s.r(e);var n=s(6),i=Object(n.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("img",{staticClass:"engine",attrs:{src:"/images/wasmer.svg",width:"18",height:"18",title:"Wasmer"}})}),[],!1,null,null,null);e.default=i.exports}}]); \ No newline at end of file diff --git a/assets/js/19.70bbb3ef.js b/assets/js/19.70bbb3ef.js new file mode 100644 index 000000000..00abcf750 --- /dev/null +++ b/assets/js/19.70bbb3ef.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[19],{264:function(t,e,n){"use strict";n.r(e);var i=n(6),s=Object(i.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("img",{staticClass:"engine",attrs:{src:"/images/noimage.png",width:"18",height:"18",title:"Wasmtime"}})}),[],!1,null,null,null);e.default=s.exports}}]); \ No newline at end of file diff --git a/assets/js/20.10384fec.js b/assets/js/20.10384fec.js new file mode 100644 index 000000000..1057475b7 --- /dev/null +++ b/assets/js/20.10384fec.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[20],{265:function(t,n,e){"use strict";e.r(n);var i=e(6),l=Object(i.a)({},(function(){var t=this.$createElement;return(this._self._c||t)("span",{staticStyle:{display:"inline-block",width:"18px",height:"18px"}})}),[],!1,null,null,null);n.default=l.exports}}]); \ No newline at end of file diff --git a/assets/js/21.0ad30828.js b/assets/js/21.0ad30828.js new file mode 100644 index 000000000..03c85fefe --- /dev/null +++ b/assets/js/21.0ad30828.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[21],{223:function(r,e,t){"use strict";t.r(e);var a=t(6),n=Object(a.a)({},(function(){var r=this,e=r.$createElement,t=r._self._c||e;return t("ContentSlotsDistributor",{attrs:{"slot-key":r.$parent.slotKey}},[t("h1",{attrs:{id:"built-with-assemblyscript"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#built-with-assemblyscript"}},[r._v("#")]),r._v(" Built with AssemblyScript")]),r._v(" "),t("p",[r._v("A place for all things AssemblyScript. Feel free to add your projects and applications.")]),r._v(" "),t("h2",{attrs:{id:"benchmarks"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#benchmarks"}},[r._v("#")]),r._v(" Benchmarks")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/jtiscione/webassembly-wave",target:"_blank",rel:"noopener noreferrer"}},[r._v("webassembly-wave"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://jtiscione.github.io/webassembly-wave/index.html",target:"_blank",rel:"noopener noreferrer"}},[r._v("demo"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nJavaScript vs WebAssembly performance comparison - wave equation demo (JS, C++, AssemblyScript).")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/t-katsumura/webassembly-examples-eratosthenes",target:"_blank",rel:"noopener noreferrer"}},[r._v("Eratosthenes"),t("OutboundLink")],1),t("br"),r._v("\nWebAssembly examples which calculate prime by Sieve of Eratosthenes.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://wasmboy.app/benchmark/",target:"_blank",rel:"noopener noreferrer"}},[r._v("WasmBoy Benchmark"),t("OutboundLink")],1),t("br"),r._v("\nBenchmarking WasmBoy emulator.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/w8r/wasm-n-body",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasm-n-body"),t("OutboundLink")],1),t("br"),r._v("\nWebAssembly N-body simulation benchmark "),t("em",[r._v("(use 1000 bodies compare to original).")])]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/nischayv/as-benchmarks",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-benchmarks"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://nischayv.github.io/as-benchmarks/index.html",target:"_blank",rel:"noopener noreferrer"}},[r._v("demo"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nA set of computational benchmarks (JS, AssemblyScript).")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/manueldois/WebAssembly/tree/master/Sort%20Colors%20Benchmark/src",target:"_blank",rel:"noopener noreferrer"}},[r._v("Sort Colors Benchmark"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://manueldois.github.io/WebAssembly/Sort%20Colors%20Benchmark/dist/index.html",target:"_blank",rel:"noopener noreferrer"}},[r._v("demo"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nBench of sorting random colors by hue component on 2d canvas.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ColinEberhardt/wasm-mandelbrot",target:"_blank",rel:"noopener noreferrer"}},[r._v("Wasm Mandelbrot"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://colineberhardt.github.io/wasm-mandelbrot/#AssemblyScript",target:"_blank",rel:"noopener noreferrer"}},[r._v("demo"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nA mandelbrot rendered using a variety of WebAssembly tools (emscripten, AssemblyScript, asm.js, etc ...)")])]),r._v(" "),t("h2",{attrs:{id:"blockchain"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#blockchain"}},[r._v("#")]),r._v(" Blockchain")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/ascontract/subscript",target:"_blank",rel:"noopener noreferrer"}},[r._v("ASContract / subscript"),t("OutboundLink")],1),t("br"),r._v("\nSubstrate smart contract framework written in AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ewasm/biturbo",target:"_blank",rel:"noopener noreferrer"}},[r._v("eWasm / Biturbo"),t("OutboundLink")],1),t("br"),r._v("\nEth1 EE using Turboproofs.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ewasm/scout.ts",target:"_blank",rel:"noopener noreferrer"}},[r._v("ewasm / scout.ts "),t("OutboundLink")],1),t("br"),r._v("\nScout is a Ethereum 2.0 Phase 2 execution prototyping engine (AssemblyScript Port).")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/near/near-sdk-as",target:"_blank",rel:"noopener noreferrer"}},[r._v("NearProtocol / near-sdk-as"),t("OutboundLink")],1),t("br"),r._v("\nAssemblyScript tools for writing smart contracts for NearProtocol.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/graphprotocol/graph-ts",target:"_blank",rel:"noopener noreferrer"}},[r._v("GraphProtocol / graph-ts"),t("OutboundLink")],1),t("br"),r._v("\nTypeScript/AssemblyScript library for writing mappings for "),t("a",{attrs:{href:"https://thegraph.com",target:"_blank",rel:"noopener noreferrer"}},[r._v("The Graph"),t("OutboundLink")],1),r._v(".")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ChainSafe/as-sha256",target:"_blank",rel:"noopener noreferrer"}},[r._v("ChainSafe / as-sha256"),t("OutboundLink")],1),t("br"),r._v("\nAssemblyScript implementation of SHA256 for "),t("a",{attrs:{href:"https://github.com/ChainSafe/lodestar",target:"_blank",rel:"noopener noreferrer"}},[r._v("Lodestar"),t("OutboundLink")],1),r._v(".")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/paritytech/srml-contracts-waterfall",target:"_blank",rel:"noopener noreferrer"}},[r._v("ParityTech / srml-contracts-waterfall"),t("OutboundLink")],1),t("br"),r._v("\nCollection of simple Substrate smart contract examples written in Rust and AssemblyScript and tests for Substrates SRML Contracts module.")])]),r._v(" "),t("h2",{attrs:{id:"build-tools"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#build-tools"}},[r._v("#")]),r._v(" Build Tools")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/lastmjs/zwitterion",target:"_blank",rel:"noopener noreferrer"}},[r._v("Zwitterion"),t("OutboundLink")],1),t("br"),r._v("\nA web dev server that lets you import anything*.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/surma/rollup-plugin-assemblyscript",target:"_blank",rel:"noopener noreferrer"}},[r._v("rollup-plugin-assemblyscript"),t("OutboundLink")],1),t("br"),r._v("\nA Rollup plugin that allows you to import AssemblyScript files and compiles them on-the-fly.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/piotr-oles/as-loader",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-loader"),t("OutboundLink")],1),t("br"),r._v("\nA webpack loader for AssemblyScript")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/willemneal/visitor-as",target:"_blank",rel:"noopener noreferrer"}},[r._v("visitor-as"),t("OutboundLink")],1),t("br"),r._v("\nTools for creating compiler transformers.")])]),r._v(" "),t("h2",{attrs:{id:"demoscene"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#demoscene"}},[r._v("#")]),r._v(" Demoscene")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://wasm-demo.codument.com",target:"_blank",rel:"noopener noreferrer"}},[r._v("Hoofdkantoor WASM Demo"),t("OutboundLink")],1),t("br"),r._v("\nA demo built with AssemblyScript (also TS and Web Audio API). It's an homage to the old school Demoscene of the early 90s.")])]),r._v(" "),t("h2",{attrs:{id:"editors"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#editors"}},[r._v("#")]),r._v(" Editors")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://wasm.fastlylabs.com/",target:"_blank",rel:"noopener noreferrer"}},[r._v("Fastly Terrarium"),t("OutboundLink")],1),t("br"),r._v("\nA compilation toolchain and sandbox to run WebAssembly server-side, with native support for AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://examples.near.org/",target:"_blank",rel:"noopener noreferrer"}},[r._v("NEAR Protocol Examples"),t("OutboundLink")],1),t("br"),r._v("\nExamples that use "),t("a",{attrs:{href:"https://gitpod.io/",target:"_blank",rel:"noopener noreferrer"}},[r._v("GitPod"),t("OutboundLink")],1),r._v(" to develop and deploy distributed web apps using NEAR smart contracts authored in AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://alpha.iodide.io/notebooks/1234",target:"_blank",rel:"noopener noreferrer"}},[r._v("Iodide Notebook"),t("OutboundLink")],1),t("br"),r._v("\nExperimental tool for scientific communication and exploration on the web ("),t("a",{attrs:{href:"https://hacks.mozilla.org/2019/03/iodide-an-experimental-tool-for-scientific-communicatiodide-for-scientific-communication-exploration-on-the-web",target:"_blank",rel:"noopener noreferrer"}},[r._v("more"),t("OutboundLink")],1),r._v(").")])]),r._v(" "),t("h2",{attrs:{id:"formatter"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#formatter"}},[r._v("#")]),r._v(" Formatter")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/HerrCai0907/assemblyscript-prettier",target:"_blank",rel:"noopener noreferrer"}},[r._v("assemblyscript-prettier"),t("OutboundLink")],1),t("br"),r._v("\nPrettier plugin for assemblyscript to resolve the incompatible part of ts and as syntax")])]),r._v(" "),t("h2",{attrs:{id:"emulators"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#emulators"}},[r._v("#")]),r._v(" Emulators")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/torch2424/wasmBoy",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasmBoy"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://wasmboy.app/",target:"_blank",rel:"noopener noreferrer"}},[r._v("demo"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nGame Boy / Game Boy Color Emulator Library, written for WebAssembly using AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ColinEberhardt/atari2600-wasm",target:"_blank",rel:"noopener noreferrer"}},[r._v("Atari 2600"),t("OutboundLink")],1),t("br"),r._v("\nAn Atari 2600 emulator written in AssemblyScript compiled to WebAssembly.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/Dotneteer/as-spectrum-engine",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-spectrum-engine"),t("OutboundLink")],1),t("br"),r._v("\nAssemblyScript implementation of a ZX Spectrum emulator engine.")])]),r._v(" "),t("h2",{attrs:{id:"games"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#games"}},[r._v("#")]),r._v(" Games")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/mhonert/chess",target:"_blank",rel:"noopener noreferrer"}},[r._v("Chess"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://mhonert.github.io/chess",target:"_blank",rel:"noopener noreferrer"}},[r._v("play"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nA free and open source chess game using AssemblyScript and React.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/jolestar/gomoku-wasm",target:"_blank",rel:"noopener noreferrer"}},[r._v("Gomoku WASM"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"http://jolestar.com/gomoku-wasm",target:"_blank",rel:"noopener noreferrer"}},[r._v("play"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nA Gomoku game implements with WebAssembly using "),t("a",{attrs:{href:"https://github.com/as2d/as2d",target:"_blank",rel:"noopener noreferrer"}},[r._v("as2d"),t("OutboundLink")],1),r._v(".")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ttulka/2d-videogame-in-assemblyscript",target:"_blank",rel:"noopener noreferrer"}},[r._v("2d-videogame-in-assemblyscript"),t("OutboundLink")],1),t("br"),r._v("\nDemo 2D videogame in AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ameliabradley/fiberoptic-game",target:"_blank",rel:"noopener noreferrer"}},[r._v("fiberoptic-game"),t("OutboundLink")],1),t("br"),r._v("\nWeb game produced with AssemblyScript for js13k 2018.")])]),r._v(" "),t("h2",{attrs:{id:"graphics-game-frameworks"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#graphics-game-frameworks"}},[r._v("#")]),r._v(" Graphics / Game Frameworks")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/as2d/as2d",target:"_blank",rel:"noopener noreferrer"}},[r._v("as2d"),t("OutboundLink")],1),t("br"),r._v("\n["),t("em",[r._v("Deprecated")]),r._v("] Bring the power of the CanvasRenderingContext2D prototype to AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/mrchantey/koora",target:"_blank",rel:"noopener noreferrer"}},[r._v("koora"),t("OutboundLink")],1),t("br"),r._v("\nAssemblyscript 3D Game Framework.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/01alchemist/as-smallpt",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-smallpt"),t("OutboundLink")],1),t("br"),r._v("\nPort of C++ smallpt, a path tracing renderer.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ycw/Babylon.Font",target:"_blank",rel:"noopener noreferrer"}},[r._v("Babylon.Font"),t("OutboundLink")],1),t("br"),r._v("\nCreate 3d text in BabylonJS.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/Tugcga/Path-Finder/tree/main/assemblyscript",target:"_blank",rel:"noopener noreferrer"}},[r._v("Path-Finder"),t("OutboundLink")],1),t("br"),r._v("\nAssemblyScript NavMesh Path Finder.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/alexvictoor/seam-carving-as",target:"_blank",rel:"noopener noreferrer"}},[r._v("seam-carving-as"),t("OutboundLink")],1),t("br"),r._v("\nSeam Carving experiments with AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/battlelinegames/ASWebGLue",target:"_blank",rel:"noopener noreferrer"}},[r._v("ASWebGLue"),t("OutboundLink")],1),t("br"),r._v("\nWebGL bindings for AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/lume/glas",target:"_blank",rel:"noopener noreferrer"}},[r._v("GLAS"),t("OutboundLink")],1),t("br"),r._v("\nWeb"),t("strong",[r._v("GL")]),r._v(" in "),t("strong",[r._v("A")]),r._v("ssembly"),t("strong",[r._v("S")]),r._v("cript, port of "),t("a",{attrs:{href:"https://github.com/mrdoob/three.js/",target:"_blank",rel:"noopener noreferrer"}},[r._v("Three.js"),t("OutboundLink")],1),r._v(" to AssemblyScript.")])]),r._v(" "),t("h2",{attrs:{id:"data-serialization-deserialization"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#data-serialization-deserialization"}},[r._v("#")]),r._v(" Data Serialization / Deserialization")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/inkeliz/karmem",target:"_blank",rel:"noopener noreferrer"}},[r._v("karmem"),t("OutboundLink")],1),t("br"),r._v("\nKarmem is a fast binary serialization format, faster than Google Flatbuffers and optimized for WebAssembly languages.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/piotr-oles/as-proto",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-proto"),t("OutboundLink")],1),t("br"),r._v("\nProtobuf encoder/decoder library.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/JairusSW/as-json",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-json"),t("OutboundLink")],1),t("br"),r._v("\nJSON encoder / decoder.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/wapc/as-msgpack",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-msgpack"),t("OutboundLink")],1),t("br"),r._v("\nMessagePack package for AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/nearprotocol/assemblyscript-bson",target:"_blank",rel:"noopener noreferrer"}},[r._v("assemblyscript-bson"),t("OutboundLink")],1),t("br"),r._v("\nBSON encoder / decoder.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/nearprotocol/assemblyscript-json",target:"_blank",rel:"noopener noreferrer"}},[r._v("assemblyscript-json"),t("OutboundLink")],1),t("br"),r._v("\nJSON encoder / decoder.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/01alchemist/AS-LZMA",target:"_blank",rel:"noopener noreferrer"}},[r._v("AS-LZMA"),t("OutboundLink")],1),t("br"),r._v("\nLZMA Decoder written in AssemblyScript.")])]),r._v(" "),t("h2",{attrs:{id:"crypto-non-blockchain"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#crypto-non-blockchain"}},[r._v("#")]),r._v(" Crypto (non-blockchain)")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/mjethani/superfasthash",target:"_blank",rel:"noopener noreferrer"}},[r._v("superfasthash"),t("OutboundLink")],1),t("br"),r._v("\nAn implementation of the SuperFastHash non-cryptographic hashing algorithm in JavaScript and WebAssembly.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/jedisct1/wasm-crypto",target:"_blank",rel:"noopener noreferrer"}},[r._v("WASM-Crypto"),t("OutboundLink")],1),t("br"),r._v("\nAn AssemblyScript set of cryptographic primitives for building authentication and key exchange protocols.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/hugomrdias/rabin-wasm",target:"_blank",rel:"noopener noreferrer"}},[r._v("rabin-wasm"),t("OutboundLink")],1),t("br"),r._v("\nRabin fingerprinting implemented in WASM "),t("em",[r._v("(used by js-ipfs)")]),r._v(".")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/krisselden/xoroshiro128starstar",target:"_blank",rel:"noopener noreferrer"}},[r._v("xoroshiro128starstar"),t("OutboundLink")],1),t("br"),r._v("\nAn AssemblyScript port of xoroshiro128starstar.c")])]),r._v(" "),t("h2",{attrs:{id:"fixed-arbitrary-precision-arithmetics"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#fixed-arbitrary-precision-arithmetics"}},[r._v("#")]),r._v(" Fixed & Arbitrary Precision Arithmetics")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/MaxGraey/as-bignum",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-bignum"),t("OutboundLink")],1),t("br"),r._v("\nFixed length big numbers like "),t("code",[r._v("u128")]),r._v(", "),t("code",[r._v("i256")]),r._v(", "),t("code",[r._v("fp128")]),r._v(" and etc for AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/ttulka/as-big",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-big"),t("OutboundLink")],1),t("br"),r._v("\nAn AssemblyScript library for arbitrary-precision decimal arithmetic.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/polywrap/as-bigint",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-bigint"),t("OutboundLink")],1),t("br"),r._v("\nBigInt is an AssemblyScript class for math with arbitrarily large integers.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/polywrap/as-bignumber",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-bignumber"),t("OutboundLink")],1),t("br"),r._v("\nAn AssemblyScript class for math with arbitrary-precision decimal and integer numbers.")])]),r._v(" "),t("h2",{attrs:{id:"language-extensions-and-types"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#language-extensions-and-types"}},[r._v("#")]),r._v(" Language Extensions and Types")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/yjhmelody/as-container",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-container"),t("OutboundLink")],1),r._v(" "),t("br"),r._v("\nAssemblyScript version of Rust Option and Result etc.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/MaxGraey/as-variant",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-variant"),t("OutboundLink")],1),t("br"),r._v("\nVariant (aka Any) data type for AssemblyScript.")])]),r._v(" "),t("h2",{attrs:{id:"bindings"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#bindings"}},[r._v("#")]),r._v(" Bindings")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/lume/asdom",target:"_blank",rel:"noopener noreferrer"}},[r._v("asdom"),t("OutboundLink")],1),t("br"),r._v("\nDOM bindings for AssemblyScript.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/aspkg/ecmassembly",target:"_blank",rel:"noopener noreferrer"}},[r._v("ecmassembly"),t("OutboundLink")],1),t("br"),r._v("\nBindings for common ECMAScript/JavaScript APIs that require host scheduling ("),t("code",[r._v("setTimeout")]),r._v(", "),t("code",[r._v("Promise")]),r._v(", etc).")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/miracle2k/wasmbind",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasmbind"),t("OutboundLink")],1),t("br"),r._v("\nWork with AssemblyScript memory and classes from Python.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/torch2424/as-bind",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-bind"),t("OutboundLink")],1),t("br"),r._v("\n["),t("em",[r._v("Deprecated")]),r._v("] Isomorphic library to handle passing high-level data structures between AssemblyScript and JavaScript, built on top of the AssemblyScript loader.")])]),r._v(" "),t("h2",{attrs:{id:"other-libraries"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#other-libraries"}},[r._v("#")]),r._v(" Other Libraries")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/samchon/astl",target:"_blank",rel:"noopener noreferrer"}},[r._v("ASTL"),t("OutboundLink")],1),t("br"),r._v("\n["),t("em",[r._v("Deprecated")]),r._v("] Migration project from C++ STL (Standard Template Library) to AssemblyScript. Containers, iterators, algorithms and functors are supported.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/kyranet/levenshtein-wasm",target:"_blank",rel:"noopener noreferrer"}},[r._v("Levenshtein Wasm"),t("OutboundLink")],1),t("br"),r._v("\nAn experimental lightning-fast Wasm-compiled levenshtein library.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/jedisct1/as-wasi",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-wasi"),t("OutboundLink")],1),t("br"),r._v("\nAn AssemblyScript API layer for WASI system calls.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/GuildOfWeavers/galois",target:"_blank",rel:"noopener noreferrer"}},[r._v("galois"),t("OutboundLink")],1),t("br"),r._v("\nArithmetic and polynomial operations in finite fields.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/GuildOfWeavers/merkle",target:"_blank",rel:"noopener noreferrer"}},[r._v("merkle"),t("OutboundLink")],1),t("br"),r._v("\nMerkle tree and other data structures.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/jamesmilneruk/pixelmatch-asc",target:"_blank",rel:"noopener noreferrer"}},[r._v("pixelmatch-asc"),t("OutboundLink")],1),t("br"),r._v("\nPixel level image comparison library.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/onsails/wasmer-as",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasmer-as"),t("OutboundLink")],1),t("br"),r._v("\nHelpers for dealing with assemblyscript memory inside wasmer-runtime.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/poria-cat/wasmer3-assemblyscript-example",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasmer3-as"),t("OutboundLink")],1),t("br"),r._v("\nExamples of lift string and lower string in wasmer 3.0")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/wasmerio/io-devices-lib",target:"_blank",rel:"noopener noreferrer"}},[r._v("io-devices-lib"),t("OutboundLink")],1),t("br"),r._v("\nLibrary for interacting with the Wasmer Experimental IO Devices.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/MaxGraey/as-string-sink",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-string-sink"),t("OutboundLink")],1),t("br"),r._v("\nAn efficient dynamically sized string buffer (aka String Builder) for AssemblyScript.")])]),r._v(" "),t("h2",{attrs:{id:"embedded-iot"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#embedded-iot"}},[r._v("#")]),r._v(" Embedded / IoT")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/wasm3/wasm3-arduino/tree/main/wasm_apps",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasm3-arduino"),t("OutboundLink")],1),t("br"),r._v("\nUsage example with wasm3 which run on Arduino, PlatformIO, Particle.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/vshymanskyy/Wasm3_RGB_Lamp",target:"_blank",rel:"noopener noreferrer"}},[r._v("Wasm3_RGB_Lamp"),t("OutboundLink")],1),t("br"),r._v("\nAnimating an RGB lamp, using WebAssembly (AssemblyScript).")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/alvarowolfx/wasm-arduino-wifi",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasm-arduino-wifi"),t("OutboundLink")],1),t("br"),r._v("\nExample how update WebAssembly via WiFi on arduino.")])]),r._v(" "),t("h2",{attrs:{id:"testing-benchmarking"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#testing-benchmarking"}},[r._v("#")]),r._v(" Testing / Benchmarking")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/romdotdog/as-tral",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-tral"),t("OutboundLink")],1),t("br"),r._v("\nAssemblyScript benchmarking library inspired by criterion.rs. (Required AssemblyScript >= 0.20)")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/jtenner/as-pect",target:"_blank",rel:"noopener noreferrer"}},[r._v("as-pect"),t("OutboundLink")],1),t("br"),r._v("\nA test framework inspired by jest. (Required AssemblyScript <= 0.19)")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/jtenner/envy",target:"_blank",rel:"noopener noreferrer"}},[r._v("envy"),t("OutboundLink")],1),t("br"),r._v("\nA test framework spiritual successor of as-pect. (Required AssemblyScript >= 0.20)")])]),r._v(" "),t("h2",{attrs:{id:"project-templates"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#project-templates"}},[r._v("#")]),r._v(" Project Templates")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/JamesLMilner/worker-assemblyscript-template",target:"_blank",rel:"noopener noreferrer"}},[r._v("worker-assemblyscript-template"),t("OutboundLink")],1),t("br"),r._v("\nA Cloudflare wrangler template for an AssemblyScript worker.")])]),r._v(" "),t("h2",{attrs:{id:"applications"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#applications"}},[r._v("#")]),r._v(" Applications")]),r._v(" "),t("ul",[t("li",[t("a",{attrs:{href:"https://github.com/torch2424/wasm-matrix",target:"_blank",rel:"noopener noreferrer"}},[r._v("wasm-matrix"),t("OutboundLink")],1),t("br"),r._v("\nA Matrix effect in your terminal using AssemblyScript and WASI, deployed to WAPM.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://petersalomonsen.com",target:"_blank",rel:"noopener noreferrer"}},[r._v("WebAssembly music experiment"),t("OutboundLink")],1),t("br"),r._v("\nA live coding environment in the browser for sequencing music with javascript and synthesizing instruments in AssemblyScript. Demonstrates compiling AssemblyScript directly in the browser, and live hot-swapping of webassembly modules.")]),r._v(" "),t("li",[t("a",{attrs:{href:"https://github.com/dested/WireWorld",target:"_blank",rel:"noopener noreferrer"}},[r._v("WireWorld"),t("OutboundLink")],1),r._v(" ("),t("a",{attrs:{href:"https://dested.com/projects/wire/",target:"_blank",rel:"noopener noreferrer"}},[r._v("demo"),t("OutboundLink")],1),r._v(")"),t("br"),r._v("\nThe Wireworld Computer in Javascript/Canvas.")])])])}),[],!1,null,null,null);e.default=n.exports}}]); \ No newline at end of file diff --git a/assets/js/22.79ff9157.js b/assets/js/22.79ff9157.js new file mode 100644 index 000000000..0930307b6 --- /dev/null +++ b/assets/js/22.79ff9157.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[22],{225:function(t,s,e){"use strict";e.r(s);var a=e(6),n=Object(a.a)({},(function(){var t=this,s=t.$createElement,e=t._self._c||s;return e("ContentSlotsDistributor",{attrs:{"slot-key":t.$parent.slotKey}},[e("h1",{attrs:{id:"using-the-compiler"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#using-the-compiler"}},[t._v("#")]),t._v(" Using the compiler")]),t._v(" "),e("p",[t._v("Similar to TypeScript's "),e("code",[t._v("tsc")]),t._v(" transpiling to JavaScript, AssemblyScript's "),e("code",[t._v("asc")]),t._v(" compiles to WebAssembly.")]),t._v(" "),e("h2",{attrs:{id:"compiler-options"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#compiler-options"}},[t._v("#")]),t._v(" Compiler options")]),t._v(" "),e("p",[t._v("The compiler supports various options available on the command line, in a configuration file and programmatically. On the command line, it looks like this:")]),t._v(" "),e("h3",{attrs:{id:"entry-file-s"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#entry-file-s"}},[t._v("#")]),t._v(" Entry file(s)")]),t._v(" "),e("p",[t._v("Non-option arguments are treated as the names of entry files. A single program can have multiple entries, with the exports of each entry becoming the exports of the WebAssembly module. Exports of imported files that are not entry files do not become WebAssembly module exports.")]),t._v(" "),e("div",{staticClass:"language-sh extra-class"},[e("pre",{pre:!0,attrs:{class:"language-sh"}},[e("code",[t._v("asc entryFile.ts\n")])])]),e("h3",{attrs:{id:"general"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#general"}},[t._v("#")]),t._v(" General")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--version, -v Prints just the compiler's version and exits.\n--help, -h Prints this message and exits.\n--config Configuration file to apply. CLI arguments take precedence.\n--target Configuration file target to use. Defaults to 'release'.\n")])])]),e("h3",{attrs:{id:"optimization"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#optimization"}},[t._v("#")]),t._v(" Optimization")]),t._v(" "),e("p",[t._v("The compiler can optimize for both speed ("),e("code",[t._v("-Ospeed")]),t._v(") and size ("),e("code",[t._v("-Osize")]),t._v("), as well as produce a debug build ("),e("code",[t._v("--debug")]),t._v(").")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--optimize, -O Optimizes the module. Typical shorthands are:\n\n Default optimizations -O\n Make a release build -O --noAssert\n Make a debug build --debug\n Optimize for speed -Ospeed\n Optimize for size -Osize\n\n--optimizeLevel How much to focus on optimizing code. [0-3]\n--shrinkLevel How much to focus on shrinking code size. [0-2, s=1, z=2]\n--converge Re-optimizes until no further improvements can be made.\n--noAssert Replaces assertions with just their value without trapping.\n--uncheckedBehavior Changes the behavior of unchecked() expressions.\n Using this option can potentially cause breakage.\n\n default The default behavior: unchecked operations are\n only used inside of unchecked().\n never Unchecked operations are never used, even when,\n inside of unchecked().\n always Unchecked operations are always used if possible,\n whether or not unchecked() is used.\n\n")])])]),e("p",[t._v("Optimization levels can also be tweaked manually: "),e("code",[t._v("--optimizeLevel")]),t._v(" (0-3) indicates how much the compiler focuses on optimizing the code with "),e("code",[t._v("--shrinkLevel")]),t._v(" (0-2, 1=s, 2=z) indicating how much it focuses on keeping the size low during code generation and while optimizing. A shorthand for both is "),e("code",[t._v("-O[optimizeLevel][shrinkLevel]")]),t._v(" , with shrink level indicated by optionally appending the letter "),e("code",[t._v("s")]),t._v(" (1) or "),e("code",[t._v("z")]),t._v(" (2).")]),t._v(" "),e("h3",{attrs:{id:"output"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#output"}},[t._v("#")]),t._v(" Output")]),t._v(" "),e("p",[t._v("Typical output formats are WebAssembly binary (.wasm, "),e("code",[t._v("--outFile")]),t._v(") and/or text format (.wat, "),e("code",[t._v("--textFile")]),t._v("). Often, both are used in tandem to run and also inspect generated code.")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--outFile, -o Specifies the WebAssembly output file (.wasm).\n--textFile, -t Specifies the WebAssembly text output file (.wat).\n--bindings, -b Specifies the bindings to generate (.js + .d.ts).\n\n esm JavaScript bindings & typings for ESM integration.\n raw Like esm, but exports just the instantiate function.\n Useful where modules are meant to be instantiated\n multiple times or non-ESM imports must be provided.\n")])])]),e("h3",{attrs:{id:"debugging"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#debugging"}},[t._v("#")]),t._v(" Debugging")]),t._v(" "),e("p",[t._v("For easier debugging during development, a "),e("a",{attrs:{href:"#source-maps"}},[t._v("source map")]),t._v(" can be emitted alongside the WebAssembly binary, and debug symbols can be embedded:")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--sourceMap Enables source map generation. Optionally takes the URL\n used to reference the source map from the binary file.\n--debug Enables debug information in emitted binaries.\n")])])]),e("h3",{attrs:{id:"features"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#features"}},[t._v("#")]),t._v(" Features")]),t._v(" "),e("p",[t._v("There are several flags that enable or disable specific WebAssembly or compiler features. By default, only the bare minimum is exposed, and fully standardized WebAssembly features will be used.")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--importMemory Imports the memory from 'env.memory'.\n--noExportMemory Does not export the memory as 'memory'.\n--initialMemory Sets the initial memory size in pages.\n--maximumMemory Sets the maximum memory size in pages.\n--sharedMemory Declare memory as shared. Requires maximumMemory.\n--zeroFilledMemory Assume imported memory is zeroed. Requires importMemory.\n--importTable Imports the function table from 'env.table'.\n--exportTable Exports the function table as 'table'.\n--exportStart Exports the start function using the specified name instead\n of calling it implicitly. Useful for WASI or to obtain the\n exported memory before executing any code accessing it.\n--runtime Specifies the runtime variant to include in the program.\n\n incremental TLSF + incremental GC (default)\n minimal TLSF + lightweight GC invoked externally\n stub Minimal runtime stub (never frees)\n ... Path to a custom runtime implementation\n\n--exportRuntime Always exports the runtime helpers (__new, __collect, __pin etc.).\n Automatically determined when generation of --bindings is enabled.\n--stackSize Overrides the stack size. Only relevant for incremental GC\n or when using a custom runtime that requires stack space.\n Defaults to 0 without and to 16384 with incremental GC.\n--enable Enables WebAssembly features being disabled by default.\n\n threads Threading and atomic operations.\n simd SIMD types and operations.\n reference-types Reference types and operations.\n gc Garbage collection (WIP).\n stringref String reference types.\n relaxed-simd Relaxed SIMD operations.\n\n--disable Disables WebAssembly features being enabled by default.\n\n mutable-globals Mutable global imports and exports.\n sign-extension Sign-extension operations\n nontrapping-f2i Non-trapping float to integer ops.\n bulk-memory Bulk memory operations.\n\n--use, -u Aliases a global object under another name, e.g., to switch\n the default 'Math' implementation used: --use Math=JSMath\n Can also be used to introduce an integer constant.\n--lowMemoryLimit Enforces very low (<64k) memory constraints.\n")])])]),e("h3",{attrs:{id:"linking"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#linking"}},[t._v("#")]),t._v(" Linking")]),t._v(" "),e("p",[t._v("Specifying the base offsets of compiler-generated memory respectively the table leaves some space for other data in front. In its current form this is mostly useful to link additional data into an AssemblyScript binary after compilation, be it by populating the binary itself or initializing the data externally upon initialization. One good example is leaving some scratch space for a frame buffer.")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--memoryBase Sets the start offset of emitted memory segments.\n--tableBase Sets the start offset of emitted table elements.\n")])])]),e("h3",{attrs:{id:"api"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#api"}},[t._v("#")]),t._v(" API")]),t._v(" "),e("p",[t._v("To integrate with the compiler, for example to post-process the AST, one or multiple custom "),e("a",{attrs:{href:"#transforms"}},[t._v("transforms")]),t._v(" can be specified.")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--transform Specifies the path to a custom transform to load.\n")])])]),e("h3",{attrs:{id:"other"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#other"}},[t._v("#")]),t._v(" Other")]),t._v(" "),e("p",[t._v("Other options include those forwarded to Binaryen and various flags useful in certain situations.")]),t._v(" "),e("h4",{attrs:{id:"binaryen"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#binaryen"}},[t._v("#")]),t._v(" Binaryen")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--trapMode Sets the trap mode to use.\n\n allow Allow trapping operations. This is the default.\n clamp Replace trapping operations with clamping semantics.\n js Replace trapping operations with JS semantics.\n\n--runPasses Specifies additional Binaryen passes to run after other\n optimizations, if any. See: Binaryen/src/passes/pass.cpp\n--noValidate Skips validating the module using Binaryen.\n")])])]),e("h4",{attrs:{id:"and-the-kitchen-sink"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#and-the-kitchen-sink"}},[t._v("#")]),t._v(" And the kitchen sink")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("--baseDir Specifies the base directory of input and output files.\n--noColors Disables terminal colors.\n--noUnsafe Disallows the use of unsafe features in user code.\n Does not affect library files and external modules.\n--disableWarning Disables warnings matching the given diagnostic code.\n If no diagnostic code is given, all warnings are disabled.\n--noEmit Performs compilation as usual but does not emit code.\n--stats Prints statistics on I/O and compile times.\n--pedantic Make yourself sad for no good reason.\n--lib Adds one or multiple paths to custom library components and\n uses exports of all top-level files at this path as globals.\n--path Adds one or multiple paths to package resolution, similar\n to node_modules. Prefers an 'ascMain' entry in a package's\n package.json and falls back to an inner 'assembly/' folder.\n--wasm Uses the specified Wasm binary of the compiler.\n-- ... Specifies node.js options (CLI only). See: node --help\n")])])]),e("h2",{attrs:{id:"configuration-file"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#configuration-file"}},[t._v("#")]),t._v(" Configuration file")]),t._v(" "),e("p",[t._v("Instead of providing the options outlined above on the command line, a configuration file typically named "),e("strong",[t._v("asconfig.json")]),t._v(" can be used. It may look like in the following example, excluding comments:")]),t._v(" "),e("div",{staticClass:"language-json extra-class"},[e("pre",{pre:!0,attrs:{class:"language-json"}},[e("code",[e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"extends"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./path/to/other/asconfig.json"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// (optional) base config")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"entries"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("[")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// (optional) entry files, e.g.")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./assembly/index.ts"')]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("]")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"options"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// common options, e.g.")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"importTable"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token boolean"}},[t._v("true")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"targets"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// (optional) targets")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"release"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v('// additional options for the "release" target, e.g.')]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"optimize"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token boolean"}},[t._v("true")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"outFile"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"myModule.release.wasm"')]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"debug"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v('// additional options for the "debug" target, e.g.')]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"debug"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token boolean"}},[t._v("true")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token property"}},[t._v('"outFile"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"myModule.debug.wasm"')]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),e("p",[t._v("Per-target options, e.g. "),e("code",[t._v("targets.release")]),t._v(", add to and override top-level "),e("code",[t._v("options")]),t._v(". Options provided on the command line override any options in the configuration file. Usage is, for example:")]),t._v(" "),e("div",{staticClass:"language-sh extra-class"},[e("pre",{pre:!0,attrs:{class:"language-sh"}},[e("code",[t._v("asc --config asconfig.json --target release\n")])])]),e("h2",{attrs:{id:"programmatic-usage"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#programmatic-usage"}},[t._v("#")]),t._v(" Programmatic usage")]),t._v(" "),e("p",[t._v("The compiler API can also be used programmatically:")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" asc "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"assemblyscript/asc"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" error"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" stdout"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" stderr"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" stats "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("await")]),t._v(" asc"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("main")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("[")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// Command line options")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"myModule.ts"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"--outFile"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"myModule.wasm"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"--optimize"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"--sourceMap"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"--stats"')]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("]")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// Additional API options")]),t._v("\n stdout"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n stderr"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n readFile"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n writeFile"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n listFiles"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n reportDiagnostic"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n transforms"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("if")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("error"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n console"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("log")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"Compilation failed: "')]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" error"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("message"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n console"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("log")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("stderr"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("toString")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("else")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n console"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("log")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("stdout"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("toString")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),e("p",[t._v("The compiler runs in browsers as well. The simplest way to set it up is to include the generated "),e("a",{attrs:{href:"https://cdn.jsdelivr.net/npm/assemblyscript@latest/dist/web.js",target:"_blank",rel:"noopener noreferrer"}},[t._v("web.js"),e("OutboundLink")],1),t._v(" so the compiler can be used with an "),e("code",[t._v("import")]),t._v(" on the Web:")]),t._v(" "),e("div",{staticClass:"language-html extra-class"},[e("pre",{pre:!0,attrs:{class:"language-html"}},[e("code",[e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("<")]),t._v("script")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token attr-name"}},[t._v("src")]),e("span",{pre:!0,attrs:{class:"token attr-value"}},[e("span",{pre:!0,attrs:{class:"token punctuation attr-equals"}},[t._v("=")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v('"')]),t._v("https://cdn.jsdelivr.net/npm/assemblyscript@x.x.x/dist/web.js"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v('"')])]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(">")])]),e("span",{pre:!0,attrs:{class:"token script"}}),e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("")])]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("<")]),t._v("script")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token attr-name"}},[t._v("type")]),e("span",{pre:!0,attrs:{class:"token attr-value"}},[e("span",{pre:!0,attrs:{class:"token punctuation attr-equals"}},[t._v("=")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v('"')]),t._v("module"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v('"')])]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(">")])]),e("span",{pre:!0,attrs:{class:"token script"}},[e("span",{pre:!0,attrs:{class:"token language-javascript"}},[t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" asc "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"assemblyscript/asc"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v("\n")])]),e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token tag"}},[e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("")])]),t._v("\n")])])]),e("p",[t._v("Here, "),e("code",[t._v("x.x.x")]),t._v(" must be replaced with the "),e("a",{attrs:{href:"https://github.com/AssemblyScript/assemblyscript/tags",target:"_blank",rel:"noopener noreferrer"}},[t._v("respective version to use"),e("OutboundLink")],1),t._v(", or "),e("code",[t._v("latest")]),t._v(" to always use the latest version (not recommended in production). By default, the script installs "),e("a",{attrs:{href:"https://cdn.jsdelivr.net/npm/assemblyscript@latest/dist/importmap.json",target:"_blank",rel:"noopener noreferrer"}},[t._v("the necessary import map"),e("OutboundLink")],1),t._v(" and, for browsers that do not yet support import maps, "),e("a",{attrs:{href:"https://github.com/guybedford/es-module-shims",target:"_blank",rel:"noopener noreferrer"}},[t._v("an import map shim"),e("OutboundLink")],1),t._v(". It also accepts the following options in case there is a need to only perform part of the setup:")]),t._v(" "),e("table",[e("thead",[e("tr",[e("th",[t._v("Script URL")]),t._v(" "),e("th",[t._v("Effect")])])]),t._v(" "),e("tbody",[e("tr",[e("td",[e("code",[t._v("web.js?noinstall")])]),t._v(" "),e("td",[t._v("Does not install the import map.")])]),t._v(" "),e("tr",[e("td",[e("code",[t._v("web.js?noshim")])]),t._v(" "),e("td",[t._v("Does not install the import map shim.")])]),t._v(" "),e("tr",[e("td",[e("code",[t._v("web.js?noinstall,noshim")])]),t._v(" "),e("td",[t._v("Does not install the import map or shim.")])])])]),t._v(" "),e("p",[t._v("Regardless of the options used, the script always declares the following global variables:")]),t._v(" "),e("table",[e("thead",[e("tr",[e("th",[t._v("Variable")]),t._v(" "),e("th",[t._v("Description")])])]),t._v(" "),e("tbody",[e("tr",[e("td",[e("code",[t._v("ASSEMBLYSCRIPT_VERSION")])]),t._v(" "),e("td",[t._v("Version string of the compiler release used")])]),t._v(" "),e("tr",[e("td",[e("code",[t._v("ASSEMBLYSCRIPT_IMPORTMAP")])]),t._v(" "),e("td",[t._v("The respective import map of the release as JSON")])])])]),t._v(" "),e("h2",{attrs:{id:"host-bindings"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#host-bindings"}},[t._v("#")]),t._v(" Host bindings")]),t._v(" "),e("p",[t._v("WebAssembly alone cannot yet transfer higher level data types like strings, arrays and objects over module boundaries, so for now some amount of glue code is required to exchange these data structures with the host / JavaScript.")]),t._v(" "),e("p",[t._v("The compiler can generate the necessary bindings using the "),e("code",[t._v("--bindings")]),t._v(" command line option (either as an ES module or a raw instantiate function), enabling exchange of:")]),t._v(" "),e("table",[e("thead",[e("tr",[e("th",[t._v("Type")]),t._v(" "),e("th",[t._v("Strategy")]),t._v(" "),e("th",[t._v("Description")])])]),t._v(" "),e("tbody",[e("tr",[e("td",[t._v("Number")]),t._v(" "),e("td",[t._v("By value")]),t._v(" "),e("td",[t._v("Basic numeric types except 64-bit integers.")])]),t._v(" "),e("tr",[e("td",[t._v("BigInt")]),t._v(" "),e("td",[t._v("By value")]),t._v(" "),e("td",[t._v("64-bit integers via js-bigint-integration.")])]),t._v(" "),e("tr",[e("td",[t._v("Boolean")]),t._v(" "),e("td",[t._v("By value")]),t._v(" "),e("td",[t._v("Coerced to "),e("code",[t._v("true")]),t._v(" or "),e("code",[t._v("false")]),t._v(".")])]),t._v(" "),e("tr",[e("td",[t._v("Externref")]),t._v(" "),e("td",[t._v("By reference")]),t._v(" "),e("td",[t._v("Using reference-types.")])]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("String")])]),t._v(" "),e("td",[t._v("Copy")]),t._v(" "),e("td")]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("ArrayBuffer")])]),t._v(" "),e("td",[t._v("Copy")]),t._v(" "),e("td")]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("TypedArray")])]),t._v(" "),e("td",[t._v("Copy")]),t._v(" "),e("td",[t._v("Any "),e("code",[t._v("Int8Array")]),t._v(", "),e("code",[t._v("Float64Array")]),t._v(" etc.")])]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("Array")])]),t._v(" "),e("td",[t._v("Copy")]),t._v(" "),e("td",[t._v("Any "),e("code",[t._v("Array")])])]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("StaticArray")])]),t._v(" "),e("td",[t._v("Copy")]),t._v(" "),e("td",[t._v("Any "),e("code",[t._v("StaticArray")])])]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("Object")])]),t._v(" "),e("td",[t._v("Copy")]),t._v(" "),e("td",[t._v("If a plain object. That is: Has no constructor or non-public fields.")])]),t._v(" "),e("tr",[e("td",[e("strong",[t._v("Object")])]),t._v(" "),e("td",[t._v("By reference")]),t._v(" "),e("td",[t._v("If not a plain object. Passed as an opaque reference counted pointer.")])])])]),t._v(" "),e("p",[t._v("Note the two different strategies used for "),e("strong",[t._v("Object")]),t._v(": In some situations, say when calling a Web API, it may be preferable to copy the object as a whole, field by field, which is the strategy chosen for plain objects with no constructor or non-public fields:")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// Copied to a JS object")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("class")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token class-name"}},[t._v("PlainObject")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n field"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("getObject")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" PlainObject "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("return")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n field"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"hello world"')]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),e("p",[t._v("However, copying may not be desirable in every situation, say when individual object properties are meant to be modified externally where serializing/deserializing the object as a whole would result in unnecessary overhead. To support this use case, the compiler can pass just an opaque reference to the object, which can be enforced by providing an empty "),e("code",[t._v("constructor")]),t._v(" (not a plain object anymore):")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// Not copied to a JS object")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("class")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token class-name"}},[t._v("ComplexObject")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("constructor")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// !")]),t._v("\n field"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("null")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("newObject")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" ComplexObject "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("return")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("new")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token class-name"}},[t._v("ComplexObject")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("setObjectField")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("target"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" ComplexObject"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" field"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("null")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n target"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("field "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" field"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("getObjectField")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("target"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" ComplexObject"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("null")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("return")]),t._v(" target"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("field"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),e("p",[t._v("Also note that exporting an entire "),e("code",[t._v("class")]),t._v(" has no effect at the module boundary (yet), and it is instead recommended to expose only the needed functionality as shown in the example above. Supported elements at the boundary are globals, functions and enums.")]),t._v(" "),e("h3",{attrs:{id:"using-esm-bindings"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#using-esm-bindings"}},[t._v("#")]),t._v(" Using ESM bindings")]),t._v(" "),e("p",[t._v("Bindings generated with "),e("code",[t._v("--bindings esm")]),t._v(" perform all the steps from compilation over instantiation to exporting the final interface. To do so, a few assumptions had to be made:")]),t._v(" "),e("ul",[e("li",[e("p",[t._v("The WebAssembly binary is located next to the JavaScript bindings file using the same name but with a "),e("code",[t._v(".wasm")]),t._v(" extension.")]),t._v(" "),e("div",{staticClass:"language- extra-class"},[e("pre",{pre:!0,attrs:{class:"language-text"}},[e("code",[t._v("build/mymodule.js\nbuild/mymodule.wasm\n")])])]),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("*")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("as")]),t._v(" myModule "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./build/mymodule.js"')]),t._v("\n")])])])]),t._v(" "),e("li",[e("p",[t._v("JavaScript globals in "),e("code",[t._v("globalThis")]),t._v(" can be accessed directly via the "),e("code",[t._v("env")]),t._v(" module namespace. For example, "),e("code",[t._v("console.log")]),t._v(" can be manually imported through:")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token decorator"}},[e("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("external")])]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"env"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"console.log"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("declare")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("consoleLog")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("s"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),e("p",[t._v("Note that this is just an example and "),e("code",[t._v("console.log")]),t._v(" is already provided by the standard library when called from an AssemblyScript file. Other global functions not already provided by the standard library may require an import as of this example, though.")])]),t._v(" "),e("li",[e("p",[t._v("Imports from other namespaces than "),e("code",[t._v("env")]),t._v(", i.e. "),e("code",[t._v('(import "module" "name")')]),t._v(", become an "),e("code",[t._v('import { name } from "module"')]),t._v(" within the binding. Importing a custom function from a JavaScript file next to the bindings file can be achieved through:")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token decorator"}},[e("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("external")])]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./otherfile.js"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"myFunction"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("declare")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("myFunction")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v("\n")])])]),e("p",[t._v("Similarly, importing a custom function from, say, a Node.js dependency can be achieved through:")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token decorator"}},[e("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("external")])]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"othermodule"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"myFunction"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("declare")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("myFunction")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v("\n")])])])])]),t._v(" "),e("p",[t._v("These assumptions cannot be intercepted or customized since, to provide static ESM exports from the bindings file directly, instantiation must start immediately when the bindings file is imported. If customization is required, "),e("code",[t._v("--bindings raw")]),t._v(" can be used instead.")]),t._v(" "),e("h3",{attrs:{id:"using-raw-bindings"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#using-raw-bindings"}},[t._v("#")]),t._v(" Using raw bindings")]),t._v(" "),e("p",[t._v("The signature of the single "),e("code",[t._v("instantiate")]),t._v(" function exported by "),e("code",[t._v("--bindings raw")]),t._v(" is:")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("async")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("instantiate")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("module"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" WebAssembly"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Module"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" imports"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" WebAssembly"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Imports"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" AdaptedExports\n")])])]),e("p",[t._v("Note that the function does not make any assumptions on how the module is to be compiled, but instead expects a readily compiled "),e("code",[t._v("WebAssembly.Module")]),t._v(" as in this example:")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" instantiate "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./module.js"')]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" exports "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("await")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("instantiate")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("await")]),t._v(" WebAssembly"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("compileStreaming")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("fetch")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./module.wasm"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("/* imports */")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),e("p",[t._v("Unlike "),e("code",[t._v("--bindings esm")]),t._v(", raw bindings also do not make any assumptions on how imports are resolved, so these must be provided manually as part of the imports object. For example, to achieve a similar result as with ESM bindings, but now customizable:")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" instantiate "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./module.js"')]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("*")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("as")]),t._v(" other "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./otherfile.js"')]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n export1"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n export2"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("await")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("instantiate")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("await")]),t._v(" WebAssembly"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("compileStreaming")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("fetch")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./module.wasm"')]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token string-property property"}},[t._v('"./otherfile.js"')]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" other\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),e("h2",{attrs:{id:"debugging-2"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#debugging-2"}},[t._v("#")]),t._v(" Debugging")]),t._v(" "),e("p",[t._v("The debugging workflow is similar to debugging JavaScript since both Wasm and JS execute in the same engine, and the compiler provides various options to set up additional WebAssembly-specific debug information. Note that any sort of optimization should be disabled in debug builds.")]),t._v(" "),e("h3",{attrs:{id:"debug-symbols"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#debug-symbols"}},[t._v("#")]),t._v(" Debug symbols")]),t._v(" "),e("p",[t._v("When compiling with the "),e("code",[t._v("--debug")]),t._v(" option, the compiler appends a name section to the binary, containing names of functions, globals, locals and so on. These names will show up in stack traces.")]),t._v(" "),e("h3",{attrs:{id:"source-maps"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#source-maps"}},[t._v("#")]),t._v(" Source maps")]),t._v(" "),e("p",[t._v("The compiler can generate a source map alongside a binary using the "),e("code",[t._v("--sourceMap")]),t._v(" option. By default, a relative source map path will be embedded in the binary which browsers can pick up when instantiating a module from a "),e("code",[t._v("fetch")]),t._v(" response. In environments that do not provide "),e("code",[t._v("fetch")]),t._v(" or an equivalent mechanism, like in Node.js, it is alternatively possible to embed an absolute source map path through "),e("code",[t._v("--sourceMap path/to/source/map")]),t._v(".")]),t._v(" "),e("h3",{attrs:{id:"breakpoints"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#breakpoints"}},[t._v("#")]),t._v(" Breakpoints")]),t._v(" "),e("p",[t._v("Some JavaScript engines also support adding break points directly in WebAssembly code. Please consult your engine's documentation: "),e("a",{attrs:{href:"https://developers.google.com/web/tools/chrome-devtools/javascript/breakpoints",target:"_blank",rel:"noopener noreferrer"}},[t._v("Chrome"),e("OutboundLink")],1),t._v(", "),e("a",{attrs:{href:"https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Set_a_breakpoint",target:"_blank",rel:"noopener noreferrer"}},[t._v("Firefox"),e("OutboundLink")],1),t._v(", "),e("a",{attrs:{href:"https://nodejs.org/api/debugger.html",target:"_blank",rel:"noopener noreferrer"}},[t._v("Node.js"),e("OutboundLink")],1),t._v(", "),e("a",{attrs:{href:"https://support.apple.com/de-de/guide/safari-developer/dev5e4caf347/mac",target:"_blank",rel:"noopener noreferrer"}},[t._v("Safari"),e("OutboundLink")],1),t._v(".")]),t._v(" "),e("h2",{attrs:{id:"transforms"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#transforms"}},[t._v("#")]),t._v(" Transforms")]),t._v(" "),e("p",[t._v("AssemblyScript is compiled statically, so code transformation cannot be done at runtime but must instead be performed at compile-time. To enable this, the compiler frontend (asc) provides a mechanism to hook into the compilation process before, while and after the module is being compiled.")]),t._v(" "),e("p",[t._v("Specifying "),e("code",[t._v("--transform ./myTransform.js")]),t._v(" on the command line will load the node module pointed to by "),e("code",[t._v("./myTransform.js")]),t._v(".")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("*")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("as")]),t._v(" assemblyscript "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"assemblyscript"')]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" Transform "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"assemblyscript/transform"')]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("class")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token class-name"}},[t._v("MyTransform")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("extends")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token class-name"}},[t._v("Transform")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("default")]),t._v(" MyTransform\n")])])]),e("h3",{attrs:{id:"properties"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#properties"}},[t._v("#")]),t._v(" Properties")]),t._v(" "),e("p",[t._v("A transform is an ES6 class/node module with the following inherited properties:")]),t._v(" "),e("ul",[e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("readonly")]),t._v(" program"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" Program\n")])])]),e("p",[t._v("Reference to the "),e("code",[t._v("Program")]),t._v(" instance.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("readonly")]),t._v(" baseDir"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),t._v("\n")])])]),e("p",[t._v("Base directory used by the compiler.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("readonly")]),t._v(" stdout"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" OutputStream\n")])])]),e("p",[t._v("Output stream used by the compiler.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("readonly")]),t._v(" stderr"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" OutputStream\n")])])]),e("p",[t._v("Error stream uses by the compiler.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("readonly")]),t._v(" log"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("typeof")]),t._v(" console"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("log\n")])])]),e("p",[t._v("Logs a message to console.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("writeFile")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("filename"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" contents"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("Uint8Array")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" baseDir"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("boolean")]),t._v("\n")])])]),e("p",[t._v("Writes a file to disk.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("readFile")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("filename"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" baseDir"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("null")]),t._v("\n")])])]),e("p",[t._v("Reads a file from disk.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("listFiles")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("dirname"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" baseDir"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("[")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("]")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("null")]),t._v("\n")])])]),e("p",[t._v("Lists all files in a directory.")])])]),t._v(" "),e("h3",{attrs:{id:"hooks"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#hooks"}},[t._v("#")]),t._v(" Hooks")]),t._v(" "),e("p",[t._v("The frontend will call several hooks, if present on the transform, during the compilation process:")]),t._v(" "),e("ul",[e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("afterParse")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("parser"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" Parser"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),e("p",[t._v("Called when parsing is complete, before a program is initialized from the AST. Note that types are not yet known at this stage and there is no easy way to obtain them.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("afterInitialize")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("program"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" Program"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),e("p",[t._v("Called once the program is initialized, before it is being compiled. Types are known at this stage, respectively can be resolved where necessary.")])]),t._v(" "),e("li",[e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("afterCompile")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("module"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" Module"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),e("p",[t._v("Called with the resulting module before it is being emitted. Useful to modify the IR before writing any output, for example to replace imports with actual functionality or to add custom sections.")])])]),t._v(" "),e("p",[t._v("Transforms are a very powerful feature, but may require profound knowledge of the compiler to utilize them to their full extent, so reading through the compiler sources is a plus.")]),t._v(" "),e("h2",{attrs:{id:"portability"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#portability"}},[t._v("#")]),t._v(" Portability")]),t._v(" "),e("p",[t._v("With AssemblyScript being very similar to TypeScript, there comes the opportunity to compile the same code to JavaScript with "),e("code",[t._v("tsc")]),t._v(" and WebAssembly with "),e("code",[t._v("asc")]),t._v(". The AssemblyScript compiler itself is portable code. Writing portable code is largely a matter of double-checking that the intent translates to the same outcome in both the strictly typed AssemblyScript and the types-stripped-away TypeScript worlds.")]),t._v(" "),e("h3",{attrs:{id:"portable-standard-library"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#portable-standard-library"}},[t._v("#")]),t._v(" Portable standard library")]),t._v(" "),e("p",[t._v("Besides the full standard library, AssemblyScript provides a portable variant of the functionality that is present in both JavaScript and WebAssembly. In addition to that, the portable library lifts some of the functionality that is only available with "),e("code",[t._v("asc")]),t._v(" to JavaScript, like the portable conversions mentioned below.")]),t._v(" "),e("p",[t._v("Also note that some parts of JavaScript's standard library function a little more loosely than how they would when compiling to WebAssembly. While the portable definitions try to take care of this, one example where this can happen is "),e("code",[t._v("Map#get")]),t._v(" returning "),e("code",[t._v("undefined")]),t._v(" when a key cannot be found in JavaScript, while resulting in an abort in WebAssembly, where it is necessary to first check that the key exists using "),e("code",[t._v("Map#has")]),t._v(".")]),t._v(" "),e("p",[t._v("To use the portable library, extend "),e("code",[t._v("assemblyscript/std/portable.json")]),t._v(" instead of "),e("code",[t._v("assemblyscript/std/assembly.json")]),t._v(" within "),e("code",[t._v("tsconfig.json")]),t._v(" and add the following somewhere along your build step so the portable features are present in the environment:")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token string"}},[t._v('"assemblyscript/std/portable.js"')]),t._v("\n")])])]),e("p",[t._v("Note that the portable standard library is still a work in progress and so far focuses on functionality useful to make the compiler itself portable, so if you need something specific, feel free to improve "),e("a",{attrs:{href:"https://github.com/AssemblyScript/assemblyscript/tree/main/std/portable",target:"_blank",rel:"noopener noreferrer"}},[t._v("its definitions and feature set"),e("OutboundLink")],1),t._v(".")]),t._v(" "),e("h3",{attrs:{id:"portable-conversions"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#portable-conversions"}},[t._v("#")]),t._v(" Portable conversions")]),t._v(" "),e("p",[t._v("While "),e("code",[t._v("asc")]),t._v(" understands the meaning of")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// non-portable")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someFloat"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("f32")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1.5")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someInt"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("<")]),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(">")]),t._v("someFloat\n")])])]),e("p",[t._v("and then inserts the correct conversion steps, "),e("code",[t._v("tsc")]),t._v(" does not because all numeric types are just aliases of "),e("code",[t._v("number")]),t._v(". Hence, when targeting JavaScript with "),e("code",[t._v("tsc")]),t._v(", the above will result in")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" someFloat "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1.5")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" someInt "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" someFloat\n")])])]),e("p",[t._v("which is obviously wrong. To account for this, portable conversions can be used, resulting in actually portable code. For example")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// portable")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someFloat"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("f32")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1.5")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someInt"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("i32")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("someFloat"),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),e("p",[t._v("will essentially result in")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" someFloat "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1.5")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" someInt "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" someFloat "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("0")]),t._v("\n")])])]),e("p",[t._v("which is correct. The best way of dealing with this is asking yourself the question: What would this code do when compiled to JavaScript?")]),t._v(" "),e("h3",{attrs:{id:"portable-overflows"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#portable-overflows"}},[t._v("#")]),t._v(" Portable overflows")]),t._v(" "),e("p",[t._v("Likewise, again because "),e("code",[t._v("asc")]),t._v(" knows the meaning but "),e("code",[t._v("tsc")]),t._v(" does not, overflows must be handled explicitly:")]),t._v(" "),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// non-portable")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someU8"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("u8")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("255")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someOtherU8"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("u8")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" someU8 "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1")]),t._v("\n")])])]),e("div",{staticClass:"language-ts extra-class"},[e("pre",{pre:!0,attrs:{class:"language-ts"}},[e("code",[e("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// portable")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someU8"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("u8")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("255")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someOtherU8"),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("u8")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token function"}},[t._v("u8")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("someU8 "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),e("p",[t._v("essentially resulting in")]),t._v(" "),e("div",{staticClass:"language-js extra-class"},[e("pre",{pre:!0,attrs:{class:"language-js"}},[e("code",[e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someU8 "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("255")]),t._v("\n"),e("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("let")]),t._v(" someOtherU8 "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("someU8 "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("1")]),e("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token operator"}},[t._v("&")]),t._v(" "),e("span",{pre:!0,attrs:{class:"token number"}},[t._v("0xff")]),t._v("\n")])])]),e("h3",{attrs:{id:"non-portable-code"}},[e("a",{staticClass:"header-anchor",attrs:{href:"#non-portable-code"}},[t._v("#")]),t._v(" Non-portable code")]),t._v(" "),e("p",[t._v("In JavaScript, all numeric values are IEEE754 doubles that cannot represent the full range of values fitting in a 64-bit integer ("),e("a",{attrs:{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER",target:"_blank",rel:"noopener noreferrer"}},[t._v("max. safe integer"),e("OutboundLink")],1),t._v(" is "),e("code",[t._v("2^53 - 1")]),t._v("). Hence "),e("code",[t._v("i64")]),t._v(" and "),e("code",[t._v("u64")]),t._v(" are not portable and not present in "),e("code",[t._v("std/portable")]),t._v(". There are several ways to deal with this. One is to use an i64 polyfill like "),e("a",{attrs:{href:"https://github.com/AssemblyScript/examples/tree/main/i64",target:"_blank",rel:"noopener noreferrer"}},[t._v("in this example"),e("OutboundLink")],1),t._v(".")]),t._v(" "),e("p",[t._v("Other than that, portable code (JavaScript) does not have a concept of memory, so there are no "),e("code",[t._v("load")]),t._v(" and "),e("code",[t._v("store")]),t._v(" implementations in the portable standard library. Technically this can be polyfilled in various ways, but no default is provided since actual implementations are expected to be relatively specific (for instance: the portable compiler accesses Binaryen's memory).")])])}),[],!1,null,null,null);s.default=n.exports}}]); \ No newline at end of file diff --git a/assets/js/23.ed294d2e.js b/assets/js/23.ed294d2e.js new file mode 100644 index 000000000..7636324d8 --- /dev/null +++ b/assets/js/23.ed294d2e.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[23],{224:function(t,s,a){"use strict";a.r(s);var e=a(6),n=Object(e.a)({},(function(){var t=this,s=t.$createElement,a=t._self._c||s;return a("ContentSlotsDistributor",{attrs:{"slot-key":t.$parent.slotKey}},[a("h1",{attrs:{id:"concepts"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#concepts"}},[t._v("#")]),t._v(" Concepts")]),t._v(" "),a("p",[t._v("An overview of basic AssemblyScript concepts.")]),t._v(" "),a("h2",{attrs:{id:"typescript-like"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#typescript-like"}},[t._v("#")]),t._v(" TypeScript-like")]),t._v(" "),a("p",[t._v("AssemblyScript is very similar to TypeScript with largely compatible syntax and semantics. As such, many of the concepts known from TypeScript apply to AssemblyScript as well, but not all TypeScript features map well to ahead of time compilation or WebAssembly's so far supported feature set. Some features have been omitted, others not yet implemented, and a few additional concepts needed to be added, technically making AssemblyScript part a subset, part a superset - a variant. As such it is unlikely that existing TypeScript code can be compiled by the AssemblyScript compiler, but likely that sufficiently strict code can be ported with little effort.")]),t._v(" "),a("p",[t._v("A detailed overview of supported TypeScript features is available within "),a("RouterLink",{attrs:{to:"/status.html"}},[t._v("Implementation status")]),t._v(".")],1),t._v(" "),a("h2",{attrs:{id:"strictly-typed"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#strictly-typed"}},[t._v("#")]),t._v(" Strictly typed")]),t._v(" "),a("p",[t._v("While TypeScript has types, its type system is able to describe many of JavaScript's dynamic features. TypeScript is a superset / a type checker on top of JavaScript after all. On the contrary, AssemblyScript is compiled statically ahead of time, making it infeasible to support very dynamic JavaScript features to not enter interpreter territory, respectively requires stricter type checking to guarantee correctness at runtime where TypeScript would not complain.")]),t._v(" "),a("p",[t._v("As a result, there is no "),a("code",[t._v("any")]),t._v(" or "),a("code",[t._v("undefined")]),t._v(":")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😢")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("foo")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("a"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" b "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" a "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("1")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("return")]),t._v(" b\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😊")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("foo")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("a"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("0")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" b "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" a "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("1")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("return")]),t._v(" b\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("p",[t._v("There are no union types yet, but a similar effect can be achieved with generics:")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😢")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("foo")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("a"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("|")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😊")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token generic-function"}},[a("span",{pre:!0,attrs:{class:"token function"}},[t._v("foo")]),a("span",{pre:!0,attrs:{class:"token generic class-name"}},[a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("<")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(">")])])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("a"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("p",[t._v("Objects must be typed, say using a "),a("code",[t._v("Map")]),t._v(" or "),a("code",[t._v("class")]),t._v(":")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😢")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" a "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\na"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("prop "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"hello world"')]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😊")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" a "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("new")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token class-name"}},[t._v("Map"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("<")]),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(">")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\na"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("set")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"prop"')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"hello world"')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😊")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("class")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token class-name"}},[a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("A")])]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("constructor")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("public")]),t._v(" prop"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("string")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" a "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("new")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token class-name"}},[a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("A")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"hello world"')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("p",[t._v("And nullability checks are limited to locals to guarantee soundness where TypeScript "),a("a",{attrs:{href:"https://www.typescriptlang.org/play?#code/G4QwTgBAZg9jBcEDOAXMBLAdgcwgHwkwFcAbEiAXggCIRqBuAKEfSggApYYBKCAb0YRkAUxQAxOADlSJdtyZCuAOhLCcKABb0IAeh2EYEYWDAwwjAL7MoRTAGMU6GJhHipMuf0HQ4lQjKYrIA",target:"_blank",rel:"noopener noreferrer"}},[t._v("would not"),a("OutboundLink")],1),t._v(" "),a("a",{attrs:{href:"https://www.typescriptlang.org/play/index.html#code/MYGwhgzhAEBiD29oG8BQ0PQvAtgUwBcALASwDsBzALiwICdyLoAfaMgVxBGgF43OQAblQBfVKgBm7MsAIl4ZaABN4AZVyFSlABQTENBPACUKdJhITouxADps+YoxNpMr5Wo2PKAURAQ81sbCbph68HaeWhQ2IHiUxILQAPRJWETwnErQeHR08HQANNAARuwE7ngQZADkBGYYYmKS0rLyiirqDlG+-oEGiM710GERXYy8-FzCIkA",target:"_blank",rel:"noopener noreferrer"}},[t._v("diagnose"),a("OutboundLink")],1),t._v(" "),a("a",{attrs:{href:"https://www.typescriptlang.org/play/index.html#code/MYGwhgzhAEBiD29oG8BQ0PQPoXgWwFMAXACwEsA7AcwC5oIiAnSq6AH2goFcQRoBeaACISBXvCEBudJirF6+YuWoAKAJR0Gzau048+aTEegh5jeYNJkIAOhyKr1accxXb9wo9aDuvZy+hzIi5GCkDifwwAX1QY1AAzLgpgIjJ4MIATeABlB2UqFXjEOgR4NRQZDDJ46ELEG1xPfPLDAKL4BryWG1NqUkloAHpB+hJ4HgzoAkZGeEYAGmgAIy4iaCyCCAoAciJK6BiYoA",target:"_blank",rel:"noopener noreferrer"}},[t._v("a problem"),a("OutboundLink")],1),t._v(":")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("doSomething")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("foo"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" Foo"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😢")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("if")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("foo"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("something"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n foo"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("something"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("length "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// fails")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("doSomething")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("foo"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" Foo"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// 😊")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("var")]),t._v(" something "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" foo"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("something\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("if")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("something"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n something"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("length "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// works")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("h2",{attrs:{id:"sandboxed-execution"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#sandboxed-execution"}},[t._v("#")]),t._v(" Sandboxed execution")]),t._v(" "),a("p",[t._v("One of WebAssembly's unique features is that a module cannot access external resources without explicitly importing them, providing strong security guarantees by default. As such, to do anything useful with WebAssembly, it is necessary to wire a module to the host environment, like for example JavaScript and the DOM.")]),t._v(" "),a("h3",{attrs:{id:"module-imports"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#module-imports"}},[t._v("#")]),t._v(" Module imports")]),t._v(" "),a("p",[t._v("In AssemblyScript, host functionality can be imported by utilizing the ambient context, that is using a "),a("code",[t._v("declare")]),t._v(" statement:")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// assembly/env.ts")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("declare")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("logInteger")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("i"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// assembly/index.ts")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" logInteger "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("from")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"./env"')]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("logInteger")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("42")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("p",[t._v("Ambient declarations in an AssemblyScript file will yield a WebAssembly module import, using the internal path of the file, without file extension, as the module name (here: "),a("code",[t._v("assembly/env")]),t._v("), and the name of the declared element as the module element (here "),a("code",[t._v("logInteger")]),t._v("). In the example above, the import can be fulfilled by providing the following imports object upon instantiation:")]),t._v(" "),a("div",{staticClass:"language-js extra-class"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[t._v("WebAssembly"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("instantiateStreaming")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("fetch")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token string-property property"}},[t._v('"assembly/env"')]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("logInteger")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token parameter"}},[t._v("i")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" console"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("log")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"logInteger: "')]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" i"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("p",[t._v("If necessary, the respective external module and element names can also be overridden using the "),a("code",[t._v("@external")]),t._v(" decorator and modifying the imports object accordingly:")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// assembly/index.ts")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("external")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"log"')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"integer"')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("declare")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("logInteger")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("i"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v('// { "log": { "integer"(i) { ... } } }')]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("logInteger")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("42")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h3",{attrs:{id:"module-exports"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#module-exports"}},[t._v("#")]),t._v(" Module exports")]),t._v(" "),a("p",[t._v("Similarly, "),a("code",[t._v("export")]),t._v("s from an entry file will yield WebAssembly module exports:")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// assembly/index.ts")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("export")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("add")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("a"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" b"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("return")]),t._v(" a "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("+")]),t._v(" b\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("p",[t._v("Module exports can then be called from the host environment:")]),t._v(" "),a("div",{staticClass:"language-js extra-class"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token literal-property property"}},[t._v("instance")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" exports "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("await")]),t._v(" WebAssembly"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("instantiateStreaming")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n\nconsole"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("log")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("exports"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("add")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("1")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[t._v("2")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("p",[t._v("See also: "),a("RouterLink",{attrs:{to:"/compiler.html#host-bindings"}},[t._v("Host bindings")]),t._v(" automate much of the wiring.")],1),t._v(" "),a("h3",{attrs:{id:"special-imports"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#special-imports"}},[t._v("#")]),t._v(" Special imports")]),t._v(" "),a("p",[t._v("Some language features need support from the host environment to function, yielding a few special module imports depending on the feature set used within the module. Generated bindings provide these automatically where necessary.")]),t._v(" "),a("ul",[a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" env"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("abort"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("message"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("usize")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" fileName"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("usize")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" line"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("u32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" column"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("u32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),a("p",[t._v("Called on unrecoverable errors. Typically present if assertions are enabled or errors are thrown.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" env"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("trace"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("message"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("usize")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" n"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" a0"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token number"}},[t._v(".4")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("f64")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("void")]),t._v("\n")])])]),a("p",[t._v("Called when "),a("code",[t._v("trace")]),t._v(" is called in user code. Only present if it is.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),t._v(" env"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("seed"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("?")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("f64")]),t._v("\n")])])]),a("p",[t._v("Called when the random number generator needs to be seeded. Only present if it is.")])])]),t._v(" "),a("p",[t._v("The respective implementations of "),a("code",[t._v("abort")]),t._v(", "),a("code",[t._v("trace")]),t._v(" and "),a("code",[t._v("seed")]),t._v(" can be overridden with, for example, "),a("code",[t._v("--use abort=assembly/index/myAbort")]),t._v(", here redirecting calls to "),a("code",[t._v("abort")]),t._v(" to a custom "),a("code",[t._v("myAbort")]),t._v(" function in "),a("code",[t._v("assembly/index.ts")]),t._v(". Useful if an environment does not provide compatible implementations, or when the respective imports are not desired and custom implementations are sufficient.")]),t._v(" "),a("h3",{attrs:{id:"accessing-memory-during-instantiation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#accessing-memory-during-instantiation"}},[t._v("#")]),t._v(" Accessing memory during instantiation")]),t._v(" "),a("p",[t._v("One important edge case to be aware of is that top-level statements are executed as part of the WebAssembly module's implicit "),a("code",[t._v("(start ...)")]),t._v(" function by default, which leads to a chicken and egg problem when top-level statements already call out to external functionality that needs to access the module's memory instance (say, reading the contents of a logged string). Since instantiation did not yet complete, the module's exports, including exported memory, are not available yet and the access will fail.")]),t._v(" "),a("p",[t._v("A solution is to utilize the "),a("code",[t._v("--exportStart")]),t._v(" command line option to force exporting the start function instead of making it implicit. Then, instantiation first returns before any code is executed. Note, however, that the exported start function must always be called first, before any other exports, or undefined behavior will occur.")]),t._v(" "),a("h2",{attrs:{id:"tree-shaking"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#tree-shaking"}},[t._v("#")]),t._v(" Tree-shaking")]),t._v(" "),a("p",[t._v("AssemblyScript does not compile a module linearly, but starts at the module's exports and only compiles what's reachable from them, often referred to as "),a("a",{attrs:{href:"https://en.wikipedia.org/wiki/Tree_shaking",target:"_blank",rel:"noopener noreferrer"}},[t._v("tree-shaking"),a("OutboundLink")],1),t._v(". As such, dead code is always validated syntactically, but not necessarily checked for semantic correctness. While this mechanism significantly helps to reduce compile times and feels almost natural to those familiar with "),a("em",[t._v("executing")]),t._v(" JavaScript, it may initially feel a little strange not only to those with a background in traditional compilers, for example because emitted diagnostics do not happen linearly, but also to those with a background in TypeScript, because even type annotations remain unchecked as part of dead code. The exception to the rule is top-level code, including top-level variable declarations and their initializers, that must be evaluated as soon as the respective file would first execute.")]),t._v(" "),a("h3",{attrs:{id:"branch-level-tree-shaking"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#branch-level-tree-shaking"}},[t._v("#")]),t._v(" Branch-level tree-shaking")]),t._v(" "),a("p",[t._v("In addition to module-level tree-shaking, the compiler ignores branches that it can prove won't be taken. Works with constants, built-ins that compile to a constant, expressions that can be precomputed to a constant, plus the following globals to detect specific compiler flags or features:")]),t._v(" "),a("ul",[a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_TARGET")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v("\n")])])]),a("p",[t._v("Indicates the compilation target. Possible values are 0 = JS (portable), 1 = WASM32, 2 = WASM64.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_NO_ASSERT")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n")])])]),a("p",[t._v("Whether "),a("code",[t._v("--noAssert")]),t._v(" has been set.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_MEMORY_BASE")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("usize")]),t._v("\n")])])]),a("p",[t._v("The value of "),a("code",[t._v("--memoryBase")]),t._v(".")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_OPTIMIZE_LEVEL")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v("\n")])])]),a("p",[t._v("The value of "),a("code",[t._v("--optimizeLevel")]),t._v(". Possible values are 0, 1, 2 and 3.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_SHRINK_LEVEL")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v("\n")])])]),a("p",[t._v("The value of "),a("code",[t._v("--shrinkLevel")]),t._v(". Possible values are 0, 1 and 2.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_LOW_MEMORY_LIMIT")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v("\n")])])]),a("p",[t._v("The value of "),a("code",[t._v("--lowMemoryLimit")]),t._v(".")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_EXPORT_RUNTIME")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("i32")]),t._v("\n")])])]),a("p",[t._v("Whether "),a("code",[t._v("--exportRuntime")]),t._v(" has been set.")])]),t._v(" "),a("li",[a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_SIGN_EXTENSION")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_MUTABLE_GLOBALS")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_NONTRAPPING_F2I")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_BULK_MEMORY")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_SIMD")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_THREADS")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_EXCEPTION_HANDLING")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_TAIL_CALLS")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_REFERENCE_TYPES")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_MULTI_VALUE")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_GC")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("const")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_MEMORY64")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("bool")]),t._v("\n")])])]),a("p",[t._v("Whether the respective feature is enabled.")]),t._v(" "),a("p",[t._v("For example, if a library supports SIMD but also wants to provide a fallback when being compiled without SIMD support:")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("if")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("ASC_FEATURE_SIMD")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// compute with SIMD operations")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("else")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// fallback without SIMD operations")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])])])]),t._v(" "),a("h2",{attrs:{id:"code-annotations"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#code-annotations"}},[t._v("#")]),t._v(" Code annotations")]),t._v(" "),a("p",[t._v("Decorators work more like compiler annotations in AssemblyScript and are evaluated at compile time.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",{staticStyle:{"text-align":"left"}},[t._v("Annotation")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Description")])])]),t._v(" "),a("tbody",[a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@inline")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Requests inlining of a constant or function.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@final")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Annotates a class as final, that is it cannot be subclassed.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@unmanaged")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Annotates a class as not tracked by GC, effectively becoming a C-like struct.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@external")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Changes the external name of an imported element. "),a("code",[t._v("@external(module, name)")]),t._v(" changes both the module and element name, "),a("code",[t._v("@external(name)")]),t._v(" changes the element name only.")])])])]),t._v(" "),a("p",[t._v("Custom decorators are ignored, unless given meaning by using a "),a("RouterLink",{attrs:{to:"/compiler.html#transforms"}},[t._v("transform")]),t._v(".")],1),t._v(" "),a("p",[t._v("There are a few more built-in decorators that are likely going to change significantly over time, or may even be removed entirely. While useful for standard library implementation currently, it is not recommend to utilize them in custom code since tooling does not recognize them.")]),t._v(" "),a("details",[a("summary",[t._v("Show me anyway")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",{staticStyle:{"text-align":"left"}},[t._v("Annotation")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Description")])])]),t._v(" "),a("tbody",[a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@global")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Registers an element to be part of the global scope.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@lazy")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Requests lazy compilation of a variable. Useful to avoid unnecessary globals.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@operator")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Annotates a method as a binary operator overload. See below.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@operator.binary")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Alias of "),a("code",[t._v("@operator")]),t._v(".")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@operator.prefix")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Annotates a method as a unary prefix operator overload.")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v("@operator.postfix")])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Annotates a method as a unary postfix operator overload.")])])])]),t._v(" "),a("h3",{attrs:{id:"binary-operator-overloads"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#binary-operator-overloads"}},[t._v("#")]),t._v(" Binary operator overloads")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("operator")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("OP")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("static")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("__op")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("left"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(",")]),t._v(" right "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("operator")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("OP")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("__op")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("right"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("table",[a("thead",[a("tr",[a("th",{staticStyle:{"text-align":"left"}},[t._v("OP")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Description")])])]),t._v(" "),a("tbody",[a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"[]"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Checked indexed get")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"[]="')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Checked indexed set")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"{}"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Unchecked indexed get")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"{}="')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Unchecked indexed set")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"=="')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Equality (also applies on "),a("code",[t._v("===")]),t._v(")")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"!="')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Inequality (also applies on "),a("code",[t._v("!==")]),t._v(")")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('">"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Greater than")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('">="')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Greater than or equal")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"<"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Less than")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"<="')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Less than or equal")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('">>"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Arithmetic right shift")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('">>>"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Logical right shift")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"<<"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Left shift")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"&"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Bitwise AND")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"|"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Bitwise OR")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"^"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Bitwise XOR")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"+"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Addition")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"-"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Subtraction")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"*"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Multiplication")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"/"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Division")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"**"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Exponentiation")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"%"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Remainder")])])])]),t._v(" "),a("h3",{attrs:{id:"unary-operator-overloads"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#unary-operator-overloads"}},[t._v("#")]),t._v(" Unary operator overloads")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("operator")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("prefix")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("OP")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("static")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("__op")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("self"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("operator")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("prefix")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("OP")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("__op")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("table",[a("thead",[a("tr",[a("th",{staticStyle:{"text-align":"left"}},[t._v("OP")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Description")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Notes")])])]),t._v(" "),a("tbody",[a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"!"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Logical NOT")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}})]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"~"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Bitwise NOT")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}})]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"+"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Unary plus")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}})]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"-"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Unary negation")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}})]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"++"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Prefix increment")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Instance overload reassigns")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"--"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Prefix decrement")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Instance overload reassigns")])])])]),t._v(" "),a("p",[t._v("Note that increment and decrement overloads can have slightly different semantics. If the overload is declared as an instance method, on "),a("code",[t._v("++a")]),t._v(" the compiler does emit code that reassigns the resulting value to "),a("code",[t._v("a")]),t._v(" while if the overload is declared static, the overload behaves like any other overload, skipping the otherwise implicit assignment.")]),t._v(" "),a("h3",{attrs:{id:"unary-postfix-operations"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#unary-postfix-operations"}},[t._v("#")]),t._v(" Unary postfix operations")]),t._v(" "),a("div",{staticClass:"language-ts extra-class"},[a("pre",{pre:!0,attrs:{class:"language-ts"}},[a("code",[a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("operator")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("postfix")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("OP")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("static")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("__op")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("self"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n\n"),a("span",{pre:!0,attrs:{class:"token decorator"}},[a("span",{pre:!0,attrs:{class:"token at operator"}},[t._v("@")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("operator")])]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("postfix")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("OP")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("__op")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token constant"}},[t._v("T")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("...")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("table",[a("thead",[a("tr",[a("th",{staticStyle:{"text-align":"left"}},[t._v("OP")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Description")]),t._v(" "),a("th",{staticStyle:{"text-align":"left"}},[t._v("Notes")])])]),t._v(" "),a("tbody",[a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"++"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Postfix increment")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Instance overload reassigns")])]),t._v(" "),a("tr",[a("td",{staticStyle:{"text-align":"left"}},[a("code",[t._v('"--"')])]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Postfix decrement")]),t._v(" "),a("td",{staticStyle:{"text-align":"left"}},[t._v("Instance overload reassigns")])])])]),t._v(" "),a("p",[t._v("Overloaded postfix operations do not preserve the original value automatically.")])])])}),[],!1,null,null,null);s.default=n.exports}}]); \ No newline at end of file diff --git a/assets/js/24.ee2d454f.js b/assets/js/24.ee2d454f.js new file mode 100644 index 000000000..6a5800ebe --- /dev/null +++ b/assets/js/24.ee2d454f.js @@ -0,0 +1 @@ +(window.webpackJsonp=window.webpackJsonp||[]).push([[24],{226:function(t,e,n){"use strict";n.r(e);var a=n(6),r=Object(a.a)({},(function(){var t=this,e=t.$createElement,n=t._self._c||e;return n("ContentSlotsDistributor",{attrs:{"slot-key":t.$parent.slotKey}},[n("h1",{attrs:{id:"editor-test"}},[n("a",{staticClass:"header-anchor",attrs:{href:"#editor-test"}},[t._v("#")]),t._v(" Editor Test")]),t._v(" "),n("p",[t._v("Text before")]),t._v(" "),n("div",{staticClass:"language-editor extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('#!runtime=stub\n// Editor A\n\nexport function add(a: i32, b: i32): i32 {\n return a + b\n}\n\nexport function sub(a: i32, b: i32): i32 {\n return a - b\n}\n\n#!html\n + + \ No newline at end of file diff --git a/basics/environment/index.html b/basics/environment/index.html new file mode 100644 index 000000000..6db2bb3c4 --- /dev/null +++ b/basics/environment/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/basics/exports-and-imports/index.html b/basics/exports-and-imports/index.html new file mode 100644 index 000000000..29f33af77 --- /dev/null +++ b/basics/exports-and-imports/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/basics/loader/index.html b/basics/loader/index.html new file mode 100644 index 000000000..21c3f7290 --- /dev/null +++ b/basics/loader/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/basics/types/index.html b/basics/types/index.html new file mode 100644 index 000000000..c9dfd249d --- /dev/null +++ b/basics/types/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/browserconfig.xml b/browserconfig.xml new file mode 100644 index 000000000..76f82c5ed --- /dev/null +++ b/browserconfig.xml @@ -0,0 +1,9 @@ + + + + + + #ffffff + + + diff --git a/built-with-assemblyscript.html b/built-with-assemblyscript.html new file mode 100644 index 000000000..367802f64 --- /dev/null +++ b/built-with-assemblyscript.html @@ -0,0 +1,161 @@ + + + + + + Built with AssemblyScript | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Built with AssemblyScript

A place for all things AssemblyScript. Feel free to add your projects and applications.

# Benchmarks

# Blockchain

# Build Tools

# Demoscene

# Editors

# Formatter

# Emulators

# Games

# Graphics / Game Frameworks

# Data Serialization / Deserialization

# Crypto (non-blockchain)

# Fixed & Arbitrary Precision Arithmetics

# Language Extensions and Types

# Bindings

# Other Libraries

# Embedded / IoT

# Testing / Benchmarking

# Project Templates

# Applications

+ ← +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/builtins.html b/builtins.html new file mode 100644 index 000000000..36b339b81 --- /dev/null +++ b/builtins.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/compiler.html b/compiler.html new file mode 100644 index 000000000..86c5b84d3 --- /dev/null +++ b/compiler.html @@ -0,0 +1,333 @@ + + + + + + Using the compiler | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Using the compiler

Similar to TypeScript's tsc transpiling to JavaScript, AssemblyScript's asc compiles to WebAssembly.

# Compiler options

The compiler supports various options available on the command line, in a configuration file and programmatically. On the command line, it looks like this:

# Entry file(s)

Non-option arguments are treated as the names of entry files. A single program can have multiple entries, with the exports of each entry becoming the exports of the WebAssembly module. Exports of imported files that are not entry files do not become WebAssembly module exports.

asc entryFile.ts
+

# General

--version, -v         Prints just the compiler's version and exits.
+--help, -h            Prints this message and exits.
+--config              Configuration file to apply. CLI arguments take precedence.
+--target              Configuration file target to use. Defaults to 'release'.
+

# Optimization

The compiler can optimize for both speed (-Ospeed) and size (-Osize), as well as produce a debug build (--debug).

--optimize, -O        Optimizes the module. Typical shorthands are:
+
+                        Default optimizations   -O
+                        Make a release build    -O --noAssert
+                        Make a debug build      --debug
+                        Optimize for speed      -Ospeed
+                        Optimize for size       -Osize
+
+--optimizeLevel       How much to focus on optimizing code. [0-3]
+--shrinkLevel         How much to focus on shrinking code size. [0-2, s=1, z=2]
+--converge            Re-optimizes until no further improvements can be made.
+--noAssert            Replaces assertions with just their value without trapping.
+--uncheckedBehavior   Changes the behavior of unchecked() expressions.
+                      Using this option can potentially cause breakage.
+
+                        default  The default behavior: unchecked operations are
+                                 only used inside of unchecked().
+                        never    Unchecked operations are never used, even when,
+                                 inside of unchecked().
+                        always   Unchecked operations are always used if possible,
+                                 whether or not unchecked() is used.
+
+

Optimization levels can also be tweaked manually: --optimizeLevel (0-3) indicates how much the compiler focuses on optimizing the code with --shrinkLevel (0-2, 1=s, 2=z) indicating how much it focuses on keeping the size low during code generation and while optimizing. A shorthand for both is -O[optimizeLevel][shrinkLevel] , with shrink level indicated by optionally appending the letter s (1) or z (2).

# Output

Typical output formats are WebAssembly binary (.wasm, --outFile) and/or text format (.wat, --textFile). Often, both are used in tandem to run and also inspect generated code.

--outFile, -o         Specifies the WebAssembly output file (.wasm).
+--textFile, -t        Specifies the WebAssembly text output file (.wat).
+--bindings, -b        Specifies the bindings to generate (.js + .d.ts).
+
+                        esm  JavaScript bindings & typings for ESM integration.
+                        raw  Like esm, but exports just the instantiate function.
+                             Useful where modules are meant to be instantiated
+                             multiple times or non-ESM imports must be provided.
+

# Debugging

For easier debugging during development, a source map can be emitted alongside the WebAssembly binary, and debug symbols can be embedded:

--sourceMap           Enables source map generation. Optionally takes the URL
+                      used to reference the source map from the binary file.
+--debug               Enables debug information in emitted binaries.
+

# Features

There are several flags that enable or disable specific WebAssembly or compiler features. By default, only the bare minimum is exposed, and fully standardized WebAssembly features will be used.

--importMemory        Imports the memory from 'env.memory'.
+--noExportMemory      Does not export the memory as 'memory'.
+--initialMemory       Sets the initial memory size in pages.
+--maximumMemory       Sets the maximum memory size in pages.
+--sharedMemory        Declare memory as shared. Requires maximumMemory.
+--zeroFilledMemory    Assume imported memory is zeroed. Requires importMemory.
+--importTable         Imports the function table from 'env.table'.
+--exportTable         Exports the function table as 'table'.
+--exportStart         Exports the start function using the specified name instead
+                      of calling it implicitly. Useful for WASI or to obtain the
+                      exported memory before executing any code accessing it.
+--runtime             Specifies the runtime variant to include in the program.
+
+                        incremental  TLSF + incremental GC (default)
+                        minimal      TLSF + lightweight GC invoked externally
+                        stub         Minimal runtime stub (never frees)
+                        ...          Path to a custom runtime implementation
+
+--exportRuntime       Always exports the runtime helpers (__new, __collect, __pin etc.).
+                      Automatically determined when generation of --bindings is enabled.
+--stackSize           Overrides the stack size. Only relevant for incremental GC
+                      or when using a custom runtime that requires stack space.
+                      Defaults to 0 without and to 16384 with incremental GC.
+--enable              Enables WebAssembly features being disabled by default.
+
+                        threads             Threading and atomic operations.
+                        simd                SIMD types and operations.
+                        reference-types     Reference types and operations.
+                        gc                  Garbage collection (WIP).
+                        stringref           String reference types.
+                        relaxed-simd        Relaxed SIMD operations.
+
+--disable             Disables WebAssembly features being enabled by default.
+
+                        mutable-globals     Mutable global imports and exports.
+                        sign-extension      Sign-extension operations
+                        nontrapping-f2i     Non-trapping float to integer ops.
+                        bulk-memory         Bulk memory operations.
+
+--use, -u             Aliases a global object under another name, e.g., to switch
+                      the default 'Math' implementation used: --use Math=JSMath
+                      Can also be used to introduce an integer constant.
+--lowMemoryLimit      Enforces very low (<64k) memory constraints.
+

# Linking

Specifying the base offsets of compiler-generated memory respectively the table leaves some space for other data in front. In its current form this is mostly useful to link additional data into an AssemblyScript binary after compilation, be it by populating the binary itself or initializing the data externally upon initialization. One good example is leaving some scratch space for a frame buffer.

--memoryBase          Sets the start offset of emitted memory segments.
+--tableBase           Sets the start offset of emitted table elements.
+

# API

To integrate with the compiler, for example to post-process the AST, one or multiple custom transforms can be specified.

--transform           Specifies the path to a custom transform to load.
+

# Other

Other options include those forwarded to Binaryen and various flags useful in certain situations.

# Binaryen

--trapMode            Sets the trap mode to use.
+
+                       allow  Allow trapping operations. This is the default.
+                       clamp  Replace trapping operations with clamping semantics.
+                       js     Replace trapping operations with JS semantics.
+
+--runPasses           Specifies additional Binaryen passes to run after other
+                      optimizations, if any. See: Binaryen/src/passes/pass.cpp
+--noValidate          Skips validating the module using Binaryen.
+

# And the kitchen sink

--baseDir             Specifies the base directory of input and output files.
+--noColors            Disables terminal colors.
+--noUnsafe            Disallows the use of unsafe features in user code.
+                      Does not affect library files and external modules.
+--disableWarning      Disables warnings matching the given diagnostic code.
+                      If no diagnostic code is given, all warnings are disabled.
+--noEmit              Performs compilation as usual but does not emit code.
+--stats               Prints statistics on I/O and compile times.
+--pedantic            Make yourself sad for no good reason.
+--lib                 Adds one or multiple paths to custom library components and
+                      uses exports of all top-level files at this path as globals.
+--path                Adds one or multiple paths to package resolution, similar
+                      to node_modules. Prefers an 'ascMain' entry in a package's
+                      package.json and falls back to an inner 'assembly/' folder.
+--wasm                Uses the specified Wasm binary of the compiler.
+-- ...                Specifies node.js options (CLI only). See: node --help
+

# Configuration file

Instead of providing the options outlined above on the command line, a configuration file typically named asconfig.json can be used. It may look like in the following example, excluding comments:

{
+  "extends": "./path/to/other/asconfig.json", // (optional) base config
+  "entries": [
+    // (optional) entry files, e.g.
+    "./assembly/index.ts"
+  ],
+  "options": {
+    // common options, e.g.
+    "importTable": true
+  },
+  "targets": {
+    // (optional) targets
+    "release": {
+      // additional options for the "release" target, e.g.
+      "optimize": true,
+      "outFile": "myModule.release.wasm"
+    },
+    "debug": {
+      // additional options for the "debug" target, e.g.
+      "debug": true,
+      "outFile": "myModule.debug.wasm"
+    }
+  }
+}
+

Per-target options, e.g. targets.release, add to and override top-level options. Options provided on the command line override any options in the configuration file. Usage is, for example:

asc --config asconfig.json --target release
+

# Programmatic usage

The compiler API can also be used programmatically:

import asc from "assemblyscript/asc";
+
+const { error, stdout, stderr, stats } = await asc.main([
+  // Command line options
+  "myModule.ts",
+  "--outFile", "myModule.wasm",
+  "--optimize",
+  "--sourceMap",
+  "--stats"
+], {
+  // Additional API options
+  stdout?: ...,
+  stderr?: ...,
+  readFile?: ...,
+  writeFile?: ...,
+  listFiles?: ...,
+  reportDiagnostic?: ...,
+  transforms?: ...
+});
+if (error) {
+  console.log("Compilation failed: " + error.message);
+  console.log(stderr.toString());
+} else {
+  console.log(stdout.toString());
+}
+

The compiler runs in browsers as well. The simplest way to set it up is to include the generated web.js (opens new window) so the compiler can be used with an import on the Web:

<script src="https://cdn.jsdelivr.net/npm/assemblyscript@x.x.x/dist/web.js"></script>
+<script type="module">
+import asc from "assemblyscript/asc";
+...
+</script>
+

Here, x.x.x must be replaced with the respective version to use (opens new window), or latest to always use the latest version (not recommended in production). By default, the script installs the necessary import map (opens new window) and, for browsers that do not yet support import maps, an import map shim (opens new window). It also accepts the following options in case there is a need to only perform part of the setup:

Script URL Effect
web.js?noinstall Does not install the import map.
web.js?noshim Does not install the import map shim.
web.js?noinstall,noshim Does not install the import map or shim.

Regardless of the options used, the script always declares the following global variables:

Variable Description
ASSEMBLYSCRIPT_VERSION Version string of the compiler release used
ASSEMBLYSCRIPT_IMPORTMAP The respective import map of the release as JSON

# Host bindings

WebAssembly alone cannot yet transfer higher level data types like strings, arrays and objects over module boundaries, so for now some amount of glue code is required to exchange these data structures with the host / JavaScript.

The compiler can generate the necessary bindings using the --bindings command line option (either as an ES module or a raw instantiate function), enabling exchange of:

Type Strategy Description
Number By value Basic numeric types except 64-bit integers.
BigInt By value 64-bit integers via js-bigint-integration.
Boolean By value Coerced to true or false.
Externref By reference Using reference-types.
String Copy
ArrayBuffer Copy
TypedArray Copy Any Int8Array, Float64Array etc.
Array Copy Any Array<T>
StaticArray Copy Any StaticArray<T>
Object Copy If a plain object. That is: Has no constructor or non-public fields.
Object By reference If not a plain object. Passed as an opaque reference counted pointer.

Note the two different strategies used for Object: In some situations, say when calling a Web API, it may be preferable to copy the object as a whole, field by field, which is the strategy chosen for plain objects with no constructor or non-public fields:

// Copied to a JS object
+class PlainObject {
+  field: string;
+}
+
+export function getObject(): PlainObject {
+  return {
+    field: "hello world"
+  };
+}
+

However, copying may not be desirable in every situation, say when individual object properties are meant to be modified externally where serializing/deserializing the object as a whole would result in unnecessary overhead. To support this use case, the compiler can pass just an opaque reference to the object, which can be enforced by providing an empty constructor (not a plain object anymore):

// Not copied to a JS object
+class ComplexObject {
+  constructor() {} // !
+  field: string | null;
+}
+
+export function newObject(): ComplexObject {
+  return new ComplexObject();
+}
+
+export function setObjectField(target: ComplexObject, field: string | null): void {
+  target.field = field;
+}
+
+export function getObjectField(target: ComplexObject): string | null {
+  return target.field;
+}
+

Also note that exporting an entire class has no effect at the module boundary (yet), and it is instead recommended to expose only the needed functionality as shown in the example above. Supported elements at the boundary are globals, functions and enums.

# Using ESM bindings

Bindings generated with --bindings esm perform all the steps from compilation over instantiation to exporting the final interface. To do so, a few assumptions had to be made:

  • The WebAssembly binary is located next to the JavaScript bindings file using the same name but with a .wasm extension.

    build/mymodule.js
+build/mymodule.wasm
+
    import * as myModule from "./build/mymodule.js"
+

  • JavaScript globals in globalThis can be accessed directly via the env module namespace. For example, console.log can be manually imported through:

    @external("env", "console.log")
+declare function consoleLog(s: string): void
+

    Note that this is just an example and console.log is already provided by the standard library when called from an AssemblyScript file. Other global functions not already provided by the standard library may require an import as of this example, though.

  • Imports from other namespaces than env, i.e. (import "module" "name"), become an import { name } from "module" within the binding. Importing a custom function from a JavaScript file next to the bindings file can be achieved through:

    @external("./otherfile.js", "myFunction")
+declare function myFunction(...): ...
+

    Similarly, importing a custom function from, say, a Node.js dependency can be achieved through:

    @external("othermodule", "myFunction")
+declare function myFunction(...): ...
+

These assumptions cannot be intercepted or customized since, to provide static ESM exports from the bindings file directly, instantiation must start immediately when the bindings file is imported. If customization is required, --bindings raw can be used instead.

# Using raw bindings

The signature of the single instantiate function exported by --bindings raw is:

export async function instantiate(module: WebAssembly.Module, imports?: WebAssembly.Imports): AdaptedExports
+

Note that the function does not make any assumptions on how the module is to be compiled, but instead expects a readily compiled WebAssembly.Module as in this example:

import { instantiate } from "./module.js"
+const exports = await instantiate(await WebAssembly.compileStreaming(fetch("./module.wasm")), { /* imports */ })
+

Unlike --bindings esm, raw bindings also do not make any assumptions on how imports are resolved, so these must be provided manually as part of the imports object. For example, to achieve a similar result as with ESM bindings, but now customizable:

import { instantiate } from "./module.js"
+import * as other from "./otherfile.js"
+export const {
+  export1,
+  export2,
+  ...
+} = await instantiate(await WebAssembly.compileStreaming(fetch("./module.wasm")), {
+  "./otherfile.js": other
+})
+

# Debugging

The debugging workflow is similar to debugging JavaScript since both Wasm and JS execute in the same engine, and the compiler provides various options to set up additional WebAssembly-specific debug information. Note that any sort of optimization should be disabled in debug builds.

# Debug symbols

When compiling with the --debug option, the compiler appends a name section to the binary, containing names of functions, globals, locals and so on. These names will show up in stack traces.

# Source maps

The compiler can generate a source map alongside a binary using the --sourceMap option. By default, a relative source map path will be embedded in the binary which browsers can pick up when instantiating a module from a fetch response. In environments that do not provide fetch or an equivalent mechanism, like in Node.js, it is alternatively possible to embed an absolute source map path through --sourceMap path/to/source/map.

# Breakpoints

Some JavaScript engines also support adding break points directly in WebAssembly code. Please consult your engine's documentation: Chrome (opens new window), Firefox (opens new window), Node.js (opens new window), Safari (opens new window).

# Transforms

AssemblyScript is compiled statically, so code transformation cannot be done at runtime but must instead be performed at compile-time. To enable this, the compiler frontend (asc) provides a mechanism to hook into the compilation process before, while and after the module is being compiled.

Specifying --transform ./myTransform.js on the command line will load the node module pointed to by ./myTransform.js.

import * as assemblyscript from "assemblyscript"
+import { Transform } from "assemblyscript/transform"
+class MyTransform extends Transform {
+  ...
+}
+export default MyTransform
+

# Properties

A transform is an ES6 class/node module with the following inherited properties:

  • readonly program: Program
+

    Reference to the Program instance.

  • readonly baseDir: string
+

    Base directory used by the compiler.

  • readonly stdout: OutputStream
+

    Output stream used by the compiler.

  • readonly stderr: OutputStream
+

    Error stream uses by the compiler.

  • readonly log: typeof console.log
+

    Logs a message to console.

  • function writeFile(filename: string, contents: string | Uint8Array, baseDir: string): boolean
+

    Writes a file to disk.

  • function readFile(filename: string, baseDir: string): string | null
+

    Reads a file from disk.

  • function listFiles(dirname: string, baseDir: string): string[] | null
+

    Lists all files in a directory.

# Hooks

The frontend will call several hooks, if present on the transform, during the compilation process:

  • function afterParse(parser: Parser): void
+

    Called when parsing is complete, before a program is initialized from the AST. Note that types are not yet known at this stage and there is no easy way to obtain them.

  • function afterInitialize(program: Program): void
+

    Called once the program is initialized, before it is being compiled. Types are known at this stage, respectively can be resolved where necessary.

  • function afterCompile(module: Module): void
+

    Called with the resulting module before it is being emitted. Useful to modify the IR before writing any output, for example to replace imports with actual functionality or to add custom sections.

Transforms are a very powerful feature, but may require profound knowledge of the compiler to utilize them to their full extent, so reading through the compiler sources is a plus.

# Portability

With AssemblyScript being very similar to TypeScript, there comes the opportunity to compile the same code to JavaScript with tsc and WebAssembly with asc. The AssemblyScript compiler itself is portable code. Writing portable code is largely a matter of double-checking that the intent translates to the same outcome in both the strictly typed AssemblyScript and the types-stripped-away TypeScript worlds.

# Portable standard library

Besides the full standard library, AssemblyScript provides a portable variant of the functionality that is present in both JavaScript and WebAssembly. In addition to that, the portable library lifts some of the functionality that is only available with asc to JavaScript, like the portable conversions mentioned below.

Also note that some parts of JavaScript's standard library function a little more loosely than how they would when compiling to WebAssembly. While the portable definitions try to take care of this, one example where this can happen is Map#get returning undefined when a key cannot be found in JavaScript, while resulting in an abort in WebAssembly, where it is necessary to first check that the key exists using Map#has.

To use the portable library, extend assemblyscript/std/portable.json instead of assemblyscript/std/assembly.json within tsconfig.json and add the following somewhere along your build step so the portable features are present in the environment:

import "assemblyscript/std/portable.js"
+

Note that the portable standard library is still a work in progress and so far focuses on functionality useful to make the compiler itself portable, so if you need something specific, feel free to improve its definitions and feature set (opens new window).

# Portable conversions

While asc understands the meaning of

// non-portable
+let someFloat: f32 = 1.5
+let someInt: i32 = <i32>someFloat
+

and then inserts the correct conversion steps, tsc does not because all numeric types are just aliases of number. Hence, when targeting JavaScript with tsc, the above will result in

var someFloat = 1.5
+var someInt = someFloat
+

which is obviously wrong. To account for this, portable conversions can be used, resulting in actually portable code. For example

// portable
+let someFloat: f32 = 1.5
+let someInt: i32 = i32(someFloat)
+

will essentially result in

var someFloat = 1.5
+var someInt = someFloat | 0
+

which is correct. The best way of dealing with this is asking yourself the question: What would this code do when compiled to JavaScript?

# Portable overflows

Likewise, again because asc knows the meaning but tsc does not, overflows must be handled explicitly:

// non-portable
+let someU8: u8 = 255
+let someOtherU8: u8 = someU8 + 1
+
// portable
+let someU8: u8 = 255
+let someOtherU8: u8 = u8(someU8 + 1)
+

essentially resulting in

let someU8 = 255
+let someOtherU8 = (someU8 + 1) & 0xff
+

# Non-portable code

In JavaScript, all numeric values are IEEE754 doubles that cannot represent the full range of values fitting in a 64-bit integer (max. safe integer (opens new window) is 2^53 - 1). Hence i64 and u64 are not portable and not present in std/portable. There are several ways to deal with this. One is to use an i64 polyfill like in this example (opens new window).

Other than that, portable code (JavaScript) does not have a concept of memory, so there are no load and store implementations in the portable standard library. Technically this can be polyfilled in various ways, but no default is provided since actual implementations are expected to be relatively specific (for instance: the portable compiler accesses Binaryen's memory).

+ ← + + Concepts + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/concepts.html b/concepts.html new file mode 100644 index 000000000..cf1594676 --- /dev/null +++ b/concepts.html @@ -0,0 +1,195 @@ + + + + + + Concepts | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Concepts

An overview of basic AssemblyScript concepts.

# TypeScript-like

AssemblyScript is very similar to TypeScript with largely compatible syntax and semantics. As such, many of the concepts known from TypeScript apply to AssemblyScript as well, but not all TypeScript features map well to ahead of time compilation or WebAssembly's so far supported feature set. Some features have been omitted, others not yet implemented, and a few additional concepts needed to be added, technically making AssemblyScript part a subset, part a superset - a variant. As such it is unlikely that existing TypeScript code can be compiled by the AssemblyScript compiler, but likely that sufficiently strict code can be ported with little effort.

A detailed overview of supported TypeScript features is available within Implementation status.

# Strictly typed

While TypeScript has types, its type system is able to describe many of JavaScript's dynamic features. TypeScript is a superset / a type checker on top of JavaScript after all. On the contrary, AssemblyScript is compiled statically ahead of time, making it infeasible to support very dynamic JavaScript features to not enter interpreter territory, respectively requires stricter type checking to guarantee correctness at runtime where TypeScript would not complain.

As a result, there is no any or undefined:

// 😢
+function foo(a?) {
+  var b = a + 1
+  return b
+}
+
+// 😊
+function foo(a: i32 = 0): i32 {
+  var b = a + 1
+  return b
+}
+

There are no union types yet, but a similar effect can be achieved with generics:

// 😢
+function foo(a: i32 | string): void {
+}
+
+// 😊
+function foo<T>(a: T): void {
+}
+

Objects must be typed, say using a Map or class:

// 😢
+var a = {}
+a.prop = "hello world"
+
+// 😊
+var a = new Map<string,string>()
+a.set("prop", "hello world")
+
+// 😊
+class A {
+  constructor(public prop: string) {}
+}
+var a = new A("hello world")
+

And nullability checks are limited to locals to guarantee soundness where TypeScript would not (opens new window) diagnose (opens new window) a problem (opens new window):

function doSomething(foo: Foo): void {
+  // 😢
+  if (foo.something) {
+    foo.something.length // fails
+  }
+}
+
+function doSomething(foo: Foo): void {
+  // 😊
+  var something = foo.something
+  if (something) {
+    something.length // works
+  }
+}
+

# Sandboxed execution

One of WebAssembly's unique features is that a module cannot access external resources without explicitly importing them, providing strong security guarantees by default. As such, to do anything useful with WebAssembly, it is necessary to wire a module to the host environment, like for example JavaScript and the DOM.

# Module imports

In AssemblyScript, host functionality can be imported by utilizing the ambient context, that is using a declare statement:

// assembly/env.ts
+export declare function logInteger(i: i32): void
+
// assembly/index.ts
+import { logInteger } from "./env"
+
+logInteger(42)
+

Ambient declarations in an AssemblyScript file will yield a WebAssembly module import, using the internal path of the file, without file extension, as the module name (here: assembly/env), and the name of the declared element as the module element (here logInteger). In the example above, the import can be fulfilled by providing the following imports object upon instantiation:

WebAssembly.instantiateStreaming(fetch(...), {
+  "assembly/env": {
+    logInteger(i) { console.log("logInteger: " + i) }
+  }
+})
+

If necessary, the respective external module and element names can also be overridden using the @external decorator and modifying the imports object accordingly:

// assembly/index.ts
+@external("log", "integer")
+declare function logInteger(i: i32): void // { "log": { "integer"(i) { ... } } }
+
+logInteger(42)
+

# Module exports

Similarly, exports from an entry file will yield WebAssembly module exports:

// assembly/index.ts
+export function add(a: i32, b: i32): i32 {
+  return a + b
+}
+

Module exports can then be called from the host environment:

const { instance: { exports } } = await WebAssembly.instantiateStreaming(...)
+
+console.log(exports.add(1, 2))
+

See also: Host bindings automate much of the wiring.

# Special imports

Some language features need support from the host environment to function, yielding a few special module imports depending on the feature set used within the module. Generated bindings provide these automatically where necessary.

  • function env.abort?(message: usize, fileName: usize, line: u32, column: u32): void
+

    Called on unrecoverable errors. Typically present if assertions are enabled or errors are thrown.

  • function env.trace?(message: usize, n: i32, a0..4?: f64): void
+

    Called when trace is called in user code. Only present if it is.

  • function env.seed?(): f64
+

    Called when the random number generator needs to be seeded. Only present if it is.

The respective implementations of abort, trace and seed can be overridden with, for example, --use abort=assembly/index/myAbort, here redirecting calls to abort to a custom myAbort function in assembly/index.ts. Useful if an environment does not provide compatible implementations, or when the respective imports are not desired and custom implementations are sufficient.

# Accessing memory during instantiation

One important edge case to be aware of is that top-level statements are executed as part of the WebAssembly module's implicit (start ...) function by default, which leads to a chicken and egg problem when top-level statements already call out to external functionality that needs to access the module's memory instance (say, reading the contents of a logged string). Since instantiation did not yet complete, the module's exports, including exported memory, are not available yet and the access will fail.

A solution is to utilize the --exportStart command line option to force exporting the start function instead of making it implicit. Then, instantiation first returns before any code is executed. Note, however, that the exported start function must always be called first, before any other exports, or undefined behavior will occur.

# Tree-shaking

AssemblyScript does not compile a module linearly, but starts at the module's exports and only compiles what's reachable from them, often referred to as tree-shaking (opens new window). As such, dead code is always validated syntactically, but not necessarily checked for semantic correctness. While this mechanism significantly helps to reduce compile times and feels almost natural to those familiar with executing JavaScript, it may initially feel a little strange not only to those with a background in traditional compilers, for example because emitted diagnostics do not happen linearly, but also to those with a background in TypeScript, because even type annotations remain unchecked as part of dead code. The exception to the rule is top-level code, including top-level variable declarations and their initializers, that must be evaluated as soon as the respective file would first execute.

# Branch-level tree-shaking

In addition to module-level tree-shaking, the compiler ignores branches that it can prove won't be taken. Works with constants, built-ins that compile to a constant, expressions that can be precomputed to a constant, plus the following globals to detect specific compiler flags or features:

  • const ASC_TARGET: i32
+

    Indicates the compilation target. Possible values are 0 = JS (portable), 1 = WASM32, 2 = WASM64.

  • const ASC_NO_ASSERT: bool
+

    Whether --noAssert has been set.

  • const ASC_MEMORY_BASE: usize
+

    The value of --memoryBase.

  • const ASC_OPTIMIZE_LEVEL: i32
+

    The value of --optimizeLevel. Possible values are 0, 1, 2 and 3.

  • const ASC_SHRINK_LEVEL: i32
+

    The value of --shrinkLevel. Possible values are 0, 1 and 2.

  • const ASC_LOW_MEMORY_LIMIT: i32
+

    The value of --lowMemoryLimit.

  • const ASC_EXPORT_RUNTIME: i32
+

    Whether --exportRuntime has been set.

  • const ASC_FEATURE_SIGN_EXTENSION: bool
+const ASC_FEATURE_MUTABLE_GLOBALS: bool
+const ASC_FEATURE_NONTRAPPING_F2I: bool
+const ASC_FEATURE_BULK_MEMORY: bool
+const ASC_FEATURE_SIMD: bool
+const ASC_FEATURE_THREADS: bool
+const ASC_FEATURE_EXCEPTION_HANDLING: bool
+const ASC_FEATURE_TAIL_CALLS: bool
+const ASC_FEATURE_REFERENCE_TYPES: bool
+const ASC_FEATURE_MULTI_VALUE: bool
+const ASC_FEATURE_GC: bool
+const ASC_FEATURE_MEMORY64: bool
+

    Whether the respective feature is enabled.

    For example, if a library supports SIMD but also wants to provide a fallback when being compiled without SIMD support:

    if (ASC_FEATURE_SIMD) {
+  // compute with SIMD operations
+} else {
+  // fallback without SIMD operations
+}
+

# Code annotations

Decorators work more like compiler annotations in AssemblyScript and are evaluated at compile time.

Annotation Description
@inline Requests inlining of a constant or function.
@final Annotates a class as final, that is it cannot be subclassed.
@unmanaged Annotates a class as not tracked by GC, effectively becoming a C-like struct.
@external Changes the external name of an imported element. @external(module, name) changes both the module and element name, @external(name) changes the element name only.

Custom decorators are ignored, unless given meaning by using a transform.

There are a few more built-in decorators that are likely going to change significantly over time, or may even be removed entirely. While useful for standard library implementation currently, it is not recommend to utilize them in custom code since tooling does not recognize them.

Show me anyway
Annotation Description
@global Registers an element to be part of the global scope.
@lazy Requests lazy compilation of a variable. Useful to avoid unnecessary globals.
@operator Annotates a method as a binary operator overload. See below.
@operator.binary Alias of @operator.
@operator.prefix Annotates a method as a unary prefix operator overload.
@operator.postfix Annotates a method as a unary postfix operator overload.

# Binary operator overloads

@operator(OP)
+static __op(left: T, right :T): T { ... }
+
+@operator(OP)
+__op(right: T): T  { ... }
+
OP Description
"[]" Checked indexed get
"[]=" Checked indexed set
"{}" Unchecked indexed get
"{}=" Unchecked indexed set
"==" Equality (also applies on ===)
"!=" Inequality (also applies on !==)
">" Greater than
">=" Greater than or equal
"<" Less than
"<=" Less than or equal
">>" Arithmetic right shift
">>>" Logical right shift
"<<" Left shift
"&" Bitwise AND
"|" Bitwise OR
"^" Bitwise XOR
"+" Addition
"-" Subtraction
"*" Multiplication
"/" Division
"**" Exponentiation
"%" Remainder

# Unary operator overloads

@operator.prefix(OP)
+static __op(self: T): T { ... }
+
+@operator.prefix(OP)
+__op(): T { ... }
+
OP Description Notes
"!" Logical NOT
"~" Bitwise NOT
"+" Unary plus
"-" Unary negation
"++" Prefix increment Instance overload reassigns
"--" Prefix decrement Instance overload reassigns

Note that increment and decrement overloads can have slightly different semantics. If the overload is declared as an instance method, on ++a the compiler does emit code that reassigns the resulting value to a while if the overload is declared static, the overload behaves like any other overload, skipping the otherwise implicit assignment.

# Unary postfix operations

@operator.postfix(OP)
+static __op(self: T): T { ... }
+
+@operator.postfix(OP)
+__op(): T { ... }
+
OP Description Notes
"++" Postfix increment Instance overload reassigns
"--" Postfix decrement Instance overload reassigns

Overloaded postfix operations do not preserve the original value automatically.

+ ← + + Types + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/contributors.svg b/contributors.svg new file mode 100644 index 000000000..12218fb13 --- /dev/null +++ b/contributors.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/debugging.html b/debugging.html new file mode 100644 index 000000000..599aa201a --- /dev/null +++ b/debugging.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/compiler/index.html b/details/compiler/index.html new file mode 100644 index 000000000..730f0111a --- /dev/null +++ b/details/compiler/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/debugging/index.html b/details/debugging/index.html new file mode 100644 index 000000000..5b337b0ee --- /dev/null +++ b/details/debugging/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/index.html b/details/index.html new file mode 100644 index 000000000..e5c4e737b --- /dev/null +++ b/details/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/interoperability/index.html b/details/interoperability/index.html new file mode 100644 index 000000000..41203d53f --- /dev/null +++ b/details/interoperability/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/memory/index.html b/details/memory/index.html new file mode 100644 index 000000000..e5c4e737b --- /dev/null +++ b/details/memory/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/peculiarities/index.html b/details/peculiarities/index.html new file mode 100644 index 000000000..f1179081a --- /dev/null +++ b/details/peculiarities/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/portability/index.html b/details/portability/index.html new file mode 100644 index 000000000..1c7a675d1 --- /dev/null +++ b/details/portability/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/runtime/index.html b/details/runtime/index.html new file mode 100644 index 000000000..465a15a03 --- /dev/null +++ b/details/runtime/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/details/transforms/index.html b/details/transforms/index.html new file mode 100644 index 000000000..079be629e --- /dev/null +++ b/details/transforms/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/detauls/development/index.html b/detauls/development/index.html new file mode 100644 index 000000000..3731b8d46 --- /dev/null +++ b/detauls/development/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/editor-test.html b/editor-test.html new file mode 100644 index 000000000..ca6ad1577 --- /dev/null +++ b/editor-test.html @@ -0,0 +1,121 @@ + + + + + + Editor Test | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Editor Test

Text before

#!runtime=stub
+// Editor A
+
+export function add(a: i32, b: i32): i32 {
+  return a + b
+}
+
+export function sub(a: i32, b: i32): i32 {
+  return a - b
+}
+
+#!html
+<script>
+loader.instantiate(module_wasm, { /* imports */ })
+  .then(({ exports }) => {
+    const output = document.getElementById('output')
+    output.value += `add(1, 2) = ${exports.add(1, 2)}\n`
+    output.value += `sub(1, 2) = ${exports.sub(1, 2)}\n`
+  })
+</script>
+
+<textarea id="output" style="height: 100%; width: 100%" readonly></textarea>
+

Text between

#!runtime=stub
+// Editor B
+
+export function sub(a: i32, b: i32): i32 {
+  return a - b
+}
+
+export function add(a: i32, b: i32): i32 {
+  return a + b
+}
+
+#!html
+<script>
+loader.instantiate(module_wasm, { /* imports */ })
+  .then(({ exports }) => {
+    const output = document.getElementById('output')
+    output.value += `sub(2, 3) = ${exports.sub(2, 3)}\n`
+    output.value += `add(2, 3) = ${exports.add(2, 3)}\n`
+  })
+</script>
+
+<textarea id="output" style="height: 100%; width: 100%" readonly></textarea>
+

Text after

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/editor.html b/editor.html new file mode 100644 index 000000000..71a1f31b7 --- /dev/null +++ b/editor.html @@ -0,0 +1,892 @@ + + + + AssemblyScript Editor + + + + + + + + + + + +
+
+ + ⚙️ +
+ + + +
+
+
+
+
+ +
+
+ + + + + + diff --git a/environment/index.html b/environment/index.html new file mode 100644 index 000000000..6db2bb3c4 --- /dev/null +++ b/environment/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/examples.html b/examples.html new file mode 100644 index 000000000..e0363c56e --- /dev/null +++ b/examples.html @@ -0,0 +1,81 @@ + + + + + + Examples | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Examples

A collection of AssemblyScript examples and snippets.

# Starter examples

Small entertaining programs showcasing low-level WebAssembly capabilities. These compile to less than one or just a few kilobytes so their text format is easy to grasp.

# Mandelbrot

Renders the Mandelbrot set to a canvas using 2048 discrete color values computed on the JS side.

easy

Preview image

# Interference

Animates and renders an interference pattern to a canvas while keeping the image buffer in WebAssembly.

easy

Preview image

# Game of Life

Continuously updates a cellular automaton and visualizes its state on a canvas according to user input.

intermediate

Preview image

# Advanced examples

# Arrays

Shows how to exchange and work with arrays using the loader.

intermediate

# Examples repository

Various more advanced examples are available as part of the examples repository (opens new window), including a sophisticated example of using the loader (opens new window), creating (node) libraries (opens new window), utilizing the browser SDK (opens new window) and hooking into the compiler using transforms (opens new window).

# Additional resources

If you are interested in learning more about specific concepts, also make sure to give Wasm By Example (opens new window) a read.

+ Mandelbrot example + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/examples/arrays.html b/examples/arrays.html new file mode 100644 index 000000000..8e55c24f6 --- /dev/null +++ b/examples/arrays.html @@ -0,0 +1,193 @@ + + + + + + Arrays example | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Arrays example

Shows how to exchange and work with arrays either created in WebAssembly or in JavaScript.

# Contents

  • Using the loader and the full runtime to work with managed objects.
  • Creating arrays in WebAssembly and using them in JavaScript.
  • Creating arrays in JavaScript and using them in WebAssembly.
  • Using both copies of and live views on arrays.
  • Performing unchecked accesses where the length of an array is known.
  • Pinning objects externally to prevent premature garbage collection.

# Example

#!optimize=speed&runtime=default&exportRuntime
+/** Creates a new array and returns it to JavaScript. */
+export function createArray(length: i32): Int32Array {
+  return new Int32Array(length)
+}
+
+/** Randomizes the specified array's values. */
+export function randomizeArray(arr: Int32Array): void {
+  for (let i = 0, k = arr.length; i < k; ++i) {
+    let value = i32((Math.random() * 2.0 - 1.0) * i32.MAX_VALUE)
+    unchecked(arr[i] = value)
+  }
+}
+
+/** Computes the sum of an array's values and returns the sum to JavaScript. */
+export function sumArray(arr: Int32Array): i32 {
+  let total = 0
+  for (let i = 0, k = arr.length; i < k; ++i) {
+    total += unchecked(arr[i])
+  }
+  return total
+}
+
+// We'll need the unique Int32Array id when allocating one in JavaScript
+export const Int32Array_ID = idof<Int32Array>()
+
+#!html
+<textarea id="output" style="width: 100%; height: 100%" readonly></textarea>
+<script>
+loader.instantiate(module_wasm).then(({ exports }) => {
+  const output = document.getElementById('output')
+
+  /** Logs a message to the textarea. */
+  function log(message = '') {
+    output.value += `${message}\n`
+  }
+
+  // A simple example using an array created in WebAssembly.
+  function example1() {
+    log('=== Example1 ===')
+
+    // Obtain the necessary runtime helpers
+    const { __pin, __unpin, __getArray } = exports
+
+    // Create a new array in WebAssembly and get a reference to it. Note that
+    // the array is not reachable from within WebAssembly, only externally, so
+    // we should pin it to prevent it from becoming garbage collected too early.
+    let arrayPtr = __pin(exports.createArray(5))
+    log(`Array pointer: ${arrayPtr}`)
+
+    // Log its elements to make sure these are zero
+    log('Initial values: ' + __getArray(arrayPtr).join(', '))
+
+    // Randomize the array in WebAssembly and log it again
+    exports.randomizeArray(arrayPtr)
+    log('Randomized values: ' + __getArray(arrayPtr).join(', '))
+
+    // Compute the array values' sum and log it. This will overflow i32 range.
+    let total = exports.sumArray(arrayPtr)
+    log(`Sum (likely overflown): ${total}`)
+
+    // We are done with the array, so __unpin it so it can become collected.
+    __unpin(arrayPtr)
+
+    log()
+  }
+  example1()
+
+  // A slightly more advanced example allocating the array in JavaScript instead
+  // of WebAssembly, and utilizing a live view to modify it in WebAssembly memory.
+  function example2() {
+    log('=== Example2 ===')
+
+    // Obtain the necessary runtime helpers
+    const { __pin, __unpin, __newArray, __getArray, __getArrayView } = exports
+
+    // Create a new array, but this time in JavaScript. Note that the array is
+    // again not reachable from within WebAssembly, only externally, so we
+    // should pin it to prevent it from becoming garbage collected too early.
+    let arrayPtr = __pin(__newArray(exports.Int32Array_ID, [
+      3, 4, 5, 6, 7, 8, 9
+    ]))
+    log('Array pointer: ' + arrayPtr)
+
+    // Log its elements to make sure these are the provided values
+    log('Initial values: ' + __getArray(arrayPtr).join(', '))
+
+    // Compute the array values' sum and log it
+    let total = exports.sumArray(arrayPtr)
+    log('Sum: ' + total)
+
+    // Instead of copying, let's obtain a live view on the array and modify its
+    // values right in WebAssembly memory.
+    let view = __getArrayView(arrayPtr)
+    view.reverse()
+
+    // Log the array's elements, now reversed
+    log('Reversed values: ' + __getArray(arrayPtr).join(', '))
+
+    // We are done with the array, so __unpin it so it can become collected.
+    __unpin(arrayPtr)
+
+    log()
+  }
+  example2()
+})
+</script>
+

NOTE

This example utilizes the loader to work with managed objects, hence requires --exportRuntime to be set to expose the runtime helpers to JavaScript.

# Resources

Further information on using the loader and the runtime helpers is available as part of the loader's and the garbage collection documentation.

+ ← + + I64 as a (node) library + + (opens new window) + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/examples/game-of-life.html b/examples/game-of-life.html new file mode 100644 index 000000000..0d1021937 --- /dev/null +++ b/examples/game-of-life.html @@ -0,0 +1,273 @@ + + + + + + Game of Life example | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Game of Life example

Continuously updates a slightly modified variant of Conway's Game of Life (opens new window) and visualizes its state on a canvas.

# Contents

  • Exporting functions from a WebAssembly module.
  • Calling functions exported from WebAssembly.
  • Importing configuration values from JavaScript.
  • Instantiating the module's memory in JavaScript and import it using --importMemory.
  • Speeding up a program by forcing helper functions in a hot path to always @inline.
  • Utilizing JavaScript's Math instead of native libm to reduce module size via --use Math=JSMath.
  • Reacting to user input by directly modifying an input image buffer.
  • Finding out about WebAssembly's unintuitive byte order.
  • And finally: Continuously updating an input to an output image buffer and rendering the output image buffer.
  • Featuring: Clicking and drawing lots of stuff.

# Example

#!optimize=speed&runtime=stub&importMemory&use=Math=JSMath
+// Configuration imported from JS
+declare const BGR_ALIVE: u32;
+declare const BGR_DEAD: u32;
+declare const BIT_ROT: u32;
+
+var width: i32, height: i32, offset: i32;
+
+/** Gets an input pixel in the range [0, s]. */
+@inline
+function get(x: u32, y: u32): u32 {
+  return load<u32>((y * width + x) << 2);
+}
+
+/** Sets an output pixel in the range [s, 2*s]. */
+@inline
+function set(x: u32, y: u32, v: u32): void {
+  store<u32>((offset + y * width + x) << 2, v);
+}
+
+/** Sets an output pixel in the range [s, 2*s] while fading it out. */
+@inline
+function rot(x: u32, y: u32, v: u32): void {
+  var alpha = max<i32>((v >> 24) - BIT_ROT, 0);
+  set(x, y, (alpha << 24) | (v & 0x00ffffff));
+}
+
+/** Initializes width and height. Called once from JS. */
+export function init(w: i32, h: i32): void {
+  width  = w;
+  height = h;
+  offset = w * h;
+
+  // Start by filling output with random live cells.
+  for (let y = 0; y < h; ++y) {
+    for (let x = 0; x < w; ++x) {
+      let c = Math.random() > 0.1
+        ? BGR_DEAD  & 0x00ffffff
+        : BGR_ALIVE | 0xff000000;
+      set(x, y, c);
+    }
+  }
+}
+
+/** Performs one step. Called about 30 times a second from JS. */
+export function step(): void {
+  var w = width,
+      h = height;
+
+  var hm1 = h - 1, // h - 1
+      wm1 = w - 1; // w - 1
+
+  // The universe of the Game of Life is an infinite two-dimensional orthogonal grid of square
+  // "cells", each of which is in one of two possible states, alive or dead.
+  for (let y = 0; y < h; ++y) {
+    let ym1 = y == 0 ? hm1 : y - 1,
+        yp1 = y == hm1 ? 0 : y + 1;
+    for (let x = 0; x < w; ++x) {
+      let xm1 = x == 0 ? wm1 : x - 1,
+          xp1 = x == wm1 ? 0 : x + 1;
+
+      // Every cell interacts with its eight neighbours, which are the cells that are horizontally,
+      // vertically, or diagonally adjacent. Least significant bit indicates alive or dead.
+      let aliveNeighbors = (
+        (get(xm1, ym1) & 1) + (get(x, ym1) & 1) + (get(xp1, ym1) & 1) +
+        (get(xm1, y  ) & 1)                     + (get(xp1, y  ) & 1) +
+        (get(xm1, yp1) & 1) + (get(x, yp1) & 1) + (get(xp1, yp1) & 1)
+      );
+
+      let self = get(x, y);
+      if (self & 1) {
+        // A live cell with 2 or 3 live neighbors rots on to the next generation.
+        if ((aliveNeighbors & 0b1110) == 0b0010) rot(x, y, self);
+        // A live cell with fewer than 2 or more than 3 live neighbors dies.
+        else set(x, y, BGR_DEAD | 0xff000000);
+      } else {
+        // A dead cell with exactly 3 live neighbors becomes a live cell.
+        if (aliveNeighbors == 3) set(x, y, BGR_ALIVE | 0xff000000);
+        // A dead cell with fewer or more than 3 live neighbors just rots.
+        else rot(x, y, self);
+      }
+    }
+  }
+}
+
+/** Fills the row and column indicated by `x` and `y` with random live cells. */
+export function fill(x: u32, y: u32, p: f64): void {
+  for (let ix = 0; ix < width; ++ix) {
+    if (Math.random() < p) set(ix, y, BGR_ALIVE | 0xff000000);
+  }
+  for (let iy = 0; iy < height; ++iy) {
+    if (Math.random() < p) set(x, iy, BGR_ALIVE | 0xff000000);
+  }
+}
+
+#!html
+<canvas id="canvas" style="width: 100%; height: 100%; background: #000; cursor: crosshair"></canvas>
+<script type="module">
+// Configuration
+const RGB_ALIVE = 0xD392E6;
+const RGB_DEAD  = 0xA61B85;
+const BIT_ROT   = 10;
+
+// Set up the canvas with a 2D rendering context
+const canvas = document.getElementById("canvas");
+const boundingRect = canvas.getBoundingClientRect();
+const ctx = canvas.getContext("2d");
+
+// Compute the size of the universe (2 pixels per cell)
+const width = boundingRect.width >>> 1;
+const height = boundingRect.height >>> 1;
+const size = width * height;
+const byteSize = (size + size) << 2; // input & output (4 bytes per cell)
+
+canvas.width = width;
+canvas.height = height;
+canvas.style.imageRendering = "pixelated";
+ctx.imageSmoothingEnabled = false;
+
+// Compute the size of and instantiate the module's memory
+const memory = new WebAssembly.Memory({ initial: ((byteSize + 0xffff) & ~0xffff) >>> 16 });
+
+// Compile and instantiate the module
+const exports = await instantiate(await compile(), {
+  env: {
+    memory
+  },
+  module: {
+    BGR_ALIVE : rgb2bgr(RGB_ALIVE) | 1, // LSB set indicates alive
+    BGR_DEAD  : rgb2bgr(RGB_DEAD) & ~1, // LSB not set indicates dead
+    BIT_ROT
+  }
+});
+
+// Initialize the module with the universe's width and height
+exports.init(width, height);
+
+var buffer = new Uint32Array(memory.buffer);
+
+// Update about 30 times a second
+(function update() {
+  setTimeout(update, 1000 / 30);
+  buffer.copyWithin(0, size, size + size);   // copy output to input
+  exports.step();                            // perform the next step
+})();
+
+// Keep rendering the output at [size, 2*size]
+var imageData = ctx.createImageData(width, height);
+var argb = new Uint32Array(imageData.data.buffer);
+(function render() {
+  requestAnimationFrame(render);
+  argb.set(buffer.subarray(size, size + size)); // copy output to image buffer
+  ctx.putImageData(imageData, 0, 0);            // apply image buffer
+})();
+
+// When clicked or dragged, fill the current row and column with random live cells
+var down = false;
+[ [canvas, "mousedown"],
+  [canvas, "touchstart"]
+].forEach(eh => eh[0].addEventListener(eh[1], e => down = true));
+[ [document, "mouseup"],
+  [document, "touchend"]
+].forEach(eh => eh[0].addEventListener(eh[1], e => down = false));
+[ [canvas, "mousemove"],
+  [canvas, "touchmove"],
+  [canvas, "mousedown"]
+].forEach(eh => eh[0].addEventListener(eh[1], e => {
+  if (!down) return;
+  var loc;
+  if (e.touches) {
+    if (e.touches.length > 1) return;
+    loc = e.touches[0];
+  } else {
+    loc = e;
+  }
+  const currentBoundingRect = canvas.getBoundingClientRect();
+  exports.fill(
+    ((loc.clientX - currentBoundingRect.left) / currentBoundingRect.width * boundingRect.width) >>> 1,
+    ((loc.clientY - currentBoundingRect.top) / currentBoundingRect.height * boundingRect.height) >>> 1,
+    0.5
+  );
+}));
+
+/** Bitshifts an RGB color to BGR instead (WebAssembly is little endian). */
+function rgb2bgr(rgb) {
+  return ((rgb >>> 16) & 0xff) | (rgb & 0xff00) | (rgb & 0xff) << 16;
+}
+</script>
+

NOTE

The example makes a couple assumptions. For instance, using the entire memory of the program as the image buffer as in this example is only possible because we know that no interferring static memory segments will be created, which is achieved by

  • using JavaScript's Math instead of native libm (usually adds lookup tables),
  • not using a more sophisticated runtime (typically adds bookkeeping) and
  • the rest of the example being relatively simple (i.e. no strings or similar).

As soon as these conditions are no longer met, one would instead either reserve some space by specifying a suitable --memoryBase or export a dynamically instantiated chunk of memory, like an Uint32Array, and utilize it as the input and output image buffers both in WebAssembly and in JavaScript.

# Running locally

Instructions are identical to those of the Mandelbrot example.

+ ← + + Snippets + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/examples/interference.html b/examples/interference.html new file mode 100644 index 000000000..025d0a8ec --- /dev/null +++ b/examples/interference.html @@ -0,0 +1,179 @@ + + + + + + Interference example | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Interference example

Colin Eberhardt's and Ben Smith's WebAssembly interference effect (opens new window), if it was written in AssemblyScript.

# Contents

  • Exporting functions and variables from a WebAssembly module.
  • Calling functions and reading variables exported from WebAssembly.
  • Utilizing 32-bit floating point math to speed up calculations by utilizing Mathf.
  • Keeping an image buffer within the module's memory and copying it to a canvas.
  • Manually growing memory depending on the size of the viewport on the browser side.
  • And finally: Continuously updating and rendering the image buffer.

# Example

EPILEPSY WARNING

A very small percentage of individuals may experience epileptic seizures when exposed to certain light patterns or flashing lights. Exposure to certain patterns or backgrounds on a computer screen may induce an epileptic seizure in these individuals. Certain conditions may induce previously undetected epileptic symptoms even in persons who have no history of prior seizures or epilepsy.

If you experience any of the following symptoms while viewing - dizziness, altered vision, eye or muscle twitches, loss of awareness, disorientation, any involuntary movement, or convulsions - IMMEDIATELY discontinue use and consult your physician.

#!optimize=speed&runtime=stub
+var width  = 320;
+var height = 200;
+
+// Let's utilize the entire heap as our image buffer
+export const offset = __heap_base;
+
+/** Sets a single pixel's color. */
+function set(x: i32, y: i32, v: f32): void {
+  var vi = <i32>v;
+  store<i32>(offset + ((width * y + x) << 2), ~vi << 24 | vi << 8);
+}
+
+/** Computes the distance between two pixels. */
+function distance(x1: i32, y1: i32, x2: f32, y2: f32): f32 {
+  var dx = <f32>x1 - x2;
+  var dy = <f32>y1 - y2;
+  return Mathf.sqrt(dx * dx + dy * dy);
+}
+
+/** Performs one tick. */
+export function update(tick: f32): void {
+  var w = <f32>width;
+  var h = <f32>height;
+  var hw = w * 0.5,
+      hh = h * 0.5;
+  var cx1 = (Mathf.sin(tick * 2) + Mathf.sin(tick      )) * hw * 0.3 + hw,
+      cy1 = (Mathf.cos(tick)                            ) * hh * 0.3 + hh,
+      cx2 = (Mathf.sin(tick * 4) + Mathf.sin(tick + 1.2)) * hw * 0.3 + hw,
+      cy2 = (Mathf.sin(tick * 3) + Mathf.cos(tick + 0.1)) * hh * 0.3 + hh;
+  var res = <f32>48 / Mathf.max(w, h);
+  var y = 0;
+  do {
+    let x = 0;
+    do {
+      set(x, y, Mathf.abs(
+        Mathf.sin(distance(x, y, cx1, cy1) * res) +
+        Mathf.sin(distance(x, y, cx2, cy2) * res)
+      ) * 120);
+    } while (++x != width)
+  } while (++y != height)
+}
+
+/** Recomputes and potentially grows memory on resize of the viewport. */
+export function resize(w: i32, h: i32): void {
+  width = w; height = h;
+  // Pages are 64kb. Rounds up using mask 0xffff before shifting to pages.
+  var needed = <i32>((offset + (w * h * sizeof<i32>() + 0xffff)) & ~0xffff) >>> 16;
+  var actual = memory.size();
+  if (needed > actual) memory.grow(needed - actual);
+}
+
+#!html
+<canvas id="canvas" style="width: 100%; height: 100%; background: #aff"></canvas>
+<script type="module">
+const exports = await instantiate(await compile());
+const canvas = document.getElementById("canvas");
+const context = canvas.getContext("2d");
+const step = 0.012;
+
+// Upscale the image to speed up calculations
+const upscaleFactor = 4;
+
+var width, height, image;
+
+// Inform the module about the viewport's size, incl. on resize
+function onresize() {
+  width = (canvas.offsetWidth / upscaleFactor) | 0;
+  height = (canvas.offsetHeight / upscaleFactor) | 0;
+  canvas.width = width;
+  canvas.height = height;
+  image = context.createImageData(width, height);
+  exports.resize(width, height);
+}
+onresize();
+new ResizeObserver(onresize).observe(canvas);
+
+// Keep updating the image
+var tick = 0.0;
+(function update() {
+  requestAnimationFrame(update);
+  exports.update(tick += step);
+  new Uint32Array(image.data.buffer).set(new Uint32Array(exports.memory.buffer, exports.offset.value, width * height));
+  context.putImageData(image, 0, 0);
+})();
+</script>
+

NOTE

The example makes one important assumption: Since we are not using a sophisticated runtime, we can instead repurpose the entire heap, starting at __heap_base, as our image buffer.

As soon as this condition is no longer met, one would instead either reserve some space by specifying a suitable --memoryBase or export a dynamically instantiated chunk of memory, like an Uint32Array, and utilize it as the image buffer both in WebAssembly and in JavaScript.

# Running locally

Set up a new AssemblyScript project as described in Getting started and copy module.ts to assembly/index.ts and index.html to the project's top-level directory. Edit the build commands in package.json to include

--runtime stub
+

The example can now be compiled with

npm run asbuild
+

To view the example, one can modify the instantiation in index.html from

loader.instantiate(module_wasm).then(({ exports }) => {
+

to

WebAssembly.instantiateStreaming(fetch('./build/optimized.wasm'), {
+  JSMath: Math
+}).then(({ exports }) => {
+

because using the loader is not ultimately necessary here (no managed objects are exchanged). If the loader is used instead, it will automatically provide JSMath.

Some browsers may restrict fetching local resources when just opening index.html now, but one can set up a local server as a workaround:

npm install --save-dev http-server
+http-server . -o -c-1
+

+ ← + + Game of Life example + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/examples/mandelbrot.html b/examples/mandelbrot.html new file mode 100644 index 000000000..bdcdf7ae3 --- /dev/null +++ b/examples/mandelbrot.html @@ -0,0 +1,224 @@ + + + + + + Mandelbrot example | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Mandelbrot example

Renders the Mandelbrot set (opens new window) to a canvas using 2048 discrete color values computed on the JS side.

# Contents

  • Exporting functions from a WebAssembly module.
  • Calling functions exported from WebAssembly.
  • Instantiating the module's memory in JavaScript and import it using --importMemory.
  • Utilizing JavaScript's Math instead of native libm to reduce module size via --use Math=JSMath.
  • And finally: Reading and translating data from WebAssembly memory to colors rendered to a canvas.

# Example

#!optimize=speed&runtime=stub&importMemory&use=Math=JSMath
+/** Number of discrete color values on the JS side. */
+const NUM_COLORS = 2048;
+
+/** Updates the rectangle `width` x `height`. */
+export function update(width: u32, height: u32, limit: u32): void {
+  var translateX = width  * (1.0 / 1.6);
+  var translateY = height * (1.0 / 2.0);
+  var scale      = 10.0 / min(3 * width, 4 * height);
+  var realOffset = translateX * scale;
+  var invLimit   = 1.0 / limit;
+
+  var minIterations = min(8, limit);
+
+  for (let y: u32 = 0; y < height; ++y) {
+    let imaginary = (y - translateY) * scale;
+    let yOffset   = (y * width) << 1;
+
+    for (let x: u32 = 0; x < width; ++x) {
+      let real = x * scale - realOffset;
+
+      // Iterate until either the escape radius or iteration limit is exceeded
+      let ix = 0.0, iy = 0.0, ixSq: f64, iySq: f64;
+      let iteration: u32 = 0;
+      while ((ixSq = ix * ix) + (iySq = iy * iy) <= 4.0) {
+        iy = 2.0 * ix * iy + imaginary;
+        ix = ixSq - iySq + real;
+        if (iteration >= limit) break;
+        ++iteration;
+      }
+
+      // Do a few extra iterations for quick escapes to reduce error margin
+      while (iteration < minIterations) {
+        let ixNew = ix * ix - iy * iy + real;
+        iy = 2.0 * ix * iy + imaginary;
+        ix = ixNew;
+        ++iteration;
+      }
+
+      // Iteration count is a discrete value in the range [0, limit] here, but we'd like it to be
+      // normalized in the range [0, 2047] so it maps to the gradient computed in JS.
+      // see also: http://linas.org/art-gallery/escape/escape.html
+      let colorIndex = NUM_COLORS - 1;
+      let distanceSq = ix * ix + iy * iy;
+      if (distanceSq > 1.0) {
+        let fraction = Math.log2(0.5 * Math.log(distanceSq));
+        colorIndex = <u32>((NUM_COLORS - 1) * clamp<f64>((iteration + 1 - fraction) * invLimit, 0.0, 1.0));
+      }
+      store<u16>(yOffset + (x << 1), colorIndex);
+    }
+  }
+}
+
+/** Clamps a value between the given minimum and maximum. */
+function clamp<T>(value: T, minValue: T, maxValue: T): T {
+  return min(max(value, minValue), maxValue);
+}
+
+#!html
+<canvas id="canvas" style="width: 100%; height: 100%"></canvas>
+<script type="module">
+
+// Set up the canvas with a 2D rendering context
+const canvas = document.getElementById("canvas");
+const boundingRect = canvas.getBoundingClientRect();
+const ctx = canvas.getContext("2d");
+
+// Compute the size of the viewport
+const ratio  = window.devicePixelRatio || 1;
+const width  = (boundingRect.width  | 0) * ratio;
+const height = (boundingRect.height | 0) * ratio;
+const size = width * height;
+const byteSize = size << 1; // discrete color indices in range [0, 2047] (2 bytes per pixel)
+
+canvas.width  = width;
+canvas.height = height;
+
+ctx.scale(ratio, ratio);
+
+// Compute the size (in pages) of and instantiate the module's memory.
+// Pages are 64kb. Rounds up using mask 0xffff before shifting to pages.
+const memory = new WebAssembly.Memory({ initial: ((byteSize + 0xffff) & ~0xffff) >>> 16 });
+const buffer = new Uint16Array(memory.buffer);
+const imageData = ctx.createImageData(width, height);
+const argb = new Uint32Array(imageData.data.buffer);
+const colors = computeColors();
+
+const exports = await instantiate(await compile(), {
+  env: {
+    memory
+  }
+})
+
+// Update state
+exports.update(width, height, 40);
+
+// Translate 16-bit color indices to colors
+for (let y = 0; y < height; ++y) {
+  const yx = y * width;
+  for (let x = 0; x < width; ++x) {
+    argb[yx + x] = colors[buffer[yx + x]];
+  }
+}
+
+// Render the image buffer.
+ctx.putImageData(imageData, 0, 0);
+
+/** Computes a nice set of colors using a gradient. */
+function computeColors() {
+  const canvas = document.createElement("canvas");
+  canvas.width = 2048;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d");
+  const grd = ctx.createLinearGradient(0, 0, 2048, 0);
+  grd.addColorStop(0.00, "#000764");
+  grd.addColorStop(0.16, "#2068CB");
+  grd.addColorStop(0.42, "#EDFFFF");
+  grd.addColorStop(0.6425, "#FFAA00");
+  grd.addColorStop(0.8575, "#000200");
+  ctx.fillStyle = grd;
+  ctx.fillRect(0, 0, 2048, 1);
+  return new Uint32Array(ctx.getImageData(0, 0, 2048, 1).data.buffer);
+}
+</script>
+

NOTE

The example makes a couple assumptions. For instance, using the entire memory of the program as the image buffer as in this example is only possible because we know that no interferring static memory segments will be created, which is achieved by

  • using JavaScript's Math instead of native libm (usually adds lookup tables),
  • not using a more sophisticated runtime (typically adds bookkeeping) and
  • the rest of the example being relatively simple (i.e. no strings or similar).

As soon as these conditions are no longer met, one would instead either reserve some space by specifying a suitable --memoryBase or export a dynamically instantiated chunk of memory, like an Uint16Array, and utilize it as the color index buffer both in WebAssembly and in JavaScript.

# Running locally

Set up a new AssemblyScript project as described in Getting started and copy module.ts to assembly/index.ts and index.html to the project's top-level directory. Edit the build commands in package.json to include

--runtime stub --use Math=JSMath --importMemory
+

The example can now be compiled with

npm run asbuild
+

To view the example, one can modify the instantiation in index.html from

loader.instantiate(module_wasm, {
+  env: {
+    memory
+  }
+}).then(({ exports }) => {
+

to

WebAssembly.instantiateStreaming(fetch('./build/optimized.wasm'), {
+  env: {
+    memory
+  },
+  Math
+}).then(({ exports }) => {
+

because using the loader is not ultimately necessary here (no managed objects are exchanged). If the loader is used instead, it will automatically provide JavaScript's Math.

Some browsers may restrict fetching local resources when just opening index.html now, but one can set up a local server as a workaround:

npm install --save-dev http-server
+http-server . -o -c-1
+

+ ← + + Interference example + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/examples/snippets.html b/examples/snippets.html new file mode 100644 index 000000000..ad50b64bd --- /dev/null +++ b/examples/snippets.html @@ -0,0 +1,332 @@ + + + + + + Snippets | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Snippets

Small, copy-pastable AssemblyScript examples using common syntax and patterns.

# Class

An AssemblyScript snippet on using Classes, their instantiation, and their static properties.

#!runtime=stub
+class Animal<T> {
+  static ONE: i32 = 1;
+  static add(a: i32, b: i32): i32 { return a + b + Animal.ONE; }
+
+  two: i16 = 2; // 6
+  instanceSub<T>(a: T, b: T): T { return a - b + <T>Animal.ONE; } // tsc does not allow this
+}
+
+export function staticOne(): i32 {
+  return Animal.ONE;
+}
+
+export function staticAdd(a: i32, b: i32): i32 {
+  return Animal.add(a, b);
+}
+
+export function instanceTwo(): i32 {
+  let animal = new Animal<i32>();
+  return animal.two;
+}
+
+export function instanceSub(a: f32, b: f32): f32 {
+  let animal = new Animal<f32>();
+  return animal.instanceSub<f32>(a, b);
+}
+
+
+#!html
+<script type="module">
+const log = console.log;
+console.log = (...args) => {
+  log(...args);
+  let str = '';
+  args.forEach(arg => {
+    if (typeof arg == 'object') {
+      str += `${JSON.stringify(arg, null, 2)}<br/>`;
+    } else {
+      str += `${arg}<br/>`;
+    }
+  });
+  document.body.innerHTML += `<div>Log: ${str}</div>`;
+}
+
+const exports = await instantiate(await compile(), { /* imports */ });
+
+console.log(exports.staticOne());
+console.log(exports.staticAdd(1, 2));
+console.log(exports.instanceTwo());
+console.log(exports.instanceSub(3.0, 1.0));
+</script>
+

# Extending Classes

Extending classes and general Object Orientated Programming (OOP) in AssemblyScript

#!runtime=stub
+
+class BaseClass {
+  static staticProp: i32 = 24;
+  instanceProp: i32;
+
+  constructor(value: i32) {
+    this.instanceProp = value;
+  }
+
+  add(a: i32, b: i32): i32 {
+    return a + b;
+  }
+}
+
+class ExtendedClass extends BaseClass {
+
+  extendedProp: i32;
+
+  constructor(extendedValue: i32) {
+    super(1);
+
+    this.extendedProp = extendedValue;
+  }
+
+  add(a: i32): i32 {
+    return super.add(a, this.extendedProp + super.instanceProp);
+  }
+}
+
+export function getStaticProp(): i32 {
+  return ExtendedClass.staticProp;
+}
+
+export function overloadAdd(value: i32): i32 {
+  let extendedClass = new ExtendedClass(value);
+  return extendedClass.add(24);
+}
+
+#!html
+<script type="module">
+const log = console.log;
+console.log = (...args) => {
+  log(...args);
+  let str = '';
+  args.forEach(arg => {
+    if (typeof arg === 'object') {
+      str += `${JSON.stringify(arg, null, 2)}<br/>`;
+    } else {
+      str += `${arg}<br/>`;
+    }
+  });
+  document.body.innerHTML += `<div>Log: ${str}</div>`;
+}
+
+const exports = await instantiate(await compile(), { /* imports */ });
+
+console.log(`getStaticProp: ${exports.getStaticProp()}`);
+console.log(`overloadAdd: ${exports.overloadAdd(24)}`);
+</script>
+

# Handling Null

Handling Null as a union type for optional return values and simulating try/catch for errors in AssemblyScript

#!runtime=stub
+class MyValue {
+  value: i32;
+
+  constructor(value: i32) {
+    this.value = value;
+  }
+}
+
+// Using a class type here, as some types are not nullable
+function getMyValue(isAble: boolean): MyValue | null {
+  let myValue = new MyValue(24);
+  if (isAble) {
+    return myValue;
+  } else {
+    return null;
+  }
+}
+
+export function positiveAddWithMyValue(a: i32): i32 {
+  let myValue = getMyValue(a > 0);
+  if (myValue == null) {
+    return -1;
+  } else {
+    return a + myValue.value;
+  }
+}
+
+#!html
+<script type="module">
+const log = console.log;
+console.log = (...args) => {
+  log(...args);
+  let str = '';
+  args.forEach(arg => {
+    if (typeof arg == 'object') {
+      str += `${JSON.stringify(arg, null, 2)}<br/>`;
+    } else {
+      str += `${arg}<br/>`;
+    }
+  });
+  document.body.innerHTML += `<div>Log: ${str}</div>`;
+}
+
+const exports = await instantiate(await compile(), { /* imports */ });
+
+if (exports.positiveAddWithMyValue(24) > -1) {
+  console.log("Add was successful")
+} else {
+  console.log("Could not add 24");
+}
+
+if (exports.positiveAddWithMyValue(-1) > -1) {
+  console.log("Add was successful")
+} else {
+  console.log("Could not add -1");
+}
+</script>
+

# Switch Case

Using switch case statements in AssemblyScript.

NOTE

Currently, the switch conditions (case values) are implicitly converted to u32, i.e. switching over strings or similar is not yet supported.

#!runtime=stub
+export function switchSurprise(a: i32): i32 {
+  let response = -1;
+
+  // Using a mix of braces and not using braces
+  // to show that both syntaxes are supported here.
+  switch (a) {
+    case 1:
+      response = 100;
+      break;
+    case 2: {   // Cases can also use braces
+      response = 200;
+      break;
+    }
+    case 3:
+      // Fall Through to the next case
+    case 4:
+      response = 400;
+      break;
+    default: {
+      response = 0;
+    }
+  }
+
+  return response;
+}
+
+#!html
+<script type="module">
+const log = console.log;
+console.log = (...args) => {
+  log(...args);
+  let str = '';
+  args.forEach(arg => {
+    if (typeof arg == 'object') {
+      str += `${JSON.stringify(arg, null, 2)}<br/>`;
+    } else {
+      str += `${arg}<br/>`;
+    }
+  });
+  document.body.innerHTML += `<div>Log: ${str}</div>`;
+}
+
+const exports = await instantiate(await compile(), { /* imports */ });
+
+console.log(`switchSurprise(1) : ${exports.switchSurprise(1)}`);
+console.log(`switchSurprise(2) : ${exports.switchSurprise(2)}`);
+console.log(`switchSurprise(3) : ${exports.switchSurprise(3)}`);
+console.log(`switchSurprise(4) : ${exports.switchSurprise(4)}`);
+console.log(`switchSurprise(57) : ${exports.switchSurprise(57)}`);
+</script>
+

# Ternary if-else

Using Ternary if-else in AssemblyScript

#!runtime=stub
+export function isTrue(a: i32): i32 {
+  let response = a > 0 ? 1 : 0;
+  return response;
+}
+
+#!html
+<script type="module">
+const log = console.log;
+console.log = (...args) => {
+  log(...args);
+  let str = '';
+  args.forEach(arg => {
+    if (typeof arg == 'object') {
+      str += `${JSON.stringify(arg, null, 2)}<br/>`;
+    } else {
+      str += `${arg}<br/>`;
+    }
+  });
+  document.body.innerHTML += `<div>Log: ${str}</div>`;
+}
+
+const exports = await instantiate(await compile(), { /* imports */ });
+
+console.log(`is 24 greater than 0? ${exports.isTrue(24) > 0 ? true : false}`);
+console.log(`is -3 greater than 0? ${exports.isTrue(-3) > 0 ? true : false}`);
+</script>
+

+ ← + + Arrays example + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/exports-and-imports.html b/exports-and-imports.html new file mode 100644 index 000000000..21486244e --- /dev/null +++ b/exports-and-imports.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/extended-library/staticarray/index.html b/extended-library/staticarray/index.html new file mode 100644 index 000000000..6f6799870 --- /dev/null +++ b/extended-library/staticarray/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/faq/index.html b/faq/index.html new file mode 100644 index 000000000..bbcee9e3c --- /dev/null +++ b/faq/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 000000000..f8c8aae06 Binary files /dev/null and b/favicon.ico differ diff --git a/favicons/android-chrome-192x192.png b/favicons/android-chrome-192x192.png new file mode 100644 index 000000000..844437c35 Binary files /dev/null and b/favicons/android-chrome-192x192.png differ diff --git a/favicons/android-chrome-512x512.png b/favicons/android-chrome-512x512.png new file mode 100644 index 000000000..3028b7b92 Binary files /dev/null and b/favicons/android-chrome-512x512.png differ diff --git a/favicons/apple-touch-icon.png b/favicons/apple-touch-icon.png new file mode 100644 index 000000000..09cb9583d Binary files /dev/null and b/favicons/apple-touch-icon.png differ diff --git a/favicons/favicon-16x16.png b/favicons/favicon-16x16.png new file mode 100644 index 000000000..f55d69008 Binary files /dev/null and b/favicons/favicon-16x16.png differ diff --git a/favicons/favicon-32x32.png b/favicons/favicon-32x32.png new file mode 100644 index 000000000..0fa8b2985 Binary files /dev/null and b/favicons/favicon-32x32.png differ diff --git a/favicons/mstile-150x150.png b/favicons/mstile-150x150.png new file mode 100644 index 000000000..449849767 Binary files /dev/null and b/favicons/mstile-150x150.png differ diff --git a/favicons/safari-pinned-tab.svg b/favicons/safari-pinned-tab.svg new file mode 100644 index 000000000..08c0b1eb0 --- /dev/null +++ b/favicons/safari-pinned-tab.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/frequently-asked-questions.html b/frequently-asked-questions.html new file mode 100644 index 000000000..21cfe0be4 --- /dev/null +++ b/frequently-asked-questions.html @@ -0,0 +1,77 @@ + + + + + + Frequently asked questions | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Frequently asked questions

Questions that may arise before, at or after this point. so if you're wondering about one thing or another, here it is:

# Is WebAssembly faster than JavaScript?

Not always, but it can be. The execution characteristics of ahead-of-time compiled WebAssembly differ from just-in-time compiled JavaScript in that it is more predictable in a way that enables a WebAssembly program to remain on a reasonably fast path over the entire course of execution, while a JavaScript VM tries hard to do all sorts of smart optimizations before and while the code is executing. This implies that a JavaScript VM can make both very smart decisions, especially for well-written code with a clear intent, but might also have to reconsider its strategy to do something more general if its assumptions did not hold. If you are primarily interested in performance, rules of thumb could be:

Scenario Recommendation
Compute-heavy algorithm Use WebAssembly
Mostly interacts with the DOM Mostly use JavaScript
Games Use WebAssembly for CPU-intensive parts
WebGL Depends how much of it is calling APIs. Probably both.
Websites, Blogs, ... JavaScript is your friend

Or: WebAssembly is great for computational tasks, stuff with numbers, but still needs some time to become more convenient and efficient at the same time where sharing numbers between the module and the host is not enough.

# Is AssemblyScript faster than JavaScript?

Not always, but there are use cases especially well-suited for it, like creating a Game Boy emulator by making use of its low-level capabilities, essentially emitting raw WebAssembly using a nicer syntax. But pre-existing TypeScript code doesn't magically become faster just by compiling to WebAssembly, especially when making extensive use of managed objects that require memory management and garbage collection (this has its cost in every language) or talking to the host in structures that WebAssembly isn't currently good at, like strings or more complex objects. Low-level code (just functions, numbers, math and hard work) is always the best choice when all you care about is raw performance.

# Will AssemblyScript support all of TypeScript eventually?

It very likely won't. While TypeScript adds some static typing to JavaScript, its type system also tries to describe any possible dynamic feature of JavaScript. TypeScript is a superset of JavaScript after all. As such there is a point where it becomes infeasible to support JavaScript features that TypeScript can describe without adding an interpreter mode to AssemblyScript, which is a non-goal.

# How can I help?

There are various ways to help. AssemblyScript is an open source project, and everyone is welcome to contribute code (opens new window), documentation (opens new window), or time. We also have an OpenCollective (opens new window) for those preferring to help the project out with a sponsorship.

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/garbage-collection.html b/garbage-collection.html new file mode 100644 index 000000000..47c4e7b80 --- /dev/null +++ b/garbage-collection.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/getting-started.html b/getting-started.html new file mode 100644 index 000000000..d35db34bb --- /dev/null +++ b/getting-started.html @@ -0,0 +1,135 @@ + + + + + + Getting started | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Getting started

Paving the way to your first AssemblyScript module.

# Setting up a new project

Make sure that a recent version of Node.js (opens new window) and its package manager npm (that comes with Node.js) are installed, then switch to a new directory and initialize a new Node.js module as usual:

npm init
+

Install the AssemblyScript compiler. Let's assume that it is not required in production and make it a development dependency:

npm install --save-dev assemblyscript
+

Once installed, the compiler provides a handy scaffolding utility to quickly set up a new project, here in the current directory:

npx asinit .
+

The asinit command automatically creates the recommended directory structure and configuration files:

  ./assembly
+  Directory holding the AssemblyScript sources being compiled to WebAssembly.
+
+  ./assembly/tsconfig.json
+  TypeScript configuration inheriting recommended AssemblyScript settings.
+
+  ./assembly/index.ts
+  Example entry file being compiled to WebAssembly to get you started.
+
+  ./build
+  Build artifact directory where compiled WebAssembly files are stored.
+
+  ./build/.gitignore
+  Git configuration that excludes compiled binaries from source control.
+
+  ./asconfig.json
+  Configuration file defining both a 'debug' and a 'release' target.
+
+  ./package.json
+  Package info containing the necessary commands to compile to WebAssembly.
+
+  ./tests/index.js
+  Starter test to check that the module is functioning.
+
+  ./index.html
+  Starter HTML file that loads the module in a browser.
+

For completeness, asinit supports the following options:

Sets up a new AssemblyScript project or updates an existing one.
+
+SYNTAX
+  asinit directory [options]
+
+EXAMPLES
+  asinit .
+  asinit ./newProject -y
+
+OPTIONS
+  --help, -h            Prints this help message.
+  --yes, -y             Answers all questions with their default option
+                        for non-interactive usage.
+

# Working with your module

The example in assembly/index.ts can now be compiled to WebAssembly by invoking the build command:

npm run asbuild
+

Doing so will emit the compiled binaries, bindings and definition files to the build/ directory.

The generated test case in tests/index.js can be executed with:

npm test
+

Once built, the directory contains all the bits to use the module like any other modern Node.js +ESM module:

import * as myModule from "myModule";
+

The generated index.html shows how the module can be used on the Web. A web server serving +the module directory, defaulting to display index.html, can be started with:

npm start
+

Note that not all of the files may be required depending on the use case, and it is safe +to delete what's not needed. If anything goes wrong, asinit can be executed again, which +would restore the deleted default files while keeping already edited ones.

# The journey ahead

So far, so good! Now it is time to start editing the project of course, which typically involves:

  • Editing and adding source files within the assembly/ directory and updating the tests in tests/.

  • Tweaking compiler options in asconfig.json to fit your project's needs.

  • Realizing that WebAssembly still has a ways to go 🙂

But that's it already for a quick start. Read on to learn more!

+ ← + + Using the compiler + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/images/chrome.svg b/images/chrome.svg new file mode 100644 index 000000000..79d4a92a5 --- /dev/null +++ b/images/chrome.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/component-mismatch.svg b/images/component-mismatch.svg new file mode 100644 index 000000000..c52fca37a --- /dev/null +++ b/images/component-mismatch.svg @@ -0,0 +1,4 @@ + + + +
Rust-like
Component
Rust-like...
Rust-like
Component
Rust-like...
Java-like
Component
Java-like...
Java-like
Component
Java-like...
Rust-like
Component
Rust-like...
Web platform
Web platform
Web platform
Web platform
Java-like
Component
Java-like...
✔️
✔️
✔️
✔️
❌
❌
❌
❌
❔
❔
✔️ Compatible        ❔ Moot 
✔️ Compatible        ❔ Moot CauseEffect
❌ Incompatible
❌ IncompatibleText is not SVG - cannot display \ No newline at end of file diff --git a/images/firefox.svg b/images/firefox.svg new file mode 100644 index 000000000..bb05ab914 --- /dev/null +++ b/images/firefox.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/game-of-life-preview.jpg b/images/game-of-life-preview.jpg new file mode 100644 index 000000000..46dcada01 Binary files /dev/null and b/images/game-of-life-preview.jpg differ diff --git a/images/header.svg b/images/header.svg new file mode 100644 index 000000000..222c8e3a6 --- /dev/null +++ b/images/header.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/images/icon.png b/images/icon.png new file mode 100644 index 000000000..2ffe8dda6 Binary files /dev/null and b/images/icon.png differ diff --git a/images/icon.svg b/images/icon.svg new file mode 100644 index 000000000..8277743b5 --- /dev/null +++ b/images/icon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/images/interference-preview.jpg b/images/interference-preview.jpg new file mode 100644 index 000000000..1a15f5c6b Binary files /dev/null and b/images/interference-preview.jpg differ diff --git a/images/logo.png b/images/logo.png new file mode 100644 index 000000000..df97a156c Binary files /dev/null and b/images/logo.png differ diff --git a/images/logo.svg b/images/logo.svg new file mode 100644 index 000000000..c225043b6 --- /dev/null +++ b/images/logo.svg @@ -0,0 +1,4 @@ + + + + diff --git a/images/managedobjectlayout.svg b/images/managedobjectlayout.svg new file mode 100644 index 000000000..1c3a5b131 --- /dev/null +++ b/images/managedobjectlayout.svg @@ -0,0 +1,3 @@ + + +
1
1HEADER- mmInfo: usize- gcInfo: u32- rtId: u32- rtSize: u32StringHEADER- [0]: u16- ...- [n]: u16
Any reference points
right after the header
Any reference points...
+ public # protected - private ~ public unsafe
+ public # protected - private ~ public...
1
1ArrayBufferViewHEADER+ buffer: ArrayBuffer~ dataStart: usize+ byteLength: i32ArrayBufferHEADER- [0]: u8- ...- [n]: u8Uint8ArrayArrayBufferViewInt16ArrayArrayBufferViewArray<T>HEADER- buffer: ArrayBuffer- dataStart: usize- byteLength: i32+ length: i32
...
...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/images/mandelbrot-preview.jpg b/images/mandelbrot-preview.jpg new file mode 100644 index 000000000..dc241bb1e Binary files /dev/null and b/images/mandelbrot-preview.jpg differ diff --git a/images/nodejs.svg b/images/nodejs.svg new file mode 100644 index 000000000..542e75268 --- /dev/null +++ b/images/nodejs.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/noimage.png b/images/noimage.png new file mode 100644 index 000000000..e18d78283 Binary files /dev/null and b/images/noimage.png differ diff --git a/images/reference-hierarchy.svg b/images/reference-hierarchy.svg new file mode 100644 index 000000000..11559dab5 --- /dev/null +++ b/images/reference-hierarchy.svg @@ -0,0 +1,4 @@ + + + +Wasm-internal references
any
any
eq
eq
i31
i31
struct
struct
array
array
null
null
(...)
(...)
null
null
(...)
(...)
null
null
string
string
null
nullExternal references
extern
extern
nullextern
nullexternFunction references
func
func
(...)
(...)
nullfunc
nullfunc
Working draft. The design is still in flux and support is incomplete / preliminary.
Working draft. The design is still in flux and support is incomplete / preliminary.String references
stringview_wtf8
stringview_wtf8
?
?
stringview_wtf16
stringview_wtf16
?
?
stringview_iter
stringview_iter
?
?Text is not SVG - cannot display \ No newline at end of file diff --git a/images/safari.svg b/images/safari.svg new file mode 100644 index 000000000..951a7e52c --- /dev/null +++ b/images/safari.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/wasi-mismatch.svg b/images/wasi-mismatch.svg new file mode 100644 index 000000000..2c8212eb8 --- /dev/null +++ b/images/wasi-mismatch.svg @@ -0,0 +1,4 @@ + + + +Cause



Web platform
Web platform...
WASI polyfill
in JavaScript
WASI polyfill...
WASI host
WASI host
Rust-like
Module
Rust-like...
Rust-like
Module
Rust-like...
Moot
MootEffect
Java-like
Module



Java-like...



Web platform
Web platform...
WASI shim
in WebAssembly
WASI shim...
WASI host
WASI host
Conceptional breakage
Conceptional breakage
WASI polyfill
in JavaScript
WASI polyfill...
Bloated & incompatible
Bloated & incompatible
Bloated
Bloated
Java-like
Module



Java-like...
WASI shim
in WebAssembly
WASI shim...Text is not SVG - cannot display \ No newline at end of file diff --git a/images/wasmer.svg b/images/wasmer.svg new file mode 100644 index 000000000..b18c1d94c --- /dev/null +++ b/images/wasmer.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/index.html b/index.html new file mode 100644 index 000000000..c87fcfceb --- /dev/null +++ b/index.html @@ -0,0 +1,79 @@ + + + + + + AssemblyScript + + + + + + + + + + + + + + + + + + +

A TypeScript-like language for WebAssembly.

+ Get Started + GitHub npm

Designed for WebAssembly

AssemblyScript targets WebAssembly's feature set specifically, giving developers low-level control over their code.

Familiar TypeScript syntax

Its similarity with TypeScript makes it easy to compile to WebAssembly without learning a new language.

Right at your fingertips

Integrates with the existing Web ecosystem - no heavy toolchains to set up. Simply npm install it!

#!runtime=stub
+/** Calculates the n-th Fibonacci number. */
+export function fib(n: i32): i32 {
+  var a = 0, b = 1
+  if (n > 0) {
+    while (--n) {
+      let t = a + b
+      a = b
+      b = t
+    }
+    return b
+  }
+  return a
+}
+
+#!html
+<textarea id="output" style="height: 100%; width: 100%" readonly></textarea>
+<script type="module">
+const exports = await instantiate(await compile(), { /* imports */ })
+const output = document.getElementById('output')
+for (let i = 0; i <= 10; ++i) {
+  output.value += `fib(${i}) = ${exports.fib(i)}\n`
+}
+</script>
+

AssemblyScript is free and open source software released under the Apache License, Version 2.0, builds upon Binaryen and is based on the WebAssembly specification. It is brought to you by the following awesome people:

Contributors

dcodeIOMaxGraeyHerrCai0907jtennerCountBleckJesseCodeBonesyjhmelodyromdotdogtorch2424technohippysaulecabreraLiaoPengalangpierceColinEberhardtDuncanUszkay1nidinsurmawillemnealLinusUFGasperghalimiandy-hansonforcepusherkazuponjayphelpsgzuidhofmattjohnsonpintFloorLampPinkaminaDianePiepiotr-olessidx1024ApsarasXJairusSWadurosphamannfatjonnyccouzenstrusktrmaxlkatcwellsErnestoBorioTyriardawsbotRehkitzDevsunfishcodeprogrammerjakemmathysporia-catpvoronanischayvWscatsrottencandycoder0107git

Why AssemblyScript?

“You are now able to write WebAssembly without learning a new language, and harness all these benefits WebAssembly might offer you. I think that is kind of powerful. AssemblyScript is absolutely usable, and very enjoyable!” – Surma, WebAssembly for Web Developers (Google I/O ’19)

“AssemblyScript is designed with WebAssembly and code size in mind. It's not an existing language that we are using for a new purpose but it's a language designed for WebAssembly. It has great wasm-opt integration, in fact it's built with it, and it's very easy to get good code size.” – Alon Zakai, Shipping Tiny WebAssembly Builds (WebAssembly Summit)

“I chose AssemblyScript because it has high-level readability and low-level control. It's like a high-level language but you get that low-level feeling and you can even directly write WebAssembly intrinsics if you want to.” – Peter Salomonsen, WebAssembly Music (WebAssembly Summit)

Thanks to our sponsors!

Most of the maintainers and contributors do this open source work in their free time. If you use AssemblyScript for a serious task or plan to do so, and you'd like us to invest more time on it, please donate to our OpenCollective. By sponsoring this project, your logo will show up below. Thank you so much for your support!

Gold Sponsors

NEAR FoundationShopifyThe GraphChainSafe Systems

Silver Sponsors

STOICFunrize™ Social CasinoWasmBook.com

Bronze Sponsors

Ryan ZurrerAlon ZakaiІгрові автоматиTriplebyteRoute4Me Route PlannerNoLimitCoinsFlint

Individual Backers

Riversweeps Sweepstakes SoftwareWebScraping.AI777 казиноTom BallingerОнлайн Казино Украины#1 Sweepstakes Software for Internet CafesОнлайн казино slotoking УкраїнаHoofdkantoorJordan TimmermanІгрові автоматиForrest MoretJacob RichardsCharlie ArnoldІгрові автоматиОнлайн казино УкраїниТоп казиноTaylor ClarkHarry SolovayFunz Citytakanori sugawaraJonathan BeriJack ArringtonJeff Wainwrightemmanuelm41Agung Sidharta SoStrapisri sai swaroopEzra SavardincognitoJulius ShapiroRubenD777Open Source CollectiveRobinMaryGuest

Join our Discord

If you have questions only a human can answer, would like to show others what you are working on or just want to hang out with other AssemblyScript folks, make sure to join our Discord server! There you'll find channels for #announcements, #help, and more.

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/interoperability.html b/interoperability.html new file mode 100644 index 000000000..47c4e7b80 --- /dev/null +++ b/interoperability.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/introduction.html b/introduction.html new file mode 100644 index 000000000..d4ece627a --- /dev/null +++ b/introduction.html @@ -0,0 +1,103 @@ + + + + + + Introduction | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Introduction

AssemblyScript compiles a variant of TypeScript (opens new window) (a typed superset of JavaScript) to WebAssembly (opens new window) using Binaryen (opens new window), looking like:

export function fib(n: i32): i32 {
+  var a = 0, b = 1
+  if (n > 0) {
+    while (--n) {
+      let t = a + b
+      a = b
+      b = t
+    }
+    return b
+  }
+  return a
+}
+
asc fib.ts --outFile fib.wasm --optimize
+

It is similiar to TypeScript but with WebAssembly types, has some constraints due to compiling strictly typed code ahead of time, but also some additions originating in WebAssembly's feature set. While not all of TypeScript can be supported, its close relation to JavaScript makes it a familiar choice for developers who are already used to writing code for the Web, and also has the potential to integrate seamlessly with existing Web Platform concepts to produce lean and mean WebAssembly modules.

# From a WebAssembly perspective

AssemblyScript provides WebAssembly and compiler foundations as built-in functions, making it suitable as a thin layer on top of raw WebAssembly. For example, memory can be accessed using built-in functions that compile to WebAssembly instructions directly:

store<i32>(ptr, load<i32>(ptr) + load<i32>(ptr, 4), 8)
+

For comparison, the following C code is roughly equivalent:

*(ptr + 2) = *ptr + *(ptr + 1)
+

Most WebAssembly instructions can also be written directly in AssemblyScript code, with generic variants available as well:

i32.ctz(...)             // ctz<i32>(...)
+f64.reinterpret_i64(...) // reinterpret<f64>(...)
+i64.load32_u(...)        // <i64>load<u32>(...)
+...
+

# From a JavaScript perspective

Implemented on top of its low-level capabilities, AssemblyScript provides a JavaScript-like standard library with many of the classes and namespaces one is used to from JavaScript, including Math (also Mathf for single precision), Array<T>, String, Map<K,V>, the typed arrays and so on.

The load/store example above could look like this when utilizing the standard library:

var view = new Int32Array(12)
+...
+view[2] = view[0] + view[1]
+

Both perspectives can be mixed depending on whether low-level control with WebAssembly instructions or idiomatic concepts with the managed standard library are desirable to accomplish an individual task.

# Frequently asked questions

Does AssemblyScript involve an interpreter, or a "VM in a VM"?

No, AssemblyScript compiles to WebAssembly bytecode directly, statically, ahead-of-time.

What are the differences between AssemblyScript and TypeScript?

TypeScript transpiles down to JavaScript, a dynamic just-in-time compiled language. AssemblyScript, on the other hand, compiles to a static WebAssembly binary. Their compiler implementations are quite different. However, the two languages are so very similar on the surface that they share many concepts. For example, TypeScript tooling can be used to author and refactor AssemblyScript code and, with some effort, the same code base can be transpiled to JavaScript with tsc and compiled to WebAssembly with asc, or code shared. The AssemblyScript compiler itself is portable.

Will AssemblyScript support all of TypeScript eventually?

It likely won't. While TypeScript adds typings to JavaScript, it is a superset after all and can describe many of JavaScript's dynamic features, not all of which are feasible to support in ahead-of-time compilation. Yet, sufficiently strict TypeScript code can often be made compatible with the AssemblyScript compiler with little effort.

What are good use cases for AssemblyScript?

Computation-heavy logic like image manipulation, hot game logic, specialized algorithms, emulators, compilers and the likes are great use cases for WebAssembly, and as such for AssemblyScript as well. In some situations it may also be preferable to ship bytecode instead of minified JS, or just the ability to utilize a TypeScript-like language may open up new opportunities, for example for embedded scripting or plugins.

Can AssemblyScript be used in non-standard ways, say outside of the browser?

Absolutely! AssemblyScript modules are self-contained and run anywhere where WebAssembly is supported. In fact, any arbitrary host interface can be supported. Here is an example of using WASI imports instead of Web APIs (opens new window).

Why the strange name?

AssemblyScript is to Assembly as JavaScript is to Java. Not quite.

But now, let's get started!

+ Getting started + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/loader.html b/loader.html new file mode 100644 index 000000000..db562f9c3 --- /dev/null +++ b/loader.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/memory.html b/memory.html new file mode 100644 index 000000000..47c4e7b80 --- /dev/null +++ b/memory.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/portability.html b/portability.html new file mode 100644 index 000000000..599aa201a --- /dev/null +++ b/portability.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..067734fec --- /dev/null +++ b/quick-start.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/robots.txt b/robots.txt new file mode 100644 index 000000000..c2b997f2d --- /dev/null +++ b/robots.txt @@ -0,0 +1,7 @@ +User-agent: * +Disallow: /404 +Disallow: /404.html +Disallow: /editor +Disallow: /editor.html +Disallow: /editor-test +Disallow: /editor-test.html diff --git a/runtime.html b/runtime.html new file mode 100644 index 000000000..43d3e0e38 --- /dev/null +++ b/runtime.html @@ -0,0 +1,94 @@ + + + + + + Runtime | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Runtime

The AssemblyScript runtime implements the necessary bits for memory management and garbage collection. It is largely invisible to a developer but can become relevant in advanced use cases, for example when integrating AssemblyScript in new environments.

TIP

If not applicable to your use case, i.e. it is not necessary to interact with the runtime directly, you can safely skip this section.

# Variants

The runtime comes in different flavors, each useful in different use cases. The desired runtime can be specified with the --runtime compiler option:

  --runtime             Specifies the runtime variant to include in the program.
+
+                         incremental  TLSF + incremental GC (default)
+                         minimal      TLSF + lightweight GC invoked externally
+                         stub         Minimal runtime stub (never frees)
+                         ...          Path to a custom runtime implementation
+
+  --exportRuntime       Exports the runtime helpers (__new, __collect etc.).
+

The default incremental runtime provides the full package recommended in most use cases. The minimal runtime is a stripped down variant (no shadow stack, no heuristic, simpler algorithm, smaller and more efficient) that is not automated and requires calling __collect externally at appropriate times (when there are no more values on the WebAssembly stack, which would be the case when WebAssembly calls out to the host, directly or indirectly), whereas the stub runtime does not provide a garbage collector at all and never frees (simple bump allocation, extremely small).

For example, the stub runtime can be useful where modules are short-lived and collected as a whole anyhow, while the minimal runtime provides a compromise for use cases where it is sufficient to collect garbage manually, occasionally, say where a module performs a fixed amount of work before being invoked again.

In case of doubt, use incremental, but feel free to experiment with the other potentially more efficient variants where a use case permits.

# Interface

Using the --exportRuntime compiler option, the runtime interface can be exported from the module to the host, so it becomes possible to allocate new managed objects and invoke the garbage collector externally.

It is typically not necessary to invoke the runtime interface manually since generated bindings take care of all the internals. In environments where bindings are not yet available, however, the runtime interface can be utilized to provide the necessary integration.

  • function __new(size: usize, id: u32): usize
+

    Allocates a new garbage collected instance of the object represented by the specified class id, of at least the specified size. Returns the pointer to the object (pointing at its data, not its internal header).

  • function __pin(ptr: usize): usize
+

    Pins the object pointed to by ptr externally so it and any object it references do not become garbage collected. Note that the same object cannot be pinned more than once.

    An external object that is not referenced from within WebAssembly must be pinned whenever an allocation might happen in between allocating it and passing it to WebAssembly. If not pinned, the allocation may trigger the garbage collector to step, which would prematurely collect the object and lead to undefined behavior.

  • function __unpin(ptr: usize): void
+

    Unpins the object pointed to by ptr externally so it can become garbage collected. Note that the respective object must have been pinned before for the unpin operation to succeed.

  • function __collect(): void
+

    Performs a full garbage collection.

  • const __rtti_base: usize
+

    Pointer to runtime type information in linear memory. RTTI contains information about the various classes utilized in a binary, mapping class ids to object kinds, their key and value layout, and base classes. Its layout is described in detail in shared/typeinfo (opens new window). Using RTTI, it becomes possible to implement instanceof for example, or to tell strings, arrays etc. apart.

# Memory layout

Overall, AssemblyScript partitions linear memory as follows:

Region Start offset End offset Description
Static data 0 __data_end Contents of static strings, arrays, etc.
Managed stack __data_end __heap_base Present only if the incremental runtime is used.
Heap __heap_base memory.size() << 16 Remaining space is used for dynamic allocations. Can grow.

# Header layout

Any kind of managed object in AssemblyScript utilizes a managed header for the runtime to operate on:

Name Offset Type Description
mmInfo -20 usize Memory manager info
gcInfo -16 usize Garbage collector info
gcInfo2 -12 usize Garbage collector info
rtId -8 u32 Unique id of the concrete class
rtSize -4 u32 Size of the data following the header
0 Payload starts here

References to an object always point at the start of the payload, with the header beginning 20 bytes before. Null references are just the value 0. When working with an AssemblyScript module externally, knowing the memory layout can be helpful to for example obtain an object's class id or size. Invoking __new automatically prepends a managed header and registers the object with the GC, using the provided class id for rtId and the provided size for rtSize.

# Class layout

Class fields are laid out similarly to C structs, sequentially and without packing. Each field is aligned to its type's native alignment, potentially leaving padding in between. If a class has the @unmanaged decorator, it effectively only describes a region of memory as if it were a struct that does not utilize a managed header, is not garbage collected, and can be used with heap.free. Managed classes with a managed header cannot be manually freed, and managed and unmanaged classes cannot be mixed (e.g. extend from each other).

Standard library data types use the following layouts:

Class Description
Object Object, the base class of all managed classes, has a class id of 0.
ArrayBuffer Buffers always use class id 1, with their untyped data as the payload.
String Strings always use class id 2, with their 16-bit char codes (UTF-16 code units, allowing isolated surrogates like JS) as the payload. For example, if rtSize is 8, the string's .length is 4.
TypedArray Typed arrays are objects composed of buffer (the reference to the viewed ArrayBuffer), dataStart (the start pointer into buffer) and byteLength fields, in this order. The respective id is picked sequentially and not predetermined.
Array<T> Normal arrays use the same layout as typed arrays, with an additional mutable length field coming last.
StaticArray<T> Static arrays do not need indirection due to not being resizable, and they have their data right in the payload, aligned according to T. Can be thought of as a typed buffer.
Function Functions are objects composed of their table index and their lexical env (currently always 0).
Map/Set/... Other collection use more complex layouts. Please refer to their respective sources.

It is also possible to build custom data types that integrate with the GC by implementing the __visit interface (that iterates all references contained in an object of this kind). Please refer to the sources of preexisting data types for examples.

# Calling convention

AssemblyScript's calling convention is relatively straight forward, as it does not add additional parameters to functions or other behind-the-scenes magic. Note that generated bindings take care of the calling convention automatically, but other environments may want to adhere to it specifically.

# Basic values

Exported functions wrap basic numeric return values to their respective value ranges. Basic numeric values passed to exported functions are wrapped to their respective value ranges on demand.

# Managed values

Any kind of object is passed as a pointer into memory, and the host is expected to perform the steps necessary to exchange the value between linear memory and the host system. For example, when a string is passed from WebAssembly to the host or vice-versa, it is not its data that is passed but a pointer to the string's data in linear memory. In order to read the data, the managed header before the payload can be evaluated to obtain the string's byte length. Note that host bindings automate this process for common data types.

# Optional arguments

When an exported function allows one or multiple arguments to be omitted, the module must be informed of the number of significant arguments by calling exports.__setArgumentsLength(numArgs) before calling the export, so it can fill in default values. Omitted arguments are not evaluated, i.e. zeroes can be passed. Not calling the helper leads to undefined behavior. If a function has a fixed number of arguments, it is not necessary to call the helper. The helper may not be present if a module only exports functions with a fixed number of arguments.

+ ← +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/scripts/wat.js b/scripts/wat.js new file mode 100644 index 000000000..9f07b5c3c --- /dev/null +++ b/scripts/wat.js @@ -0,0 +1,713 @@ +// 'WebAssembly Text Format' Monarch language + +var WebAssemblyTextLanguage = { + config: { + brackets: [ + ['(', ')'], + ['if', 'end'], + ['loop', 'end'], + ['block', 'end'] + ], + autoClosingPairs: [ + { open: '(', close: ')' }, + { open: 'if', close: 'end' }, + { open: 'loop', close: 'end' }, + { open: 'block', close: 'end' } + ], + surroundingPairs: [ + { open: '(', close: ')' }, + { open: 'if', close: 'end' }, + { open: 'loop', close: 'end' }, + { open: 'block', close: 'end' } + ] + }, + tokens: { + keywords: [ + 'module', + 'import', + 'export', + 'memory', + 'data', + 'table', + 'elem', + 'start', + 'func', + 'tag', + 'type', + 'param', + 'result', + 'global', + 'local', + 'mut', + 'struct', + 'array', + 'field' + ], + types: [ + 'i8', + 'i16', + 'i32', + 'i64', + 'f32', + 'f64', + 'v128', + 'i31ref', + 'eqref', + 'anyref', + 'dataref', + 'externref', + 'funcref', + 'exnref', + 'extern', + 'null', + 'any', + 'eq' + ], + instructions: [ + 'pop', + 'nop', + 'drop', + 'data.drop', + 'elem.drop', + 'local.get', + 'local.set', + 'local.tee', + 'global.get', + 'global.set', + 'tuple.make', + 'tuple.extract', + 'select', + 'v128.const', + 'v128.and', + 'v128.or', + 'v128.xor', + 'v128.not', + 'v128.andnot', + 'v128.bitselect', + 'v128.load', + 'v128.load8x8_s', + 'v128.load8x8_u', + 'v128.load16x4_s', + 'v128.load16x4_u', + 'v128.load32x2_s', + 'v128.load32x2_u', + 'v128.load8_lane', + 'v128.load16_lane', + 'v128.load32_lane', + 'v128.load64_lane', + 'v128.load8_splat', + 'v128.load16_splat', + 'v128.load32_splat', + 'v128.load64_splat', + 'v128.load32_zero', + 'v128.load64_zero', + 'v128.store', + 'v128.store8_lane', + 'v128.store16_lane', + 'v128.store32_lane', + 'v128.store64_lane', + 'v128.any_true', + 'i8x16.shuffle', + 'i8x16.swizzle', + 'i8x16.bitmask', + 'i8x16.splat', + 'i8x16.popcnt', + 'i8x16.replace_lane', + 'i8x16.extract_lane_s', + 'i8x16.extract_lane_u', + 'i8x16.all_true', + 'i8x16.abs', + 'i8x16.add', + 'i8x16.add_sat_s', + 'i8x16.add_sat_u', + 'i8x16.sub', + 'i8x16.sub_sat_s', + 'i8x16.sub_sat_u', + 'i8x16.mul', + 'i8x16.neg', + 'i8x16.shl', + 'i8x16.shr_s', + 'i8x16.shr_u', + 'i8x16.eq', + 'i8x16.ne', + 'i8x16.lt_s', + 'i8x16.lt_u', + 'i8x16.le_s', + 'i8x16.le_u', + 'i8x16.gt_s', + 'i8x16.gt_u', + 'i8x16.ge_s', + 'i8x16.ge_u', + 'i8x16.min_s', + 'i8x16.min_u', + 'i8x16.max_s', + 'i8x16.max_u', + 'i8x16.avgr_u', + 'i8x16.narrow_i16x8_s', + 'i8x16.narrow_i16x8_u', + 'i16x8.bitmask', + 'i16x8.splat', + 'i16x8.load_8x8_s', + 'i16x8.load_8x8_u', + 'i16x8.replace_lane', + 'i16x8.extract_lane_s', + 'i16x8.extract_lane_u', + 'i16x8.extend_low_i8x16_s', + 'i16x8.extend_high_i8x16_s', + 'i16x8.extend_low_i8x16_u', + 'i16x8.extend_high_i8x16_u', + 'i16x8.all_true', + 'i16x8.abs', + 'i16x8.add', + 'i16x8.add_sat_s', + 'i16x8.add_sat_u', + 'i16x8.extadd_pairwise_i8x16_s', + 'i16x8.extadd_pairwise_i8x16_u', + 'i16x8.sub', + 'i16x8.sub_sat_s', + 'i16x8.sub_sat_u', + 'i16x8.q15mulr_sat_s', + 'i16x8.mul', + 'i16x8.extmul_low_i8x16_s', + 'i16x8.extmul_high_i8x16_s', + 'i16x8.extmul_low_i8x16_u', + 'i16x8.extmul_high_i8x16_u', + 'i16x8.neg', + 'i16x8.shl', + 'i16x8.shr_s', + 'i16x8.shr_u', + 'i16x8.eq', + 'i16x8.ne', + 'i16x8.lt_s', + 'i16x8.lt_u', + 'i16x8.le_s', + 'i16x8.le_u', + 'i16x8.gt_s', + 'i16x8.gt_u', + 'i16x8.ge_s', + 'i16x8.ge_u', + 'i16x8.min_s', + 'i16x8.min_u', + 'i16x8.max_s', + 'i16x8.max_u', + 'i16x8.avgr_u', + 'i16x8.narrow_i32x4_s', + 'i16x8.narrow_i32x4_u', + 'i32x4.bitmask', + 'i32x4.splat', + 'i32x4.load_16x4_s', + 'i32x4.load_16x4_u', + 'i32x4.replace_lane', + 'i32x4.extract_lane', + 'i32x4.extend_low_i16x8_s', + 'i32x4.extend_high_i16x8_s', + 'i32x4.extend_low_i16x8_u', + 'i32x4.extend_high_i16x8_u', + 'i32x4.all_true', + 'i32x4.abs', + 'i32x4.add', + 'i32x4.extadd_pairwise_i16x8_s', + 'i32x4.extadd_pairwise_i16x8_u', + 'i32x4.sub', + 'i32x4.mul', + 'i32x4.extmul_low_i16x8_s', + 'i32x4.extmul_high_i16x8_s', + 'i32x4.extmul_low_i16x8_u', + 'i32x4.extmul_high_i16x8_u', + 'i32x4.neg', + 'i32x4.shl', + 'i32x4.shr_s', + 'i32x4.shr_u', + 'i32x4.eq', + 'i32x4.ne', + 'i32x4.lt_s', + 'i32x4.lt_u', + 'i32x4.le_s', + 'i32x4.le_u', + 'i32x4.gt_s', + 'i32x4.gt_u', + 'i32x4.ge_s', + 'i32x4.ge_u', + 'i32x4.min_s', + 'i32x4.min_u', + 'i32x4.max_s', + 'i32x4.max_u', + 'i32x4.trunc_sat_f32x4_s', + 'i32x4.trunc_sat_f32x4_u', + 'i32x4.trunc_sat_f64x2_s_zero', + 'i32x4.trunc_sat_f64x2_u_zero', + 'i32x4.dot_i16x8_s', + 'i64x2.bitmask', + 'i64x2.splat', + 'i64x2.load32x2_s', + 'i64x2.load32x2_u', + 'i64x2.replace_lane', + 'i64x2.extract_lane', + 'i64x2.extend_low_i32x4_s', + 'i64x2.extend_high_i32x4_s', + 'i64x2.extend_low_i32x4_u', + 'i64x2.extend_high_i32x4_u', + 'i64x2.all_true', + 'i64x2.abs', + 'i64x2.add', + 'i64x2.sub', + 'i64x2.mul', + 'i64x2.neg', + 'i64x2.shl', + 'i64x2.shr_s', + 'i64x2.shr_u', + 'f32x4.splat', + 'f32x4.replace_lane', + 'f32x4.extract_lane', + 'f32x4.add', + 'f32x4.sub', + 'f32x4.mul', + 'i64x2.extmul_low_i32x4_s', + 'i64x2.extmul_high_i32x4_s', + 'i64x2.extmul_low_i32x4_u', + 'i64x2.extmul_high_i32x4_u', + 'i64x2.eq', + 'i64x2.ne', + 'i64x2.lt_s', + 'i64x2.le_s', + 'i64x2.gt_s', + 'i64x2.ge_s', + 'f32x4.neg', + 'f32x4.eq', + 'f32x4.ne', + 'f32x4.lt', + 'f32x4.le', + 'f32x4.gt', + 'f32x4.ge', + 'f32x4.abs', + 'f32x4.min', + 'f32x4.pmin', + 'f32x4.max', + 'f32x4.pmax', + 'f32x4.div', + 'f32x4.sqrt', + 'f32x4.ceil', + 'f32x4.floor', + 'f32x4.trunc', + 'f32x4.nearest', + 'f32x4.demote_f64x2_zero', + 'f32x4.convert_i32x4_s', + 'f32x4.convert_i32x4_u', + 'f64x2.splat', + 'f64x2.replace_lane', + 'f64x2.extract_lane', + 'f64x2.add', + 'f64x2.sub', + 'f64x2.mul', + 'f64x2.neg', + 'f64x2.eq', + 'f64x2.ne', + 'f64x2.lt', + 'f64x2.le', + 'f64x2.gt', + 'f64x2.ge', + 'f64x2.abs', + 'f64x2.min', + 'f64x2.max', + 'f64x2.pmin', + 'f64x2.pmax', + 'f64x2.div', + 'f64x2.sqrt', + 'f64x2.ceil', + 'f64x2.floor', + 'f64x2.trunc', + 'f64x2.nearest', + 'f64x2.promote_low_f32x4', + 'f64x2.convert_low_i32x4_s', + 'f64x2.convert_low_i32x4_u', + 'i32.atomic.load', + 'i32.atomic.load8_u', + 'i32.atomic.load16_u', + 'i32.atomic.store', + 'i32.atomic.store8', + 'i32.atomic.store16', + 'i32.atomic.rmw.add', + 'i32.atomic.rmw.sub', + 'i32.atomic.rmw.and', + 'i32.atomic.rmw.or', + 'i32.atomic.rmw.xor', + 'i32.atomic.rmw.xchg', + 'i32.atomic.rmw.cmpxchg', + 'i32.atomic.rmw8.add_u', + 'i32.atomic.rmw8.sub_u', + 'i32.atomic.rmw8.and_u', + 'i32.atomic.rmw8.or_u', + 'i32.atomic.rmw8.xor_u', + 'i32.atomic.rmw8.xchg_u', + 'i32.atomic.rmw8.cmpxchg_u', + 'i32.atomic.rmw16.add_u', + 'i32.atomic.rmw16.sub_u', + 'i32.atomic.rmw16.and_u', + 'i32.atomic.rmw16.or_u', + 'i32.atomic.rmw16.xor_u', + 'i32.atomic.rmw16.xchg_u', + 'i32.atomic.rmw16.cmpxchg_u', + 'i64.atomic.load', + 'i64.atomic.load8_u', + 'i64.atomic.load16_u', + 'i64.atomic.load32_u', + 'i64.atomic.store', + 'i64.atomic.store8', + 'i64.atomic.store16', + 'i64.atomic.store32', + 'i64.atomic.rmw.add', + 'i64.atomic.rmw.sub', + 'i64.atomic.rmw.and', + 'i64.atomic.rmw.or', + 'i64.atomic.rmw.xor', + 'i64.atomic.rmw.xchg', + 'i64.atomic.rmw.cmpxchg', + 'i64.atomic.rmw8.add_u', + 'i64.atomic.rmw8.sub_u', + 'i64.atomic.rmw8.and_u', + 'i64.atomic.rmw8.or_u', + 'i64.atomic.rmw8.xor_u', + 'i64.atomic.rmw8.xchg_u', + 'i64.atomic.rmw8.cmpxchg_u', + 'i64.atomic.rmw16.add_u', + 'i64.atomic.rmw16.sub_u', + 'i64.atomic.rmw16.and_u', + 'i64.atomic.rmw16.or_u', + 'i64.atomic.rmw16.xor_u', + 'i64.atomic.rmw16.xchg_u', + 'i64.atomic.rmw16.cmpxchg_u', + 'i64.atomic.rmw32.add_u', + 'i64.atomic.rmw32.sub_u', + 'i64.atomic.rmw32.and_u', + 'i64.atomic.rmw32.or_u', + 'i64.atomic.rmw32.xor_u', + 'i64.atomic.rmw32.xchg_u', + 'i64.atomic.rmw32.cmpxchg_u', + 'atomic.fence', + 'func.bind', + 'ref', + 'ref.eq', + 'ref.null', + 'ref.is_null', + 'ref.is_func', + 'ref.is_data', + 'ref.is_i31', + 'ref.as_func', + 'ref.as_non_null', + 'ref.as_data', + 'ref.as_i31', + 'ref.func', + 'ref.cast', + 'ref.cast_static', + 'ref.test', + 'ref.test_static', + 'table.get', + 'table.set', + 'table.size', + 'table.grow', + 'table.fill', + 'table.init', + 'table.copy', + 'throw', + 'rethrow', + 'i32.load', + 'i32.load8_s', + 'i32.load8_u', + 'i32.load16_s', + 'i32.load16_u', + 'i32.store', + 'i32.store8', + 'i32.store16', + 'i32.const', + 'i32.eqz', + 'i32.eq', + 'i32.ne', + 'i32.lt_s', + 'i32.lt_u', + 'i32.le_s', + 'i32.le_u', + 'i32.gt_s', + 'i32.gt_u', + 'i32.ge_s', + 'i32.ge_u', + 'i32.clz', + 'i32.ctz', + 'i32.popcnt', + 'i32.add', + 'i32.sub', + 'i32.mul', + 'i32.div_s', + 'i32.div_u', + 'i32.rem_s', + 'i32.rem_u', + 'i32.and', + 'i32.or', + 'i32.xor', + 'i32.shl', + 'i32.shr_s', + 'i32.shr_u', + 'i32.rotl', + 'i32.rotr', + 'i32.wrap_i64', + 'i32.trunc_f32_s', + 'i32.trunc_f32_u', + 'i32.trunc_f64_s', + 'i32.trunc_f64_u', + 'i32.reinterpret_f32', + 'i64.load', + 'i64.load8_s', + 'i64.load8_u', + 'i64.load16_s', + 'i64.load16_u', + 'i64.load32_s', + 'i64.load32_u', + 'i64.store', + 'i64.store8', + 'i64.store16', + 'i64.store32', + 'i64.const', + 'i64.eqz', + 'i64.eq', + 'i64.ne', + 'i64.lt_s', + 'i64.lt_u', + 'i64.le_s', + 'i64.le_u', + 'i64.gt_s', + 'i64.gt_u', + 'i64.ge_s', + 'i64.ge_u', + 'i64.clz', + 'i64.ctz', + 'i64.popcnt', + 'i64.add', + 'i64.sub', + 'i64.mul', + 'i64.div_s', + 'i64.div_u', + 'i64.rem_s', + 'i64.rem_u', + 'i64.and', + 'i64.or', + 'i64.xor', + 'i64.shl', + 'i64.shr_s', + 'i64.shr_u', + 'i64.rotl', + 'i64.rotr', + 'i64.extend_i32_s', + 'i64.extend_i32_u', + 'i64.trunc_f32_s', + 'i64.trunc_f32_u', + 'i64.trunc_f64_s', + 'i64.trunc_f64_u', + 'i64.reinterpret_f64', + 'f32.load', + 'f32.store', + 'f32.const', + 'f32.eq', + 'f32.ne', + 'f32.lt', + 'f32.le', + 'f32.gt', + 'f32.ge', + 'f32.abs', + 'f32.neg', + 'f32.ceil', + 'f32.floor', + 'f32.trunc', + 'f32.nearest', + 'f32.sqrt', + 'f32.add', + 'f32.sub', + 'f32.mul', + 'f32.div', + 'f32.min', + 'f32.max', + 'f32.copysign', + 'f32.convert_i32_s', + 'f32.convert_i32_u', + 'f32.convert_i64_s', + 'f32.convert_i64_u', + 'f32.demote_f64', + 'f32.reinterpret_i32', + 'f64.load', + 'f64.store', + 'f64.const', + 'f64.eq', + 'f64.ne', + 'f64.lt', + 'f64.le', + 'f64.gt', + 'f64.ge', + 'f64.abs', + 'f64.neg', + 'f64.ceil', + 'f64.floor', + 'f64.trunc', + 'f64.nearest', + 'f64.sqrt', + 'f64.add', + 'f64.sub', + 'f64.mul', + 'f64.div', + 'f64.min', + 'f64.max', + 'f64.copysign', + 'f64.convert_i32_s', + 'f64.convert_i32_u', + 'f64.convert_i64_s', + 'f64.convert_i64_u', + 'f64.promote_f32', + 'f64.reinterpret_i64', + 'i32.extend8_s', + 'i32.extend16_s', + 'i64.extend8_s', + 'i64.extend16_s', + 'i64.extend32_s', + 'i32.trunc_sat_f32_s', + 'i32.trunc_sat_f32_u', + 'i32.trunc_sat_f64_s', + 'i32.trunc_sat_f64_u', + 'i64.trunc_sat_f32_s', + 'i64.trunc_sat_f32_u', + 'i64.trunc_sat_f64_s', + 'i64.trunc_sat_f64_u', + 'memory.size', + 'memory.grow', + 'memory.copy', + 'memory.fill', + 'memory.init', + 'memory.atomic.notify', + 'memory.atomic.wait32', + 'memory.atomic.wait64', + 'i31.new', + 'i31.get_u', + 'i31.get_s', + 'array.new', + 'array.new_default', + 'array.init', + 'array.init_static', + 'array.get', + 'array.get_s', + 'array.get_u', + 'array.set', + 'array.len', + 'array.copy', + 'struct.new', + 'struct.new_default', + 'struct.new_with_rtt', + 'struct.new_default_with_rtt', + 'struct.get', + 'struct.get_s', + 'struct.get_u', + 'struct.set', + 'rtt.canon', + 'rtt.sub', + 'rtt.fresh_sub' + ], + controlInstructions: [ + 'block', + 'loop', + 'if', + 'else', + 'then', + 'end', + 'do', + 'let', + 'br', + 'br_if', + 'br_table', + 'br_on_exn', + 'br_on_null', + 'br_on_non_null', + 'br_on_cast', + 'br_on_cast_static', + 'br_on_cast_fail', + 'br_on_cast_static_fail', + 'br_on_func', + 'br_on_non_func', + 'br_on_data', + 'br_on_non_data', + 'br_on_i31', + 'br_on_non_i31', + 'call', + 'call_indirect', + 'call_ref', + 'return', + 'return_call', + 'return_call_indirect', + 'return_call_ref', + 'try', + 'catch', + 'catch_all', + 'delegate', + 'unreachable' + ], + + escapes: /\\(?:[abfnrtv\\"']|x[0-9A-Fa-f]{1,4}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})/, + digits: /\d+(_+\d+)*/, + octaldigits: /[0-7]+(_+[0-7]+)*/, + binarydigits: /[0-1]+(_+[0-1]+)*/, + hexdigits: /[[0-9a-fA-F]+(_+[0-9a-fA-F]+)*/, + + tokenizer: { + root: [ + + // whitespace + { include: '@whitespace' }, + + // strings + [/"([^"\\]|\\.)*$/, 'string.invalid'], // non-teminated string + [/"/, 'string', '@string'], + + // numbers (not all of these are generated, but here to be sure) + [/(@digits)[eE]([\-+]?(@digits))?[fFdD]?/, 'number.float'], + [/(@digits)\.(@digits)([eE][\-+]?(@digits))?[fFdD]?/, 'number.float'], + [/0[xX](@hexdigits)[Ll]?/, 'number.hex'], + [/0(@octaldigits)[Ll]?/, 'number.octal'], + [/0[bB](@binarydigits)[Ll]?/, 'number.binary'], + [/(@digits)[fFdD]/, 'number.float'], + [/(@digits)[lL]?/, 'number'], + + // variable names + [/\$[^\s\)]*/, { token: 'identifier' }], + + // instructions and types + [/[a-z0-9_]+(?:\.[a-z0-9_]+)*/, { + cases: { + '@types': { token: 'type.$0' }, + '@keywords': { token: 'keyword.$0' }, + '@controlInstructions': { token: 'controlInstruction.$0' }, + '@instructions': { token: 'instruction.$0' }, + '@default': 'identifier' + } + }] + ], + + string: [ + [/[^\\"]+/, 'string'], + [/@escapes/, 'string.escape'], + [/\\./, 'string.escape.invalid'], + [/"/, 'string', '@pop'] + ], + + whitespace: [ + [/[ \t\r\n]+/, ''], + [/(;; )(ERROR |FAILURE )([^\n]*)/, [ 'comment', 'error', '' ]], + [/(;; )(WARNING )([^\n]*)/, [ 'comment', 'warning', '' ]], + [/(;; )(INFO )([^\n]*)/, [ 'comment', 'info', '' ]], + [/(;; )(PEDANTIC )([^\n]*)/, [ 'comment', 'pedantic', '' ]], + [/(;; +)(~+|\^)$/, ['comment', 'underline']], + [/(;; )([^\n]*)/, ['comment', '']], + [/;;[^\n]*/, 'comment'] + ] + } + } +} + +if (typeof define === 'function' && define.amd) { + define(() => WebAssemblyTextLanguage) +} else if (typeof module === 'object' && module.exports) { + module.exports = WebAssemblyTextLanguage +} diff --git a/site.webmanifest b/site.webmanifest new file mode 100644 index 000000000..43d151574 --- /dev/null +++ b/site.webmanifest @@ -0,0 +1,19 @@ +{ + "name": "AssemblyScript", + "short_name": "AssemblyScript", + "icons": [ + { + "src": "/favicons/android-chrome-192x192.png", + "sizes": "192x192", + "type": "image/png" + }, + { + "src": "/favicons/android-chrome-512x512.png", + "sizes": "512x512", + "type": "image/png" + } + ], + "theme_color": "#ffffff", + "background_color": "#ffffff", + "display": "standalone" +} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 000000000..f42a666ef --- /dev/null +++ b/sitemap.xml @@ -0,0 +1 @@ +https://www.assemblyscript.org/built-with-assemblyscript.htmldailyhttps://www.assemblyscript.org/concepts.htmldailyhttps://www.assemblyscript.org/compiler.htmldailyhttps://www.assemblyscript.org/editor-test.htmldailyhttps://www.assemblyscript.org/examples/game-of-life.htmldailyhttps://www.assemblyscript.org/examples.htmldailyhttps://www.assemblyscript.org/examples/arrays.htmldailyhttps://www.assemblyscript.org/examples/mandelbrot.htmldailyhttps://www.assemblyscript.org/examples/interference.htmldailyhttps://www.assemblyscript.org/examples/snippets.htmldailyhttps://www.assemblyscript.org/frequently-asked-questions.htmldailyhttps://www.assemblyscript.org/getting-started.htmldailyhttps://www.assemblyscript.org/dailyhttps://www.assemblyscript.org/introduction.htmldailyhttps://www.assemblyscript.org/standards-objections.htmldailyhttps://www.assemblyscript.org/runtime.htmldailyhttps://www.assemblyscript.org/status.htmldailyhttps://www.assemblyscript.org/stdlib/array.htmldailyhttps://www.assemblyscript.org/stdlib/arraybuffer.htmldailyhttps://www.assemblyscript.org/stdlib/console.htmldailyhttps://www.assemblyscript.org/stdlib/dataview.htmldailyhttps://www.assemblyscript.org/stdlib/crypto.htmldailyhttps://www.assemblyscript.org/stdlib/date.htmldailyhttps://www.assemblyscript.org/stdlib/globals.htmldailyhttps://www.assemblyscript.org/stdlib/error.htmldailyhttps://www.assemblyscript.org/stdlib/heap.htmldailyhttps://www.assemblyscript.org/stdlib/map.htmldailyhttps://www.assemblyscript.org/stdlib/math.htmldailyhttps://www.assemblyscript.org/stdlib/process.htmldailyhttps://www.assemblyscript.org/stdlib/number.htmldailyhttps://www.assemblyscript.org/stdlib/set.htmldailyhttps://www.assemblyscript.org/stdlib/staticarray.htmldailyhttps://www.assemblyscript.org/stdlib/symbol.htmldailyhttps://www.assemblyscript.org/stdlib/string.htmldailyhttps://www.assemblyscript.org/stdlib/typedarray.htmldailyhttps://www.assemblyscript.org/types.htmldaily \ No newline at end of file diff --git a/sponsors.svg b/sponsors.svg new file mode 100644 index 000000000..ee1504319 --- /dev/null +++ b/sponsors.svg @@ -0,0 +1,55 @@ + + + + +Gold Sponsors + + + +Silver Sponsors + + +Bronze Sponsors + + + + + + +Individual Backers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/sponsors/battagline.svg b/sponsors/battagline.svg new file mode 100644 index 000000000..8e7c089f5 --- /dev/null +++ b/sponsors/battagline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/sponsors/chainsafeth.svg b/sponsors/chainsafeth.svg new file mode 100644 index 000000000..11bed9e66 --- /dev/null +++ b/sponsors/chainsafeth.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/sponsors/fastly.svg b/sponsors/fastly.svg new file mode 100644 index 000000000..114ba7204 --- /dev/null +++ b/sponsors/fastly.svg @@ -0,0 +1,4 @@ + + + + diff --git a/sponsors/graphprotocol.svg b/sponsors/graphprotocol.svg new file mode 100644 index 000000000..7d376d38d --- /dev/null +++ b/sponsors/graphprotocol.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/sponsors/nearprotocol.svg b/sponsors/nearprotocol.svg new file mode 100644 index 000000000..abfa156e2 --- /dev/null +++ b/sponsors/nearprotocol.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/sponsors/nearprotocol1.svg b/sponsors/nearprotocol1.svg new file mode 100644 index 000000000..c1d9455c2 --- /dev/null +++ b/sponsors/nearprotocol1.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/sponsors/shopify.svg b/sponsors/shopify.svg new file mode 100644 index 000000000..07bb41a92 --- /dev/null +++ b/sponsors/shopify.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/standard-library/array/index.html b/standard-library/array/index.html new file mode 100644 index 000000000..bb37b3e2a --- /dev/null +++ b/standard-library/array/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/arraybuffer/index.html b/standard-library/arraybuffer/index.html new file mode 100644 index 000000000..03106736f --- /dev/null +++ b/standard-library/arraybuffer/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/dataview/index.html b/standard-library/dataview/index.html new file mode 100644 index 000000000..9034d71b8 --- /dev/null +++ b/standard-library/dataview/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/date/index.html b/standard-library/date/index.html new file mode 100644 index 000000000..b3656f5f8 --- /dev/null +++ b/standard-library/date/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/error/index.html b/standard-library/error/index.html new file mode 100644 index 000000000..8e527851d --- /dev/null +++ b/standard-library/error/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/globals/index.html b/standard-library/globals/index.html new file mode 100644 index 000000000..0734b8dd9 --- /dev/null +++ b/standard-library/globals/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/map/index.html b/standard-library/map/index.html new file mode 100644 index 000000000..44836ebac --- /dev/null +++ b/standard-library/map/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/math/index.html b/standard-library/math/index.html new file mode 100644 index 000000000..3eed7f3fe --- /dev/null +++ b/standard-library/math/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/number/index.html b/standard-library/number/index.html new file mode 100644 index 000000000..698a50326 --- /dev/null +++ b/standard-library/number/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/set/index.html b/standard-library/set/index.html new file mode 100644 index 000000000..0a8c9a319 --- /dev/null +++ b/standard-library/set/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/string/index.html b/standard-library/string/index.html new file mode 100644 index 000000000..a0009b14f --- /dev/null +++ b/standard-library/string/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standard-library/typedarray/index.html b/standard-library/typedarray/index.html new file mode 100644 index 000000000..5a14439d5 --- /dev/null +++ b/standard-library/typedarray/index.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/standards-objections.html b/standards-objections.html new file mode 100644 index 000000000..7ba942730 --- /dev/null +++ b/standards-objections.html @@ -0,0 +1,80 @@ + + + + + + Standards objections | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Standards objections

In extraordinary circumstances, when collaboration towards eventual resolution is no longer deemed possible, AssemblyScript may object to individual efforts in context of WebAssembly standardization. This page covers our objections and their relevant context.

# W3C WebAssembly Working and Community Group

After thorough consideration, AssemblyScript considers WASI, derived proposals, the W3C's endorsement of its subgroup and the Bytecode Alliance's practices, that not all of their respective members necessarily are aware and/or approve of, harmful to open standards in general and the WebAssembly specification in particular.

# WASI, 2022-09

WASI (opens new window) is a POSIX-like import namespace for non-Web WebAssembly that provides a set of external functions (opens new window) such as fd_write inspired by a low-level layer exposed in systems programming languages such as C++ and Rust, but not on the Web platform. WASI, which is marketed as (opens new window) a standard (opens new window) in close proximity to an official W3C standardization effort, has little overlap with WebAssembly's scope (opens new window) and high-level goals (opens new window), and is governed by a powerful and largely independent-acting W3C subgroup working towards select custom goals (opens new window). Over time, the WASI subgroup has expanded its scope, devising its own proposals (opens new window) that in part compete with established or currently devised Web standards, nowadays promoting fragmentation in tension with the purpose of standards. As part of the disconnect, we have been exposed to a modus operandi of abuse of power when voicing concerns, where our representatives have been systematically discriminated and their concerns silenced, for example by the WASI chair under a pretense with appended derogatory retrospective (opens new window), with the outcome that concerns expressed remain unaddressed.

All in all, WASI and the WASI group make it almost impossible for other participants to pursue (opens new window) efforts (opens new window) aligned with WebAssembly's goals, many of which solely exist on paper today to the broader community's astonishment, while WASI's concepts and ideas continue to diffuse into everything WebAssembly, progressing a premature ecosystem split that is ironically mediated via the standard itself.

Our assessment of WASI's relation to several of WebAssembly's high-level goals (opens new window) and values is as follows:

Communicated technical goal Assessment
Portable
While it can be polyfilled (opens new window), WASI is not a reasonably portable abstraction for high-level languages / the Web.		 In violation
Support for languages other than C/C++ (and Rust)
Languages that would naturally fit the Web platform not only are overlooked, but WASI's self-imposed abstinence of Web concepts undermines other languages' interoperability potential with JS and the Web platform specifically.		 In violation
Execute within and integrate well with the existing Web platform
WASI does not integrate with the existing Web platform but fundamentally competes with it.		 In violation
Maintain the versionless, feature-tested and backwards-compatible evolution story of the Web
WASI's concepts are not backwards-compatible (opens new window) with Web platform concepts.		 In violation
Execute in the same semantic universe as JavaScript
WASI's semantics fundamentally differ from JavaScript's, effectively establishing an alternative universe.		 In violation
Access browser functionality through the same Web APIs that are accessible to JavaScript
WASI is unconcerned with Web APIs and JavaScript and its group refuses to take their existence into account.		 In violation
Promote other compilers and tools targeting WebAssembly
WASI stifles other compilers and breaks other languages through introduction of inefficiency and incompatibility.		 In violation
Communicated organizational value Assessment
Charter (opens new window)
WASI's adherence to scope, participation, communication and decision policy is generally questionable. Specifically, WASI's deliverables certainly do not "interoperate gracefully with JavaScript and the Web".		 In violation
CEPC (opens new window)
The WASI group systematically abuses the CEPC to "win" losing arguments.		 In violation

Summarized, WASI has little overlap with technical goals and organizational values in Web standards in general and the WebAssembly specification in particular. Its subgroup nourishes a discriminatory and exclusionary environment to its own advantage which lopsidedly reinforces its technical bias. It is our impression that the WASI group deliberately applies said practices in order to strongly disadvantage its competitors (opens new window), willingly taking chances that the overall standardization effort is profoundly damaged.

Concrete technical or related concerns we have voiced that remained unaddressed are:

  • For languages that are a natural fit for the Web platform, WASI leads to a shim in Wasm (opens new window) and, lacking alternatives, a polyfill in JS, with conceptional breakage in between, indicating that it is not the right abstraction to support many programming languages well.
  • WASI mandates concepts uncommon on the Web (for e.g. strings) that are fundamentally incompatible with Java-like languages and JavaScript, indicating that it is not a reasonable abstraction when compatibility with the existing Web platform is the goal. +

    Diagram of cause and effect of WASI's choices.

  • WASI introduces redundancy where functionality available on the Web platform is eagerly implemented differently on top of WASI.
  • Overuse of WASI leads to code bloat in WebAssembly on the Web / in browsers, where code size arguably matters the most.
  • WASI promotes fragmentation by introducing the requirement to recompile modules for different environments.
  • WASI promotes fragmentation through eagerly extending its scope and independently devising competing APIs.

Nonetheless, we are open to consider re-engagement with WASI as a custom effort given that the following conditions are met:

  • Relocation of WASI repositories and venues out of the W3C / WebAssembly organization to +
    • a) clearly indicate its not necessarily aligned non-polyglot, non-Web approach and
    • b) end the detrimental effects of endorsement over all other efforts.
  • Clear communication that WASI is unconcerned with many of WebAssembly's overall goals and the existing Web platform.
  • An acknowledgement of wrongdoing and sincere apology to lessen the suffering of those discriminated, discredited and excluded.
  • The presence of well-intention and honesty and the absence of political finesse when addressing the conditions.

We recommend to the WebAssembly CG to ensure that the first condition is fulfilled in any case as we expect that failure to do so will prolong the endorsement's emergent political properties that run counter to rational and constructive technical discourse.

# Component Model, 2022-09

The same considerations as for WASI apply to its Component Model (opens new window), a proposal to define "portable, virtualizable, statically-analyzable, capability-safe, language-agnostic interfaces, especially those being defined by WASI" for all of WebAssembly, that, even though it does not make the connection obvious, is aptly named the "WASI Component Model" by those in the know 1 (opens new window) 2 (opens new window) 3 (opens new window). The Component Model not only cements WASI's preferences as the standard's foundation, but has almost silently replaced long awaited proposals such as JS+DOM (opens new window), WebIDL bindings (opens new window) and Interface Types (opens new window), even though improvements to Wasm/JS interoperability are commonly considered obvious wins yet surprisingly remain absent from the WebAssembly platform. So far we haven't seen any credible evidence that would support the drift away from bindings to the differently scoped Component Model, and suspect strategical reasons.

Our assessment of the Component Model's relation to several of WebAssembly's high-level goals and values is identical to our assessment on WASI above, whereas the Component Model affects all of WebAssembly while violating important properties such as compatibility and security. Our assessment of the Component Model's relation to several of its own goals (opens new window) is as follows:

Communicated technical goal Assessment
Portable, cross-language composition
Works if all languages involved are Rust-like. Breaks in all other cases, incl. when interfacing with JS / Web APIs.		 In violation
Language neutrality
The Component Model only supports one family of programming languages — the exact bias it claims to avoid.		 In violation
Formal semantics
The Component Model is not defined in the same semantic framework as core Wasm, which is the Web platform.		 In violation
Web platform integration
The Component Model undermines Web platform integration for languages that would otherwise be a natural fit.		 In violation

Concrete technical or related concerns we have voiced that remained unaddressed are:

  • The Component Model unnecessarily restricts its concepts (for e.g. strings), introducing incompatibility and security issues via target-oriented design choices like its "canonical ABI" or a questionable distinction between "external" and "internal" function calls, where the distinction conveniently does not make a difference for WASI's audience yet "external" calls break Web-, JS- and self-interop for any language that would naturally fit the Web platform. Support for affected use cases is not proposed by the Component Model. +

    Diagram of cause and effect of the Component Model's choices.

  • The Component Model proposes Rust/non-Web concepts exclusively, with Java-like/Web platform concepts nowhere to be found.
  • The Component Model's chosen "canonical ABI" needlessly biases WebAssembly against the Web platform in favor of C++ and Rust.
  • The Component Model states the goals of "language neutrality" and "Web platform integration", which it exactly does not honor.
  • Using the Component Model for ESM-integration will break the Web platform on the fundamental level of function calls, say when JavaScript modules, including transparently in dependencies, are upgraded to or otherwise replaced with WebAssembly modules.

Various process discrepancies respectively violations have been observed over the course of the Component Model being established:

  • In May 2020, the champion of the Component Model proposal (Interface Types at the time) acknowledged (opens new window) that Interface Types' preferred choice of semantics does not match Java-like languages, including JavaScript, and that it would be technically trivial to support Java-like respectively Web platform semantics as well. The group signaled support for the resolution. However, in a later rebase commit that didn't indicate a connection, the exact opposite (opens new window) was committed and justified with nonsensical prose:

    While the canonical representation of all the numeric types are obvious, due to their fixed-power-of-2 sizes, char requires the proposal to choose an arbitrary character encoding. To match the core wasm spec's choice of UTF-8 (opens new window), and the more general trend of "UTF-8 Everywhere" (opens new window), this proposal also chooses UTF-8. By choosing a canonical string encoding happy path while providing a graceful fallback to efficient transcoding, Interface Types provides a gentle pressure to eventually converge without performance cliffs in the meantime.

    First, there is a better than an arbitrary choice: Do what the Web platform does. Second, a file format's choice has little to do with the requirements of API calls. Third, "UTF-8 Everywhere" is an opinion piece by people who publicly state that JavaScript, still WebAssembly's primary interop language, is harmful. Fourth, there is no "happy path", no "graceful fallback" and no "efficient transcoding" for Java-like languages and JavaScript interop. Fifth, it is not any proposal's business to provide pressure against the Web platform. Sixth, eventual convergence is impossible due to hard backwards-compatibility constraints. Seventh, surely there will be performance cliffs, even worse incompatibility, not just in the meantime, but forever if the most fundamental building block, the char type, is already artificially restricted. Unicode code points would instead have been a compatible choice.

  • In May 2021, a series of polls was proposed (opens new window) to the CG's meeting agenda to establish the Component Model. The accompanying presentation (opens new window) contained inaccurate "Proposed next steps" to justify a single "canonical ABI" that would inscribe WASI's semantic choices, calling anything else "just an optimization", which is obviously untrue, while sidestepping "hard design questions", which, also given the prior acknowledgement, is a stretch. A clarifying presentation to inform the group about the implications was proposed (opens new window) by AssemblyScript, which was simply rejected to be given before the polls would take place.

  • AssemblyScript nonetheless hurried to publish an issue with the presentation attached (opens new window) the weekend before the polls would take place. Issue and presentation remained unaddressed until the polls had passed. In the discussion before the polls (opens new window), the concerns were mentioned, but the line of thought harshly interrupted mid-sentence by an Interface Types champion so the concern was not adequately discussed. The polls subsequently passed with the WASI lobby voting in favor. The AssemblyScript representative voted "against" as he was advised by a member of the WebAssembly WG to not vote strongly. It was said doing so would be considered bad practice. During the discussion, an Interface Types champion clarified upon request by another member that the poll would not prescribe specific semantics, which later turned out to be untrue, yet likely convinced more people to vote neutral or in favor.

  • In preparation for their presentation, the AssemblyScript representative requested an ongoing invite to the WASI subgroup's meetings, where Interface Types' and later the Component Model's design choices are first presented. He was first not admitted based on vague conduct accusations by the WASI chair, and after politely agreeing to special rules was only admitted to a single meeting and discouraged from speaking up, with the WASI chair stating that the concerns were uninteresting and nobody would address them anyhow. Meanwhile, one day after proposing the Component Model, the WASI subgroup had declared itself an equal part (opens new window) of the standardization process regardless of the many prior process and organizational discrepancies its endorsement had already fueled. Other chairs ignored the recent incident when the AssemblyScript representative asked for help when suspecting foul play. Eventually, the WASI chair suggested publicly that the male individual might have made her uncomfortable on her personal Twitter account (opens new window), a potentially career-ending move, even though there has never been a personal correspondence.

  • After the polls, in June 2021, a Google employee authored two (opens new window) threads (opens new window) in the W3C Technical Architecture Group that would break JavaScript string semantics and thus compatibility with the Web platform by design principle. Only days later, the existence of the threads was used as part of a list of similarly natured arguments (opens new window) to justify breaking with JavaScript/Web platform semantics.

  • In a discussion slot nonetheless requested in a later meeting in June 2021, an Interface Types champion filibustered (opens new window). When time ran out, a CG chair suggested a follow-up meeting. The follow-up meeting was cancelled shortly after, stating "reluctance". The group was not informed, even though requested. An orderly Interface Types subgroup was not established, even though suggested, so both Interface Types and the Component Model remain specified in the largely independent-acting WASI subgroup until today.

  • For an August 2021 meeting, a summary and hard-to-grasp poll (opens new window) were added to the CG meeting agenda by the Component Model champion. AssemblyScript requested (opens new window) to clarify the poll's text by at least referencing the respective WebIDL concepts so more people would understand what is voted for, which was collectively rejected by WG members and chairs. Our renewed concerns and suggestions (opens new window) were cleverly bypassed (opens new window) during the final decision process (see next item).

  • In the August 2021 meeting, the Component Model champion did not present a summary according to their agenda item (opens new window) but one-sided arguments in favor (opens new window), even though it was clarified beforehand (opens new window) that the champion would summarize. The May 2021 poll, that was said to not prescribe specific semantics, was used as an argument to decide for specific semantics. The polls then passed, with the WASI lobby voting in favor. Two members disagreed strongly this time and were ridiculed by the group for voicing frustration at the end of the meeting. Their strong votes made no difference. Other AssemblyScript contributors later voiced that they didn't understand what was being voted for respectively were surprised by the one-sided presentation.

  • In September 2021, the Component Model repository was created, ironically stating the goals (opens new window) of "language neutrality" and "Web platform integration", both of which are exactly not being honored respectively undermined by the Component Model.

  • Also in September 2021, a big picture discussion (opens new window) in context of WASI and in spirit of this objection was closed and locked under a pretense, the latter of which is untypical, by the WASI chair. An unsolicited retrospective was attached, painting the AssemblyScript representative, who cannot respond, in a bad light. The representative later complained to the W3C ombuds (opens new window) about the action. The ombuds didn't respond, instead the chairs disregarded the complaint, the WASI chair edited and doubled-down on their closing comment, and when finally voicing major frustration regarding the series of process violations and discrepancies the AssemblyScript representative was banned from participating in the WebAssembly organization in all forms by the W3C CEO upon request of the WASI chair. A list of foregoing process and conduct violations similar to this one was provided in response, but was disregarded.

As such, we have reason to believe that the events surrounding the Component Model are politically motivated, whereas technical facts have either been misrepresented or ignored, and people been discouraged, discriminated and excluded with the intent to silence them.

Even though we consider the process and conduct violations in context of the Component Model extraordinarily serious and the amount of technical disinformation and bias unacceptable, we are open to a constructive re-engagement with a revised Component Model proposal given that the following conditions are met:

  • Freezing the Component Model proposal until Wasm/JS interoperability has been significantly improved, mitigating risks of premature standardization ahead of the market respectively in dangerous contradiction to WebAssembly's overall goals.
  • A firmly established commitment to consider compatibility with the Open Web Platform critically important (opens new window).
  • An acknowledgement of wrongdoing and actual adherence to Wasm's and the Component Model's communicated goals.
  • The presence of well-intention and honesty and the absence of political finesse when addressing the conditions.

If not possible or refused, we recommend to the WebAssembly CG to delegitimize the Component Model proposal and to not advance it any further, since standardizing it would prematurely bias WebAssembly against the existing Web platform respectively against exactly those programming languages that would fit the Web platform by design, which is, given the power constellation and consequent experience, almost certainly forever, and as such would set a fatal precedent that politically undermining purpose and goals of W3C standardization efforts with questionable practices is a viable and, even worse, legitimate strategy.

# Notes on the W3C

Even though the W3C is undoubtedly aware, its role in context of the events remains unclear to us. Regardless of our bad experience, we obviously agree that a respectable standardization body should responsibly shepherd the WebAssembly standardization effort, and we are open to extend our engagement with the W3C given that the following conditions are met:

  • Relocation of WASI repositories and venues out of the W3C / WebAssembly organization to end the detrimental endorsement.
  • The appointment of reasonably neutral and responsible chairs to re-establish trust into the W3C's processes and values.
  • Removal of members who have abused the CEPC to discriminate and exclude members for voicing their opinion.
  • A firmly established commitment to consider compatibility with the Open Web Platform critically important (opens new window).
  • An acknowledgement of wrongdoing and sincere apology to lessen the suffering of those systematically mistreated.
  • The presence of well-intention and honesty and the absence of political finesse when addressing the conditions.

If not possible or refused, we recommend to the community to investigate whether Ecma would be a more suitable venue. We recognize that there is no such path if the browser vendors have an interest to leave the situation suboptimal at their discretion.

# Notes on the Bytecode Alliance

We are skeptical of a re-engagement with the Bytecode Alliance, a coalition of several tech giants and select collaborators that is (opens new window) "dedicated to creating … new software foundations, building on standards such as … WASI". Its founding members describe (opens new window) the dawn of WebAssembly as an "opportunity to fix what’s broken" (presumably the Web), "build new foundations for native development" (presumably a non-Web), while taking "deliberate, cross-industry action to ensure this happens in the right way" (likely explaining the political properties). Subsequently, from what we've witnessed, it appears to selectively empower respectively weaken players in the WebAssembly space, applies questionable process values (opens new window) such as "disagree and commit" that are, realistically, suitable to break anything, including its own technical values (opens new window), solely by authoritative claim, and, if our experience with its management-level figures taught us anything, operates well beyond the limits of its purported social values (opens new window) of "collaboration", "inclusiveness" and "openness". Given its not strictly necessary but remarkable concentration of power, and that its members' actions in context of a supposedly open and collaborative standardization effort speak a very clear language, we'd like to caution the public to keep an eye on potential anti-competitive practices that would indicate the need for antitrust legislation to step in. We recognize that not all members of the Bytecode Alliance necessarily are aware and/or approve of its surface-level actions, since several of them have engaged with us in good faith, even though the Bytecode Alliance's representatives have not. All in all we believe that WebAssembly, and in turn the Web, would be better off without it, since realistically, the processes and venues to drive its ideas already exist, but now are at risk to be rendered dysfunctional by the deliberateness of its operation.

# Ecosystem considerations

We believe that the WebAssembly standard, its ecosystem, the Web platform, its stakeholders and the public would benefit immensely from compatibility of WebAssembly with the existing Web platform (opens new window) while putting an emphasis on fostering a truly open and collaborative space where everyone can participate without fear of harassment, so ideas can be exchanged, many more programming languages and use cases become viable and the Web's principles and values are adhered to. We see negative value in an arbitrarily neutered technology that was taken over by politics while ignoring technical concerns, well-established facts and broad public interest. No amount of creative marketing and political finesse will make up for the enormous damage a select few's divisive efforts are doing to the WebAssembly technology that amazed us with the promise to bring many programming languages and use cases not only to the Web but their people closer together. Given that use cases that would fit the Web platform are artificially disadvantaged, while hard to pick up programming languages and often metered use cases with diverging concepts are irrationally advantaged, we thus look with sorrow not only towards the future of the Web platform but also towards the various new endeavors in the WebAssembly space, since, in its current politically constrained form that is stripping Wasm of its true potential while simultaneously introducing portability, compatibility and security problems, the market will likely not grow large enough soon enough to support them all. As such we believe that it is in almost everyone's best interest to ensure that purpose, goals and values of open Web standards are honored, which currently is, frankly, not the case — and sadly, the situation is reinforced by many who put almost religious programming language preference, predatory business practices in support of non-Web use cases or the interplay of both over a once so promising vision.

We hope that we managed to express our objections clearly and in sufficient detail. Thank you for your consideration.

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/status.html b/status.html new file mode 100644 index 000000000..822717e48 --- /dev/null +++ b/status.html @@ -0,0 +1,110 @@ + + + + + + Implementation status | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Implementation status

AssemblyScript both aims to be a thin and efficient layer on top of WebAssembly, as well as a language with familiar syntax for developers coming from TypeScript. These two goals are sometimes in conflict, since not all features are equally viable to implement on top of WebAssembly's capabilities right now, respectively applicable in general in ahead-of-time compilation. As such the focus is to implement what's feasible first, and where possible to delay features that are better served by one of the future WebAssembly proposals to avoid otherwise duplicate work. In a sense, the approach is similar to the MVP model used in WebAssembly specification. Some features are critical to make AssemblyScript work right now of course, so there are some exceptions to this rule.

# WebAssembly features

Some language features rely on future WebAssembly functionality (opens new window) to become viable. The following table aims to give an overview from a WebAssembly perspective:

WebAssembly spec Engines AssemblyScript (flag) Perspective
✔️ Finished proposal
Import/export of mutable globals (opens new window) ⁞ ✔️ good Interop
JS BigInt integration (opens new window)1 ✔️ good Interop
Sign-extension operations (opens new window) ⁞ ✔️ good Efficiency
Non-trapping float-to-int conversions (opens new window) ⁞ ✔️ good Efficiency
Bulk memory operations (opens new window) ⁞ ✔️ good Efficiency
Fixed-width SIMD (opens new window) ⁞ 🏁 simd good Feature
Reference types (opens new window) ⁞ 🔨 reference-types good Interop
Multi-value (opens new window) ⁞ good Feature
🏁 Standardize the feature
Extended constant expressions (opens new window) 🔨 good Efficiency
Tail call (opens new window) good Efficiency
🔨 Implementation phase
Relaxed SIMD (opens new window) 🏁 relaxed-simd good Feature
Exception handling (opens new window) 🔨 exception-handling good Feature
Typed function references (opens new window) 🔨 gc good Feature
Garbage collection (opens new window) 🔨 gc good Efficiency / Interop
Multiple memories (opens new window) 🔨 good Feature
Branch hinting (opens new window) good Efficiency
JS Promise integration (opens new window) uncertain
Threads (opens new window) 🔨 threads uncertain
Memory64 (opens new window) 🔨 uncertain
📖 Spec text available
ECMAScript module integration (opens new window) good Interop
Instrument and tracing (opens new window) good Debugging
💡 Feature proposal
Reference-typed strings (opens new window) 🔨 stringref good Interop
Extended name section (opens new window) 🔨 good Debugging
JS customization for GC (opens new window) good Interop
Type imports (opens new window) good Interop
Flexible vectors (opens new window) good Feature
Constant time (opens new window) good Security
Stack switching (opens new window) uncertain
Call tags (opens new window) uncertain
Memory control (opens new window) uncertain
Profiles (opens new window) uncertain
Component model (opens new window)2 harmful
❔ Quasi proposal
WASI (opens new window)2 ⁞ harmful

Web:   + Chrome Firefox Safari Node.js   ⁞   +Non-Web:   + Wasmer Wasmtime

1 Supported otherwise by Non-Web hosts.   2 See our detailed standards objections.

Perspective Description
good This specification is conceptually good and worth looking into
uncertain AssemblyScript is uncertain about this specification and not in a hurry to implement it
harmful AssemblyScript considers this specification to be harmful in its current state

# Language features

As such, certain higher-level language features still have their limitations or are not yet available. From a language perspective:

Feature What to expect?
🐤 Functional
Bootstrap The compiler can compile itself to WebAssembly, passing the test suite. Note that the compiler is not technically "self hosted" in WebAssembly yet, as it currently uses a JavaScript frontend for I/O and links to Binaryen (C++ compiled with Emscripten), which again requires some amount of JS glue code.
OOP Largely implemented in linear memory. Access modifiers like private and protected are not currently enforced. There is rudimentary support for interfaces.
Standard library Largely implemented in linear memory. Some APIs function a little different than in JavaScript due to differences introduced by static typing or not yet available future features. There is a separate status document (opens new window) specific to the standard library.
Generics Generics are compiled as monomorphized templates for now and can be specialized with static type checks. Constraining extends XY clauses are not yet enforced.
Garbage collection Implemented in linear memory for the time being, independent of the host GC.
Host integration Enabled by generated host bindings, respectively the runtime interface for integration into non-Web environments.
🐣 Limited
Union types Union types are not supported yet, except for nullable class types. There is no any type. A viable alternative is to use generics specialized with static type checks to achieve a similar effect.
Symbols Symbols are implemented in the standard library, but don't have deep compiler integration yet.
Object literals Object literals can be used in places where the current type is a bare class, then corresponding to an instantiation of the class.
JSON JSON is not strictly typed in nature, so we haven't settled on a standard yet. Solutions developed by the community: assemblyscript-json (opens new window)
RegExp Regular expressions need quite a lot of supporting code with many quirks, and we haven't decided on an implementation yet. Solutions developed by the community: assemblyscript-regex (opens new window)
Date There is initial support for the UTC parts, but WebAssembly lacks access to the system's time zone data. In general the Temporal proposal could be more feasible to adopt. Solutions developed by the community: assemblyscript-temporal (opens new window).
🥚 Not implemented
Closures Captures of local variables are not yet supported and would be best implemented on top of future WebAssembly features, also to avoid inventing a custom ABI. Can be worked around by using a global variable instead (does not need to be captured), or passing an argument with the relevant values.
Iterators Iterators and for..of loops are not supported yet. APIs that would return an iterator return an array of keys or values for now instead.
Rest parameters Rest parameters are not supported yet. Would benefit from a WebAssembly proposal to avoid a custom ABI, but there is none yet. Optional parameters with a default value are supported and can often be used as an alterantive.
Exceptions Exceptions require support from the WebAssembly engine first. Throwing currently aborts the program.
Promises There is no concept of async/await yet due to the lack of an event loop. Future WebAssembly proposals might help with the stack switching parts (pause and resume execution).
BigInt Instead of BigInts, AssemblyScript has opted to utilize WebAssembly's 64-bit integers. It is currently unclear how both concepts could mix.
🕳️ Not supported
Dynamicness AssemblyScript avoids overly dynamic JavaScript features by design and focuses on static compilation.

# On closures

Closures (functions with a captured environment) are not yet supported and we are waiting for the Function References 🦄 and Garbage collection 🦄 (captured environments are GC'ed) proposals to land. However, since this is a crucial language feature, we may end up with a filler implementation using linear memory. Not available yet, though.

In the meantime we recommend to restructure code so closures are not necessary, i.e. instead of writing

function computeSum(arr: i32[]): i32 {
+  var sum = 0
+  arr.forEach(value => {
+    sum += value // fails
+  })
+  return sum
+}
+

restructure to

var sum: i32 // becomes a WebAssembly Global
+function computeSum(arr: i32[]): i32 {
+  sum = 0
+  arr.forEach(value => {
+    sum += value // works
+  })
+  return sum
+}
+

or to

function computeSum(arr: i32[]): i32 {
+  var sum = 0
+  for (let i = 0, k = arr.length; i < k; ++i) {
+    sum += arr[i] // works
+  }
+  return sum
+}
+

# On dynamicness

AssemblyScript intentionally avoids very dynamic JavaScript features that cannot be compiled efficiently, like for example:

  • Assigning any value to any variable.
  • Compare values of incompatible types.
  • Implicitly convert from a non-string to a string without using x.toString().
  • Assign a new property, that has not been statically declared, to a class or object.
  • Assign a class to a variable (e.g. var clazz = MyClass) since classes are static constructs without a runtime representation.
  • Patch class .prototypes since there are none.
  • Access arguments to dynamically obtain function arguments.
  • Dynamically obtain the name of a function at runtime or otherwise use reflection.

Some of these restrictions, like implicit conversion to strings when concatenating with a string, may be lifted in the future, while others, like prototypes, may never be viable in ahead-of-time compilation. For instance, some features would work in an interpreter and may become efficient with a JIT compiler, yet going down that rabbit hole runs counter to WebAssembly's, and by definition AssemblyScript's, goals.

# Tooling features

Feature What to expect?
🐤 Functional
Debugging There is support for debug information and source maps. See also.
Testing Unopinionated with simple assertions. Solutions developed by the community: as-pect (opens new window)
🐣 Limited
Linting AssemblyScript re-uses TypeScript tooling with a // @ts-ignore here or there but would benefit from a dedicated language server eventually. Solutions developed by the community: asls (opens new window)

+ ← + + Using the runtime + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/array.html b/stdlib/array.html new file mode 100644 index 000000000..f2181fa92 --- /dev/null +++ b/stdlib/array.html @@ -0,0 +1,126 @@ + + + + + + Array | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Array

A randomly accessible sequence of values of a generic type.

The Array API is very similar to JavaScript's (MDN (opens new window)), with the notable difference that one must make sure that there are no null values if T is a non-nullable reference type. Example:

var arr = new Array<string>(10)
+// arr[0]; // would error 😢
+for (let i = 0; i < arr.length; ++i) {
+  arr[i] = ""
+}
+arr[0]; // now it works 😊
+

# Constructor

  • new Array<T>(capacity?: i32)
+
    Constructs a new array.

# Static members

  • function isArray<U>(value: U): bool
+
    Tests if a value is an array.

# Instance members

# Fields

  • var length: i32
+
    The length of this array. Setting the length to a value larger than internal capacity will automatically grow the array.

# Methods

  • function concat(other: Array<T>): Array<T>
+

    Concatenates the values of this and the other array to a new array, in this order.

  • function copyWithin(target: i32, start: i32, end?: i32): this
+

    Copies a region of an array's values over the respective values starting at the target location.

  • function every(fn: (value: T, index: i32, self: Array<T>) => bool): bool
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns false. Returns true if all functions returned true or the array is empty, otherwise false.

  • function fill(value: T, start?: i32, end?: i32): this
+

    Replaces the values of the array from start inclusive to end exclusive in place with the specified value, returning the array.

  • function filter(fn: (value: T, index: i32, self: Array<T>) => bool): Array<T>
+

    Calls the specified function with every value of the array, returning a new array with all values for which the function returned true.

  • function findIndex(fn: (value: T, index: i32, self: Array<T>) => bool): i32
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

  • function findLastIndex(fn: (value: T, index: i32, self: Array<T>) => bool): i32;
+

    Calls the specified function with every value of the array starting at the end until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

  • function flat(): valueof<T>[]
+

    Flattens an array of arrays to a one-dimensional array. null entries are ignored.

  • function forEach(fn: (value: T, index: i32, self: Array<T>) => void): void
+

    Calls the specified function with every value of the array.

  • function includes(value: T, fromIndex?: i32): bool
+

    Tests if the array includes the specified value, optionally providing a starting index.

  • function indexOf(value: T, fromIndex?: i32): i32
+

    Gets the first index where the specified value can be found in the array. Returns -1 if not found.

  • function join(separator?: string): string
+

    Concatenates all values of the array to a string, separated by the specified separator (default: ,).

  • function lastIndexOf(value: T, fromIndex?: i32): i32
+

    Gets the last index where the specified value can be found in the array. Returns -1 if not found.

  • function map<U>(fn: (value: T, index: i32, self: Array<T>) => U): Array<U>
+

    Calls the specified function with every value of the array, returning a new array of the function's return values.

  • function pop(): T
+

    Removes and returns the last value of the array. Modifies Array#length. Throws a RangeError if the array is empty.

  • function push(value: T): i32
+

    Adds one more value to the end of the array and returns the Array's new length. Modifies Array#length.

  • function reduce<U>(
+  fn: (accumValue: U, currentValue: T, index: i32, self: Array<T>) => U,
+  initialValue: U
+): U
+

    Calls the specified reducer function with each value of the array, resulting in a single return value. The respective previous reducer function's return value is remembered in accumValue, starting with initialValue, becoming the final return value in the process.

  • function reduceRight<U>(
+  fn: (accumValue: U, currentValue: T, index: i32, self: Array<T>) => U,
+  initialValue: U
+): U
+

    Calls the specified reducer function with each value of the array, from right to left, resulting in a single return value. See Array#reduce for the reducer function's signature.

  • function reverse(): this
+

    Reverses an array's values in place, modifying the array before returning it.

  • function shift(): T
+

    Removes and returns the first value of the array. Modifies Array#length.

  • function slice(start?: i32, end?: i32): Array<T>
+

    Returns a shallow copy of the array's values from begin inclusive to end exclusive, as a new array. If omitted, end defaults to the end of the array.

  • function some(fn: (value: T, index: i32, self: Array<T>) => bool): bool
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning true. Returns false otherwise or if the array is empty.

  • function sort(fn?: (a: T, b: T) => i32): this
+

    Sorts the values of the array in place, using the specified comparator function, modifying the array before returning it. The comparator returning a negative value means a < b, a positive value means a > b and 0 means that both are equal. Unlike in JavaScript, where an implicit conversion to strings is performed, the comparator defaults to compare two values of type T.

  • function splice(start: i32, deleteCount?: i32): Array<T>
+

    Removes deleteCount (defaults to all remaining) values from the array, starting at index start, modifying the array in place, returning the removed values.

  • function toString(): string
+

    Returns the result of Array#join().

  • function unshift(value: T): i32
+

    Adds one more value to the start of the array and returns the Array's new length. Modifies Array#length.

+ ← + + ArrayBuffer + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/arraybuffer.html b/stdlib/arraybuffer.html new file mode 100644 index 000000000..1f4c8dedb --- /dev/null +++ b/stdlib/arraybuffer.html @@ -0,0 +1,90 @@ + + + + + + ArrayBuffer | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# ArrayBuffer

A fixed-length raw binary buffer.

The ArrayBuffer API is exactly as in JavaScript (MDN (opens new window)).

# Constructor

  • new ArrayBuffer(length: i32)
+
    Constructs a new buffer of the given length in bytes.

# Static members

  • function isView<T>(value: T): bool
+
    Returns true if value is one of the buffer views, such as one of the typed arrays or a DataView.

# Instance members

# Fields

  • readonly byteLength: i32
+
    The buffer's length, in bytes.

# Methods

  • function slice(begin?: i32, end?: i32): ArrayBuffer
+

    Returns a copy of this buffer from begin, inclusive, up to end, exclusive.

  • function toString(): string
+

    Returns a string representation of this buffer.

+ ← + + console + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/console.html b/stdlib/console.html new file mode 100644 index 000000000..c3896b087 --- /dev/null +++ b/stdlib/console.html @@ -0,0 +1,94 @@ + + + + + + console | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# console

An implementation of the console global.

# Static members

  • function assert<T>(assertion: T, message?: string): void
+

    Logs message to console if assertion is false-ish.

  • function log(message?: string): void
+

    Outputs message to the console.

  • function debug(message?: string): void
+function info(message?: string): void
+function warn(message?: string): void
+function error(message?: string): void
+

    Outputs message to the console, prefixed with "Debug:", "Info:", "Warning:" or "Error:" respectively.

  • function time(label?: string): void
+

    Starts a new timer using the specified label.

  • function timeLog(label?: string): void
+

    Logs the current value of a timer previously started with console.time.

  • function timeEnd(label?: string): void
+

    Logs the current value of a timer previously started with console.time and discards the timer.

+ ← + + crypto + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/crypto.html b/stdlib/crypto.html new file mode 100644 index 000000000..25ae8584f --- /dev/null +++ b/stdlib/crypto.html @@ -0,0 +1,86 @@ + + + + + + crypto | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# crypto

An implementation of the crypto global.

# Static members

  • function getRandomValues(array: Uint8Array): void
+
    Fills array with cryptographically strong random values.

+ ← + + DataView + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/dataview.html b/stdlib/dataview.html new file mode 100644 index 000000000..e06fe4ee2 --- /dev/null +++ b/stdlib/dataview.html @@ -0,0 +1,110 @@ + + + + + + DataView | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# DataView

An interface for working with a raw binary buffer.

The DataView API is exactly as in JavaScript (MDN (opens new window)).

# Constructor

  • new DataView(buffer: ArrayBuffer, byteOffset?: i32, byteLength?: i32)
+
    Constructs a new DataView on the specified buffer and region.

# Instance members

# Fields

  • readonly buffer: ArrayBuffer
+

    The backing buffer.

  • readonly byteLength: i32
+

    The length of this view from the start of its buffer.

  • readonly byteOffset: i32
+

    The offset of this view from the start of its buffer.

# Methods

  • function getFloat32(byteOffset: i32, littleEndian?: bool): f32
+

    Gets the 32-bit float value at the specified offset from the start of the view.

  • function getFloat64(byteOffset: i32, littleEndian?: bool): f64
+

    Gets the 64-bit float value at the specified offset from the start of the view.

  • function getInt8(byteOffset: i32): i8
+

    Gets the signed 8-bit integer value at the specified offset from the start of the view.

  • function getInt16(byteOffset: i32, littleEndian?: bool): i16
+

    Gets the signed 16-bit integer value at the specified offset from the start of the view.

  • function getInt32(byteOffset: i32, littleEndian?: bool): i32
+

    Gets the signed 32-bit integer value at the specified offset from the start of the view.

  • function getInt64(byteOffset: i32, littleEndian?: bool): i64
+

    Gets the signed 64-bit integer value at the specified offset from the start of the view.

  • function getUint8(byteOffset: i32, littleEndian?: bool): u8
+

    Gets the unsigned 8-bit integer value at the specified offset from the start of the view.

  • function getUint16(byteOffset: i32, littleEndian?: bool): u16
+

    Gets the unsigned 16-bit integer value at the specified offset from the start of the view.

  • function getUint32(byteOffset: i32, littleEndian?: bool): u32
+

    Gets the unsigned 32-bit integer value at the specified offset from the start of the view.

  • function getUint64(byteOffset: i32, littleEndian?: bool): u64
+

    Gets the unsigned 64-bit integer value at the specified offset from the start of the view.

  • function setFloat32(byteOffset: i32, value: f32, littleEndian?: bool): void
+

    Sets the 32-bit float value at the specified offset from the start of the view.

  • function setFloat64(byteOffset: i32, value: f64, littleEndian?: bool): void
+

    Sets the 64-bit float value at the specified offset from the start of the view.

  • function setInt8(byteOffset: i32, value: i8): void
+

    Sets the signed 8-bit integer value at the specified offset from the start of the view.

  • function setInt16(byteOffset: i32, value: i16, littleEndian?: bool): void
+

    Sets the signed 16-bit integer value at the specified offset from the start of the view.

  • function setInt32(byteOffset: i32, value: i32, littleEndian?: bool): void
+

    Sets the signed 32-bit integer value at the specified offset from the start of the view.

  • function setInt64(byteOffset: i32, value: i64, littleEndian?: bool): void
+

    Sets the signed 64-bit integer value at the specified offset from the start of the view.

  • function setUint8(byteOffset: i32, value: u8, littleEndian?: bool): void
+

    Sets the unsigned 8-bit integer value at the specified offset from the start of the view.

  • function setUint16(byteOffset: i32, value: u16, littleEndian?: bool): void
+

    Sets the unsigned 16-bit integer value at the specified offset from the start of the view.

  • function setUint32(byteOffset: i32, value: u32, littleEndian?: bool): void
+

    Sets the unsigned 32-bit integer value at the specified offset from the start of the view.

  • function setUint64(byteOffset: i32, value: u64, littleEndian?: bool): void
+

    Sets the unsigned 64-bit integer value at the specified offset from the start of the view.

  • function toString(): string
+

    Returns a string representation of this object.

Endianness defaults to littleEndian = false.

+ ← + + Date + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/date.html b/stdlib/date.html new file mode 100644 index 000000000..1ec7b006e --- /dev/null +++ b/stdlib/date.html @@ -0,0 +1,120 @@ + + + + + + Date | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Date

Represents timestamps.

The Date API is still preliminary with only a subset of properties and methods implemented. Note that getting the current date, via Date.now, requires importing the Date object from the host (as Date).

WARNING

Date does not currently support timezones other than UTC. Therefore, methods such as toString and toTimeString can only be partially implemented.

# Constructor

  • new Date(value: i64)
+
    Constructs a new date object from an UTC timestamp in milliseconds.

# Static members

  • function now(): i64
+

    Returns the current UTC timestamp in milliseconds. To use this function you must import the Date object from the host (as Date).

  • function UTC(
+  year: i32,
+  month?: i32,
+  day?: i32,
+  hour?: i32,
+  minute?: i32,
+  second?: i32,
+  millisecond?: i64
+): i64
+

    Returns the UTC timestamp in milliseconds of the specified date.

  • function parse(dateString: string): Date
+

    Parses a Date object from a string (ISO 8601 format only).

  • function fromString(dateTimeString: string): Date
+

    Creates a Date object from an ISO 8601 formatted string.

# Instance members

  • function getTime(): i64
+

    Gets the UTC timestamp of this date in milliseconds.

  • function setTime(value: i64): i64
+

    Sets the UTC timestamp of this date in milliseconds and returns the timestamp.

  • function getUTCFullYear(): i32
+

    Gets the full year according to universal time.

  • function setUTCFullYear(value: i32): i32
+

    Sets the full year according to universal time.

  • function getUTCMonth(): i32
+

    Gets the (zero indexed) month according to universal time.

  • function setUTCMonth(value: i32): i32
+

    Sets the (zero indexed) month according to universal time.

  • function getUTCDate(): i32
+

    Gets the day of the month according to universal time.

  • function setUTCDate(value: i32): i32
+

    Sets the day of the month according to universal time.

  • function getUTCDay(): i32
+

    Gets the day of the week in the specified date according to universal time, where 0 represents Sunday.

  • function getUTCHours(): i32
+

    Gets the hour according to universal time.

  • function setUTCHours(value: i32): i32
+

    Sets the hour according to universal time.

  • function getUTCMinutes(): i32
+

    Gets the minute according to universal time.

  • function setUTCMinutes(value: i32): i32
+

    Sets the minute according to universal time.

  • function getUTCSeconds(): i32
+

    Gets the second according to universal time.

  • function setUTCSeconds(value: i32): i32
+

    Sets the second according to universal time.

  • function getUTCMilliseconds(): i32
+

    Gets the millisecond according to universal time.

  • function setUTCMilliseconds(value: i32): i32
+

    Sets the millisecond according to universal time.

  • function toISOString(): string
+

    Returns the a string in simplified extended ISO 8601 format.

  • function toUTCString(): string
+

    Returns the a string in RFC-1123 format and the UTC time zone.

  • function toDateString(): string
+

    Returns the a date string in human readable form in English WWW MMM DD YYYY format.

  • function toTimeString(): string
+

    Returns the a time string in HH:MM:SS format.

WARNING

At the moment toTimeString doesn't output time zone and doesn't use local time zone offset!

  • function toString(): string
+
    Returns the a time string in human readable form in English WWW MMM DD YYYY HH:MM:SS format.

WARNING

At the moment toString doesn't output time zone and doesn't use local time zone offset!

+ ← + + Error + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/error.html b/stdlib/error.html new file mode 100644 index 000000000..aaea24217 --- /dev/null +++ b/stdlib/error.html @@ -0,0 +1,90 @@ + + + + + + Error | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Error

Represents a runtime error.

The Error API is very similar to JavaScript's (MDN (opens new window)), with some properties not being implemented yet.

# Variants

Variant Description
Error Represents a general error.
RangeError Represents an error where a value is not in the range of allowed values.
TypeError Represents an error where a value is not of the expected type.
SyntaxError Represents an error where the syntax of the input in invalid.

The Errorclass can also be sub-classed by forwarding message and setting the name property in the overloaded constructor.

# Constructor

  • new Error(message?: string)
+
    Constructs a new error object.

# Instance members

# Fields

  • var message: string
+

    The message of this error.

  • var name: string
+

    The name of this error. In case of Error, this is "Error".

  • var stack: string
+

    The stack trace of this error. Not supported yet, hence an empty string.

# Methods

  • function toString(): string
+
    Returns a string representation of this error in the form name: message.

+ ← + + heap + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/globals.html b/stdlib/globals.html new file mode 100644 index 000000000..d563700f2 --- /dev/null +++ b/stdlib/globals.html @@ -0,0 +1,255 @@ + + + + + + Globals | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Globals

The following global constants and functions are present alongside the standard library's classes.

# Constants

  • const NaN: auto // f32 or f64
+

    Not a number as a 32-bit or 64-bit float depending on context. Compiles to a constant.

  • const Infinity: auto // f32 or f64
+

    Positive infinity as a 32-bit or 64-bit float depending on context. Compiles to a constant.

# Functions

  • function isNaN<T>(value: T): bool
+

    Tests if a 32-bit or 64-bit float is NaN.

  • function isFinite<T>(value: T): bool
+

    Tests if a 32-bit or 64-bit float is finite, that is not NaN or +/-Infinity.

  • function parseInt(str: string, radix?: i32): f64
+

    Parses a string representing an integer to an f64 number Returns NaN on invalid inputs.

    Type-specific variants of parseInt are available separately:

    • F32.parseInt to parse to a 32-bit float.
    • I8.parseInt to parse to a signed 8-bit integer, respectively U8.parseInt if unsigned.
    • I16.parseInt to parse to a signed 16-bit integer, respectively U16.parseInt if unsigned.
    • I32.parseInt to parse to a signed 32-bit integer, respectively U32.parseInt if unsigned.
    • I64.parseInt to parse to a signed 64-bit integer, respectively U64.parseInt if unsigned.
  • function parseFloat(str: string): f64
+

    Parses a string to a 64-bit float. Returns NaN on invalid inputs.

# Builtins

The following builtins provide direct access to WebAssembly and compiler features. They form the low-level foundation of the standard library, while also being available for everyone to utilize where directly tapping into WebAssembly or the compiler is desired.

# Static type checks

By making use of the following special type checks, especially in generic contexts, untaken branches can be eliminated statically, leading to concrete WebAssembly functions that handle one type specificially.

  • function isInteger<T>(value?: T): bool
+

    Tests if the specified type or expression is of an integer type and not a reference. Compiles to a constant.

  • function isSigned<T>(value?: T): bool
+

    Tests if the specified type or expression can represent negative numbers. Compiles to a constant.

  • function isFloat<T>(value?: T): bool
+

    Tests if the specified type or expression is of a float type. Compiles to a constant.

  • function isVector<T>(value?: T): bool
+

    Tests if the specified type or expression is of a SIMD vector type. Compiles to a constant.

  • function isReference<T>(value?: T): bool
+

    Tests if the specified type or expression is of a reference type. Compiles to a constant.

  • function isString<T>(value?: T): bool
+

    Tests if the specified type or expression can be used as a string. Compiles to a constant.

  • function isArray<T>(value?: T): bool
+

    Tests if the specified type or expression can be used as an array. Compiles to a constant.

  • function isFunction<T>(value?: T): bool
+

    Tests if the specified type or expression is of a function type. Compiles to a constant.

  • function isNullable<T>(value?: T): bool
+

    Tests if the specified type or expression is of a nullable reference type. Compiles to a constant.

  • function isDefined(expression: auto): bool
+

    Tests if the specified expression resolves to a defined element. Compiles to a constant.

  • function isConstant(expression: auto): bool
+

    Tests if the specified expression evaluates to a constant value. Compiles to a constant.

  • function isManaged<T>(expression: auto): bool
+

    Tests if the specified type or expression is of a managed type. Compiles to a constant. Usually only relevant when implementing custom collection-like classes.

# Example of static type checking

function add<T>(a: T, b: T): T {
+  return a + b // addition if numeric, string concatenation if a string
+}
+
+function add<T>(a: T, b: T): T {
+  if (isString<T>()) { // eliminated if T is not a string
+    return parseInt(a) + parseInt(b)
+  } else { // eliminated if T is a string
+    return a + b
+  }
+}
+

TIP

If you are not going to use low-level WebAssembly in the foreseeable future, feel free to come back to the following paragraphs at a later time.

# Utilities

  • function bswap<T>(value: T): T
+

    Reverses the byte order of the specified integer.

  • function sizeof<T>(): usize
+

    Determines the byte size of the respective basic type. Means: If T is a class type, the size of usize, the pointer type, is returned. To obtain the size of a class in memory, use offsetof<T>() instead. Compiles to a constant.

  • function offsetof<T>(fieldName?: string): usize
+

    Determines the offset of the specified field within the given class type. If fieldName is omitted, this returns what could be interpreted as either the size of the class, or the offset where the next field would be located, before alignment. Compiles to a constant. The fieldName argument must be a compile-time constant string because there is no information about field names anymore at runtime. Therefore, the field's name must be known at the time the returned constant is computed.

  • function alignof<T>(): usize
+

    Determines the alignment (log2) of the specified underlying basic type; i.e. If T is a class type, the alignment of usize is returned. Compiles to a constant.

  • function assert<T>(isTrueish: T, message?: string): T
+

    Traps if the specified value is not true-ish, otherwise returns the non-nullable value. Like assertions in C, aborting the entire program if the expectation fails. Where desired, the --noAssert compiler option can be used to disable assertions in production.

  • function trace(message: string, n?: i32, a0?: f64, a1?: f64, a2?: f64, a3?: f64, a4?: f64): void
+

    Simple trace function which prints message and 5 optional f64 arguments to a console. n is count of used arguments.

    # Usage examples

    trace("foo");
+trace("one arg:", 1, 5.0);
+trace("three args:", 3, 1.0, <f64>2, 3);
+
  • function instantiate<T>(...args: auto[]): T
+

    Instantiates a new instance of T using the specified constructor arguments.

  • function changetype<T>(value: auto): T
+

    Changes the type of a value to another one. Useful for casting class instances to their pointer values and vice-versa.

  • function idof<T>(): u32
+

    Obtains the computed unique id of a class type. Usually only relevant when allocating objects or dealing with RTTI externally.

  • function nameof<T>(value?: T): string
+

    Returns the name of a given type.

# WebAssembly

# Math

The following generic built-ins compile to WebAssembly instructions directly.

  • function clz<T>(value: T): T
+
    Performs the sign-agnostic count leading zero bits operation on a 32-bit or 64-bit integer. All zero bits are considered leading if the value is zero.
    T Instruction
    i8, u8, i16, u16, i32, u32, bool i32.clz
    i64, u64 i64.clz
  • function ctz<T>(value: T): T
+
    Performs the sign-agnostic count trailing zero bits operation on a 32-bit or 64-bit integer. All zero bits are considered trailing if the value is zero.
    T Instruction
    i8, u8, i16, u16, i32, u32, bool i32.ctz
    i64, u64 i64.ctz
  • function popcnt<T>(value: T): T
+
    Performs the sign-agnostic count number of one bits operation on a 32-bit or 64-bit integer.
    T Instruction
    i8, u8, i16, u16, i32, u32 i32.popcnt
    i64, u64 i64.popcnt
    bool none
  • function rotl<T>(value: T, shift: T): T
+
    Performs the sign-agnostic rotate left operation on a 32-bit or 64-bit integer.
    T Instruction
    i32, u32 i32.rotl
    i64, u64 i64.rotl
    i8, u8, i16, u16 emulated
    bool none
  • function rotr<T>(value: T, shift: T): T
+
    Performs the sign-agnostic rotate right operation on a 32-bit or 64-bit integer.
    T Instruction
    i32, u32 i32.rotr
    i64, u64 i64.rotr
    i8, u8, i16, u16 emulated
    bool none
  • function abs<T>(value: T): T
+
    Computes the absolute value of an integer or float.
    T Instruction
    f32 f32.abs
    f64 f64.abs
    i8, i16, i32, i64 emulated
    u8, u16, u32, u64, bool none
  • function max<T>(left: T, right: T): T
+
    Determines the maximum of two integers or floats. If either operand is NaN, returns NaN.
    T Instruction
    f32 f32.max
    f64 f64.max
    i8, u8, i16, u16, i32, u32, i64, u64, bool emulated
  • function min<T>(left: T, right: T): T
+
    Determines the minimum of two integers or floats. If either operand is NaN, returns NaN.
    T Instruction
    f32 f32.min
    f64 f64.min
    i8, u8, i16, u16, i32, u32, i64, u64, bool emulated
  • function ceil<T>(value: T): T
+
    Performs the ceiling operation on a 32-bit or 64-bit float.
    T Instruction
    f32 f32.ceil
    f64 f64.ceil
    i8, u8, i16, u16, i32, u32, i64, u64, bool none
  • function floor<T>(value: T): T
+
    Performs the floor operation on a 32-bit or 64-bit float.
    T Instruction
    f32 f32.floor
    f64 f64.floor
    i8, u8, i16, u16, i32, u32, i64, u64, bool none
  • function copysign<T>(x: T , y: T): T
+
    Composes a 32-bit or 64-bit float from the magnitude of x and the sign of y.
    T Instruction
    f32 f32.copysign
    f64 f64.copysign
  • function nearest<T>(value: T): T
+
    Rounds to the nearest integer half to even of a 32-bit or 64-bit float.
    T Instruction
    f32 f32.nearest
    f64 f64.nearest
    i8, u8, i16, u16, i32, u32, i64, u64, bool none
  • function reinterpret<TTo>(value: auto): TTo
+
    Reinterprets the bits of the specified value as type T.
    TTo Instruction
    i32, u32 i32.reinterpret_f32
    i64, u64 i64.reinterpret_f64
    f32 f32.reinterpret_i32
    f64 f64.reinterpret_i64
  • function sqrt<T>(value: T): T
+
    Calculates the square root of a 32-bit or 64-bit float.
    T Instruction
    f32 f32.sqrt
    f64 f64.sqrt
  • function trunc<T>(value: T): T
+
    Rounds to the nearest integer towards zero of a 32-bit or 64-bit float.
    T Instruction
    f32 f32.trunc
    f64 f64.trunc
    i8, u8, i16, u16, i32, u32, i64, u64, bool none

# Memory

Similarly, the following built-ins emit WebAssembly instructions accessing or otherwise modifying memory.

NOTE

The immOffset and immAlign arguments, if provided, must be compile time constant values. See more details in rationale (opens new window).

  • function load<T>(ptr: usize, immOffset?: usize, immAlign?: usize): T
+
    Loads a value of the specified type from memory. Equivalent to dereferencing a pointer in other languages.
    T Instruction If contextual type is i64
    i8 i32.load8_s i64.load8_s
    u8 i32.load8_u i64.load8_u
    i16 i32.load16_s i64.load16_s
    u16 i32.load16_u i64.load16_u
    i32 i32.load i64.load32_s
    u32 i32.load i64.load32_u
    i64, u64 i64.load n/a
    f32 f32.load n/a
    f64 f64.load n/a
    <ref> i32/i64.load n/a
  • function store<T>(ptr: usize, value: auto, immOffset?: usize, immAlign?: usize): void
+
    Stores a value of the specified type to memory. Equivalent to dereferencing a pointer in other languages and assigning a value.
    T Instruction If value is i64
    i8, u8 i32.store8 i64.store8
    i16, u16 i32.store16 i64.store16
    i32, u32 i32.store i64.store32
    i64, u64 i64.store n/a
    f32 f32.store n/a
    f64 f64.store n/a
    <ref> i32/i64.store n/a
  • function memory.size(): i32
+

    Returns the current size of the memory in units of pages. One page is 64kb.

  • function memory.grow(value: i32): i32
+

    Grows linear memory by a given unsigned delta of pages. One page is 64kb. Returns the previous size of the memory in units of pages or -1 on failure.

    WARNING

    Calling memory.grow where a memory manager is present might break it.

  • function memory.copy(dst: usize, src: usize, n: usize): void
+

    Copies n bytes from src to dst . Regions may overlap. Emits the respective instruction if bulk-memory is enabled, otherwise ships a polyfill.

  • function memory.fill(dst: usize, value: u8, n: usize): void
+

    Fills n bytes at dst with the given byte value. Emits the respective instruction if bulk-memory is enabled, otherwise ships a polyfill.

  • function memory.repeat(dst: usize, src: usize, srcLength: usize, count: usize): void
+

    Repeats a sequence of bytes given as src with srcLength count times into destination dst.

  • function memory.compare(lhs: usize, rhs: usize, n: usize): i32
+

    Compares the first n bytes of left and right and returns a value that indicates their relationship:

    • Negative value if the first differing byte in lhs is less than the corresponding byte in rhs.
    • Positive value if the first differing byte in lhs is greater than the corresponding byte in rhs.
    • Zero​ if all n bytes of lhs and rhs are equal.
  • function memory.data(size: i32, align?: i32): usize
+

    Gets a pointer to a zeroed static chunk of memory of the given size. Alignment defaults to 16. Arguments must be compile-time constants.

  • function memory.data<T>(values: T[], align?: i32): usize
+

    Gets a pointer to a pre-initialized static chunk of memory. Alignment defaults to the size of T. Arguments must be compile-time constants.

# Control flow

  • function select<T>(ifTrue: T, ifFalse: T, condition: bool): T
+

    Selects one of two pre-evaluated values depending on the condition. Differs from an if/else in that both arms are always executed and the final value is picked based on the condition afterwards. Performs better than an if/else only if the condition is random (means: branch prediction is not going to perform well) and both alternatives are cheap. It is also worth to note that Binaryen will do relevant optimizations like switching to a select automatically, so simply using a ternary ? : may be preferable.

  • function unreachable(): auto
+

    Emits an unreachable instruction that results in a runtime error (trap) when executed. Both a statement and an expression of any type. Beware that trapping in managed code will most likely lead to memory leaks or even break the program because it ends execution prematurely.

# Atomics 🦄

The following instructions represent the WebAssembly threads and atomics (opens new window) specification. Must be enabled with --enable threads.

  • function atomic.load<T>(ptr: usize, immOffset?: usize): T
+

    Atomically loads an integer value from memory and returns it.

  • function atomic.store<T>(ptr: usize, value: auto, immOffset?: usize): void
+

    Atomically stores an integer value to memory.

  • function atomic.add<T>(ptr: usize, value: T, immOffset?: usize): T
+

    Atomically adds an integer value in memory.

  • function atomic.sub<T>(ptr: usize, value: T, immOffset?: usize): T
+

    Atomically subtracts an integer value in memory.

  • function atomic.and<T>(ptr: usize, value: T, immOffset?: usize): T
+

    Atomically performs a bitwise AND operation on an integer value in memory.

  • function atomic.or<T>(ptr: usize, value: T, immOffset?: usize): T
+

    Atomically performs a bitwise OR operation on an integer value in memory.

  • function atomic.xor<T>(ptr: usize, value: T, immOffset?: usize): T
+

    Atomically performs a bitwise XOR operation on an integer value in memory.

  • function atomic.xchg<T>(ptr: usize, value: T, immOffset?: usize): T
+

    Atomically exchanges an integer value in memory.

  • function atomic.cmpxchg<T>(ptr: usize, expected: T, replacement: T, immOffset?: usize): T
+

    Atomically compares and exchanges an integer value in memory if the condition is met.

  • function atomic.wait<T>(ptr: usize, expected: T, timeout: i64): AtomicWaitResult
+

    Performs a wait operation on an address in memory, suspending this agent if the integer condition is met. Return values are

    Value Description
    0 OK - Woken by another agent.
    1 NOT_EQUAL - Loaded value did not match the expected value.
    2 TIMED_OUT - Not woken before the timeout expired.
  • function atomic.notify(ptr: usize, count: i32): i32
+

    Performs a notify operation on an address in memory waking up suspended agents.

  • function atomic.fence(): void
+

    Performs a fence operation, preserving synchronization guarantees of higher level languages.

# SIMD 🦄

Likewise, these represent the WebAssembly SIMD (opens new window) specification. Must be enabled with --enable simd.

  • function v128(a: i8, ... , p: i8): v128
+

    Initializes a 128-bit vector from sixteen 8-bit integer values. Arguments must be compile-time constants.

    See Constructing constant vectors for additional type-specific options.

  • function v128.splat<T>(x: T): v128
+
    Creates a vector with identical lanes.
    T Instruction
    i8, u8 i8x16.splat
    i16, u16 i16x8.splat
    i32, u32 i32x4.splat
    i64, u64 i64x2.splat
    f32 f32x4.splat
    f64 f64x2.splat
  • function v128.extract_lane<T>(x: v128, idx: u8): T
+
    Extracts one lane as a scalar.
    T Instruction
    i8 i8x16.extract_lane_s
    u8 i8x16.extract_lane_u
    i16 i16x8.extract_lane_s
    u16 i16x8.extract_lane_u
    i32, u32 i32x4.extract_lane
    i64, u64 i64x2.extract_lane
    f32 f32x4.extract_lane
    f64 f64x2.extract_lane
  • function v128.replace_lane<T>(x: v128, idx: u8, value: T): v128
+
    Replaces one lane.
    T Instruction
    i8, u8 i8x16.replace_lane
    i16, u16 i16x8.replace_lane
    i32, u32 i32x4.replace_lane
    i64, u64 i64x2.replace_lane
    f32 f32x4.replace_lane
    f64 f64x2.replace_lane
  • function v128.shuffle<T>(a: v128, b: v128, ...lanes: u8[]): v128
+
    Selects lanes from either vector according to the specified lane indexes.
    T Instruction
    i8, u8 i8x16.shuffle
    i16, u16 i8x16.shuffle emulating i16x8.shuffle
    i32, u32 i8x16.shuffle emulating i32x4.shuffle
    i64, u64 i8x16.shuffle emulating i64x2.shuffle
    f32 i8x16.shuffle emulating f32x4.shuffle
    f64 i8x16.shuffle emulating f64x2.shuffle
  • function v128.swizzle(a: v128, s: v128): v128
+

    Selects 8-bit lanes from the first vector according to the indexes [0-15] specified by the 8-bit lanes of the second vector.

  • function v128.load(ptr: usize, immOffset?: usize, immAlign?: usize): v128
+

    Loads a vector from memory.

  • function v128.load_ext<TFrom>(ptr: usize, immOffset?: usize, immAlign?: usize): v128
+
    Creates a vector by loading the lanes of the specified integer type and extending each to the next larger type.
    TFrom Instruction
    i8 v128.load8x8_s
    u8 v128.load8x8_u
    i16 v128.load16x4_s
    u16 v128.load16x4_u
    i32 v128.load32x2_s
    u32 v128.load32x2_u
  • function v128.load_zero<TFrom>(ptr: usize, immOffset?: usize, immAlign?: usize): v128
+
    Creates a vector by loading a value of the specified type into the lowest bits and initializing all other bits of the vector to zero.
    TFrom Instruction
    i32, u32, f32 v128.load32_zero
    i64, u64, f64 v128.load64_zero
  • function v128.load_lane<T>(
+  ptr: usize, vec: v128, idx: u8, immOffset?: usize, immAlign?: usize
+): v128
+
    Loads a single lane from memory into the specified lane of the given vector. Other lanes are bypassed as is.
    T Instruction
    i8, u8 v128.load8_lane
    i16, u16 v128.load16_lane
    i32, u32, f32 v128.load32_lane
    i64, u64, f64 v128.load64_lane
  • function v128.store_lane<T>(
+  ptr: usize, vec: v128, idx: u8, immOffset?: usize, immAlign?: usize
+): v128
+
    Stores the single lane at the specified index of the given vector to memory.
    T Instruction
    i8, u8 v128.store8_lane
    i16, u16 v128.store16_lane
    i32, u32, f32 v128.store32_lane
    i64, u64, f64 v128.store64_lane
  • function v128.load_splat<T>(ptr: usize, immOffset?: usize, immAlign?: usize): v128
+
    Creates a vector with identical lanes by loading the splatted value.
    T Instruction
    i8, u8 v128.load8_splat
    i16, u16 v128.load16_splat
    i32, u32, f32 v128.load32_splat
    i64, u64, f64 v128.load64_splat
  • function v128.store(ptr: usize, value: v128, immOffset?: usize, immAlign?: usize): void
+

    Stores a vector to memory.

  • function v128.add<T>(a: v128, b: v128): v128
+
    Adds each lane.
    T Instruction
    i8, u8 i8x16.add
    i16, u16 i16x8.add
    i32, u32 i32x4.add
    i64, u64 i64x2.add
    f32 f32x4.add
    f64 f64x2.add
  • function v128.sub<T>(a: v128, b: v128): v128
+
    Subtracts each lane.
    T Instruction
    i8, u8 i8x16.sub
    i16, u16 i16x8.sub
    i32, u32 i32x4.sub
    i64, u64 i64x2.sub
    f32 f32x4.sub
    f64 f64x2.sub
  • function v128.mul<T>(a: v128, b: v128): v128
+
    Multiplies each lane.
    T Instruction
    i16, u16 i16x8.mul
    i32, u32 i32x4.mul
    i64, u64 i64x2.mul
    f32 f32x4.mul
    f64 f64x2.mul
  • function v128.div<T>(a: v128, b: v128): v128
+
    Divides each floating point lane.
    T Instruction
    f32 f32x4.div
    f64 f64x2.div
  • function v128.neg<T>(a: v128): v128
+
    Negates each lane.
    T Instruction
    i8, u8 i8x16.neg
    i16, u16 i16x8.neg
    i32, u32 i32x4.neg
    i64, u64 i64x2.neg
    f32 f32x4.neg
    f64 f64x2.neg
  • function v128.add_sat<T>(a: v128, b: v128): v128
+
    Adds each signed small integer lane using saturation.
    T Instruction
    i8 i8x16.add_sat_s
    u8 i8x16.add_sat_u
    i16 i16x8.add_sat_s
    u16 i16x8.add_sat_u
  • function v128.sub_sat<T>(a: v128, b: v128): v128
+
    Subtracts each signed small integer lane using saturation.
    T Instruction
    i8 i8x16.sub_sat_s
    u8 i8x16.sub_sat_u
    i16 i16x8.sub_sat_s
    u16 i16x8.sub_sat_u
  • function v128.shl<T>(a: v128, b: i32): v128
+
    Performs a bitwise left shift by a scalar on each integer lane.
    T Instruction
    i8, u8 i8x16.shl
    i16, u16 i16x8.shl
    i32, u32 i32x4.shl
    i64, u64 i64x2.shl
  • function v128.shr<T>(a: v128, b: i32): v128
+
    Performs a bitwise right shift by a scalar on each integer lane.
    T Instruction
    i8 i8x16.shr_s
    u8 i8x16.shr_u
    i16 i16x8.shr_s
    u16 i16x8.shr_u
    i32 i32x4.shr_s
    u32 i32x4.shr_u
    i64 i64x2.shr_s
    u64 i64x2.shr_u
  • function v128.and(a: v128, b: v128): v128
+

    Performs the bitwise a & b operation on each lane.

  • function v128.or(a: v128, b: v128): v128
+

    Performs the bitwise a | b operation on each lane.

  • function v128.xor(a: v128, b: v128): v128
+

    Performs the bitwise a ^ b operation on each lane.

  • function v128.andnot(a: v128, b: v128): v128
+

    Performs the bitwise a & !b operation on each lane.

  • function v128.not(a: v128): v128
+

    Performs the bitwise !a operation on each lane.

  • function v128.bitselect(v1: v128, v2: v128, mask: v128): v128
+

    Selects bits of either vector according to the specified mask. Selects from v1 if the bit in mask is 1, otherwise from v2.

  • function v128.any_true(a: v128): bool
+

    Reduces a vector to a scalar indicating whether any lane is considered true.

  • function v128.all_true<T>(a: v128): bool
+
    Reduces a vector to a scalar indicating whether all lanes are considered true.
    T Instruction
    i8, u8 i8x16.all_true
    i16, u16 i16x8.all_true
    i32, u32 i32x4.all_true
    i64, u64 i64x2.all_true
  • function v128.bitmask<T>(a: v128): bool
+
    Extracts the high bit of each integer lane (except 64-bit) and produces a scalar mask with all bits concatenated.
    T Instruction
    i8, u8 i8x16.bitmask
    i16, u16 i16x8.bitmask
    i32, u32 i32x4.bitmask
    i64, u64 i64x2.bitmask
  • function v128.popcnt<T>(a: v128): v128
+
    Counts the number of bits set to one within each lane.
    T Instruction
    i8, u8 i8x16.popcnt
  • function v128.min<T>(a: v128, b: v128): v128
+
    Computes the minimum of each lane.
    T Instruction
    i8 i8x16.min_s
    u8 i8x16.min_u
    i16 i16x8.min_s
    u16 i16x8.min_u
    i32 i32x4.min_s
    u32 i32x4.min_u
    f32 f32x4.min
    f64 f64x2.min
  • function v128.max<T>(a: v128, b: v128): v128
+
    Computes the maximum of each lane.
    T Instruction
    i8 i8x16.max_s
    u8 i8x16.max_u
    i16 i16x8.max_s
    u16 i16x8.max_u
    i32 i32x4.max_s
    u32 i32x4.max_u
    f32 f32x4.max
    f64 f64x2.max
  • function v128.pmin<T>(a: v128, b: v128): v128
+
    Computes the psuedo-minimum of each lane.
    T Instruction
    f32 f32x4.pmin
    f64 f64x2.pmin
  • function v128.pmax<T>(a: v128, b: v128): v128
+
    Computes the pseudo-maximum of each lane.
    T Instruction
    f32 f32x4.pmax
    f64 f64x2.pmax
  • function v128.dot<T>(a: v128, b: v128): v128
+
    Computes the dot product of two 16-bit integer lanes each, yielding lanes one size wider than the input.
    T Instruction
    i16 i32x4.dot_i16x8_s
  • function v128.avgr<T>(a: v128, b: v128): v128)
+
    Computes the rounding average of each unsigned small integer lane.
    T Instruction
    u8 i8x16.avgr_u
    u16 i16x8.avgr_u
  • function v128.abs<T>(a: v128): v128
+
    Computes the absolute value of each lane (except 64-bit integers).
    T Instruction
    i8, u8 i8x16.abs
    i16, u16 i16x8.abs
    i32, u32 i32x4.abs
    i64, u64 i64x2.abs
    f32 f32x4.abs
    f64 f64x2.abs
  • function v128.sqrt<T>(a: v128): v128
+
    Computes the square root of each floating point lane.
    T Instruction
    f32 f32x4.sqrt
    f64 f64x2.sqrt
  • function v128.ceil<T>(a: v128): v128
+
    Performs the ceiling operation on each lane.
    T Instruction
    f32 f32x4.ceil
    f64 f64x2.ceil
  • function v128.floor<T>(a: v128): v128
+
    Performs the floor operation on each lane.
    T Instruction
    f32 f32x4.floor
    f64 f64x2.floor
  • function v128.trunc<T>(a: v128): v128
+
    Rounds to the nearest integer towards zero of each lane.
    T Instruction
    f32 f32x4.trunc
    f64 f64x2.trunc
  • function v128.nearest<T>(a: v128): v128
+
    Rounds to the nearest integer half to even of each lane.
    T Instruction
    f32 f32x4.nearest
    f64 f64x2.nearest
  • function v128.eq<T>(a: v128, b: v128): v128
+
    Computes which lanes are equal.
    T Instruction
    i8, u8 i8x16.eq
    i16, u16 i16x8.eq
    i32, u32 i32x4.eq
    i64, u64 i64x2.eq
    f32 f32x4.eq
    f64 f64x2.eq
  • function v128.ne<T>(a: v128, b: v128): v128
+
    Computes which lanes are not equal.
    T Instruction
    i8, u8 i8x16.ne
    i16, u16 i16x8.ne
    i32, u32 i32x4.ne
    i64, u64 i64x2.ne
    f32 f32x4.ne
    f64 f64x2.ne
  • function v128.lt<T>(a: v128, b: v128): v128
+
    Computes which lanes of the first vector are less than those of the second.
    T Instruction
    i8 i8x16.lt_s
    u8 i8x16.lt_u
    i16 i16x8.lt_s
    u16 i16x8.lt_u
    i32 i32x4.lt_s
    u32 i32x4.lt_u
    i64 i64x2.lt_s
    f32 f32x4.lt
    f64 f64x2.lt
  • function v128.le<T>(a: v128, b: v128): v128
+
    Computes which lanes of the first vector are less than or equal those of the second.
    T Instruction
    i8 i8x16.le_s
    u8 i8x16.le_u
    i16 i16x8.le_s
    u16 i16x8.le_u
    i32 i32x4.le_s
    u32 i32x4.le_u
    i64 i64x2.le_s
    f32 f32x4.le
    f64 f64x2.le
  • function v128.gt<T>(a: v128, b: v128): v128
+
    Computes which lanes of the first vector are greater than those of the second.
    T Instruction
    i8 i8x16.gt_s
    u8 i8x16.gt_u
    i16 i16x8.gt_s
    u16 i16x8.gt_u
    i32 i32x4.gt_s
    u32 i32x4.gt_u
    i64 i64x2.gt_s
    f32 f32x4.gt
    f64 f64x2.gt
  • function v128.ge<T>(a: v128, b: v128): v128
+
    Computes which lanes of the first vector are greater than or equal those of the second.
    T Instruction
    i8 i8x16.ge_s
    u8 i8x16.ge_u
    i16 i16x8.ge_s
    u16 i16x8.ge_u
    i32 i32x4.ge_s
    u32 i32x4.ge_u
    i64 i64x2.ge_s
    f32 f32x4.ge
    f64 f64x2.ge
  • function v128.convert<TFrom>(a: v128): v128
+
    Converts each lane of a vector from integer to single-precision floating point.
    TFrom Instruction
    i32 f32x4.convert_i32x4_s
    u32 f32x4.convert_i32x4_u
  • function v128.convert_low<TFrom>(a: v128): v128
+
    Converts the low lanes of a vector from integer to double-precision floating point.
    TFrom Instruction
    i32 f64x2.convert_low_i32x4_s
    u32 f64x2.convert_low_i32x4_u
  • function v128.trunc_sat<TTo>(a: v128): v128
+
    Truncates each lane of a vector from single-precision floating point to integer with saturation. Takes the target type.
    TTo Instruction
    i32 i32x4.trunc_sat_f32x4_s
    u32 i32x4.trunc_sat_f32x4_u
  • function v128.trunc_sat_zero<TTo>(a: v128): v128
+
    Truncates each lane of a vector from double-precision floating point to integer with saturation. Takes the target type.
    TTo Instruction
    i32 i32x4.trunc_sat_f64x2_s_zero
    u32 i32x4.trunc_sat_f64x2_u_zero
  • function v128.narrow<TFrom>(a: v128, b: v128): v128
+
    Narrows wider integer lanes to their respective narrower lanes.
    TFrom Instruction
    i16 i8x16.narrow_i16x8_s
    u16 i8x16.narrow_i16x8_u
    i32 i16x8.narrow_i32x4_s
    u32 i16x8.narrow_i32x4_u
  • function v128.extend_low<TFrom>(a: v128): v128
+
    Extends the low half of narrower integer lanes to their respective wider lanes.
    TFrom Instruction
    i8 i16x8.extend_low_i8x16_s
    u8 i16x8.extend_low_i8x16_u
    i16 i32x4.extend_low_i16x8_s
    u16 i32x4.extend_low_i16x8_u
    i32 i64x2.extend_low_i32x4_s
    u32 i64x2.extend_low_i32x4_u
  • function v128.extend_high<TFrom>(a: v128): v128
+
    Extends the high half of narrower integer lanes to their respective wider lanes.
    TFrom Instruction
    i8 i16x8.extend_high_i8x16_s
    u8 i16x8.extend_high_i8x16_u
    i16 i32x4.extend_high_i16x8_s
    u16 i32x4.extend_high_i16x8_u
    i32 i64x2.extend_high_i32x4_s
    u32 i64x2.extend_high_i32x4_u
  • function v128.extadd_pairwise<TFrom>(a: v128): v128
+
    Adds lanes pairwise producing twice wider extended results.
    TFrom Instruction
    i16 i16x8.extadd_pairwise_i8x16_s
    u16 i16x8.extadd_pairwise_i8x16_u
    i32 i32x4.extadd_pairwise_i16x8_s
    u32 i32x4.extadd_pairwise_i16x8_u
  • function v128.demote_zero<T>(a: v128): v128
+
    Demotes each float lane to lower precision. The higher lanes of the result are initialized to zero.
    T Instruction
    f64 f32x4.demote_f64x2_zero
  • function v128.promote_low<T>(a: v128): v128
+
    Promotes the lower float lanes to higher precision.
    T Instruction
    f32 f64x2.promote_low_f32x4
  • function v128.q15mulr_sat<T>(a: v128, b: v128): v128
+
    Performs the line-wise saturating rounding multiplication in Q15 format ((a[i] * b[i] + (1 << (Q - 1))) >> Q where Q=15).
    T Instruction
    i16 i16x8.q15mulr_sat_s
  • function v128.extmul_low<T>(a: v128, b: v128): v128
+
    Performs the lane-wise integer extended multiplication of the lower lanes producing a twice wider result than the inputs.
    T Instruction
    i8 i16x8.extmul_low_i8x16_s
    u8 i16x8.extmul_low_i8x16_u
    i16 i32x4.extmul_low_i16x8_s
    u16 i32x4.extmul_low_i16x8_u
    i32 i64x2.extmul_low_i32x4_s
    u32 i64x2.extmul_low_i32x4_u
  • function v128.extmul_high<T>(a: v128, b: v128): v128
+
    Performs the lane-wise integer extended multiplication of the higher lanes producing a twice wider result than the inputs.
    T Instruction
    i8 i16x8.extmul_high_i8x16_s
    u8 i16x8.extmul_high_i8x16_u
    i16 i32x4.extmul_high_i16x8_s
    u16 i32x4.extmul_high_i16x8_u
    i32 i64x2.extmul_high_i32x4_s
    u32 i64x2.extmul_high_i32x4_u

# Constructing constant vectors

  • function i8x16(a: i8, ... , p: i8): v128
+

    Initializes a 128-bit vector from sixteen 8-bit integer values.

  • function i16x8(a: i16, ..., h: i16): v128
+

    Initializes a 128-bit vector from eight 16-bit integer values.

  • function i32x4(a: i32, b: i32, c: i32, d: i32): v128
+

    Initializes a 128-bit vector from four 32-bit integer values.

  • function i64x2(a: i64, b: i64): v128
+

    Initializes a 128-bit vector from two 64-bit integer values.

  • function f32x4(a: f32, b: f32, c: f32, d: f32): v128
+

    Initializes a 128-bit vector from four 32-bit float values.

  • function f64x2(a: f64, b: f64): v128
+

    Initializes a 128-bit vector from two 64-bit float values.

# Relaxed SIMD 🦄

The following instructions represent the WebAssembly Relaxed SIMD (opens new window) specification. Must be enabled with --enable relaxed-simd.

  • function v128.relaxed_swizzle(a: v128, s: v128): v128
+

    Selects 8-bit lanes from a using indices in s. Indices in the range [0-15] select the i-th element of a.

    Unlike v128.swizzle, the result of an out of bounds index is implementation-defined, depending on hardware capabilities: Either 0 or a[s[i]%16].

  • function v128.relaxed_trunc<T>(a: v128): v128
+
    Truncates each lane of a vector from 32-bit floating point to a 32-bit signed or unsigned integer as indicated by T.
    T Instruction
    i32 i32x4.relaxed_trunc_f32x4_s
    u32 i32x4.relaxed_trunc_f32x4_u

    Unlike v128.trunc_sat, the result of lanes out of bounds of the target type is implementation defined, depending on hardware capabilities:

    • If the input lane contains NaN, the result is either 0 or the respective maximum integer value.
    • If the input lane contains a value otherwise out of bounds of the target type, the result is either the saturatated result or maximum integer value.
  • function v128.relaxed_trunc_zero<T>(a: v128): v128
+
    Truncates each lane of a vector from 64-bit floating point to a 32-bit signed or unsigned integer as indicated by T. Unused higher integer lanes of the result are initialized to zero.
    T Instruction
    i32 i32x4.relaxed_trunc_f64x2_s_zero
    u32 i32x4.relaxed_trunc_f64x2_u_zero

    Unlike v128.trunc_sat_zero, the result of lanes out of bounds of the target type is implementation defined, depending on hardware capabilities:

    • If the input lane contains NaN, the result is either 0 or the respective maximum integer value.
    • If the input lane contains a value otherwise out of bounds of the target type, the result is either the saturatated result or maximum integer value.
  • function v128.relaxed_madd<T>(a: v128, b: v128, c: v128): v128
+
    Performs the fused multiply-add operation (a * b + c) on 32- or 64-bit floating point lanes as indicated by T.
    T Instruction
    f32 f32x4.relaxed_madd
    f64 f64x2.relaxed_madd

    The result is implementation defined, depending on hardware capabilities:

    • Either a * b is rounded once and the final result rounded again, or
    • The expression is evaluated with higher precision and only rounded once
  • function v128.relaxed_nmadd<T>(a: v128, b: v128, c: v128): v128
+
    Performs the fused negative multiply-add operation (-(a * b) + c) on 32- or 64-bit floating point lanes as indicated by T.
    T Instruction
    f32 f32x4.relaxed_nmadd
    f64 f64x2.relaxed_nmadd

    The result is implementation defined, depending on hardware capabilities:

    • Either a * b is rounded once and the final result rounded again, or
    • The expression is evaluated with higher precision and only rounded once
  • function v128.relaxed_laneselect<T>(a: v128, b: v128, m: v128): v128
+
    Selects 8-, 16-, 32- or 64-bit integer lanes as indicated by T from a or b based on masks in m.
    T Instruction
    i8, u8 i8x16.relaxed_laneselect
    i16, u16 i16x8.relaxed_laneselect
    i32, u32 i32x4.relaxed_laneselect
    i64, u64 i64x2.relaxed_laneselect

    Behaves like v128.bitselect if masks in m do have all bits either set (result is a[i]) or unset (result is b[i]). Otherwise the result is implementation-defined, depending on hardware capabilities: If the most significant bit of m is set, the result is either bitselect(a[i], b[i], mask) or a[i], otherwise the result is b[i].

  • function v128.relaxed_min<T>(a: v128, b: v128): v128
+
    Computes the minimum of each 32- or 64-bit floating point lane as indicated by T.
    T Instruction
    f32 f32x4.relaxed_min
    f64 f64x2.relaxed_min

    Unlike v128.min, the result is implementation-defined if either value is NaN or both are -0.0 and +0.0, depending on hardware capabilities: Either a[i] or b[i].

  • function v128.relaxed_max<T>(a: v128, b: v128): v128
+
    Computes the maximum of each 32- or 64-bit floating point lane as indicated by T.
    T Instruction
    f32 f32x4.relaxed_max
    f64 f64x2.relaxed_max

    Unlike v128.max, the result is implementation-defined if either value is NaN or both are -0.0 and +0.0, depending on hardware capabilities: Either a[i] or b[i].

  • function v128.relaxed_q15mulr<T>(a: v128, b: v128): v128
+
    Performs the lane-wise rounding multiplication in Q15 format ((a[i] * b[i] + (1 << (Q - 1))) >> Q where Q=15).
    T Instruction
    i16 i16x8.relaxed_q15mulr_s

    Unlike v128.q15mulr_sat, the result is implementation-defined if both inputs are the minimum signed value: Either the minimum or maximum signed value.

  • function v128.relaxed_dot<T>(a: v128, b: v128): v128
+
    Computes the dot product of two 8-bit integer lanes each, yielding lanes one size wider than the input.
    T Instruction
    i16 i16x8.relaxed_dot_i8x16_i7x16_s

    Unlike v128.dot, if the most significant bit of b[i] is set, whether b[i] is interpreted as signed or unsigned by the intermediate multiplication is implementation-defined.

  • function v128.relaxed_dot_add<T>(a: v128, b: v128, c: v128): v128
+
    Computes the dot product of two 8-bit integer lanes each, yielding lanes two sizes wider than the input with the lanes of c accumulated into the result.
    T Instruction
    i32 i32x4.relaxed_dot_i8x16_i7x16_add_s

    Unlike v128.dot, if the most significant bit of b[i] is set, whether b[i] is interpreted as signed or unsigned by the intermediate multiplication is implementation-defined.

# Inline instructions

In addition to using the generic builtins above, most WebAssembly instructions can be written directly in AssemblyScript code. For example, the following is equivalent:

// generic builtin
+v128.splat<i32>(42);
+
+// inline instruction
+i32x4.splat(42);
+

+ ← + + Array + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/heap.html b/stdlib/heap.html new file mode 100644 index 000000000..de80cb20a --- /dev/null +++ b/stdlib/heap.html @@ -0,0 +1,89 @@ + + + + + + heap | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# heap

An unsafe interface to use the dynamic memory manager directly, resembling malloc, realloc and free. Manual memory management can be used in parallel to garbage collection, which can be quite handy, but manually managed blocks cannot be mixed with garbage collected objects (i.e. trying to heap.free a GC object or casting a block to a managed object respectively would break since one has a GC header and the other does not).

# Static members

  • function heap.alloc(size: usize): usize
+

    Allocates a chunk of memory of at least the specified size.

  • function heap.realloc(ptr: usize, size: usize): usize
+

    Reallocates a chunk of memory to have at least the specified size.

  • function heap.free(ptr: usize): void
+

    Frees a chunk of memory.

  • function heap.reset(): void
+

    Dangerously resets the entire heap. Specific to the "stub" runtime.

+ ← + + Math + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/map.html b/stdlib/map.html new file mode 100644 index 000000000..ccaa355b1 --- /dev/null +++ b/stdlib/map.html @@ -0,0 +1,102 @@ + + + + + + Map | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Map

A mapping of generic keys to generic values.

The Map API is very similar to JavaScript's (MDN (opens new window)), with the notable difference that a .get with a key that does not exist results in an error, because undefined cannot be represented. Example:

var map = new Map<i32,string>()
+
+// Because `undefined` cannot be represented if a key is not found, this will error:
+var str = map.get(1) // ERROR
+
+// The error can be avoided by first making sure that the key exists, so this works:
+var str: string | null = map.has(1) ? map.get(1) : null // OK
+

# Constructor

  • new Map<K,V>()
+
    Constructs a new map mapping keys of type K to values of type V.

# Instance members

# Fields

  • readonly size: i32
+
    The current number of key-value pairs in this map.

# Methods

  • function clear(): void
+

    Clears the map, deleting all key-value pairs.

  • function delete(key: K): bool
+

    Deletes the key-value pair for the corresponding key. Returns true if the key did exist, otherwise false.

  • function get(key: K): V
+

    Gets the value corresponding to the specified key. Traps if the key does not exist because "not found" cannot be represented in all cases (use Map#has to check).

  • function has(key: K): bool
+

    Tests if the specified key exists.

  • function keys(): Array<K>
+

    Gets the keys contained in this map as an array, in insertion order. This is preliminary while iterators are not supported.

  • function set(key: K, value: V): this
+

    Sets the value for the specified key. Creates a new key-value pair if the key did not exist.

  • function values(): Array<V>
+

    Gets the values contained in this map as an array, in insertion order. This is preliminary while iterators are not supported.

  • function toString(): string
+

    Returns a string representation of this map.

+ ← + + Number + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/math.html b/stdlib/math.html new file mode 100644 index 000000000..e2664d9af --- /dev/null +++ b/stdlib/math.html @@ -0,0 +1,130 @@ + + + + + + Math | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Math

Mathematical operations as known from JavaScript.

The Math API is very much like JavaScript's (MDN (opens new window)), with the notable exceptions stated above and rest parameters not being supported yet.

# Variants

Math in AssemblyScript is available in multiple variants.

Variant Description
NativeMath WebAssembly implementation for f64
NativeMathf WebAssembly implementation for f32
JSMath JavaScript implementation for f64 (imported from the host)

By default, the global Math object is an alias of NativeMath and Mathf is an alias of NativeMathf .

# Using JSMath

By default, the compiler utilizes NativeMath which is implemented in WebAssembly directly, but where small module size is more important than performance, one can opt to override the default by adding --use Math=JSMath on the command line, essentially aliasing Math with JSMath instead, which maps to an import of the browser's math implementation. Naturally, this option requires importing the browser's Math object as a whole, but does not require seeding / is not seedable. Generated bindings automatically take care of importing the browser's math in this scenario.

# Static members

The type T below substitutes either f32 or f64 depending on the implementation used. Note that Math is not actually generic, but concrete implementations like Math and Mathf have an identical interface that only differs in the implementation's floating-point precision denoted by T.

# Constants

  • const E: T
+

    The base of natural logarithms, e, approximately 2.718.

  • const LN2: T
+

    The natural logarithm of 2, approximately 0.693.

  • const LN10: T
+

    The natural logarithm of 10, approximately 2.302.

  • const LOG2E: T
+

    The base 2 logarithm of e, approximately 1.442.

  • const LOG10E: T
+

    The base 10 logarithm of e, approximately 0.434.

  • const PI: T
+

    The ratio of the circumference of a circle to its diameter, approximately 3.14159.

  • const SQRT1_2: T
+

    The square root of 1/2, approximately 0.707.

  • const SQRT2: T
+

    The square root of 2, approximately 1.414.

# Functions

  • function abs(x: T): T
+

    Returns the absolute value of x.

  • function acos(x: T): T
+

    Returns the arccosine (in radians) of x.

  • function acosh(x: T): T
+

    Returns the hyperbolic arc-cosine of x.

  • function asin(x: T): T
+

    Returns the arcsine (in radians) of x.

  • function asinh(x: T): T
+

    Returns the hyperbolic arcsine of x.

  • function atan(x: T): T
+

    Returns the arctangent (in radians) of x.

  • function atan2(y: T, x: T): T
+

    Returns the arctangent of the quotient of its arguments.

  • function atanh(x: T): T
+

    Returns the hyperbolic arctangent of x.

  • function cbrt(x: T): T
+

    Returns the cube root of x.

  • function ceil(x: T): T
+

    Returns the smallest integer greater than or equal to x.

  • function clz32(x: T): T
+

    Returns the number of leading zero bits in the 32-bit binary representation of x.

  • function cos(x: T): T
+

    Returns the cosine (in radians) of x.

  • function cosh(x: T): T
+

    Returns the hyperbolic cosine of x.

  • function exp(x: T): T
+

    Returns e to the power of x.

  • function expm1(x: T): T
+

    Returns e to the power of x, minus 1.

  • function floor(x: T): T
+

    Returns the largest integer less than or equal to x.

  • function fround(x: T): T
+

    Returns the nearest 32-bit single precision float representation of x.

  • function hypot(value1: T, value2: T): T
+

    Returns the square root of the sum of squares of its arguments.

  • function imul(a: T, b: T): T
+

    Returns the result of the C-like 32-bit multiplication of a and b.

  • function log(x: T): T
+

    Returns the natural logarithm (base e) of x.

  • function log10(x: T): T
+

    Returns the base 10 logarithm of x.

  • function log1p(x: T): T
+

    Returns the natural logarithm (base e) of 1 + x.

  • function log2(x: T): T
+

    Returns the base 2 logarithm of x.

  • function max(value1: T, value2: T): T
+

    Returns the largest-valued number of its arguments.

  • function min(value1: T, value2: T): T
+

    Returns the lowest-valued number of its arguments.

  • function pow(base: T, exponent: T): T
+

    Returns base to the power of exponent.

  • function random(): T
+

    Returns a pseudo-random number in the range from 0.0 inclusive up to but not including 1.0.

    Note that Math.random needs a way to seed the random number generator, which is achieved with a special import env.seed returning the seed as an f64 value. Generated bindings and WASI take care of it automatically.

  • function round(x: T): T
+

    Returns the value of x rounded to the nearest integer.

  • function seedRandom(value: i64): void
+

    Seeds the random function. Called internally by random if the seed hasn't been set.

  • function sign(x: T): T
+

    Returns the sign of x, indicating whether the number is positive, negative or zero.

  • function signbit(x: T): bool
+

    Returns whether the sign bit of x is set.

  • function sin(x: T): T
+

    Returns the sine of x.

  • function sinh(x: T): T
+

    Returns the hyperbolic sine of x.

  • function sqrt(x: T): T
+

    Returns the square root of x.

  • function tan(x: T): T
+

    Returns the tangent of x.

  • function tanh(x: T): T
+

    Returns the hyperbolic tangent of x.

  • function trunc(x: T): T
+

    Returns the integer part of x by removing any fractional digits.

# Considerations

The Math implementations are meant as a drop-in replacement for JavaScript's Math with all its quirks. For example, Math.round always rounds towards +Infinity and Math.imul and similar functions operate on number, which is f64 in AssemblyScript. Hence, using WebAssembly's math instructions directly where possible is often more efficient.

+ ← + + Map + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/number.html b/stdlib/number.html new file mode 100644 index 000000000..6368e7d25 --- /dev/null +++ b/stdlib/number.html @@ -0,0 +1,104 @@ + + + + + + Number | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Number

Wrappers for basic numerical values.

The Number object has been split into one class per basic WebAssembly type as well. Unlike in JavaScript, these classes cannot have actual instances, hence it works a bit different than JavaScript's (MDN (opens new window)).

# Integers

The name Number below stands for one of the wrappers I8, I16, I32, I64, U8, U16, U32 or U64 representing their respective basic integer type T.

# Static members

  • const MIN_VALUE: T
+

    The smallest representable value of the respective basic type. Differs from floating point values where it is the smallest representable positive value.

  • const MAX_VALUE: T
+

    The largest representable value of the respective basic type.

  • function parseInt(value: string, radix?: i32): T
+

    Parses a string to a value of the respective basic type.

# Instance members

  • function toString(radix?: i32): string
+
    Returns the respective basic value converted to a string.

# Floats

The name Number below stands for one of the wrappers F32 or F64 representing their respective basic floating point type T.

# Static members

  • const EPSILON: T
+

    The difference between 1.0 and the smallest number larger than 1.0.

  • const MAX_VALUE: T
+

    The largest representable positive value by the respective basic type.

  • const MIN_VALUE: T
+

    The smallest representable positive value by the respective basic type.

  • const MAX_SAFE_INTEGER: T
+

    The largest safe integer representable by the respective basic type.

  • const MIN_SAFE_INTEGER: T
+

    The smallest safe integer representable by the respective basic type.

  • const POSITIVE_INFINITY: T
+

    Positive infinity of the respective basic type.

  • const NEGATIVE_INFINITY: T
+

    Negative infinity of the respective basic type.

  • const NaN: T
+

    NaN (Not A Number) of the respective basic type.

  • function isNaN(value: T): bool
+

    Tests if the value is NaN.

  • function isFinite(value: T): bool
+

    Tests if the value is finite, that is not NaN , POSITIVE_INFINITY or NEGATIVE_INFINITY.

  • function isInteger(value: T): bool
+

    Tests if the value is an integer.

  • function isSafeInteger(value: T): bool
+

    Tests if the value is a safe integer.

  • function parseInt(value: string, radix?: i32): T
+

    Parses a string to an integer value of the respective basic type.

  • function parseFloat(value: string): T
+

    Parses a string to a float value of the respective basic type.

# Instance members

  • function toString(radix?: i32): string
+
    Returns the respective basic value converted to a string. The radix parameter is currently ignored here.

+ ← + + process + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/process.html b/stdlib/process.html new file mode 100644 index 000000000..57571fa06 --- /dev/null +++ b/stdlib/process.html @@ -0,0 +1,96 @@ + + + + + + process | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# process

An implementation of a Node.js-like process global.

# Static members

  • const arch: string
+

    String representing the CPU architecture for which the binary was compiled. Either wasm32 or wasm64.

  • const platform: string
+

    String representing the operating system platform for which the binary was compiled. Always wasm.

  • const argv: string[]
+

    Array of command line arguments passed to the binary upon instantiation.

  • const env: Map<string,string>
+

    Map of variables in the binary's user environment.

  • var exitCode: i32
+

    Process exit code to use when the process exits gracefully. Defaults to 0.

  • function exit(code?: i32): void
+

    Terminates the process with either the given exit code, or process.exitCode if omitted.

  • const stdin: ReadableStream
+const stdout: WritableStream
+const stderr: WritableStream
+

    Streams connected to stdin (fd 0), stdout (fd 1) and stderr (fd 2) respectively.

  • function time(): i64
+

    Obtains the system's current time of day, in milliseconds since Unix epoch.

  • function hrtime(): u64
+

    Obtains the system's monotonic high resolution time, in nanoseconds since an arbitrary time in the past.

+ ← + + Set + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/set.html b/stdlib/set.html new file mode 100644 index 000000000..0ebcd159c --- /dev/null +++ b/stdlib/set.html @@ -0,0 +1,93 @@ + + + + + + Set | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Set

A set of unique generic values.

The Set API is very similar to JavaScript's (MDN (opens new window)), but iterators are not implemented yet.

# Constructor

  • new Set<T>()
+
    Constructs a new set of unique value of type T.

# Instance members

# Fields

  • readonly size: i32
+
    The current number of unique values in the set.

# Methods

  • function add(value: T): void
+

    Adds the specified value to the set. Does nothing if the value already exists.

  • function delete(value: T): bool
+

    Deletes the specified value. Returns true if the value was found, otherwise false.

  • function clear(): void
+

    Clears the set, deleting all values.

  • function has(value: T): bool
+

    Tests if the specified value exists in the set.

  • function values(): Array<T>
+

    Gets the values contained in this set as an array, in insertion order. This is preliminary while iterators are not supported.

  • function toString(): string
+

    Returns a string representation of this set.

+ ← + + StaticArray + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/staticarray.html b/stdlib/staticarray.html new file mode 100644 index 000000000..7e2b8a7f3 --- /dev/null +++ b/stdlib/staticarray.html @@ -0,0 +1,117 @@ + + + + + + StaticArray | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# StaticArray

A randomly accessible sequence of values of a generic type with a fixed length.

The StaticArray API is similar to the Array API, with the important difference that it has a fixed length that cannot change. Unlike a normal Array, a StaticArray does not have a separate backing buffer, so no level of indirection, and as such can have minimal overhead and performance characteristics very similar to arrays in C.

# Constructor

  • new StaticArray<T>(length: i32)
+
    Constructs a new static array.

# Static members

  • function fromArray<T>(source: Array<T>): StaticArray<T>
+

    Creates a static array from a normal array.

  • function concat<T>(source: StaticArray<T>, other: StaticArray<T>): StaticArray<T>
+

    Deprecated! Like the instance member concat, but taking and returning a StaticArray.

    Instead of StaticArray.concat better to use parametric concat instance method.

  • function slice<T>(source: StaticArray<T>, start?: i32, end?: i32): StaticArray<T>
+

    Deprecated! Like the instance member slice, but returning a StaticArray.

    Instead of StaticArray.slice better to use parametric slice instance method.

# Instance members

# Fields

  • readonly length: i32
+
    The fixed length of this static array.

# Methods

  • function at(pos: i32): T
+

    Gets the element at the specified position. This method allows for positive and negative integers. Negative integers count back from the last element.

  • function concat<U extends ArrayLike<T> = Array<T>>(other: U): U
+

    Concatenates the values of this static and the other normal array to a new normal array, in this order. Patameter U accepts Array<T> or StaticArray<T> types.

  • function copyWithin(target: i32, start: i32, end?: i32): this
+

    Copies a region of an array's values over the respective values starting at the target location.

  • function every(fn: (value: T, index: i32, self: StaticArray<T>) => bool): bool
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns false. Returns true if all functions returned true or the array is empty, otherwise false.

  • function fill(value: T, start?: i32, end?: i32): this
+

    Replaces the values of the array from start inclusive to end exclusive in place with the specified value, returning the array.

  • function filter(fn: (value: T, index: i32, self: StaticArray<T>) => bool): Array<T>
+

    Calls the specified function with every value of the array, returning a new array with all values for which the function returned true.

  • function findIndex(fn: (value: T, index: i32, self: StaticArray<T>) => bool): i32
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

  • function findLastIndex(fn: (value: T, index: i32, self: StaticArray<T>) => bool): i32;
+

    Calls the specified function with every value of the array starting at the end until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

  • function forEach(fn: (value: T, index: i32, self: StaticArray<T>) => void): void
+

    Calls the specified function with every value of the array.

  • function includes(value: T, fromIndex?: i32): bool
+

    Tests if the array includes the specified value, optionally providing a starting index.

  • function indexOf(value: T, fromIndex?: i32): i32
+

    Gets the first index where the specified value can be found in the array. Returns -1 if not found.

  • function join(separator?: string): string
+

    Concatenates all values of the array to a string, separated by the specified separator (default: ,).

  • function lastIndexOf(value: T, fromIndex?: i32): i32
+

    Gets the last index where the specified value can be found in the array. Returns -1 if not found.

  • function map<U>(fn: (value: T, index: i32, self: StaticArray<T>) => U): Array<U>
+

    Calls the specified function with every value of the array, returning a new array of the function's return values.

  • function slice<U extends ArrayLike<T> = Array<T>>(start?: i32, end?: i32): U
+

    Returns a shallow copy of this static array's values from begin inclusive to end exclusive, as a new normal array. If omitted, end defaults to the end of the array. Patameter U accepts Array<T> or StaticArray<T> types.

  • function some(fn: (value: T, index: i32, self: StaticArray<T>) => bool): bool
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning true. Returns false otherwise or if the array is empty.

  • function sort(fn?: (a: T, b: T) => i32): this
+

    Sorts the values of the array in place, using the specified comparator function, modifying the array before returning it. The comparator returning a negative value means a < b, a positive value means a > b and 0 means that both are equal. Unlike in JavaScript, where an implicit conversion to strings is performed, the comparator defaults to compare two values of type T.

  • function reduce<U>(
+  fn: (accumValue: U, currentValue: T, index: i32, self: StaticArray<T>) => U,
+  initialValue: U
+): U
+

    Calls the specified reducer function with each value of the array, resulting in a single return value. The respective previous reducer function's return value is remembered in accumValue, starting with initialValue, becoming the final return value in the process.

  • function reduceRight<U>(
+  fn: (accumValue: U, currentValue: T, index: i32, self: StaticArray<T>) => U,
+  initialValue: U
+): U
+

    Calls the specified reducer function with each value of the array, from right to left, resulting in a single return value. See Array#reduce for the reducer function's signature.

  • function reverse(): this
+

    Reverses an array's values in place, modifying the array before returning it.

  • function toString(): string
+

    Returns the result of join().

+ ← + + String + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/string.html b/stdlib/string.html new file mode 100644 index 000000000..c76d118a5 --- /dev/null +++ b/stdlib/string.html @@ -0,0 +1,128 @@ + + + + + + String | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# String

A fixed-length sequence of UTF-16 code units.

The String API works very much like JavaScript's (MDN (opens new window)), with the notable difference that the string type is an actual alias of String.

# Static members

  • function fromCharCode(unit: i32, surr?: i32): string
+

    Creates a one character long string from the specified UTF-16 code units.

  • function fromCharCodes(units: u16[]): string
+

    Creates a string from a sequence of UTF-16 code units.

  • function fromCodePoint(code: i32): string
+

    Creates a one character long string from the specified Unicode code point.

  • function fromCodePoints(codes: i32[]): string
+

    Creates a string from a sequence of Unicode code points.

# Instance members

# Fields

  • readonly length: i32
+
    The length of the string in UTF-16 code units.

# Methods

  • function at(pos: i32): string
+

    Gets the UTF-16 code unit at the specified position as a single character string. This method allows for positive and negative integers. Negative integers count back from the last string character.

  • function charAt(pos: i32): string
+

    Gets the UTF-16 code unit at the specified position as a single character string. Returns "" (empty string) if out of bounds.

  • function charCodeAt(pos: i32): i32
+

    Gets the UTF-16 code unit at the specified position as a number. Returns -1 if out of bounds.

  • function codePointAt(pos: i32): i32
+

    Gets the Unicode code point at the specified (UTF-16 code unit) position as a number, possibly combining multiple successive UTF-16 code units. Returns -1 if out of bounds.

  • function concat(other: string): string
+

    Concatenates this string with another string, in this order, and returns the resulting string.

  • function endsWith(search: string, end?: i32): bool
+

    Tests if the strings ends with the specified string. If specified, end indicates the position at which to stop searching, acting as if it is the length of the string.

  • function includes(search: string, start?: i32): bool
+

    Tests if the string includes the search string. If specified, start indicates the position at which to begin searching.

  • function indexOf(search: string, start?: i32): i32
+

    Gets the first index of the specified search string within the string, or -1 if not found. If specified, start indicates the position at which to begin searching.

  • function lastIndexOf(search: string, start?: i32): i32
+

    Gets the last index of the specified search string within the string, or -1 if not found. If specified, start indicates the position at which to begin searching from right to left.

  • function padStart(length: i32, pad: string): string
+

    Pads the string with the contents of another string, possibly multiple times, until the resulting string reaches the specified length, returning the resulting string.

  • function padEnd(length: i32, pad: string): string
+

    Pads the string with the contents of another string, possibly multiple times, until the resulting string reaches the specified length, returning the resulting string.

  • function repeat(count?: i32): string
+

    Repeats the string count times and returns the concatenated result.

  • function replace(search: string, replacement: string): string
+

    Replaces the first occurrence of search with replacement.

  • function replaceAll(search: string, replacement: string): string
+

    Replaces all occurrences of search with replacement.

  • function slice(start: i32, end?: i32): string
+

    Returns the region of the string from start inclusive to end exclusive, as a new string. If omitted, end defaults to the end of the string.

  • function split(separator?: string, limit?: i32): string[]
+

    Splits the string at each occurrence of separator and returns the result as a new array of strings that has a maximum of limit values. If limit is omitted, no limit is assumed. If separator is omitted or not present in the string, the string becomes the sole element of the array. If separator is an empty string, the split is performed between code units (not code points), potentially destroying surrogate pairs.

  • function startsWith(search: string, start?: i32): bool
+

    Tests if the string starts with the specified string. If specified, start indicates the position at which to begin searching, acting as the start of the string.

  • function substring(start: i32, end?: i32): string
+

    Gets the part of the string in between start inclusive and end exclusive as a new string.

  • function toString(): this
+

    Returns the string.

  • function trim(): string
+

    Removes white space characters from both the start and the end of the string, returning the resulting string.

  • function trimStart(): string
+function trimLeft(): string
+

    Removes white space characters from the start of the string, returning the resulting string.

  • function trimEnd(): string
+function trimRight(): string
+

    Removes white space characters from the end of the string, returning the resulting string.

# Encoding API

# UTF8

When integrating with an environment that uses UTF-8, the following helpers can be used to quickly re-encode String data.

  • function String.UTF8.byteLength(str: string, nullTerminated?: bool): i32
+

    Calculates the byte length of the specified string when encoded as UTF-8, optionally null terminated.

  • function String.UTF8.encode(str: string, nullTerminated?: bool): ArrayBuffer
+

    Encodes the specified string to UTF-8 bytes, optionally null terminated.

  • function String.UTF8.encodeUnsafe(str: usize, len: i32, buf: usize, nullTerminated?: bool): usize
+

    Encodes the specified raw string to UTF-8 bytes, opionally null terminated. Returns the number of bytes written.

  • function String.UTF8.decode(buf: ArrayBuffer, nullTerminated?: bool): string
+

    Decodes the specified buffer from UTF-8 bytes to a string, optionally null terminated.

  • function String.UTF8.decodeUnsafe(
+  buf: usize,
+  len: usize,
+  nullTerminated?: bool
+): string
+

    Decodes raw UTF-8 bytes to a string, optionally null terminated.

TIP

Note that any ArrayBuffer return value is a pointer to the buffer's data internally and thus can be passed to let's say a C-function directly. However, if the pointer is meant to live longer than the immediate external function call, the lifetime of the buffer must be tracked so it doesn't become collected prematurely with the data becoming invalid.

# UTF16

The following mostly exist to have a safe way to copy between Strings and ArrayBuffers, but doesn't involve a re-encoding step.

  • function String.UTF16.byteLength(str: string): i32
+

    Calculates the byte length of the specified string when encoded as UTF-16.

  • function String.UTF16.encode(str: string): ArrayBuffer
+

    Encodes the specified string to UTF-16 bytes.

  • function String.UTF16.encodeUnsafe(str: usize, len: i32, buf: usize): usize
+

    Encodes the specified raw string to UTF-16 bytes. Returns the number of bytes written.

  • function String.UTF16.decode(buf: ArrayBuffer): string
+

    Decodes the specified buffer from UTF-16 bytes to a string.

  • function String.UTF16.decodeUnsafe(buf: usize, len: usize): string
+

    Decodes raw UTF-16 bytes to a string.

# Considerations

TL;DR: AssemblyScript does strings like JavaScript, but...

AssemblyScript strings purposely share their semantics with JavaScript strings, including that isolated surrogates can occur and are not eagerly sanitized. This is done for two reasons. First, as the Unicode Standard, Version 13.0 (opens new window) states in §2.7 Unicode Strings:

Depending on the programming environment, a Unicode string may or may not be required to be in the corresponding Unicode encoding form. For example, strings in Java, C#, or ECMAScript are Unicode 16-bit strings, but are not necessarily well-formed UTF-16 sequences. In normal processing, it can be far more efficient to allow such strings to contain code unit sequences that are not well-formed UTF-16—that is, isolated surrogates. Because strings are such a fundamental component of every program, checking for isolated surrogates in every operation that modifies strings can create significant overhead, especially because supplementary characters are extremely rare as a percentage of overall text in programs worldwide.

Second, sanitization is also not desirable in between AssemblyScript and JavaScript, or between two AssemblyScript modules, where it can be critical to maintain equality, inequality and hash integrity of idiomatic strings when function calls traverse JS<->AS or AS<->AS boundaries. It is common, for example, that an application is composed of both AssemblyScript and JavaScript code, or that an AssemblyScript module replaces a JavaScript module, and it is expected that two AssemblyScript modules can exchange strings, where sanitizing (mutating) strings eagerly would be unnecessary and dangerous. Also, ESM-integration aims to make JavaScript and WebAssembly modules interchangeable more broadly, which can only be achieved safely when maintaining compatibility.

Note that this stance differs from what the majority within the WebAssembly CG has decided (opens new window) for Interface Types and the Component Model, including its Web integration, regardless of our concerns (1 (opens new window), 2 (opens new window)), yet we believe that sanitization should only be performed where unavoidable, ideally as late as possible, matching what Web APIs do today (say right when calling an HTTP API but no earlier) to not impose unresolvable problems on the many popular languages already matching what JavaScript and the Web do. As such, we'd prefer if Interface Types and similar or related proposals revised their approach to follow WebIDL's precedent, where DOMString (opens new window) represents the concept and USVString (opens new window) is the special case. As WebIDL states:

When in doubt, use DOMString.

Of course we agree that USVString should be supported in some capacity to match what Rust and C++ do, but making it the only supported concept will not only break the other half of the ecosystem on a fundamental level, but also the Web platform as a whole, which is unnecessary and avoidable given that sanitization can easily be performed by an interface adapter only when needed.

+ ← + + Symbol + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/symbol.html b/stdlib/symbol.html new file mode 100644 index 000000000..7c0581fff --- /dev/null +++ b/stdlib/symbol.html @@ -0,0 +1,89 @@ + + + + + + Symbol | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Symbol

A primitive data type representing a unique global symbol.

The symbol type is very similar to JavaScript's (MDN (opens new window)), but is not deeply integrated with the compiler yet.

# Construction

  • function Symbol(description?: string): symbol
+
    Creates a new unique symbol. Note that this is not a constructor (symbols are primitive data types) so cannot be invoked with new.

# Static members

  • function for(key: string): symbol
+

    Obtains the existing unique symbol for the specified global key or creates a new unique symbol if the key does not exist.

  • function keyFor(sym: symbol): string | null
+

    Obtains the global key of the specified unique symbol, if any.

# Instance members

  • function toString(): string
+
    Returns a string representation of the symbol of the form "Symbol(key?)".

+ ← + + TypedArray + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/stdlib/typedarray.html b/stdlib/typedarray.html new file mode 100644 index 000000000..40badc2ee --- /dev/null +++ b/stdlib/typedarray.html @@ -0,0 +1,114 @@ + + + + + + TypedArray | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# TypedArray

An Array-like view on a raw binary buffer.

The TypedArray API works very much like JavaScript's (MDN (opens new window)). The name TypedArray below represents one of the variants of element type T and is not an actual class. Note that typed arrays are not actually generic, but concrete implementations like Uint8Array and Float64Array have an identical interface that only differs in the implementation's element type denoted as T.

# Variants

Variant Element type Description
Int8Array i8 A view on 8-bit signed integer values.
Int16Array i16 A view on 16-bit signed integer values.
Int32Array i32 A view on 32-bit signed integer values.
Int64Array i64 A view on 64-bit signed integer values.
Uint8Array u8 A view on 8-bit unsigned integer values.
Uint8ClampedArray u8 A view on 8-bit unsigned integer values,
with set values clamped between 0 and 255 inclusive.
Uint16Array u16 A view on 16-bit unsigned integer values.
Uint32Array u32 A view on 32-bit unsigned integer values.
Uint64Array u64 A view on 64-bit unsigned integer values.
Float32Array f32 A view on 32-bit float values.
Float64Array f64 A view on 64-bit float values.

# Constructor

  • new TypedArray(length: i32)
+
    Constructs a new typed array view with a new backing buffer and all values initialized to zero. See wrap below for wrapping a raw buffer.

# Static members

  • const BYTES_PER_ELEMENT: usize
+

    Number of bytes per element.

  • function wrap(buffer: ArrayBuffer, byteOffset?: i32, length?: i32): TypedArray
+

    Wraps a raw buffer to be viewed as a sequence of values of the typed array's value type. This is equivalent to the respective alternative constructor signature in JS but exists because there is no function overloading (yet).

# Instance members

# Fields

  • readonly buffer: ArrayBuffer
+

    The backing array buffer of this view.

  • readonly byteOffset: i32
+

    The offset in bytes from the start of the backing buffer.

  • readonly byteLength: i32
+

    The length in bytes from the start of the backing buffer.

  • readonly length: i32
+

    The length in elements.

# Methods

  • function every(fn: (value: T, index: i32, self: TypedArray) => bool): bool
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns false. Returns true if all functions returned true or the array is empty, otherwise false.

  • function fill(value: T, start?: i32, end?: i32): this
+

    Replaces the values of the array from start inclusive to end exclusive in place with the specified value, returning the array.

  • function findIndex(fn: (value: T, index: i32, self: TypedArray) => bool): i32
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

  • function findLastIndex(fn: (value: T, index: i32, self: TypedArray) => bool): i32
+

    Calls the specified function with every value of the array starting at the end until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

  • function forEach(fn: (value: T, index: i32, self: TypedArray) => void): void
+

    Calls the specified function with every value of the array.

  • function includes(value: T, fromIndex?: i32): bool
+

    Tests if the array includes the specified value, optionally providing a starting index.

  • function indexOf(value: T, fromIndex?: i32): i32
+

    Gets the first index where the specified value can be found in the array. Returns -1 if not found.

  • function lastIndexOf(value: T, fromIndex?: i32): i32
+

    Gets the last index where the specified value can be found in the array. Returns -1 if not found.

  • function map(fn: (value: T, index: i32, self: TypedArray) => T): TypedArray
+

    Calls the specified function with every value of the array, returning a new array of the function's return values.

  • function reduce<U>(
+  fn: (accumValue: U, currentValue T, index: i32, self: TypedArray) => U,
+  initialValue: U
+): U
+

    Calls the specified reducer function with each value of the array, resulting in a single return value. The respective previous reducer function's return value is remembered in accumValue, starting with initialValue, becoming the final return value in the process.

  • function reduceRight<U>(
+  fn: (accumValue: U, currentValue: T, index: i32, self: TypedArray) => U,
+  initialValue: U
+): U
+

    Calls the specified reducer function with each value of the array, from right to left, resulting in a single return value.

  • function reverse(): this
+

    Reverses an array's values in place, modifying the array before returning it.

  • function set(source: ArrayLike<number>, offset?: i32): void
+

    Sets the typed array values (starting at offset, or 0), reading input values from a specified source array.

  • function some(fn: (value: T, index: i32, self: TypedArray) => bool): bool
+

    Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning true. Returns false otherwise or if the array is empty.

  • function sort(fn: (a: T, b: T) => i32): this
+

    Sorts the values of the array in place, using the specified comparator function, modifying the array before returning it. The comparator returning a negative value means a < b, a positive value means a > b and 0 means that both are equal. Unlike in JavaScript, where an implicit conversion to strings is performed, the comparator defaults to compare two values of type T.

  • function subarray(start?: i32, end?: i32): TypedArray
+

    Returns a new view on the array's backing buffer from begin inclusive to end exclusive relative to this array. If omitted, end defaults to the end of the array. Does not copy.

+ ← + + Implementation status + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + + diff --git a/transforms.html b/transforms.html new file mode 100644 index 000000000..599aa201a --- /dev/null +++ b/transforms.html @@ -0,0 +1,43 @@ + + + + + + +

+ Redirect after 3s +

+

+ Powered by vuepress-plugin-redirect +

+ + + \ No newline at end of file diff --git a/types.html b/types.html new file mode 100644 index 000000000..4a718f0cb --- /dev/null +++ b/types.html @@ -0,0 +1,128 @@ + + + + + + Types | The AssemblyScript Book + + + + + + + + + + + + + + + + + + +
The AssemblyScript Book

# Types

AssemblyScript inherits WebAssembly's more specific integer, floating point and reference types:

AssemblyScript Type WebAssembly type TypeScript type Description
Integer types
i32 i32 number A 32-bit signed integer.
u32 i32 number A 32-bit unsigned integer.
i64 i64 bigint A 64-bit signed integer.
u64 i64 bigint A 64-bit unsigned integer.
isize i32 or i64 number or bigint A 32-bit signed integer in WASM32.
A 64-bit signed integer in WASM64 🦄.
usize i32 or i64 number or bigint A 32-bit unsigned integer in WASM32.
A 64-bit unsigned integer in WASM64 🦄.
Floating point types
f32 f32 number A 32-bit float.
f64 f64 number A 64-bit float.
Small integer types
i8 i32 number An 8-bit signed integer.
u8 i32 number An 8-bit unsigned integer.
i16 i32 number A 16-bit signed integer.
u16 i32 number A 16-bit unsigned integer.
bool i32 boolean A 1-bit unsigned integer.
Vector types
v128 v128 - A 128-bit vector.
Reference / GC types
ref_extern (ref extern) Object An external reference.
ref_func (ref func) Function A function reference.
ref_any (ref any) Object An internal reference. 🦄
ref_eq (ref eq) Object An equatable reference. 🦄
ref_struct (ref struct) Object A data reference. 🦄
ref_array (ref array) Array An array reference. 🦄
ref_string (ref string) string A string reference. 🦄
ref_stringview_wtf8 (ref stringview_wtf8) - A WTF-8 string view reference. 🦄
ref_stringview_wtf16 (ref stringview_wtf16) string A WTF-16 string view reference. 🦄
ref_stringview_iter (ref stringview_iter) - A string iterator reference. 🦄
Special types
void - void Indicates no return value.

Note

The base reference types above are non-nullable. Canonical aliases, as per the spec, are available as well and refer to the respective nullable type, e.g. type externref = ref_extern | null mapping to externref == (ref null extern) in Wasm. The ref_ prefix avoids naming collisions for the time being and might be dropped in the future.

Just like in TypeScript, types are annotated after variable, function argument or class member names, separated by :, like so:

function add(a: i32, b: i32): i32 {
+  let sum: i32 = a + b; // type can be inferred, annotation can be omitted
+  return sum;
+}
+

# Type rules

The compiler will complain when it sees an implicit conversion that might not actually be intended, quite similar to what a C compiler would do.

# Casting

In AssemblyScript, the type assertions <T>expression and expression as T known from TypeScript become explicit type conversions, essentially telling the compiler that the conversion is intended. In addition, each of the type names mentioned above, except aliases, also act as portable conversion built-ins that can be used just like i32(expression). Using portable conversions is especially useful where the exact same code is meant to be compiled to JavaScript with the TypeScript compiler (see), that otherwise would require the insertion of asm.js-style type coercions like expression | 0.

# Inference

Compared to TypeScript, type inference in AssemblyScript is limited because the type of each expression must be known in advance. This means that variable and parameter declarations must either have their type annotated or have an initializer. Without a type annotation and only an initializer, AssemblyScript will assume i32 at first and only reconsider another type if the value doesn't fit (becomes i64), is a float (becomes f64) or irrefutably has another type than these, like the type of a variable, the return type of a function or a class type. Furthermore, functions must be annotated with a return type to help the compiler make the correct decisions, for example where a literal is returned or multiple return statements are present.

# Nullability

Basic types cannot be nullable, but class and function types can. Appending | null declares a nullable type.

# Assignability

Assigning a value of one type to a target of another type can be performed without explicit casts where the full range of possible values can be represented in the target type, regardless of interpretation/signedness:

↱ bool i8/u8 i16/u16 i32/u32 i64/u64 f32 f64
bool ✓ ✓ ✓ ✓ ✓ ✓ ✓
i8/u8 ✓ ✓ ✓ ✓ ✓ ✓
i16/u16 ✓ ✓ ✓ ✓ ✓
i32/u32 ✓ ✓ ✓
i64/u64 ✓
f32 ✓ ✓
f64 ✓

Note that isize and usize are aliases of either i32 and u32 in WASM32 respectively i64 and u64 in WASM64 🦄.

var  i8val: i8  = -128  // 0x80
+var  u8val: u8  = i8val // becomes 128 (0x80)
+var i16val: i16 = i8val // becomes -128 through sign-extension (0xFF80)
+var u16val: u16 = i8val // becomes 65408 through masking (0xFF80)
+var f32val: f32 = i8val // becomes -128.0
+

Wasm reference and GC types are anticipated to adhere to the following hierarchy 🦄:

Diagram of anticipated reference types hierarchy.

Dashed elements are not exposed and/or unclear. (...)-placeholders indicate the concrete subtypes, e.g. an array of a specific element type, a struct with specific field types and potentially a supertype, or a function with specific parameter and return types. For details, see Wasm GC's subtyping rules (opens new window).

# Comparability

Comparing two values of different types can be performed without an explicit cast under the same rules as outlined in assignability above

  1. if the comparison is absolute (== or ===, != or !==)
  2. if the comparison is relative (>, <, >=, <=) and both types have the same signedness

because WebAssembly has distinct operations for signed and unsigned comparisons. The comparison uses the larger type and returns bool.

Note that == and === respectively != and !== are the same in AssemblyScript because comparing two values of different types is invalid under its strict typing rules anyhow.

# Bit shifts

The result of a bit shift (<<, >>) is the left type, with the right type implicitly converted to the left type, performing an arithmetic shift if the left type is signed and a logical shift if the left type is unsigned.

The result of an unsigned right shift (>>>) is the left type (signedness is retained), with the right type implicitly converted to the left type, but always performing a logical shift.

Note that only the log2(sizeof<T>()) least significant bits of the shift affect the result:

Type Significant bits Example
i8 / u8 3 x << y ≡ x << (y & 7)
i16 / u16 4 x << y ≡ x << (y & 15)
i32 / u32 5 x << y ≡ x << (y & 31)
i64 / u64 6 x << y ≡ x << (y & 63)

If the left type is a float, an error is emitted.

# Macro types

The following macro types provide access to related types that would otherwise be impossible to obtain.

Macro type Description
native<T> Obtains the underlying native type of T, e.g. u32 if T is a class (in WASM32).
indexof<T> Obtains the index type of a collection based on the indexed access overload.
valueof<T> Obtains the value type of a collection based on the indexed access overload.
returnof<T> Obtains the return type of a function type.

# Range limits

Various range limits specific to the WebAssembly types are present as global constants for convenience:

  • const i8.MIN_VALUE: i8 = -128
+const i8.MAX_VALUE: i8 = 127
+
  • const i16.MIN_VALUE: i16 = -32768
+const i16.MAX_VALUE: i16 = 32767
+
  • const i32.MIN_VALUE: i32 = -2147483648
+const i32.MAX_VALUE: i32 = 2147483647
+
  • const i64.MIN_VALUE: i64 = -9223372036854775808
+const i64.MAX_VALUE: i64 = 9223372036854775807
+
  • const isize.MIN_VALUE: isize // WASM32: i32.MIN_VALUE, WASM64: i64.MIN_VALUE
+const isize.MAX_VALUE: isize // WASM32: i32.MAX_VALUE, WASM64: i64.MAX_VALUE
+
  • const u8.MIN_VALUE: u8 = 0
+const u8.MAX_VALUE: u8 = 255
+
  • const u16.MIN_VALUE: u16 = 0
+const u16.MAX_VALUE: u16 = 65535
+
  • const u32.MIN_VALUE: u32 = 0
+const u32.MAX_VALUE: u32 = 4294967295
+
  • const u64.MIN_VALUE: u64 = 0
+const u64.MAX_VALUE: u64 = 18446744073709551615
+
  • const usize.MIN_VALUE: usize = 0
+const usize.MAX_VALUE: usize // WASM32: u32.MAX_VALUE, WASM64: u64.MAX_VALUE
+
  • const bool.MIN_VALUE: bool = 0
+const bool.MAX_VALUE: bool = 1
+
  • const f32.MIN_VALUE: f32 = -3.40282347e+38
+const f32.MAX_VALUE: f32 = 3.40282347e+38
+const f32.MIN_NORMAL_VALUE: f32 = 1.17549435e-38
+const f32.MIN_SAFE_INTEGER: f32 = -16777215
+const f32.MAX_SAFE_INTEGER: f32 = 16777215
+const f32.EPSILON: f32 = 1.19209290e-07
+
  • const f64.MIN_VALUE: f64 = -1.7976931348623157e+308
+const f64.MAX_VALUE: f64 = 1.7976931348623157e+308
+const f64.MIN_NORMAL_VALUE: f64 = 2.2250738585072014e-308
+const f64.MIN_SAFE_INTEGER: f64 = -9007199254740991
+const f64.MAX_SAFE_INTEGER: f64 = 9007199254740991
+const f64.EPSILON: f64 = 2.2204460492503131e-16
+

+ ← + + Globals + + → +

Apache-2.0 licensed, + Copyright © 2020-2024 The AssemblyScript Authors

+ + +