ruby-temporal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca52af9ee124f93b4d3992cd1a0b05cc3d7c20299dad22cbf47b711c94765bd1
+  data.tar.gz: ec3a36d0b0714f24751b0eb416ce2b5fc94e9969735dea98658848dfc67ec768
+SHA512:
+  metadata.gz: 0ee0b1ea084f251371a3e5fd4e0d075f85de4dab8c960a8742d8362cdd5b1d110b9cf866054c0f5b9cd5c7ffc0927ec63d7e46affc76756c97cbae1c3775a561
+  data.tar.gz: '03787383471ade7b8e79b1531942b6d0cd43501bfd87350e3582f32bb10127d6e3cdee24be19cef09acde1e38953239ddb1d1c444da747ee32c03db06b091766'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-04
+
+- Create Temporal base classes with only constructor definition. Other methods will be defined in later releases.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ruby-temporal" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["leonardoprado@gmail.com"](mailto:"leonardoprado@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Leonardo Prado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# Ruby Temporal
+
+This gem is a implementation of TC39 Temporal API.
+
+## Specification
+
+This gem aims to be a direct implementation from the original spec, with only small changes to adapt it to Ruby sinatx and idioms.
+
+To achieve this, we are using as a base all specs from [test262 repo](https://github.com/tc39/test262). We converted their logic from JavaScript to Ruby using minitest with the exception of languiage specific tests, like `prototype`, for example.
+
+The tests are being created using commit `d8d4c064` as reference. Changes from later commits will be added after the initial implementation is completed.
+
+The planned tests are the following:
+
+| Original test path | Path on gem tests|
+| --- | --- |
+| test/built-ins/Temporal | test/test262/built-ins/ |
+| test/intl402/Temporal   | test/test262/intl402/   |
+
+## Installation
+
+```bash
+bundle add temporal
+# or
+gem install temporal
+```
+
+## Usage
+
+Instructions will be made after the API is defined and implemented.
+
+The official usage reference from original implementation can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` or `minitest` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+The objective of initial development is to implement all test262 specs. We are doing it using TDD, without specific focus on being idiomatic, performant or DRY. Those are reserved for the next step in the project.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/DNA/ruby-temporal. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/DNA/ruby-temporal/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ruby-temporal project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/DNA/ruby-temporal/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/temporal/duration.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Temporal
+  class Duration
+    UNIT_LIMITS = {
+      year:    4_294_967_296,         #  2**32
+      month:   4_294_967_296,         #  2**32
+      week:    4_294_967_296,         #  2**32
+      days:    104_249_991_375,       # (2**53 / 86_400.0).ceil | 2**53 is based
+      hours:   2_501_999_792_984,     # (2**53 / 86_400.0).ceil | on EcmaScript
+      minutes: 150_119_987_579_017,   # (2**53 / 86_400.0).ceil | Number.MAX_SAFE_INTEGER
+      seconds: 9_007_199_254_740_992, #  2**53
+    }.freeze
+
+    UNITS = %i[years months days
+               hours minutes seconds weeks
+               milliseconds microseconds nanoseconds].freeze
+
+    attr_reader(*UNITS)
+
+    def initialize(years = nil, months = nil, weeks = nil, days = nil,
+                   hours = nil, minutes = nil, seconds = nil,
+                   milliseconds = nil, microseconds = nil, nanoseconds = nil)
+      values = [years, months, weeks, days,
+                hours, minutes, seconds,
+                milliseconds, microseconds, nanoseconds]
+      values.map! do |v|
+        case v
+        in 0 then nil
+        in String then v.to_i
+        in Numeric then v
+        else nil
+        end
+      end
+
+      values.uniq!.compact!
+
+      unless values.all?(&:positive?) || values.all?(&:negative?)
+        raise RangeError, "Can't mix positive and negative numbers"
+      end
+
+      self.years        = years
+      self.months       = months
+      self.weeks        = weeks
+      self.days         = days
+      self.hours        = hours
+      self.minutes      = minutes
+      self.seconds      = seconds
+      self.milliseconds = milliseconds
+      self.microseconds = microseconds
+      self.nanoseconds  = nanoseconds
+
+      overboard
+    end
+
+    def total(unit)
+      if unit == :seconds
+        (days * 86_400) +
+          (hours * 3600) +
+          (minutes * 60) +
+          seconds +
+          (((milliseconds * 1_000_000) +
+            (microseconds * 1_000) +
+            nanoseconds
+           ) / 1_000_000_000.0)
+      else
+        0
+      end
+    end
+
+    private
+
+    def overboard
+      overboard_unit(:nanoseconds,  :microseconds, 1000)
+      overboard_unit(:microseconds, :milliseconds, 1000)
+      overboard_unit(:milliseconds, :seconds,      1000)
+      overboard_unit(:seconds,      :minutes,      60)
+      overboard_unit(:minutes,      :hours,        60)
+      overboard_unit(:hours,        :days,         24)
+    end
+
+    def overboard_unit(from, to, mod)
+      from_value   = send(from)
+      to_value     = send(to)
+      carry, value = from_value.abs.divmod(mod)
+
+      if from_value.negative?
+        value = -value
+        carry = -carry
+      end
+
+      send(:"#{from}=", value)
+      send(:"#{to}=", to_value + carry) unless carry.zero?
+    end
+
+    def years=(value)
+      @years = convert_type(value, 4_294_967_296)
+    end
+
+    def months=(value)
+      @months = convert_type(value, 4_294_967_296)
+    end
+
+    def weeks=(value)
+      @weeks = convert_type(value, 4_294_967_296)
+    end
+
+    def days=(value)
+      @days = convert_type(value, 104_249_991_375)
+    end
+
+    def hours=(value)
+      @hours = convert_type(value, 2_501_999_792_984)
+    end
+
+    def minutes=(value)
+      @minutes = convert_type(value, 150_119_987_579_017)
+    end
+
+    def seconds=(value)
+      @seconds = convert_type(value, 9_007_199_254_740_992)
+    end
+
+    def milliseconds=(value)
+      @milliseconds = convert_type(value)
+    end
+
+    def microseconds=(value)
+      @microseconds = convert_type(value)
+    end
+
+    def nanoseconds=(value)
+      @nanoseconds = convert_type(value)
+    end
+
+    def convert_type(value, limit = nil)
+      value = case value
+              in Float
+                raise RangeError, "Can't use fractional values" unless value == value.truncate
+
+                value.to_i
+              in Numeric then value.to_i
+              in NilClass then 0
+              in String then Integer(value)
+              else raise TypeError
+              end
+
+      if limit
+        raise RangeError if value >= limit
+        raise RangeError if value <= -limit
+      end
+
+      value
+    end
+  end
+end

data/lib/temporal/instant.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Temporal
+  MAX_TIMESTAMP = 8_640_000_000_000_000_000
+
+  class Instant
+    def initialize(timestamp)
+      self.timestamp = timestamp
+    end
+
+    def epoch_milliseconds = (@timestamp / 1_000_000_000).truncate
+    def epoch_nanoseconds =  @timestamp / 1_000
+
+    private
+
+    def timestamp=(value)
+      value = Float(value)
+
+      raise RangeError, "timestamp overflow"  if value >  MAX_TIMESTAMP
+      raise RangeError, "timestamp underflow" if value < -MAX_TIMESTAMP
+
+      @timestamp = value * 1_000
+    rescue TypeError, ArgumentError => e
+      raise TypeError, "Invalid string for timestamp", cause: e
+    end
+  end
+end

data/lib/temporal/now.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Temporal
+  class Now
+    def self.time_zone_id = "UTC"
+
+    def self.instant
+      Temporal::Instant.new(now.to_f)
+    end
+
+    def self.plain_date_iso(tz = nil)
+      t = now(tz)
+      Temporal::PlainDate.new(t.year, t.month, t.day)
+    end
+
+    def self.plain_date_time_iso(tz = nil)
+      t = now(tz)
+      Temporal::PlainDateTime.new(t.year, t.month, t.day, t.hour, t.min, t.sec)
+    end
+
+    def self.plain_time_iso(tz = nil)
+      t = now(tz)
+      Temporal::PlainTime.new(t.hour, t.min, t.sec)
+    end
+
+    def self.zoned_date_time_iso(tz = "UTC")
+      Temporal::ZonedDateTime.new(now(tz).to_f, tz: validate_timezone(tz))
+    end
+
+    def self.now(tz = nil)
+      if tz
+        Time.now(in: validate_timezone(tz))
+      else
+        Time.now
+      end
+    end
+
+    ISO_TZ_OFFSET    = /[+-]\d\d:?\d\d/ #  +12:34   -12:34   +1234   -1234
+    ENDLINE_OFFSET   = /#{ISO_TZ_OFFSET}$/o #  +12:34$  -12:34$  +1234$  -1234$
+    BRACKETED_OFFSET = /\[(#{ISO_TZ_OFFSET})\]/o # [+12:34] [-12:34] [+1234] [-1234]
+    IANA_TZ          = /\[(\w+)\]/               # [ISO]
+
+    def self.validate_timezone(value)
+      value = value.downcase if value.respond_to? :downcase
+
+      case value
+      in "a".."i" | "k".."z"
+        value.upcase
+      in "utc" | "UTC" | /z$/
+        "UTC"
+      in IANA_TZ
+        value[IANA_TZ, 1]
+      in BRACKETED_OFFSET
+        value[BRACKETED_OFFSET, 1]
+      in ENDLINE_OFFSET
+        value[ENDLINE_OFFSET]
+      else
+        raise RangeError, "Invalid value `#{value}` for timezone"
+      end
+    end
+  end
+end

data/lib/temporal/plain_date.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Temporal
+  class PlainDate
+    attr_reader :year, :month, :day, :calendar_id
+
+    def initialize(year, month, day, calendar_id: nil)
+      @year = Units::Year.new(year)
+      @month = Units::Month.new(month, @year)
+      @day = Units::Day.new(day, @month)
+      @month.lower = @day
+      self.calendar_id = calendar_id
+    end
+
+    def month_code = :"#{format("M%02d", month)}"
+
+    def era_year = nil
+
+    def era = nil
+
+    def add(hash = {}, **kwargs)
+      raise ArgumentError unless hash.instance_of? Hash
+
+      values = hash.merge kwargs
+      raise ArgumentError if values.empty?
+
+      unit_keys = %i[years months weeks days hours minutes
+                     seconds milliseconds microseconds nanoseconds]
+
+      units = values.slice(*unit_keys)
+
+      raise ArgumentError, "No valid unit found" if units.empty?
+
+      raise RangeError, "Can't mix positive and negative numbers" unless
+        units.values.reject(&:zero?).all?(&:positive?) ||
+        units.values.reject(&:zero?).all?(&:negative?)
+
+      @day += values[:days] || 0
+      @month += values[:months] || 0
+      @year += values[:years] || 0
+
+      self
+    end
+
+    def ==(other)
+      @year == other.year &&
+        @month == other.month &&
+        @day == other.day
+    end
+
+    private
+
+    def calendar_id=(value)
+      value = case value
+              in Symbol then value
+              in String then value.downcase.to_sym
+              in NilClass then :iso8601
+              else raise RangeError
+              end
+
+      raise RangeError if value != :iso8601
+
+      @calendar_id = value
+    end
+  end
+end

data/lib/temporal/plain_date_time.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Temporal
+  class PlainDateTime
+    def initialize(year, month, day, hour = 0, minute = 0, second = 0,
+                   millisecond = 0, microsecond = 0, nanosecond = 0,
+                   calendar_id: nil)
+      @date = PlainDate.new(year, month, day, calendar_id: calendar_id)
+      @time = PlainTime.new(hour, minute, second, millisecond, microsecond, nanosecond)
+    end
+
+    def year        = @date.year
+    def month       = @date.month
+    def day         = @date.day
+    def era         = @date.era
+    def era_year    = @date.era_year
+    def month_code  = @date.month_code
+
+    def hour        = @time.hour
+    def minute      = @time.minute
+    def second      = @time.second
+    def millisecond = @time.millisecond
+    def microsecond = @time.microsecond
+    def nanosecond  = @time.nanosecond
+    def calendar_id = @date.calendar_id
+  end
+end

data/lib/temporal/plain_month_day.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Temporal
+  class PlainMonthDay
+    attr_reader :month, :day, :calendar_id
+
+    IMPLICIT_YEAR = 1972
+
+    def initialize(month, day, year: nil, calendar_id: nil)
+      @year = (Units::Year.new(year) if year)
+      @month = Units::Month.new(month, @year)
+      @day = Units::Day.new(day, @month)
+      @month.lower = @day
+      self.calendar_id = calendar_id
+    end
+
+    def year
+      @year || IMPLICIT_YEAR
+    end
+
+    def month_code = :"#{format("M%02d", month)}"
+
+    def era = nil
+
+    def to_s(calendar_name: nil)
+      if calendar_name == :always
+        "#{year}-#{@month}-#{@day}[u-ca=#{calendar_id}]"
+      elsif year
+        "#{year}-#{@month}-#{@day}"
+      else
+        "#{@month}-#{@day}"
+      end
+    end
+
+    private
+
+    def calendar_id=(value)
+      value = case value
+              in Symbol then value
+              in String then value.downcase.to_sym
+              in NilClass then :iso8601
+              else raise RangeError
+              end
+
+      raise RangeError if value != :iso8601
+
+      @calendar_id = value
+    end
+  end
+end

data/lib/temporal/plain_time.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Temporal
+  class PlainTime
+    attr_reader :hour, :minute, :second, :millisecond, :microsecond, :nanosecond
+
+    def initialize(hour = 0, minute = 0, second = 0,
+                   millisecond = 0, microsecond = 0, nanosecond = 0)
+      self.hour = hour
+      self.minute = minute
+      self.second = second
+      self.millisecond = millisecond
+      self.microsecond = microsecond
+      self.nanosecond = nanosecond
+    end
+
+    def hour=(value)
+      @hour = case value
+              in (..-1)
+                raise RangeError, "Hour can't be negative"
+              in (24..)
+                raise RangeError, "Hour can't be bigger than 23"
+              else
+                value.to_i
+              end
+    end
+
+    def minute=(value)
+      @minute = case value
+                in (..-1)
+                  raise RangeError, "Minute can't be negative"
+                in (59..)
+                  raise RangeError, "Minute can't be bigger than 59"
+                else
+                  value.to_i
+                end
+    end
+
+    def second=(value)
+      @second = case value
+                in (..-1)
+                  raise RangeError, "Second can't be negative"
+                in (59..)
+                  raise RangeError, "Second can't be bigger than 59"
+                else
+                  value.to_i
+                end
+    end
+
+    def millisecond=(value)
+      @millisecond = case value
+                     in (..-1)
+                       raise RangeError, "Millisecond can't be negative"
+                     in (999..)
+                       raise RangeError, "Millisecond can't be bigger than 999"
+                     else
+                       value.to_i
+                     end
+    end
+
+    def microsecond=(value)
+      @microsecond = case value
+                     in (..-1)
+                       raise RangeError, "Microsecond can't be negative"
+                     in (999..)
+                       raise RangeError, "Microsecond can't be bigger than 999"
+                     else
+                       value.to_i
+                     end
+    end
+
+    def nanosecond=(value)
+      @nanosecond = case value
+                    in (..-1)
+                      raise RangeError, "Nanosecond can't be negative"
+                    in (999..)
+                      raise RangeError, "Nanosecond can't be bigger than 999"
+                    else
+                      value.to_i
+                    end
+    end
+  end
+end

data/lib/temporal/plain_year_month.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Temporal
+  class PlainYearMonth
+    attr_reader :year, :month, :calendar_id
+
+    IMPLICIT_DAY = 1
+
+    def initialize(year, month, day: nil, calendar_id: nil)
+      @year = Units::Year.new(year)
+      @month = Units::Month.new(month, @year)
+      self.calendar_id = calendar_id
+
+      return unless day
+
+      @day = Units::Day.new(day, @month)
+      @month.lower = @day
+    end
+
+    def day = @day || IMPLICIT_DAY
+
+    def month_code = :"#{format("M%02d", month)}"
+
+    def era = nil
+
+    def era_year = nil
+
+    def to_s(calendar_name: nil)
+      if calendar_name == :always
+        "%4d-%02d-%02d[u-ca=%s]" % [@year, @month, day, calendar_id]
+      elsif day
+        "%4d-%02d-%02d" % [@year, @month, day]
+      else
+        "%4d-%02d" % [@year, @month]
+      end
+    end
+
+    private
+
+    def calendar_id=(value)
+      value = case value
+              in Symbol then value
+              in String then value.downcase.to_sym
+              in NilClass then :iso8601
+              else raise RangeError
+              end
+
+      raise RangeError if value != :iso8601
+
+      @calendar_id = value
+    end
+  end
+end

data/lib/temporal/units/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Temporal::Units
+  class Base
+    include Comparable
+
+    def initialize(value)
+      self.value = value
+    end
+
+    def <=>(other) = @value <=> other
+
+    def ==(other) = @value == other
+
+    def +(other) = self.class.new(@value + other)
+
+    def -(other) = self.class.new(@value - other)
+
+    def to_s = @value.to_s
+
+    def to_i = @value.to_i
+
+    def to_f = @value.to_f
+
+    def inspect
+      "<#{self.class} @value=#{@value} @reference=#{@reference}>"
+    end
+
+    private
+
+    def value=(value)
+      raise TypeError, "Value for month must respond to #to_i" unless value.respond_to? :to_i
+
+      value ||= 0
+
+      @value = Float(value).to_i
+    rescue ArgumentError
+      raise TypeError, "Value can't be converted into a number"
+    end
+  end
+end

data/lib/temporal/units/day.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Temporal::Units
+  class Day < Base
+    def initialize(value, upper)
+      @upper = upper
+
+      super(value)
+    end
+
+    def max_value = @upper.max_day
+
+    def over_value = max_value + 1
+
+    def +(other)
+      sum = @value + other
+
+      @value = case sum
+               when (..0)
+                 @upper -= 1
+                 max_value - sum.abs
+               when (over_value..)
+                 @upper += 1
+                 sum - max_value + 1
+               else
+                 sum
+               end
+      self
+    end
+
+    def -(other)
+      sum = @value - other
+
+      @value = case sum
+               when (..0)
+                 @upper -= 1
+                 max_value - sum.abs
+               when (over_value..)
+                 @upper += 1
+                 sum - max_value
+               else
+                 sum
+               end
+
+      self
+    end
+
+    private
+
+    def value=(value)
+      int = super
+
+      case int.to_i
+      when (..0)
+        raise RangeError, "Day must be bigger than zero"
+      when (over_value...)
+        raise RangeError, "Day #{int} for month #{@upper} can't be bigger than #{max_value}"
+      else
+        @value = int.to_i
+      end
+    end
+  end
+end

data/lib/temporal/units/month.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Temporal::Units
+  class Month < Base
+    attr_reader :lower
+
+    def initialize(value, year = nil)
+      @year = year
+
+      super(value)
+    end
+
+    def on_leap_year? = @year.nil? || (@year.respond_to?(:leap?) && @year.leap?)
+
+    def max_day
+      case [@value, on_leap_year?]
+      in [1 | 3 | 5 | 7 | 8 | 10 | 12, *]
+        31
+      in [4 | 6 | 9 | 11, *]
+        30
+      in [2, true]
+        29
+      in [2, false]
+        28
+      end
+    end
+
+    def lower=(unit)
+      @lower = case unit
+               in Integer, Float then Day.new(unit)
+               in String then Day.new(unit.to_i)
+               in Day then unit
+               else raise ArgumentError, "Month lower unit must be a number or instance of Day"
+               end
+    end
+
+    def +(other)
+      sum = @value + other
+
+      @value = case sum
+               when (..0)
+                 @year = @year.send(:-, 1, inplace: true)
+                 12 - sum.abs
+               when (13..)
+                 @year = @year.send(:+, 1, inplace: true)
+                 sum - 12
+               else
+                 sum
+               end
+
+      if @lower > max_day
+        diff = max_day - @lower.to_i
+
+        @lower += diff
+      end
+
+      self
+    end
+
+    def -(other)
+      sum = @value - other
+
+      @value = case sum
+               when (..0)
+                 @year = @year.send(:+, 1, inplace: true)
+                 12 + sum
+               when (13..)
+                 @year = @year.send(:-, 1, inplace: true)
+                 sum - 12
+               else
+                 sum
+               end
+
+      if @lower > max_day
+        diff = max_day - @lower.to_i
+
+        @lower += diff
+      end
+
+      self.class.new(sum, @year)
+    end
+
+    private
+
+    def value=(value)
+      int = super
+
+      case int.to_i
+      when (..0)
+        raise RangeError, "Month must be bigger than zero"
+      when (13..)
+        raise RangeError, "Month must be less than 13"
+      else
+        @value = int.to_i
+      end
+    end
+  end
+end

data/lib/temporal/units/year.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Temporal::Units
+  class Year < Base
+    def leap? = (@value % 4).zero?
+
+    def +(other, inplace: true)
+      result = @value + other
+
+      @value = result if inplace
+
+      self.class.new(result)
+    end
+
+    def -(other, inplace: true)
+      result = @value - other
+
+      @value = result if inplace
+
+      self.class.new(result)
+    end
+
+    private
+
+    def value=(value)
+      value = case value
+              in true then 1
+              in false then 0
+              else value
+              end
+
+      super
+    end
+  end
+end

data/lib/temporal/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Temporal
+  VERSION = "0.1.0"
+end

data/lib/temporal/zoned_date_time.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Temporal
+  class ZonedDateTime
+    MAX_TIMESTAMP = 864 * (10**19)
+    MIN_TIMESTAMP = -MAX_TIMESTAMP
+
+    attr_reader :calendar_id
+
+    def initialize(timestamp, tz: "UTC", calendar_id: nil)
+      raise RangeError, "Timestamp underflow" if timestamp < MIN_TIMESTAMP
+      raise RangeError, "Timestamp overflow"  if timestamp > MAX_TIMESTAMP
+
+      self.timezone = tz
+      self.calendar_id = calendar_id
+
+      seconds, nanosecond = timestamp.divmod(1_000_000_000)
+
+      @time = Time.at(seconds, nanosecond, :nanosecond, in: tz)
+      @timestamp = timestamp
+    end
+
+    def year        = @time.year
+    def month       = @time.month
+    def day         = @time.day
+    def era         = @time.era
+    def era_year    = @time.era_year
+    def month_code = :"#{format("M%02d", @time.month)}"
+
+    def hour        = @time.hour
+    def minute      = @time.min
+    def second      = @time.sec
+    def millisecond = (@time.subsec.to_f * 1_000).to_i
+    def microsecond = @time.usec % 1_000
+    def nanosecond  = @time.nsec % 1_000
+
+    def epoch_milliseconds = (@time.to_f * 1_000).to_i
+    def epoch_nanoseconds = @timestamp
+
+    def day_of_week = @time.wday
+    def day_of_year = @time.yday
+    def week_of_year = (@time.yday / 7) + 1
+    def days_in_week = 7
+    def days_in_month = 30
+    def days_in_year = 366
+    def months_in_year = 12
+    def leap_year? = true
+    def offset = "+00:00"
+    def offset_nanoseconds = 0
+
+    def time_zone_id = @timezone.upcase
+
+    def to_s = "#{@time.inspect[..-5]}+00:00[UTC]".tr(" ", "T")
+
+    private
+
+    def timezone=(value)
+      @timezone = case value
+                  in "a".."i" | "k".."z" | "utc" | "UTC"
+                    value.upcase
+                  in /(\+|-)\d\d:\d\d/
+                    value
+                  else
+                    raise RangeError, "Invalid value `#{value}` for timezone"
+                  end
+    end
+
+    def calendar_id=(value)
+      value = case value
+              in Symbol then value
+              in String then value.downcase.to_sym
+              in NilClass then :iso8601
+              else raise RangeError
+              end
+
+      raise RangeError if value != :iso8601
+
+      @calendar_id = value
+    end
+  end
+end

data/lib/temporal.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "temporal/duration"
+require_relative "temporal/instant"
+require_relative "temporal/now"
+require_relative "temporal/plain_date"
+require_relative "temporal/plain_date_time"
+require_relative "temporal/plain_month_day"
+require_relative "temporal/plain_time"
+require_relative "temporal/plain_year_month"
+require_relative "temporal/units/base"
+require_relative "temporal/units/day"
+require_relative "temporal/units/month"
+require_relative "temporal/units/year"
+require_relative "temporal/version"
+require_relative "temporal/zoned_date_time"
+
+module Temporal
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.3"

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: ruby-temporal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leonardo Prado
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-06 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- leonardoprado@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/temporal.rb
+- lib/temporal/duration.rb
+- lib/temporal/instant.rb
+- lib/temporal/now.rb
+- lib/temporal/plain_date.rb
+- lib/temporal/plain_date_time.rb
+- lib/temporal/plain_month_day.rb
+- lib/temporal/plain_time.rb
+- lib/temporal/plain_year_month.rb
+- lib/temporal/units/base.rb
+- lib/temporal/units/day.rb
+- lib/temporal/units/month.rb
+- lib/temporal/units/year.rb
+- lib/temporal/version.rb
+- lib/temporal/zoned_date_time.rb
+- mise.toml
+homepage: https://github.com/DNA/ruby-temporal
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/DNA/ruby-temporal
+  source_code_uri: https://github.com/DNA/ruby-temporal
+  changelog_uri: https://github.com/DNA/ruby-temporal/blob/main/README.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby implementation of TC39 Temporal API.
+test_files: []