darkroom 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec78b55ac1e82e265e1f5546a929ed3b12ab72585bc448d5f3c3d06c8804ec10
-  data.tar.gz: 2df42517847826a826ebe32d90b8bbbe41fe242872e56db06672e5b5c1d4fb3b
+  metadata.gz: b6ac679135bef28a77e6bd0df80d65d9fff5af142fa5ed928a97355ed02e8488
+  data.tar.gz: 77d7593cc83a00dc06d6e4eda009837707f5912b0b6fff0ee43e4056193cfc27
 SHA512:
-  metadata.gz: 49970a3c8e73e1a44f54ccca8bef6c31e55c56bd5c0b1a9194beef31ecc188ce6c54d225d02c68261e42f6c9a8fee15b160a492f0dd5bbba1be07097d7f6182f
-  data.tar.gz: 109f67f9c64b8443d11404af38d33f154f94a3acef3a041b66499c3cfade22ad3516d6abb55cbb48c42ed2592e2a46575e4c52c6b9745f147f0af9fb84fbda4b
+  metadata.gz: cb0eda914cb475f656410c2d25188726c4e3697ba11e5877810c14dcf2639ae3340a77ba8982a1b0ebf86d2f9570ebb1cf01e756983fdd591fa6bf23eb3ad65b
+  data.tar.gz: bef29d0cfea183be2350772684c64baea0d2ee2751f46759d7ea540a2a9e46c61eef1a4c441c80cff201f46e10c85a25f602da18b486bde6b9127ed878f21864

data/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 * Nothing yet
 
+## 0.0.10 (2025 February 19)
+
+* Include a few more instance variables in `Asset#inspect`
+* **Require Ruby 3.0.0 or later**
+* Make ProcessingError enumerable
+* **Ensure import and reference regexes have the required named captures**
+* Gracefully handle invalid reference entities
+* **Fix delegate finalize library not getting required**
+
 ## 0.0.9 (2025 January 21)
 
 * **Remove deprecated delegate creation via hash and associated accessors**

data/README.md

@@ -1,32 +1,24 @@
 # Darkroom
 
-Darkroom is a fast, lightweight, and straightforward web asset management library. Processed assets are all
-stored in and served directly from memory rather than being written to disk (though a dump to disk can be
-performed for upload to a CDN or proxy server in production environments); this keeps asset management
-simple and performant in development. Darkroom also supports asset bundling for CSS and JavaScript using
-each language's native import statement syntax.
-
-The following file types are supported out of the box, though support for others can be added (see the
-[Extending](#extending) section):
-
-| Name       | Content Type     | Extension(s) |
-|------------|------------------|--------------|
-| APNG       | image/apng       | .apng        |
-| AVIF       | image/avif       | .avif        |
-| CSS        | text/css         | .css         |
-| GIF        | image/gif        | .gif         |
-| HTML       | text/html        | .htm, .html  |
-| HTX        | text/javascript  | .htx         |
-| ICO        | image/x-icon     | .ico         |
-| JavaScript | text/javascript  | .js          |
-| JPEG       | image/jpeg       | .jpg, .jpeg  |
-| JSON       | application/json | .json        |
-| PNG        | image/png        | .png         |
-| SVG        | image/svg+xml    | .svg         |
-| Text       | text/plain       | .txt         |
-| WebP       | image/webp       | .webp        |
-| WOFF       | font/woff        | .woff        |
-| WOFF2      | font/woff2       | .woff2       |
+Darkroom is a simple and straightforward web asset management and bundling library written entirely in Ruby.
+It is designed to be used directly within a Ruby web server process—no external dependencies or process
+management is needed.
+
+* **Asset Bundling** — CSS and JavaScript assets are bundled using each language's native import statement
+  syntax.
+  * `@import '/header.css';` includes the contents of header.css in a CSS asset.
+  * `import '/api.js'` includes the contents of api.js in a JavaScript asset.
+* **Asset References** — Asset paths are versioned with a URL query parameter.
+  * `<img src='/logo.svg?asset-path'>` gets replaced with `<img src='/logo-[fingerprint].svg'>`.
+* **Asset Inlining** — Certain kinds of assets (e.g. images in HTML documents) can be inlined using a URL
+  query parameter.
+  * `<img src='/logo.svg?asset-content=utf8'>` gets replaced with
+    `<img src='data:image/svg+xml;utf8,<svg>[...]</svg>'>`.
+* **JavaScript Modules** — JavaScript bundles can (optionally) encapsulate the content of each file with
+  imports defined as local variables to mimic native ES6 modules within a single file.
+* **In-Memory** — Processed assets are all stored in and served directly from memory to avoid the issues
+  that generally ensue from writing to and managing files on disk. Assets can however be dumped to disk for
+  upload to a CDN or proxy server in production environments.
 
 ## Installation
 
@@ -59,6 +51,8 @@ To create and start using a Darkroom instance, specify one or more load paths (a
 optional):
 
 ```ruby
+Darkroom.javascript_iife = true      # Use IIFEs to emulate ES6-style JavaScript modules
+
 darkroom = Darkroom.new('app/assets', 'vendor/assets', '...',
   hosts: [                           # Hosts to prepend to asset paths (useful in production
     'https://cname1.cdn.com',        #   when assets are served from a CDN with multiple
@@ -75,7 +69,8 @@ darkroom = Darkroom.new('app/assets', 'vendor/assets', '...',
   minify: true,                      # Minify assets that can be minified
   minified: /(\.|-)min\.\w+$/,       # Files to skip minification on when minify: true; can
                                      #   be a string, regex, or array of such
-  min_process_interval: 1,           # Minimum time that must elapse between process calls
+  min_process_interval: 1,           # Minimum seconds that must elapse between process
+                                     #   calls (otherwise processing is skipped)
 )
 ```
 
@@ -141,101 +136,120 @@ asset.integrity(:sha512)        # => "sha512-[hash]"
 
 ## Asset Bundling
 
-CSS and JavaScript assets specify their dependencies by way of each language's native import statement. Each
-import statement is replaced with the content of the imported asset. Example:
-
-```css
-/* Unprocessed /header.css */
-header { background: #f1f1f1; }
-```
-
-```css
-/* Unprocessed /app.css */
-@import '/header.css';
-
-body { background: #fff; }
-```
-
-```css
-/* Processed /app.css */
-header { background: #f1f1f1; }
-
-body { background: #fff; }
-```
+JavaScript and CSS assets specify their dependencies by way of each language's native import statement. Each
+import statement is replaced with the content of the imported asset.
 
 Imported assets can also contain import statements, and those assets are all included in the base asset.
 Imports can even be cyclical. If `asset-a.css` imports `asset-b.css` and vice-versa, each asset will simply
 contain the content of both of those assets (though order will be different as an asset's own content always
 comes after any imported assets' contents).
 
-By default, JavaScript files are concatenated in the same way that CSS files are. Example:
+### JavaScript - Single Scope
 
-```javascript
-// Unprocessed /api.js
-function API() { console.log('API called!') }
-```
+By default, JavaScript bundles are a simple concatenation of files. Imports should all be "side effect"
+style and result in all code using one shared scope:
 
-```javascript
-// Unprocessed /app.js
-import '/api.js'
+* **/api.js** (raw file)
+  ```javascript
+  function API() {
+    console.log('API called!')
+  }
+  ```
+* **/app.js** (raw file)
+  ```javascript
+  import '/api.js'
 
-API()
-```
+  API()
+  ```
+* **/app.js** (processed)
+  ```javascript
+  function API() {
+    console.log('API called!')
+  }
 
-```javascript
-// Processed /app.js
-function API() { console.log('API called!') }
+  API()
+  ```
 
-API()
-```
+### JavaScript - Modules
 
 Alternatively, setting `Darkroom.javascript_iife = true` will cause JavaScript assets to be compiled to a
-series of IIFEs that provide the same encapsulation as native ES6 modules (indentation is not quite as
-pretty as shown here, but has been altered here for readability):
-
-```javascript
-// Unprocessed /api.js
-export function API() { console.log('API called!') }
-```
-
-```javascript
-// Unprocessed /app.js
-import {API} from '/api.js'
-
-API()
-```
-
-```javascript
-// Processed /app.js
-((...bundle) => {
-  const modules = {}
-  const setters = []
-  const $import = (name, setter) =>
-    modules[name] ? setter(modules[name]) : setters.push([setter, name])
-
-  for (const [name, def] of bundle)
-    modules[name] = def($import)
-
-  for (const [setter, name] of setters)
-    setter(modules[name])
-})(
-  ['/api.js', $import => {
-    function API() { console.log('API called!') }
-
-    return Object.seal({
-      API: API,
-    })
-  }],
-
-  ['/app.js', $import => {
-    let API; $import('/api.js', m => API = m.API)
-
-    API()
-
-    return Object.seal({})
-  }],
-)
-```
+series of IIFEs that provide the same encapsulation as native ES6 modules. In this case, objects must be
+explicitly exported to be importable and named (rather than side effect) imports used:
+
+* **/api.js** (raw file)
+  ```javascript
+  export function API() {
+    console.log('API called!')
+  }
+  ```
+* **/app.js** (raw file)
+  ```javascript
+  import {API} from '/api.js'
+
+  API()
+  ```
+* **/app.js** (processed)
+  ```javascript
+  ((...bundle) => {
+    const modules = {}
+    const setters = []
+    const $import = (name, setter) =>
+      modules[name] ? setter(modules[name]) : setters.push([setter, name])
+
+    for (const [name, def] of bundle)
+      modules[name] = def($import)
+
+    for (const [setter, name] of setters)
+      setter(modules[name])
+  })(
+    ['/api.js', $import => {
+      function API() {
+        console.log('API called!')
+      }
+
+      return Object.seal({
+        API: API,
+      })
+    }],
+
+    ['/app.js', $import => {
+      let API; $import('/api.js', m => API = m.API)
+
+      API()
+
+      return Object.seal({})
+    }],
+  )
+  ```
+
+### CSS
+
+CSS imports are always just a simple concatenation.
+
+* **/header.css** (raw file)
+  ```css
+  header {
+    background: #f1f1f1;
+  }
+  ```
+* **/app.css** (raw file)
+  ```css
+  @import '/header.css';
+
+  body {
+    background: #fff;
+  }
+  ```
+* **/app.css** (processed)
+  ```css
+  header {
+    background: #f1f1f1;
+  }
+
+  body {
+    background: #fff;
+  }
+  ```
 
 ## Asset References
 
@@ -290,8 +304,29 @@ replaced appropriately.
 
 ## Extending
 
-Darkroom is extensible. Support for arbitrary file types can be added by specifying one or more extensions
-and a content type:
+The following file types are supported out of the box:
+
+| Name       | Content Type     | Extension(s) |
+|------------|------------------|--------------|
+| APNG       | image/apng       | .apng        |
+| AVIF       | image/avif       | .avif        |
+| CSS        | text/css         | .css         |
+| GIF        | image/gif        | .gif         |
+| HTML       | text/html        | .htm, .html  |
+| HTX        | text/javascript  | .htx         |
+| ICO        | image/x-icon     | .ico         |
+| JavaScript | text/javascript  | .js          |
+| JPEG       | image/jpeg       | .jpg, .jpeg  |
+| JSON       | application/json | .json        |
+| PNG        | image/png        | .png         |
+| SVG        | image/svg+xml    | .svg         |
+| Text       | text/plain       | .txt         |
+| WebP       | image/webp       | .webp        |
+| WOFF       | font/woff        | .woff        |
+| WOFF2      | font/woff2       | .woff2       |
+
+But Darkroom is extensible, allowing support for any kind of asset to be added. This is done most simply by
+specifying one or more extensions and a content type:
 
 ```ruby
 Darkroom.register('.ext1', '.ext2', '...', 'content/type')
@@ -299,7 +334,7 @@ Darkroom.register('.ext1', '.ext2', '...', 'content/type')
 
 ### DSL
 
-For more advanced functionality, the DSL can be used one of three ways. With a block:
+For more advanced functionality, a DSL is provided which can be used one of three ways. With a block:
 
 ```ruby
 Darkroom.register('.ext1', '.ext2', '...') do
@@ -356,10 +391,10 @@ Darkroom.register('.ext1', '.ext2', '...') do
   # ...
 
   # The (optional) block is passed three keyword arguments:
-  #   parse_data: - Hash for storing data across calls to this and other parse handlers.
-  #   match:      - MatchData object from the match against the provided regex.
+  #   parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+  #   match:      - MatchData object from the match against the regex.
   #   asset:      - Asset object of the asset being imported.
-  import(/import #{Asset::QUOTED_PATH_REGEX.source};/) do |parse_data:, match:, asset:|
+  import(/import '(?<path>[^']+)';/) do |parse_data:, match:, asset:|
     parse_data[:imports] ||= []          # Accumulate and use arbitrary parse data.
     parse_data[:imports] << match[:path] # Use the MatchData object of the regex match.
 
@@ -402,10 +437,11 @@ Darkroom.register('.ext1', '.ext2', '...') do
   reference_regex = /ref=#{Asset::REFERENCE_REGEX.source}/x
 
   # The (optional) block is passed four keyword arguments:
-  #   parse_data: - Hash for storing data across calls to this and other parse handlers.
-  #   match:      - MatchData object from the match against the provided regex.
-  #   asset:      - Asset object of the asset being referenced.
-  #   format:     - Format of the reference (see Asset::REFERENCE_FORMATS).
+  #
+  # parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+  # match:      - MatchData object from the match against the regex.
+  # asset:      - Asset object of the asset being referenced.
+  # format:     - String format of the reference (see Asset::REFERENCE_FORMATS).
   reference(reference_regex) do |parse_data:, match:, asset:, format:|
     parse_data[:refs] ||= []          # Accumulate and use arbitrary parse data.
     parse_data[:refs] << match[:path] # Use the MatchData object of the regex match.
@@ -437,8 +473,9 @@ Darkroom.register('.ext1', '.ext2', '...') do
   # ...
 
   # The block is passed two keyword arguments:
-  #   parse_data: - Hash for storing data across calls to this and other parse handlers.
-  #   match:      - MatchData object from the match against the provided regex.
+  #
+  # parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+  # match:      - MatchData object from the match against the regex.
   parse(:exports, /export (?<name>.+)/) do |parse_data:, match:|
     parse_data[:exports] ||= []          # Accumulate and use arbitrary parse data.
     parse_data[:exports] << match[:name] # Use the MatchData object of the regex match.
@@ -466,14 +503,19 @@ end
 Compilation allows for a library to require (optional), a delegate to use after compilation (optional), and
 a block that returns the compiled version of the asset's own content.
 
+Passing a delegate will cause the asset to be treated as if it is that type once it has been compiled. For
+example, HTX templates use `delegate: JavaScriptDelegate` because they get compiled to JavaScript and thus
+should be treated as JavaScript files post compilation.
+
 ```ruby
 Darkroom.register('.ext1', '.ext2', '...') do
   # ...
 
   # The block is passed three keyword arguments:
-  #   parse_data:  - Hash of data collected during parsing.
-  #   path:        - Path of the asset being compiled.
-  #   own_content: - Asset's own content (without imports).
+  #
+  # parse_data:  - Hash for storing arbitrary data across calls to this and other handlers.
+  # path:        - String path of the asset.
+  # own_content: - String own content (without imports) of the asset.
   compile(lib: 'compile_lib', delegate: SomeDelegate) do |parse_data:, path:, own_content:|
     CompileLib.compile(own_content)
   end
@@ -491,9 +533,10 @@ Darkroom.register('.ext1', '.ext2', '...') do
   # ...
 
   # The block is passed three keyword arguments:
-  #   parse_data: - Hash of data collected during parsing.
-  #   path:       - Path of the asset being finalized.
-  #   content:    - Asset's compiled content (with imports prepended).
+  #
+  # parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+  # path:       - String path of the asset.
+  # content:    - String content of the compiled asset (with imports prepended).
   finalize(lib: 'finalize_lib') do |parse_data:, path:, content:|
     FinalizeLib.finalize(content)
   end
@@ -511,9 +554,10 @@ Darkroom.register('.ext1', '.ext2', '...') do
   # ...
 
   # The block is passed three keyword arguments:
-  #   parse_data: - Hash of data collected during parsing.
-  #   path:       - Path of the asset being finalized.
-  #   content:    - Asset's finalized content.
+  #
+  # parse_data: - Hash for storing arbitrary data across calls to this and other handlers.
+  # path:       - String oath of the asset being minified.
+  # content:    - string content of the finalized asset.
   minify(lib: 'minify_lib') do |parse_data:, path:, content:|
     MinifyLib.compress(content)
   end

data/VERSION

@@ -1 +1 @@
-0.0.9
+0.0.10