get-smart 0.0.1

data/files/ruby/data_types/advanced/scoped_refinements.md

@@ -0,0 +1,31 @@
+## 🎭 Scope Core Extensions Safely with Refinements
+Refinements let you patch core classes in a module or class scope without polluting global behavior.
+
+```ruby
+module StringExtras
+  refine String do
+    def shout
+      upcase + "!"
+    end
+  end
+end
+
+class Greeter
+  using StringExtras
+
+  def greet(name)
+    name.shout
+  end
+end
+
+puts Greeter.new.greet("hello")
+# => "HELLO!"
+
+# Outside the class, original String unaffected:
+begin
+  "hello".shout
+rescue NoMethodError => e
+  puts e.message
+end
+# => undefined method `shout' for "hello":String
+```

data/files/ruby/data_types/beginner/ruby_arrays.md

@@ -0,0 +1,16 @@
+## 📚 Arrays for Ordered Collections
+
+Arrays hold ordered lists of elements and can contain objects of any type. You can create arrays, add elements, access by index, and iterate over them. Arrays are dynamic, so you can change their size at runtime.
+
+```ruby
+# Create an array
+fruits = ['apple', 'banana', 'cherry']
+# Add an element
+fruits << 'date'
+# Access first and last elements
+first, last = fruits.first, fruits.last
+# Iterate over each element
+fruits.each do |fruit|
+  puts fruit.capitalize
+end
+```

data/files/ruby/data_types/beginner/ruby_hashes.md

@@ -0,0 +1,16 @@
+## 🗂️ Hashes for Key-Value Storage
+
+Hashes (dictionaries) map unique keys to values, allowing fast lookup. Keys are often symbols or strings, and values can be any object. You can add, update, access, and iterate over key-value pairs easily.
+
+```ruby
+# Define a hash
+person = { name: 'Bob', age: 30 }
+# Access a value by key
+puts person[:name]   # => Bob
+# Add or update a key
+person[:occupation] = 'Developer'
+# Iterate over key-value pairs
+person.each do |key, value|
+  puts "#{key}: #{value}"
+end
+```

data/files/ruby/data_types/beginner/ruby_numbers.md

@@ -0,0 +1,14 @@
+## 🔢 Numbers and Basic Arithmetic
+
+Ruby provides Integer and Float types for numeric operations. Integers are whole numbers, while Floats represent decimal values. You can perform arithmetic operations like addition, subtraction, multiplication, and division directly.
+
+```ruby
+# Integer operations
+sum = 2 + 3
+difference = 5 - 1
+
+# Float operations
+average = 4.0 / 2.0
+product = 2 * 3.5
+puts sum, difference, average, product
+```

data/files/ruby/data_types/beginner/ruby_strings.md

@@ -0,0 +1,11 @@
+## 🔤 Working with Strings
+
+Ruby strings are used to represent text in your programs. You can define them with single or double quotes—double-quoted strings support interpolation and escape sequences, making them more flexible.
+
+```ruby
+# Single-quoted string (no interpolation)
+name = 'Alice'
+# Double-quoted string with interpolation and newline
+welcome = "Hello, #{name}!\nWelcome to Ruby."
+puts welcome
+```

data/files/ruby/data_types/beginner/ruby_symbols.md

@@ -0,0 +1,15 @@
+## 🔖 Symbols as Lightweight Identifiers
+
+Symbols are immutable, reusable constants preceded by a colon. They are often used as keys in hashes or to reference method names. Because they are reused, symbols are more memory-efficient than strings for identifiers.
+
+```ruby
+# Define a symbol
+status = :active
+# Compare symbols
+event_state = :active
+puts 'Event is active' if status == event_state
+
+# Use symbols as hash keys
+settings = { theme: 'dark', notifications: true }
+puts settings[:theme]   # => "dark"
+```

data/files/ruby/data_types/expert/custom_numeric_coercion.md

@@ -0,0 +1,36 @@
+## 🔢 Custom Numeric Coercion
+
+Ruby’s `Numeric` protocol allows you to define your own number types that interoperate seamlessly with built‑ins. By implementing the `coerce` method you enable Ruby to reorder mixed operations and delegate them back to your class, preserving type fidelity.
+
+```ruby
+class MyRatio < Numeric
+  attr_reader :num, :den
+  def initialize(num, den=1)
+    @num, @den = num, den
+  end
+
+  def +(other)
+    o = coerce(other).first
+    MyRatio.new(num * o.den + o.num * den, den * o.den).reduce
+  end
+
+  def coerce(other)
+    case other
+    when Numeric
+      [MyRatio.new(other,1), self]
+    else
+      raise TypeError, "#{other.class} can't be coerced into MyRatio"
+    end
+  end
+
+  protected
+  def reduce
+    g = num.gcd(den)
+    MyRatio.new(num/g, den/g)
+  end
+end
+
+r = MyRatio.new(3,4)
+p r + 2       # => MyRatio(11,4)
+p 2 + r       # coerce called, => MyRatio(11,4)
+```

data/files/ruby/data_types/expert/deep_immutable_structures.md

@@ -0,0 +1,22 @@
+## ❄️ Deep Immutable Structures with Refinements
+
+Freezing top‑level objects often leaves nested arrays and hashes mutable. This refinement injects a `deep_freeze` method to recursively freeze every element, locking down entire graphs for thread‑safety and caching use cases.
+
+```ruby
+module DeepFreeze
+  refine Object do
+    def deep_freeze
+      case self
+      when Array then each(&:deep_freeze)
+      when Hash  then each { |k,v| k.deep_freeze; v.deep_freeze }
+      end
+      freeze
+    end
+  end
+end
+
+using DeepFreeze
+config = { users: [{name: 'Alice'}, {name: 'Bob'}], meta: { count: 2 }}
+config.deep_freeze
+# config[:users][0][:name] = 'Eve' # => RuntimeError: can't modify frozen String
+```

data/files/ruby/data_types/expert/high_precision_arithmetic.md

@@ -0,0 +1,18 @@
+## 📈 High‑Precision Arithmetic with Rational & Complex
+
+Combine Ruby’s `Rational`, `Complex`, and `BigDecimal` to avoid floating‑point drift in scientific or financial domains. Leverage the built‑in `coerce` to mix these types seamlessly.
+
+```ruby
+require 'bigdecimal'
+
+r = Rational(22,7)
+bd = BigDecimal('1.23456789')
+c = Complex(r, bd)
+
+# Mixed operations: BigDecimal + Complex will invoke coerce
+sum = bd + c
+product = r * c
+
+puts sum       # => (3.1428571428571428571428571428571429+1.23456789i)
+puts product   # => (3.486804107142857142857142857142857i?)
+```

data/files/ruby/data_types/expert/lazy_infinite_sequences.md

@@ -0,0 +1,24 @@
+## ♾️ Lazy Infinite Enumerables with Enumerator::Lazy
+
+Ruby’s lazy enumerators let you describe potentially infinite sequences without materializing them until needed. Pair them with `take`, `map`, or `select` to derive just the slice you care about.
+
+```ruby
+# Fibonacci sequence as an infinite lazy enumerator
+def fib_stream
+  Enumerator.new do |yielder|
+    a, b = 0, 1
+    loop do
+      yielder << a
+      a, b = b, a + b
+    end
+  end.lazy
+end
+
+# Compute first 10 Fibonacci numbers divisible by 3
+result = fib_stream
+  .select { |n| (n % 3).zero? }
+  .take(10)
+  .to_a
+
+p result # => [0, 3, 21, 144, 987, ...]
+```

data/files/ruby/data_types/expert/pattern_matching_hashes.md

@@ -0,0 +1,22 @@
+## 🧩 Pattern Matching on Complex Hashes
+
+Ruby 2.7+ supports destructuring via pattern matching, letting you concisely extract deeply nested values without manual guards. This is invaluable when handling JSON‑like payloads.
+
+```ruby
+payload = {
+  user: {
+    id: 42,
+    profile: {
+      name: "Carol",
+      stats: { posts: 100, followers: 2500 }
+    }
+  }
+}
+
+case payload
+in { user: { profile: { stats: { posts: posts, followers: f } } } }
+  puts "Posts: #{posts}, Followers: #{f}"
+else
+  puts "Unexpected format"
+end
+```

data/files/ruby/data_types/middle/array_destructuring_splat.md

@@ -0,0 +1,22 @@
+## 🔀 Use Array Destructuring and Splat for Flexible Assignments
+
+Ruby’s multiple assignment combined with the splat operator (`*`) lets you unwrap arrays concisely, extract head/tail elements, or group remaining items without verbose loops.
+
+```ruby
+# Basic parallel assignment
+a, b = [1, 2]         # a = 1, b = 2
+
+# Splat to capture rest of the array
+first, *middle, last = [1, 2, 3, 4, 5]
+# first = 1, middle = [2, 3, 4], last = 5
+
+# Swap variables without temp
+a, b = b, a
+
+# Unpack arguments in method definition
+def process(title, *tags)
+  puts "#{title} (tags: #{tags.join(', ')})"
+end
+
+process('Rails Tips', 'ruby', 'rails', 'performance')
+```

data/files/ruby/data_types/middle/frozen_string_literals.md

@@ -0,0 +1,20 @@
+## ❄️ Freeze Strings for Improved Performance
+
+Mutating string literals creates new objects and increases GC pressure. Use the frozen string literal pragma or `String#freeze` to prevent unnecessary allocations.
+
+```ruby
+# Magic comment at the top of your file:
+# frozen_string_literal: true
+
+def greet(name)
+  # name << "!"  # => raises RuntimeError: can't modify frozen String
+  "Hello, #{name}!"  # no new literal allocated for 'Hello, '
+end
+
+# Explicit freezing
+greeting = "Welcome".freeze
+puts greeting.frozen?  # => true
+# greeting << "!"    # => RuntimeError: can't modify frozen String
+```
+
+Enabling `frozen_string_literal` in modern Ruby (>= 2.3) reduces transient string churn and speeds up your application.

data/files/ruby/data_types/middle/hash_default_proc.md

@@ -0,0 +1,19 @@
+## 🎯 Leverage Hash Default Values vs Default Procs
+
+By default, a hash returns `nil` for missing keys. You can provide a static default or a dynamic one via a proc—but beware of mutable defaults.
+
+```ruby
+# Static default value (shared object!)
+h = Hash.new([])
+h[:a] << 1
+puts h[:b]          # => [1]
+puts h[:a].object_id == h[:b].object_id  # => true
+
+# Dynamic default via proc (avoids sharing)
+h = Hash.new { |hash, key| hash[key] = [] }
+h[:a] << 1
+h[:b] << 2
+puts h              # => {:a=>[1], :b=>[2]}
+```
+
+Use the proc form when you need separate mutable defaults per key, and the static form for simple immutable defaults.

data/files/ruby/data_types/middle/optimize_hash_keys.md

@@ -0,0 +1,17 @@
+## 🔑 Optimize Hash Keys with Symbols
+
+Symbols are immutable and memory‑efficient, making them perfect for hash keys compared to strings. When you use strings as keys, Ruby allocates a new object on each assignment; symbols avoid that overhead.
+
+```ruby
+# Using strings as hash keys allocates new String objects:
+h1 = { "user" => "Alice" }
+h2 = { "user" => "Bob" }
+puts h1.keys.first.object_id == h2.keys.first.object_id  # => false
+
+# Using symbols reuses the same Symbol object:
+h3 = { user: "Alice" }
+h4 = { user: "Bob" }
+puts h3.keys.first.object_id == h4.keys.first.object_id  # => true
+```
+
+Whenever possible, define static keys as symbols. If you need to convert dynamic string keys to symbols, use `to_sym` or `intern` carefully to avoid symbol table bloat.

data/files/ruby/data_types/middle/range_iteration_step.md

@@ -0,0 +1,18 @@
+## 🔢 Harness Ranges for Iteration and Step Incrementation
+
+Ranges are handy for succinct loops, conditional checks, and stepping through numeric sequences or characters without manually managing counters.
+
+```ruby
+# Inclusive and exclusive ranges
+(1..5).each { |n| print n }      # 1 2 3 4 5
+(1...5).to_a                     # [1, 2, 3, 4]
+
+# Step through a range
+(0..10).step(2) { |n| puts n }   # 0, 2, 4, 6, 8, 10
+
+# Checking inclusion
+puts ('a'..'f').cover?('c')     # => true
+puts (1..100).include?(150)      # => false
+```
+
+Use ranges to replace manual loops, improve readability, and leverage built‑in methods like `step`, `cover?`, and `to_a`.

data/files/ruby/date_time/advanced/business_days_enumeration.md

@@ -0,0 +1,18 @@
+## 🚀 Enumerating Business Days with Custom Holiday Calendar
+
+Generate a range of business days by filtering out weekends and custom holidays. Using Ruby’s range and `#select` makes the logic declarative and thread‑safe.
+
+```ruby
+require 'date'
+
+def business_days(start_date, end_date, holidays = [])
+  (start_date..end_date).select do |d|
+    (1..5).cover?(d.wday) && !holidays.include?(d)
+  end
+end
+
+holidays = [Date.new(2022,12,25), Date.new(2023,1,1)]
+range    = business_days(Date.new(2022,12,20), Date.new(2023,1,5), holidays)
+puts range
+# => [2022-12-20, ..., 2022-12-23, 2022-12-26, ..., 2022-12-30, 2023-01-02, ..., 2023-01-05]
+```

data/files/ruby/date_time/advanced/custom_date_parsing.md

@@ -0,0 +1,16 @@
+## 📅 Custom Date Parsing with Fractional Seconds
+
+Ruby’s built‑in parsers may drop subsecond precision. Use `DateTime.strptime` with `%L` or `%Q` to capture milliseconds and microseconds explicitly. This ensures you don’t lose critical timing data.
+
+```ruby
+require 'date'
+
+# Parse ISO8601 with milliseconds
+dt = DateTime.strptime('2022-03-13T15:45:30.123Z', '%Y-%m-%dT%H:%M:%S.%L%Z')
+puts dt.strftime('%Y-%m-%d %H:%M:%S.%L %Z')
+# => "2022-03-13 15:45:30.123 UTC"
+
+# Parse with microseconds (Ruby 2.7+)
+dt2 = DateTime.strptime('2022-03-13T15:45:30.123456Z', '%Y-%m-%dT%H:%M:%S.%6N%Z')
+puts dt2.strftime('%Y-%m-%d %H:%M:%S.%6N %Z')
+```

data/files/ruby/date_time/advanced/high_precision_arithmetic.md

@@ -0,0 +1,15 @@
+## 🧮 High‑Precision DateTime Arithmetic Using Rational
+
+Floating‑point arithmetic can introduce rounding errors in date math. Use `Rational` to represent fractions of a day exactly (1 day = 1, so 1 second = 1/86_400). This preserves nanosecond precision over long intervals.
+
+```ruby
+require 'date'
+
+start_dt = DateTime.now
+# Add 1.5 seconds precisely
+interval = Rational(3, 2) / 86_400
+next_dt  = start_dt + interval
+
+diff_seconds = (next_dt - start_dt) * 86_400
+puts diff_seconds.to_f # => 1.5
+```

data/files/ruby/date_time/advanced/iso8601_duration_handling.md

@@ -0,0 +1,20 @@
+## 🔍 Parsing and Applying ISO8601 Durations with the iso8601 Gem
+
+Ruby doesn’t support ISO8601 durations out of the box. The `iso8601` gem lets you parse `PnYnMnDTnHnMnS` strings and convert them to seconds or directly apply them to a `Time` or `DateTime`.
+
+```ruby
+# Add to your Gemfile:
+# gem 'iso8601'
+require 'iso8601'
+require 'date'
+
+duration = ISO8601::Duration.new('P1Y2M10DT2H30M')
+start_dt = DateTime.parse('2022-01-01T00:00:00Z')
+# Compute end datetime
+end_dt   = start_dt >> (duration.years * 12 + duration.months)
+end_dt   = end_dt + Rational(duration.days, 1)
+end_dt   = end_dt + Rational(duration.hours * 3600 + duration.minutes * 60 + duration.seconds, 86_400)
+
+puts end_dt.iso8601
+# => "2023-03-11T02:30:00+00:00"
+```

data/files/ruby/date_time/advanced/timezone_conversion.md

@@ -0,0 +1,17 @@
+## 🕰️ Timezone Conversion with ActiveSupport::TimeZone
+
+When working with multiple timezones, avoid manual UTC offsets and leverage ActiveSupport::TimeZone for accurate DST handling. Use `in_time_zone`, `Time.zone.local` and `Time.zone.parse` to ensure conversions respect zone definitions.
+
+```ruby
+require 'active_support/all'
+
+Time.zone = 'America/New_York'
+# Parse a string in the configured zone
+local_time = Time.zone.parse('2022-11-06 01:30')
+# Convert a UTC time to the configured zone
+utc_time   = Time.utc(2022, 11, 06, 5, 30)
+ny_time    = utc_time.in_time_zone
+
+puts local_time # => 2022-11-06 01:30:00 -0400
+puts ny_time    # => 2022-11-06 01:30:00 -0500 (DST end)
+```

data/files/ruby/date_time/beginner/date_arithmetic.md

@@ -0,0 +1,15 @@
+## ➕ Performing Date Arithmetic
+
+Ruby allows you to add or subtract days directly on `Date` objects, and subtracting one date from another yields a `Rational` difference in days.
+
+```ruby
+require 'date'
+
+start_date = Date.new(2023, 3, 1)
+end_date = start_date + 14  # adds 14 days
+puts end_date       # => 2023-03-15
+
+# Difference in days
+days_between = end_date - start_date
+puts days_between.to_i  # => 14
+```

data/files/ruby/date_time/beginner/formatting_dates_times.md

@@ -0,0 +1,18 @@
+## ✨ Formatting Dates and Times
+
+Use `strftime` to output dates and times in custom formats. You pass a format string with percent directives to control output.
+
+```ruby
+require 'date'
+
+date = Date.new(2023, 3, 15)
+time = Time.new(2023, 3, 15, 14, 30)
+
+# Date formatting
+echo = date.strftime("%B %d, %Y")
+puts echo         # => "March 15, 2023"
+
+# Time formatting
+puts time.strftime("%Y-%m-%d %H:%M:%S %Z")
+# => "2023-03-15 14:30:00 UTC"
+```

data/files/ruby/date_time/beginner/getting_current_date_time.md

@@ -0,0 +1,15 @@
+## 🕒 Getting Current Date and Time
+
+Ruby provides two core classes for date and time: `Date` (for dates only) and `Time` (for full timestamps). Use `Date.today` to fetch just the date, and `Time.now` for both date and time with system timezone and precision.
+
+```ruby
+require 'date'
+
+# Get current date
+today = Date.today
+puts today        # => 2023-03-15
+
+# Get current date and time
+time_now = Time.now
+puts time_now     # => 2023-03-15 14:30:00 +0000
+```

data/files/ruby/date_time/beginner/handling_time_zones.md

@@ -0,0 +1,17 @@
+## 🌐 Handling Time Zones
+
+Working with time zones ensures your app displays correct local times. Use `Time.now.getlocal` or create a `Time`/`DateTime` object with an offset.
+
+```ruby
+# Current time in local zone
+time_local = Time.now.getlocal
+puts time_local   # => 2023-03-15 10:30:00 -0400
+
+# Create a Time with specific offset
+time_with_offset = Time.new(2023, 3, 15, 14, 30, 0, "+02:00")
+puts time_with_offset  # => 2023-03-15 14:30:00 +0200
+
+# DateTime with zone
+dt = DateTime.new(2023,3,15,14,30,0,"-05:00")
+puts dt           # => 2023-03-15T14:30:00-05:00
+```

data/files/ruby/date_time/beginner/parsing_date_strings.md

@@ -0,0 +1,15 @@
+## 📅 Parsing Date Strings
+
+Converting user input or string data into `Date` or `DateTime` objects lets you perform calculations and validations. Ruby’s `parse` methods handle common formats automatically.
+
+```ruby
+require 'date'
+
+# Parse a simple date string
+date = Date.parse('2023-03-15')
+puts date         # => #<Date: 2023-03-15 ((2459993j,0s,0n),+0s,2299161j)>
+
+# Parse ISO 8601 timestamp to DateTime
+datetime = DateTime.parse('2023-03-15T14:30:00+02:00')
+puts datetime     # => 2023-03-15T14:30:00+02:00
+```

data/files/ruby/date_time/expert/astronomical_julian_day_conversion.md

@@ -0,0 +1,18 @@
+## 🌌 Astronomical Calculations with Julian Day
+
+Under the hood, Ruby’s `Date` and `DateTime` use Julian Day (JD) for calendar arithmetic. You can leverage `Date#jd` and `Date.jd` (or `Date#civil_to_jd`) to perform precise astronomical computations, such as calculating the date of an eclipse or converting to Modified Julian Day.
+
+Example: convert a UTC timestamp into JD and back:
+
+```ruby
+require 'date'
+# Convert a civil date to Julian day
+jd = DateTime.new(2024, 6, 30, 12, 0, 0, '+00:00').jd
+# Perform an offset (+1.5 days)
+new_jd = jd + 1.5
+# Convert back to DateTime
+dt = DateTime.jd(new_jd)
+puts "Original JD: #{jd}, After 1.5 days: #{dt.iso8601}"
+```
+
+This gives sub-day precision—essential for telescope scheduling or astrodynamics.

data/files/ruby/date_time/expert/business_calendar_refinement.md

@@ -0,0 +1,31 @@
+## 📆 Refinement-based Business Calendar
+
+To avoid polluting the global `Date` class while adding domain‑specific logic (e.g., business days excluding weekends and holidays), use a `Module` with refinements. You get scoped extensions and can easily switch calendars per context.
+
+Example: define and use a refined business calendar:
+
+```ruby
+module BusinessCalendar
+  refine Date do
+    HOLIDAYS = [Date.new(2024, 1, 1), Date.new(2024, 12, 25)]
+
+    def business_day?
+      !(saturday? || sunday? || HOLIDAYS.include?(self))
+    end
+
+    def advance_business(days)
+      date = self
+      days.abs.times do
+        date += days.positive? ? 1 : -1
+        redo unless date.business_day?
+      end
+      date
+    end
+  end
+end
+
+using BusinessCalendar
+puts Date.today.advance_business(10)  # skips weekends & holidays
+```
+
+This pattern gives you full control over core refinements and keeps your calendar logic isolated.

data/files/ruby/date_time/expert/high_res_monotonic_timing.md

@@ -0,0 +1,16 @@
+## 🕰️ High-Resolution Monotonic Timing
+
+When profiling or benchmarking critical code paths, relying on `Time.now` can introduce errors due to NTP adjustments or clock drift. Instead, use the OS’s monotonic clock via `Process.clock_gettime(Process::CLOCK_MONOTONIC)` for nanosecond precision and immunity to system time changes.
+
+Example: benchmarking a database call:
+
+```ruby
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+# ... expensive operation ...
+result = MyDatabase.query("SELECT * FROM users")
+finish = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+elapsed_ns = ((finish - start) * 1_000_000_000).to_i
+puts "Query took #{elapsed_ns} ns"
+```
+
+You can wrap this in a helper to automatically handle conversion to ms or µs without polluting global scope.

data/files/ruby/date_time/expert/leap_second_wrapper.md

@@ -0,0 +1,36 @@
+## 🎛️ Custom Leap Second Handling
+
+Ruby’s core `Time`/`DateTime` ignores leap seconds, leading to subtle off‑by‑one-second errors in physics or telecom domains. Maintain an external leap‑second table (from IERS) and wrap conversions to adjust UTC ↔ TAI properly.
+
+Example: lightweight leap‑second wrapper:
+
+```ruby
+require 'date'
+LEAP_SECONDS = {
+  DateTime.new(2016,12,31,23,59,60,'+00:00') => 1,
+  # ... load from official table ...
+}
+
+class LeapTime
+  def initialize(dt)
+    @dt = dt
+  end
+
+  # Returns TAI (International Atomic Time) offset in seconds
+  def to_tai
+    offset = LEAP_SECONDS.select { |d,_| d <= @dt }.values.sum
+    @dt.to_time.to_i + offset
+  end
+
+  # Convert TAI seconds back to UTC DateTime
+  def self.from_tai(tai_sec)
+    # reverse lookup: subtract cumulative leap seconds
+    dt = Time.at(tai_sec).utc.to_datetime
+    corrections = LEAP_SECONDS.select { |d,_| d <= dt }.values.sum
+    (Time.at(tai_sec - corrections).utc).to_datetime
+  end
+end
+
+dt = DateTime.now.new_offset(0)
+puts "TAI seconds: #{LeapTime.new(dt).to_tai}"
+```

data/files/ruby/date_time/expert/tzinfo_caching.md

@@ -0,0 +1,23 @@
+## ⌛ TZInfo Caching for High-Throughput Time Zone Conversions
+
+Repeatedly resolving time zones can be expensive under heavy load. By caching the `Timezone` object and its transition periods, you minimize lookups and GC overhead in hot paths.
+
+Example: thread‑local caching of a TZInfo period:
+
+```ruby
+require 'tzinfo'
+module FastTZ
+  def self.local_time(zone_name, utc_time)
+    tz = Thread.current[:tz_cache] ||= {}
+    tz[zone_name] ||= TZInfo::Timezone.get(zone_name)
+    period = tz[zone_name].period_for_utc(utc_time)
+    period.to_local(utc_time)
+  end
+end
+
+utc = Time.now.utc
+ny = FastTZ.local_time('America/New_York', utc)
+puts ny.strftime('%Y-%m-%d %H:%M:%S %Z')
+```
+
+By reusing `Timezone` instances per thread and caching periods, you drastically reduce overhead when converting millions of timestamps.