jscalendar 0.1.0

data/lib/jscalendar/calendar.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Jscalendar
+  class Model
+    def self.build(**properties)
+      data = { "@type" => name.split("::").last }
+      data.merge!("uid" => SecureRandom.uuid, "updated" => Time.now.utc.iso8601) if %w[Event Task Group].include?(data["@type"])
+      data.merge!(camel_properties(properties))
+      item = new(data)
+      yield item if block_given?
+      item.validate!
+    end
+
+    def self.camel_properties(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [key.is_a?(Symbol) ? key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase } : key, camel_properties(item)] }
+      when Array then value.map { |item| camel_properties(item) }
+      else value
+      end
+    end
+
+    def localize(language)
+      patch = @data.fetch("localizations", {})[language]
+      return self.class.new(to_h, time_zones: @time_zones, **@limits) unless patch
+
+      data = PatchObject.new(PatchObject.localization(patch), **@limits).apply(to_h, validate: false)
+      data["locale"] = language
+      self.class.new(data, strict: true, time_zones: @time_zones, **@limits)
+    end
+  end
+
+  module RecurringCalendar
+    def start_time(time_zone: nil)
+      value = @data["start"] || @data["due"]
+      raise ValidationError, "calendar has no start or due" unless value
+
+      zone = @data["timeZone"] || time_zone
+      raise UnsupportedError, "floating time requires time_zone" unless zone
+
+      TimeZoneResolver.new(zone, effective_time_zones).to_utc(LocalDateTime.new(value))
+    end
+
+    def end_time(time_zone: nil)
+      zone = @data["timeZone"] || time_zone
+      raise UnsupportedError, "floating time requires time_zone" unless zone
+
+      return TimeZoneResolver.new(zone, effective_time_zones).to_utc(LocalDateTime.new(@data["due"])) if is_a?(Task) && @data["due"]
+
+      duration = Duration.new(@data.fetch("duration", "PT0S"))
+      local = duration.add_to(@data.fetch("start"), time_zone: zone, time_zones: effective_time_zones)
+      TimeZoneResolver.new(zone, effective_time_zones).to_utc(local)
+    end
+
+    def occurrences(from:, to:, limit: 1000, time_zone: nil, timeout: 2.0)
+      validate!
+      Occurrences.new(self, from: from, to: to, limit: limit, time_zone: time_zone, timeout: timeout)
+    end
+
+    def add_recurrence_rule(**properties)
+      rule = Model.camel_properties(properties)
+      rule["@type"] = "RecurrenceRule"
+      rule.fetch("byDay", []).each { |day| day["@type"] ||= "NDay" }
+      (@data["recurrenceRules"] ||= []) << rule
+      self
+    end
+
+    def effective_time_zones
+      @time_zones.merge(@data.fetch("timeZones", {}))
+    end
+  end
+
+  Event.include(RecurringCalendar)
+  Task.include(RecurringCalendar)
+end

data/lib/jscalendar/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Jscalendar
+  Violation = Struct.new(:pointer, :message, keyword_init: true)
+
+  class Error < StandardError
+    attr_reader :pointer
+
+    def initialize(message = nil, pointer: nil)
+      @pointer = pointer
+      super(message)
+    end
+  end
+
+  class ParseError < Error; end
+  class ConversionError < Error; end
+  class LimitError < Error; end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(errors, pointer: nil)
+      @errors = errors.is_a?(Array) ? errors : [Violation.new(pointer: pointer || "", message: errors)]
+      super(@errors.map { |error| "#{error.pointer}: #{error.message}" }.join("; "), pointer: pointer || @errors.first&.pointer)
+    end
+  end
+end

data/lib/jscalendar/model.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Jscalendar
+  # A typed view over a JSON object; nested views write into their owning model.
+  class Model
+    attr_reader :limits
+
+    def initialize(data = nil, strict: false, time_zones: {}, **limits)
+      @limits = DEFAULT_LIMITS.merge(limits).freeze
+      validator = Validator.new(**limits)
+      @time_zones = Jscalendar.deep_copy(time_zones)
+      data ||= { "@type" => type_name }
+      raise ValidationError, "expected a JSON object" unless data.is_a?(Hash)
+
+      @data = Jscalendar.deep_copy(data, max_depth: @limits[:max_depth])
+      violations = validator.validate(@data, type: type_name, time_zones: @time_zones)
+      raise ValidationError, violations if strict && !violations.empty?
+    end
+
+    def self.wrap(data, limits, time_zones = {})
+      value = allocate
+      value.instance_variable_set(:@data, data)
+      value.instance_variable_set(:@limits, limits)
+      value.instance_variable_set(:@time_zones, time_zones)
+      value
+    end
+
+    def [](name)
+      name = name.to_s
+      rule = SCHEMA.fetch(type_name).fetch("properties")[name]
+      return @data[name] unless rule
+      return wrap_value(Jscalendar.deep_copy(rule["default"]), rule.fetch("type")) if !@data.key?(name) && rule.key?("default")
+
+      wrap_value(@data[name], rule.fetch("type"))
+    end
+
+    def []=(name, value)
+      @data[name.to_s] = Jscalendar.deep_copy(value, max_depth: @limits[:max_depth])
+    end
+
+    def key?(name)
+      @data.key?(name.to_s)
+    end
+
+    def delete(name)
+      @data.delete(name.to_s)
+    end
+
+    def to_h
+      Jscalendar.deep_copy(@data, max_depth: @limits[:max_depth])
+    end
+
+    def to_json(options = nil)
+      validate!
+      data = to_h
+      data["@type"] ||= type_name
+      Jscalendar.generate_json(data, options || { max_nesting: @limits[:max_depth] })
+    end
+
+    def errors
+      Validator.new(**@limits).validate(@data, type: type_name, time_zones: @time_zones)
+    end
+    alias warnings errors
+
+    def valid?
+      errors.empty?
+    end
+
+    def validate!
+      violations = errors
+      raise ValidationError, violations unless violations.empty?
+
+      self
+    end
+
+    def ==(other)
+      other.is_a?(Model) && to_h == other.to_h
+    end
+
+    protected
+
+    def type_name
+      self.class.name.split("::").last
+    end
+
+    private
+
+    def wrap_value(value, signature)
+      return Jscalendar.const_get(signature).new(value) if value && %w[LocalDateTime Duration SignedDuration].include?(signature)
+      return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+      zones = @time_zones.merge(@data["timeZones"].is_a?(Hash) ? @data["timeZones"] : {})
+      if %w[Entry Trigger].include?(signature) && value.is_a?(Hash)
+        type = value["@type"]
+        return SCHEMA.key?(type) ? Jscalendar.const_get(type).wrap(value, @limits, zones) : value
+      end
+
+      if SCHEMA.key?(signature) && value.is_a?(Hash)
+        Jscalendar.const_get(signature).wrap(value, @limits, zones)
+      elsif (match = /\A(?:Id|String)\[(\w+)\]\z/.match(signature)) && SCHEMA.key?(match[1]) && value.is_a?(Hash)
+        IdMap.new(value, type: match[1], limits: @limits,
+                         validate_ids: signature.start_with?("Id["), time_zones: zones)
+      elsif signature.end_with?("[]") && value.is_a?(Array)
+        value.map { |item| wrap_value(item, signature.delete_suffix("[]")) }
+      elsif signature.include?("|") && value.is_a?(Hash)
+        type = value.fetch("@type", signature.split("|").first)
+        SCHEMA.key?(type) ? Jscalendar.const_get(type).wrap(value, @limits, zones) : value
+      else
+        value
+      end
+    end
+  end
+
+  # A map preserving source identifiers and exposing typed member values.
+  class IdMap
+    include Enumerable
+
+    def initialize(data = {}, type:, limits: DEFAULT_LIMITS, validate_ids: true, time_zones: {})
+      @data = data
+      @type = type
+      @limits = limits
+      @validate_ids = validate_ids
+      @time_zones = time_zones
+    end
+
+    def [](id)
+      value = @data[id.to_s]
+      value.is_a?(Hash) ? Jscalendar.const_get(@type).wrap(value, @limits, @time_zones) : value
+    end
+
+    def []=(id, value)
+      id = id.to_s
+      raise ValidationError.new("invalid map Id", pointer: Jscalendar.pointer("", id)) if @validate_ids && !Types.id?(id)
+      raise LimitError, "map exceeds max_map_size" if !@data.key?(id) && @data.size >= @limits[:max_map_size]
+
+      @data[id] = Jscalendar.deep_copy(value, max_depth: @limits[:max_depth])
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      @data.each_key { |id| yield id, self[id] }
+      self
+    end
+
+    def keys
+      @data.keys
+    end
+
+    def values
+      map { |_id, value| value }
+    end
+
+    def size
+      @data.size
+    end
+    alias length size
+
+    def empty?
+      @data.empty?
+    end
+
+    def key?(id)
+      @data.key?(id.to_s)
+    end
+
+    def delete(id)
+      value = self[id]
+      @data.delete(id.to_s)
+      value
+    end
+
+    def add(value, prefix: "id")
+      counter = 1
+      counter += 1 while @data.key?("#{prefix}#{counter}")
+      id = "#{prefix}#{counter}"
+      self[id] = value
+      id
+    end
+
+    def to_h
+      Jscalendar.deep_copy(@data, max_depth: @limits[:max_depth])
+    end
+  end
+
+  SCHEMA.each do |name, definition|
+    model = const_set(name, Class.new(Model))
+    definition.fetch("properties").each_key do |property|
+      next if property == "@type"
+
+      model.define_method(property) { self[property] }
+      model.define_method("#{property}=") { |value| self[property] = value }
+      snake = property.gsub(/([A-Z])/, '_\\1').downcase
+      next if snake == property
+
+      model.alias_method(snake, property)
+      model.alias_method("#{snake}=", "#{property}=")
+    end
+  end
+end

data/lib/jscalendar/patch_object.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Jscalendar
+  class PatchObject
+    RECURRENCE_IGNORED = %w[@type excludedRecurrenceRules method privacy prodId recurrenceId recurrenceIdTimeZone
+                            recurrenceOverrides recurrenceRules relatedTo replyTo sentBy timeZones uid].freeze
+
+    def self.recurrence(patches)
+      patches.reject { |path, _| RECURRENCE_IGNORED.any? { |prefix| path.start_with?(prefix) } }
+    end
+
+    def self.localization(patches)
+      patches.select { |path, _| !path.start_with?("recurrenceOverrides") && %w[title description name].any? { |suffix| path.end_with?(suffix) } }
+    end
+
+    def initialize(patches, max_patches: 1_000, **limits)
+      raise ArgumentError, "max_patches must be a nonnegative integer" unless max_patches.is_a?(Integer) && max_patches >= 0
+      raise ValidationError, "PatchObject must be an object" unless patches.is_a?(Hash)
+      raise LimitError.new("Too many patches", pointer: "") if patches.size > max_patches
+
+      @limits = limits.merge(max_patches: max_patches)
+      @patches = Jscalendar.deep_copy(patches, max_depth: @limits.fetch(:max_depth, 32))
+    end
+
+    def to_h
+      Jscalendar.deep_copy(@patches, max_depth: @limits.fetch(:max_depth, 32))
+    end
+
+    # RFC 8984 section 1.4.9: resolve every path before modifying the copy.
+    def apply(data, validate: true)
+      raise ValidationError, "Patch target must be an object" unless data.is_a?(Hash)
+
+      result = Jscalendar.deep_copy(data, max_depth: @limits.fetch(:max_depth, 32))
+      type = result["@type"]
+      validator = Validator.new(**@limits, validate_patches: false)
+      errors = validator.validate_json(result) + validator.validate_json(@patches)
+      raise ValidationError, errors unless errors.empty?
+
+      paths = @patches.keys.map { |path| [tokens(path), path] }.sort_by(&:first)
+      paths.each_cons(2) do |(first, _), (second, path)|
+        invalid(path, "Patch paths must not overlap") if second.first(first.size) == first
+      end
+      operations = paths.map do |parts, path|
+        parent = parts[0...-1].reduce(result) { |value, token| member(value, token, path) }
+        key = parts.last
+        invalid(path, "Patch parent must be an object; arrays cannot be traversed") unless parent.is_a?(Hash)
+        [parent, key, @patches[path]]
+      end
+      operations.each do |parent, key, value|
+        if value.nil?
+          parent.delete(key)
+        else
+          parent[key] = Jscalendar.deep_copy(value, max_depth: @limits.fetch(:max_depth, 32))
+        end
+      end
+      errors = if validate && (type || result["@type"])
+                 raise ValidationError.new("Unknown patch target type", pointer: "/@type") unless SCHEMA.key?(type || result["@type"])
+
+                 validator.validate(result, type: type || result["@type"])
+               else
+                 validator.validate_json(result)
+               end
+      raise ValidationError, errors unless errors.empty?
+
+      result
+    end
+
+    private
+
+    def tokens(path)
+      invalid(path, "Invalid JSON Pointer escape") if path.match?(/~(?:[^01]|\z)/)
+      (path.empty? ? [""] : path.split("/", -1)).map { |token| token.gsub(/~[01]/) { |escape| escape == "~0" ? "~" : "/" } }
+    end
+
+    def member(parent, key, path)
+      invalid(path, "Intermediate reference must be an existing object member") unless parent.is_a?(Hash) && parent.key?(key)
+      parent[key]
+    end
+
+    def invalid(path, message)
+      raise ValidationError.new(message, pointer: "/#{path.gsub("~", "~0").gsub("/", "~1")}")
+    end
+  end
+end

data/lib/jscalendar/recurrence.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Jscalendar
+  module Recurrence
+    PARTS = { "interval" => "INTERVAL", "firstDayOfWeek" => "WKST", "byMonthDay" => "BYMONTHDAY",
+              "byMonth" => "BYMONTH", "byYearDay" => "BYYEARDAY", "byWeekNo" => "BYWEEKNO", "byHour" => "BYHOUR",
+              "byMinute" => "BYMINUTE", "bySecond" => "BYSECOND", "bySetPosition" => "BYSETPOS", "count" => "COUNT" }.freeze
+
+    module_function
+
+    def to_rrule(rule)
+      rule = rule.to_h if rule.is_a?(Model)
+      errors = Validator.new.validate(rule, type: "RecurrenceRule")
+      raise ValidationError, errors unless errors.empty?
+      raise UnsupportedError, "only Gregorian recurrence expansion is supported" unless rule.fetch("rscale", "gregorian") == "gregorian"
+      raise UnsupportedError, "rrule supports only skip=omit" unless rule.fetch("skip", "omit") == "omit"
+      raise UnsupportedError, "rrule does not support leap seconds" if rule.fetch("bySecond", []).include?(60)
+
+      parts = ["FREQ=#{rule.fetch("frequency").upcase}"]
+      PARTS.each { |name, keyword| parts << "#{keyword}=#{Array(rule[name]).join(",").upcase}" if rule.key?(name) }
+      parts << "BYDAY=#{rule["byDay"].map { |day| "#{day["nthOfPeriod"]}#{day.fetch("day").upcase}" }.join(",")}" if rule["byDay"]
+      # The engine runs in UTC as a wall-clock calendar; zone conversion occurs afterwards.
+      parts << "UNTIL=#{LocalDateTime.new(rule["until"]).to_time.strftime("%Y%m%dT%H%M%SZ")}" if rule["until"]
+      parts.join(";")
+    end
+
+    def rule_times(rule, initial, from, to, limit:, include_initial: true)
+      return [] if rule.fetch("count", 1).zero?
+
+      rule = Jscalendar.deep_copy(rule)
+      count = rule.delete("count")
+      if rule["frequency"] == "yearly" && rule.key?("byWeekNo") && !(rule.key?("byYearDay") || rule.key?("byMonthDay") || rule.key?("byDay"))
+        # RFC 8984 section 4.3.3 supplies this default; rrule 0.8 does not.
+        rule["byDay"] = [{ "@type" => "NDay", "day" => %w[su mo tu we th fr sa][initial.wday] }]
+      end
+      string = to_rrule(rule)
+      engine = RRule::Rule.new(string, dtstart: initial, tzid: "UTC", max_year: to.year + 1)
+      result = []
+      generated = 0
+      if include_initial
+        generated = 1
+        result << initial if initial >= from && initial < to
+        return result if count == 1 || result.size >= limit
+      end
+      # The engine strips fractions. Shift its lower bound before restoring them.
+      engine.each(floor_date: (count ? initial : from) - initial.subsec) do |date|
+        date = date.to_time.getutc + initial.subsec
+        next if include_initial && date == initial
+        break if date >= to
+        break if rule["until"] && date > LocalDateTime.new(rule["until"]).to_time
+        break if count && generated >= count
+        next unless clock_matches?(rule, date)
+
+        generated += 1
+        result << date if date >= from
+        break if result.size >= limit
+      end
+      result
+    end
+
+    # rrule 0.8 overwrites clock filters for hourly and faster frequencies.
+    def clock_matches?(rule, date)
+      checks = case rule["frequency"]
+               when "hourly" then { "byHour" => date.hour }
+               when "minutely" then { "byHour" => date.hour, "byMinute" => date.min }
+               when "secondly" then { "byHour" => date.hour, "byMinute" => date.min, "bySecond" => date.sec }
+               else {}
+               end
+      checks.all? { |name, number| !rule.key?(name) || rule[name].include?(number) }
+    end
+  end
+
+  class RecurrenceRule
+    def to_rrule
+      Recurrence.to_rrule(to_h)
+    end
+  end
+
+  class Occurrence
+    attr_reader :recurrence_id, :event
+    alias calendar event
+
+    def initialize(id, event, time_zone)
+      @recurrence_id = LocalDateTime.new(id)
+      @event = event
+      @time_zone = time_zone
+    end
+
+    def start_time(time_zone: @time_zone)
+      @event.start_time(time_zone: time_zone)
+    end
+  end
+
+  class Occurrences
+    include Enumerable
+
+    def initialize(calendar, from:, to:, limit:, time_zone:, timeout:)
+      raise ArgumentError, "from and to must be Times with from < to" unless from.is_a?(Time) && to.is_a?(Time) && from < to
+      unless limit.is_a?(Integer) && limit.positive? && limit <= calendar.limits[:max_occurrences]
+        raise ArgumentError, "limit must be positive and <= max_occurrences"
+      end
+      raise ArgumentError, "timeout must be positive and finite" unless timeout.is_a?(Numeric) && timeout.positive? && timeout.finite?
+
+      @truncated = false
+      @items = Timeout.timeout(timeout, LimitError, "recurrence expansion exceeded time limit") do
+        expand(calendar, from, to, limit, time_zone)
+      end
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @items.each(&block)
+      self
+    end
+
+    def truncated?
+      @truncated
+    end
+
+    private
+
+    def expand(calendar, from, to, limit, time_zone)
+      data = calendar.to_h
+      initial_text = data["start"] || data["due"]
+      raise ValidationError, "calendar has no start or due" unless initial_text
+
+      initial = LocalDateTime.new(initial_text).to_time
+      zone = data["timeZone"] || time_zone
+      resolver = zone && TimeZoneResolver.new(zone, calendar.effective_time_zones)
+      lower, upper = resolver ? resolver.wall_bounds(from, to) : [from.getutc, to.getutc]
+      maximum = calendar.limits[:max_occurrences]
+      rules = data.fetch("recurrenceRules", [])
+      exclusions = data.fetch("excludedRecurrenceRules", [])
+      overrides = data.fetch("recurrenceOverrides", {})
+      raise LimitError, "too many recurrence rules" if rules.size + exclusions.size > calendar.limits[:max_rules]
+
+      # Without removals, moved instances, or offset changes, each rule's first
+      # limit+1 dates suffice to determine the first limit results and truncation.
+      simple = exclusions.empty? && overrides.empty? && [nil, "UTC"].include?(zone)
+      generation_limit = simple ? limit + 1 : maximum + 1
+      candidates = [initial]
+      rules.each do |rule|
+        dates = Recurrence.rule_times(rule, initial, lower, upper, limit: generation_limit)
+        @truncated ||= dates.size > maximum
+        candidates.concat(dates.first(maximum))
+      end
+      exclusions.each do |rule|
+        dates = Recurrence.rule_times(rule, initial, lower, upper, limit: maximum + 1, include_initial: false)
+        raise LimitError, "excluded recurrence set exceeds max_occurrences" if dates.size > maximum
+
+        candidates -= dates
+      end
+      candidates.concat(overrides.keys.map { |date| LocalDateTime.new(date).to_time })
+      property = data.key?("start") ? "start" : "due"
+      resolvers = {}
+      items = candidates.uniq.filter_map do |date|
+        id = LocalDateTime.from_time(date).to_s
+        patch = overrides.fetch(id, {})
+        next if patch.fetch("excluded", data.fetch("excluded", false)) == true
+
+        fields = { "start" => data["start"], "due" => data["due"], "timeZone" => data["timeZone"] }
+        fields[property] = id
+        fields.merge!(patch.slice("start", "due", "timeZone"))
+        local = LocalDateTime.new(fields["start"] || fields["due"])
+        actual_zone = fields["timeZone"] || time_zone
+        instant = if actual_zone
+                    resolvers[actual_zone] ||= TimeZoneResolver.new(actual_zone, calendar.effective_time_zones)
+                    resolvers[actual_zone].to_utc(local)
+                  else
+                    local.to_time
+                  end
+        next unless instant >= from && instant < to
+
+        [instant, id, patch]
+      end
+      items.sort_by!(&:first)
+      @truncated ||= items.size > limit
+      bytes = 0
+      items.first(limit).map do |_instant, id, patch|
+        occurrence_data = data.except("recurrenceRules", "excludedRecurrenceRules", "recurrenceOverrides")
+        occurrence_data[property] = id
+        occurrence_data["recurrenceId"] = id
+        occurrence_data["recurrenceIdTimeZone"] = data["timeZone"]
+        occurrence_data = PatchObject.new(PatchObject.recurrence(patch), **calendar.limits).apply(occurrence_data, validate: false) unless patch.empty?
+        bytes += Jscalendar.generate_json(occurrence_data).bytesize
+        raise LimitError, "expanded data exceeds max_occurrence_bytes" if bytes > calendar.limits[:max_occurrence_bytes]
+
+        occurrence = calendar.class.new(occurrence_data, time_zones: calendar.effective_time_zones, **calendar.limits)
+        Occurrence.new(id, occurrence, time_zone)
+      end
+    end
+  end
+end