opal 1.5.1 → 1.6.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e07c91ee89f49091b5245745dc0889d8266c6c437349f6c0a5f31c99ab34e61
-  data.tar.gz: bef7cf7822bd78100f39044d4243a588d8a752541bb9af584c324b7d9b31ed79
+  metadata.gz: 799fb70bbdbc0be33af9c9757287797702fd8752f29e3beb4b3515f3dc0e7a66
+  data.tar.gz: 757ec0cb6cc3a5bb24e7a6e6e2aec81fa70d5f05f98025ee00528d00b0779d48
 SHA512:
-  metadata.gz: '05894c0ce50acfcda6bf2f333410639603c994ffdd56db7c892ae579601e7f739a13fb37b430e28048ae9ea84148956a5f3b37fc629506ccd11f913a1300cf7b'
-  data.tar.gz: deb8dfb2fecfb910d506a2707ad34a5306429debb693d4b54b61163195311807600b0b859db18e744669bdcfb4a07a610b31871050dbbb7df9f6dbf5ef712291
+  metadata.gz: f3024674d274a45c92bbb5094416074ef754802a78c0484a71d68a7b03815867a8ac42f8499e23a9f2d05587212afeafb752c0894cfabc4a6ace63faf0da4098
+  data.tar.gz: f1d8ec6f6ac95d89233d4af4a26ab4eaed8d275edd86b154dd06d6fea5477c9aa869dc644f571a2c95737bf674703f03db9b8bed7b43a8af322d5dad6e3a0516

data/.github/workflows/build.yml

@@ -8,6 +8,9 @@ on:
       - "*/ci-check"
   pull_request: {}
 
+permissions:
+  contents: read
+
 jobs:
   rake:
     name: ${{ matrix.combo.name || matrix.combo.ruby }}
@@ -58,7 +61,7 @@ jobs:
             permissive: true
             fetchdepth: '0'
             command: bin/rake performance:compare
-            os: ryzen
+            # os: ryzen
 
           # Currently failing:
           # - ruby: truffleruby

data/HACKING.md

@@ -185,6 +185,29 @@ Array#permutation_returns_an_Enumerator_which_works_as_expected_even_when_the_ar
 Array#permutation_generates_from_a_defensive_copy,_ignoring_mutations                                                         0.038
 ```
 
+### AsciiDoctor Benchmark and git branch performance comparison
+
+It is testing the performance for the real life application AsciiDoctor, compiling it, running it and asset size.
+It prints a nice summary to compare the current branch with the master branch.
+On Windows make sure to have the Ruby DevKit enabled with `ridk enable`.
+
+Run the task on any system with: `bundle exec rake performance:compare`
+
+Example output:
+```
+=== Summary ===
+Summary of performance changes between (previous) master and (current) v1.5.1-48-gc470e969:
+
+Comparison of V8 function optimization status:
+Dateien tmp/performance/optstatus_previous und tmp/performance/optstatus_current sind identisch.
+
+Comparison of the Asciidoctor (a real-life Opal application) compile and run:
+                  Compile time: 9.367 (±2.21%) -> 9.579 (±17.53%) (change: +2.26%)
+                      Run time: 2.049 (±9.25%) -> 2.147 (±19.70%) (change: +4.80%)
+                   Bundle size: 4740.27 kB -> 4740.27 kB (change: +0.00%)
+          Minified bundle size: 995.10 kB -> 995.10 kB (change: +0.00%)
+            Mangled & minified: 706.32 kB -> 706.32 kB (change: +0.00%)
+```
 
 ## Parser
 

data/UNRELEASED.md

@@ -7,3 +7,45 @@
 ### Performance
 ### Fixed
 -->
+
+### Changed
+
+- No longer truncate stacktraces to 15 lines (#2440)
+
+### Performance
+
+- Improve method block performance for runtime (#2449)
+- Uninline non-typical argument handling (#2419)
+- Logic optimization of runtime.js (#2415)
+- Windows support for `performance:compare` CI check (#2450)
+- Improve block performance for even more cases (#2465)
+
+### Added
+
+- Added support for `#freeze` and `#frozen?` (#2444, #2468)
+- Add CLI support for ESM, at least for Chrome, NodeJS, QuickJS and GJS (#2435)
+- Support exit in Chrome CLI Runner, both sync and async (#2439)
+- Make sure the Server CLI Runner can pick up changes in sources (#2436)
+- Delegate and ruby2_keywords (#2446)
+- Source code can now be embedded in the compiled file to improve development/debugging, e.g. RSpec reports, `Proc#source_location` (#2440)
+- Added `Kernel#caller_locations` (#2440)
+- `Opal::Builder::Prefork` for blazingly fast multicore compilation times (#2263, #2462, #2454)
+
+### Fixed
+
+- Closure tracking support fixes a whole array of bugs handling `break` / `next` / `retry` / … (#2357)
+- Fix an edge case of if in the most complex form not returning (#2433)
+- `String#length` is now available when using `opal/mini` (#2438)
+- Auto-await produced invalid code (#2440)
+- Fix `Enumerable#collect_concat` and `#flat_map` implementation (#2440)
+- Improved await support for PromiseV1 (#2440)
+- Compilation error occurs while compiling `being/end` returning a `case/when` (#2459)
+- Ensure UTF-8 encoding of `.sourcesContent` of source maps (#2451)
+- Benchmarks require string/unpack (#2453)
+
+### Internal
+
+- GitHub Workflows security hardening (#2432)
+- Retry if file cache write operation exits with Zlib::BufError (#2463)
+- Eliminate redundant `var constructor` in `allocate_class` (#2452)
+- Fix `performance:compare` asset size calculation (#2457)

data/benchmark/run.rb

@@ -1,6 +1,7 @@
 if RUBY_ENGINE == 'opal'
   require 'opal/compiler'
   require 'nodejs'
+  require 'corelib/string/unpack'
 end
 
 BEST_OF_N = Integer(ENV['BEST_OF_N']) rescue 1

data/docs/compiled_ruby.md

@@ -617,6 +617,14 @@ myHash.$to_n(); // provided by the Native module
 
 NOTE: Be aware `Hash#to_n` produces a duplicate copy of the hash.
 
+
+### Freezing Objects
+
+Starting with Opal 1.6.0 freezing objects is supported in general but a few differences to Ruby apply.
+Contrary to Ruby, where #freeze is often used to optimize performance, there is no performance benefit when freezing objects in Opal, instead its main use case is to prevent modification of objects.
+There are a few edge cases, where accessing frozen objects in Opal behaves different from Ruby. In those cases a modification attempt will fail silently, with no "FrozenError" exception thrown.
+
+
 ## Advanced Compilation
 
 ### Method Missing

data/docs/compiler.md

@@ -9,7 +9,7 @@ other runtime helpers.
 
 The compiler can be broken down into 3 separate stages:
 
-* lexing/parsing
+* lexing + parsing
 * code generation
 
 ### Lexer/Parser

data/docs/compiler_directives.md

@@ -1,4 +1,4 @@
-# Compiler Directives
+# Compiler File Loading Directives
 
 The Opal compiler supports some special directives that can optimize or
 enhance the output of compiled Ruby code to suit the Ruby environment.

data/docs/getting_started.md

@@ -45,3 +45,20 @@ Opal.append_path '../my_lib'
 Now, any ruby files in this directory can be discovered.
 
 
+## FAQ
+
+### Why does Opal exist?
+
+To try and keep ruby relevant in a world where client-side applications are making javascript the primary development platform.
+
+### How compatible is Opal?
+
+We run opal against the [ruby spec](https://github.com/ruby/spec) as our primary testing setup. We try to make Opal as compatible as possible, whilst also taking into account restrictions of JavaScript when applicable. Opal supports the majority of ruby syntax features, as well as a very large part of the corelib implementation. We support method\_missing, modules, classes, instance\_exec, blocks, procs and lots lots more. Opal can compile and run RSpec unmodified, as well as self hosting the compiler at runtime.
+
+### What version of ruby does Opal target?
+
+We are running tests under ruby 3.0.0 conditions, but are mostly compatible with 2.6 level features.
+
+### Why doesn't Opal support mutable strings?
+
+All strings in Opal are immutable because ruby strings just get compiled directly into javascript strings, which are immutable. Wrapping ruby strings as a custom JavaScript object would add a lot of overhead as well as making interaction between ruby and javascript libraries more difficult.

data/docs/headless_chrome.md

@@ -1,4 +1,4 @@
-# Headless Chrome
+# Running code in a Headless Chrome
 
 ## Requirements
 

data/docs/index.md

@@ -0,0 +1,123 @@
+# Opal Guides for v1.6.dev
+
+These guides are designed to make you immediately productive with Opal, and to help you understand how all of the pieces fit together.
+
+The guides for earlier releases are [available here](/docs).
+
+---
+
+## Start here
+
+#### [Getting Started with Opal](etting_started.html)
+
+Everything you need to know to install Opal and create your first application.
+
+---
+
+## Using JavaScript Features from Ruby
+
+#### [Async](async.html)
+
+Learn more about JavaScript `async`/`await` support in Opal and how you can use it to avoid explicit callbacks and promises.
+
+#### [Promises](promises.html)
+
+How to interact and leverage the power of JavaScript promises from Ruby.
+
+#### [Source Maps](source_maps.html)
+
+How to enable and consume source-maps for your Opal application and be able to debug your Ruby scripts right inside the browser.
+
+---
+
+## Using Ruby Features
+
+#### [Working with ERB and Haml Templates](templates.html)
+
+How to work with template libraries in Opal, be it to share the templates with the server or to write your own.
+
+---
+
+## Working with Frameworks
+
+#### [Rails](rails.html)
+
+How to use `opal-rails` to use Opal as the JavaScript compiler.
+
+#### [Static Applications](static_applications.html)
+
+The most basic setup for a static Opal powered website that can be hosted anywhere.
+
+#### [Sinatra](sinatra.html)
+
+Serve Opal applications through Sinatra and `opal-sprockets`.
+
+#### [Roda + Sprockets](roda-sprockets.html)
+
+Setup Roda + Sprockets to start serving Opal applications from Roda.
+
+---
+
+## Interacting with Other Libraries
+
+#### [jQuery](jquery.html)
+
+This guide covers the `opal-jquery` wrapper around the popular library.
+
+#### [RSpec](rspec.html)
+
+Write specs for your Opal code RSpec and run them on Node.js or in a browser.
+
+#### [Using Sprockets](using_sprockets.html)
+
+Configure the long-lasting asset handler to work with Opal.
+
+---
+
+## Digging Deeper
+
+#### [Configuring Gems](configuring_gems.html)
+
+How to make your gem work in Opal and differentiate code for the JavaScript environment.
+
+#### [Compiler](compiler.html)
+
+A very general overview of how the Opal compiler works.
+
+#### [Compiled Ruby](compiled_ruby.html)
+
+This guide documents how each part of Ruby is mapped to JavaScript internally.
+
+#### [Compiler File Loading Directives](compiler_directives.html)
+
+The Opal compiler supports some special directives that can optimize or
+enhance the output of compiled Ruby code to suit the Ruby environment.
+
+#### [Using the Opal parser inside a JavaScript environment](opal_parser.html)
+
+This guide documents how to parse and run Ruby scripts within a browser or any supported JavaScript environment
+
+#### [Encoding](encoding.html)
+
+(WIP) How to handle encoding within Opal in the browser and in the code.
+
+#### [Running code in a Headless Chrome](headless_chrome.html)
+
+How to run your Opal application in a headless Chrome from the CLI instead of Node.js.
+
+#### [Unsupported Features](unsupported_features.html)
+
+Some things that are very difficult, impossible, or outright incompatible with a JavaScript environment.
+
+---
+
+## Releases
+
+#### [Upgrading Opal](upgrading.html)
+
+This guide provides steps to be followed when you upgrade your applications to a newer version of Opal.
+
+#### [Releasing Instructions](releasing.html)
+
+(WIP) A step-by-step guide on who to release a new version of Opal.
+

data/docs/templates.md

@@ -42,6 +42,43 @@ Template['login']
 # => #<Template: 'login'>
 ```
 
+## ERB Templates
+
+Support for `erb` templates is built in directly to the opal gem and stdlib.
+There is one caveat though when working with sprockets - it must have the
+`.opalerb` file extension, instead of `.erb`. This is because sprockets has a
+built in handler for `.erb` files.
+
+If we have the same user class as above, create an `app/views/user.opalerb`
+file:
+
+```erb
+<!-- app/views/user.opalerb -->
+<div class="row">
+  <div class="col-md-3"><%= self.name %></div>
+</div>
+```
+
+Again, you must then require the template (without the `.opalerb` extension):
+
+```ruby
+# app/application.rb
+require 'opal'
+require 'views/user'
+```
+
+And then you can access and render the template:
+
+```ruby
+# app/application.rb
+
+template = Template['views/user']
+user = User.new('Ford Prefect')
+
+puts template.render(user)
+# => "<div class="row">...</div>"
+```
+
 ## Haml templates
 
 `opal-haml` allows `.haml` templates to be compiled, just like opal compiles
@@ -111,40 +148,3 @@ check it out, you should see it compiled into something like the following:
   </div>
 </div>
 ```
-
-## ERB Templates
-
-Support for `erb` templates is built in directly to the opal gem and stdlib.
-There is one caveat though when working with sprockets - it must have the
-`.opalerb` file extension, instead of `.erb`. This is because sprockets has a
-built in handler for `.erb` files.
-
-If we have the same user class as above, create an `app/views/user.opalerb`
-file:
-
-```erb
-<!-- app/views/user.opalerb -->
-<div class="row">
-  <div class="col-md-3"><%= self.name %></div>
-</div>
-```
-
-Again, you must then require the template (without the `.opalerb` extension):
-
-```ruby
-# app/application.rb
-require 'opal'
-require 'views/user'
-```
-
-And then you can access and render the template:
-
-```ruby
-# app/application.rb
-
-template = Template['views/user']
-user = User.new('Ford Prefect')
-
-puts template.render(user)
-# => "<div class="row">...</div>"
-```

data/docs/unsupported_features.md

@@ -24,10 +24,6 @@ Encodings only have a very small implementation inside Opal.
 
 JavaScript does not have a native `Thread` implementation, so they are not present inside Opal. There is a placeholder `Thread` class just to provide some small level of compatibility with libraries that expect it. It does not have any function.
 
-#### Frozen Objects ####
-
-Opal does not currently support frozen objects, but has placeholder methods to prevent other libraries breaking when expecting these methods. Opal could support frozen objects in the future once a similar implementation becomes available across JavaScript runtimes.
-
 #### Private, Public and Protected methods ####
 
 All methods in Opal are defined as `public` to avoid additional runtime overhead. `Module#private` and `Module#protected` exist as just placeholder methods and are no-op methods.

data/lib/opal/builder.rb

@@ -4,6 +4,7 @@ require 'opal/path_reader'
 require 'opal/paths'
 require 'opal/config'
 require 'opal/cache'
+require 'opal/builder_scheduler'
 require 'set'
 
 module Opal
@@ -55,8 +56,6 @@ module Opal
       processor_extensions.each { |ext| extensions << ext }
     end
 
-
-
     class MissingRequire < LoadError
     end
 
@@ -76,6 +75,11 @@ module Opal
       @compiler_options         ||= Opal::Config.compiler_options
       @missing_require_severity ||= Opal::Config.missing_require_severity
       @cache                    ||= Opal.cache
+      @scheduler                ||= Opal.builder_scheduler
+
+      if @scheduler.respond_to? :new
+        @scheduler = @scheduler.new(self)
+      end
 
       @processed = []
     end
@@ -99,11 +103,10 @@ module Opal
       rel_path = expand_ext(rel_path)
       asset = processor_for(source, rel_path, abs_path, false, options)
       requires = preload + asset.requires + tree_requires(asset, abs_path)
-      requires.map { |r| process_require(r, asset.autoloads, options) }
+      # Don't automatically load modules required by the module
+      process_requires(rel_path, requires, asset.autoloads, options.merge(load: false))
       processed << asset
       self
-    rescue MissingRequire => error
-      raise error, "A file required by #{rel_path.inspect} wasn't found.\n#{error.message}", error.backtrace
     end
 
     def build_require(path, options = {})
@@ -134,6 +137,39 @@ module Opal
       path_reader.append_paths(*paths)
     end
 
+    def process_require_threadsafely(rel_path, autoloads, options)
+      return if prerequired.include?(rel_path)
+
+      autoload = autoloads.include? rel_path
+
+      source = stub?(rel_path) ? '' : read(rel_path, autoload)
+
+      # The handling is delegated to the runtime
+      return if source.nil?
+
+      abs_path = expand_path(rel_path)
+      rel_path = expand_ext(rel_path)
+      asset = processor_for(source, rel_path, abs_path, autoload, options.merge(requirable: true))
+      process_requires(
+        rel_path,
+        asset.requires + tree_requires(asset, abs_path),
+        asset.autoloads,
+        options
+      )
+      asset
+    end
+
+    def process_require(rel_path, autoloads, options)
+      return if already_processed.include?(rel_path)
+      already_processed << rel_path
+      asset = process_require_threadsafely(rel_path, autoloads, options)
+      processed << asset if asset
+    end
+
+    def already_processed
+      @already_processed ||= Set.new
+    end
+
     include UseGem
 
     attr_reader :processed
@@ -141,8 +177,26 @@ module Opal
     attr_accessor :processors, :path_reader, :stubs, :prerequired, :preload,
       :compiler_options, :missing_require_severity, :cache
 
+    def esm?
+      @compiler_options[:esm]
+    end
+
+    # Output extension, to be used by runners. At least Node.JS switches
+    # to ESM mode only if the extension is "mjs"
+    def output_extension
+      if esm?
+        'mjs'
+      else
+        'js'
+      end
+    end
+
     private
 
+    def process_requires(rel_path, requires, autoloads, options)
+      @scheduler.process_requires(rel_path, requires, autoloads, options)
+    end
+
     def tree_requires(asset, asset_path)
       dirname = asset_path.to_s.empty? ? Pathname.pwd : Pathname(asset_path).expand_path.dirname
       abs_base_paths = path_reader.paths.map { |p| File.expand_path(p) }
@@ -201,30 +255,6 @@ module Opal
       end
     end
 
-    def process_require(rel_path, autoloads, options)
-      return if prerequired.include?(rel_path)
-      return if already_processed.include?(rel_path)
-      already_processed << rel_path
-
-      autoload = autoloads.include? rel_path
-
-      source = stub?(rel_path) ? '' : read(rel_path, autoload)
-
-      # The handling is delegated to the runtime
-      return if source.nil?
-
-      abs_path = expand_path(rel_path)
-      rel_path = expand_ext(rel_path)
-      asset = processor_for(source, rel_path, abs_path, autoload, options.merge(requirable: true))
-      process_requires(
-        rel_path,
-        asset.requires + tree_requires(asset, abs_path),
-        asset.autoloads,
-        options
-      )
-      processed << asset
-    end
-
     def expand_ext(path)
       abs_path = path_reader.expand(path)
 
@@ -243,16 +273,6 @@ module Opal
       (path_reader.expand(path) || File.expand_path(path)).to_s
     end
 
-    def process_requires(rel_path, requires, autoloads, options)
-      requires.map { |r| process_require(r, autoloads, options) }
-    rescue MissingRequire => error
-      raise error, "A file required by #{rel_path.inspect} wasn't found.\n#{error.message}", error.backtrace
-    end
-
-    def already_processed
-      @already_processed ||= Set.new
-    end
-
     def stub?(path)
       stubs.include?(path)
     end