opal 1.2.0.beta1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a574a86358acd4f97b91deecaa9395068503a2198c6a8b646ee5b9df35a8d5c
-  data.tar.gz: 800255837fc95ecbfa4268c4a4b21df99ad1fb427fe4b90a5100bbed75833791
+  metadata.gz: 0b7a4b076832e2c4f5cf807f40bf1a9d7e1a0328e1ef4b245f1514ae2ff145dd
+  data.tar.gz: 5df94eda8d910641c918d913b7421796b5e513b05600e51d1debd0cd3944cf20
 SHA512:
-  metadata.gz: 471561bdda1f595110d95be228b6caad444b0064e84b13d37c250c70b1e505e897c6f9f69c93afa11b13a268b98acef4d62508ba19ac1304d3c5d8178563b10f
-  data.tar.gz: 4620c4fc0ee08df1840300b1b03fe3cedabee19dc22c986b7151538b211da69046c4b164c8bd4145c16e4d54307376314a4514b9b95fb540fc0e37fdb8671511
+  metadata.gz: 04050f1589cf7ee4a3be39907e4618434659157968b63f225c6ae27a46da5f9e77c57080ca0c741aa333c3a3e48e2bbe38a3719f8540e55aefe26a3b6c4d3710
+  data.tar.gz: 867a69aa3810572ff1636f4b6dc0df14435fa54dc06655101dde8017e71ab1892393e5a61517194f4828d596301097876e36734d9c4039f2d2109c70a011a3cb

data/.eslintrc.await.js

@@ -0,0 +1,6 @@
+module.exports = {
+  "extends": "./.eslintrc.js",
+  "parserOptions": {
+    "ecmaVersion": 8
+  },
+};

data/.eslintrc.js

@@ -0,0 +1,34 @@
+module.exports = {
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": 3
+  },
+  "rules": {
+    "no-unused-vars": ["error", {
+      "varsIgnorePattern": "(\$(\$|\$\$|yield|post_args|[a-z])|self)",
+      "argsIgnorePattern": "(\$(\$|\$\$|yield|post_args|[a-z])|self)",
+    }],
+    "no-extra-semi": "off",
+    "no-empty": "off",
+    "no-unreachable": "off",
+    "no-cond-assign": "off",
+    "no-prototype-builtins": "off",
+    "no-constant-condition": ["error", { "checkLoops": false }],
+    "no-useless-escape": "off",
+    "no-fallthrough": ["error", { "commentPattern": "raise|no-break" }],
+    "no-regex-spaces": "off",
+    "no-control-regex": "off",
+  },
+  "globals": {
+    "Opal": "readonly",
+    "DataView": "readonly",
+    "ArrayBuffer": "readonly",
+    "globalThis": "readonly",
+    "Uint8Array": "readonly",
+    "Promise": "readonly",
+  }
+};

data/.github/workflows/build.yml

@@ -49,6 +49,12 @@ jobs:
             ruby: 3.0
           - name: timezone
             ruby: 3.0
+          - name: performance
+            ruby: 3.0
+            permissive: true
+            fetchdepth: '0'
+            command: bin/rake performance:compare
+            os: ryzen
 
           # Currently failing:
           # - ruby: truffleruby
@@ -56,9 +62,13 @@ jobs:
           # - ruby: ruby-head
 
     runs-on: ${{ matrix.combo.os || 'ubuntu-latest' }}
+    continue-on-error: ${{ matrix.combo.permissive || false }}
     steps:
       - uses: actions/checkout@v2
-      - uses: ruby/setup-ruby@v1
+        with:
+          fetch-depth: ${{ fromJSON(matrix.combo.fetchdepth || '1') }}
+      - if: ${{ matrix.combo.os != 'ryzen' }}
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.combo.ruby }}
           # NOTE: Bundler 2.2.0 fails to install libv8

data/.rubocop.yml

@@ -71,6 +71,7 @@ Layout/CommentIndentation:
   Exclude:
     - 'lib/opal/rewriters/binary_operator_assignment.rb'
     - 'lib/opal/rewriters/logical_operator_assignment.rb'
+    - 'lib/opal/source_map/file.rb'
 
 # We need to support older rubies
 Layout/IndentHeredoc:
@@ -92,6 +93,7 @@ Style/GlobalVars:
     - 'stdlib/nodejs/irb.rb'
     - 'stdlib/console.rb'
     - 'stdlib/native.rb'
+    - 'stdlib/await.rb'
 
 Layout/ExtraSpacing:
   Exclude:
@@ -107,8 +109,9 @@ Layout/SpaceAroundOperators:
 
 Lint/BooleanSymbol:
   Exclude:
-    # There are AST nodes with types :true and :false
+    # There are AST nodes and rewriters with types :true and :false
     - 'lib/opal/nodes/**/*.rb'
+    - 'lib/opal/rewriters/**/*.rb'
 
 Lint/InheritException:
   Exclude:
@@ -123,6 +126,11 @@ Lint/LiteralAsCondition:
     - 'opal/**/*.rb'
     - 'stdlib/**/*.rb'
 
+Lint/Loop:
+  Exclude:
+    # This is for optimization purposes mostly
+    - 'opal/corelib/io.rb'
+
 # Allow the use of if/unless inside blocks
 Style/Next:
   Enabled: false
@@ -133,6 +141,7 @@ Lint/RescueException:
     - 'opal/corelib/enumerator.rb'
     # Promises must care about all exceptions
     - 'stdlib/promise.rb'
+    - 'opal/corelib/binding.rb'
 
 Lint/StringConversionInInterpolation:
   Exclude:
@@ -411,6 +420,7 @@ Style/ConditionalAssignment:
 Naming/MemoizedInstanceVariableName:
   Exclude:
     - lib/opal/parser/patch.rb # it's a monkey-patch on the parser gem
+    - lib/opal/nodes/rescue.rb # we know what we are doing here and no, it's not memoization
 
 Style/AccessModifierDeclarations:
   Enabled: false

data/CHANGELOG.md

@@ -15,6 +15,170 @@ Changes are grouped as follows:
 
 
 
+## [1.3.0](https://github.com/opal/opal/compare/v1.2.0...v1.3.0) - 2021-10-27
+
+
+### Added
+
+- Add support for `retry` ([#2264](https://github.com/opal/opal/pull/2264))
+- Modernize Exceptions ([#2264](https://github.com/opal/opal/pull/2264))
+  - Add `#cause`, `#backtrace_locations`, `#full_message` to `Exception`
+  - Normalize backtraces across platforms
+  - Add `Thread::Backtrace::Location`
+  - Output Exception#full_message on uncaught exceptions ([#2269](https://github.com/opal/opal/pull/2269))
+- TracePoint `:class` support ([#2049](https://github.com/opal/opal/pull/2049))
+- Implement the Flip-Flop operators ([#2261](https://github.com/opal/opal/pull/2261))
+- Add `JS[]` to access properties on the global object ([#2259](https://github.com/opal/opal/pull/2259))
+- Add `ENV.fetch` to the Nodejs implementation of `ENV` ([#2259](https://github.com/opal/opal/pull/2259))
+- Opal::Cache, an optional compiler cache (enabled by default) (#2242, #2278, #2329)
+- Alias for gvars, alias on main ([#2270](https://github.com/opal/opal/pull/2270))
+- Support for GJS (GNOME's JavaScript runtime) runner ([#2280](https://github.com/opal/opal/pull/2280))
+- Scope variables support for `eval()` ([#2256](https://github.com/opal/opal/pull/2256))
+- Add support for `Kernel#binding` ([#2256](https://github.com/opal/opal/pull/2256))
+- A (mostly) correct support for refinements ([#2256](https://github.com/opal/opal/pull/2256))
+- Add support for ECMAScript modules with an `--esm` CLI option ([#2286](https://github.com/opal/opal/pull/2286))
+- Implement `Regexp#names` and add named captures support ([#2272](https://github.com/opal/opal/pull/2272))
+- REPL improvements: ([#2285](https://github.com/opal/opal/pull/2285))
+  - Colored output & history support
+  - `ls` to show available constants and variable
+- Add `Method#===` as an alias to `Method#call`, works the same as `Proc#===` ([#2305](https://github.com/opal/opal/pull/2305))
+- Add `IO#gets` and `IO#read_proc` along with other supporting methods ([#2309](https://github.com/opal/opal/pull/2309))
+  - Support `#gets` on most platforms, including browsers (via `prompt`)
+  - Move the REPL to a `--repl` CLI option of the main executable
+  - Completely refactor IO, now supporting methods like `#each_line` throughout the entire IO chain
+  - Add a runner for MiniRacer (as `miniracer`)
+  - Support Windows on the Chrome runner
+  - Support Windows on the REPL
+  - Platforms an IO implementations should either set `IO#read_proc` or overwrite `IO#sysread`
+- [experimental] Add support for JavaScript async/await ([#2221](https://github.com/opal/opal/pull/2221))
+  - Enable the feature by adding a magic comment: `# await: true`
+  - The magic comment can be also used to mark specific method patterns to be awaited
+    (e.g. `# await: *_await, sleep` will make any method ending in `_await` or named `sleep` to be awaited)
+  - Add `Kernel#__await__` as a bridge to the `await` keyword (inspired by CoffeeScript await support)
+  - Require `opal/await` to get additional support
+  - Read more on the newly added documentation page
+- Better interoperability between legacy Promise (v1) and native Promise (v2) ([#2221](https://github.com/opal/opal/pull/2221))
+  - Add `PromiseV1` as an alias to the original (legacy) Promise class
+  - Add `#to_v1` and `#to_v2` to both classes
+  - `Promise#to_n` will convert it to a native Promise (v2)
+- Add `Opal::Config.esm` to enable/disable ES modules ([#2316](https://github.com/opal/opal/pull/2316))
+  - If Config.esm is enabled, SimpleServer does type="module"
+  - Add new rack-esm example
+- Add a QuickJS (https://bellard.org/quickjs/) runner ([#2331](https://github.com/opal/opal/pull/2331))
+- Add `IO#fileno`, `Method#curry`, `Buffer#to_s`, `Pathname.pwd` ([#2332](https://github.com/opal/opal/pull/2332))
+- Add NodeJS support for `ARGF`, `ENV.{inspect,to_h,to_hash,merge}`, `File.{delete,unlink}`, `Kernel#system`, <code>Kernel#\`</code>, `Process::Status` ([#2332](https://github.com/opal/opal/pull/2332))
+- Introduce `__dir__` support ([#2323](https://github.com/opal/opal/pull/2323))
+- Full autoload support ([#2323](https://github.com/opal/opal/pull/2323))
+  - Now compatible with `opal-zeitwerk` and `isomorfeus`
+  - Allow toplevel autoloads
+  - Allow dynamic autoloads (e.g. can be hooked to fetch a URL upon autoload with a custom loader)
+  - Allow overwriting `require` (e.g. like rubygems does)
+  - Allow autoloading trees with `require_tree "./foo", autoload: true`
+  - Add Module#autoload?
+- Autoload parts of the corelib ([#2323](https://github.com/opal/opal/pull/2323))
+
+### Fixed
+
+- Fixed multiple line `Regexp` literal to not generate invalid syntax as JavaScript ([#1616](https://github.com/opal/opal/pull/1616))
+- Fix `Kernel#{try,catch}` along with `UncaughtThrowError` ([#2264](https://github.com/opal/opal/pull/2264))
+- Update source-map-support to fix an off-by-one error ([#2264](https://github.com/opal/opal/pull/2264))
+- Source map: lines should start from 1, not 0 ([#2273](https://github.com/opal/opal/pull/2273))
+- Allow for multiple underscored args with the same name in strict mode ([#2292](https://github.com/opal/opal/pull/2292))
+- Show instance variables in `Kernel#inspect` ([#2285](https://github.com/opal/opal/pull/2285))
+- `0.digits` was returning an empty array in strict mode ([#2301](https://github.com/opal/opal/pull/2301))
+- Non Integer numbers were responding to `#digits` ([#2301](https://github.com/opal/opal/pull/2301))
+- Correctly delete hash members when dealing with boxed strings ([#2306](https://github.com/opal/opal/pull/2306))
+- Escape string components in interpolated strings (`dstrs`) correctly ([#2308](https://github.com/opal/opal/pull/2308))
+- Don't try to return the JS `debugger` statement, just return `nil` ([#2307](https://github.com/opal/opal/pull/2307))
+- Retain the `-` while stringifying `-0.0` ([#2304](https://github.com/opal/opal/pull/2304))
+- Fix super support for rest args and re-assignments with implicit arguments ([#2315](https://github.com/opal/opal/pull/2315))
+- Fix calling `Regexp#last_match` when `$~` is nil ([#2328](https://github.com/opal/opal/pull/2328))
+- Windows support for chrome runner ([#2324](https://github.com/opal/opal/pull/2324))
+  - Use correct node separator for NODE_PATH on Windows
+  - Pass dir and emulate exec a bit on Windows
+  - Use Gem.win_platform?, match supported platform to ruby, simplify run
+- NodeJS: Drop the first `--` argument in `ARGV` ([#2332](https://github.com/opal/opal/pull/2332))
+- Fix `Object#require` not pointing to `Kernel#require` ([#2323](https://github.com/opal/opal/pull/2323))
+
+### Changed
+
+- Fast-track bad constant names passed to `Struct.new` ([#2259](https://github.com/opal/opal/pull/2259))
+- Renamed internal `super` related helpers,
+  `find_super_dispatcher` is now `find_super`, `find_iter_super_dispatcher` is now `find_block_super` ([#2090](https://github.com/opal/opal/pull/2090))
+- The `opal-repl` CLI now requires files to be passed with `--require` (or `-r`) instead of the bare filename ([#2309](https://github.com/opal/opal/pull/2309))
+- `Process` is now a Module, not a Class - just like in MRI ([#2332](https://github.com/opal/opal/pull/2332))
+- `s = StringIO.new("a"); s << "b"; s.string` now returns "b", like MRI, but Opal used to return "ab" ([#2309](https://github.com/opal/opal/pull/2309))
+
+### Deprecated
+
+### Removed
+
+### Internal
+
+- Switch from jshint to ESLint ([#2289](https://github.com/opal/opal/pull/2289))
+- Switch from UglifyJS to Terser ([#2318](https://github.com/opal/opal/pull/2318))
+- [CI] Performance regression check (#2276, #2282)
+
+
+
+
+## [1.2.0](https://github.com/opal/opal/compare/v1.1.1...v1.2.0) - 2021-07-28
+
+
+### Added
+
+- Support for multiple arguments in Hash#{merge, merge!, update} ([#2187](https://github.com/opal/opal/pull/2187))
+- Support for Ruby 3.0 forward arguments: `def a(...) puts(...) end` ([#2153](https://github.com/opal/opal/pull/2153))
+- Support for beginless and endless ranges: `(1..)`, `(..1)` ([#2150](https://github.com/opal/opal/pull/2150))
+- Preliminary support for `**nil` argument - see #2240 to note limitations ([#2152](https://github.com/opal/opal/pull/2152))
+- Support for `Random::Formatters` which add methods `#{hex,base64,urlsafe_base64,uuid,random_float,random_number,alphanumeric}` to `Random` and `SecureRandom` ([#2218](https://github.com/opal/opal/pull/2218))
+- Basic support for ObjectSpace finalizers and ObjectSpace::WeakMap ([#2247](https://github.com/opal/opal/pull/2247))
+- A more robust support for encodings (especially binary strings) ([#2235](https://github.com/opal/opal/pull/2235))
+- Support for `"\x80"` syntax in String literals ([#2235](https://github.com/opal/opal/pull/2235))
+- Added `String#+@`, `String#-@` ([#2235](https://github.com/opal/opal/pull/2235))
+- Support for `begin <CODE> end while <CONDITION>` ([#2255](https://github.com/opal/opal/pull/2255))
+- Added Hash#except and `Hash#except!` ([#2243](https://github.com/opal/opal/pull/2243))
+- Parser 3.0: Implement pattern matching (as part of this `{Array,Hash,Struct}#{deconstruct,deconstruct_keys} methods were added)` ([#2243](https://github.com/opal/opal/pull/2243))
+- [experimental] Reimplement Promise to make it bridged with JS native Promise, this new implementation can be used by requiring `promise/v2` ([#2220](https://github.com/opal/opal/pull/2220))
+
+### Fixed
+
+- Encoding lookup was working only with uppercase names, not giving any errors for wrong ones (#2181, #2183, #2190)
+- Fix `Number#to_i` with huge number ([#2191](https://github.com/opal/opal/pull/2191))
+- Add regexp support to `String#start_with` ([#2198](https://github.com/opal/opal/pull/2198))
+- `String#bytes` now works in strict mode ([#2194](https://github.com/opal/opal/pull/2194))
+- Fix nested module inclusion ([#2053](https://github.com/opal/opal/pull/2053))
+- SecureRandom is now cryptographically secure on most platforms (#2218, #2170)
+- Fix performance regression for `Array#unshift` on v8 > 7.1 ([#2116](https://github.com/opal/opal/pull/2116))
+- String subclasses now call `#initialize` with multiple arguments correctly (with a limitation caused by the String immutability issue, that a source string must be the first argument and `#initialize` can't change its value) (#2238, #2185)
+- Number#step is moved to Numeric ([#2100](https://github.com/opal/opal/pull/2100))
+- Fix class Class < superclass for invalid superclasses ([#2123](https://github.com/opal/opal/pull/2123))
+- Fix `String#unpack("U*")` on binary strings with latin1 high characters, fix performance regression on that call (#2235, #2189, #2129, #2099, #2094, #2000, #2128)
+- Fix `String#to_json` output on some edge cases ([#2235](https://github.com/opal/opal/pull/2235))
+- Rework class variables to support inheritance correctly ([#2251](https://github.com/opal/opal/pull/2251))
+- ISO-8859-1 and US-ASCII encodings are now separated as in MRI ([#2235](https://github.com/opal/opal/pull/2235))
+- `String#b` no longer modifies object strings in-place ([#2235](https://github.com/opal/opal/pull/2235))
+- Parser::Builder::Default.check_lvar_name patch ([#2195](https://github.com/opal/opal/pull/2195))
+
+### Changed
+
+- `String#unpack`, `Array#pack`, `String#chars`, `String#length`, `Number#chr`, and (only partially) `String#+` are now encoding aware ([#2235](https://github.com/opal/opal/pull/2235))
+- `String#inspect` now uses `\x` for binary stirngs ([#2235](https://github.com/opal/opal/pull/2235))
+- `if RUBY_ENGINE == "opal"` and friends are now outputing less JS code (#2159, #1965)
+- `Array`: `to_a`, `slice`/`[]`, `uniq`, `*`, `difference`/`-`, `intersection`/`&`, `union`/`|`, flatten now return Array, not a subclass, as Ruby 3.0 does ([#2237](https://github.com/opal/opal/pull/2237))
+- `Array`: `difference`, `intersection`, `union` now accept multiple arguments ([#2237](https://github.com/opal/opal/pull/2237))
+
+### Deprecated
+
+- Stopped testing Opal on Ruby 2.5 since it reached EOL.
+
+### Removed
+
+- Removed support for the outdated `c_lexer`, it was optional and didn't work for the last few releases of parser ([#2235](https://github.com/opal/opal/pull/2235))
+
+
+
+
 ## [1.1.1](https://github.com/opal/opal/compare/v1.1.0...v1.1.1) - 2021-02-23
 
 

data/README.md

@@ -116,7 +116,7 @@ your web applications.
 <html>
   <head>
     <meta charset="utf-8">
-    <script src="https://cdn.opalrb.com/opal/current/opal.js" onload="Opal.load('opal')"></script>
+    <script src="https://cdn.opalrb.com/opal/current/opal.js"></script>
     <script src="https://cdn.opalrb.com/opal/current/opal-parser.js" onload="Opal.load('opal-parser')"></script>
 
     <script type="text/ruby">

data/Rakefile

@@ -7,5 +7,6 @@ import 'tasks/building.rake'
 import 'tasks/linting.rake'
 import 'tasks/benchmarking.rake'
 import 'tasks/releasing.rake'
+import 'tasks/performance.rake'
 
 task :default => [:rspec, :mspec, :minitest]

data/UNRELEASED.md

@@ -1,46 +1,6 @@
 ### Added
-
-- Support for multiple arguments in Hash#{merge, merge!, update} (#2187)
-- Support for Ruby 3.0 forward arguments: `def a(...) puts(...) end` (#2153)
-- Support for beginless and endless ranges: `(1..)`, `(..1)` (#2150)
-- Preliminary support for `**nil` argument - see #2240 to note limitations (#2152)
-- Support for `Random::Formatters` which add methods `#{hex,base64,urlsafe_base64,uuid,random_float,random_number,alphanumeric}` to `Random` and `SecureRandom` (#2218)
-- Basic support for ObjectSpace finalizers and ObjectSpace::WeakMap (#2247)
-- A more robust support for encodings (especially binary strings) (#2235)
-- Support for `"\x80"` syntax in String literals (#2235)
-- Added `String#+@`, `String#-@` (#2235)
-- Support for `begin <CODE> end while <CONDITION>` (#2255)
-
 ### Fixed
-
-- Encoding lookup was working only with uppercase names, not giving any errors for wrong ones (#2181, #2183, #2190)
-- Fix `Number#to_i` with huge number (#2191)
-- Add regexp support to `String#start_with` (#2198)
-- `String#bytes` now works in strict mode (#2194)
-- Fix nested module inclusion (#2053)
-- SecureRandom is now cryptographically secure on most platforms (#2218, #2170)
-- Fix performance regression for `Array#unshift` on v8 > 7.1 (#2116)
-- String subclasses now call `#initialize` with multiple arguments correctly (with a limitation caused by the String immutability issue, that a source string must be the first argument and `#initialize` can't change its value) (#2238, #2185)
-- Number#step is moved to Numeric (#2100)
-- Fix class Class < superclass for invalid superclasses (#2123)
-- Fix `String#unpack("U*")` on binary strings with latin1 high characters, fix performance regression on that call (#2235, #2189, #2129, #2099, #2094, #2000, #2128)
-- Fix `String#to_json` output on some edge cases (#2235)
-- Rework class variables to support inheritance correctly (#2251)
-- ISO-8859-1 and US-ASCII encodings are now separated as in MRI (#2235)
-- `String#b` no longer modifies object strings in-place (#2235)
-
 ### Changed
-
-- `String#unpack`, `Array#pack`, `String#chars`, `String#length`, `Number#chr`, and (only partially) `String#+` are now encoding aware (#2235)
-- `String#inspect` now uses `\x` for binary stirngs (#2235)
-- `if RUBY_ENGINE == "opal"` and friends are now outputing less JS code (#2159, #1965)
-- `Array`: `to_a`, `slice`/`[]`, `uniq`, `*`, `difference`/`-`, `intersection`/`&`, `union`/`|`, flatten now return Array, not a subclass, as Ruby 3.0 does (#2237)
-- `Array`: `difference`, `intersection`, `union` now accept multiple arguments (#2237)
-
 ### Deprecated
-
-- Stopped testing Opal on Ruby 2.5 since it reached EOL.
-
 ### Removed
-
-- Removed support for the outdated `c_lexer`, it was optional and didn't work for the last few releases of parser (#2235)
+### Internal

data/docs/async.md

@@ -0,0 +1,109 @@
+# Asynchronous code (PromiseV2 / async / await)
+
+Please be aware that this functionality is marked as experimental and may change
+in the future.
+
+In order to disable the warnings that will be shown if you use those experimental
+features, add the following line before requiring `promise/v2` or `await` and after
+requiring `opal`.
+
+```ruby
+`Opal.config.experimental_features_severity = 'ignore'`
+```
+
+## PromiseV2
+
+In Opal 1.2 we introduced PromiseV2 which is to replace the default Promise in Opal 2.0
+(which will become PromiseV1). Right now it's experimental, but the interface of PromiseV1
+stay unchanged and will continue to be supported.
+
+It is imperative that during the transition period you either `require 'promise/v1'` or
+`require 'promise/v2'` and then use either `PromiseV1` or `PromiseV2`.
+
+If you write library code it's imperative that you don't require the promise itself, but
+detect if `PromiseV2` is defined and use the newer implementation, for instance using the
+following code:
+
+```ruby
+module MyLibrary
+  Promise = defined?(PromiseV2) ? PromiseV2 : ::Promise
+end
+```
+
+The difference between `PromiseV1` and `PromiseV2` is that `PromiseV1` is a pure-Ruby
+implementation of a Promise, while `PromiseV2` is reusing the JavaScript `Promise`. Both are
+incompatible with each other, but `PromiseV2` can be awaited (see below) and they translate
+1 to 1 to the JavaScript native `Promise` (they are bridged; you can directly return a
+`Promise` from JavaScript API without a need to translate it). The other difference is that
+`PromiseV2` always runs a `#then` block a tick later, while `PromiseV1` would could run it
+instantaneously.
+
+## Async/await
+
+In Opal 1.3 we implemented the CoffeeScript pattern of async/await. As of now, it's hidden
+behind a magic comment, but this behavior may change in the future.
+
+Example:
+
+```ruby
+# await: true
+
+require "await"
+
+def wait_5_seconds
+  puts "Let's wait 5 seconds..."
+  sleep(5).await
+  puts "Done!"
+end
+
+wait_5_seconds.__await__
+```
+
+It's important to understand what happens under the hood: every scope in which `#__await__` is
+encountered will become async, which means that it will return a Promise that will resolve
+to a value. This includes methods, blocks and the top scope. This means, that `#__await__` is
+infectious and you need to remember to `#__await__` everything along the way, otherwise
+a program will finish too early and the values may be incorrect.
+
+[You can take a look at how we ported Minitest to support asynchronous tests.](https://github.com/opal/opal/pull/2221/commits/8383c7b45a94fe4628778f429508b9c08c8948b0) Take note, that
+it was ported to use `#await` while the finally accepted version uses `#__await__`.
+
+It is certainly correct to `#__await__` any value, including non-Promises, for instance
+`5.__await__` will correctly resolve to `5` (except that it will make the scope an async
+function, with all the limitations described above).
+
+The `await` stdlib module includes a few useful functions, like async-aware `each_await`
+function and `sleep` that doesn't block the thread. It also includes a method `#await`
+which is an alias of `#itself` - it makes sense to auto-await that method.
+
+This approach is certainly incompatible with what Ruby does, but due to a dynamic nature
+of Ruby and a different model of JavaScript this was the least invasive way to catch up
+with the latest JavaScript trends and support `Promise` heavy APIs and asynchronous code.
+
+## Auto-await
+
+The magic comment also accepts a comma-separated list of methods to be automatically
+awaited. An individual value can contain a wildcard character `*`. For instance,
+those two blocks of code are equivalent:
+
+```ruby
+# await: true
+
+require "await"
+
+[1,2,3].each_await do |i|
+  p i
+  sleep(i).__await__
+end.__await__
+```
+
+```ruby
+# await: sleep, *await*
+
+require "await"
+
+[1,2,3].each_await do |i|
+  p i
+  sleep i
+end
+```

data/docs/roda-sprockets.md

@@ -22,8 +22,6 @@ require 'roda'
 class App < Roda
    plugin :sprockets, precompile: %w(application.js),
                       prefix: %w(app/),
-                      root: __dir__,
-                      public_path: 'public/',
                       opal: true,
                       debug: ENV['RACK_ENV'] != 'production'
    plugin :public

data/examples/rack/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 gem 'rack'
 gem 'opal', :path => '../../'
+gem 'puma'

data/examples/rack/Gemfile.lock

@@ -1,24 +1,28 @@
 PATH
   remote: ../..
   specs:
-    opal (1.0.0)
+    opal (1.3.0.dev)
       ast (>= 2.3.0)
-      parser (~> 2.6)
+      parser (~> 3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.0)
-    parser (2.6.4.1)
-      ast (~> 2.4.0)
-    rack (2.0.7)
+    ast (2.4.2)
+    nio4r (2.5.8)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    puma (5.5.0)
+      nio4r (~> 2.0)
+    rack (2.2.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   opal!
+  puma
   rack
 
 BUNDLED WITH
-   1.17.3
+   2.1.4

data/examples/rack-esm/.gitignore

@@ -0,0 +1 @@
+tmp

data/examples/rack-esm/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'rack'
+gem 'opal', :path => '../../'
+gem 'puma'

data/examples/rack-esm/app/application.rb

@@ -0,0 +1,27 @@
+require 'opal'
+require 'user'
+require 'opal/platform'
+
+module MyApp
+  class Application
+    def initialize
+      @user = User.new('Bob')
+    end
+
+    def title
+      "#{@user.name} is #{:not unless @user.authenticated?} authenticated"
+    end
+  end
+end
+
+$app = MyApp::Application.new
+
+require 'native'
+
+$$[:document][:title] = "#{$app.title}"
+
+bill = User.new('Bill')
+
+$$.alert "The user is named #{bill.name}."
+
+bill.authenticated?

data/examples/rack-esm/app/user.rb

@@ -0,0 +1,24 @@
+class User
+  def initialize(name)
+    puts "wow"
+    @name = name
+  end
+
+  attr_reader :name
+
+  def authenticated?
+    if admin? or special_permission?
+      true
+    else
+      raise "not authenticated"
+    end
+  end
+
+  def admin?
+    @name == 'Bob'
+  end
+
+  def special_permission?
+    false
+  end
+end

data/examples/rack-esm/config.ru

@@ -0,0 +1,25 @@
+require 'bundler'
+Bundler.require
+
+# Instructions: bundle in this directory
+# then run `bundle exec rackup` to start the server
+# and browse to http://localhost:9292
+
+# a very small application that just tries to authenticate a user and fails
+# it just writes to the console in the browser (no visible html)
+
+# with gems like opal-jquery or opal-browser you could manipulate the dom directly
+
+# the directory where the code is (add to opal load path )
+Opal.append_path 'app'
+
+# Enable ESM
+Opal::Config.esm = true
+
+run Opal::SimpleServer.new { |s|
+  # the name of the ruby file to load. To use more files they must be required from here (see app)
+  s.main = 'application'
+  # need to set the index explicitly for opal server to pick it up
+  s.index_path = 'index.html.erb'
+}
+

data/examples/rack-esm/index.html.erb

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>opal-sprockets demo</title>
+
+    <%= javascript_include_tag 'application' %>
+  </head>
+  <body>
+  </body>
+</html>