hanami-importmap 0.1.0

data/lib/hanami/importmap/packager.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "net/http"
+require "pathname"
+require "uri"
+require_relative "errors"
+
+module Hanami
+  module Importmap
+    # Resolves npm packages to ES module URLs with the jspm.io generator API, vendors them into an
+    # assets directory, and keeps `config/importmap.rb` pin lines in step.
+    #
+    # A port of importmap-rails' `Importmap::Packager`.
+    #
+    # @api private
+    class Packager
+      ENDPOINT = URI("https://api.jspm.io/generate")
+
+      IMPORTMAP_HEADER = <<~RUBY
+        # frozen_string_literal: true
+
+        # Pin JavaScript modules for this import map. `pin` names what you `import`; `to:` is an
+        # asset name, as you'd give to `javascript_tag` (defaults to the name plus ".js").
+        #
+        # Vendor npm packages with `bundle exec hanami importmap pin <package>`.
+      RUBY
+
+      attr_reader :importmap_path, :vendor_path
+
+      # @param importmap_path [String, Pathname] the `config/importmap.rb` to update
+      # @param vendor_path [String, Pathname] where to download packages (`<assets>/vendor`)
+      def initialize(importmap_path:, vendor_path:)
+        @importmap_path = Pathname(importmap_path)
+        @vendor_path = Pathname(vendor_path)
+      end
+
+      # Resolves packages and their dependencies.
+      #
+      # @return [Hash{String => String}, nil] package name → URL, or nil if nothing was found
+      def import(*packages, from: "jspm", env: "production")
+        response = post_json(
+          "install" => packages,
+          "flattenScope" => true,
+          "env" => ["browser", "module", env],
+          "provider" => (from.to_s == "jspm") ? "jspm.io" : from.to_s
+        )
+
+        case response.code
+        when "200" then JSON.parse(response.body).dig("map", "imports")
+        when "404", "401" then nil
+        else raise_failure(response)
+        end
+      end
+
+      # Downloads a package into the vendor directory, replacing any earlier version.
+      def download(package, url)
+        FileUtils.mkdir_p(vendor_path)
+        response = get(url)
+        raise_failure(response) unless response.code == "200"
+
+        source = response.body.dup.force_encoding(Encoding::UTF_8).gsub(%r{^//# sourceMappingURL=.*}, "")
+        vendored_path(package).write("// #{package}#{version_from(url)} downloaded from #{url}\n\n#{source}")
+      end
+
+      # Adds or replaces the pin line for a vendored package.
+      def pin(package, url, preload: true)
+        filename = package_filename(package)
+        line = %(pin "#{package}")
+        line += %(, to: "#{filename}") unless filename == "#{package}.js"
+        line += ", preload: false" unless preload
+        line += " # #{version_from(url)}" if version_from(url)
+
+        write_pin_line(package, line)
+      end
+
+      # Removes a package's file and pin line. Returns false if it wasn't pinned.
+      def remove(package)
+        FileUtils.rm_f(vendored_path(package))
+        return false unless pinned?(package)
+
+        importmap_path.write(importmap_path.readlines.grep_v(pin_line_regexp(package)).join)
+        true
+      end
+
+      def pinned?(package)
+        importmap_path.file? && importmap_path.readlines.any? { _1.match?(pin_line_regexp(package)) }
+      end
+
+      def package_filename(package)
+        "#{package.gsub("/", "--")}.js"
+      end
+
+      def vendored_path(package)
+        vendor_path.join(package_filename(package))
+      end
+
+      private
+
+      def write_pin_line(package, line)
+        unless importmap_path.file?
+          FileUtils.mkdir_p(importmap_path.dirname)
+          importmap_path.write(IMPORTMAP_HEADER)
+        end
+
+        lines = importmap_path.readlines
+        index = lines.index { _1.match?(pin_line_regexp(package)) }
+
+        if index
+          lines[index] = "#{line}\n"
+        else
+          lines << "\n" unless lines.empty? || lines.last.end_with?("\n")
+          lines << "#{line}\n"
+        end
+
+        importmap_path.write(lines.join)
+      end
+
+      def pin_line_regexp(package)
+        /\A\s*pin\s+["']#{Regexp.escape(package)}["']/
+      end
+
+      def version_from(url)
+        url[/@\d+\.\d+\.\d+(?:-[\w.]+)?/]
+      end
+
+      def post_json(body)
+        Net::HTTP.post(ENDPOINT, JSON.generate(body), "Content-Type" => "application/json")
+      rescue => exception
+        raise Error, "Couldn't reach #{ENDPOINT.host} (#{exception.class}: #{exception.message})"
+      end
+
+      def get(url)
+        Net::HTTP.get_response(URI(url))
+      rescue => exception
+        raise Error, "Couldn't download #{url} (#{exception.class}: #{exception.message})"
+      end
+
+      def raise_failure(response)
+        message = begin
+          JSON.parse(response.body.to_s)["error"]
+        rescue JSON::ParserError
+          nil
+        end
+
+        raise Error, message || "Unexpected response from #{ENDPOINT.host} (HTTP #{response.code})"
+      end
+    end
+  end
+end

data/lib/hanami/importmap/resolver.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+require "hanami/assets"
+require_relative "errors"
+require_relative "compiler"
+
+module Hanami
+  module Importmap
+    # Turns the `importmap.json` written by the {Compiler} into a browser import map, resolving
+    # asset names through hanami-assets (so `config.assets.base_url` and subresource integrity
+    # apply exactly as they do for `javascript_tag`).
+    #
+    # Results are cached per assets directory and rebuilt when `importmap.json` or `assets.json`
+    # change, so `hanami assets watch` output is picked up without restarting the server.
+    #
+    # @api public
+    class Resolver
+      # A resolved import map.
+      #
+      # @!attribute imports [Hash{String => String}] module name → URL
+      # @!attribute integrity [Hash{String => String}] URL → SRI value
+      # @!attribute preloads [Array<String>] URLs to preload
+      ResolvedMap = Data.define(:imports, :integrity, :preloads) do
+        # @return [Hash] the import map, ready to serialize into `<script type="importmap">`
+        def to_h
+          {"imports" => imports, "integrity" => (integrity unless integrity.empty?)}.compact
+        end
+      end
+
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        # @param assets [Hanami::Assets] the app's or slice's assets (`context.assets` in views)
+        #
+        # @return [ResolvedMap]
+        #
+        # @raise [MissingImportmapError] if the import map hasn't been built
+        def call(assets)
+          root = Pathname(assets.root)
+          stamp = [mtime(root.join(Compiler::IMPORTMAP)), mtime(root.join(Compiler::MANIFEST))]
+
+          @mutex.synchronize do
+            cached = @cache[root.to_s]
+            return cached.last if cached && cached.first == stamp
+
+            # Use fresh assets rather than the given ones, whose manifest is read once and memoized.
+            fresh = Hanami::Assets.new(config: assets.config, root:)
+            resolved = new(fresh, root).call
+            @cache[root.to_s] = [stamp, resolved]
+            resolved
+          end
+        end
+
+        # @api private
+        def reset!
+          @mutex.synchronize { @cache.clear }
+        end
+
+        private
+
+        def mtime(path)
+          path.mtime
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+
+      def initialize(assets, root)
+        @assets = assets
+        @root = root
+      end
+
+      # @return [ResolvedMap]
+      def call
+        path = @root.join(Compiler::IMPORTMAP)
+
+        unless path.file?
+          raise MissingImportmapError, "No import map found at #{path}. " \
+            "Add a config/importmap.rb and run `hanami assets compile` (or `hanami dev`)."
+        end
+
+        data = JSON.parse(path.read)
+        imports = {}
+        integrity = {}
+        preloads = []
+
+        data.fetch("pins").each do |pin|
+          if pin["asset"]
+            asset = @assets[pin["asset"]]
+            url = asset.url
+            sri = Array(asset.sri).join(" ")
+            integrity[url] = sri unless sri.empty?
+          else
+            url = pin.fetch("url")
+            integrity[url] = pin["integrity"] if pin["integrity"]
+          end
+
+          imports[pin.fetch("name")] = url
+          preloads << url if pin["preload"]
+        end
+
+        ResolvedMap.new(imports:, integrity:, preloads: preloads.uniq)
+      end
+    end
+  end
+end

data/lib/hanami/importmap/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Importmap
+    VERSION = "0.1.0"
+  end
+end

data/lib/hanami/importmap.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "hanami"
+require_relative "importmap/version"
+require_relative "importmap/errors"
+require_relative "importmap/map"
+require_relative "importmap/compiler"
+require_relative "importmap/resolver"
+
+module Hanami
+  # Import maps for Hanami: ES modules without Node or a bundler.
+  #
+  # Requiring this file adds `javascript_importmap_tags` to the standard view helpers. The gem also
+  # replaces `hanami assets compile` and `hanami assets watch` with a pure-Ruby bundler (see
+  # {Compiler}), and adds `hanami importmap` commands.
+  #
+  # @example
+  #   # config/app.rb
+  #   require "hanami"
+  #   require "hanami/importmap"
+  #
+  # @api public
+  module Importmap
+  end
+end
+
+require_relative "importmap/helpers" if Hanami.bundled?("hanami-view")

data/lib/hanami-importmap.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Loaded by Bundler.require (the `hanami` CLI requires the `:cli` group). The app itself requires
+# "hanami/importmap" from config/app.rb.
+require "hanami/cli"
+
+if Hanami::CLI.within_hanami_app?
+  require_relative "hanami/importmap/cli"
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: hanami-importmap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrea Fomera
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hanami-assets
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: dry-inflector
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A pure-Ruby bundler for hanami-assets that fingerprints your JavaScript,
+  CSS and images, plus `config/importmap.rb`, the `javascript_importmap_tags` helper
+  and `hanami importmap pin`
+email:
+- afomera@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/hanami-importmap.rb
+- lib/hanami/importmap.rb
+- lib/hanami/importmap/cli.rb
+- lib/hanami/importmap/cli/assets.rb
+- lib/hanami/importmap/cli/hooks.rb
+- lib/hanami/importmap/cli/importmap.rb
+- lib/hanami/importmap/cli/install.rb
+- lib/hanami/importmap/compiler.rb
+- lib/hanami/importmap/errors.rb
+- lib/hanami/importmap/helpers.rb
+- lib/hanami/importmap/map.rb
+- lib/hanami/importmap/packager.rb
+- lib/hanami/importmap/resolver.rb
+- lib/hanami/importmap/version.rb
+homepage: https://github.com/afomera/hanami-importmap
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Import maps for Hanami: ship ES modules without Node or a bundler'
+test_files: []