Sass @use versus @import: map key resolution across implementations

Confirmed Behavior

Map key resolution differs between @use (Dart Sass) and @import (Ruby Sass) due to type coercion rules. Dart Sass coerces all map keys to strings during map.get(), while Ruby Sass preserves original key types. This causes map.get() to return null silently in Dart Sass when querying with mismatched types, whereas Ruby Sass may emit runtime errors depending on version.

Key Differences

• Type Coercion: Dart Sass converts numeric keys to strings automatically; Ruby Sass does not.
• Missing Key Handling: Dart Sass returns null silently; Ruby Sass behavior varies by version, sometimes throwing errors.
• Caching: @use caches modules, preventing re-evaluation; @import re-evaluates files on each reference.
• Map Merging: Multiple @use directives with duplicate keys follow last-wins strategy in Dart Sass.

Conditions for Silent Null vs Error

map.get() produces silent null when:

1. Using Dart Sass with @use
2. Key type mismatch exists (e.g., numeric key queried as string)
3. Key does not exist in map

An explicit error may occur in Ruby Sass when:

1. Using @import
2. Key type mismatch triggers internal lookup failure
3. Version-specific error handling is enabled

Build-Pipeline Impact

Caching in @use can mask key resolution issues during development rebuilds. The last-wins merge strategy for duplicate keys across multiple @use directives may silently override theme values without notification. CSS custom property output remains consistent, but intermediate Sass processing may fail silently with @use.

Verification Steps

To confirm behavior in your pipeline:

1. Create a Sass map with numeric keys: $theme: (1: 'primary', 2: 'secondary');
2. Query with string key: map.get($theme, '1')
3. Compile with Dart Sass and observe null output
4. Repeat with Ruby Sass using @import and check for errors
5. Test missing key queries to verify null vs error behavior

Recommendation

Standardize on Dart Sass for predictable string-based key resolution. Explicitly cast keys to strings when using numeric or mixed-type keys. Use map-has-key() to check existence before map.get() calls in theme systems to avoid silent null propagation.